Design Canon is an open design-policy compiler, linter, and visual-QA project for AI coding agents. It turns a structured catalog of contextual design rules into compact instructions for the interface you are actually building, then checks the result for detectable violations.

It is not an 800,000-character prompt brick. It is a versioned system.

Watch the Launch Film

Design Canon turns generic AI-generated interface defaults into scoped, testable, versioned design policy.

Why

AI agents can generate polished frontend code quickly, but they often converge on the same defaults: centered hero stacks, purple gradients, giant rounded cards, decorative shadows, generic copy, weak focus states, and motion sprayed everywhere.

A giant markdown file can nudge the model, but it creates four new problems:

• irrelevant context consumes tokens and dilutes important rules
• universal bans confuse taste with dogma
• prose rules cannot prove they were followed
• the system cannot learn from explicit user preferences

Design Canon separates rules, profiles, compilation, linting, visual review, and taste memory.

Working Alpha

The repository already includes:

• atomic, scoped design rules with rationale and verification
• profiles for marketing pages, product applications, and editorial layouts
• compilation to DESIGN.md, SKILL.md, or general agent instructions
• a zero-runtime-dependency linter for mechanical heuristics
• project-local, rationale-required suppressions that preserve evidence
• safe dry-run installation and uninstall adapters for AGENTS.md, Codex, Hermes, Claude Code, Cursor, and Windsurf
• an installable Agent Skill for Codex, Hermes Agent, Claude Code, Cursor, and compatible tools
• tests and an intentionally terrible example fixture

Quick Start

git clone https://github.com/asimons81/design-canon.git
cd design-canon
npm test

node ./bin/design-canon.js compile \
  --profile marketing \
  --target design \
  --output DESIGN.md

node ./bin/design-canon.js lint ./src --profile marketing

Available profiles:

node ./bin/design-canon.js profiles

Install into an Agent

Preview a portable root AGENTS.md installation:

node ./bin/design-canon.js init . \
  --profile product-app \
  --target agents

Apply it only after reviewing the preview:

node ./bin/design-canon.js init . \
  --profile product-app \
  --target agents \
  --write

Targets include agents, codex, hermes, claude, cursor, and windsurf. See docs/ADAPTERS.md for file locations, scope behavior, safety guarantees, and uninstall commands.

Justified Exceptions

Design Canon does not confuse a detector with an aesthetic law. Projects can suppress a finding only through an explicit, scoped rationale in design-canon.config.json:

{
  "$schema": "./schema/config.schema.json",
  "version": 1,
  "profile": "marketing",
  "suppressions": [
    {
      "rule": "color.purple-gradient-default",
      "files": ["src/brand/**/*.css"],
      "reason": "Purple is the documented primary brand color for this campaign.",
      "approvedBy": "design-systems",
      "expires": "2099-12-31"
    }
  ]
}

node ./bin/design-canon.js lint . \
  --config design-canon.config.json \
  --format json

Expired, unknown, duplicated, absolute, or path-escaping suppressions fail closed. Suppressed findings remain in the JSON report with their evidence and rationale. Unused suppressions are reported for cleanup.

See docs/CONFIGURATION.md for the complete contract.

The Upgrade

| Prompt bundle | Design Canon | |---|---| | One enormous context file | Compiles only relevant rules | | Blanket style bans | Contextual profiles and overrides | | Advice only | Static lint plus planned visual evidence | | No verification contract | Every rule can define checks | | Same taste for everyone | Planned project-local preference memory | | Unclear provenance | Versioned, reviewable, open rule packs | | “Looks better” claims | Planned paired benchmarks |

Benchmark Status

The repository includes a hardened benchmark harness, but the public benchmark campaign has not been run. The nonofficial B000 calibration completed successfully across four frozen conditions and validated runner isolation, capture, network denial, and artifact integrity. B000 is claim-ineligible and did not select a winner.

B001-B015 remain unexecuted. Any provider-backed benchmark run requires separate user authorization, an exact call count, and a reviewed spend estimate. Normal installation, compilation, linting, and agent-adapter workflows do not invoke a model provider.

See research/benchmark/calibration/B000-PHASE2-RUNNER.md for the calibration record and safety boundaries.

Repository Map

bin/                    CLI entry point
src/                    compiler, selector, linter, and adapters
rules/                  atomic design-policy catalog
profiles/               surface-specific rule selection
schema/                 open JSON schemas
skills/design-canon/    portable Agent Skill
examples/sloppy/        violation fixture
tests/                  regression tests
docs/ARCHITECTURE.md    system design
docs/CONFIGURATION.md   configuration and suppression contract
docs/ADAPTERS.md        safe agent installation and uninstall
ROADMAP.md              path to visual QA, benchmarks, and taste memory

Philosophy

Gradients are not illegal. Shadows are not illegal. Inter is not illegal. Cards are not illegal.

Unexamined defaults are the enemy.

A detector creates a review obligation, not an automatic aesthetic verdict. The final authority remains the person shipping the interface.

Clean-Room Notice

Design Canon is an independent clean-room implementation based on public product behavior, open design standards, and original rules. Do not submit copied proprietary prompt files or unlicensed branded design systems.

License

MIT