Design craft, the shipped default

Every produced skill ships one file that did not come from your design system. references/design-craft.md is generic composition guidance, copied byte-for-byte from the meta-skill. This lesson explains why it exists, what it covers, and why it is the only file in the produced skill that does not follow the cite-or-[VERIFY] contract.

Why design craft ships at all

A DS skill tells the agent how to use a specific design system's tokens, components, and wiring. It does not tell the agent how to lay out a page, where the hierarchy lives, how dense to make the content, or how much motion is too much. Most design systems do not document those things, and the ones that do mix them into prose foundation pages where the rules are hard to extract cleanly.

Without a default, an agent composing a screen would invent the missing rules every time. The result is the typical "AI-generated UI" look: hero followed by three feature cards followed by CTA, purple-to-cyan gradients, identical icon tiles, headlines that wrap down a narrow column.

design-craft.md is the floor. It is the set of composition defaults the agent applies wherever the DS is silent.

Why it is byte-for-byte, not extracted

The skill solves this by copying the file rather than generating it. scripts/scaffold.sh runs cp from the meta-skill's assets/design-craft.md into the produced skill's references/design-craft.md. No model output sits between the source and the destination.

Three consequences follow:

• The cite-or-[VERIFY] contract does not apply. There is nothing to cite. Every other rule in the produced skill points at a file:line in the DS source. The design-craft file does not, and the audit does not require it to.
• The file never gets edited per DS. Adapting it to feel more "Acme-ish" would either silently soften a default that the DS does not actually override, or hard-code a rule that conflicts with one the DS makes elsewhere. The byte-diff check catches this.
• The file gets replaced wholesale on re-extract. Any local edit to the produced design-craft.md is lost the next time the skill is extracted. Improvements belong upstream in the meta-skill's asset, not in the produced copy.

The precedence rule

The file's own header states the rule:

Precedence (read first). These are defaults for where the design
system is silent. The design system is canonical: wherever a DS
token, font, scale, component, or documented rule contradicts a
line below, follow the design system and drop the conflicting line
without comment.

This is what makes a static file safe across wildly different design systems. A craft rule that contradicts a DS rule loses, every time, with no negotiation. The DS skill's other reference files (tokens, components, foundations) carry the source of truth. design-craft.md fills silence.

The rule grammar

Every line in the file uses one of three keywords:

The rules fire at composition time: screens, pages, sections. They do not fire on token lookups or single-component API questions. An agent answering "what is the medium button size in Acme UI?" never reads design-craft.md. An agent building a pricing page does.

What the file covers

Eight categories, each a short list of MUST / SHOULD / NEVER bullets.

Layout and structure

Bans the hero-then-three-feature-cards-then-CTA default. Requires a deliberate macrostructure (stat-led, long-document, bento, split, workbench, editorial). Bans nesting cards inside cards and identical icon-tile grids. Prefers three to five intentional items over eight filler ones.

Hierarchy and density

Requires three prominence levels (lead, support, detail) resolvable within two seconds. One primary action per screen. All four data states designed (loading, empty, error, populated). Density matches the job; one density everywhere is a default, not a decision.

Typography

Every size from the DS type scale. Display headings capped at two or three lines. When the DS does not mandate fonts, pair a distinctive display face with a refined body face (a single generic sans for both jobs is the most recognisable generated-UI tell). Bans italicised headings as default emphasis.

Colour

Every colour from a DS token; no improvised hex or oklch values mid-build. One accent hue per view, used sparingly. Bans purple-to-cyan gradient heroes on white. Bans gray text on coloured backgrounds and glow as a primary cue.

Spacing

Every gap from the DS spacing scale. Generous vertical rhythm between sections. Optical centring for icons and glyphs, not just geometric.

Motion

Animate compositor properties only (transform, opacity). Bans transition: all and animating layout properties. Entrances ease-out, exits ease-in, user-initiated motion capped at 300ms. Honour prefers-reduced-motion. Bans bounce easing on interface state changes. One orchestrated moment beats scattered micro-effects.

Interactive states and accessibility floor

Every applicable state handled: default, hover, focus-visible, active, disabled, plus loading, error, success. Visible focus ring always. Text contrast at 4.5:1 or better. Touch targets at 44px or larger. Errors adjacent to the field, not only in a summary. Never signal state by colour alone. Never put information-bearing tooltips behind hover alone. Never wrap a clickable label to two lines. Never horizontal-scroll on mobile.

Honesty and restraint

Composition defaults that resist the generative-UI tells: avoid manufactured drama (stat counters that animate on scroll for no reason), prefer real content over placeholder Lorem, name what is uncertain rather than papering over it.

How the audit protects the file

scripts/check-skill-docs.sh includes a DESIGN_CRAFT check that asserts two things after Phase 3 writes:

• The produced references/design-craft.md is a byte-for-byte copy of the meta-skill's original asset. A diff means the file was regenerated, paraphrased, trimmed, or "adapted". The check fails.
• The produced SKILL.md routing table carries the fixed design-craft row.

The byte-diff is the entire enforcement mechanism. It catches the most likely failure mode: a future agent reads assets/design-craft.md into context during extraction "to be safe" and emits a paraphrased version into the produced skill. The check fails the run. The fix is to delete the produced file and re-run the scaffolder, which copies the original bytes again.

How to opt out

Say "skip design craft" at the Phase 1 confirmation step. The discovery summary's craft ship-note line is the prompt for this. When opted out:

• scripts/scaffold.sh runs with --no-design-craft.
• The file is not copied.
• The routing table row is omitted from SKILL.md.
• The DESIGN_CRAFT check does not fire.

The default ships the file. Opt out only if your DS already documents composition defaults at this level and you want to avoid the small risk of a precedence-rule conflict you have not reviewed.

What the file is not

What to take away

1. Design craft is the floor. It is the default the agent applies wherever the DS is silent.
2. It ships byte-for-byte from the meta-skill. The cite-or-[VERIFY] contract does not apply to it.
3. The DS wins on conflict, every time, without comment.
4. Rules use MUST / SHOULD / NEVER and fire at composition time, not on token or component questions.
5. Opt out at Phase 1 with "skip design craft" if your DS already covers this territory. Otherwise ship the default.
6. Never edit the produced file in place. Improvements go upstream in the meta-skill.

Primary source: .claude/skills/extract-ds-skill/assets/design-craft.md (the file itself), .claude/skills/extract-ds-skill/SKILL.md ("Scope (locked)" section), and references/persist.md ("Design-craft materialization" section).