darkmatter-design-system

Darkmatter 设计系统

这是 darkmatter 的设计系统：一种以深色为先、具有终端／控制台美学的系统，基于 Tailwind CSS v4、React 19 和 Radix UI 构建。当应用没有其他既定系统时，可使用它的外观、设计令牌和组件 API。可复用 UI 仍位于仓库自己的 UI 包中（ADR-0013）；不要依赖 @native/ui 或任何其他别名。

设置 — 基于 starter 构建

starter 是一个示例布局，不是必需的导入路径。

• app/globals.css 导入 tailwindcss，然后导入随仓库提供的 theme.css（它会导入 native-tokens.css）。这会建立 OKLCH --n-* 色阶、shadcn 语义桥接和 Tailwind 调色板覆盖。不要添加第二套 Tailwind 主题，也不要重新声明设计令牌。
• 根布局挂载 ThemeProvider（强制使用深色主题）、加载字体（Inter / Space Grotesk / 等宽数字），并在 <html> 上设置 className="dark"。
• 从本仓库的 UI 包导入组件。在 starter 中，该包以 @native/ui/* 的形式随仓库提供；其他仓库使用不同的别名。请从工作区 / packages/* / vendor 目录中查找。

要构建屏幕：在应用下添加路由／组件，从 UI 包导入组件，并使用系统的布局原语组合页面。无需重新创建脚手架、重新接线 Provider 或重新导入全局样式。

导入规则

• 按照 UI 包的导出方式导入每个组件（单文件路径或 barrel；遵循仓库的做法）。
• cn 和其他辅助函数与组件一起位于该包中。
• 大多数组件均为客户端组件（"use client"）。在框架允许的情况下，页面应保持为服务端组件。
• 完整模块列表及各任务领域文件的文档位置，请参阅 references/components/index.md。

权威依据

• 仓库中的 UI 包是组件 API、props 和变体的权威依据。本技能中的参考文件会引用 packages/ui/src/button.tsx 等示例路径。
• 设计令牌仅来自 theme.css + native-tokens.css（或仓库中这两个文件的副本）。切勿硬编码十六进制／OKLCH 值，也不要使用未映射的 Tailwind 标准色阶 — 请参阅 references/foundations/colors.md。

路由规则 — 构建前阅读

• 颜色与设计令牌 → references/foundations/colors.md
• 排版与字体 → references/foundations/typography.md
• 间距、圆角与布局 → references/foundations/spacing-layout.md
• 响应式设计与断点 → references/foundations/responsiveness.md（构建布局前务必查阅）
• 动效 → references/foundations/motion.md
• 组件目录 + 任务领域文档 → references/components/index.md
• 示例 → references/examples/

硬性规则

• 深色优先。该系统只定义一种深色主题；没有浅色模式。
• 使用设计令牌和已映射的工具类（bg-n-bg-2、text-n-mute、border-n-hl、text-primary、bg-card），绝不使用原始十六进制／OKLCH 值或未映射的 Tailwind 颜色。
• 使用 Tailwind 断点和系统布局原语（PageLayout、Grid）构建响应式布局。绝不要为页面结构硬编码固定像素宽度。
• 数值／财务数据使用 tabular-nums（--font-num 字体），使列对齐 — 请参阅排版文档。
• 未经批准，绝不自行发明组件、props、变体或设计令牌名称。

最终检查

完成任何 Darkmatter UI 前：

• 所有可复用 UI 均来自仓库的 UI 包；不混用第二个组件库。
• 颜色均映射到 --n-* 设计令牌或已映射的工具类；没有原始值。
• 布局使用 PageLayout/Grid，并能在各断点下响应式呈现。
• 数值数据使用 tabular-nums。
• 屏幕整体呈现深色、紧凑、类似终端的风格 — 如果感觉不像 Darkmatter，就依据设计基础调整布局组合，而不是添加一次性样式。