Twentyfirst UI: two React UI kits, one API

Why Twentyfirst UI

• One API, two looks. Every component, prop, class and token exists in both kits. Load both and switch with data-kit: markup and state stay, only the CSS changes. A parity test fails the build if the kits drift apart.
• 236 components, 37 complete screens. From buttons and data tables to chat, tool calls, agent status and human-in-the-loop approvals, plus commerce, admin, real-estate and life building blocks (health, habits, money, insurance, deadlines, documents).
• Finished from the first render. Empty, loading, error and approval states come with the components.
• Mobile first. Works from 320px up: shells collapse, tables scroll, dialogs become sheets, inputs never zoom.
• Accessible. Keyboard paths, focus rings and ARIA on every component; axe (WCAG 2.1 AA) runs on every example in both kits, light and dark.
• Themes like shadcn/ui. The same variables (--primary, --secondary, --muted, --accent, --destructive, --border, --ring, --radius, charts, sidebar) restyle every component in both kits, light and dark. Paste a theme from ui.shadcn.com/themes or build one live.
• Glass for UI over maps, 3D, video and gradients. surface="glass", FloatingLayout and Ambient turn panels, tiles, the whole app shell, menus and controls into translucent, blurred glass that stays readable over any backdrop, milky in Halo, dark and hairline-edged in Pro.
• Motion with one switch. Choreographed page entrances, charts that draw once their card is in, layers that animate out as well as in, page transitions and reveal on scroll. motion="off" | "standard" | "expressive"; reduced motion always wins.
• Tokens only. No colour literals in component CSS. One token file per kit feeds CSS variables and a Tailwind v4 preset with shadcn's utility names (bg-primary, text-muted-foreground).
• Any stack. React first; every component also ships as a custom element for plain HTML, Vue, Svelte, Angular and Astro.
• Private by default. Self-hosted fonts, no telemetry, no network requests from components. Tree-shakeable: a Button is about 3 KB.
• Built for coding agents. An MCP server, llms.txt and a Markdown version of every docs page, so Claude Code, Cursor and friends use the real components instead of guessing.

Two looks, one API

The same JSX renders either way:

Quick start

npx @twentyfirstmedia/ui init --kit halo   # or --kit pro

init installs the kit, imports its styles (and the Tailwind preset if you use Tailwind), creates a UIProvider root and wires up the Next.js layout. Or set it up by hand:

npm install @twentyfirstmedia/halo

import "@twentyfirstmedia/halo/styles.css";
import { Button, Panel, TextField, UIProvider } from "@twentyfirstmedia/halo";

export function App() {
  return (
    <UIProvider theme="system">
      <Panel title="Workspace">
        <TextField label="Name" defaultValue="Northwind" />
        <Button variant="primary">Save</Button>
      </Panel>
    </UIProvider>
  );
}

Both kits in one app: import @twentyfirstmedia/ui-core/themes.css instead and switch with <UIProvider kit="pro"> or data-kit="pro" on <html>.

Tailwind v4: @import "@twentyfirstmedia/halo/tailwind.css"; after @import "tailwindcss"; maps every token to utilities (bg-surface, text-ink, rounded-lg, shadow-card).

Theming

Both kits read shadcn/ui's theme variables, so any shadcn theme works as it is, and every component follows it:

@import "@twentyfirstmedia/halo/styles.css";

:root {
  --primary: oklch(0.546 0.245 262.881);
  --primary-foreground: oklch(0.985 0 0);
  --radius: 0.75rem;
}
.dark {
  --primary: oklch(0.707 0.165 254.624);
}

Six brand presets ship as CSS (@twentyfirstmedia/halo/themes/violet.css), npx @twentyfirstmedia/ui theme ./shadcn-theme.css writes and imports a theme, <UIProvider tokens={…}> sets one at runtime, and the theme builder shows it live on real components. A test applies a theme to every example in both kits, light and dark, and fails if any part ignores it.

Plain HTML, Vue, Svelte, Angular

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@twentyfirstmedia/halo/dist/styles.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/@twentyfirstmedia/elements/dist/elements.js"></script>

<tf-panel title="Workspace">
  <tf-text-field label="Name" default-value="Northwind"></tf-text-field>
  <tf-button variant="primary">Save</tf-button>
</tf-panel>

See Plain HTML and frameworks.

Use it with AI agents

The CLI ships an MCP server with the docs of the version you installed. It runs offline, needs no account and has no runtime dependencies.

npx @twentyfirstmedia/ui mcp init

This registers it for Claude Code (.mcp.json), Cursor (.cursor/mcp.json) and VS Code (.vscode/mcp.json) and adds the kit's rules to AGENTS.md. To add it by hand:

claude mcp add twentyfirst-ui -- npx -y @twentyfirstmedia/ui mcp --kit halo

Tools: search_docs, list_components, get_component, get_pattern, get_guide, get_tokens, list_icons and check_usage. check_usage reviews code for unknown components, props or icons, missing required props and colour literals.

For any other LLM: /llms.txt, /llms-full.txt, and every page as Markdown: append .md to its path.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗