surface-theme-scaffold-gen

name	surface-theme-scaffold-gen
description	Generate Clef Surface design system theme scaffolds including palette configuration , typography scale , motion definitions , elevation scale , and light dark theme manifests Follows WCAG accessibility guidelines for contrast ratios
argument-hint	--name <theme-name>
allowed-tools	Read, Write, Bash

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 name (string), $1 primaryColor (string), $2 fontFamily (string), $3 baseSize (int), $4 mode (string)

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 name (string), $1 primaryColor (string), $2 fontFamily (string), $3 baseSize (int), $4 mode (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)?
• 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

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
/surface-component-scaffold	Generate components to use the theme tokens
/suite-scaffold	Generate suite manifests for theme packages