halo-ds

Halo Design System

デザイナーと開発者のためのオープンソースのデザインシステムです。同じデザイントークンから構築されたFigmaライブラリとReactコンポーネントライブラリを備え、ライトモードとダークモードに対応しています。

📖 ウェブサイトとドキュメント：https://halo-design-system.github.io/Halo-design-system/

🧪 コンポーネントプレイグラウンド（Storybook）：https://halo-design-system.github.io/Halo-design-system/storybook/

• FigmaとReactで利用できる56個のコンポーネントと、2,125個のFigmaバリアント
• ライトモードとダークモードの288個のデザイントークンと42個のテキストスタイル
• 1,512個のアイコン、100個のイラスト、3,719個の絵文字、271個の旗、1,489個のブランドロゴ
• ウェブサイト上でクリックして試せる8個の既製ブロックと7個のサンプルアプリ
• AIアシスタントがHaloを正しく使って構築できるようにする、MCPサーバー、CLI、Claude Codeプラグイン

MITライセンスのもとで無料で利用できるオープンソースです。現在のバージョンはnpmの0.5.0です。

パッケージ

パッケージ	説明
@halo-ds/tokens	Figmaから生成された、CSS変数（ライト＋ダーク）、JSON、JS形式のデザイントークン
@halo-ds/react	Reactコンポーネント
halo-ds	CLIとMCPサーバー：npx halo-ds init、theme、add、docs、mcp
figma-plugin	Figmaプラグイン：すべてのコンポーネントを検索してキャンバスに配置
halo-ds plugin	Claude Codeプラグイン：UIの構築、レビュー、テーマ設定、移行のためのスキル
site	ウェブサイト：ドキュメント、コンポーネント、基礎情報、実際に動作するサンプルアプリ
docs	Storybook：ライブドキュメントとコンポーネントプレイグラウンド

Haloを使う

npx halo-ds init

Haloをインストールし、モードとブランドカラーを指定します。または、自分でインストールすることもできます。

npm install @halo-ds/react

セットアップはこれだけです。コンポーネントを使うと、スタイル、デザイントークン、Geistフォントが自動的に読み込まれます。

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

<html>のdata-theme属性でテーマを切り替えます。light（デフォルト）、dark、またはsystem（OSの設定に従う）を指定できます。

すべてのトークンは--halo-で始まるCSS変数なので、独自のスタイルでも使用できます。

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

自分用にカスタマイズする

• 手軽な方法： ブランドカラーを指定してnpx halo-ds theme "#2F6BFF"を実行するか、ウェブサイトで色を選びます。ライトモードとダークモードのブランドカラーが設定されます。再ビルドは不要です。
• 詳細な方法： Figmaファイルのコピー内で変数を変更してエクスポートし、トークンを再ビルドします。これにより、デザインとコードを一致させられます。

テーマ設定のページでは、両方の方法を順を追って説明しています。

AIアシスタントと一緒に使う

MCPサーバーを追加すると、アシスタントが各コンポーネントのprops、例、ルールを把握できるようになります。

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

Cursor、VS Code、Windsurfなどのセットアップ方法：https://halo-design-system.github.io/Halo-design-system/docs/ai

Haloの開発

必要な環境：Node.js 22.12以降とpnpm（npm install -g pnpm）。プロジェクトではNode 24のランタイムが固定されており、pnpmが自動的にダウンロードします。

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

プロジェクト構成

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/       the website, with the live example apps in src/live
  docs/       Storybook (foundations pages + component stories)
  video/      the launch video (Remotion)
docs/         design notes (e.g. dark-mode mapping)

デザインからコードへのワークフロー

1. Haloの変数を使ってFigmaでコンポーネントをデザインします（生の16進数値は使わないでください）。
2. 対応するCSS変数を使って、packages/react/src/components/<Name>/にコンポーネントを実装します。
3. <Name>.stories.tsxを追加して、Storybookに表示されるようにします。
4. Storybookでライトモードとダークモードの両方を確認します。

詳しくはCONTRIBUTING.mdをご覧ください。

ライセンス

MIT。Figmaライブラリには、他のオープンソースプロジェクトの絵文字、アイコン、旗、ブランドロゴも含まれています。ライセンスと必要なクレジットについては、THIRD_PARTY_NOTICES.mdをご覧ください。