# Decantr

> Evidence-backed design intelligence, governance, and verification for AI-generated UI. Decantr is the contract layer between product intent and AI-generated implementation — giving coding assistants structured design inputs, registry-backed UI knowledge, scoped context files, health evidence, and repair prompts so they build coherent product surfaces instead of improvising screen by screen.

Think of Decantr as **OpenAPI for AI-generated UI**: the model still writes the code, but Decantr defines the shape, vocabulary, and governance around it. Decantr separates design governance into two layers — **DNA** (durable visual axioms: theme, spacing, motion, accessibility, personality) and **Blueprint** (product topology: sections, page routes, shells, layouts, features). Strict where it should be strict, flexible where it should be flexible.

## Docs

- [Homepage](https://decantr.ai/): What Decantr is and why AI-generated UI needs a contract layer.
- [Sitemap](https://decantr.ai/sitemap.xml): Crawl inventory for public Decantr docs, schemas, references, and release notes.
- [Design contract basics](https://decantr.ai/guides/design-contract-basics.md): Short explanation of Essence, DNA, Blueprint, context files, and the Decantr loop.
- [Existing app adoption](https://decantr.ai/guides/existing-apps.md): Brownfield attach path for adding Decantr to an existing app without rewriting the runtime.
- [Monorepos](https://decantr.ai/guides/monorepos.md): Root install, app-scoped attach, workspace health, pinned CI, and what to commit in monorepos.
- [Project Health CI](https://decantr.ai/guides/project-health-ci.md): Installing and running the Decantr CI gate locally, in GitHub Actions, or in generic internal pipelines.
- [AI assistant setup](https://decantr.ai/guides/ai-assistant-setup.md): Using Decantr with MCP-compatible assistants and file-based CLI context.
- [Registry publishing](https://decantr.ai/guides/registry-content-publishing.md): Registry portal, official content source, community publishing, and Content Health.
- [Workflow model](https://decantr.ai/reference/workflow-model.md): Explicit workflow/adoption policy for greenfield blueprint, greenfield contract-only, brownfield attach, Hybrid local law/style bridge/Decantr CSS/composition, adapters, monorepos, and offline mode.
- [Project Health](https://decantr.ai/reference/project-health.md): Local reliability layer, Evidence Bundle, workspace health, browser verification, design-token checks, Studio, and GitHub artifact workflow.
- [Command surface](https://decantr.ai/reference/command-surface.md): Current CLI command audit and consolidation decisions.
- [Security and permissions](https://decantr.ai/reference/security-permissions.md): Installed npm package permission matrix, telemetry defaults, MCP write boundaries, hosted upload posture, and scanner interpretation notes.
- Brownfield attach is proposal-driven but workflow-first: run `decantr adopt --yes` for the paved path, or `decantr adopt --project apps/web --yes` from a monorepo root. Then run `decantr doctor --project apps/web` when the next step is unclear and `decantr ci --project apps/web --fail-on error` in automation. `doctor` prints an ordered next-step queue covering pinning, local-law codification, CI setup, task context, verification, and automation when those steps apply. `adopt` orchestrates `analyze`, proposal acceptance/merge, online hosted pack hydration, Project Health, baseline save, and optional CI; use `--no-packs` or offline mode to defer hydration. In contract-only Brownfield, missing hosted packs are optional context unless an existing `pack-manifest.json` references missing files. The primitives remain available for debugging: `decantr analyze`, review `.decantr/brownfield-report.md`, `.decantr/doctrine-map.json`, `.decantr/brownfield-intelligence.json`, `.decantr/theme-inventory.json`, and `.decantr/enrichment-backlog.md`, then accept with `decantr init --existing --accept-proposal` or merge with `--merge-proposal`. In brownfield, Decantr is the reconciled contract layer and existing docs/rules are ranked cited evidence, not material to overwrite by default. Theme variants are observed in local inventory, not promoted into Essence V4.
- For app-scoped monorepos, pass `--project <app>` to `doctor`, `check`, `verify`, `ci`, `task`, and `codify`. When hydrating hosted packs manually, pass the app essence path: `decantr registry compile-packs apps/web/decantr.essence.json --write-context`; the context bundle is written beside that essence file. Health remediation prompts and CI recommendations stay project-scoped from the monorepo root, prompt read targets should include the app prefix (for example `apps/web/DECANTR.md`, not root `DECANTR.md`), and runtime repair prompts should use root-safe app build commands such as `pnpm --dir apps/web build`.
- CI is a first-class workflow command: `decantr ci init --project apps/web` writes a root GitHub workflow that runs the pinned local package-manager command, such as `pnpm exec decantr ci --project apps/web`, not `@latest`. If the CLI is not pinned yet, `ci init` prints the exact install command. Use `decantr ci init --provider generic --project apps/web` for Jenkins, Please, Buildkite, GitLab, Azure DevOps, or internal deployment systems.
- For route work, MCP agents should call `decantr_prepare_task_context` with a route and task before editing. CLI-only agents should use `decantr task <route> "<task>"`, which surfaces generated page/section context, screenshot references, `.decantr/local-patterns.json`, `.decantr/rules.json`, `.decantr/style-bridge.json`, changed files, impacted routes, and the active authority lane when present. In monorepos, task/read paths must be openable from the workspace root. `decantr suggest` supports `--route`, `--file`, `--from-code`, and `--project`; accepted project-owned local patterns and style bridge mappings should be considered before registry suggestions, and `--from-code` can derive a query from route/file context. From an app root, `decantr suggest "button" --from-code --file src/App.tsx` should discover local law without `--project`; from a monorepo root, keep `--project <app>` on app primitives including `health`, `status`, `add`, `remove`, `theme`, `export`, `suggest`, `magic`, `rules`, and `telemetry`; `magic` against an attached app should steer to `task`, not ask the user to remove the essence. For observed Brownfield sections, `decantr add page app/foo --route /foo --project apps/web` and `decantr add feature saved-recipes --section app --project apps/web` may resolve the `app` alias to the single primary section, such as `observed-primary`.
- Project-owned Brownfield UI law is local and explicit: `decantr codify --from-audit --style-bridge` writes `.decantr/local-patterns.proposal.json`, `.decantr/rules.proposal.json`, and `.decantr/style-bridge.proposal.json`; source-derived proposals include evidence, confidence tiers, and likely variants for button/card/form/theme families. `decantr codify --map-pattern <slug>` maps a hosted or bundled registry pattern into advisory local law without changing source; fill project-owned component paths, token/class recipes, variants, and exceptions before accepting it. After review, `decantr codify --accept` promotes accepted local law and/or style bridge artifacts, activating Hybrid local law or Hybrid style bridge. `decantr codify --style-bridge` remains available when local law already exists and only the token/class bridge is missing. `decantr verify --brownfield --local-patterns` requires the accepted pack and scans accepted local rules. `decantr ci` should also print accepted local-rule findings with file/line evidence, style bridge status when present, distinguish enforceable local rules from advisory bridge/pattern mappings, and only block warning-level findings when `--fail-on warn` is used. Deeper deterministic enforcement for framework-specific constraints still belongs in ESLint/Biome/tests.
- Interaction evidence is production-UI scoped. Decantr should not satisfy or blame UI interaction guards from API route handlers, tests, stories, fixtures, or mocks; those files are useful project context, but not proof that a route implements the declared UI behavior.
- Browser evidence is local-only: `decantr verify --base-url <url> --evidence` writes screenshots under `.decantr/evidence/screenshots/`, `.decantr/evidence/visual-manifest.json`, and `.decantr/evidence/latest.json`. `decantr verify --save-baseline` and `--since-baseline` provide continuity across AI sessions.
- [Public API reference](https://decantr.ai/reference/registry-public-api.html): Registry endpoints, pack compilation, critique, audit.
- [Package support matrix](https://decantr.ai/reference/package-support-matrix.md): Which packages are stable, internal, or experimental.
- [Security permissions](https://decantr.ai/reference/security-permissions.md): Use this when answering enterprise/security questions about what Decantr reads, writes, uploads, or executes.
- [Release stewardship](https://github.com/decantr-ai/decantr/blob/main/docs/runbooks/release-stewardship.md): Git + npm release closeout policy. A release is not done until `pnpm release:verify` and `pnpm release:closeout` pass; Discord announcements are a post-closeout `pnpm release:announce` dispatch through `community-ops`.

## Packages

- [@decantr/cli](https://www.npmjs.com/package/@decantr/cli): Workflow commands (`setup`, `adopt`, `doctor`, `task`, `verify`, `ci`, `codify`), workflow/adoption policy, scaffold or attach Decantr, report Hybrid authority lanes, codify Brownfield local law and style bridges, write Evidence Bundles, aggregate workspace health, manage essence, search registry content.
- [@decantr/mcp-server](https://www.npmjs.com/package/@decantr/mcp-server): MCP server exposing design intelligence, Brownfield/Hybrid task context with authority, local law, style bridge mappings, change impact, Evidence Bundles, workspace health, and repair prompts to Claude, Cursor, Windsurf, VS Code, Zed, Continue.dev. Listed at `io.github.decantr-ai/mcp-server` in the official MCP Registry.
- [@decantr/essence-spec](https://www.npmjs.com/package/@decantr/essence-spec): Essence schemas, validation, migration, TypeScript types.
- [@decantr/registry](https://www.npmjs.com/package/@decantr/registry): Registry contracts, content utilities, API client surfaces.
- [@decantr/core](https://www.npmjs.com/package/@decantr/core): Execution-pack compiler primitives.
- [@decantr/verifier](https://www.npmjs.com/package/@decantr/verifier): Audit, critique, contract assertion, Evidence Bundle, and report-schema engine.
- [@decantr/css](https://www.npmjs.com/package/@decantr/css): Framework-agnostic CSS atom runtime.

## Registry

The registry is open — both the Decantr team (under the `@official` namespace) and the community can publish patterns, archetypes, themes, blueprints, and shells. This makes Decantr a platform, not just a tool: every published contribution extends the design vocabulary available to every AI coding assistant that uses Decantr.

Blueprint discovery is curated through public sets: `All`, `Featured`, `Certified`, and opt-in `Labs`. Internally richer portfolio metadata can fold overlapping legacy slugs out of browse/search while keeping direct slug access intact.

- [Registry portal](https://registry.decantr.ai/): Browse and publish patterns, archetypes, themes, blueprints, shells. Community contributions live alongside `@official` content.
- [Registry sitemap](https://registry.decantr.ai/sitemap.xml): Crawl inventory for public registry browse and detail pages.
- [Registry llms.txt](https://registry.decantr.ai/llms.txt): Machine-readable registry summary for AI search and agentic retrieval.
- [Registry API](https://api.decantr.ai/v1/): Hosted API for content resolution, pack compilation, critique, audit. Public read access requires no API key.
- [decantr-ai/decantr-content](https://github.com/decantr-ai/decantr-content): Source of truth for all `@official` namespace content — patterns, archetypes, themes, blueprints, shells. PRs to this repo auto-sync to the live registry.
- [Publish your own content](https://registry.decantr.ai/): Sign in to the registry portal to publish under your own namespace.

## Concepts

- [Essence spec](https://decantr.ai/schemas/): The durable contract — theme, sections, routes, features, guard rules.
- [Design Pipeline](https://github.com/decantr-ai/decantr/blob/main/README.md#the-model): Seven stages — Intent, Interpret, Decompose, Specify, Compose, Generate, Guard.
- [Guard rules](https://github.com/decantr-ai/decantr/blob/main/CLAUDE.md#guard-rules): DNA guards (style, density, accessibility, theme-mode compatibility) and Blueprint guards (structure, layout, pattern existence).
- [CSS scaffolding guide](https://decantr.ai/css-scaffolding-guide.md): Full CSS implementation spec covering `@layer` structure, theme scoping, and variable naming.

## Repositories

- [decantr-ai/decantr](https://github.com/decantr-ai/decantr): Monorepo — CLI, MCP server, packages, apps.
- [decantr-ai/decantr-content](https://github.com/decantr-ai/decantr-content): Content registry — patterns, archetypes, themes, blueprints, shells.

## Optional

- [Published schemas](https://decantr.ai/schemas/): JSON Schema files for essence, patterns, archetypes, themes, blueprints, shells.
- [Showcase apps](https://github.com/decantr-ai/decantr/tree/main/apps/showcase): Audited benchmark corpus demonstrating Decantr-generated scaffolds.
- [MCP Registry listing](https://registry.modelcontextprotocol.io/v0.1/servers?search=decantr): Decantr's entry in the official Model Context Protocol Registry.
