Help us improve
Share bugs, ideas, or general feedback.
From leyline
Use when implementing any task whose "Files:" block touches a user-facing surface, before writing the code for that surface. Enforces the DRAW-BUILD-RECONCILE cycle: the UX artifact is the source of truth, the implementation instantiates it, and any divergence is resolved explicitly. An overlay during stage 5 alongside test-driven-development.
npx claudepluginhub forsonny/leyline --plugin leylineHow this skill is triggered — by the user, by Claude, or both
Slash command
/leyline:design-driven-developmentThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> I'm using the design-driven-development skill. The UX artifact at `docs/leyline/design/<file>` is the source of truth. I will not diverge from it without updating the artifact and re-getting approval; I will not implement from memory.
Guides technical evaluation of code review feedback: read fully, restate for understanding, verify against codebase, respond with reasoning or pushback before implementing.
Share bugs, ideas, or general feedback.
I'm using the design-driven-development skill. The UX artifact at
docs/leyline/design/<file>is the source of truth. I will not diverge from it without updating the artifact and re-getting approval; I will not implement from memory.
NO USER-FACING SURFACE WITHOUT AN APPROVED DESIGN ARTIFACT FIRST
Violating the letter of the rules is violating the spirit of the rules.
Surfaces shipped without an approved artifact ship the first thing that works, not the thing that should ship. Without the artifact as source of truth, implementation decisions - empty-state text, error recovery, spacing, order of operations - are made by the implementer under time pressure and in isolation. Those decisions drift from each other across surfaces, accumulate silently, and become the codebase's UX over time. The artifact exists so the decisions are made once, reviewed once, and applied consistently.
Any output a human perceives:
When in doubt, it is a surface.
Only these are valid, and they must be asked before taking them:
"It is a small change" is NOT an exception. "We are in a hurry" is NOT an exception. "The surface is internal" is ONLY an exception for the specific cases above.
The UX analog of RED-GREEN-REFACTOR:
digraph ddd_flow {
Start [shape=doublecircle, label="Task touches a surface"];
Draw [shape=box, label="1. DRAW: artifact exists and is current"];
DrawCheck [shape=diamond, label="Artifact current and approved?"];
LoopBack [shape=box, label="STOP; loop to design-brainstorming"];
Match [shape=diamond, label="Artifact covers this surface?"];
Build [shape=box, label="2. BUILD: minimal code that instantiates the artifact"];
TDD [shape=box, label="(TDD runs in parallel under 6a.1)"];
Reconcile [shape=box, label="3. RECONCILE: side-by-side artifact vs implementation"];
Diverge [shape=diamond, label="Divergence?"];
FixImpl [shape=box, label="Fix the implementation to match the artifact"];
FixArt [shape=box, label="OR update the artifact and re-approve (loop to design-brainstorming)"];
Done [shape=doublecircle, label="Design did not lie"];
Start -> Draw;
Draw -> DrawCheck;
DrawCheck -> LoopBack [label="no"];
DrawCheck -> Match [label="yes"];
Match -> LoopBack [label="no - surface not designed"];
Match -> Build [label="yes"];
Build -> TDD;
TDD -> Reconcile;
Reconcile -> Diverge;
Diverge -> FixImpl [label="yes - code wrong"];
Diverge -> FixArt [label="yes - artifact wrong"];
FixImpl -> Reconcile;
FixArt -> Build;
Diverge -> Done [label="no - matches"];
}
Note on apparent duplication with Stage 5's Experience gate: the dispatching skill (
subagent-driven-development/executing-plans) already runs checks 1-3 pre-dispatch. DRAW re-verifies inside the task because (a) the inlineexecuting-planspath may skip the pre-dispatch check under pressure, (b) the UX artifact could have been modified between dispatch and execution (long-running task, another session touched the file), and (c) check 4 (surface coverage in the state matrix) is unique to DRAW and has no pre-dispatch equivalent. The cost of re-running checks 1-3 is seconds; the cost of missing one is a shipped surface with no artifact.
Before any code:
Locate the artifact. docs/leyline/design/<YYYY-MM-DD>-<feature-name>-ux.md. If it does not exist, STOP - there is no source of truth. Route to design-brainstorming.
Confirm it is approved. Grep for the verbatim marker:
grep -E '^UX spec approved - round [0-9]+ - [0-9]{4}-[0-9]{2}-[0-9]{2}$' "<path>"
If missing, STOP and route to design-brainstorming.
Confirm it is current. The spec's highest-round approval marker is the current round. If the plan's Spec references block names a specific UX spec round (UX spec round <N>), the spec's current round must be >= N; if the spec is behind, STOP and route to design-brainstorming to catch it up. If the plan does NOT name a round (older plans or minimal templates), accept the spec's latest round as current. Drift from a plan-named round to the spec's current round is a finding only when the plan explicitly named the round.
Confirm the surface is covered. The task's "Files:" block touches surface X. Is X enumerated in the UX spec's Surfaces list? Is X a row in the state matrix? If not, STOP - the task is touching a surface the artifact does not describe. Route to design-brainstorming to add the surface.
Exit DRAW only when all four confirmations pass.
RECONCILE step will catch it.After GREEN (from TDD):
Surfaces: cross-platform, the UX spec may declare intentional per-platform divergence (iOS modal presents bottom-up; Android presents inline; the same surface diverges by platform by design). Intentional divergence explicitly documented in the UX spec's "Per-platform adaptation" section IS the artifact's truth for that platform. RECONCILE against the per-platform section, not the default section, when the target is one of the declared platforms. Silent divergence - behavior that differs by platform without the UX spec declaring it - is still forbidden; if you implement per-platform behavior that is not in the spec, update the spec first.design-brainstorming for the human partner's re-approval. Do not edit the artifact silently; the re-approval is what keeps the artifact a source of truth.Silent drift is forbidden. "Good enough for now, will reconcile later" never reconciles later. Intentional per-platform divergence is NOT silent drift if it is declared in the UX spec; it is the artifact's truth.
Do not claim a surface-touching task complete until:
accessibility-verification gate also passed (the 6b.2 iron law is additive).If a surface was built without an approved artifact (or the artifact drifted silently):
design-brainstorming."Delete the surface" is not a suggestion. A surface shipped without an artifact carries the implementer's taste, not the team's decisions. Keeping it "to save time" embeds the uncurated decisions into the codebase; the next surface copies them; the pattern propagates.
design-brainstorming.| Thought | Reality |
|---|---|
| "The artifact is almost right, I'll tweak it in the code" | Tweak it in the artifact, not the code. |
| "This loading state is obvious, artifact doesn't need to say" | Obvious-to-you is framework-default-leaking-through. |
| "The error text is cleaner in my version" | Then update the artifact. Keep one source of truth. |
| "RECONCILE took 30 seconds, passed" | 30 seconds is not every state-matrix row. Do the walk. |
| "Permission-denied is rare, skip it" | Rare is not none. Rare is where user trust breaks. |
| "I'll polish the empty state later" | Empty states ship as first-run experiences. Do not defer. |
Do not say:
This is an overlay. After RECONCILE completes and the task passes the claim-to-evidence gate, control returns to the caller (typically subagent-driven-development or executing-plans). No explicit successor. accessibility-verification runs next for the same task.
../../dev/principles/iron-laws.md - catalogues this iron law../../dev/principles/experience-discipline.md - the 6b overlay rationale../../dev/stages/06-discipline.md - canonical overlay definition../../dev/reference/surface-types.md - what counts as a surface; template by Surfaces value../design-brainstorming/SKILL.md - produces the artifact this skill consumes; loop-back target../accessibility-verification/SKILL.md - the sibling iron law that runs for the same surface../test-driven-development/SKILL.md - 6a.1 cycle that runs in parallel during BUILD