darkmatter-design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Darkmatter Design System

Darkmatter 设计系统

This is darkmatter's design system: a dark-first, terminal/console aesthetic built on Tailwind CSS v4, React 19, and Radix UI. Use it for look, tokens, and component APIs when the app has no other established system. Reusable UI still lives in the repo's own UI package (ADR-0013); do not require

@native/ui

or any other alias.

这是 darkmatter 的设计系统：主打深色优先、终端/控制台美学，基于 Tailwind CSS v4、React 19 和 Radix UI 构建。当应用没有其他成熟的设计系统时，可使用它来统一视觉风格、设计令牌和组件 API。可复用 UI 仍存放在仓库自身的 UI 包中（ADR-0013）；不要引入

@native/ui

或任何其他别名。

Setup — build on the starter

配置——基于启动模板构建

The starter is an example layout, not a required import path.

app/globals.css
imports
```
tailwindcss
```
, then the vendored
```
theme.css
```
(which imports
```
native-tokens.css
```
). This establishes the OKLCH
```
--n-*
```
ramp, the shadcn semantic bridge, and the Tailwind palette overrides. Do not add a second Tailwind theme or re-declare tokens.
Root layout mounts
```
ThemeProvider
```
(forced dark), loads the fonts (Inter / Space Grotesk / mono numerics), and sets
```
className="dark"
```
on
```
<html>
```
.
Import components from this repo's UI package. In the starter that package is vendored as
```
@native/ui/*
```
; other repos use a different alias. Discover it from workspaces /
```
packages/*
```
/ vendor trees.

To build a screen: add routes/components under the app, import from the UI package, and compose with the system's layout primitives. You do not need to re-create the scaffold, re-wire the provider, or re-import globals.

启动模板是一个示例布局，而非必需的导入路径。

app/globals.css
先引入
```
tailwindcss
```
，再引入内置的
```
theme.css
```
（该文件会引入
```
native-tokens.css
```
）。这会建立 OKLCH
```
--n-*
```
色阶、shadcn 语义桥接以及 Tailwind 调色板覆盖。请勿添加第二个 Tailwind 主题或重新声明设计令牌。
根布局挂载
```
ThemeProvider
```
（强制深色模式），加载字体（Inter / Space Grotesk / 等宽数字字体），并在
```
<html>
```
标签上设置
```
className="dark"
```
。
从当前仓库的 UI 包导入组件。在启动模板中，该包以
```
@native/ui/*
```
的形式内置；其他仓库会使用不同的别名。可从工作区 /
```
packages/*
```
/ 依赖目录中找到它。

构建界面的方式：在 app 目录下添加路由/组件，从 UI 包导入组件，并使用系统的布局原语进行组合。你无需重新创建脚手架、重新配置 provider 或重新引入全局样式。

Import rules

导入规则

Import each component from the UI package the way that package exports it (per-file paths or a barrel — follow the repo).
```
cn
```
and other helpers live next to the components in that package.
Most interactive components are client components (
```
"use client"
```
). Keep pages as server components where the framework allows it.
See
```
references/components/index.md
```
for the full list of modules and which task-area file documents each.

按照 UI 包的导出方式导入每个组件（单文件路径或统一导出入口——遵循仓库规范）。
```
cn
```
及其他工具函数与该包中的组件放在一起。
大多数交互组件是客户端组件（
```
"use client"
```
）。在框架允许的情况下，页面请保持为服务端组件。
完整的模块列表以及各模块对应的任务领域文档，请查看
```
references/components/index.md
```
。

Source of truth

权威来源

The UI package in the repo is the authority for component APIs, props, and variants. The reference files in this skill cite example paths like
```
packages/ui/src/button.tsx
```
.
Tokens come only from
```
theme.css
```
+
```
native-tokens.css
```
(or the repo's copies of those files). Never hard-code hex/OKLCH values or reach for stock Tailwind shades that aren't mapped — see
```
references/foundations/colors.md
```
.

仓库中的 UI 包是组件 API、属性和变体的权威依据。本技能中的参考文件引用了类似
```
packages/ui/src/button.tsx
```
的示例路径。
设计令牌仅来自
```
theme.css
```
+
```
native-tokens.css
```
（或仓库中这些文件的副本）。切勿硬编码十六进制/OKLCH 值，也不要使用未映射的原生 Tailwind 色阶——详见
```
references/foundations/colors.md
```
。

Routing rules — read before building

查阅路径——构建前必读

Colors & tokens →
```
references/foundations/colors.md
```
Typography & fonts →
```
references/foundations/typography.md
```

Spacing, radii & layout →

references/foundations/spacing-layout.md

Responsiveness & breakpoints →
```
references/foundations/responsiveness.md
```
(always consult before building layouts)
Motion →
```
references/foundations/motion.md
```
Component catalog + task-area docs →
```
references/components/index.md
```
Worked examples →
```
references/examples/
```

颜色与设计令牌 →
```
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/
```

Hard rules

硬性规则

Dark-first. The system defines a single dark theme; there is no light mode.
Use design tokens and mapped utilities (
```
bg-n-bg-2
```
,
```
text-n-mute
```
,
```
border-n-hl
```
,
```
text-primary
```
,
```
bg-card
```
), never raw hex/OKLCH or unmapped Tailwind colors.
Build responsively with Tailwind breakpoints and the system's layout primitives (
```
PageLayout
```
,
```
Grid
```
). Never hard-code fixed pixel widths for page structure.
Numeric/financial data uses
```
tabular-nums
```
(the
```
--font-num
```
face) so columns align — see typography.
Never invent components, props, variants, or token names without approval first.

深色优先。系统仅定义了一套深色主题，没有浅色模式。
使用设计令牌和映射后的工具类（
```
bg-n-bg-2
```
、
```
text-n-mute
```
、
```
border-n-hl
```
、
```
text-primary
```
、
```
bg-card
```
），切勿使用原始的十六进制/OKLCH 值或未映射的 Tailwind 颜色。
使用 Tailwind 断点和系统的布局原语（
```
PageLayout
```
、
```
Grid
```
）构建响应式界面。切勿为页面结构硬编码固定像素宽度。
数字/金融数据使用
```
tabular-nums
```
（
```
--font-num
```
字体）以保证列对齐——详见排版文档。
未经批准，切勿自行创建组件、属性、变体或设计令牌名称。

Final checks

最终检查

Before finishing any Darkmatter UI:

All reusable UI comes from the repo's UI package; no second component library mixed in.
Colors resolve to
```
--n-*
```
tokens or mapped utilities; no raw values.
Layout uses
```
PageLayout
```
/
```
Grid
```
and is responsive across breakpoints.
Numeric data uses
```
tabular-nums
```
.
The screen reads as dark, dense, and terminal-like — if it doesn't feel like Darkmatter, fix the composition against the foundations, not with one-off styles.

在完成任何 Darkmatter UI 开发前，请确认：

所有可复用 UI 均来自仓库的 UI 包，没有混入其他组件库。
颜色都解析为
```
--n-*
```
令牌或映射后的工具类，没有使用原始值。
布局使用
```
PageLayout
```
/
```
Grid
```
，且在各个断点下都具备响应式效果。
数字数据使用
```
tabular-nums
```
。
界面呈现深色、紧凑、类似终端的视觉效果——如果感觉不像 Darkmatter 的风格，请依据基础规范调整组合方式，不要使用一次性样式。