SurfaceThemeScaffoldGen

Scaffold a Clef Surface design system theme $ARGUMENTS with oklch palette, typography scale, spacing tokens, motion definitions, elevation shadows, and radius tokens in .theme format.

When to use: Use when creating a new Clef Surface design system theme. Generates a .theme spec file with @version annotation, palette (oklch color scales), typography (modular ratio, fonts, weights, line-heights, tracking), spacing (base multiplier), motion (durations, easing, reduced-motion), elevation (shadow layers), radius tokens, and extends support for theme variants. Follows WCAG accessibility guidelines for contrast.

Design Principles

• Token-Based Design: Every visual value is a named design token — no hardcoded colors, sizes, or shadows anywhere in component code.
• WCAG Compliance: Every color pair must meet WCAG 2.1 AA contrast (4.5:1 normal text, 3:1 large text). The generator validates at generation time.
• Reduced Motion Respect: All motion durations collapse to 0ms when prefers-reduced-motion is active. This is built into the motion token system, not opt-in.
• Theme Layering: Themes are layered: base + variants. Multiple variants can be active simultaneously, resolved by priority then activation order.

Step-by-Step Process

Step 1: Register Generator

Self-register with PluginRegistry so KindSystem can track ThemeConfig → SurfaceTheme transformations. Registration is also handled automatically by register-generator-kinds.sync.

Examples: Register the theme scaffold generator

const result = await surfaceThemeScaffoldGenHandler.register({}, storage);

Step 2: Preview Changes

Dry-run the generation using Emitter content-addressing to classify each output file as new, changed, or unchanged. No files are written.

Arguments: $0 name (string), $1 primaryColor (string), $2 fontFamily (string), $3 baseSize (int), $4 scale (float?), $5 secondaryColor (string?), $6 borderRadius (string?), $7 mode (string), $8 extends (string?)

Step 3: Generate Clef Surface Theme

Generate a complete Clef Surface theme scaffold ( . theme file ) with purpose , palette ( oklch colors ) , typography ( fonts , scale , weights , line heights , tracking ) , spacing ( base multiplier ) , motion ( durations , easing , reduced motion ) , elevation ( shadow layers ) , and radius tokens . Supports extends for theme variants .

Arguments: $0 name (string), $1 primaryColor (string), $2 fontFamily (string), $3 baseSize (int), $4 scale (float?), $5 secondaryColor (string?), $6 borderRadius (string?), $7 mode (string), $8 extends (string?)

Checklist:

• Theme name is kebab-case?
• Primary color generates full 50-950 scale?
• Palette has semantic roles (primary, secondary, error, etc.)?
• WCAG contrast ratios meet AA standard (4.5:1 normal, 3:1 large)?
• Typography uses modular ratio scale?
• Motion respects prefers-reduced-motion?
• Elevation scale covers 0-5 levels?
• Light and dark themes are generated (if mode=both)?
• Palette uses oklch() for perceptual uniformity?
• Spacing follows a consistent base multiplier?
• Radius tokens defined?
• All files written through Emitter (not directly to disk)?
• Source provenance attached to each file?
• Generation step recorded in GenerationPlan?

Examples: Generate a theme with defaults

clef scaffold theme --name ocean

Generate a custom theme

clef scaffold theme --name brand --primary '#3b82f6' --font 'Inter, sans-serif' --base-size 18

Generate light-only theme

clef scaffold theme --name print --mode light

Step 4: Edit the Theme Specification

Open the generated .theme file and refine each section: 1. Write a purpose block describing the theme's design intent. 2. Define palette colors using oklch() for perceptual uniformity. 3. Set typography scale with font families, sizes (modular ratio), weights, line-heights, and tracking. 4. Configure spacing tokens with a consistent base multiplier. 5. Define motion durations and easing curves (respect prefers-reduced-motion). 6. Set elevation shadow scale (0-5 levels). 7. Define radius tokens for border rounding. 8. Verify all text/background pairs meet WCAG AA contrast (4.5:1). 9. If extending a base theme, only override changed tokens.

References

• Clef Surface design system and theme architecture
• Theme specification grammar

Supporting Materials

• Clef Surface theme scaffolding walkthrough

Quick Reference

Input	Type	Purpose
name	String	Theme name (kebab-case)
primaryColor	String	Primary color hue or hex value
secondaryColor	String	Secondary color hue or hex
fontFamily	String	Primary font stack
baseSize	Int	Base font size in pixels (default: 16)
scale	Float	Modular ratio (default: 1.25 major third)
borderRadius	String	Default border radius
mode	String	light, dark, or both (default: both)

Output Files:

File	Purpose
suite.yaml	Theme suite manifest
themes/{name}-light.json	Light theme tokens
themes/{name}-dark.json	Dark theme tokens
tokens/palette.json	Color scale configuration
tokens/typography.json	Type scale and font stacks
tokens/motion.json	Animation timing and easing
tokens/elevation.json	Shadow scale

Anti-Patterns

Hardcoded colors in components

Component uses raw hex values instead of design tokens.

Bad:

.button { background: #3b82f6; color: #ffffff; }

Good:

.button {
  background: var(--color-primary);
  color: var(--color-on-primary);
}

Ignoring reduced motion

Animations play regardless of prefers-reduced-motion setting.

Bad:

.dialog { transition: transform 300ms ease; }

Good:

.dialog {
  transition: transform var(--motion-duration-slow) var(--motion-ease-default);
}
@media (prefers-reduced-motion: reduce) {
  .dialog { transition-duration: 0ms; }
}

Validation

Generate a Clef Surface theme scaffold:

npx tsx cli/src/index.ts scaffold theme --name ocean --primary 220 --font 'Inter, sans-serif'

Run scaffold generator tests:

npx vitest run tests/scaffold-generators.test.ts

Related Skills

Skill	When to Use
/create-widget	Generate components to use the theme tokens
/create-suite	Generate suite manifests for theme packages