Halo Design System

An open-source design system for designers and developers: a Figma library and a React component library built from the same design tokens, with light and dark mode.

📖 Website and docs: https://halo-design-system.github.io/Halo-design-system/

🧪 Component playground (Storybook): https://halo-design-system.github.io/Halo-design-system/storybook/

• 56 components in Figma and React, with 2,125 Figma variants
• 288 design tokens and 42 text styles, in light and dark
• 1,512 icons, 100 illustrations, 3,719 emojis, 271 flags and 1,489 brand logos
• 8 ready-made blocks and 7 example apps you can click through on the site
• An MCP server, a CLI and a Claude Code plugin, so AI assistants build with Halo correctly

Free and open source under the MIT licence. Current version: 0.6.0 on npm.

Packages

Using Halo

npx halo-ds init

This installs Halo and asks for the mode and a brand colour. Or install it yourself:

npm install @halo-ds/react

That is all the setup: the styles, the design tokens and the Geist font load by themselves when you use a component.

import { Button } from '@halo-ds/react';

Switch themes with the data-theme attribute on <html>: light (default), dark, or system (follows the OS).

Every token is a CSS variable starting with --halo-, so your own styles can use them too:

.card {
  background: var(--halo-surface-primary);
  color: var(--halo-text-primary);
  padding: var(--halo-spacing-md);
  border-radius: var(--halo-radius-sm);
}

Make it yours

• Quick: run npx halo-ds theme "#2F6BFF" with your brand colour, or pick one on the website. It sets your brand colour in light and dark. No rebuild needed.
• Full: change the variables in your copy of the Figma file, export them, and rebuild the tokens so design and code match.

The Theming page walks through both.

Use it with AI assistants

Add the MCP server so your assistant knows every component's props, examples and rules:

claude mcp add halo -- npx -y halo-ds mcp

Setup for Cursor, VS Code, Windsurf and others: https://halo-design-system.github.io/Halo-design-system/docs/ai

Working on Halo

Requirements: Node.js 22.12+ and pnpm (npm install -g pnpm). The project pins its own Node 24 runtime, which pnpm downloads automatically.

pnpm install     # install dependencies
pnpm dev         # build tokens and start Storybook at http://localhost:6006
pnpm build       # build every package
pnpm typecheck   # type-check every package

Project structure

packages/
  tokens/     figma/ ← Figma variable exports (source of truth)
              scripts/build.mjs → dist/tokens.css, tokens.json, index.js
  react/      src/ ← components
  cli/        the halo-ds CLI and MCP server
  figma-plugin/
plugins/
  halo-ds/    the Claude Code plugin
apps/
  site/     

... [View full README on GitHub](https://github.com/halo-design-system/halo-design-system#readme)