Primitiv is a design system infrastructure designed to keep teams and AI coding agents in sync. Its core philosophy is: retrieval provides data, while reconciliation provides truth. Design system knowledge is typically scattered across code, Figma, Storybook, and documentation, and when these sources drift, humans rely on experience to reconcile differences, while AI coding agents often fall back to generic patterns that work but do not belong to the product. Through machine-readable contracts and a read-only MCP interface, Primitiv provides every agent with the same and up-to-date design context, helping agents reuse what already exists, follow established decisions, and expose inconsistencies before release.
Key capabilities include: bringing together design context from codebases, Figma, and Storybook; making existing tokens, components, rules, and rationale available to agents; exposing conflicts, drift, and hardcoded token misuse; providing read-only access for MCP-compatible agents and editors; and verifying in CI that contracts remain up to date.
How to use: run commands in the project root directory. init sets up Primitiv for the current project, build creates its design contract, and serve makes that contract available to MCP-compatible agents. It is recommended to configure Primitiv at the project level, because a global MCP configuration may provide the wrong project's contract when switching repositories.
Primitiv also checks local JSX usage against the complete finite property domain of each codebase component. Known out-of-domain values produce pending in-source conflicts, even in automatic resolution mode. Aligning the JSX usage or expanding the declared domain resolves them. warn reports these conflicts without blocking; error and verify --strict exit with code 2. Dynamic values and incomplete domains remain unknown.
When component evidence cannot be compared, primitiv verify reports a brief diagnostic summary. Use primitiv verify --verbose to see the reasons, or use --json for a structured report. Diagnostics explain uncertainty and do not count as conflicts or directly cause verification failure; however, changes to them can still make the saved contract stale. --fast reports saved diagnostics instead of rebuilding them. Agents can read diagnostic counts in the MCP summary and retrieve detailed information through get_design_context using category: "diagnostics" with pagination.
In CDetects component drift in I: run primitiv verify against the saved contract to check declared property facts, finite variant values, observed JSX values, and component relationships. Verification also compares Storybook default args, story args, and control options, including mapped values. Story labels and other presentation metadata do not count as API drift. Observations and example descriptions describe static source evidence, not runtime frequency or breaking-change severity. For example, changing Button usage from size="sm" to size="lg" is detected even if the number of JSX sites is unchanged. Drift messages identify the component ID and field path, such as components/Button and usage.props.size.
Normal verification scans the current source in memory and reports and governs using its current conflicts. Introducing or fixing out-of-domain JSX values takes effect immediately in verification. The saved contract remains the drift baseline, and verification never rewrites it: run primitiv build to refresh it, then verify again. MCP continues to serve the saved contract until it is rebuilt and reloaded.
Failing sources and incomplete or truncated evidence cannot prove that unavailable facts have been removed or conflicts have been resolved. Verification reports available changes and comparison uncertainty. Older contracts remain readable; newly available evidence makes them stale until rebuilt.
Stale evidence exits with code 1, and with code 2 under --strict. Pending conflicts exit with code 2 under error governance or --strict; warning-only conflicts do not independently cause verification to fail. --fast uses saved findings and file modification times instead of scanning current API evidence, so use normal verification in CI. Use --json to get verification results, and --verbose for detailed comparison diagnostics.
Primitiv runs locally, and code never leaves the user's machine. The project is licensed under Apache-2.0.
