Gantry

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

Gantry scans your React 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 — atoms / molecules / organisms, with search, props, and a description for each.
• 👀 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 with no reload).
• 🎚 Variant axes — pick one option per independent axis (e.g. size × shape × tone) and preview any combination — not a flat list of pre-baked combos.
• 🎨 Customize colors — edit a component's real colors with a picker, eyedropper, opacity, and a component palette; changes preview live everywhere.
• 🪙 Design-token manager — scans CSS custom properties (:root) and presents them as a structured, layered table:
  • Primitives / Semantic / Component layers, switchable.
  • Aliases (var(--…)) are resolved to their real color for the swatch.
  • Edit a token's value and write it back to source (your CSS), picked up via HMR.
• 🤖 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 include your live component catalog, design-token catalog by layer, and opinionated conventions (composition-first atomic design, tokens-only styling, and API/token restraint — fewer, better variants).
• 🎛 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. This creates:

   • gantry.config.json
   • src/components/{atoms,molecules,organisms}/
   • src/gantry/overrides.generated.json

3. Add a component:

   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, and the AI rules are written. That's it — Gantry re-syncs automatically when files change.

Configuration — gantry.config.json

{
  "framework": "react",
  "componentsDir": "./src/components",
  "rules": {
    "forbidRawElements": ["div", "button", "input", "a", "span"],
    "forbidInlineStyles": true
  }
}

Define design tokens as CSS custom properties under :root in your global stylesheet (e.g. src/index.css) and Gantry will pick them up.

How it works

VS Code / Cursor
├── Extension host (Node)
│   ├── scanner          reads components/ + props (ts-morph) and CSS tokens
│   ├── generator        writes .cursor/rules/gantry.mdc + .gantry/gantry-rules.md + CLAUDE.md
│   ├── preview server   Vite (or esbuild fallback) on a free port
│   └── webview provider wires the panel ↔ host
└── Webview (React panel)
    ├── component tree + variant axes + properties
    ├── color customizer + 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 React + TypeScript project. Vite gives the best preview fidelity (Tailwind/PostCSS); other toolchains use the esbuild fallback (plain CSS / CSS Modules supported; Tailwind utilities are not processed in fallback mode).
• Node.js 18+.

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:

License

MIT