# decantr.ai

We don't care what you build with.

We care what you build.

Decantr is the evidence-backed reliability layer for AI-generated web applications.

Not a component library. Not a code generator. A contract the AI checks, proves, and repairs against.

Get Started GitHub

How are you starting?

⭐ Recommended

### Greenfield blueprint

New project from a published app composition — theme, sections, voice, and personality baked in.

$ decantr new my-app --blueprint=X --adoption=decantr-css
Existing app

### Brownfield adoption

Attach Decantr to an existing app as a contract layer first. No rewrite, no CSS takeover.

$ decantr adopt --yes
Layer in

### Hybrid operating layer

Any attached project. Codify local UI law, then layer Decantr guidance deliberately.

$ decantr codify · task
Tooling only

### Greenfield contract-only

Start a new repo with Decantr context, checks, and AI contracts while keeping your runtime choices open.

$ decantr init --workflow=greenfield --adoption=contract-only

## Every AI-generated app has an expiration date

AI coding assistants have no memory of design intent. Every prompt is a fresh start. By prompt 10, your app looks like it was built by 10 different people.

Without Decantr · drift compounds

Prompt 1
Prompt 5
Prompt 10

With Decantr · same contract, any theme

luminarum
terminal
carbon
Zero drift · 3 themes · one essence

## One command. You'll never go back.

Scaffold a complete design system, then paste one prompt. The AI reads the context files and builds a visually stunning, production-quality app.

1

### Initialize

$ npx @decantr/cli new my-app --blueprint=esports-hq
2

### Paste the prompt

Build this application using the Decantr design system. Read DECANTR.md for the design spec, CSS approach, and guard rules. Read .decantr/context/scaffold.md for the app overview, topology, routes, and voice guidance. Read each .decantr/context/section-*.md file before building that section's pages. Import src/styles/global.css, src/styles/tokens.css, and src/styles/treatments.css. Start with the shell layouts, then build each section's pages.
3

### What the AI receives

DECANTR.md
Guard rules · CSS atoms · Layout rules · Motion philosophy · Interactivity
→
scaffold.md
Topology · Routes · Voice & copy · Shared components · Dev mode
→
section-*.md
Shell layout · Decorators · Tokens · Composition · Motion · Responsive
→
Production UI
Visually stunning, consistent, production-ready code

## How Decantr works

Three tiers of context, each more specific than the last. The AI gets everything it needs to build every page correctly.

DECANTR.md

- Design rules
- Guard system
- CSS approach
- Layout rules
- Motion philosophy
- Interactivity philosophy
- Development workflow

scaffold.md

- App topology
- Route map
- Voice & copy guidance
- Shared components
- Zone transitions
- Development mode

section-*.md

- Shell implementation specs
- Quick start guide
- Spacing guide
- Decorator tables
- Token palette
- Visual briefs
- Composition algebra
- Motion specs
- Responsive strategies

## Rich, actionable context -- not vague instructions

Every section context is self-contained. The AI gets everything it needs for each page in one file.

## Quick Start # From section-agent-orchestrator.md: Shell: SidebarMainLayout (sidebar 260px, main fluid) Sidebar: fixed, dark bg, 60px header zone, nav groups with icons Tokens: import tokens.css -- surfaces, borders, text, accents Treatments: import treatments.css -- cards, code blocks, data rows ## Pattern: Agent Timeline Visual brief: Vertical feed of agent execution events. Each node shows timestamp, agent name, action type, and status badge. Connected by a thin vertical line (border-left on the timeline track). Composition: timeline-track > timeline-node[] > { icon, meta, detail } Spacing: gap-4 between nodes, p-4 inside cards Motion: nodes fade-in staggered 50ms on mount Responsive: single-column, full-width at all breakpoints
## Topology # From scaffold.md — the full app overview Zones: public → marketing-core (home, pricing, about) gateway → auth-full (/login, /register) app → agent-orchestrator (/chat, /settings) Transitions: public → gateway via CTA clicks (Sign up, Sign in) gateway → app via successful auth (redirect /chat) app → gateway via logout (redirect /login) ## Voice & Copy Tone: confident, technical, warm CTA verbs: Start, Build, Compose — never "Click here" Empty: "No agents yet. Compose your first one." Errors: one sentence, cause + next action ## Development Mode Dev auth: the generated auth flag bypasses gateway Mock data: every page ships with realistic seeded fixtures
## Pattern: split-feature # Resolved via decantr_resolve_pattern Visual brief: Two-column feature block. Left column holds a tight code snippet or terminal capture; right column carries the headline, body copy, and a single CTA. Asymmetric alignment — text is top-aligned, media floats. Slots: - media (code-sample · terminal · image) - eyebrow (optional uppercase label) - headline - body - cta-primary Composition: split-container > [ split-media > { slot: media }, split-content > { eyebrow, headline, body, cta-primary } ] Motion: media slides in 80px → 0 on scroll. content fades. Responsive: stacks under 720px — media on top, content below A11y: media is decorative unless media.role = "demo"

## 25 tools for your AI assistant

Install once. Every prompt gets smarter.

Add the MCP server
$ claude mcp add decantr -- npx -y @decantr/mcp-server
# ~/.cursor/mcp.json { "mcpServers": { "decantr": { "command": "npx", "args": ["-y", "@decantr/mcp-server"] } } }
# ~/.codeium/windsurf/mcp_config.json { "mcpServers": { "decantr": { "command": "npx", "args": ["-y", "@decantr/mcp-server"] } } }
$ npm i -g @decantr/mcp-server && decantr-mcp # Then register the binary in your editor's MCP config
Read Surface the contract and context the AI needs to work
decantr_read_essence

Read the current design spec

decantr_get_scaffold_context

Top-level scaffold context for the whole app

decantr_get_section_context

Scoped context for a specific app section

decantr_get_page_context

Page-scoped context for one route or page id

decantr_get_execution_pack

Read compiled scaffold, page, section, review, or mutation packs

decantr_get_showcase_benchmarks

Inspect shortlist, manifest, and showcase verification metadata

decantr_get_registry_intelligence_summary

Hosted aggregate intelligence coverage without crawling the registry

Reason Resolve registry content into concrete structural specs
decantr_search_registry

Search patterns, archetypes, themes, blueprints, shells

decantr_resolve_pattern

Full pattern details with layout specs

decantr_resolve_archetype

App templates with page maps

decantr_resolve_blueprint

Composed templates with topology, zones, and transitions

decantr_suggest_patterns

Pattern recommendations for any page description

Mutate Write structured changes back into the contract
decantr_create_essence

Generate a design spec from a description

decantr_update_essence

Apply structured updates to DNA or Blueprint

decantr_accept_drift

Resolve violations by accepting, scoping, rejecting, or deferring

decantr_compile_execution_packs

Compile a hosted execution-pack bundle from an essence

Verify Score, audit, and repair generated UI against the contract
decantr_validate

Validate an Essence against the schema

decantr_check_drift

Detect design-spec violations in code changes

decantr_critique

Score generated code on treatments, decorators, motion, a11y, responsive

decantr_audit_project

Schema-backed project audit against packs, guards, and drift

decantr_get_evidence_bundle

Local evidence bundle for AI repair loops and CI artifacts

decantr_get_repair_prompt

Scoped repair prompt with exact finding evidence and rerun commands

decantr_workspace_health

Aggregate health for many attached Decantr projects in a monorepo

decantr_run_health_loop

Run health, evidence, and the next repair prompt in one local loop

decantr_prepare_task_context

Resolve route-local Brownfield or Hybrid authority, local law, visual evidence, and theme inventory before editing

### CLI Commands

Manage your project from the terminal

new <name> --blueprint=X

Scaffold a new project from a blueprint

refresh

Regenerate context files from the essence

add page

Add a new page to a section

remove page

Remove a page from a section

theme switch

Switch to a different theme

verify

Run the local reliability gate for humans, CI, and agents

verify --evidence

Write a privacy-redacted Evidence Bundle for AI repair and CI artifacts

suggest --route --from-code

Rank patterns against route, file, source-code evidence, and accepted local law

magic "prompt"

Scaffold greenfield apps from natural language; attached apps are steered into task context

adopt

Analyze, attach, verify, baseline, and show the Brownfield operating loop

doctor

Explain app/workspace state, adoption lane, stale artifacts, local law, CI wiring, and the ordered next-step queue

task <route>

Prepare route context, authority, local law, evidence, and changed-file impact before an LLM edits code

ci

Run the non-mutating required automation gate with schema-backed artifacts

codify --from-audit

Turn local buttons, cards, forms, themes, evidence, variants, and starter rules into project-owned UI law

search <query>

Search the registry across patterns, themes, blueprints

audit

Full project audit — drift, packs, guard, critique

verify --workspace

Aggregate Project Health across many Decantr projects

export --to figma-tokens

Bridge Decantr tokens into Tokens Studio-compatible JSON

## Get started

Pick a blueprint, scaffold, build. Three steps to a production-quality app.

### Step 1: Pick a blueprint

agent-studio
certified flagship

AI agent ops and eval workspace

registry-platform
certified flagship

Design intelligence registry

observability-platform
certified flagship

Incident and telemetry command center

esports-hq
certified flagship

Matchday operations and VOD review

### Step 2: Scaffold

$ npx @decantr/cli new my-app --blueprint=esports-hq

### Step 3: Build

Paste the generated prompt into Claude Code, Cursor, or any AI coding assistant. The AI reads your context files and builds a production-quality app.

## The AI scores its own work.

`decantr_critique` grades generated code against the essence — treatments, decorators, personality alignment, motion, a11y, responsive. The AI iterates until the score is green.

First pass
42/100

- Treatments
  6 of 18 components use `d-surface`. Raw Tailwind everywhere else.
- Decorators
  0 theme decorators applied. Personality says "luminous glass" — not visible.
- Motion
  No entrance transitions. Essence spec requires staggered reveals.
- Accessibility
  WCAG AA focus rings, skip nav present.

one iteration
After AI re-reads section context
94/100

- Treatments
  17 of 18 components on `d-surface` / `d-interactive`.
- Decorators
  `luminarum-glass` applied to cards. `luminarum-glow` on primary CTAs.
- Motion
  50ms staggered fade-in on every list. Respects `prefers-reduced-motion`.
- Accessibility
  WCAG AA · focus visible · skip nav · keyboard nav verified.

## Already have a project? Adopt Decantr without a rewrite.

Brownfield adoption is a first-class path. Decantr inventories what you have, drafts an observed contract proposal, keeps existing code and styling authoritative, and gives your LLM a repeatable route context before it edits.

1

### Adopt

$ decantr adopt --yes

Runs the adoption workflow: analysis, observed contract proposal, deterministic acceptance or merge, hosted pack hydration when online, Project Health, and baseline. In monorepos, install at the workspace root and pass --project apps/web; app primitives keep that scope instead of falling back to the root. Visual evidence is an optional follow-up when the app is running.

2

### Activate

$ decantr task /feed "add saved recipe actions"

Surfaces route-local context, page and section packs, screenshot references, Brownfield intelligence, theme inventory, accepted local patterns, accepted local rules, changed-file impact, and the active authority lane before the assistant edits code.

3

### Diagnose and gate

$ decantr doctor && decantr ci

Use doctor when the next step is unclear, codify project-owned button/card/form/shell/theme law when you are ready for Hybrid, and run ci as the non-mutating pull-request gate. Accepted local-rule findings show up in CI with file and line evidence. Setup, task paths, health prompts, refresh summaries, token exports, custom themes, and suggestions remain app-scoped in monorepos.

## Layer in what you need, when you need it.

Hybrid lets an attached app adopt selected Decantr or project-owned authority without handing Decantr the whole source tree. Start with local law, map hosted ideas into your own components, then tighten verification only where the team agrees.

### Codify local law

$ decantr codify --from-audit --style-bridge

Turn observed buttons, cards, forms, shells, theme variants, source evidence, confidence tiers, and token/class mappings into project-owned law before enforcing them. Suggest and CI surface those accepted laws as active authority.

### See the active lane

$ decantr doctor

Doctor says whether the app is contract-only, Hybrid local law, style bridge, Decantr CSS, or composition mode.

### Activate route context

$ decantr task /feed "standardize cards"

Task context includes source authority, style authority, active laws, style bridge mappings, and runtime boundary warnings before the LLM edits.

### Map hosted ideas

$ decantr codify --map-pattern hero

Bring registry guidance into local law as advisory context first. Add project-owned components, token/class recipes, variants, and exceptions before treating it as enforceable.

## 225+ patterns. 30+ themes. Curated blueprint sets.

Browse Featured, Certified, All, and Labs blueprint cuts without exposing internal maintainer labels — or publish your own patterns, themes, and blueprints for others to use.

225+
Patterns
Browse →
30+
Themes
Browse →
40+
Blueprints
Browse →
200+
Archetypes
Browse →
Browse the Registry → Read the Public API Read Project Health

## Open source. MIT licensed.

Eight packages, one mission: make AI-generated UI reliable enough to govern.

Foundation
@decantr/essence-spec

Schema, validator, guard rules, and TypeScript types for the Essence format

v2.0.1
@decantr/registry

Content resolver and discovery helpers for patterns, archetypes, themes, blueprints, and shells

v2.2.0
@decantr/css

Framework-agnostic CSS atoms runtime for layout utilities

v2.0.0
@decantr/core

Design Pipeline IR engine -- the brain behind intent-to-composition

v2.1.0
@decantr/telemetry

Privacy-preserving event contracts, clients, and analytics sinks

v2.2.1
Delivery
@decantr/cli

Workflow commands, project scaffolding, Brownfield activation, Hybrid authority lanes, doctor, CI, local law, style bridges, visual evidence, baselines, workspace health, and registry sync

v2.13.1
@decantr/mcp-server

MCP server exposing design intelligence and reliability tools to AI assistants, including task-time Brownfield/Hybrid context with authority, local law, style bridges, and change impact

v2.5.0
@decantr/verifier

Shared audit, critique, source-grounded interaction evidence, Evidence Bundle, CI report schema with style bridge summaries, and Project Health engine

v2.5.1

Security reviews should inspect the installed npm surface, not internal release scripts or showcase fixtures. See the security and permissions matrix for filesystem, network, process, telemetry, hosted upload, and MCP write-tool behavior.

## Works with your stack

Patterns are framework-agnostic. Your AI assistant writes the code in whatever you're already using.

AI assistants
Claude Code MCP · tested
Cursor MCP · tested
Windsurf MCP · tested
Any MCP client stdio · compatible
Frameworks
React + Vite starter adapter
Next.js starter adapter
Native HTML/CSS starter adapter
Vue starter adapter
SvelteKit starter adapter
Angular starter adapter
Solid starter adapter
Styling
CSS tokens generated per theme
@decantr/css atoms framework-agnostic
Tailwind coexists

runnable adapter · generic-web contract-only fallback — your AI writes the runtime

## Stop generating UI slop.

Add Decantr to your AI assistant in 30 seconds.

Get Started