first-commit

craft/README.md

@@ -0,0 +1,62 @@
+# Craft references
+
+Brand-agnostic craft knowledge. Each file is a small, dense rulebook on one
+dimension of professional UI craft (typography, color, motion, …). Skills
+opt into the references they need; the daemon injects only the requested
+ones into the system prompt above the active skill body.
+
+## Why a third axis next to `skills/` and `design-systems/`
+
+| Axis | Scope | Example |
+|---|---|---|
+| `skills/` | Artifact shape | `saas-landing`, `dashboard`, `pricing-page` |
+| `design-systems/` | Brand visual language (the 9-section `DESIGN.md`) | `linear-app`, `apple`, `notion` |
+| `craft/` | **Universal** craft knowledge — true regardless of brand | letter-spacing rules, 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 a skill opts in
+
+Add an `od.craft.requires` array to the skill's front-matter. Only the
+listed sections are injected, so a skill that needs only typography pays
+no token cost for color/motion content.
+
+```yaml
+od:
+  craft:
+    requires: [typography, color, anti-ai-slop]
+```
+
+Allowed values match the file names in this directory minus the `.md`
+extension. Unknown values are silently ignored (forward-compatible).
+
+### Why silent fallback instead of fail-fast?
+
+A skeptical reader will ask: "If a skill requests `motion` and we don't
+ship `motion.md` yet, shouldn't we warn the user?" We chose
+forward-compatibility over fail-fast: a skill authored today can list
+`motion` and start benefiting the moment we vendor `craft/motion.md` in
+a follow-up PR, with no skill edit needed. The cost of a missed
+reference is a missing paragraph in the system prompt, not a broken
+skill — so the loud failure mode is not worth the friction.
+
+## Files
+
+| File | Section name | When to require |
+|---|---|---|
+| `typography.md` | `typography` | Any skill that emits typed content (~all skills) |
+| `color.md` | `color` | Any skill that emits styled output (~all skills) |
+| `anti-ai-slop.md` | `anti-ai-slop` | Marketing pages, landing pages, decks |
+
+More sections (`motion`, `icons`, `craft-details`) will be added in
+follow-up PRs as we wire the linter side.
+
+## Attribution
+
+Craft content is adapted from the MIT-licensed
+[refero_skill](https://github.com/referodesign/refero_skill) project
+(© Refero Design), with edits to fit Open Design's house style and link
+back to OD's design tokens (`var(--accent)` etc.) instead of generic
+Tailwind hex values.

craft/anti-ai-slop.md

@@ -0,0 +1,84 @@
+# Anti-AI-slop rules
+
+Concrete, checkable rules that distinguish "designed by a human who has
+shipped product" from "default LLM output." Several rules below are
+auto-enforced by the daemon's `lint-artifact` linter — failing an
+enforced rule is not a style preference, it is a regression. The
+rest are guidance for agents and reviewers and are flagged inline as
+"(guidance, not auto-checked)" so the contract with the linter stays
+honest.
+
+> Adapted from [refero_skill](https://github.com/referodesign/refero_skill)
+> (MIT), tightened to match Open Design's lint surface.
+
+## The seven cardinal sins
+
+These are the patterns the linter blocks at P0 (must-fix):
+
+1. **Default Tailwind indigo as accent** — exactly `#6366f1`, `#4f46e5`,
+   `#4338ca`, `#3730a3`, `#8b5cf6`, `#7c3aed`, `#a855f7`. The active
+   `DESIGN.md` provides `--accent`; use it. Indigo is the textbook AI
+   tell. (The daemon's `lint-artifact` flags any of these as a solid
+   accent; keep this list in sync with `AI_DEFAULT_INDIGO` in
+   `apps/daemon/src/lint-artifact.ts`.)
+2. **Two-stop "trust" gradient on the hero** — purple→blue, blue→cyan,
+   indigo→pink. A flat surface + intentional type beats this every
+   time.
+3. **Emoji as feature icons** — `✨`, `🚀`, `🎯`, `⚡`, `🔥`, `💡`
+   inside `<h*>`, `<button>`, `<li>`, or `class*="icon"`. Use
+   1.6–1.8px-stroke monoline SVG with `currentColor`.
+4. **Sans-serif on display text when the seed binds a serif** — h1/h2
+   must use `var(--font-display)`, not a hardcoded Inter / Roboto /
+   `system-ui`.
+5. **Rounded card with a colored left-border accent** — the canonical
+   "AI dashboard tile" shape. Drop either the radius or the left
+   border.
+6. **Invented metrics** — "10× faster", "99.9% uptime", "3× more
+   productive". Either pull from a real source or use a labelled
+   placeholder.
+7. **Filler copy** — `lorem ipsum`, `feature one / two / three`,
+   `placeholder text`, `sample content`. An empty section is a design
+   problem to solve with composition, not by inventing words.
+
+## Soft tells (P1 — should fix)
+
+- **Standard "Hero → Features → Pricing → FAQ → CTA" sequence with no
+  variation** *(guidance, not auto-checked)*. This is the AI-template
+  skeleton; introduce at least one unconventional section (testimonial
+  wall as full-bleed quote, pricing as comparison-against-status-quo,
+  an inline mini-product-demo).
+- **External placeholder image CDNs** (`unsplash.com`, `placehold.co`,
+  `placekitten.com`, `picsum.photos`). Fragile and obvious. Use the
+  shipped `.ph-img` placeholder class.
+- **More than ~12 raw hex values outside `:root`.** Tokens were not
+  honoured.
+- **`var(--accent)` used 6+ times in the rendered body.** Cap at 2
+  visible uses per screen.
+
+## Polish tells (P2 — nice to fix)
+
+- **Sections without `data-od-id`** — comment mode can't target them.
+- **Decorative blob / wave SVG backgrounds** *(guidance, not
+  auto-checked)* — meaningless geometry.
+- **Perfect symmetric layout with no visual tension** *(guidance, not
+  auto-checked)* — alternating density (one tight section, one
+  breathing section) reads as intentional.
+
+## How to add soul without breaking the rules
+
+Aim for **~80% proven patterns + ~20% distinctive choice**. The 20%
+should live in:
+
+- One bold visual move — a typography choice, a single color decision,
+  an unexpected proportion.
+- Voice and microcopy — a button that says "Start tracking" beats one
+  that says "Get started".
+- One micro-interaction the user will remember — a button press that
+  moves 2px, a number that counts up.
+- One detail that could only have been put there by someone who used
+  the product (a subtle kbd shortcut hint, a status badge with
+  product-specific phrasing).
+
+If a reviewer screenshots the artifact and someone outside the project
+can identify which product it's from — you have soul. If not, you
+shipped a template.

craft/color.md

@@ -0,0 +1,88 @@
+# Color craft rules
+
+Universal color rules applied on top of the active `DESIGN.md`. The
+design system supplies the palette tokens; this file enforces how to
+*use* them.
+
+> Adapted from [refero_skill](https://github.com/referodesign/refero_skill)
+> (MIT). All examples reference Open Design's standard tokens
+> (`--bg`, `--surface`, `--fg`, `--muted`, `--border`, `--accent`).
+
+## Palette structure
+
+A coherent palette has four layers. Plan all four before writing any CSS.
+
+| Layer | Share of pixels | Tokens |
+|---|---|---|
+| **Neutrals** | 70–90% | `--bg`, `--surface`, `--fg`, `--muted`, `--border` |
+| **Accent** (one) | 5–10% | `--accent` only — never invent a second accent |
+| **Semantic** | 0–5% | `--success`, `--warn`, `--danger` |
+| **Effect** | <1% | gradients, glows; rarely justified |
+
+## Accent discipline
+
+The single biggest readability failure in AI-generated UIs is accent
+overuse. Hard caps:
+
+- **At most 2 visible uses of `--accent` per screen.** Typical pair:
+  one eyebrow / chip + one primary CTA. Or one accent card + one tab
+  pill. Pick a pair, not a flood.
+- Links count as accent; demote to `--fg` underline if you also have a
+  CTA on the same screen.
+- Hover/focus rings count as accent. Ration accordingly.
+
+## Contrast minimums
+
+Run these as gates, not goals:
+
+| Pair | Minimum |
+|---|---|
+| Body text (≤16 px) on background | **4.5:1** |
+| Large text (>18 px or 14 px bold) | **3:1** |
+| UI components against adjacent surfaces | **3:1** |
+
+When the brand color clashes (low-contrast indigo on light background is
+common), darken the accent to a `600`-level shade for text use; reserve
+the brand-bright variant for fills only.
+
+## Dark themes
+
+Avoid pure black and pure white — both cause vibration and eye strain.
+
+| Token | Dark theme | Light theme |
+|---|---|---|
+| Background | `#0f0f0f` (not `#000`) | `#fafafa` (not `#fff`) |
+| Foreground | `#f0f0f0` (not `#fff`) | `#111111` (not `#000`) |
+
+On dark surfaces, prefer **semi-transparent white borders** over solid
+dark borders — a 1px `rgba(255,255,255,0.08)` reads as structure
+without adding visual noise.
+
+## Semantic color naming
+
+Always name tokens by **purpose**, never by hue:
+
+```css
+/* good */
+--accent: #2f6feb;
+--success: #17a34a;
+
+/* bad — locks you out of theming */
+--blue-500: #2f6feb;
+--green-500: #17a34a;
+```
+
+## Anti-defaults
+
+- **Indigo `#6366f1`** (Tailwind `indigo-500`) is the most reliable
+  AI-slop tell. The active `DESIGN.md` provides `--accent`; use it. If
+  the brief truly needs indigo, make the user say so explicitly. If
+  your `DESIGN.md` encodes indigo as `--accent`, that is intentional —
+  the linter only flags hardcoded hex, so `var(--accent)` uses are
+  unaffected even when the resolved color happens to be `#6366f1`.
+- **Two-stop "trust" gradient** (purple → blue, blue → cyan, etc.) on a
+  hero is the second most reliable tell. A flat surface + one
+  type-driven hierarchy beats it every time.
+- **Decorative gradients with no functional purpose**. Gradients should
+  separate hierarchies (header → body, primary CTA → secondary), not
+  decorate empty space.

craft/typography.md

@@ -0,0 +1,88 @@
+# Typography craft rules
+
+Universal typography rules that apply on top of any `DESIGN.md`. The
+active design system decides *which* fonts; this file decides *how* they
+behave at every size.
+
+> Adapted from [refero_skill](https://github.com/referodesign/refero_skill)
+> (MIT) — distilled and re-tuned for Open Design's token system.
+
+## Type scale
+
+Use a multiplicative scale (1.2 or 1.25). Cap at 6–8 sizes per artifact.
+
+| Role | Range |
+|---|---|
+| Display | 48–72 px |
+| H1 | 32–48 px |
+| H2 | 24–32 px |
+| H3 | 20–24 px |
+| Body | 15–18 px |
+| Small | 13–14 px |
+| Caption | 11–12 px |
+
+## Line height (leading)
+
+| Text size | Line height |
+|---|---|
+| Display / H1 (≥32 px) | `1.0`–`1.2` (tight) |
+| Body (15–18 px) | `1.5`–`1.6` |
+| Small (≤14 px) | `1.5` |
+
+## Letter-spacing — the rule that makes or breaks craft
+
+This is the single most-skipped rule in AI-generated design. **No
+exceptions.**
+
+| Context | Letter-spacing |
+|---|---|
+| Body text (14–18 px) | `0` (default) |
+| Small text (11–13 px) | `0.01em` to `0.02em` (positive) |
+| UI labels and button text | `0.02em` |
+| **ALL CAPS** | **`0.06em` to `0.1em` (required)** |
+| Headings 32 px+ | `-0.01em` to `-0.02em` |
+| Display 48 px+ | `-0.02em` to `-0.03em` |
+
+ALL CAPS without positive tracking looks cramped and amateur. Display
+text without negative tracking looks loose and weak. These two failures
+are the most reliable AI-slop tells.
+
+The `0.06em` floor is not arbitrary: it is the empirical lower bound
+that print and web typographers have converged on for uppercase
+tracking (cf. Bringhurst's *Elements of Typographic Style* §3.2.7,
+which recommends 5–10% of the em for caps; modern screen practice
+rounds the lower end to 0.06em). Anything tighter and the counters
+collide on screen; the upper bound `0.1em` keeps the word from
+disintegrating into letters.
+
+## Font pairing
+
+- Maximum 2 typefaces per artifact (display + body, or one variable face
+  used at multiple weights).
+- Always declare a system fallback chain. If the active `DESIGN.md`
+  ships a webfont URL, the fallback must still produce a coherent look.
+- Never set `font-family: system-ui` alone on a heading — that is the
+  textbook AI default; always pair it with an intentional first choice.
+
+## Line length
+
+Limit body copy to **50–75 characters** per line. In CSS:
+`max-width: 65ch` is a safe default.
+
+## Three-weight system
+
+Most well-crafted UIs use exactly 3 weights:
+- **Read** (400 / 450) — body copy
+- **Emphasize** (510 / 550) — UI text, labels, navigation
+- **Announce** (590 / 600) — headlines, buttons
+
+Weight 700+ is rarely needed. If your design uses bold for "emphasis on
+emphasis," it likely lacks weight discipline elsewhere.
+
+## Common mistakes (lint these)
+
+- ALL CAPS without `letter-spacing` ≥ `0.06em`.
+- Display text (≥32 px) without negative tracking.
+- More than 3 type sizes visible above the fold.
+- Mixed serif and slab on the same screen without a clear role split.
+- Body copy in `text-align: justify` (creates rivers; never use on the web).