| name | design-spec |
| trigger | When creating design-spec.css, setting brand colors, extracting design tokens from a reference, searching design trends, or generating CSS custom properties |
| description | Manage design-spec.css — match resource library, handle medium differentiation (web/app/poster), auto-learn from completed projects |
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:
- Exact match (industry + scene + medium) → copy
design-spec.css directly, present for confirmation
- Near match → propose with adjustments noted, confirm before applying
- No match → generate from scratch with palette YAML
Medium Differentiation
design-spec.css must be scoped to the correct medium. Properties vary:
| Property | Web | App | Poster |
|---|
| Default width | 1200-1440px | 375px | 800px |
| Base font size | 16px | 16px (touch-friendly) | dynamic (vw units) |
| Min font size | 12px | 14px (legibility) | no limit |
| Spacing grid | 4px base | 8px base | free |
| Color contrast | WCAG AA required | WCAG AA required | not enforced |
| Interaction states | hover + focus + active | active only (no hover) | none |
| Border radius | 4-8px | 12-16px | free |
| Font preference | Inter / Roboto | Roboto / system fonts | Playfair / display fonts |
design-spec.css Output Format
:root {
--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;
--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;
--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;
--radius-sm: 4px;
--radius-md: 8px;
--radius-lg: 12px;
--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);
--page-width: 1200px;
--page-width-narrow: 800px;
--sidebar-width: 240px;
--header-height: 56px;
}
[data-theme="dark"] {
--color-surface: #1F2937;
--color-surface-alt: #111827;
--color-text-primary: #F9FAFB;
--color-text-secondary: #9CA3AF;
}
Generating from Palette YAML
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:
web_fetch the page- Extract: colors, fonts, spacing, border-radius, layout patterns
- Infer medium type (web/app/poster)
- Generate design-spec.css with
/* Source: {url} */ comment
- 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"):
- Propose: "Save this as a reusable design scheme?"
- If yes, extract from design-spec.css + HTML analysis:
- Colors, fonts, spacing, layout patterns
- Infer: industry, scenes, medium, style tags
- Show extracted manifest for confirmation
- 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
