An open-source agentic design system for Software 3.0: React components and style guides that humans can browse and AI agents can read, build with and operate.
npm install @peerproblem/sw3-uiDocs and live demos · npm · Changelog
- Components: forms, dates, overlays, menus, lists, navigation, layout, media and data views, plus a dashboard kit. Each one is keyboard-complete and ARIA-correct, and is built on shared primitives (
usePopup,useListNavigation,useFieldControl). - Rules in two layers: structure rules (one primary action, hierarchy, one frame per group, responsive, accessible, token-only values) hold in every app. The look is a default theme you change with tokens. See Design principles.
- Default look: neutral ink-on-paper palette, Geist with tight tracking, 1px frames and squircle corners with corner smoothing of 0.6. Apps can set a brand accent, their own typefaces, or swap a design with
data-design="calm|frost". - Motion: Motion for React presets for press, lift, glide and enter, off under reduced motion.
- Charts: Unovis wrappers themed with the tokens (
@peerproblem/sw3-ui/charts), with guidance on which chart answers which question. - Maps: MapLibre GL with routes, pins, areas and a theme-aware basemap (
@peerproblem/sw3-ui/map). - Dashboards:
AppShell,SidebarNav,DashboardGridandBreadcrumbsfor the frame; everything inside is the base kit. See the Dashboards guide. - Extras: specialized components outside the core kit (
@peerproblem/sw3-ui/extras): PosterCard, ActionSquare, PillButton, Canvas, WeekSchedule. - Agent bridge:
@peerproblem/sw3-ui/agentlets an AI agent read and change components through their APIs (snapshot,query,act,subscribe). Permissions useallowandconfirm, and the tools publish to WebMCP browsers. - Docs for agents: a metadata entry per component (props, examples, when to use, what to avoid, rules, DOM contract) compiled into
packages/ui/agent/: a shortllms.txtrouter, one file per topic, one file per component andregistry.json. Every rendered component carriesdata-sw="<slug>".
npm install @peerproblem/sw3-uiimport '@peerproblem/sw3-ui/styles.css'
import { SwProvider, Button } from '@peerproblem/sw3-ui'
export function App() {
return (
<SwProvider>
<main className="sw-root">
<Button variant="accent">Publish</Button>
</main>
</SwProvider>
)
}React 18 or 19 is required. Install the optional peers for the entry points you use:
| Entry point | Install separately |
|---|---|
@peerproblem/sw3-ui/charts |
npm install @unovis/react@~1.8.1 @unovis/ts@~1.8.1 d3-hierarchy@^3.1.0 |
@peerproblem/sw3-ui/map |
npm install maplibre-gl@^6.18.0, then load the MapLibre CSS in its layer |
With TypeScript installed in the app, run npx --no-install sw3-check src to check app-owned TSX, JSX and CSS. The checker prints JSON with each violation's location and suggested fix. Use checkDesign(viewRoot) from @peerproblem/sw3-ui/check to check a rendered view. See the design check guide.
To build with an AI agent, point it at node_modules/@peerproblem/sw3-ui/agent/llms.txt (for example from your AGENTS.md), or copy skills/sw3-ui into .claude/skills/.
npm install
npm run dev # builds the agent docs, then serves the docs site on http://localhost:5178packages/ui/ @peerproblem/sw3-ui — the SDK
src/tokens/ tokens.ts (source of truth for every value)
src/primitives/ squircle, popup/overlay, list keyboard, controlled state, field wiring
src/agent/ useAgentBinding + @peerproblem/sw3-ui/agent bridge (snapshot / query / act, WebMCP)
src/hooks/ useAsyncOptions, useShortcut, useListQuery
src/kit/ export lists for the core kit
src/extras.ts @peerproblem/sw3-ui/extras (specialized components)
src/themes/ data-design themes (calm, frost)
src/motion/ motion presets
src/components/ core components
src/charts/ @peerproblem/sw3-ui/charts (Unovis)
src/map/ @peerproblem/sw3-ui/map (MapLibre)
src/meta/ component metadata — the agent contract
scripts/ build-agent-docs.ts (tokens.css and agent/)
agent/ generated and shipped: llms.txt router, llms/<topic>.txt, components/<slug>.md, tokens.md, registry.json
apps/playground/ docs site: component gallery, charts, maps, blocks, tokens, corner lab, agent bridge console
guides/ design guides, compiled into the topic files
skills/sw3-ui/ drop-in agent skill (copy to .claude/skills/)
AGENTS.md instructions for agents working in or with this repo
| Command | What it does |
|---|---|
npm run dev |
Regenerates agent docs, starts the playground |
npm run agent:build |
tokens.ts + meta + guides → tokens.css and packages/ui/agent/ |
npm run typecheck |
Typechecks the SDK and playground |
npm run build |
Builds the package (tsup + CSS) and the playground |
npm test |
Unit tests: agent bridge, design check, CSS rules |
npm run test:keyboard |
Chromium keyboard and accessibility regressions against the playground |
npm run test:package |
Packs the library and checks clean installs under React 18 and 19 |
Install the test browser once with npx playwright install chromium --only-shell. Use npm run test:keyboard -- --ui to inspect each test and its steps.
See guides/09-contributing-components.md. In short: build the component, export it, add a defineMeta entry, add a demo, then run npm run agent:build. Design rules go in guides/*.md or in a component's rules; both end up in the agent docs.
Each component's metadata has a status:
stable: the props and DOM contract follow semver. Breaking changes wait for a major version.beta: complete and tested, but props may still change in a minor version. The changelog lists every change.experimental: may change or be removed in any release.
Agents see the status at the top of each component's docs. Prefer stable components when two would do the job.
With the latest @types/react (18 or 19), TypeScript reports an error inside framer-motion's own type definitions (MotionStyle). Set "skipLibCheck": true in the app's tsconfig.json. The Vite and Next.js templates already do.
See CONTRIBUTING.md to work on the SDK and RELEASING.md to publish a version.
MIT