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

<!-- 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 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*
```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` **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*
```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
```

## References

- [Clef Surface design system and theme architecture](references/surface-theme-guide.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 |
| --- | --- |
| `/surface-component-scaffold` | Generate components to use the theme tokens |
| `/suite-scaffold` | Generate suite manifests for theme packages |