Skip to content

About

Agentic React design system: accessible components, design rules and tokens that AI agents can read, build with and operate.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SW3 UI SDK

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-ui

Docs 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, DashboardGrid and Breadcrumbs for 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/agent lets an AI agent read and change components through their APIs (snapshot, query, act, subscribe). Permissions use allow and confirm, 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 short llms.txt router, one file per topic, one file per component and registry.json. Every rendered component carries data-sw="<slug>".

Use it in an app

npm install @peerproblem/sw3-ui
import '@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/.

Develop

npm install
npm run dev        # builds the agent docs, then serves the docs site on http://localhost:5178

Repo layout

packages/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

Scripts

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.

Adding components and design rules

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.

Stability

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.

Known issues

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.

Contributing and releases

See CONTRIBUTING.md to work on the SDK and RELEASING.md to publish a version.

License

MIT

About

Agentic React design system: accessible components, design rules and tokens that AI agents can read, build with and operate.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages