halo-ds

Halo 设计系统

面向设计师和开发者的开源设计系统：一个 Figma 资源库和一个 React 组件库，二者基于相同的设计令牌构建，并支持浅色和深色模式。

📖 网站和文档：https://halo-design-system.github.io/Halo-design-system/

🧪 组件演练场（Storybook）：https://halo-design-system.github.io/Halo-design-system/storybook/

• 56 个组件，可用于 Figma 和 React，包含 2,125 个 Figma 变体
• 288 个设计令牌和 42 种文本样式，支持浅色和深色模式
• 1,512 个图标、100 个插画、3,719 个表情符号、271 面旗帜和 1,489 个品牌标志
• 8 个现成区块和 7 个示例应用，可在网站上逐一浏览
• MCP 服务、命令行工具和 Claude Code 插件，帮助 AI 助手正确使用 Halo 构建项目

采用 MIT 许可证，免费开源。当前版本：npm 上的 0.5.0（npm）。

软件包

软件包	描述
@halo-ds/tokens	由 Figma 生成的设计令牌，提供 CSS 变量（浅色 + 深色）、JSON 和 JS 格式
@halo-ds/react	React 组件
halo-ds	命令行工具和 MCP 服务：npx halo-ds init、theme、add、docs 和 mcp
figma-plugin	Figma 插件：搜索所有组件并将其放置到画布上
halo-ds 插件	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（跟随操作系统设置）。

每个令牌都是以 --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 服务，让助手了解每个组件的属性、示例和规则：

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. 在 Figma 中使用 Halo 变量设计组件（不要使用原始十六进制值）。
2. 使用匹配的 CSS 变量，在 packages/react/src/components/<Name>/ 中构建组件。
3. 添加 <Name>.stories.tsx，使组件显示在 Storybook 中。
4. 在 Storybook 中分别检查浅色和深色模式下的组件。

详情请参阅 CONTRIBUTING.md。

许可证

MIT。Figma 资源库还包含来自其他开源项目的表情符号、图标、旗帜和品牌标志；相关许可证和必要署名请参阅 THIRD_PARTY_NOTICES.md。