# Craft references

Brand-agnostic craft knowledge. Each file is a small, dense rulebook on one
dimension of professional UI craft (typography, color, motion, …). These
rules apply on top of whichever `DESIGN.md` / design system is active and
are true regardless of brand.

## Three-axis taxonomy

| Axis | Scope | Example |
|---|---|---|
| `skills/` (planned) | Artifact shape | `pitch-deck`, `mobile-screens`, `dashboard` |
| `design-systems/` | Brand visual language | `apple`, `linear`, `editorial-monocle` |
| `craft/` (this dir) | **Universal** craft knowledge — true regardless of brand | ALL CAPS tracking ≥0.06em, accent-overuse caps, anti-AI-slop |

`DESIGN.md` tells the agent which colors and fonts a brand uses. `craft/`
tells the agent the universal rules a competent designer applies on top —
e.g. ALL CAPS always needs ≥0.06em tracking, regardless of the brand.

## How the agent uses this directory

In alpha.5 the agent reads craft files directly and surfaces them in the
critique prompt. When the skill system lands, each `SKILL.md` will opt
into only the files it needs via front-matter:

```yaml
cd:
  craft:
    requires: [typography, color, anti-ai-slop]
```

Only listed sections will be injected into the system prompt, so a skill
that needs only typography pays no token cost for color/motion content.

## CSS vocabulary ↔ Figma vocabulary

The rule files were authored against web output. Because the rules are
about visual intent, they apply identically in Figma with a simple mapping:

| Rule language | Figma equivalent |
|---|---|
| `var(--accent)`, `var(--fg)`, `var(--bg)`, `--surface`, `--border` | Figma **color variables** bound to the corresponding DS role |
| `var(--font-display)`, `var(--font-body)` | Figma **text styles** named `display` / `body` etc., or font variables |
| `letter-spacing: 0.06em` | Figma text **letter-spacing = 6%** |
| `line-height: 1.5` | Figma text **line-height = 150%** |
| `<h1>`, `<h2>`, `<button>`, `<li>` | Figma text layers using the matching text style (`h1`, `h2`, `button`, list-item body) |
| `rgba(255,255,255,0.08)` border | Figma 1px stroke, white fill with 8% opacity |
| `text-align: justify` | Figma paragraph alignment = justify |
| `data-od-id` | Figma node name prefix or plugin data (node metadata used by the comment/refinement loop) |
| `class*="icon"` | Figma frame/component named `icon-*` or tagged as an icon |
| `:root` custom properties | Figma root variable collection (design tokens) |

## Enforcement levels

Craft files mix auto-checked rules and guidance.

- **Auto-checked.** Rules wired into `tools/craftLint.ts` (planned for P0
  deterministic lint): the P0 list in `anti-ai-slop.md` (Tailwind-indigo
  accent, two-stop hero gradients, emoji-as-icons, invented metrics,
  filler copy).
- **Guidance.** The rest. The agent reads the rules, reviewers apply them,
  the linter doesn't check them.

A purely behavioral craft file (state-coverage, animation-discipline) is
guidance unless a specific rule is later promoted into the lint tool.

## Files

| File | Section name | When to require |
|---|---|---|
| `typography.md` | `typography` | Any artifact that emits typed content (~all skills) |
| `typography-hierarchy.md` | `typography-hierarchy` | Artifacts where hierarchy must feel authored, not assembled |
| `typography-hierarchy-editorial.md` | `typography-hierarchy-editorial` | Sustained reading surfaces: blog post, docs page, long-form deck |
| `color.md` | `color` | Any styled artifact (~all skills) |
| `anti-ai-slop.md` | `anti-ai-slop` | Marketing pages, landing pages, decks |
| `state-coverage.md` | `state-coverage` | Stateful UI: dashboards, mobile apps, forms, lists/tables |
| `animation-discipline.md` | `animation-discipline` | Any artifact that ships motion |
| `accessibility-baseline.md` | `accessibility-baseline` | Interactive UI: dashboards, forms, mobile flows |
| `rtl-and-bidi.md` | `rtl-and-bidi` | Localized text or layout (Arabic / Hebrew / Persian) |
| `form-validation.md` | `form-validation` | Artifacts with an interactive form |
| `laws-of-ux.md` | `laws-of-ux` | Composition decisions that hit named cognitive limits |

## Attribution

Craft content is adapted from:

1. [refero_skill](https://github.com/referodesign/refero_skill) — © Refero
   Design, MIT license. Original source of the rule sets.
2. [nexu-io/open-design](https://github.com/nexu-io/open-design) —
   Apache-2.0. open-design curated and tuned the refero content for their
   agent's house style and lint surface.

CodeDesign vendors the open-design versions as a starting point and adapts
the vocabulary to Figma. See repo-root `NOTICE` for the full attribution
chain.
