design-stylecards

# Design Stylecards

Specs beat vibes. A stylecard is a named aesthetic recipe with **exact values** — the difference
between "add a nice shadow" (reinvented differently every session) and `elevation/md` (identical
every time, reviewed once, versioned forever).

```bash
/ork:design-stylecards list                      # Catalog index
/ork:design-stylecards elevation/md              # Show one recipe
/ork:design-stylecards apply glass/dark to src/components/Panel.tsx
```

## Why declarative recipes

Pipeline skills (`design-to-code`, `design-context-extract`) answer *how to produce* design output.
Stylecards answer *what good looks like* — as literal values an agent pastes, not adjectives it
interprets. Inspired by MengTo/Skills' stylecard micro-skills (MIT), consolidated into one catalog
to avoid manifest sprawl.

## Workflow

### 1. Resolve the request to a recipe

```python
Read("${CLAUDE_PLUGIN_ROOT}/skills/design-stylecards/references/stylecards.md")   # The catalog — always read before choosing
# Match the user's intent to ONE recipe by its Use-When line.
# No match → say so and offer the closest two; never freehand values.
```

### 2. Show or apply

- **Show**: print the recipe verbatim — values, Use-When, Avoid. No paraphrasing values.
- **Apply**: edit the target file using the recipe's exact values. Adapt only the syntax
  (Tailwind arbitrary class ↔ plain CSS ↔ CSS custom property), never the numbers.

### 3. Respect the recipe's Avoid block

Every recipe ends with falsifiable Avoid rules (e.g. "never stack two elevation recipes on one
element"). Violating an Avoid rule to satisfy a user request requires saying so explicitly.

## Catalog index

Full recipes with exact values: `references/stylecards.md`.

| Recipe | Use when |
|--------|----------|
| `elevation/sm` `md` `lg` | Layered neutral shadows — compact controls / cards / hero surfaces |
| `glass/dark` | Frosted glass panel on a dark backdrop |
| `border/gradient` | 1px gradient border without a wrapper hack |
| `background/mesh` | 2–3 hue radial mesh page background |
| `type/editorial` | Display + body + mono role split with tracking values |
| `motion/budget` | The four allowed durations + the one-signature-moment rule |

## Authoring a new stylecard

Add to `references/stylecards.md` following the contract — a recipe without all three parts is
not shippable:

1. **Use when** — one line, concrete surfaces ("cards, panels, popovers"), not adjectives.
2. **Values** — copy-paste-ready code. Numbers, not descriptions.
3. **Avoid** — falsifiable don'ts observed from real misuse.

Source recipes from shipped, reviewed UI (this repo's playground standard, production apps you've
extracted with `design-context-extract`) — never from imagination.

## Anti-Patterns

- **NEVER** freehand shadow/gradient/blur values when a recipe exists — that defeats the catalog
- **NEVER** paraphrase a recipe's values ("roughly 6% black") — paste them exactly
- **NEVER** mix two recipes of the same category (two elevations, two glass treatments) on one element

## Quality Bar

Done means all of these hold:
- The chosen recipe's Use-When line actually matches the user's surface (quote both if challenged)
- Applied values are byte-identical to the catalog entry — only syntax adapted, never numbers
- No Avoid rule of the applied recipe is violated in the final diff
- New recipes carry all three contract parts: Use-When, exact values, Avoid

## Related Skills

- `ork:design-context-extract` — mines new recipe candidates from real apps
- `ork:design-system-tokens` — where recipes graduate into project token architecture
- `ork:design-to-code` — pipeline that consumes stylecards during generation