Tokens and React components on Base UI and StyleX, installed as source through a shadcn registry.

Ultima is a design system for React projects that compile StyleX. The shadcn CLI copies each component's source into your project, and you own it from there. Dark is the default color mode. Light is a full peer: every semantic token, contrast check, and demo exists in both.

Ultima has no version number. The registry serves the latest build, and every installed file carries a stamp the ultima-design CLI reads for drift.

Install

init sets up a new or existing Vite or Next.js App Router project in one reviewed step. It wires the StyleX compiler, installs the setup item with Button, Card and Dialog, and puts a small preview on the page for you to replace.

npx ultima-design@latest init my-app --framework vite
npx ultima-design@latest init my-next-app --framework next --layout src
npx ultima-design@latest init .

Ultima is plug-and-play for the supported combinations. A fresh agent given only ultima.systems and this command built a themed first screen in about five minutes. It passed ultima-design check, StyleX lint, the raw-paint scan and a production build in both modes and system mode, with no step outside the printed guidance and no undocumented choice (evidence).

Choose a theme in Theme Studio, then follow the install walkthrough: install the registry item, apply the export after StyleX, and check a production build in both modes and system mode. A fresh project can keep Neutral. Preserve an existing brand in an authorized custom draft; review local design guidance and the active theme before replacing files.

For a project init does not cover, the setup items do the same by hand.

Vite:

npx [email protected] add https://ultima.systems/r/setup-vite.json
npx [email protected] add @ultima/button

Next.js App Router:

npx [email protected] add https://ultima.systems/r/setup-next.json
npx [email protected] add @ultima/button

The setup item writes components.json and the StyleX compiler config, and never overwrites a file your scaffold already owns. Installing Button pulls in the tokens and the shared component helpers. The steps you still do by hand are on the install page.

import { Button } from '@/components/ui/button';

<Button variant="solid" size="md" tone="accent">Save</Button>

What ships

• Fifty-four components, one file each, from Button and Field to Combobox, Sidebar, and Toast. See the catalogue.
• Tokens for color, space, radius, type, and motion, as StyleX variables. Six twelve-step palette scales with a dark and a light value per step. See tokens and the palette.
• Tokens as CSS at /tokens.css, for consumers that cannot run StyleX.
• An agent guide at /llms.txt: principles, conventions, component list, and token names in one plain Markdown file. The installable ultima-design skill directs your agent to this current guidance and the CLI checks.
• The registry at /r/registry.json, one item per component.
• Elements at /elements/ultima.js: the report set as custom elements for hosts that cannot run React. Each element also ships as a registry item: ult-badge, ult-button, ult-card, ult-code, ult-meter, ult-stat, ult-table, ult-tabs, and ult-tooltip.
• The ultima-design CLI, which verifies your setup, checks your edits against the consumer rules, and reports installed items' drift. See the CLI page.

Install the agent skill

These GitHub installation routes become publicly available when this repository is public. Until then, they require repository access.

Through skills.sh, choose ultima-design for projects using Ultima:

npx skills add frankieramirez/ultima --skill ultima-design

Or use the Ultima marketplace in Claude Code:

/plugin marketplace add frankieramirez/ultima
/plugin install ultima-design@ultima

The Claude plugin exposes /ultima-design:ultima-design. Both routes install the same consumer skill. forge is for contributors working inside the Ultima repository.

Install the CLI in your project to run the skill's checks:

npm i -D ultima-design

For a CLI-managed skill with post-edit hooks, use npx ultima-design install as an alternative to the skill installers. Skills installed through skills.sh or Claude remain owned by that installer; update or remove them there. The CLI preserves unstamped skill files and does not refresh them.

How it is built

• Components take a style slot of StyleX styles and have no className. There is no second styling system to fall back to.
• Tokens are the only source of raw values. A literal in component code is a bug, and a new need becomes a new token.
• Semantic token names are stable. You re-skin at the semantic layer and nothing renames underneath you.
• Contrast is a build gate. Every pairing passes WCAG 2.2 AA in both modes or the palette does not ship. APCA is reported beside the pairings.
• The fantasy theme lives in the brand layer only: the name, the six scale names (mithril, arcane, mana, verdant, ember, ruin), page titles, and the 404. Component, part, prop, and semantic token names stay conventional.

The rationale page and the ADRs hold the reasoning. The specification holds the rules.

Stack

• Base UI for the primitives.
• Zag.js for the element primitives, bundled inside each vendored artifact.
• StyleX for styling.
• A shadcn registry for distribution.
• Vite and TanStack Router for the docs site, which also serves the registry, the token exports, and the agent guide.

Repository

apps/docs          The docs site, its MDX content, and the component demos.
packages/analysis  The architecture checker's engine: scopes, rules, and the dependency policy.
packages/cli       The ultima-design consumer CLI: install, doctor, check, status, diff.
packages/elements  The custom-element re-implementations and the bundle the registry serves.
packages/tokens    Token sources, themes, the palette generator, and the generated tokens.css and tokens.json.
packages/ui        One file per component in src/, shared helper types in src/lib/, tests in src/__tests__/.
registry/          Build output, apart from the authored static/ and metadata/ descriptors.
scripts/           The catalogue generator, the registry build, verification helpers, and smoke-install.
skills/            Ultima's own agent skills. forge authors and revises a component.
verification/      Feature and scenario records, one JSON file each.
docs/              The specification, ADRs, and research notes.

Develop

Requires Node 22 or later and pnpm 10.

Command	Runs
pnpm install	Install the workspace.
pnpm dev	The docs site, in development.
pnpm build	Every package, the registry, and the docs site.
pnpm test	The Vitest suites, including the axe sweep.
pnpm typecheck	Typecheck every package.
pnpm registry:build	Regenerate registry/, /r/*.json, the token exports, and /llms.txt.
python3 packages/tokens/scripts/palette.py	Regenerate palette.json. --check fails on a hand edit.
scripts/smoke-install.sh	Install every setup target from the registry and build it.

Read the principles before changing anything. AGENTS.md lists the rules that are easy to break.

Brand

The Compact wordmark uses custom lowercase lettering, with a squared u for icons. The wordmark uses ink and paper; browser and app icons add a cyan background. Brand guidelines cover the SVG and PNG exports, social image, avatar, and regeneration command.

Related

mana is the audit toolkit whose report is the first consumer of the tokens CSS export.

License

MIT