design-os

Autonomous design-quality loop and design harness. Composes kai-taste's rubric, a render+critique pipeline (vendored from ux-qa-harness), and an approval-gated shipping queue (vendored from approval-inbox) into a scheduled pipeline — and, on top of that, enforces a researched canon of design mastery as machine-checkable rules:

• design_os/canon/ — distilled philosophies/workflows of the masters (Rams, Swiss school, Refactoring UI, Linear/Stripe/Vercel, Apple HIG, brand identity, typography, system governance, critique practice, motion, information design, proof posterism, and MoonshotAI's atomic visual-perception evaluation)
• design_os/rules/catalog.yaml — every rule with a stable ID, threshold, severity (block/flag/advise) and check type (deterministic/vision/process)
• design_os/lint/ — deterministic rules computed over a live style snapshot
• design_os/critique/lenses.py — three-lens critique panel returning per-rule verdicts with evidence
• design_os/process/ — workflow stage gates (divergence before convergence, taste contracts instead of adjectives, critique before ship)
• waivers.yaml — the only sanctioned way to break a rule: scoped, justified, expiring

The iron rule, enforced in orchestrator/run.py: an unwaived block failure never auto-ships. See AGENTS.md for the full harness contract.

Ships as a single self-contained Python package — no sibling repos to clone, no setup scripts to patch missing packaging metadata. design_os/_vendor/ carries a pinned copy of the two pieces design-os actually calls (ux-qa-harness's qa.py/vision.py render+critique engine, approval-inbox's ApprovalStore); design_os/taste/kai-taste/ carries the kai-taste rubric content directly. These are vendored, not live-synced — if the upstream repos change, re-copy the relevant files by hand.

See docs/superpowers/specs/2026-07-02-design-os-design.md for the design.

Fast path: run the included example

The starter example is deliberately offline. It gives you a real poster-like HTML artifact, a process log, a style snapshot, and a small perception-review record. Run every check with one command from the repository root:

python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\python -m pip install -e ".[dev]"
# macOS/Linux: .venv/bin/python -m pip install -e ".[dev]"

python examples/run_example.py

Or run the gates one at a time while you are designing:

python -m design_os.process examples/starter/process-log.yaml
python -m design_os.lint examples/starter/style-snapshot.json --target-id proof-poster-starter --artifact-type page
python -m design_os.orchestrator.run --watchlist examples/starter/watchlist.yaml --dry-run

The lint output intentionally reports unimplemented catalog rules as UNIMPLEMENTED; that is a visible gap report, not a false pass. The command only blocks on an actual unwaived deterministic block failure. To audit a live page, pass its URL instead of the snapshot path. Playwright must have a browser installed for that path:

playwright install chromium
python -m design_os.lint https://your-site.example --target-id your-site --snapshot-out runs/your-site/style-snapshot.json

Read examples/starter/README.md for the artifact, the process-log decisions, and the perception-review pattern.

Setup from scratch

python -m venv .venv
python -m pip install -e ".[dev]"

The live non-dry-run path is audit-only in v1: it renders and critiques URLs, records the result, and never publishes a change. See deploy/README.md.

Research basis

The operational translation of the visual references and MoonshotAI research lives in docs/research-basis.md. The short version: borrow reduction, hierarchy, symbols, direct language, and atomic evaluation; do not copy an artist's surface style.

---

Built and maintained by Connor Gallic — connect on LinkedIn.