Skip to content

Use with AI agents

A coding agent that can’t see your design system will invent one: a new button, a hex colour, an import that doesn’t exist. The SuperDuper CLI lets it look up the real components and tokens first, and checks the result afterwards.

@superduperui/cli 2.0.0-rc.3. MIT licence. Needs Node 22.12 or later.

Why

Agents are good at following rules they can read and bad at remembering rules they can’t. The CLI puts the system where the agent is working. It answers in fixed JSON or short text, so the agent spends few tokens and doesn’t have to guess.

It carries its own snapshot of the component manifest, the docs, the token list and the registry index, so the answers always match the version you installed. Pro components are included in lookups and in check.

Install

Run it with npx, or add it to the project so the whole team and your CI use the same version.

npx @superduperui/cli component Button
# or
npm install --save-dev @superduperui/cli
npx superduper check

Pro components install from the shadcn registry with the licence key that comes with a paid plan. Lookups and check cover them without a key. The plans are on the design systems page.

Commands

The superduper commands and what each gives you
CommandWhat it gives you
superduper search <query>One ranked list across components, tokens, registry blocks and docs.
superduper component <Name>Purpose, when to use it and when not, import lines, tier, required props and screen reader output. --props adds the prop table; --list lists every component.
superduper tokens [name]Token classes with their values, and the text-on-surface pairs. Look one up by class, token name or CSS variable.
superduper docs <topic>A component doc, tokens, or rules (the rules for agents), as markdown.
superduper check [paths...]A static check of your code. Exits 0 when clean and 1 on errors.
superduper theme generate --accent <hex>CSS that rebrands the system from one accent colour in all five themes, with every text pair re-checked for contrast. --name names the theme; --out writes a file.
superduper manifestThe CLI’s own capability manifest: commands, flags, response types, exit codes and error codes.
superduper mcpA stdio MCP server with search, component, tokens, docs, check and theme_generate tools.

Add --json for the JSON envelope, --dense for short text, and --detail full for product rules, keyboard steps and component tokens.

Look things up

Search for a need, and the answer names the component and the command to read more.

$ superduper search "icon button" --limit 3
component IconButton            free  An icon-only action with a required name, shown as a tooltip on hover and keyboard focus.
                                superduper component IconButton
doc       tokens                      TOKENS.md: every token and the surfaces text may sit on
                                superduper docs tokens
component Button                free  Triggers an action. Text label always; use IconButton for icon-only actions.
                                superduper component Button

Then read the component before using it. This is what an agent gets, with the import line, the required props and when not to use it.

$ superduper component Button --dense
Button (free, tier 1): Triggers an action. Text label always; use IconButton for icon-only actions.
registry: import { Button, buttonVariants } from "@/components/ui/button"
npm: import { Button, buttonVariants } from "@superduperui/react"
required: children
use: Submitting or saving a form; Starting a task in the current view; Opening a Dialog
avoid: Navigating to another page: use a link; Icon-only actions: use IconButton; Toggling a setting: use Switch
screen reader: "Save changes, button"; loading adds "busy"
item: @superduperui/button doc: docs/components/button.md

Tokens work the same way. Give it a class, a token name or a CSS variable.

$ superduper tokens bg-surface
color.bg.canvas  (colour, semantic)
  classes: bg-surface
  variable: var(--sd-color-bg-canvas)
  value: #ffffff
  Page background.

Check your code

check reads your .tsx, .jsx, .ts and .css files and reports what the system already covers. It looks for rebuilt components, invented imports, missing required props and colours, shadows and lengths that aren’t tokens. Every finding comes with the fix. With no paths it checks src/, app/ and components/, and skips components/ui/.

Here is a file with a hand-built button and two colours from outside the system.

export function Actions() {
  return (
    <div>
      <button className="bg-blue-600 text-white px-4 py-2" onClick={() => {}}>
        Save
      </button>
    </div>
  );
}
$ superduper check src
src/Toolbar.tsx
     4  error    off-system-colour  bg-blue-600 is a colour from outside the system.
        fix: Use bg-action-primary, the nearest semantic token.
     4  error    off-system-colour  text-white is a colour from outside the system.
        fix: Use text-fg-inverse, the nearest semantic token.
     4  error    reinvented-intrinsic  <button> rebuilds a button, which the system has as <Button>.
        fix: Use <Button>: import { Button } from "@/components/ui/button";

1 file checked: 3 errors, 0 warnings. Failed.

It exits 1 when there are errors, and also on warnings with --strict. That makes it a CI step. In GitHub Actions:

- name: Check against the design system
  run: npx @superduperui/cli check --strict

Tell your agent to run it before it finishes and fix every error. superduper docs rules prints the rules for agents as markdown, ready to paste into your CLAUDE.md or AGENTS.md.

MCP server

superduper mcp speaks MCP over stdio. It has the tools search, component, tokens, docs, check and theme_generate. They take the same arguments as the commands and return the same JSON. The check tool reads only inside the folder the server runs in.

Claude Code

claude mcp add superduper -- npx -y @superduperui/cli mcp

Cursor

Add this to .cursor/mcp.json.

{
  "mcpServers": {
    "superduper": { "command": "npx", "args": ["-y", "@superduperui/cli", "mcp"] }
  }
}

JSON contract

Every command takes --json. A success has type (the command name), data and meta, and exits 0. A check that finds errors exits 1 with the same shape.

{ "apiVersion": "1", "type": "component", "data": { "name": "Button", "tier": "free" }, "meta": { "system": "SuperDuper Design System", "version": "2.0.0-rc.3" } }

An error has a stable code and often suggestions, and exits 2.

{
  "apiVersion": "1",
  "error": "There is no component \"Buton\".",
  "code": "ERR_UNKNOWN_COMPONENT",
  "suggestions": ["Button", "Icon"]
}

superduper manifest --json describes every command, flag, response shape and code, so an agent can read the contract instead of guessing it. The codes:

Error codes
CodeMeaning
ERR_USAGEMissing or extra arguments, an unknown flag, or a flag value that is not allowed.
ERR_UNKNOWN_COMMANDNo such command. Suggestions name the nearest.
ERR_UNKNOWN_COMPONENTNo component by that name or alias. Suggestions name the nearest components.
ERR_UNKNOWN_TOKENNo token by that class, name or variable. Suggestions name the nearest tokens.
ERR_UNKNOWN_TOPICNo docs topic by that name. Suggestions name the nearest topics.
ERR_NO_FILEScheck found no .tsx, .jsx, .ts or .css files to check.
ERR_BAD_SYSTEMThe --system file is not a readable system manifest.
ERR_ACCENT_UNSAFEtheme generate can’t keep the contrast rules with this accent. Suggestions name the nearest accents that pass.
ERR_PATH_OUTSIDE_PROJECTMCP only: a check path leads outside the folder the server runs in.
ERR_INTERNALAn unexpected failure inside the CLI.

The package is on npm. To see what it checks against, browse the components and tokens.