DESIGN:OS (design-os)

Multi-runtime design operating system and CLI for Claude Code, OpenAI Codex, Gemini CLI, and Google Antigravity.

Install once to equip any AI coding agent with 12+ domain design skills, deterministic verification gates, 2:1 axonometric art direction, and live Figma / SVG / 3D / SwiftUI / packaging workflows.

---

Why this exists

AI coding agents write functional code quickly, but their default visual output suffers from inconsistent spacing, hallucinated tokens, rainbow badges, and zero verification gates. DESIGN:OS turns aesthetic taste and design systems engineering into deterministic, runtime-agnostic contracts.

Dimension	Generic AI / Manual Workflow	DESIGN:OS CLI (DESIGN:OS)
Visual Quality	Generic purple-gradient AI slop and ad-hoc CSS	Token-locked typography, 8pt modular grid, and 2:1 axonometric art direction
Context Budget	Dumping massive style guides into every prompt	Progressive skill disclosure (SKILL.md router + on-demand domain packs)
Verification	Visual eyeballing with zero automated checks	Deterministic CLI gates (self_check.py, contrast, and anti-flop audits)
Multi-Agent Parity	Locked to a single IDE or proprietary prompt format	One canonical skill tree across Claude Code, Codex, Gemini CLI & Antigravity
Privacy & Telemetry	Opaque cloud telemetry or unverified third-party APIs	Zero telemetry — 100% local execution (PRIVACY.md audited)

---

Quickstart

1. Install the plugin or CLI

In Claude Code:

/plugin marketplace add jangtrinh/design-os
/plugin install design-os@design-os

Or from your terminal (Codex, Gemini CLI, Antigravity, OpenCode, or standalone CLI):

git clone https://github.com/jangtrinh/design-os.git
cd design-os
npx @easestart/design-os init

2. Ask in plain English

Open your project in your AI coding agent and describe what you need:

"Initialize DESIGN:OS in this repo and wire our design tokens and verification gates for Claude Code and Codex."

"Audit our current frontend components against DESIGN:OS typography, spacing, and WCAG 2.2 AA contrast gates."

"Scaffold a new product landing page with 2:1 axonometric B&W technical illustrations and SEO/AEO/GEO metadata."

3. Verify your setup

python3 scripts/self_check.py

---

What it makes

Every deliverable produced by design-os is backed by a deterministic verification gate rather than freehand AI guesswork.

Deliverable / Mode	Best for	Output Format	Verification Gate
Multi-Runtime Skill Pack	Wiring Claude Code, Codex, Gemini CLI, and Antigravity to one design standard	.claude-plugin + skills/	python3 scripts/self_check.py
Design System Tokens & Gates	Enforcing spacing, typography, and WCAG 2.2 AA contrast in CI	JSON / CSS / CLI exit code	Zero contrast or grid violations
Cross-Engine Orchestration	Routing tasks to Figma, SVG Animation, 3D Blender, Apple SwiftUI, or Origami CAD	Verified domain artifacts	13-engine ecosystem parity
Design-System Guidelines Pack	Teaching any design agent the rules a library cannot show — owner rulings, look-alike components, measured anti-patterns — and shipping them as a Figma library guidelines bundle	design/guidelines/*.md + figma-guidelines/	ui ds guidelines check — no invented names, no tampered facts, Figma's 8-file / 200 KB limits

---

Installation

Choose the setup that matches your AI coding agent. Every option installs the same canonical skill (skills/design-os/SKILL.md) and /doctor diagnostic suite.

Claude Code

Run these two commands inside Claude Code:

/plugin marketplace add jangtrinh/design-os
/plugin install design-os@design-os

OpenAI Codex

Install to your personal Codex skills directory:

git clone https://github.com/jangtrinh/design-os.git /tmp/design-os
mkdir -p ~/.codex/skills/design-os ~/.codex/prompts
cp -R /tmp/design-os/skills/design-os/* ~/.codex/skills/design-os/
cp /tmp/design-os/prompts/doctor.md ~/.codex/prompts/design-os-doctor.md
rm -rf /tmp/design-os

Gemini CLI & Google Antigravity

git clone https://github.com/jangtrinh/design-os.git /tmp/design-os
mkdir -p ~/.gemini/skills/design-os
cp -R /tmp/design-os/skills/design-os/* ~/.gemini/skills/design-os/
rm -rf /tmp/design-os

OpenCode, Cursor, Windsurf & Other Agent Harnesses

git clone https://github.com/jangtrinh/design-os.git /tmp/design-os
mkdir -p ~/.agents/skills/design-os
cp -R /tmp/design-os/skills/design-os/* ~/.agents/skills/design-os/
rm -rf /tmp/design-os

Verify installation:

python3 scripts/self_check.py

Or run /doctor inside Claude Code / Codex to inspect installed skill paths, plugin manifests, and gate health.

Uninstall:

rm -rf ~/.claude/skills/design-os ~/.codex/skills/design-os ~/.gemini/skills/design-os ~/.agents/skills/design-os

---

Usage & Prompt Cookbook

Once installed, skills/design-os/SKILL.md activates automatically when your prompt matches its domain triggers. Browse docs/cookbook.md for copy-paste prompt recipes.

Generate & Scaffold

"Initialize DESIGN:OS in this repo and wire our design tokens and verification gates for Claude Code and Codex."

Audit & Verify

"Audit our current frontend components against DESIGN:OS typography, spacing, and WCAG 2.2 AA contrast gates."

Export & Automate

"Scaffold a new product landing page with 2:1 axonometric B&W technical illustrations and SEO/AEO/GEO metadata."

---

Commands & Diagnostics

Command	Environment	What it does
/doctor	Claude Code / Codex	Read-only diagnostic check of installed skill paths, plugin manifests, and runtime prerequisites
python3 scripts/self_check.py	Terminal / CI	Deterministic offline verification of manifests, skill contracts, and governance files
npx @easestart/design-os doctor	Terminal / CI	Inspect active runtime adapters (Claude Code, Codex, Gemini CLI, Antigravity) and installed skill packs
ui taste-lint — 34 absolute checks	Terminal / CI	Generated-UI taste checks across motion, typography, spacing, and focus states
ui validate-layout — 20 checks	Terminal / CI	Structural and overflow safety checks (100vw traps, unclosed tags, sticky overflow)
ui content-lint — 12 checks	Terminal / CI	Honest copy checks (placeholder text, lorem-ipsum, generic names, all-caps shouting)
ui tell-lint — 43 checks, any language	Terminal / CI	Polyglot design-tell checks across HTML, JSX/TSX, Vue, Svelte, CSS, SwiftUI, and Flutter
ui ds guidelines build | check | export --target figma	Terminal / CI	Compile a cited guidelines pack from your sealed design system, rulings and glossary; lint it; export a ready-to-upload Figma library guidelines bundle
skills/design-os-designer — build.mjs, validate.mjs, look.mjs	Any agent runtime	The shipped design skill: build an evidence folder for a page, run ui gate plus file checks, render a three-width sheet with measured items; ui init wires it into Claude Code, Antigravity and Codex

---

How it works

1. Intent Routing — Your AI agent matches your request against skills/design-os/SKILL.md frontmatter triggers.
2. Progressive Context Loading — Only the entry-point SKILL.md router loads initially; detailed recipes and scripts load on demand.
3. Deterministic Execution — Domain scripts and contracts execute locally with reproducible inputs and outputs.
4. Gate Verification — scripts/self_check.py and domain verifiers (npx @easestart/design-os init) validate the artifact before completion.
5. Zero-Telemetry Delivery — Verified files are written directly to your workspace with zero external network calls.

User Prompt / CLI Invocation
            │
            ▼
┌───────────────────────────────────────────────┐
│ skills/design-os/SKILL.md
│ Progressive disclosure router & hard rules    │
└───────────┬───────────────────────────────────┘
            │ loads on demand
            ▼
┌───────────────────────────────────────────────┐
│ npx @easestart/design-os doctor
│ Deterministic build & contract enforcement    │
└───────────┬───────────────────────────────────┘
            │ verifies
            ▼
┌───────────────────────────────────────────────┐
│ python3 scripts/self_check.py + /doctor       │
│ Zero-telemetry local verification gate        │
└───────────────────────────────────────────────┘

What loads when

design-os uses progressive context disclosure so your agent's context window stays fast and focused:

File	Loaded when
skills/design-os/SKILL.md	Always (~100–150 lines) — routing rules, triggers, and execution workflow
docs/cookbook.md	When selecting multi-step prompt recipes or domain patterns
commands/doctor.md / prompts/doctor.md	Only when running /doctor diagnostics
llms.txt	When indexed by AI answer engines, RAG pipelines, or repo crawlers

---

File structure

design-os/
├── .claude-plugin/
│   ├── plugin.json                 # Claude Code plugin manifest
│   └── marketplace.json            # Claude Code marketplace catalog
├── .codex-plugin/
│   └── plugin.json                 # OpenAI Codex plugin & interface manifest
├── .agents/
│   └── plugins/marketplace.json    # Cross-agent local plugin registry
├── .factory-plugin/
│   ├── plugin.json                 # Factory / Droid plugin manifest
│   └── marketplace.json            # Factory marketplace metadata
├── skills/
│   └── design-os/
│       └── SKILL.md                # Canonical agent skill entrypoint
├── commands/
│   └── doctor.md                   # /doctor diagnostic slash command
├── prompts/
│   └── doctor.md                   # Codex diagnostic prompt mirror
├── scripts/
│   └── self_check.py               # Deterministic repository & skill self-check
├── docs/
│   ├── cookbook.md                 # Copy-paste prompt recipes by job
│   └── llms.txt                    # GEO / LLM discovery index
├── PRIVACY.md                      # Zero-telemetry & local-first privacy commitment
├── SECURITY.md                     # Vulnerability disclosure & security policy
├── CONTRIBUTING.md                 # Contribution workflow & verification rules
├── CODE_OF_CONDUCT.md              # Contributor Covenant code of conduct
├── CHANGELOG.md                    # Release history
├── llms.txt                        # Root LLM indexing manifest
├── LICENSE                         # PolyForm Shield 1.0.0
└── README.md

---

Quality bar & Limitations

It's working if...

• python3 scripts/self_check.py prints ok: design-os self-check passed (design-os) and exits 0.
• npx @easestart/design-os init passes with zero contract or test regressions.
• Your AI coding agent loads skills/design-os/SKILL.md automatically when given any prompt from docs/cookbook.md.
• Network traffic during execution remains zero (guaranteed by PRIVACY.md).

When not to use

• Throwaway backend scripts with zero user-facing UI, CLI, or documentation surface.
• Teams looking for a hosted cloud SaaS design tool rather than a local-first, git-tracked engineering toolchain.
• Replacing human brand strategy — DESIGN:OS enforces and scales design systems, not customer discovery.

---

Watch

DESIGN:OS is free and source-available (PolyForm Shield). The Autonomous Design Agent talks from the design:os by Jang channel (Vietnamese, with English terms):

• Xây dựng autonomous design agent cho doanh nghiệp? how? (7:06): How the DESIGN:OS CLI, plugin bridge and deterministic gates turn an ontology into an autonomous design agent for enterprise design systems. Vietnamese, with English terms.
• Ontology là gì? apply vào build AI design agent như thế nào? (7:33): What an ontology is and how it grounds an AI design agent: shared vocabulary, semantic RAG and reusable design decisions. Vietnamese, with English terms.
• Autonomous Design Agent · Tập 03: Model + Harness và 6 trụ cột DESIGN:OS (8:44): Agent = Model + Harness: the six pillars of DESIGN:OS (single source of truth, Ontology Graph RAG, dual-layer spec, 126 CI gates, 9-verb patch, watchers). Vietnamese, with English terms.

More: Autonomous Design Agent series.

---

DESIGN:OS Ecosystem

design-os is one of the 13 source-available engines in the DESIGN:OS ecosystem:

Engine	Live Docs	Repository	Layer
DESIGN:OS CLI	jangtrinh.github.io/design-os	jangtrinh/design-os	cli
Knowledge Builder	jangtrinh.github.io/design-os-knowledge-builder	jangtrinh/design-os-knowledge-builder	compiler
Figma Plugin & CLI	jangtrinh.github.io/design-os-figma-plugin	jangtrinh/design-os-figma-plugin	plugin
SVG Animation Engine	jangtrinh.github.io/design-os-svg-animation	jangtrinh/design-os-svg-animation	engine
3D Blender Agent	jangtrinh.github.io/design-os-3d-blender

---

Contributing, Governance & License

• Contributing: See CONTRIBUTING.md for pull request guidelines and verification gates (python3 scripts/self_check.py).
• Code of Conduct: Governed by CODE_OF_CONDUCT.md.
• Security & Privacy: Zero telemetry — see SECURITY.md and PRIVACY.md.
• Changelog & LLM Index: Track releases in CHANGELOG.md and machine-readable index in llms.txt.
• License: PolyForm Shield 1.0.0 © Jang Trinh. Free to use and modify, including for paid client work; you may not resell it or build a competing product from it.

---

If design-os saves you time, a star on GitHub helps other engineers and AI agents find it.