glyph-ai 0.1.0

package/bundled/server/data/design.md

@@ -0,0 +1,971 @@
+# Design System
+
+This document serves two purposes:
+
+1. **A constraint system** — the rules, token structures, and component guidelines that all generated interfaces must adhere to, regardless of aesthetic direction.
+2. **A living token file** — when an agent reads this document alongside a codebase, it fills in the token values below based on what it finds, resolves any inconsistencies with the user, and uses the completed file as the source of truth for all subsequent generation.
+
+---
+
+## Agent Instructions
+
+> These instructions are for Claude Code, Cursor, or any agent with filesystem access. Read this section first and determine which mode applies before doing anything else.
+
+### Step 1 — Determine the operating mode
+
+Ask the user (or infer from their request) which of the following modes applies:
+
+**Mode A — Extract & Codify**
+> "My existing designs work. Turn them into a design system."
+
+The user wants their current design conventions captured and systematized. Do not change anything aesthetically. Your job is to observe, extract, and document.
+
+**Mode B — Improve & Codify**
+> "My existing designs need work. Improve them and create a design system."
+
+The user wants their design leveled up while keeping their intent intact. You will analyze what exists, propose a refined version, fill in the tokens with the improved values, and apply those values back to the codebase.
+
+---
+
+### Step 2 — Read the codebase
+
+Before filling in any tokens, scan the codebase for design signals. Look in:
+
+- CSS files, Tailwind config, CSS modules, styled-components, or any file with style definitions
+- Component files for inline styles or class usage patterns
+- Global stylesheets (`globals.css`, `index.css`, `app.css`, `theme.ts`, `tokens.ts`, etc.)
+- Any existing design token files (`tokens.json`, `theme.js`, etc.)
+
+Extract the following from what you find:
+
+| Signal | What to look for |
+|---|---|
+| Colors | Every hex, rgb, hsl, or Tailwind color value used. Group by frequency and role. |
+| Typefaces | Font family declarations, Google Fonts imports, `@font-face` blocks |
+| Font sizes | Every `font-size`, `text-*` class, or size value used |
+| Font weights | Every `font-weight` or `font-*` weight class used |
+| Spacing | Padding and margin values. Identify the base unit and scale. |
+| Border radius | Every `border-radius` or `rounded-*` value used |
+| Shadows | Every `box-shadow` value |
+| Breakpoints | Media query breakpoints defined or used |
+| Component patterns | Recurring UI structures: cards, buttons, inputs, nav, modals |
+
+---
+
+### Step 3 — Identify and resolve inconsistencies
+
+Before filling in the token template, check for conflicts. For each category below, if you find more than one value competing for the same role, **stop and ask the user to choose one before proceeding**.
+
+Use this exact prompt format when surfacing a conflict:
+
+```
+I found [N] values being used for [role]. Which should be the canonical token?
+
+  Option A: [value] — used in [files/components]
+  Option B: [value] — used in [files/components]
+  Option C: [value] — used in [files/components]  (if applicable)
+
+Pick one, or tell me a new value to use instead.
+```
+
+**Conflicts to check for:**
+
+- [ ] Multiple primary/accent colors (most common)
+- [ ] Multiple base font families
+- [ ] Inconsistent border radius values for the same component type (e.g. some buttons at 4px, some at 8px)
+- [ ] Spacing values that don't resolve to a consistent base unit
+- [ ] Multiple shadow levels used interchangeably
+- [ ] Mixed heading weight conventions (some h2s at 500, others at 700)
+
+Do not guess or average. Always ask.
+
+---
+
+### Step 4 — Fill in the token template
+
+Once you have extracted all values and resolved all conflicts, fill in **Section 15: Active Token Values** below. This is the canonical source of truth the agent uses for all code generation going forward.
+
+If operating in **Mode B**, apply the improvement guidelines in Section 16 before filling in tokens. Use the improved values — not the raw extracted ones — as the final token set.
+
+---
+
+### Step 5 — Apply tokens to the codebase (Mode B only)
+
+If the user requested improvements (Mode B):
+
+1. Replace all hardcoded color, spacing, radius, shadow, and font values in the codebase with references to the new CSS custom properties.
+2. Update component styles to match the improved token values.
+3. Do not restructure component logic — only modify styles.
+4. After applying, summarize what changed in a brief changelog comment at the bottom of this file.
+
+---
+
+## 1. Guiding Principles
+
+Before generating any interface, the agent must:
+
+1. **Choose a clear aesthetic direction** and commit to it. Vague or blended aesthetics produce incoherent results.
+2. **Establish a conceptual anchor** — one word or phrase that describes the feeling of the UI (e.g. "surgical", "warm", "kinetic", "archival").
+3. **Apply tokens consistently** — never deviate from defined spacing, type scale, and color roles mid-component.
+4. **Default to restraint** — when uncertain, do less. Complexity must be earned by context.
+
+---
+
+## 2. Color
+
+### Roles
+
+Every color used must be assigned to one of these semantic roles. Never apply color arbitrarily.
+
+| Role | Description |
+|---|---|
+| `background` | Page or surface base |
+| `surface` | Cards, panels, modals — elevated above background |
+| `border` | Dividers, outlines, separators |
+| `text-primary` | Primary readable content |
+| `text-secondary` | Supporting labels, captions, metadata |
+| `text-disabled` | Inactive or non-interactive content |
+| `accent` | Brand or action color — used sparingly |
+| `accent-hover` | Hover state of accent |
+| `destructive` | Errors, delete actions, warnings |
+| `success` | Confirmations, completion states |
+
+### Rules
+
+- **Use CSS custom properties** for all color values. Never hardcode hex values inline.
+- **Palette size**: Limit to 6–8 colors per UI. Additional shades must derive from the core palette (e.g. `accent` at 10% opacity for hover backgrounds).
+- **Contrast**: Text on any background must meet WCAG AA minimum (4.5:1 for body, 3:1 for large text/UI elements).
+- **Accent restraint**: The accent color should occupy no more than ~10–15% of visual surface area. If it appears everywhere, it means nothing.
+- **Dark and light modes**: If the UI supports both, define both in tokens. Never assume one mode.
+
+### Anti-patterns
+
+- ❌ Purple gradients on white — overused AI default
+- ❌ More than two colors competing for attention in a single component
+- ❌ Using accent color for non-interactive decorative elements
+- ❌ Low-contrast text rationalized as "secondary" — still must pass AA
+
+---
+
+## 3. Typography
+
+### Typeface Selection
+
+- Choose **two typefaces maximum** per UI: one for display/headings, one for body/UI. A single well-chosen typeface with varied weights is also acceptable.
+- Typefaces must be **loaded from a reliable CDN** (e.g. Google Fonts, Bunny Fonts) or declared as system font stacks.
+- **Avoid**: Inter, Roboto, Arial, and system-ui as the sole type choice. These are defaults, not decisions.
+- **Prefer**: Typefaces with clear personality that matches the conceptual anchor — geometric sans, humanist, transitional serif, monospace, slab serif, etc.
+
+### Type Scale
+
+Use a consistent modular scale. Suggested base: `1rem` (16px) with a 1.25 or 1.333 ratio.
+
+| Token | Suggested Size | Usage |
+|---|---|---|
+| `text-xs` | 0.75rem | Captions, badges, timestamps |
+| `text-sm` | 0.875rem | Labels, secondary UI text |
+| `text-base` | 1rem | Body copy, form inputs |
+| `text-lg` | 1.125rem | Lead text, emphasized body |
+| `text-xl` | 1.25rem | Subheadings, card titles |
+| `text-2xl` | 1.5rem | Section headings |
+| `text-3xl` | 1.875rem | Page titles |
+| `text-4xl+` | 2.25rem+ | Display / hero text |
+
+### Line Height & Spacing
+
+| Context | Line Height |
+|---|---|
+| Body text | 1.6–1.7 |
+| UI labels / buttons | 1.2–1.3 |
+| Display headings | 1.0–1.15 |
+
+- **Letter spacing**: Tighten large headings (`-0.02em` to `-0.04em`). Loosen small caps or labels (`0.05em` to `0.1em`). Body text: default (0).
+- **Max line length**: 60–75 characters for readable body copy. Never let text span full viewport width unconstrained.
+
+### Rules
+
+- **Never mix more than two type sizes within a single component** unless establishing a clear hierarchy.
+- **Font weight** is a hierarchy tool — use it intentionally. Three weights maximum per UI (e.g. 400, 500, 700).
+- **Avoid italic for UI labels** — use weight or color for emphasis instead.
+
+---
+
+## 4. Spacing
+
+### Scale
+
+All spacing values must come from a defined scale. Use multiples of a base unit (4px recommended).
+
+| Token | Value | Usage |
+|---|---|---|
+| `space-1` | 4px | Tight internal padding, icon gaps |
+| `space-2` | 8px | Component internal spacing |
+| `space-3` | 12px | Small gaps between related elements |
+| `space-4` | 16px | Standard padding unit |
+| `space-6` | 24px | Section separation within components |
+| `space-8` | 32px | Between components |
+| `space-12` | 48px | Between sections |
+| `space-16` | 64px | Major layout sections |
+| `space-24` | 96px | Hero / page-level breathing room |
+
+### Rules
+
+- **Never use arbitrary values** like `margin: 13px`. All spacing must map to a token.
+- **Consistent internal padding**: Components of the same type must share padding values (e.g. all cards use `space-6` internal padding).
+- **Whitespace is intentional** — generous spacing signals clarity and confidence. Cramped UIs signal poor decisions, not information density.
+- **Vertical rhythm**: Maintain consistent spacing between typographic elements. Headings should have more space above than below.
+
+---
+
+## 5. Layout
+
+### Grid
+
+- Use a **12-column grid** for complex layouts, **4-column** for mobile.
+- Define a **max content width** and center it. Recommended: `1200px–1440px` for full layouts, `720px` for reading/form-heavy pages.
+- Use **CSS Grid** for two-dimensional layout, **Flexbox** for one-dimensional (rows, stacks, nav bars).
+
+### Responsive Breakpoints
+
+| Name | Min Width | Typical Usage |
+|---|---|---|
+| `sm` | 640px | Large phones, small tablets |
+| `md` | 768px | Tablets |
+| `lg` | 1024px | Laptops |
+| `xl` | 1280px | Desktops |
+| `2xl` | 1536px | Large screens |
+
+- **Mobile-first**: Write base styles for mobile, layer up with breakpoints.
+- **Never hide critical content on mobile** — simplify layout, not information.
+
+### Rules
+
+- **Align to the grid** — elements that break the grid must do so intentionally (e.g. a full-bleed image, an overlapping decorative element). Accidental misalignment is always wrong.
+- **Consistent gutters**: Gutter width must be uniform across a layout tier (e.g. 24px gutters on desktop everywhere, not 24px in one section and 16px in another).
+- **Group related elements visually** — proximity implies relationship. Elements that belong together must be spaced tighter than elements that don't.
+
+---
+
+## 6. Borders & Radius
+
+### Border
+
+- **Default border**: `1px solid var(--border)` — never thicker unless intentionally expressive.
+- **Border as separator**: Use `border-bottom` or `border-top` for dividers, not full-box borders on list items.
+- **Avoid decorative borders** that don't communicate structure.
+
+### Radius
+
+Define a radius scale and apply it consistently by component type.
+
+| Token | Value | Usage |
+|---|---|---|
+| `radius-sm` | 4px | Badges, tags, small inputs |
+| `radius-md` | 8px | Buttons, inputs, cards |
+| `radius-lg` | 12px | Modals, panels, popovers |
+| `radius-xl` | 16px | Large cards, image containers |
+| `radius-full` | 9999px | Pills, avatar circles, toggles |
+
+- **Consistency within component type**: All buttons share one radius value. All cards share one radius value. Never mix radii within the same component class.
+- **Sharp vs. rounded**: The radius choice contributes to aesthetic personality. Commit to one direction — tight/sharp for utilitarian, generous/rounded for approachable — and apply it uniformly.
+
+---
+
+## 7. Elevation & Shadow
+
+Shadows communicate hierarchy and separation. Use them intentionally, not decoratively.
+
+| Level | Usage | Suggested Value |
+|---|---|---|
+| `shadow-sm` | Subtle card lift | `0 1px 3px rgba(0,0,0,0.08)` |
+| `shadow-md` | Dropdowns, popovers | `0 4px 12px rgba(0,0,0,0.10)` |
+| `shadow-lg` | Modals, floating panels | `0 8px 32px rgba(0,0,0,0.14)` |
+| `shadow-none` | Flat surfaces, no elevation | — |
+
+### Rules
+
+- **One elevation level per component** — never stack multiple shadows on the same element.
+- **Dark mode**: Replace box shadows with borders or background differentiation (`surface` token) — shadows don't read on dark backgrounds.
+- **Don't use shadows as decoration** — they should communicate that something is above another layer.
+
+---
+
+## 8. Iconography
+
+- Use a **single icon library** per project. Don't mix Heroicons with Lucide with Material — inconsistent stroke weights and styles clash.
+- **Preferred**: Lucide, Heroicons, Phosphor (all consistent, open-source, multiple weights).
+- **Size**: Icons must align to the type scale of their context. Icon beside `text-base` label → 16px icon. Icon in a heading → match heading cap height.
+- **Stroke weight**: Match the weight of the chosen icon set to the overall aesthetic. Light strokes = refined. Heavier strokes = bold/accessible.
+- **Never use emoji as functional UI icons.**
+
+---
+
+## 9. Motion & Animation
+
+Motion must serve communication, not decoration.
+
+### Principles
+
+- **Purposeful**: Every animation must have a reason — feedback, orientation, hierarchy, or delight.
+- **Fast**: UI transitions should feel instant but smooth. Most transitions: `150ms–300ms`. Entrances: up to `400ms`.
+- **Easing**: Use `ease-out` for elements entering the screen (decelerating = natural). Use `ease-in` for exits. Avoid `linear` except for looping animations (spinners).
+- **Reduced motion**: Always respect `prefers-reduced-motion`. Wrap all non-essential animations in a media query check.
+
+### Common Patterns
+
+| Pattern | Duration | Easing |
+|---|---|---|
+| Button hover state | 100–150ms | ease-out |
+| Dropdown/popover open | 150–200ms | ease-out |
+| Modal entrance | 200–300ms | ease-out |
+| Page section reveal | 300–500ms | ease-out |
+| Toast notification | 250ms in / 200ms out | ease-out / ease-in |
+| Skeleton shimmer | 1.5s loop | linear |
+
+### Rules
+
+- **Stagger, don't overwhelm**: If animating a list of items in, stagger by `50–80ms` per item. Don't animate more than 5–6 items in a sequence.
+- **Don't animate layout properties** (`width`, `height`, `top`, `left`) — use `transform` and `opacity` for performance.
+- ❌ Avoid: Bouncy springs on functional UI elements, excessive particle effects, animations that delay interaction.
+- ❌ Avoid: Animating everything on page load — one well-executed entrance is more effective than a cascade of movement.
+
+---
+
+## 10. Component Guidelines
+
+### Buttons
+
+- **Hierarchy**: One primary action per view. Secondary and ghost variants for supporting actions.
+- **Sizing**: Minimum tap target 44×44px (mobile). Desktop: height `36px` (sm), `40px` (md), `48px` (lg).
+- **States**: Every button must have `default`, `hover`, `active`, `focus`, and `disabled` states defined.
+- **Labels**: Verb-first ("Save changes", "Delete account", not "Changes" or "Account deletion").
+- ❌ Never use more than one primary button per section.
+
+### Inputs & Forms
+
+- **Label above input**, always. Placeholder text is not a label.
+- **Error messages** appear below the input in `destructive` color with an icon.
+- **Focus state**: Must be visible — `2px outline` offset by `2px` using the `accent` color.
+- **Input height**: Match button height for the same size tier (consistent rhythm).
+- **Disabled state**: Reduced opacity (`0.4–0.5`) + `cursor: not-allowed`.
+
+### Cards
+
+- One consistent internal padding token (e.g. `space-6` everywhere).
+- Clear visual separation from background via `surface` color, `shadow-sm`, or `border`.
+- Don't overload a card — one primary action, one primary data point.
+
+### Navigation
+
+- **Active state** must be unambiguous — not just a color change, but weight or indicator.
+- **Mobile nav**: Hamburger menus are acceptable; bottom tab bars are preferred for primary navigation on mobile apps.
+- Never rely solely on color to indicate active state (accessibility).
+
+### Modals & Dialogs
+
+- Always include a visible close affordance (× button or explicit "Cancel").
+- **Backdrop**: Semi-transparent overlay (`rgba(0,0,0,0.4–0.6)`) behind the modal.
+- **Focus trap**: Keyboard focus must be trapped inside an open modal.
+- **Max width**: Modals should not exceed `560px` for forms/confirmations, `800px` for content-heavy dialogs.
+
+### Empty States
+
+- Every list, table, or data view must have an empty state.
+- Empty states must include: an illustration or icon, a clear label, and a primary call to action where appropriate.
+- ❌ Never show a blank white box with no content.
+
+### Loading States
+
+- **Skeleton screens** over spinners for content-heavy loads (cards, lists, tables).
+- **Inline spinners** for button actions and small fetch operations.
+- **Progress indicators** for long operations with knowable duration.
+- All loading states must communicate that something is happening — never leave the user with a frozen UI.
+
+---
+
+## 11. Accessibility Baselines
+
+These are non-negotiable floors, not aspirational targets.
+
+- **Color contrast**: AA minimum for all text. AAA preferred for body copy.
+- **Keyboard navigation**: All interactive elements reachable and operable via keyboard.
+- **Focus indicators**: Never remove focus outlines. Style them to match the design system.
+- **Semantic HTML**: Use correct elements (`<button>` for actions, `<a>` for navigation, heading hierarchy, `<label>` for inputs).
+- **ARIA**: Only use ARIA attributes when semantic HTML is insufficient. Don't over-ARIA.
+- **Alt text**: All meaningful images have descriptive `alt` attributes. Decorative images use `alt=""`.
+- **Touch targets**: Minimum 44×44px on mobile.
+
+---
+
+## 12. Anti-patterns (Global)
+
+The following are prohibited in all generated interfaces regardless of aesthetic direction:
+
+| Anti-pattern | Why |
+|---|---|
+| Hardcoded color values (`#3B82F6` inline) | Breaks theming and token system |
+| Arbitrary spacing values (`margin: 13px`) | Breaks spatial consistency |
+| More than 2 typefaces | Visual noise, loading overhead |
+| Missing hover/focus/disabled states | Incomplete component contracts |
+| Color as the only differentiator for state | Accessibility failure |
+| Placeholder as label | Disappears on input; fails accessibility |
+| Shadows on dark mode surfaces | Invisible, looks broken |
+| Animations on layout properties | Causes jank and repaints |
+| Blank empty states | Disorienting UX |
+| Mixing icon libraries | Inconsistent visual language |
+| Generic purple gradient on white | Overused AI aesthetic default |
+| Full-width body text (no max-width) | Unreadable line lengths |
+
+---
+
+## 13. Token Reference Template
+
+Use this template when initializing a new project's CSS custom properties:
+
+```css
+:root {
+  /* Color */
+  --color-background: ;
+  --color-surface: ;
+  --color-border: ;
+  --color-text-primary: ;
+  --color-text-secondary: ;
+  --color-text-disabled: ;
+  --color-accent: ;
+  --color-accent-hover: ;
+  --color-destructive: ;
+  --color-success: ;
+
+  /* Typography */
+  --font-display: ;
+  --font-body: ;
+
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+  --text-2xl: 1.5rem;
+  --text-3xl: 1.875rem;
+  --text-4xl: 2.25rem;
+
+  /* Spacing */
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-12: 48px;
+  --space-16: 64px;
+  --space-24: 96px;
+
+  /* Radius */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-xl: 16px;
+  --radius-full: 9999px;
+
+  /* Shadow */
+  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.08);
+  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.10);
+  --shadow-lg: 0 8px 32px rgba(0, 0, 0, 0.14);
+}
+```
+
+---
+
+## 14. Aesthetic Direction: Precision Dark
+
+**Conceptual anchor**: Surgical. Clinical. Unhurried.
+
+Inspired by the visual language of ElevenLabs — dark-mode-first, typographically restrained, almost no decorative color. Every element earns its place. The UI feels like a tool built by people who trust the product to speak for itself.
+
+---
+
+### 14.1 Personality
+
+| Attribute | Value |
+|---|---|
+| Mode | Dark-first |
+| Density | Low-to-medium. Breathing room over information density. |
+| Personality | Restrained, precise, confident |
+| Color usage | Near-monochromatic. One accent, used sparingly. |
+| Motion | Minimal. Functional only. |
+| Radius | Tight. Sharp-edged components. |
+| Borders | Subtle. Structure via contrast, not heavy lines. |
+
+---
+
+### 14.2 Color Tokens
+
+```css
+:root {
+  /* Backgrounds */
+  --color-background: #0a0a0a;       /* Near-black page base */
+  --color-surface: #111111;          /* Cards, sidebars, panels */
+  --color-surface-raised: #1a1a1a;   /* Hover state surfaces, nested panels */
+
+  /* Borders */
+  --color-border: #222222;           /* Default border — barely visible */
+  --color-border-strong: #333333;    /* Emphasized dividers, active states */
+
+  /* Text */
+  --color-text-primary: #f5f5f5;     /* Primary content */
+  --color-text-secondary: #888888;   /* Labels, metadata, captions */
+  --color-text-disabled: #444444;    /* Inactive elements */
+  --color-text-inverse: #0a0a0a;     /* Text on accent backgrounds */
+
+  /* Accent */
+  --color-accent: #e8e8e8;           /* Off-white — primary interactive */
+  --color-accent-hover: #ffffff;     /* Full white on hover */
+  --color-accent-subtle: rgba(232, 232, 232, 0.08); /* Hover fill on ghost elements */
+
+  /* Semantic */
+  --color-destructive: #ef4444;
+  --color-destructive-subtle: rgba(239, 68, 68, 0.10);
+  --color-success: #22c55e;
+  --color-success-subtle: rgba(34, 197, 94, 0.10);
+}
+```
+
+**Color usage rules for this aesthetic:**
+- The accent is off-white, not a hue. This keeps the palette near-monochromatic and avoids competing focal points.
+- Use `--color-accent` only for primary buttons, active states, and critical interactive affordances.
+- Surface differentiation is done through subtle background lightness steps (`#0a0a0a` → `#111` → `#1a1a1a`), not shadows.
+- No gradients on UI elements. Gradients are permitted only on illustrative/hero visuals and must be subtle (low-contrast, dark-on-dark).
+- ❌ No colored glows, no neon accents, no brand-color fills on surfaces.
+
+---
+
+### 14.3 Typography Tokens
+
+```css
+:root {
+  --font-display: 'Geist', 'DM Sans', sans-serif;  /* Clean geometric sans */
+  --font-body: 'Geist', 'DM Sans', sans-serif;     /* Unified — one family */
+  --font-mono: 'Geist Mono', 'JetBrains Mono', monospace;
+
+  --font-weight-regular: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+}
+```
+
+**Typography rules for this aesthetic:**
+- One typeface throughout. Hierarchy is created through size and weight alone — not through font mixing.
+- Headings: `font-weight: 500` or `600`. Never heavy/bold (700+) — this aesthetic avoids aggression.
+- Body: `font-weight: 400`. `line-height: 1.6`.
+- Labels and UI metadata: `font-weight: 400–500`, `--text-sm`, `--color-text-secondary`.
+- Monospace for any code, API keys, file names, or data values.
+- Letter spacing on headings: `-0.02em` to `-0.03em`. Tighten, don't loosen.
+- ❌ No decorative typefaces. No serif. No display fonts with personality — the restraint is the personality.
+
+---
+
+### 14.4 Spacing Behavior
+
+This aesthetic uses **generous vertical space** and **tight horizontal padding**.
+
+- Page-level sections: `--space-16` to `--space-24` vertical separation.
+- Component internal padding: `--space-4` (16px) horizontal, `--space-3` (12px) vertical for standard density.
+- Between a label and its value: `--space-1` to `--space-2`.
+- Between sibling components: `--space-6` to `--space-8`.
+- Content max-width: `720px` for reading/form views. `1100px` for dashboards.
+
+---
+
+### 14.5 Border & Radius
+
+```css
+:root {
+  --radius-sm: 4px;    /* Badges, tags */
+  --radius-md: 6px;    /* Buttons, inputs — keep it tight */
+  --radius-lg: 8px;    /* Cards, panels */
+  --radius-xl: 10px;   /* Modals — still restrained */
+  --radius-full: 9999px;
+}
+```
+
+- Radius is **deliberately small**. The sharpness signals precision.
+- Borders default to `1px solid var(--color-border)` — barely visible, structure through contrast not lines.
+- No heavy border treatments. No 2px borders except for active/selected component states.
+
+---
+
+### 14.6 Elevation & Shadows
+
+- **Shadows are not used** as the primary elevation signal in dark mode.
+- Elevation is communicated via background color stepping:
+  - Page → `#0a0a0a`
+  - Sidebar / panel → `#111111`
+  - Card / modal → `#1a1a1a`
+- If a shadow is needed (e.g. a floating dropdown), use:
+  ```css
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.5);
+  ```
+- ❌ No colorful or glowing shadows.
+
+---
+
+### 14.7 Component Specifics
+
+**Buttons**
+- Primary: `background: var(--color-accent)` (off-white), `color: var(--color-text-inverse)`, `radius: var(--radius-md)`.
+- Secondary/Ghost: transparent background, `border: 1px solid var(--color-border-strong)`, text `--color-text-primary`. On hover: `background: var(--color-accent-subtle)`.
+- Destructive: ghost by default, text in `--color-destructive`. Reserve filled destructive for confirmation dialogs only.
+- Height: `36px` (sm), `40px` (md — default). No large buttons unless hero context.
+- Padding: `12px 16px` (md).
+
+**Inputs**
+- Background: `var(--color-surface)`.
+- Border: `1px solid var(--color-border)`. On focus: `1px solid var(--color-border-strong)` + `outline: 2px solid rgba(232,232,232,0.15)`.
+- No colored focus rings — keep it monochromatic.
+- Placeholder: `var(--color-text-disabled)`.
+
+**Cards / Panels**
+- Background: `var(--color-surface)`.
+- Border: `1px solid var(--color-border)`. No shadow.
+- Internal padding: `--space-6` (24px).
+- Header/body division: `border-bottom: 1px solid var(--color-border)`, not a background color change.
+
+**Navigation (Sidebar)**
+- Background: matches `--color-surface` or `--color-background` — flush with page.
+- Active item: `background: var(--color-surface-raised)`, `color: var(--color-text-primary)`. No colored indicator bar — background shift is sufficient.
+- Inactive items: `--color-text-secondary`.
+- Icon + label pairs: `--space-2` gap, icons at 16px.
+
+**Data / Labels**
+- Key-value pairs: label in `--color-text-secondary` `--text-sm`, value in `--color-text-primary` `--text-base` or `--text-sm`.
+- Tables: no zebra striping. Row hover: `background: var(--color-surface-raised)`. Header row: `--color-text-secondary`, `--text-xs`, uppercase, `letter-spacing: 0.06em`.
+
+---
+
+### 14.8 Motion Rules
+
+This aesthetic uses **the minimum effective motion**.
+
+- Transition duration: `150ms` for hover states, `200ms` for panel opens, `250ms` for modals.
+- Easing: `ease-out` universally.
+- Entrance animations: `opacity: 0 → 1` + `translateY(4px) → translateY(0)`. Subtle. Never slides more than 6–8px.
+- ❌ No spring physics. No elastic easing. No bounce.
+- ❌ No staggered list animations unless the list load is a primary UX moment.
+- ❌ No background particle effects, no ambient motion.
+
+---
+
+### 14.9 Do / Don't Summary
+
+| ✅ Do | ❌ Don't |
+|---|---|
+| Near-black backgrounds with layered surfaces | True black `#000000` — too harsh |
+| Off-white accent, used sparingly | Colored accents (blue, purple, green) |
+| One geometric sans typeface | Mixing fonts or using serifs |
+| Tight radius (4–8px) | Pill-shaped cards or panels |
+| Structure via border + bg contrast | Heavy shadows or glows |
+| Generous vertical breathing room | Dense, packed layouts |
+| Monochromatic palette with 1 semantic accent | Multi-color UI elements |
+| Minimal, fast transitions | Bouncy, expressive animation |
+| Subtle `translateY` entrance motion | Full slide-ins or dramatic reveals |
+
+---
+
+## 15. Active Token Values
+
+> **Agent instructions**: This section is filled in by the agent after reading the codebase (Step 4 of the Agent Instructions above). Replace every `FILL_IN` placeholder with the extracted or improved value. Do not leave any placeholder blank — if a value cannot be determined from the codebase, make a best-judgment recommendation and flag it with a `# inferred` comment.
+>
+> Once filled in, this section is the canonical source of truth. All code generation must reference these tokens.
+
+### 15.1 Metadata
+
+```
+Codebase path:         FILL_IN
+Mode:                  FILL_IN  (A — Extract & Codify  |  B — Improve & Codify)
+Conceptual anchor:     FILL_IN  (one word or phrase describing the aesthetic)
+Date extracted:        FILL_IN
+Conflicts resolved:    FILL_IN  (list any, or "none")
+```
+
+---
+
+### 15.2 Color Tokens
+
+```css
+:root {
+  /* --- Backgrounds --- */
+  --color-background:        FILL_IN;   /* Page base */
+  --color-surface:           FILL_IN;   /* Cards, panels, sidebars */
+  --color-surface-raised:    FILL_IN;   /* Hover surfaces, nested panels */
+
+  /* --- Borders --- */
+  --color-border:            FILL_IN;   /* Default border */
+  --color-border-strong:     FILL_IN;   /* Active states, emphasized dividers */
+
+  /* --- Text --- */
+  --color-text-primary:      FILL_IN;   /* Primary readable content */
+  --color-text-secondary:    FILL_IN;   /* Labels, captions, metadata */
+  --color-text-disabled:     FILL_IN;   /* Inactive elements */
+  --color-text-inverse:      FILL_IN;   /* Text on accent-colored backgrounds */
+
+  /* --- Accent --- */
+  --color-accent:            FILL_IN;   /* Primary interactive / brand color */
+  --color-accent-hover:      FILL_IN;   /* Accent on hover */
+  --color-accent-subtle:     FILL_IN;   /* Low-opacity accent for hover fills */
+
+  /* --- Semantic --- */
+  --color-destructive:       FILL_IN;
+  --color-destructive-subtle: FILL_IN;
+  --color-success:           FILL_IN;
+  --color-success-subtle:    FILL_IN;
+}
+```
+
+**Light mode** (fill in if the UI supports both modes):
+
+```css
+[data-theme="light"] {
+  --color-background:        FILL_IN;
+  --color-surface:           FILL_IN;
+  --color-surface-raised:    FILL_IN;
+  --color-border:            FILL_IN;
+  --color-border-strong:     FILL_IN;
+  --color-text-primary:      FILL_IN;
+  --color-text-secondary:    FILL_IN;
+  --color-text-disabled:     FILL_IN;
+  --color-text-inverse:      FILL_IN;
+  --color-accent:            FILL_IN;
+  --color-accent-hover:      FILL_IN;
+  --color-accent-subtle:     FILL_IN;
+}
+```
+
+---
+
+### 15.3 Typography Tokens
+
+```css
+:root {
+  --font-display:          FILL_IN;   /* Display / heading typeface */
+  --font-body:             FILL_IN;   /* Body / UI typeface */
+  --font-mono:             FILL_IN;   /* Code, data values, keys */
+
+  --font-weight-regular:   FILL_IN;   /* e.g. 400 */
+  --font-weight-medium:    FILL_IN;   /* e.g. 500 */
+  --font-weight-semibold:  FILL_IN;   /* e.g. 600 */
+
+  --text-xs:    FILL_IN;   /* e.g. 0.75rem */
+  --text-sm:    FILL_IN;   /* e.g. 0.875rem */
+  --text-base:  FILL_IN;   /* e.g. 1rem */
+  --text-lg:    FILL_IN;   /* e.g. 1.125rem */
+  --text-xl:    FILL_IN;   /* e.g. 1.25rem */
+  --text-2xl:   FILL_IN;   /* e.g. 1.5rem */
+  --text-3xl:   FILL_IN;   /* e.g. 1.875rem */
+  --text-4xl:   FILL_IN;   /* e.g. 2.25rem */
+
+  --leading-tight:   FILL_IN;   /* Headings, e.g. 1.1 */
+  --leading-snug:    FILL_IN;   /* UI labels, e.g. 1.3 */
+  --leading-normal:  FILL_IN;   /* Body copy, e.g. 1.6 */
+
+  --tracking-tight:  FILL_IN;   /* Large headings, e.g. -0.02em */
+  --tracking-normal: 0;
+  --tracking-wide:   FILL_IN;   /* Uppercase labels, e.g. 0.06em */
+}
+```
+
+**Notes** (fill in after extraction):
+```
+Heading weight:    FILL_IN
+Body weight:       FILL_IN
+Max line length:   FILL_IN  (characters)
+Font source:       FILL_IN  (Google Fonts / Bunny / self-hosted / system)
+```
+
+---
+
+### 15.4 Spacing Tokens
+
+```css
+:root {
+  --space-base: FILL_IN;   /* Base unit, e.g. 4px */
+
+  --space-1:   FILL_IN;    /* 1× base */
+  --space-2:   FILL_IN;    /* 2× base */
+  --space-3:   FILL_IN;    /* 3× base */
+  --space-4:   FILL_IN;    /* 4× base */
+  --space-6:   FILL_IN;    /* 6× base */
+  --space-8:   FILL_IN;    /* 8× base */
+  --space-12:  FILL_IN;    /* 12× base */
+  --space-16:  FILL_IN;    /* 16× base */
+  --space-24:  FILL_IN;    /* 24× base */
+}
+```
+
+**Notes**:
+```
+Component internal padding (standard):   FILL_IN
+Between sibling components:              FILL_IN
+Between page sections:                   FILL_IN
+Content max-width (reading):             FILL_IN
+Content max-width (dashboard):           FILL_IN
+```
+
+---
+
+### 15.5 Border & Radius Tokens
+
+```css
+:root {
+  --border-width:         FILL_IN;   /* e.g. 1px */
+  --border-style:         FILL_IN;   /* e.g. solid */
+
+  --radius-sm:    FILL_IN;   /* Badges, tags */
+  --radius-md:    FILL_IN;   /* Buttons, inputs */
+  --radius-lg:    FILL_IN;   /* Cards, panels */
+  --radius-xl:    FILL_IN;   /* Modals */
+  --radius-full:  9999px;
+}
+```
+
+---
+
+### 15.6 Shadow Tokens
+
+```css
+:root {
+  --shadow-sm:    FILL_IN;   /* Subtle card lift */
+  --shadow-md:    FILL_IN;   /* Dropdowns, popovers */
+  --shadow-lg:    FILL_IN;   /* Modals, floating panels */
+  --shadow-none:  none;
+}
+```
+
+**Notes**:
+```
+Elevation strategy:   FILL_IN  (shadows | background-stepping | borders | mixed)
+Dark mode approach:   FILL_IN
+```
+
+---
+
+### 15.7 Motion Tokens
+
+```css
+:root {
+  --duration-fast:    FILL_IN;   /* Hover states, e.g. 150ms */
+  --duration-base:    FILL_IN;   /* Panel opens, e.g. 200ms */
+  --duration-slow:    FILL_IN;   /* Modals, entrances, e.g. 300ms */
+
+  --ease-out:   cubic-bezier(0.0, 0.0, 0.2, 1);
+  --ease-in:    cubic-bezier(0.4, 0.0, 1, 1);
+  --ease-inout: cubic-bezier(0.4, 0.0, 0.2, 1);
+}
+```
+
+**Entrance animation pattern**:
+```
+FILL_IN  (e.g. opacity 0→1 + translateY(4px)→0, duration: --duration-slow, easing: --ease-out)
+```
+
+---
+
+### 15.8 Breakpoints
+
+```css
+/* FILL_IN — confirm or adjust based on codebase */
+--breakpoint-sm:   640px;
+--breakpoint-md:   768px;
+--breakpoint-lg:   1024px;
+--breakpoint-xl:   1280px;
+--breakpoint-2xl:  1536px;
+```
+
+---
+
+### 15.9 Component Conventions
+
+> Fill in after reading component files. One row per component type found in the codebase.
+
+| Component | Radius | Padding | Border | Shadow | Notes |
+|---|---|---|---|---|---|
+| Button (primary) | FILL_IN | FILL_IN | FILL_IN | FILL_IN | |
+| Button (secondary) | FILL_IN | FILL_IN | FILL_IN | FILL_IN | |
+| Input | FILL_IN | FILL_IN | FILL_IN | FILL_IN | |
+| Card | FILL_IN | FILL_IN | FILL_IN | FILL_IN | |
+| Modal | FILL_IN | FILL_IN | FILL_IN | FILL_IN | |
+| Nav item (active) | FILL_IN | FILL_IN | FILL_IN | FILL_IN | |
+| Badge / Tag | FILL_IN | FILL_IN | FILL_IN | FILL_IN | |
+| Table row (hover) | FILL_IN | FILL_IN | FILL_IN | FILL_IN | |
+
+---
+
+## 16. Improvement Guidelines (Mode B Only)
+
+> Read this section only if operating in **Mode B — Improve & Codify**. These are the upgrade criteria applied before filling in Section 15 tokens. Use the improved values — not the raw extracted values — when completing the token template.
+
+When improving an existing design, evaluate each category below and apply the relevant upgrade if the existing design falls short.
+
+### 16.1 Color
+
+| If the codebase has… | Upgrade to… |
+|---|---|
+| More than 8 distinct colors | Consolidate. Map all colors to the role system in Section 2. Eliminate any that don't serve a role. |
+| Hardcoded hex values throughout | Extract to CSS custom properties. |
+| Low-contrast text | Adjust text or background values to meet WCAG AA. |
+| A colored accent used everywhere | Reduce usage to interactive elements only. Create an `accent-subtle` token for hover fills. |
+| No dark mode | Add a `[data-theme="dark"]` layer if the aesthetic warrants it. Flag if unsure. |
+| Generic blue/purple as accent | Keep if it's intentional brand color. Flag as worth revisiting if it appears to be a framework default. |
+
+### 16.2 Typography
+
+| If the codebase has… | Upgrade to… |
+|---|---|
+| Inter, Roboto, or Arial as the only typeface | Replace with a more characterful choice that fits the aesthetic. Retain if it's an intentional brand decision — ask the user. |
+| More than 3 font weights | Reduce to 3. Map usage to `regular`, `medium`, `semibold`. |
+| No consistent type scale | Map all sizes to the nearest step on the modular scale. Eliminate outliers. |
+| Heading weights at 700+ | Reduce to 500–600 for a more refined feel, unless bold is core to the aesthetic. |
+| Inconsistent line heights | Normalize to `--leading-tight` (headings), `--leading-snug` (UI), `--leading-normal` (body). |
+
+### 16.3 Spacing
+
+| If the codebase has… | Upgrade to… |
+|---|---|
+| Arbitrary margin/padding values (e.g. 13px, 22px) | Round to nearest scale step. |
+| No consistent base unit | Establish 4px base. Map all values. |
+| Tight, cramped components | Increase internal padding to at least `--space-3` vertical / `--space-4` horizontal. |
+| Excessive whitespace in dense UI | Tighten to `--space-2` / `--space-3` internal where appropriate. |
+
+### 16.4 Radius
+
+| If the codebase has… | Upgrade to… |
+|---|---|
+| Inconsistent radius across same component type | Normalize. Pick one radius per component tier. |
+| Very high radius (≥16px) on functional components | Reduce unless the aesthetic is explicitly approachable/friendly. |
+| 0px radius (sharp) on all components | Introduce `--radius-sm` (4px) minimum for softness, unless brutalist aesthetic is intentional. |
+
+### 16.5 Shadows
+
+| If the codebase has… | Upgrade to… |
+|---|---|
+| `box-shadow` with colored or glowing tints | Replace with neutral `rgba(0,0,0,x)` shadows. |
+| Same shadow value used at all elevation levels | Introduce 3-level shadow scale (sm / md / lg). |
+| Shadows on dark mode surfaces | Remove. Use background-color stepping for elevation instead. |
+
+### 16.6 General
+
+- **Consolidate duplication**: If the same component is implemented differently across files (different padding, different colors), unify under the token system.
+- **Remove magic numbers**: Any value that can't be explained by the token scale should be replaced or flagged.
+- **Don't redesign, refine**: Mode B is not a full redesign. The user's visual intent should be preserved. You are improving execution, not changing direction — unless the user explicitly asks.
+
+---
+
+## 17. Changelog
+
+> The agent appends an entry here after each run. Format: date, mode, summary of changes made.
+
+```
+[FILL_IN date] — Mode [A/B]
+  - FILL_IN (e.g. "Extracted tokens from globals.css and 14 component files")
+  - FILL_IN (e.g. "Resolved conflict: 3 accent colors consolidated to #3B82F6")
+  - FILL_IN (e.g. "Applied improved type scale across 8 components")
+```