create-theme

Create a Clef Surface Theme

Design and implement a new theme specification named $ARGUMENTS for the Clef Surface system.

When to Use This Skill

Use this skill when you need to:

• Define a new visual theme for a Clef Surface application
• Create a dark mode, high-contrast, or brand-specific variant
• Extend an existing base theme with overrides
• Establish design tokens (colors, type, spacing, motion) in a declarative spec
• Capture an expressive aesthetic (material, mood, density, motif, iconography) through the advanced axes that were previously sidecar .theme.json files

Important — the .theme DSL is the single source of truth. The legacy .theme.json sidecar format has been retired. All advanced sections (material, mood, density, motif, iconography, colorScheme, colorSpace, fontMetrics, typeScale, shape, scope, springPhysics, motionChoreography, imageFilter, preference, constraint, tokens) now live inside the same .theme file as palette/typography/spacing/motion/elevation/radius. Do not produce .theme.json output. See references/advanced-sections.md.

Do NOT use this skill for:

• Component styling (use Surface component specs instead)
• Layout definitions (use Surface layout specs)
• One-off CSS overrides (themes are systematic, not ad-hoc)

Core Design Principles

1. Perceptual Uniformity -- Use oklch for all color tokens. oklch guarantees that equal lightness values look equally light to human eyes, unlike hsl or hex.
2. Accessibility First -- Every foreground/background pair must meet WCAG AA contrast (4.5:1 for normal text, 3:1 for large text). Aim for AAA (7:1) when possible.
3. Systematic Scales -- Spacing, typography, and radius use deliberate scales, not arbitrary values. Prefer a base unit with multipliers.
4. Token Semantics -- Name tokens by role (e.g., on-primary, surface-variant) not by appearance (e.g., blue-500, light-gray). Semantic names survive theme switching.
5. Minimal Overrides -- When extending a base theme, override only what changes. Inherited sections need no redeclaration.

Step-by-Step Design Process

Step 1: Define the Theme Identity

Decide:

• Name: A short, lowercase, hyphenated identifier (e.g., light, dark, ocean-dark, brand-vivid)
• Purpose: A prose description of what this theme is for and when it should be used
• Base theme: If this theme extends another, identify which one. Most themes extend light or dark.

Step 2: Design the Palette

Read references/color-systems.md for oklch guidance and WCAG contrast requirements.

Design the palette in layers:

1. Brand colors -- primary, secondary, tertiary with hover/active/container variants
2. Surface colors -- background, surface, surface-dim, surface-bright, surface-variant
3. On-colors -- foreground colors for each surface (on-primary, on-surface, etc.)
4. Outline colors -- outline, outline-variant, outline-focus
5. Status colors -- error, warning, success, info with container and on-variants
6. Utility colors -- shadow, scrim, overlay-backdrop
7. Interactive state layers -- hover, press, focus, drag, disabled (with alpha)

Palette checklist:

• All colors use oklch (preferred) or hsl/hex (acceptable fallback)
• Every foreground/background pair meets WCAG AA (4.5:1 minimum)
• Brand colors have hover, active, and container variants
• Status colors have container and on-container variants
• Interactive state layers use alpha transparency
• Disabled states use reduced alpha (0.38 for content, 0.12 for containers)

Step 3: Design the Typography Scale

Use a modular scale for consistent size progression. Common ratios:

Define these token categories:

1. Font families -- sans, mono, serif with full fallback stacks
2. Display styles -- display-lg, display-md, display-sm (hero text)
3. Heading styles -- heading-lg, heading-md, heading-sm
4. Body styles -- body-lg, body-md, body-sm
5. Label styles -- label-lg, label-md, label-sm (UI chrome)
6. Utility styles -- caption, overline, code, code-sm

Each compound style is a nested block: { size, lineHeight, weight, tracking, family }.

Typography checklist:

• Minimum body text size is 1rem (16px)
• Line heights are between 1.2 (headings) and 1.6 (body)
• Tracking (letter-spacing) is negative for large sizes, positive for small
• Font families include system fallbacks
• Weights are standard values (400, 500, 600, 700, 800)

Step 4: Design the Spacing Scale

Choose a base unit (typically 4px) and build a scale from multiples:

base: 4px
xs:   4px    (1x)
sm:   8px    (2x)
md:   16px   (4x)
lg:   24px   (6x)
xl:   32px   (8x)
2xl:  48px   (12x)
3xl:  64px   (16x)

Add semantic aliases for common use cases (gutter, section, page-inline, stack-sm, etc.).

Step 5: Design the Motion Tokens

Define durations, easings, and compound transitions:

Duration scale:

• instant: 50-100ms (micro-interactions)
• fast: 100-200ms (hover, focus)
• normal: 200-300ms (general transitions)
• slow: 300-500ms (complex animations)
• slower: 500-700ms (page transitions)

Easing curves:

• default: Standard deceleration curve
• emphasize: Dramatic entry
• decelerate: Slow to stop (entering elements)
• accelerate: Quick start (exiting elements)
• spring: Overshoot bounce
• linear: Constant rate

Compound transitions combine duration + easing + property:

transition-fade: { duration: duration-fast, easing: easing-default, property: opacity }

Always include reduce-motion: prefers-reduced-motion to respect user preferences.

Step 6: Design Elevation and Radius

Elevation uses 5 levels (level-0 through level-5) with increasing shadow blur and offset. Add semantic aliases (elevation-card, elevation-dialog, etc.).

Radius uses a scale from none to full (9999px for pill shapes). Add semantic aliases (radius-button, radius-card, etc.).

Step 7: Design the Advanced Expressive Axes

The seven foundation sections (palette through radius) define what tokens exist. The advanced sections define how the theme feels and adapts. For curated themes (OS imitations, beautiful web-app references, CSS Zen Garden classics), use ALL of these — that's where most of the aesthetic character lives. See references/advanced-sections.md for the full menu.

Skipping any of these for a curated theme is leaving expressive surface area on the floor. For a minimal brand variant on top of light, you can omit the optional ones — but you should still set mood, material, density, motif, iconography, colorScheme, and constraint.

Step 8: Write the .theme File

Place the file at: repertoire/themes/<name>.theme

See references/theme-grammar.md for the complete grammar and references/advanced-sections.md for the full menu of advanced section keys and value shapes.

Section order is always:

1. @version(1) annotation
2. File-level comment describing the theme
3. theme <name> [extends <base>] { ... }
4. purpose { ... } (optional prose block)
5. palette { ... }
6. typography { ... }
7. spacing { ... }
8. motion { ... }
9. elevation { ... }
10. radius { ... }
11. colorSpace { ... }
12. colorScheme { ... }
13. density { ... }
14. motif { ... }
15. iconography { ... }
16. material { ... }
17. mood { ... }
18. fontMetrics { ... }
19. typeScale { ... }
20. shape { ... }
21. scope { ... } (optional)
22. springPhysics { ... } (optional)
23. motionChoreography { ... } (optional)
24. imageFilter { ... } (optional)
25. preference { ... }
26. constraint { ... }
27. tokens { ... } (optional escape hatch)

Step 9: Validate by Parsing

Run the parser to verify the theme is syntactically valid AND that every advanced section parsed (an empty advanced section in the manifest output means a typo or a missing keyword):

npx tsx --tsconfig tsconfig.json scripts/_theme-parse-check.ts repertoire/themes/<name>.theme

The che

Content truncated.