`, no ligatures |
| chat-message | Inter | 15 | 400 | 1.6 | -0.005 | — | Streaming chat body |
| em-accent | Instrument Serif | inherit | 400 | inherit | inherit | — | `` italic in brand color |

### Principles

- **Display tightens with size.** `-0.035em` at 72px → `-0.005em` at
  15px → `0` at 12px. The reverse of the browser default.
- **Weights stay restrained.** Display is `500`, never `700`. Body
  is `400`. The only `500`+ surfaces are mono labels and button text.
- **`` is a design token.** Instrument Serif italic in brand
  color. Used inside display headlines only.
- **Type is theme-invariant.** Sizes, weights, and tracking do not
  change between editorial-dark / bright / cool-blue. Only colors
  swap.
- **Streaming cursor.** A brand-colored `▋` glyph with a 1s
  step-end blink, applied via `.cursor-blink::after`. Visible only
  during active stream.
- **OpenType is global.** `font-feature-settings` is set on ``
  to opt into `ss01` and `cv11` once.
- **Mono is reserved.** JetBrains Mono only on labels, code, tool
  args, and numeric data — never body prose.

## 4. Component Stylings

### Button — Primary

- Background: `var(--color-brand)`
- Text: `var(--color-text-on-brand)`
- Padding: `14px 20px`
- Radius: `standard` (8px)
- Font: Inter 14 / 500, tracking `-0.005em`
- Hover: background → `brand-hover`. **No scale, no glow, no
  translate.**
- Active: background → `brand-pressed`.
- Disabled: opacity `0.40`, cursor `not-allowed`.
- Use: hero CTA — *Get AgentKit*, *Buy*, *Sign up*.

### Button — Ghost

- Background: transparent
- Text: `var(--color-text)`
- Padding: `14px 20px`
- Radius: `standard` (8px)
- Border: `1px solid var(--color-border-strong)`
- Hover: background → `bg-card-hover`; border tightens to `text-dim`.
- Use: secondary action paired with a primary CTA.

### Button — Icon

- 36px square, `comfortable` radius (12px), `text-dim` glyph.
- Hover: background → `bg-card-hover`, glyph → `text`.
- Use: copy-to-clipboard, theme-switch (dev only), dismiss.

### Card

- Background: `var(--color-bg-card)`
- Border: `1px solid var(--color-border)`
- Radius: `card` (16px)
- Padding: `24px` default, `32px` for featured tier.
- Hover: background → `bg-card-hover`. No translate.
- No shadow on dark themes; on bright theme a subtle ambient-light
  shadow may be used (1px 2px at 6% opacity).

### ChatHero (anchor component)

- Background: `bg-card`
- Border: `1px solid border`
- Radius: `card` (16px)
- Padding: `24px`
- Header: `Label` mono uppercase row at top — *"AGENT • LIVE"* — with
  brand dot.
- Body: alternating message bubbles, `assistant-bg = bg-card`,
  `user-bg = bg-card-hover`.
- Streaming cursor: `▋` glyph in `brand` color with `cursor-blink`
  1s step-end animation, stops on stream end.

### AgentTraceViewer (anchor component)

- Background: `bg-card`
- Radius: `card` (16px)
- Padding: `24px`
- Each step: numbered `01.`, `02.`, mono uppercase, with a
  collapse/expand chevron on the right.
- Open state: Radix `accordion-down` with
  `--radix-accordion-content-height`, 200ms `ease-standard`.

### ToolCallPanel (anchor component)

- Background: `bg-card`
- Border: `1px solid border`
- Radius: `card` (16px)
- 4 phases — `prompt` → `calling` → `result` → `final` — each as a
  small card with mono-uppercase label and code-inline tool name.
- Phase progression: each card slides in from below with 8px translate
  and fades in over 240ms `ease-emphasized`. The `calling` card shows
  a spinning `text-dim` `Loader` icon; the `result` card shows a
  `success` checkmark.

### MessageBubble

- User bubble: `bg-card-hover`, right-aligned, max-width 80%.
- Assistant bubble: `bg-card`, left-aligned, max-width 100%.
- Padding: `12px 16px`, radius: `comfortable` (12px).
- Code blocks inside: JetBrains Mono 13px on `bg-elev` with `small`
  radius.

### ModelSelector

- Background: `bg-elev`
- Border: `1px solid border-strong`
- Radius: `standard` (8px)
- Trigger shows model logo + name + chevron; popover lists available
  models with selected one in `brand`.

### Input

- Background: `bg-elev`
- Text: `text`; placeholder `text-faint`
- Border: `1px solid border-strong`
- Padding: `12px 14px`
- Radius: `small` (6px)
- Focus: border → `border-brand-strong`; ring `0 0 0 2px brand-tint-strong`.

### Label

- Mono 11 / 500 / 0.15em / uppercase, color `text-dim`.
- 6px solid `brand` dot, 8px to the left of the text.
- The rhythm anchor of every section.

### Badge

- Background: `brand-tint`
- Text: `brand`
- Border: `1px solid border-brand`
- Mono 11 / 500 / 0.10em / uppercase, padding `3px 8px`, radius
  `micro` (3px).

### Em

- Instrument Serif italic 400, color `brand`, inherits size and
  line-height from parent.
- Used inside display headlines only.

## 5. Layout Principles

### Spacing System

- Base unit: `4px`. Scale: `[0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64,
  80, 96, 128, 160]`.
- Named: `xxs` → `xs` → `sm` → `md` → `lg` → `xl` → `xxl` → `section`
  (64) → `section-large` (96) → `section-hero` (128).

### Grid & Container

- `page-width` (1200px) — the full marketing page.
- `prose-width` (800px) — long-form text columns.
- Hero is `1fr 1fr` desktop, single-column mobile.
- Streaming feature row: `1.4fr 1fr` (chat panel weighted larger).
- Trace viewer feature row: `1fr 1fr`.
- Tool-call feature row: `1.4fr 1fr`.

### Whitespace Philosophy

Section rhythm uses `--space-13` (128px) between major sections on
desktop; scales to `--space-10` (64px) on mobile. Hero gets an extra
32px of top padding.

### Section Cadence

Sections do **not** alternate light/dark bands. The page is a single
ground tone with cards and elevation doing the visual layering.
Section labels (mono uppercase + brand dot) mark "new section starts
here".

## 6. Shapes & Radius Scale

| Tier | Value | Use |
| --- | --- | --- |
| none | 0px | Full-bleed dividers |
| micro | 3px | Badges, mono code highlights |
| small | 6px | Inputs, dropdowns |
| standard | 8px | Buttons, most interactive surfaces |
| comfortable | 12px | Message bubbles, FAQ rows |
| card | 16px | Content cards, ChatHero, TraceViewer |
| hero | 24px | Large hero panels, theme-preview tile |
| pill | 9999px | Toggle pills, status chips |

Pure-zero radius is forbidden except on full-bleed dividers. The mix
of `8px` (functional) and `16px` (card) gives the page calm
geometry without feeling Web-3 bubbly.

## 7. Depth & Elevation

| Level | Treatment | Use |
| --- | --- | --- |
| 0 | flat — `bg` ground | Default |
| 1 | `bg-elev` | Sticky nav, input field |
| 2 | `bg-card` | Cards, anchor components |
| 3 | `bg-card-hover` | Hovered card |
| 4 | `surface-overlay` + blur | Modal scrim |
| 5 | `shadow.modal` + level-4 | Floating dialog |

**Shadow Philosophy.** Tonal stacking, not shadows. The 4-tier surface
scale provides implicit depth on every theme. Drop shadows are
reserved for floating UI primitives only — Tooltip, Popover, Toast,
Dialog. Cards use borders and surface elevation, not shadows. The
`bright` theme uses softer, lower-opacity black shadows; the dark
themes use higher-opacity neutral black.

## 8. Interaction & Motion

### Easing

- `ease-standard` `cubic-bezier(0.4, 0, 0.2, 1)` — default for hovers,
  state changes, and accordion.
- `ease-emphasized` `cubic-bezier(0.2, 0, 0, 1)` — modal entrance,
  tool-call phase progression, page-level transitions.
- `ease-decelerate` `cubic-bezier(0, 0, 0.2, 1)` — incoming elements.
- `ease-accelerate` `cubic-bezier(0.4, 0, 1, 1)` — outgoing elements.

### Durations

- `duration-instant` 80ms — micro-feedback (toggle thumb, copy
  acknowledgement).
- `duration-fast` 150ms — button hover, link underline.
- `duration-standard` 240ms — card hover, input focus ring,
  tool-call phase entrance.
- `duration-slow` 320ms — modal entrance, theme swap fade.
- `duration-slower` 480ms — page transitions, hero reveal.

### Per-component micro-states

- **Button hover** — background tint shifts (`brand` → `brand-hover`)
  over 150ms. No translate, no scale, no shadow.
- **Card hover** — background `bg-card` → `bg-card-hover` over 240ms.
- **Link hover** — decoration color `text-faint` → `brand` over
  150ms.
- **Input focus** — ring fades in at 240ms with `ease-emphasized`.
- **Accordion (TraceViewer)** — Radix `accordion-down` /
  `accordion-up` with `--radix-accordion-content-height`, 240ms
  `ease-standard`.
- **Modal entrance** — opacity 0 → 1 with translate-y 8px → 0 over
  320ms `ease-emphasized`.
- **Tool-call phase progression** — each phase card opacity 0 → 1
  with translate-y 8px → 0 over 240ms `ease-emphasized`. Phases
  advance every 800 – 1200ms during the loop.
- **Streaming cursor** — `cursor-blink` 1s `step-end` infinite.
  Stops on stream end (visibility goes `hidden`).
- **Theme swap** — when `data-theme` changes, `` transitions
  `background-color` and `color` over 320ms `ease-standard`.

### Page transitions

The kit ships **without** view-transitions; each page loads
independently. Adopters can opt in via Next 16 view-transitions where
appropriate.

### Reduced motion

Honored at the root via `prefers-reduced-motion: reduce`. All
non-essential transitions become opacity-only at 80ms. The
streaming `cursor-blink` is replaced with a static brand-colored
caret. Tool-call phase entrances render instantly with no slide-in.
Theme swap snaps without transition.

## 9. Accessibility & A11y

### Contrast

| Pair | dark | bright | cool-blue |
| --- | --- | --- | --- |
| text on bg | 14.6 (AAA) | 17.5 (AAA) | 14.0 (AAA) |
| text-dim on bg | 5.9 (AA) | 7.4 (AAA) | 5.6 (AA) |
| text-on-brand on brand | 13.2 (AAA) | 4.7 (AA) | 11.8 (AAA) |
| brand on bg | 14.1 (AAA) | 4.5 (AA) | 6.5 (AA) |

The `bright` theme is tuned so emerald `#16a34a` clears AA at body
sizes against `#fafafa`; for AAA on small text, fall back to
`brand-deep` (`#14532d`).

### Focus indicators

A `2px solid var(--color-focus-ring)` ring with `2px offset` wraps
every interactive element. Uses `:focus-visible` so the ring only
appears on keyboard focus.

### ARIA patterns

- **ChatHero** streams: outer container is `aria-live="polite"
  aria-busy={isStreaming}`; finished messages are not announced
  again.
- **AgentTraceViewer** uses Radix `Accordion` semantics; each step
  trigger is a `` with proper `aria-expanded`.
- **ToolCallPanel** phase changes are announced via a hidden
  `aria-live="polite"` region: *"Tool call: search_web. Phase:
  result."*
- **ModelSelector** uses Radix `Select` (combobox pattern,
  WAI-ARIA 1.2).
- **Theme switcher** (dev mode) uses Radix `ToggleGroup`.

### Keyboard nav

Tab order matches DOM order. The `` chat input is
focusable and has `aria-label="Send a message to the agent"`.
The theme switcher is excluded from production tab order.

### Reduced motion

See §8. The streaming cursor and tool-call phase animation are
the two motion-heavy elements; both fall back to a static state
under reduced motion.

### Screen reader

Streaming chat output is announced incrementally via `aria-live`.
`` rows next to a heading are `aria-hidden`. Icon-only buttons
carry `aria-label`.

### Sizes

Minimum text size is `12px` (caption). Touch targets meet the 44px
minimum on mobile; chat input field is 48px height.

## 10. Responsive Behavior

| Breakpoint | Width | Anchor |
| --- | --- | --- |
| mobile | <480 | Single column, hero 48px |
| tablet | 480 – 768 | Single column, hero 56px |
| laptop | 768 – 1024 | Two-column where helpful, hero 64px |
| desktop | 1024 – 1280 | Full grids, hero 72px |
| wide | ≥1280 | Page-width capped at 1200 |

### Touch targets

44px minimum across mobile and tablet. Chat input is 48px.

### Collapsing strategy

- **Hero `1fr 1fr`** → stacks to single-column at <768px.
- **ChatHero feature row `1.4fr 1fr`** → stacks at <1024px with
  chat above prose.
- **TraceViewer `1fr 1fr`** → stacks at <1024px.
- **ToolCallPanel `1.4fr 1fr`** → stacks at <1024px.
- **Pricing 3-up** → 2-up at <1024px → 1-up at <640px.

### Image behavior

Theme-preview tiles use `aspect-ratio: 4/3` with `object-fit: cover`
inside a `bg-card` plate.

### Container queries

Used on `` so user-bubble width adapts when the chat
panel is in a sidebar vs full-width context.

## 11. Content & Voice

### Tone

**Technical, calm, agent-aware.** AgentKit writes for the developer
shipping their first agent product. Headlines are imperative and
ground-truthed. Adjectives are sparse; verbs are specific. Sample
hero: *"Ship your AI agent's landing page this afternoon.
65 components. 9 sections. Three swappable themes. One install."*

### Microcopy patterns

- **Buttons use verbs.** *Get AgentKit*, *Buy*, *View source*,
  *Read the docs*, *Try the demo*.
- **Errors describe the cause.** *"OPENAI_API_KEY missing. Add it to
  `.env.local` and restart."*
- **Success is quiet.** *"Theme set to bright."* — not *"Your theme
  preference has been successfully updated!"*
- **Empty states explain how to fill them.** *"No messages yet. Type
  below to ping the agent."*

### CTA verb conventions

- Primary: *Get AgentKit*, *Buy*, *Sign up*, *Try the demo*.
- Secondary: *View source*, *Read the docs*, *See examples*.
- Tertiary (link): *Learn more*, *Browse components*, *See all*.

The kit avoids: *Click here*, *Submit*, *Get started for free*,
*Transform your business*.

## 12. Dark Mode & Theming

AgentKit is **theme-first**. Three themes ship by default —
`editorial-dark` (default), `bright` (light), and `cool-blue`
(slate). Theme is selected via a `data-theme` attribute on ``
and persisted in `localStorage` as `agentkit:theme`. An inline
script in `` reads the stored value and applies it
synchronously **before paint** to prevent FOUC:

```html

```

CSS variables are declared per theme inside `:root[data-theme="..."]`
selectors using Tailwind 4's `@theme` directive. Components reference
`var(--color-*)` tokens only — never hex literals — so swapping
themes is a single attribute change with zero component rewrites.

When a developer ships AgentKit in production, they typically pick
**one** theme and remove the dev-only theme switcher from their
build. The system supports all three at runtime, but production
sites usually commit to one identity.

### System preference

`prefers-color-scheme` is read on first load. Users on a light OS
default to `bright`; users on a dark OS default to `editorial-dark`.
Stored preference always wins over system preference.

## 13. Lineage & Influences

AgentKit extends webdesignhot's editorial-dark canvas into a
three-theme system inspired by Vercel's Geist (themed but locked
to a single component library) and Linear's spatial restraint.
The chat-hero + agent-trace-viewer + tool-call-panel anchor
components are the kit's own contribution — there's no reference for
"agent product landing page" yet, so the kit defines the genre. The
cool-blue theme borrows its palette discipline from Stripe (deep
navy + cyan accent) for fintech-adjacent products; the bright theme
tracks Resend's clean daylight feel. Type system is unchanged across
themes — only color swaps — proving that hierarchy comes from size
and tracking, not hue.

What it rejects: gradient hero backgrounds, glow shadows, illustrated
3D agent mascots, "AI sparkles" iconography, multi-accent palettes,
600+ display weights, marketing pages that don't show the product.

**Named influences**
- [webdesignhot](https://www.webdesignhot.com) — source canvas, type
  voices, em-as-token rule.
- [Vercel Geist](https://vercel.com/geist/introduction) — themed but
  unified component library pattern.
- [Linear](https://linear.app) — spatial restraint, dense
  agent-product surfaces.
- [Stripe](https://stripe.com) — cool-blue palette discipline
  (fintech-grade calm).
- [Resend](https://resend.com) — bright theme's daylight clarity.
- [Anthropic](https://anthropic.com) — editorial calm, mono-with-dot
  section rhythm.
- [Rauno Freiberg](https://rauno.me) — italic-serif `` accents.

## 14. Do's and Don'ts

### Do

- Pick **one** theme before shipping production.
- Use `` for italic-serif accents inside display headlines.
- Reference colors via `var(--color-*)` only — never hex literals.
- Keep `` mono uppercase + brand dot at every section.
- Use the supplied keyframes (`accordion-down`, `accordion-up`,
  `cursor-blink`, `fade-in-up`).
- Apply theme via `data-theme` synchronously in `` to prevent
  FOUC.
- Use `text-on-brand` (theme-aware) on the brand CTA — never default
  to white or black.
- Honor `prefers-reduced-motion` everywhere.
- Use `:focus-visible` so the focus ring only appears on keyboard
  nav.
- Cap chat-message width at 80% so messages remain scannable.

### Don't

- Introduce a second accent color per theme.
- Use `brand` as a gradient or glow — solid fill only.
- `box-shadow` cards for depth — use `bg-card-hover` and
  `border-strong` instead.
- Hard-code hex values in components — always `var(--color-token)`.
- Ship with the theme switcher visible to your end users.
- Use bold (`700`+) weights on display type.
- Translate or scale buttons on hover — color-only state changes.
- Use `` for grammatical emphasis — it's a design token.
- Mix tokens between themes (e.g. dark text on bright background).
- Skip the streaming-cursor stop logic — the caret must disappear
  the moment the agent finishes speaking.

## 15. Agent Prompt Guide

### Quick Color Reference (editorial-dark default)

```
bg:           #0a0a0a
text:         #ededed
text-dim:     #8a8a8a
brand:        #c6f432
text-on-brand:#0a0a0a
bg-card:      #141416
border:       rgba(255,255,255,0.08)
focus-ring:   #c6f432
```

### Bright theme

```
bg:    #fafafa | text: #0a0a0a | brand: #16a34a | text-on-brand: #fff
```

### Cool-blue theme

```
bg:    #0b1120 | text: #f1f5f9 | brand: #06b6d4 | text-on-brand: #0b1120
```

### Example Component Prompts

1. *"Create an AgentKit ChatHero in the editorial-dark theme:
   `#141416` background, 16px radius, 24px padding, 1px
   `rgba(255,255,255,0.08)` border. Header is a mono uppercase row
   'AGENT • LIVE' with a 6px `#c6f432` dot. Below, alternating
   message bubbles — assistant on `#141416` left-aligned, user on
   `#1a1a1c` right-aligned, both 12px radius. Streaming cursor is a
   `#c6f432` `▋` glyph blinking at 1s step-end."*

2. *"Build an AgentTraceViewer card: `bg-card` background, 16px
   radius, 24px padding. Each step starts with a mono uppercase
   `01.` label in `text-dim`, the step title in 22px Inter / 500.
   Steps expand via Radix accordion with
   `--radix-accordion-content-height` over 240ms `ease-standard`.
   Inside an open step, render tool-call rows with mono code-inline
   for tool name and args."*

3. *"Compose a ToolCallPanel with 4 phases — prompt, calling, result,
   final — each as a small card with mono uppercase phase label and
   code-inline tool name. Phase progression slides each card in from
   below with 8px translate over 240ms `ease-emphasized`. Calling
   shows a spinning `text-dim` Loader; result shows a `success`
   checkmark."*

4. *"Design a primary button in the bright theme: `#16a34a`
   background, white text, 14px Inter / 500, 14/20px padding, 8px
   radius. Hover lightens to `#15913f` over 150ms — no scale, no
   glow."*

5. *"Build a theme-preview row showing the same hero in all three
   themes side-by-side: each tile is 4/3 aspect, `card` (16px)
   radius, 1px theme-appropriate border, with a mono uppercase
   label below the tile naming the theme. Tiles render the same
   ChatHero component — only colors differ."*

6. *"Create a section anchor: 64px section padding, mono uppercase
   label '03 — TRACE VIEWER' in `text-dim` 11/500/0.15em with brand
   dot, a 40px Inter / 500 / -0.025 tracking headline below, and an
   optional Instrument Serif italic `` accent inside the
   headline."*

### Iteration Guide

1. **Pick the default theme first.** Do all your composition in
   `editorial-dark` until the layout reads correctly. Only after the
   structure is solid, swap to `bright` and `cool-blue` and tune
   contrast.
2. **Reference variables only.** If you find yourself writing
   `#c6f432` in a component, replace it with `var(--color-brand)`
   immediately. The single discipline that makes the kit work.
3. **Hold the accent in reserve.** Don't introduce the brand color
   until the layout reads correctly without it. The accent should
   arrive as a deliberate moment.
4. **Build the anchor components first.** ChatHero, AgentTraceViewer,
   and ToolCallPanel are what differentiate the kit. Compose
   sections around them, not the other way around.
5. **Use `` once per hero.** Place exactly one Instrument Serif
   italic accent inside the display headline. Test that removing
   it flattens the page; test that adding a second one fights for
   attention.
6. **Apply the theme synchronously.** Read `localStorage` and set
   `data-theme` on `` in an inline `` script before
   first paint. FOUC is the most common single mistake when
   shipping multi-theme.
7. **Stop the streaming cursor.** The most common bug: the `▋`
   keeps blinking after the stream ends. Wire `isStreaming === false`
   to `visibility: hidden` on the cursor.
8. **Audit accent count per theme.** When you're done, count every
   `var(--color-brand)` reference. If it's above ~8 per page, remove
   the weakest two. The kit is at its strongest when the accent is
   rare on every theme.