# jonesand.ai — Design System

Canonical source of truth for the brand and product visual system. Anything in `docs/jonesandai-visual-system-guide.html` is a rendered presentation of this document — when the two diverge, this file wins.

The system is **grounded modernist**: editorial typography, restrained palette, architectural layout, calm motion. Two accents — one cool, one warm — and one system color reserved for errors.

---

## 1. Brand principles

These shape every decision below.

1. **Restraint is the brand.** Every element earns its place. Decorative ornament is a tax on credibility.
2. **Asymmetry over symmetry.** Centered everything reads as default-template. Left-aligned anchors give the page a reading rhythm.
3. **Whitespace signals quality.** Dense layouts feel cheap. Generous space communicates "I had time to think about this."
4. **One accent moment per viewport.** If everything is highlighted, nothing is.
5. **Hierarchy through contrast, not color.** Size, weight, and position do most of the work. Color is the tiebreaker.
6. **Motion is invisible when it works.** Reach for it only to clarify state changes.

### 1.1 Brand direction

**Primary direction:** Grounded Modernist.

The site should feel polished, calm, credible, modern, high taste, minimal but not sterile, optimistic about AI without hype, and distinctive enough to feel intentional rather than templated.

The site should not feel like an AI bro landing page, a black-neon cyberpunk startup, a generic PM portfolio, a course funnel, or Tailwind defaults wearing better copy.

### 1.2 Brand anti-patterns

Never default to:

- Centered-everything hero sections
- Oversaturated gradients
- Oversized rounded corners everywhere
- Vague startup copy
- Decorative UI without purpose
- Stock dashboard patterns on a personal site
- Generic purple-gradient AI styling
- Heavy marketing framing where a plain invitation would work better

---

## 2. Color

### 2.1 Named colors (the palette)

| Name | Hex | Role |
|---|---|---|
| Ink | `#121212` | Primary text, key UI, brand mark |
| Paper | `#F6F3EE` | Page background — warm off-white |
| Surface | `#FFFFFF` | Raised surfaces (cards, inputs) |
| Soft Gray | `#D8D3CC` | Borders, dividers, subtle fills |
| Signal Blue | `#2F6BFF` | Primary accent — links, CTAs, brand moments |
| Mustard | `#D8A12D` | Secondary accent — occasional warmth, highlights, tags |
| Warm Red | `#E5483B` | **System only** — errors and destructive actions. Never on marketing surfaces. |

### 2.2 Semantic tokens (use these in code)

Engineers should reference role tokens, not named colors. This is what keeps the brand from drifting when new pages get built.

| Token | Maps to | Used for |
|---|---|---|
| `--color-text-primary` | Ink | Body and heading text |
| `--color-text-muted` | Ink @ 65% | Captions, metadata, secondary text |
| `--color-text-subtle` | Ink @ 45% | Tertiary text, disabled labels |
| `--color-text-inverse` | Paper | Text on dark surfaces |
| `--color-surface` | Paper | Page background |
| `--color-surface-raised` | Surface (`#FFFFFF`) | Cards, inputs, popovers |
| `--color-surface-sunken` | `#EDE9E2` | Section backgrounds within pages |
| `--color-border` | Soft Gray | Default border, dividers |
| `--color-border-strong` | Ink @ 20% | Emphasized borders, focus rings |
| `--color-accent` | Signal Blue | Primary CTAs, accent blocks, large links |
| `--color-accent-strong` | `#1F54D6` | Inline body links, body-text accent (passes AA at body sizes) |
| `--color-accent-hover` | `#1742B5` | Hover state for accent |
| `--color-highlight` | Mustard | Highlight blocks, secondary tags |
| `--color-danger` | Warm Red | Error states, destructive actions |

### 2.3 Contrast & accessibility

All foreground/background pairings used for body text must meet **WCAG AA (4.5:1)**. UI text ≥ 18px or bold ≥ 14px must meet **3:1**.

| Pairing | Ratio | Use |
|---|---|---|
| Ink on Paper | 16.9:1 | All body, headings — AAA |
| Ink on Surface | 18.4:1 | Card body — AAA |
| Ink @ 65% on Paper | 8.9:1 | Muted text — AA |
| Signal Blue on Paper | 4.1:1 | **AA Large only** (≥18px regular or ≥14px bold). Use for buttons and large links. For inline body links use Accent Strong (`#1F54D6`, 5.7:1). |
| Paper on Signal Blue | 4.1:1 | Inverse button fill — AA Large only. Keep button text ≥14px medium. |
| Accent Strong (`#1F54D6`) on Paper | 5.7:1 | Inline body links, body-text accent — AA |
| Mustard on Paper | 2.1:1 | **Fails AA for text.** Mustard is for backgrounds, tags, and decorative blocks only — never body type. |
| Warm Red on Paper | 3.6:1 | **AA Large only.** Inline error copy must be ≥14px bold or ≥18px, and pair with iconography. |

### 2.4 Color rules

- **Do** use Ink for ≥80% of all text on a page.
- **Do** reserve Signal Blue for links, primary CTAs, and one accent moment per viewport.
- **Do** use Mustard sparingly — chips, callout backgrounds, occasional decorative blocks.
- **Don't** mix Signal Blue and Mustard inside the same component.
- **Don't** use Warm Red anywhere except errors and destructive confirms.
- **Don't** use pure black (`#000`) or pure white (`#FFF`) for backgrounds.

### 2.5 Night mode

Night mode should feel like the same grounded modernist system in a quieter reading state. It is not a separate brand direction. Avoid cyberpunk, neon glow, pure black, and high-saturation "AI" styling.

The current implementation uses these dark theme values in `src/app/globals.css`:

| Token | Value | Role |
|---|---|---|
| `--color-background` | `#101214` | Page background |
| `--color-foreground` | `#F3EEE6` | Primary foreground text |
| `--color-ink` | `#F3EEE6` | Primary text and key UI |
| `--color-paper` | `#101214` | Dark page surface |
| `--color-paper-deep` | `#171A1E` | Subtle section depth |
| `--color-surface` | `#1D2127` | Raised surfaces, cards, inputs |
| `--color-surface-muted` | `rgba(255, 255, 255, 0.04)` | Quiet translucent surfaces |
| `--color-header-bg` | `rgba(13, 16, 20, 0.86)` | Sticky header background |
| `--color-soft-gray` | `#2B3139` | Borders and dividers |
| `--color-signal-blue` | `#78A6FF` | Dark-mode accent, links, focus, CTAs |
| `--color-warm-red` | `#FF7A6B` | Errors and destructive actions only |
| `--color-mustard` | `#E0B85A` | Occasional highlights and tags |
| `--color-muted` | `rgba(243, 238, 230, 0.72)` | Secondary text |
| `--color-muted-soft` | `rgba(243, 238, 230, 0.52)` | Tertiary text |
| `--color-muted-strong` | `rgba(243, 238, 230, 0.86)` | Emphasized muted text |

Key contrast checks against the current implementation:

| Pairing | Ratio | Use |
|---|---|---|
| Foreground on Background | 16.25:1 | Primary body and heading text — AAA |
| Foreground on Surface | 14.00:1 | Card and input body text — AAA |
| Muted on Background | 8.68:1 | Secondary text — AAA |
| Muted Soft on Background | 5.03:1 | Tertiary text — AA |
| Signal Blue on Background | 7.77:1 | Links, focus, CTAs — AAA |
| Signal Blue on Surface | 6.69:1 | Card links and controls — AA |
| Background on Signal Blue | 7.77:1 | Filled accent buttons — AAA |
| Warm Red on Background | 7.37:1 | Error text/icons — AAA |
| Mustard on Background | 9.99:1 | Highlight text when needed — AAA |

Night-mode rules:

- **Do** keep dark surfaces close together and use borders, spacing, and type hierarchy for structure.
- **Do** use `#78A6FF` for links, focus states, and primary actions in night mode; it is intentionally lighter than Signal Blue for contrast.
- **Do** keep body copy on `--color-foreground`, `--color-muted`, or `--color-muted-soft`; all three pass AA on the dark background.
- **Do** pair low-contrast surfaces such as `--color-paper-deep`, `--color-surface`, and `--color-soft-gray` with text/icons, not rely on them alone to communicate state.
- **Don't** add glow effects, saturated gradients, or high-contrast dark panels that make the site feel like a different brand.
- **Don't** use Mustard or Warm Red as large marketing accents in night mode; their role stays constrained.

---

## 3. Typography

### 3.1 Type families

- **Display:** Inter Tight (600) — headlines, brand moments
- **Body:** Inter (400, 500) — everything else
- **Mono:** SF Mono / JetBrains Mono — code, metadata, dates

### 3.2 Type scale (modular, 1.25 ratio)

| Token | Size / line-height | Weight | Use |
|---|---|---|---|
| `text-display` | 72 / 1.05 | 600 | Brand-mark display (rare; hero only) |
| `text-h1` | 56 / 1.08 | 600 | Page hero |
| `text-h2` | 44 / 1.1 | 600 | Major section heading |
| `text-h3` | 28 / 1.2 | 600 | Subsection heading |
| `text-h4` | 22 / 1.3 | 600 | Block heading, card title |
| `text-eyebrow` | 13 / 1.2 | 600 | Tracking 0.08em, uppercase — section labels |
| `text-body-l` | 18 / 1.65 | 400 | Long-form essay body |
| `text-body` | 16 / 1.6 | 400 | Default UI body |
| `text-small` | 14 / 1.5 | 400 | Captions, metadata |
| `text-caption` | 12 / 1.4 | 500 | Timestamps, labels |

### 3.3 Letter-spacing

| Context | Tracking |
|---|---|
| Display, H1 | -0.02em |
| H2, H3 | -0.01em |
| Body, small | 0 |
| Eyebrow, caption uppercase | 0.08em |

### 3.4 Line-height roles

- **Tight (1.05–1.1):** display, H1 — presence
- **Snug (1.15–1.3):** H2–H4 — punchy
- **Normal (1.5–1.6):** UI body — readable
- **Relaxed (1.65):** long-form essay — breathing room

### 3.5 Type rules

- **Do** use Display weight 600. Heavier weights are off-brand.
- **Do** keep body line-length 60–75 characters (`max-width: 65ch` for long-form).
- **Do** use `text-eyebrow` to label sections without consuming heading hierarchy.
- **Don't** use sizes below 14px for body content.
- **Don't** use italic Inter — it reads as a different typeface.
- **Don't** mix Display and Body inside a single line.

---

## 4. Spacing

### 4.1 Scale (4-point grid)

| Token | Value | Use |
|---|---|---|
| `space-1` | 4 | Icon gap, button internal padding |
| `space-2` | 8 | Inline element gap, tight stack |
| `space-3` | 12 | Form-field internal padding |
| `space-4` | 16 | Standard component padding, list-item rhythm |
| `space-6` | 24 | Card gutter, default content gap |
| `space-8` | 32 | Block padding, between paragraphs and headings |
| `space-12` | 48 | Major content blocks, section internal padding |
| `space-16` | 64 | Between major sections |
| `space-20` | 80 | Hero top/bottom |
| `space-24` | 96 | Page-level dividers |
| `space-32` | 128 | Reserved — only for very large layouts |

### 4.2 Layout rules

- Default vertical rhythm between sections: **64px** (`space-16`)
- Default horizontal page padding: **40px desktop, 24px mobile**
- Default container max-width: **1200px** for marketing, **720px** for long-form
- Default card gutter: **24px** (`space-6`)

---

## 5. Grid & layout

### 5.1 Grid

- **Desktop:** 12 columns, 24px gutters, 1200px max
- **Tablet (768–1023):** 8 columns, 24px gutters, fluid
- **Mobile (< 768):** 4 columns, 16px gutters, fluid

### 5.2 Common spans

| Layout | Spans |
|---|---|
| Marketing hero text | 8 cols, left-aligned |
| Asymmetric feature | 8 / 4 (content / accent) |
| Even split | 6 / 6 |
| Card grid | 4 / 4 / 4 |
| Long-form essay | 7 cols centered, max 65ch |

### 5.3 Breakpoints

| Name | Min-width |
|---|---|
| `sm` | 640 |
| `md` | 768 |
| `lg` | 1024 |
| `xl` | 1280 |

### 5.4 Layout principles

- **Left alignment is the default.** Centered text is reserved for hero quotes and confirmation states.
- **Asymmetric over symmetric** for feature blocks. 2:1 column ratios create hierarchy.
- **Vertical rhythm matters more than visual variety.** Reuse spacing tokens across sections.

---

## 6. Components

Specs every component must adhere to. New components inherit these defaults.

### Banned patterns

These read as generic AI/SaaS chrome and weaken the brand. Don't use them anywhere:

- **Colored left-border accents anywhere** (`border-left: 4px solid <accent>`, Tailwind `border-l-*`) — this applies to cards, callouts, quotes, notes, and content blocks. Replace with eyebrow labels, numbered prefixes, or hairline rules.
- **Colored top-border accents on cards** (`border-top: 3px solid <accent>`) — replace with a subtle hairline under the title.
- **Auto-applied accent strips** on every grid item — too uniform, reads as templated.

When a component needs an accent moment, give it a label, a number, or a hairline — not a colored side bar. Editorial restraint over SaaS decoration.

### 6.1 Button

| Variant | Background | Text | Border | Use |
|---|---|---|---|---|
| Primary | Signal Blue | Paper | none | One per viewport — main CTA |
| Secondary | Surface | Ink | 1px Soft Gray | Supporting action |
| Ghost | transparent | Ink | none | Tertiary, low-noise |
| Danger | Warm Red | Paper | none | Destructive only |

**Sizes:** `sm` (12 / 14 padding, text-small), `md` (14 / 18, text-body), `lg` (16 / 22, text-body-l).
**States:** default, hover (`-4%` lightness), active (`-8%`), focus (2px Ink outline, 2px offset), disabled (40% opacity, no pointer events).
**Radius:** 6px.

### 6.2 Input

- Background: Surface
- Border: 1px Soft Gray
- Text: Ink, text-body
- Padding: 14 / 18
- Radius: 6px
- **Focus:** border becomes Signal Blue, 2px outer ring at 20% opacity
- **Error:** border Warm Red, helper text Warm Red below
- Always pair with a `<label>` — never rely on placeholder text for naming

### 6.3 Link

- **Inline body links** (text-body and smaller): use `--color-accent-strong` (`#1F54D6`) — passes AA at body sizes. Underline in long-form prose; underline-on-hover in UI.
- **Large links and CTAs** (≥18px regular or ≥14px bold): use `--color-accent` (`#2F6BFF`).
- Hover: shift to `--color-accent-hover` (`#1742B5`); underline appears if not already shown.
- Visited: same as default — do not differentiate visited links (too noisy for editorial).
- Focus: 2px Ink outline, 2px offset.

### 6.4 Card

- Background: Surface
- Padding: 28–32px
- Radius: 8px
- Shadow: `0 2px 8px rgba(18, 18, 18, 0.06)` — subtle, not lifted
- Border: optional 1px Soft Gray for un-shadowed variants
- Hover (interactive cards only): shadow strengthens to `0 4px 16px rgba(18, 18, 18, 0.08)`

### 6.5 Tag / chip

- Background: Soft Gray
- Text: Ink @ 80%, text-caption
- Padding: 6 / 12
- Radius: 4px
- Mustard variant for highlight tags ("In Progress", "Featured")

### 6.6 Code

- Inline: monospace 0.9em, background Surface, 2px padding, 4px radius
- Block: monospace 14px, background `#1A1A1A`, text `#E5E5E5`, padding 24px, radius 8px, scroll-x on overflow

### 6.7 Callout / quote

Eyebrow-label pattern — no colored side borders. The label gives the block its role.

- Background: Surface Sunken (`#EDE9E2`) for default, Mustard @ 12% for highlight variant
- Padding: 24 / 28
- Radius: 8px on all corners
- Eyebrow label above content: 11px, weight 600, uppercase, tracking 0.1em, in `--color-text-muted` (or `#8A6310` for highlight variant)
- Body: 15px, line-height 1.6
- No left or top accent border — that pattern reads as generic AI/SaaS chrome and is banned from the system

---

## 7. Motion

### 7.1 Durations

| Token | Value | Use |
|---|---|---|
| `motion-fast` | 120ms | Icon swaps, tooltips |
| `motion-base` | 200ms | Hover states, focus rings |
| `motion-slow` | 320ms | Page transitions, modal in/out |

### 7.2 Easing

Use a single curve everywhere:

```css
--ease-out: cubic-bezier(0.2, 0, 0, 1);
```

### 7.3 Motion rules

- **Always honor `prefers-reduced-motion`.** Wrap any non-essential animation in a media query that disables it.
- **Don't animate position for decorative reveals.** Subtle opacity is enough.
- **Don't auto-play hero animations.** They feel desperate.

```css
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}
```

---

## 8. Iconography & imagery

- **Icons:** Lucide remains the default UI icon set (24px default, 1.5px stroke). Match Ink color by default; never use multicolored icons.
- **Supplementary icons:** Custom jonesand.ai icons are additive, not replacements for Lucide. Use them only when the concept is specific to the brand or working-note system and Lucide does not have a close match.
- **Photography:** muted, slightly desaturated, warm-leaning. Workshop / desk / process imagery beats stock product shots.
- **Illustrations:** allowed when they behave like editorial or technical graphics. They should clarify a concept, process, or artifact. Avoid mascot art, cartoons, decorative scenes, and generic AI imagery.

### 8.1 Editorial article images

Use editorial, type-led images for working notes and social cards when a post needs a strong visual anchor. These are not illustrations in the decorative sense. They are structured editorial graphics that make one idea legible at a glance.

The `Lessons learned in my Claude.md File` image is the reference pattern:

- **Core composition:** left-aligned headline block on warm Paper, with a restrained product or document artifact on the right for context.
- **Aspect ratios:** use `1200x626` for hero and social images, `1252x1252` for square thumbnails. Create the square as its own composition instead of cropping the hero.
- **Typography:** large Inter Tight headline, heavy enough to hold up when reduced. Use mono labels for file names, commands, prompts, and technical artifacts.
- **Palette:** Paper background, Ink headline, one Signal Blue rule or highlight, one small Mustard label when useful.
- **Texture:** add a very light paper grain or soft shadow only. The image should feel printed and editorial, not glossy.
- **Density:** one large claim, one small explanatory line, and optional artifact details. Avoid filling the frame with small text.
- **Artifact treatment:** show documents, cards, interface snippets, annotations, arrows, or labels when they clarify the point. Keep them secondary to the main claim.
- **Readability:** the headline must still read at `156px` wide on the blog index. Test the square thumbnail at small sizes before publishing.

Reusable generation prompt:

```text
Create a jonesand.ai editorial article image in the grounded modernist style.

Canvas:
- Hero version: 1200x626.
- Square thumbnail version: 1252x1252.
- Warm off-white Paper background (#F6F3EE) with very subtle paper grain.

Composition:
- Left-aligned editorial headline block.
- One short mono eyebrow label at the top, using Mustard (#D8A12D) as a small rectangular tag.
- Large Ink (#121212) headline in Inter Tight style, bold, tight leading, clean spacing.
- One short supporting line in muted Ink below the headline.
- One Signal Blue (#2F6BFF) rule or small highlight under the headline.
- Optional right-side artifact that supports the topic, such as a Markdown file, code note, prompt card, or annotated document.

Style:
- Calm, credible, editorial, modernist.
- Strong hierarchy through type and spacing.
- Minimal shadows, no glossy UI, no neon, no purple gradients, no stock imagery, no cartoon illustration.
- Use only Ink, Paper, Soft Gray, Signal Blue, and a small Mustard accent.

Content:
- Eyebrow label: [SHORT TECHNICAL LABEL]
- Headline: [ONE STRONG CLAIM]
- Supporting line: [SHORT CONTEXT LINE]
- Artifact details: [OPTIONAL DOCUMENT OR UI TEXT]

Output:
- Produce a clean, high-resolution bitmap.
- Keep all text sharp and readable.
- Make the square thumbnail a designed square layout, not a crop of the hero image.
```

Example adaptation:

```text
Eyebrow label: CLAUDE.md
Headline: Critical Thinking > Agreement
Supporting line: CLAUDE.md instructions for better product work
Artifact details: A Markdown file panel with sections for Purpose, Core Principles, How to Respond, and Reminders, plus small labels for evidence, tradeoffs, and ask, don't invent.
```

### 8.2 Supplementary icon set

Use custom icons as a small subject-specific set for working notes, toolkit items, and article graphics. They should feel like notebook marks or technical sketches, not a second general-purpose icon library.

- **Additive rule:** use Lucide first for standard UI actions like search, menu, close, mail, download, external link, copy, and theme. Use custom icons for brand-specific concepts like journal, prompt, output, model, experiment, iterate, compare, document, toolkit, project, and insight.
- **Construction:** 32px viewBox, 1.5px Ink stroke, rounded caps and joins when useful. Keep detail simple enough to read at 24px.
- **Color:** Ink for primary strokes. Soft Gray may be used for secondary internal detail lines. Avoid Signal Blue, Mustard, Warm Red, and multicolor icon shapes.
- **Fills:** prefer stroke-only. Tiny Ink fills are allowed for functional dots, terminals, nodes, or status points. Do not use filled icon silhouettes.
- **Sizing:** 24px default in UI with a text label. 16px minimum only with a label. 48px is allowed for hero or article moments.
- **Usage:** icons support labels and structure; they should not become decoration scattered through prose.

### 8.3 Structural graphics

Structural graphics are the system's technical drawing layer. Use them to add order, measurement, and process cues without making the site feel like a dashboard.

Approved elements:

- **Bracket callouts:** corner-bracket framing on Surface Sunken for pull quotes, definitions, and short claims. These can replace colored side-border callouts.
- **Corner art blocks:** restrained corner registration marks around feature blocks, pull quotes, or article image details. Use Ink only and keep them rare.
- **Technical notes:** thin border, small floated mono label, Surface background. No fill-heavy badges.
- **Crosshair marks and tick rules:** section anchors, dividers, or annotation details. Use them as quiet structure, not ornament.
- **Measurement brackets:** diagram annotations and article graphics. Pair with mono labels.
- **Numbered station marks:** process steps, lessons, and analysis sequences.
- **Dot-grid texture:** allowed only inside contained diagrams, article graphics, or small structural blocks. Do not use it as a full-page background or repeated section wallpaper.

Rules:

- Keep structural marks Ink or Soft Gray. Use Signal Blue only for a single active point, measurement, or critical node.
- Do not use colored left or top borders. The ban in §6 still stands.
- Do not combine every mark in one component. Pick one structural device per block.
- Keep marks aligned to the grid. They should make layout feel measured, not busy.

### 8.4 Flow diagrams

Use flow diagrams for process explanations, prompt loops, agent workflows, evaluation paths, and experiment results.

- **Linear flows:** use numbered stations connected by orthogonal lines or simple arrows. Highlight only the current, active, or most important node.
- **Flow loops:** allowed when the concept is genuinely cyclical, such as revise-and-test workflows. Prefer orthogonal return paths. Curves are allowed only when a straight return path makes the diagram harder to read.
- **Network diagrams:** use sparingly for relationships between tools, models, inputs, and outputs. Keep labels short and connections sparse.
- **Comparison bars:** use horizontal bars for experiment results. Signal Blue may mark the leading or selected result; Ink and Soft Gray carry the rest.
- **Accent discipline:** one Signal Blue highlight per diagram. Do not make every arrow, node, or bar blue.
- **Labels:** use mono metadata for station numbers, sample sizes, dates, and evaluation notes.
- **Avoid:** decorative arrows, complex bezier paths, dense node maps, 3D diagrams, glowing nodes, and dashboard-like chart packs.

---

## 9. Voice

The brand is **grounded, practical, optimistic**. It sounds like a senior PM who has shipped real things and is now learning a new craft in public.

Quick test: the writing should feel grounded, practical, calm, non-hypey, direct, and credible.

### 9.1 Voice attributes

| Attribute | What it means |
|---|---|
| Grounded | Calm, credible. No hype, no fear-mongering. |
| Practical | "Here's what I tried" beats "here's what experts say." |
| Optimistic | Excited about possibility, suspicious of snake oil. |
| Direct | No throat-clearing. The audience is busy and smart. |
| Curious | "I don't know yet" is a valid answer. Learning in public is the point. |
| Credible | 14 years across product, delivery, and analysis shows up as confidence, not credentials. |

### 9.2 Voice in micro-copy

This is where voice either lives or dies.

| Surface | Good | Bad |
|---|---|---|
| Hero CTA button | `Subscribe` | `Join the movement!` |
| Newsletter promise | `One email a week. No hype.` | `Don't miss out — sign up now!` |
| Form error | `That email doesn't look right. Try again?` | `Invalid input.` |
| Empty state | `Nothing here yet. New notes ship most weeks.` | `No content available.` |
| 404 | `That page doesn't exist — but plenty of others do.` | `Oops! Something went wrong.` |

### 9.3 Do / don't

**Do:** "I tried X and here's what happened." • "Here's what actually matters." • "I don't know yet, but…" • "14 years across product, delivery, and analysis."

**Don't:** "AI is changing everything!!!" • "I'm not technical, but…" (don't lead with limitation) • "14 years as a PM at EA" (only ~3 years were at EA — see §11) • "The future of work is here" (generic futurism).

### 9.4 No audience-scolding setup

Do not open an argument by claiming that other people are using AI badly. Avoid lines like "Most people treat AI like a clever autocomplete tool", "Everyone is prompting wrong", or "88% of people make this mistake."

These setups sound clickbaited and usually invent a crowd to argue against. State the useful idea directly from experience, evidence, or the system being described.

- **Use:** "A weak AI workflow usually lacks context, standards, or feedback."
- **Use:** "The output gets better when the surrounding system gets better."
- **Avoid:** "Most people use AI as autocomplete."
- **Avoid:** "88% of people are doing AI wrong."

---

## 10. Message hierarchy

Every jonesand.ai surface should let a visitor extract three things, in order, in under five seconds:

1. **Identity (who).** "Making sense of AI by building with it."
2. **Mission (why).** "A practical record of learning what AI is actually useful for, where it falls short, and how it changes the work."
3. **Journey (how).** "No hype cycle recap. Just useful experiments, working notes, and lessons from figuring this out in practice."

Show this hierarchy *visually* — Identity at display weight, Mission at H3, Journey at body-muted. Same-size text breaks the hierarchy.

---

## 11. Bio facts (don't drift)

Used to keep voice and bio copy accurate. Reference, not voice guidance.

- **14 years** in product, delivery, and analysis (combined).
- **~3 years at EA** — significant but not the whole story.
- Currently learning to build software with AI assistance.
- Audience: product managers and operators, not engineers.

---

## 12. Tailwind v4 mapping

Every token below should appear in `src/app/globals.css` inside `@theme`. This is what makes the design system real in code.

`@theme` should define the light defaults. Theme-specific runtime values should be overridden under `html[data-theme="light"]` and `html[data-theme="dark"]`. The current implementation still uses compatibility tokens such as `--color-background`, `--color-foreground`, `--color-muted`, and `--color-paper-deep`; when refactoring, map those onto the semantic roles in §2.2 without changing the visual result.

```css
@theme {
  /* Color — named */
  --color-ink: #121212;
  --color-paper: #F6F3EE;
  --color-surface: #FFFFFF;
  --color-surface-sunken: #EDE9E2;
  --color-soft-gray: #D8D3CC;
  --color-signal-blue: #2F6BFF;
  --color-signal-blue-strong: #1F54D6;
  --color-signal-blue-hover: #1742B5;
  --color-mustard: #D8A12D;
  --color-warm-red: #E5483B;

  /* Color — semantic */
  --color-text-primary: var(--color-ink);
  --color-text-muted: rgb(18 18 18 / 0.65);
  --color-text-subtle: rgb(18 18 18 / 0.45);
  --color-text-inverse: var(--color-paper);
  --color-border: var(--color-soft-gray);
  --color-border-strong: rgb(18 18 18 / 0.2);
  --color-accent: var(--color-signal-blue);
  --color-accent-strong: var(--color-signal-blue-strong);
  --color-accent-hover: var(--color-signal-blue-hover);
  --color-highlight: var(--color-mustard);
  --color-danger: var(--color-warm-red);

  /* Typography */
  --font-display: 'Inter Tight', 'Helvetica Neue', -apple-system, sans-serif;
  --font-body: 'Inter', -apple-system, sans-serif;
  --font-mono: 'JetBrains Mono', 'SF Mono', ui-monospace, monospace;

  --text-display: 4.5rem;       /* 72 */
  --text-h1: 3.5rem;            /* 56 */
  --text-h2: 2.75rem;           /* 44 */
  --text-h3: 1.75rem;           /* 28 */
  --text-h4: 1.375rem;          /* 22 */
  --text-eyebrow: 0.8125rem;    /* 13 */
  --text-body-l: 1.125rem;      /* 18 */
  --text-body: 1rem;            /* 16 */
  --text-small: 0.875rem;       /* 14 */
  --text-caption: 0.75rem;      /* 12 */

  /* Spacing — 4pt grid */
  --spacing-1: 0.25rem;   /* 4 */
  --spacing-2: 0.5rem;    /* 8 */
  --spacing-3: 0.75rem;   /* 12 */
  --spacing-4: 1rem;      /* 16 */
  --spacing-6: 1.5rem;    /* 24 */
  --spacing-8: 2rem;      /* 32 */
  --spacing-12: 3rem;     /* 48 */
  --spacing-16: 4rem;     /* 64 */
  --spacing-20: 5rem;     /* 80 */
  --spacing-24: 6rem;     /* 96 */

  /* Radius */
  --radius-sm: 4px;
  --radius-md: 6px;
  --radius-lg: 8px;
  --radius-xl: 12px;

  /* Shadow */
  --shadow-card: 0 2px 8px rgb(18 18 18 / 0.06);
  --shadow-card-hover: 0 4px 16px rgb(18 18 18 / 0.08);

  /* Motion */
  --ease-out: cubic-bezier(0.2, 0, 0, 1);
  --motion-fast: 120ms;
  --motion-base: 200ms;
  --motion-slow: 320ms;
}
```

---

## 13. Application by touchpoint

Brief reminders. Full specs live in §1–§12.

- **Website:** audience-first, not consultancy-first. The primary goal is newsletter signups; secondary goals are establishing voice and trust, giving visitors paths into the journal and toolkit, and showing active projects as proof.
- **Homepage:** use **The Builder's Journal** concept. Structure it as hero with identity and newsletter CTA, latest journal entries, useful toolkit items, active projects, then footer. Newsletter is the primary action; journal, toolkit, and projects are secondary actions.
- **Hero:** left-aligned, direct, confident, not inflated. Must include an identity statement, short subhead, newsletter signup, and secondary navigation actions.
- **Journal list:** date clearly visible, title first, concise summary second. It should feel like a living work log, not marketing content.
- **Toolkit shelf:** publish reusable prompts, docs, guides, and systems only when they are practical assets another person can use directly. Keep toolkit cards restrained and useful, not marketplace-like.
- **Project cards:** show status where relevant, use restrained tags, present active work as proof of motion, and keep descriptions concise and specific. Brand-system outputs such as the visual system guide belong here when they are case-study/project evidence rather than reusable templates.
- **Newsletter form:** integrated into the hero, not bolted on. Clean input/button treatment, no heavy funnel framing, copy that feels like an invitation.
- **Newsletter:** clean readable layout, one accent color per issue, minimal header/footer, focus on the writing.
- **Social:** consistent visual templates, process over product, threads for complex ideas, occasional Signal Blue accent.
- **Presentations:** architectural slide layouts, one idea per slide, large type, accent blocks for emphasis.
- **Video / YouTube:** clean title cards, lower thirds in brand type, minimal motion graphics, workshop lighting aesthetic.
- **Products / tools built on the brand:** same color and type system, functional over decorative, polished but not precious.

---

## 14. Change log

Track meaningful system changes here. New tokens, palette shifts, voice updates.

- **2026-05-27** — Folded in the visual language review: allowed controlled editorial and technical illustrations, made custom icons explicitly additive to Lucide, and added rules for structural graphics, dot-grid texture, accent discipline, and flow loops.
- **2026-05-27** — Added editorial article image guidance, reusable generation prompt, and the `Lessons learned in my Claude.md File` image as the reference pattern for type-led working-note visuals.
- **2026-05-07** — Merged the useful root `DESIGN.md` brand direction, anti-generic rules, homepage strategy, and component guidance into this canonical system document. Removed root `DESIGN.md` so this file is the only design-system source.
- **2026-05-07** — Moved the rendered visual system guide source from the repo root to `docs/jonesandai-visual-system-guide.html`; kept `public/jonesandai-visual-system-guide.html` as the live site copy.
- **2026-05-07** — Documented the existing night-mode palette from `src/app/globals.css`, added contrast checks for key dark-theme pairings, and clarified night-mode usage rules.
- **2026-05-09** — Reclassified the visual system guide as a project instead of a toolkit item because it is a brand-system output and case study, not a reusable asset.
- **2026-04-27** — Initial canonical design.md. Demoted Warm Red to system-only role; added semantic tokens, motion layer, component specs, contrast ratios, Tailwind v4 mapping. Split homepage concept into `docs/homepage-concept.html`.