85 lines
4.6 KiB
Markdown
85 lines
4.6 KiB
Markdown
|
# 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 a planned-but-not-yet-vendored
|
||
|
|
section and the corresponding file doesn't exist yet, shouldn't we warn
|
||
|
|
the user?" We chose forward-compatibility over fail-fast: a skill
|
||
|
|
authored today can list a planned slug and start benefiting the moment
|
||
|
|
the matching `craft/<slug>.md` is vendored 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.
|
||
|
|
|
||
|
|
Note for skill authors arriving from older guidance: an earlier draft
|
||
|
|
used `motion` as the future-slug placeholder. The shipped equivalent
|
||
|
|
today is `animation-discipline`. Use that one if your skill emits
|
||
|
|
motion.
|
||
|
|
|
||
|
|
### 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 in `anti-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) |
|
||
|
|
| `animation-discipline.md` | `animation-discipline` | Any skill that ships motion: mobile apps, multi-screen flows, gamified UI, transitions, microinteractions |
|
||
|
|
| `accessibility-baseline.md` | `accessibility-baseline` | Any skill that ships interactive UI: dashboards, forms, mobile flows, anything with focus/labels/keyboard paths |
|
||
|
|
| `rtl-and-bidi.md` | `rtl-and-bidi` | Any skill that ships localized text or layout: blogs, docs, financial tables, mobile apps, anything that may render Arabic / Hebrew / Persian |
|
||
|
|
| `form-validation.md` | `form-validation` | Any skill whose primary artifact contains an interactive form: lead capture, sign-in, signup, settings, multi-step intake |
|
||
|
|
|
||
|
|
**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 (`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.
|