Design Spec

Design Spec Management

Create and manage design-spec.css — the single source of CSS custom properties for a design project. Design specs are generated from palette YAML + medium-specific defaults.

Priority: Resource Library First

Before generating from scratch, check the resource library for matching schemes:

cat $WORKDIR/design-works/.cache/assets/INDEX.md

Matching logic:

1. Exact match (industry + scene + medium) → copy design-spec.css directly, present for confirmation
2. Near match → propose with adjustments noted, confirm before applying
3. No match → generate from scratch with palette YAML

Medium Differentiation

design-spec.css must be scoped to the correct medium. Properties vary:

design-spec.css Output Format

/* === Design Tokens for {Project Name} === */
/* Medium: {web|app|poster} */
/* Colors: from palette YAML (auto-generated) */

:root {
  /* Color System */
  --color-primary: #4F46E5;
  --color-primary-hover: #4338CA;
  --color-primary-light: #E0E7FF;
  --color-secondary: #0EA5E9;
  --color-secondary-hover: #0284C7;
  --color-secondary-light: #E0F2FE;
  --color-accent: #F59E0B;
  --color-accent-hover: #D97706;
  --color-accent-light: #FEF3C7;
  --color-surface: #FFFFFF;
  --color-surface-alt: #F9FAFB;
  --color-surface-hover: #F3F4F6;
  --color-text-primary: #111827;
  --color-text-secondary: #6B7280;
  --color-text-disabled: #D1D5DB;
  --color-text-inverse: #FFFFFF;
  --color-border: #E5E7EB;
  --color-border-focus: #4F46E5;
  --color-success: #10B981;
  --color-warning: #F59E0B;
  --color-error: #EF4444;
  --color-info: #3B82F6;

  /* Typography */
  --font-sans: 'Inter', 'Noto Sans SC', -apple-system, sans-serif;
  --font-serif: 'Playfair Display', 'Noto Serif SC', Georgia, serif;
  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
  --font-hand: 'LXGW WenKai', cursive;
  --font-icon: 'Material Symbols Rounded';
  --font-body: var(--font-sans);
  --font-heading: var(--font-sans);

  --text-base: 16px;
  --text-sm: 0.875rem;
  --text-lg: 1.125rem;
  --text-xl: 1.25rem;
  --text-2xl: 1.5rem;
  --text-3xl: 1.875rem;

  /* Spacing (4px grid) */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 20px;
  --space-6: 24px;
  --space-8: 32px;
  --space-10: 40px;
  --space-12: 48px;

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

  /* Shadows */
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07);
  --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);

  /* Layout */
  --page-width: 1200px;
  --page-width-narrow: 800px;
  --sidebar-width: 240px;
  --header-height: 56px;
}

/* Dark mode overrides — only when mode is "dark" */
[data-theme="dark"] {
  --color-surface: #1F2937;
  --color-surface-alt: #111827;
  --color-text-primary: #F9FAFB;
  --color-text-secondary: #9CA3AF;
}

Generating from Palette YAML

# Read palette, generate color section of design-spec.css
python3 -c "
import yaml, sys
with open('.library/palettes/2024/saas-blue.yml') as f:
    pal = yaml.safe_load(f)['palette']
colors = pal['colors']
dark = pal.get('dark_mode', {})

for role in ['primary', 'secondary', 'accent']:
    if role in colors and colors[role]:
        for k, v in colors[role].items():
            suffix = '' if k == 'base' else f'-{k}'
            print(f'  --color-{role}{suffix}: {v};')

for role in ['surface', 'text', 'border']:
    if role in colors and colors[role]:
        for k, v in colors[role].items():
            if k == 'base':
                print(f'  --color-{role}: {v};')
            else:
                print(f'  --color-{role}-{k}: {v};')

if 'semantic' in colors and colors['semantic']:
    for k, v in colors['semantic'].items():
        print(f'  --color-{k}: {v};')
"

Extracting from Reference

When user provides a reference URL:

1. web_fetch the page
2. Extract: colors, fonts, spacing, border-radius, layout patterns
3. Infer medium type (web/app/poster)
4. Generate design-spec.css with /* Source: {url} */ comment
5. Ask user: "Save this scheme to the resource library?"

Searching Design Trends

tai tool web_search '{"query": "2026 web design trends UI patterns typography"}'

Synthesize results, recommend, confirm, apply. Optionally save as new scheme to .library/designs/{year}/.

Auto-Learning from Completed Projects

When user confirms satisfaction ("looks good", "I like it", "ship it"):

1. Propose: "Save this as a reusable design scheme?"
2. If yes, extract from design-spec.css + HTML analysis:
   • Colors, fonts, spacing, layout patterns
   • Infer: industry, scenes, medium, style tags
3. Show extracted manifest for confirmation
4. Save to .library/designs/{year}/{scheme-name}/

Workflow Summary

User Request
  ├─ "Create design spec" → Check resource library → Match?
  │     ├─ Exact → Copy scheme → Show → Confirm
  │     ├─ Near  → Recommend → Confirm → Tweak
  │     └─ None  → Generate from palette YAML (by medium)
  ├─ "Reference this page" → Extract → Show → Confirm → Update
  │     └─ Ask: "Save to library?"
  ├─ "Search trends" → web_search → Summarize → Recommend → Apply
  ├─ "Change brand color" → Update palette YAML → Regenerate design-spec.css colors
  └─ Project done + user happy → Auto-learn → Abstract → Save to .library/

Rules

• ALWAYS check the resource library before generating from scratch
• Medium type must be annotated in the CSS header comment
• web/app/poster use different default values — never mix them
• Colors section is auto-generated from palette YAML (never hand-edit)
• When updating existing design-spec.css, preserve user-edited values (diff before overwrite)
• Extracted schemes: source: "extracted", curated: source: "curated", trends: source: "trending"
• Auto-learning cap: 20 extracted schemes per year, evict oldest on overflow
• Always ask before saving extracted schemes to the resource library