Overview of Rift DS
How the system is built, and why its docs stay true
Rift DS ships as the npm package rift-ds: layered CSS tokens, React components, and complete themes, each applied by one data-brand attribute. This site installs it like any consumer, and the build holds these docs to the code: generators write them from the registries in the repo, and validators fail the build when the two disagree. You can install it yourself and re-theme it live.
The specs (CLAUDE.md, design.md, content-design.md), the skills, and the loops are yours to lift into your own codebase or AI tooling. Agents read the same contracts through the MCP endpoint at /api/mcp, or as files: one JSON schema per component and the tokens in the DTCG format.
The system is designed and built by Robert Ritacca, who writes the specs Claude Code builds from.
Using it in your product
Install the package, import the token stylesheet and the base sheet, and compose the components. A data-brand attribute on your root element applies a complete theme, light and dark. Your coding agent joins through this site: one command installs the agent skills, and the MCP endpoint serves the exact contracts while it builds.
The rules it keeps
The same rules hold across the whole library, and the build or CI checks each one, so a broken rule fails instead of shipping.
- Tokens. Three tiers, never skipped: primitives hold raw values, semantic tokens point at them, and components use only the semantic tokens. The action colour is reserved for actions, and shape is set per element type, so every button matches every other. A theme changes the values, never the tiers.
- Props. Every component passes its ref and your attributes to its element. State you can own takes the same names everywhere:
valueto control it,defaultValueto let the component keep it, andonValueChangeeither way, with the same shape forchecked,valuesandopen. Every word a component writes is a prop with an English default, so all of it translates. - Behaviour. Every overlay joins one layer stack, so Escape closes only the top one and a menu inside a Dialog closes first. Key bindings share one listener, layout follows the reading direction, and numbers and dates follow your locale. The accessibility page has the detail.
- The API. It only grows. A prop or export is deprecated, never removed, so an older name keeps working after an upgrade.
design.md holds the full set.
How the system fits together
One repo becomes a website, a Storybook, and an npm package through one gate: generators derive every surface from one source of truth, validators fail the build on drift, and CI runs the chain on every push. Each map below pans, zooms, and expands to full screen.
Figma
Claude Code
GitHub
Storybook
Vite
Next.js
Vercel
npm
What the repo holds
The repo is five layers deep: primitives feed the semantic tokens, tokens feed the components, and the components compose the site UI and every page. The graph page reads every edge from the CSS and imports at build time; pick a token or component to trace what it depends on and what depends on it.
How a change ships
Every change goes live in five stages: author, generate and validate, build, gate, ship. A push to main deploys the site; the package publishes to npm on its own lane, with provenance and no stored token. The map shows each check in the gate.
How Claude Code runs it
Claude Code drives the pipeline through skills named for their end state. A change sits in one of four states, and checkpoint, park, land, and ship move it between them. Audit skills read and fix but never deploy; only ship and super-ship, which runs a full drift audit first, reach production.
What runs once it’s live
Pages come from Vercel with the fonts and the chat corpus baked in, and a scheduled smoke re-checks production.
- The chat answers through Claude from the site's corpus, looking up prop and token contracts when it needs them. Rate limits and a daily budget cap it, and conversations are kept 30 days, tied to no name.
/api/mcpserves agents five tools with no key, no account, and no model behind them: the component list, prop APIs, tokens resolved per theme, install setup, and site search. Component and token answers cite the published file.
How the chat answers
The corpus holds everything published as prose, cached for an hour, so most answers come from context alone. Exact facts (a prop's type or default, a token count, a token's value in a theme) come from lookup tools that read the same data /api/mcp serves, shown in the widget as a trace point. The corpus keeps the chat fluent; the tools keep it exact.