SurfaceThemeScaffoldGen

Scaffold a Clef Surface design system theme $ARGUMENTS with palette tokens, typography scale, motion transitions, and elevation shadows.

When to use: Use when creating a new Clef Surface design system theme. Generates palette configuration, typography scale, motion definitions, elevation scale, and light/dark theme manifests with WCAG accessibility compliance.

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 → CoifTheme 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

$1

$2

$3

$4

Step 3: Generate Clef Surface Theme

Generate a complete Clef Surface theme scaffold with palette tokens , typography scale , motion transitions , elevation shadows , and light dark theme JSON files

Arguments:

$0

$1

$2

$3

$4

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)?
• 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

References

• Clef Surface design system and theme architecture

Supporting Materials

• Clef Surface theme scaffolding walkthrough

Quick Reference

Output Files:

suite.yaml

themes/{name}-light.json

themes/{name}-dark.json

tokens/palette.json

tokens/typography.json

tokens/motion.json

tokens/elevation.json

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

/surface-component-scaffold

/suite-scaffold