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 checkPro 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
| Command | What 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 manifest | The CLI’s own capability manifest: commands, flags, response types, exit codes and error codes. |
superduper mcp | A 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 ButtonThen 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.mdTokens 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 --strictTell 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 mcpCursor
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:
| Code | Meaning |
|---|---|
ERR_USAGE | Missing or extra arguments, an unknown flag, or a flag value that is not allowed. |
ERR_UNKNOWN_COMMAND | No such command. Suggestions name the nearest. |
ERR_UNKNOWN_COMPONENT | No component by that name or alias. Suggestions name the nearest components. |
ERR_UNKNOWN_TOKEN | No token by that class, name or variable. Suggestions name the nearest tokens. |
ERR_UNKNOWN_TOPIC | No docs topic by that name. Suggestions name the nearest topics. |
ERR_NO_FILES | check found no .tsx, .jsx, .ts or .css files to check. |
ERR_BAD_SYSTEM | The --system file is not a readable system manifest. |
ERR_ACCENT_UNSAFE | theme generate can’t keep the contrast rules with this accent. Suggestions name the nearest accents that pass. |
ERR_PATH_OUTSIDE_PROJECT | MCP only: a check path leads outside the folder the server runs in. |
ERR_INTERNAL | An unexpected failure inside the CLI. |
The package is on npm. To see what it checks against, browse the components and tokens.