ab58b62b17
* feat(craft): add state-coverage rules + opt-ins on dashboard, mobile-app, kanban-board
State coverage is the most reliable AI-design failure: agents ship only the
populated state. This adds craft/state-coverage.md (108 lines, matches the
existing craft format) covering the five required states (loading, empty,
error, populated, edge), three form-specific states, ARIA/focus rules, and
loading-duration thresholds.
Sources are public: WCAG 2.2, NN/g, Material Design 3, Apple HIG, Baymard.
Three skills with stateful UI opt in via od.craft.requires:
- dashboard
- mobile-app
- kanban-board
Decks, ppt, image-poster and other static-output skills do not opt in.
Refs: see issue body for the broader proposal (state-coverage is module 1
of 5 behavioral craft modules).
* fix(craft): address review findings on state-coverage
Four P2 findings from #502 review addressed in one pass.
- Edge state Test matrix added under the five-states table (dashboard,
mobile, form, search, detail-view scenarios with concrete thresholds).
- Server-driven empty pattern added as trailing note in the empty-state
composition section.
- Retry discipline subsection added after error severity tiers
(immediate first retry, exponential 2s/4s/8s backoff, 3-retry floor,
Last-attempted timestamp).
- README enforcement-levels subsection added distinguishing auto-checked
P0 rules from guidance; partial-stateful skill clarification added
after the Files table.
No rewrites. ~30 lines added. File stays inside the 80-110-line craft
target.
* fix(craft): correct lint enforcement claim + remove duplicate threshold message
Two findings from @mrcfps review (Looper-generated against
|
||
|---|---|---|
| .. | ||
| anti-ai-slop.md | ||
| color.md | ||
| README.md | ||
| state-coverage.md | ||
| typography.md | ||
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.
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.
Enforcement levels
Craft files mix auto-checked rules and guidance.
- Auto-checked. Rules wired into
apps/daemon/src/lint-artifact.ts— currently the P0 list inanti-ai-slop.md(Tailwind-indigo accent, two-stop hero gradients, emoji-as-icons, etc.). The linter reports these as findings back to the UI (for P0/P1 badges) and to the agent (as a system reminder for self-correction). Artifact persistence is not currently hard-blocked on P0 hits. - 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 lint-artifact.ts.
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 |
state-coverage.md |
state-coverage |
Any skill with stateful UI (dashboards, mobile apps, forms, list/table views) |
Partial-stateful skills. A skill that's mostly static but contains an embedded form, data table, or query surface should opt in. State-coverage rules apply to the stateful component, not the whole page.
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 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.