Hulian UI is a production-ready React design system with 406 components. Every component is exported from @hulianui/ui and uses the shared design tokens.
Install
pnpm add @hulianui/ui @hulianui/tokens@hulianui/tokens provides the required theme CSS. Install it together with @hulianui/ui.
Peer dependencies: react>=18 react-dom>=18 tailwindcss>=4 motion>=11 @base-ui/react>=1.0.0
Add the CSS with Tailwind CSS v4
Import the tokens and preset at the top of your global stylesheet, then include the library source in Tailwind scanning:
/* Design tokens: colors, radii, shadows, and light/dark theme values */
@import "@hulianui/tokens/tokens.css";
/* Tailwind CSS v4 preset: semantic tokens, utilities, and the data-theme dark variant */
@import "@hulianui/tokens/preset.css";
/* Hulian UI ships TypeScript source; make Tailwind scan it. Adjust this path for your stylesheet. */
@source "../node_modules/@hulianui/ui/src/**/*.{ts,tsx}";Add providers
Wrap the application with ThemeProvider, then mount each imperative overlay provider once:
import {
ThemeProvider,
ToastProvider,
ModalProvider,
NotificationProvider,
} from "@hulianui/ui";
export default function App({ children }: { children: React.ReactNode }) {
return (
<ThemeProvider defaultSetting="system">
{children}
{/* Required mount points for toast(), modal.*(), and notification.*() */}
<ToastProvider />
<ModalProvider />
<NotificationProvider />
</ThemeProvider>
);
}Non-negotiable rules
- Use components from
@hulianui/ui. Search the library before writing an equivalent component yourself. - Import from the root package:
import { Button, DatePicker, Table } from "@hulianui/ui". There are no subpath entry points, including for the date family. - Use theme tokens instead of fixed colors. For SVG attributes and inline styles, use values such as
var(--color-primary)andvar(--color-foreground). Color variables must include the--color-prefix so Tailwind CSS v4 can resolve them. - Do not reach into a component's internal markup with local styles. Use the component's public props to change appearance or behavior.
- Read the documentation before coding instead of guessing props. With MCP installed, call
get_component_doc. Otherwise fetch https://hulianui.haloritual.com/d/<component-slug>.md.
Recommended: install the MCP server
@hulianui/mcp lets an AI assistant query components, usage, and rules on demand instead of loading the whole library or guessing prop signatures.
npx @hulianui/mcp init-agentIt writes the usage contract into the files each client reads (CLAUDE.md, AGENTS.md, .cursor/rules/hulianui.mdc, and others) without touching your existing content.
Claude Code and Cursor configuration:
{
"mcpServers": {
"hulianui": { "command": "npx", "args": ["-y", "@hulianui/mcp"] }
}
}Once connected, the server tells the assistant when and in what order to call each tool. See the @hulianui/mcp documentation for the full tool list and the audit workflow for existing projects.
Without MCP, point the assistant at the machine-readable docs: https://hulianui.haloritual.com/d/<component-slug>.md for one component and https://hulianui.haloritual.com/llms.txt for the component index. Every component page also has a Copy MD button.
Install blocks and pages
Blocks are usually self-contained. Pages can compose several blocks. Registry metadata installs recursive block dependencies and rewrites repository paths for the consuming project:
npx shadcn@latest add https://hulianui.haloritual.com/r/block-pricing-table.json
npx shadcn@latest add https://hulianui.haloritual.com/r/page-dashboard.jsonAfter installation, replace sample data, copy, callbacks, and providers listed in the item's replace and providers fields. Composable regions appear in slots. Then run:
npx -y @hulianui/guard srcComponents normally do not need source installation; import them directly unless you intend to modify the component implementation. See registry.json for the complete installable catalog.
Prompt template
I am using the @hulianui/ui React design system.
Read this integration guide first and follow its non-negotiable rules:
https://hulianui.haloritual.com/start
For complete interfaces such as login pages, pricing tables, and dashboards,
inspect registry blocks and pages before starting from scratch.