Hareru UI

A semantic design system built for agents.

Features

• Semantic CSS — BEM naming (hui-*) and CSS custom properties (--hui-*). No Tailwind dependency.
• Layered architecture — Tokens, styles, and component behavior live in independent packages. Each layer is consumable on its own by both humans and AI agents.
• DTCG tokens — 150+ tokens in W3C Design Token Community Group format with JSON Schema validation. A typed contract between designers, developers, and AI agents.
• Zero-runtime theming — Light and dark themes via data-theme attribute. Pure CSS, no JS runtime cost.
• OKLCH colors — Perceptually uniform color space with automatic dark theme generation.
• Accessible components — 60 components built on Base UI primitives. WAI-ARIA compliant.
• MCP server — @hareru/mcp exposes design rules directly where AI agents operate via Model Context Protocol. Tokens, schema, and component registry are all queryable.
• AG-UI chat components — ChatContainer, StreamingText, ToolCallCard, and useAGUIState hook for building agent UIs with the AG-UI protocol.

Installation

# npm
npm install @hareru/tokens @hareru/ui

# pnpm
pnpm add @hareru/tokens @hareru/ui

# yarn
yarn add @hareru/tokens @hareru/ui

Peer dependencies: react >= 19, react-dom >= 19

Quick Start

1. Import CSS

A. Standalone (Hareru-only app — one import, everything included):

@import "@hareru/ui/styles.css";

B. Portable (alongside other frameworks — no global reset):

@import "@hareru/tokens/css";
@import "@hareru/ui/styles/components.css";
@import "@hareru/ui/styles/scope.css"; /* opt-in: .hui-root subtree typography */

C. Tailwind v4 coexistence (recommended for Tailwind projects):

@layer theme, base, hui, components, utilities;
@import "tailwindcss";
@import "@hareru/tokens/css";
@import "@hareru/ui/styles/components.layer.css";
@import "@hareru/ui/styles/scope.css"; /* opt-in */

D. Per-component (minimal bundle):

@import "@hareru/tokens/css";
@import "@hareru/ui/styles/components/Button.css";
@import "@hareru/ui/styles/components/Card.css";
/* Add @hareru/ui/styles/animations.css when using StreamingText, ReasoningPanel, or ToolCallCard */

styles.css already bundles tokens, so @hareru/tokens/css is not needed when using it.

If your host app has no CSS reset, optionally add @import "@hareru/ui/styles/baseline.css" for box-sizing: border-box and form element font inheritance.

2. Set up the provider

"use client"; // Required for Next.js App Router

import { ThemeProvider, Toaster } from "@hareru/ui";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider defaultTheme="system">
      {children}
      <Toaster />
    </ThemeProvider>
  );
}

3. Use components

import { Button, Card, CardHeader, CardTitle, CardContent } from "@hareru/ui";

function Example() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hareru UI</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Click me</Button>
        <Button variant="destructive">Delete</Button>
      </CardContent>
    </Card>
  );
}

All components are exported from @hareru/ui. There are no subpath imports.

CLI

# Initialize project (auto-detects framework + CSS mode)
npx @hareru/cli init --write

# Switch CSS mode
npx @hareru/cli update --mode portable --write

# List all components
npx @hareru/cli list

# Inspect a component
npx @hareru/cli info Button

# Generate CSS imports and append to your stylesheet
npx @hareru/cli add Button --write

# Specify CSS mode explicitly
npx @hareru/cli add Button --write --mode tailwind

Packages

Package	Description
@hareru/tokens	Design tokens and CSS custom properties (DTCG format)
@hareru/ui	57 React components with semantic CSS styling
@hareru/registry	Shared registry types, loaders, and CSS mode recommendation
@hareru/cli	CLI for component management — init, update, list, info, add
@hareru/mcp	MCP server for AI agent integration (6 resources, 5 tools, 3 prompts)

Contributing

Contributions are welcome. Please open an issue first to discuss what you would like to change.

pnpm install    # Install dependencies
pnpm build      # Build all packages
pnpm test       # Run tests
pnpm lint       # Lint with Biome

License

MIT — Copyright (c) 2026 MUSUBI Inc.