Gantry

A visual component & design-token manager for AI-powered front-end development — inside VS Code / Cursor.

Gantry scans your React, Vue or Svelte component library and design tokens, gives you a live visual browser in the sidebar, and keeps your AI assistant's rules up to date automatically — for both Cursor and Claude Code — so the AI always builds UI from your real design system instead of inventing markup.

Why

Design systems drift. The AI in your editor doesn't know which components and tokens exist, so it reinvents buttons, hardcodes #hex colors, and ignores your conventions. Gantry fixes the loop:

You add a component or token → Gantry notices → it regenerates the AI rules → the AI builds from your system.

Features

• 🧩 Component browser — grouped by architecture layer (atoms / molecules / organisms by default, or whatever layers you configure), with search, props, and a description for each. Detects components written as React.FC, arrow functions, forwardRef/memo, or default exports, in folder or flat-file layouts.
• 👀 Live preview — renders the selected component through your project's own toolchain.
  • Uses your project's Vite dev server (Tailwind, CSS, path aliases, all just work).
  • No Vite? A built-in esbuild fallback bundles and serves the preview, so Next.js / webpack / CRA projects still get a preview.
  • Robust transport (dynamic port, auto-restart, remote/Codespaces support, postMessage updates) and a reload on sync so style changes appear without restarting the editor.
  • Components that render nothing on their own (layout primitives like Row / Stack / Grid) show a "Preview unavailable" placard explaining why, instead of a blank canvas.
• 🎚 Variant axes — pick one option per independent axis (e.g. size × shape × tone) and preview any combination. Union types are resolved through the TypeScript checker, so named aliases (type Variant = 'a' | 'b') and imported unions expand into axes too. Already have Storybook? Gantry imports your *.stories.tsx (CSF3) as curated preview states automatically — no migration.
• 🩺 Health & drift — a score bar above the tabs grades your design system 0–100 and lists drift: layer-import violations & dependency cycles, hardcoded colors, inline styles, raw HTML in composing layers, low-contrast color token pairs (WCAG AA), and unused / duplicate tokens — each jumps to file:line. One click copies a fix plan for your AI assistant. A composition-coverage metric tracks how much UI is built from the catalog vs raw HTML.
• 🪙 Design-token manager — scans tokens from three sources and presents them as a structured, layered table:
  • CSS custom properties (:root / html / :host) — editable; write a new value back to source, picked up via HMR.
  • DTCG / Tokens Studio JSON (the Figma Tokens export format) — nested groups flatten to --group-name, and {alias} references resolve to their real value for the swatch. Editable — edits write back to the token's $value / value.
  • Tailwind theme — both the v3 JS/TS config (tailwind.config.{js,ts}) and the v4 CSS-first @theme { … } block — colors, spacing, radii, type scale, shadows… surfaced with their utility-class usage hint (bg-primary-500). The v4 @theme values are editable and write back to source.
  • Primitives / Semantic / Component layers, switchable; aliases resolved for the swatch.
• 🤖 AI rules, always current — on every sync Gantry regenerates:
  • .cursor/rules/gantry.mdc for Cursor.
  • .gantry/gantry-rules.md + a managed import block in CLAUDE.md for Claude Code.
  • Both lead with a live health summary and include your component catalog (with real usage examples), the design-token catalog by layer, and opinionated conventions (composition-first layered design, tokens-only styling, API/token restraint).
• 🔌 MCP server — lets the assistant query your design system on demand instead of loading one big rules file: tools find_component, get_component, list_components, list_layers, list_tokens, get_health, and screenshot_component — which renders a component (any named variant) headlessly through your real build pipeline and returns a PNG the assistant can see, so it can verify UI visually before reusing or after building. The same data is also exposed as resources (gantry://catalog, gantry://tokens, gantry://health, gantry://layers, gantry://component/{name}) the assistant can pull into context directly. Auto-registered in .cursor/mcp.json and .mcp.json on activation (idempotent).
• ⌨️ CLI / CI gate — the same scan, health/drift analysis, rules generation and screenshots run headlessly via the gantry command, so the design system is enforced in CI, not just one developer's editor:
  • gantry init — infers a gantry.config.json from an existing project (component dir + architecture), so you can adopt Gantry without restructuring first.
  • gantry check — fails the build past drift thresholds (--min-score, --max-errors, --max-warnings), with --json for tooling.
  • gantry fix — rewrites hardcoded literals to the matching design token: colors (#e11d48 / rgb(225,29,72) → var(--color-danger)) and spacing / radius / sizing values in inline styles & CSS (padding: '1rem' → padding: 'var(--space-4)', property-gated and exact-value matched); --dry-run previews the changes. Also available in-editor as Gantry: Fix Hardcoded Colors.
  • gantry sync — regenerates the Cursor/Claude rules + .gantry/catalog.json without opening an editor.
  • gantry screenshot <Name> [--variant …] — renders a component variant to a PNG.
• ➕ Scaffolding — Gantry: New Component creates a convention-following component folder in the layer you pick, then syncs.
• 🎛 Native UI — Material Design 3 Expressive, neutral surfaces with a purple accent, adapts to your VS Code light/dark theme.

Quick start

1. Install the extension (from a .vsix you build, or the Marketplace once published).

2. Open your React project and run Gantry: Initialize Project from the command palette. It asks you to pick an architecture — Atomic (atoms/molecules/organisms, the default), Primitives → Components → Features, Flat, or Custom — then creates:

   • gantry.config.json (with your chosen layers)
   • the matching folders under src/components/ (e.g. atoms/, molecules/, organisms/ for Atomic)

3. Add a component (or run Gantry: New Component to scaffold one):

   src/components/atoms/Button/
     Button.tsx          # implementation
     Button.types.ts     # exported ButtonProps interface
     index.ts            # re-export
   

4. Open the Gantry view in the activity bar. Your component appears, renders live, the AI rules are written, and the MCP server is registered for Cursor / Claude Code (reload the window once to connect). That's it — Gantry re-syncs automatically when files change.

Configuration — gantry.config.json

{
  "framework": "react",
  "componentsDir": "./src/components",
  "tiers": {
    "atom": ["atoms"],
    "molecule": ["molecules"],
    "organism": ["organisms"]
  },
  "rules": {
    "forbidRawElements": ["div", "button", "input", "a", "span"],
    "forbidInlineStyles": true
  },
  "tokens": { "sources": ["css", "dtcg", "tailwind"] },
  "mcp": { "autoSetup": true }
}

Tokens are scanned from your CSS custom properties (under :root in e.g. src/index.css), any DTCG / Tokens Studio JSON, and your Tailwind theme — merged into one catalog (CSS wins on name collisions, since it's the editable source).

Architecture layers

Gantry models your component architecture as an ordered list of layers (lowest → highest), each declaring which layers it may import from. The invariant Gantry enforces is: a component imports only from its layer's allowed layers, and the import graph stays acyclic. The classic atomic model (atom → molecule → organism) is just the default preset — zero-config projects behave exactly as before.

Define your own layers when atomic doesn't fit (e.g. primitives → components → features):

{
  "componentsDir": "./src/components",
  "layers": [
    { "name": "primitive", "folders": ["primitives"] },
    { "name": "component", "folders": ["components"], "canImport": ["primitive", "component"] },
    { "name": "feature",   "folders": ["features"],   "canImport": ["primitive", "component", "feature"] }
  ]
}

Per-layer fields: name, folders (folder names under componentsDir), canImport (allowed layer names — default: every strictly-lower layer, so omitting it gives classic layering), primitive (leaf that may render raw HTML — default: the lowest layer), and composes (must be built from catalog components, driving raw-element drift + coverage — default: !primitive).

Flat-library mode. If none of the configured layer folders exist (shadcn/Radix/MUI-style flat libraries), Gantry infers layers from the import graph instead: a component that imports no other catalog component is a primitive; one that composes others is a component. The only hard rule then is no circular dependencies.

CLI & CI

Gantry ships a gantry binary that runs the same engine headlessly — ideal for a CI gate that keeps the design system healthy across the whole team, not just in one editor.

# Fail the build if the design system regresses
npx gantry check --min-score 85 --max-errors 0

# Regenerate AI rules + catalog in a pre-commit hook or CI step
npx gantry sync

# Render a component variant to a PNG
npx gantry screenshot Button --variant secondary --out button.png

check exits non-zero when a threshold is crossed (--min-score, --max-errors, --max-warnings) and prints the offending drift with file:line; pass --json for machine-readable output. All commands accept --cwd <dir> to target another project root.

Example GitHub Actions step:

- run: npx gantry check --min-score 85 --max-errors 0

How it works

VS Code / Cursor
├── Extension host (Node)
│   ├── scanner          reads components/ + props (ts-morph), CSS tokens, usage & coverage
│   ├── driftScanner     detects layer/cycle/token/markup drift → Health
│   ├── generator        writes .cursor/rules/gantry.mdc + .gantry/gantry-rules.md + CLAUDE.md
│   ├── catalog          writes .gantry/catalog.json + registers the MCP config
│   ├── preview server   Vite (or esbuild fallback) on a free port
│   └── webview provider wires the panel ↔ host
├── MCP server (separate Node process)
│   ├── serves the catalog/tokens/health to Cursor & Claude Code on demand
│   └── screenshot_component → drives a headless browser over the preview server → PNG
├── CLI (gantry)        headless check / sync / screenshot for CI & scripts
└── Webview (React panel)
    ├── component tree + variant axes + properties
    ├── Health bar + token manager
    └── <iframe> live preview (postMessage transport)

The preview writes a tiny app into __gantry_preview__/ and renders your component there using your project's real build pipeline.

Requirements

• VS Code ^1.85.0 (or Cursor).
• A TypeScript project in React, Vue or Svelte — scanned for the catalog, props, layers, drift, AI rules and MCP. Vite gives the best preview fidelity (Tailwind/PostCSS). Vue/Svelte live preview requires Vite (their SFCs compile through the project's @vitejs/plugin-vue / @sveltejs/vite-plugin-svelte); the esbuild fallback is React-only (plain CSS / CSS Modules supported; Tailwind utilities are not processed in fallback mode).
• Node.js 18+.
• Screenshots (screenshot_component / gantry screenshot) need a Chromium-family browser already installed (Chrome, Edge, Brave, or Chromium) — Gantry drives it via puppeteer-core and does not download one. Set GANTRY_CHROME to point at a specific executable if auto-detection misses it.

Development

git clone https://github.com/oleksiikoa/gantry.git
cd gantry
npm install
npm run build        # builds the extension host (esbuild) + webview (vite)
# Press F5 in VS Code to launch the Extension Development Host

Useful scripts:

The scanner is framework-agnostic and delegates component detection + prop/import extraction to a FrameworkAdapter (src/core/frameworks/). React, Vue (.vue SFCs — defineProps, withDefaults, runtime/array forms, Options API) and Svelte (.svelte — export let props and Svelte 5 $props() runes) adapters are implemented; set framework in gantry.config.json. The catalog, props, layers, drift, AI rules, MCP and live preview work for all three — Vue/Svelte render through the project's own Vite (the preview config merges your vite.config, so your @vitejs/plugin-vue / @sveltejs/vite-plugin-svelte and the installed runtime are reused). Without Vite, preview falls back to esbuild, which is React-only.

License

PolyForm Strict 1.0.0 — free to use for any purpose, including commercial. You may not copy, distribute, or modify the software. Distribution or modification rights require a separate license.