---
name: surface-theme-scaffold-gen
description: Generate Clef Surface design system theme scaffolds including palette ( oklch color scales ) , typography ( modular ratio ) , spacing tokens , motion definitions ( with reduced motion ) , elevation scale , radius tokens , and light dark theme manifests . Supports theme extension via extends . Follows WCAG accessibility guidelines for contrast ratios
argument-hint: --name <theme-name>
allowed-tools: Read, Write, Bash
---

<!-- Auto-generated by Clef Clef Bind — claude-skills target -->
<!-- Concept: SurfaceThemeScaffoldGen -->
<!-- Do not edit manually; regenerate with: clef interface generate -->

# 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*
```typescript
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*
```bash
clef scaffold theme --name ocean
```
*Generate a custom theme*
```bash
clef scaffold theme --name brand --primary '#3b82f6' --font 'Inter, sans-serif' --base-size 18
```
*Generate light-only theme*
```bash
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](references/surface-theme-guide.md)
- [Theme specification grammar](references/theme-grammar.md)
## Supporting Materials

- [Clef Surface theme scaffolding walkthrough](examples/scaffold-surface-theme.md)
## 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:*
```bash
npx tsx cli/src/index.ts scaffold theme --name ocean --primary 220 --font 'Inter, sans-serif'
```
*Run scaffold generator tests:*
```bash
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 |