DesignContract
DesignContract v1
The versioned JSON contract is canonical. Rendered Markdown, CSS, HTML, and scorecards are views of the same object — not separate opinions.
Overview
DesignContract v1 is the enforceable layer between your product brief and implementation. When strategy changes, you regenerate the contract. When layout tweaks, you patch the implementation and re-score.
JSON is canonical. DESIGN.md, route.json, tokens.css, scorecard.md, and contract-preview.html are rendered views of the same object so humans and agents read identical constraints.
Schema highlights
Full schema: contracts/schema/design-contract.schema.json. CI compiles 20 golden briefs and validates every output against this schema.
| Field area | What it controls |
|---|---|
| audience + primaryAction | Who the page is for and the single main CTA |
| route + sections | Page type and ordered section jobs |
| proofRequirements | Evidence that must appear before the ask |
| forbiddenPatterns | Explicit anti-slop rules (no generic bento proof, etc.) |
| qaGates | Clause IDs used by lint and score |
| tokens + motion | Visual grammar constraints |
| agentHandoff | How builders should read and obey the pack |
Commands
npx dzine-skill compile "premium AI product site" --contract --out dzine-packnpx dzine-skill validate dzine-pack/design-contract.jsonnpx dzine-skill lint dzine-pack/design-contract.jsonnpx dzine-skill render dzine-pack/design-contract.json --out-dir dzine-pack/renderednpx dzine-skill score --contract dzine-pack/design-contract.json --url http://localhost:3003 --out dzine-pack/score-report.jsonnpx dzine-skill repair --contract dzine-pack/design-contract.json --scorecard dzine-pack/score-report.json --out dzine-pack/repair-prompt.mdArtifacts
| File | Reader | Purpose |
|---|---|---|
| design-contract.json | Scripts, CI, agents | Source of truth |
| DESIGN.md | Agents, humans | Structured Markdown handoff |
| route.json | Agents | Section architecture |
| tokens.css | Implementers | Starter semantic tokens |
| scorecard.md | QA, agents | Pass/fail review gates |
| contract-preview.html | Humans | Browser dossier |
Sample: examples/design-contracts/sample-ai-product/ · Gallery: Examples
Workflow
- Compile a brief into DesignContract v1.
- Lint before implementation — fix weak audience, proof, or action fields.
- Build with your agent using the rendered pack.
- Score the live URL against contract clause paths.
- Repair only failed clauses; re-score until gates pass.
Weak contracts
Lint intentionally fails contracts missing proof, vague primary actions, or empty accessibility rules. CI includes two weak fixtures to ensure the failure path stays working.