@arcticworks/design

v0.1.0

Published

a month ago

ArcticWorks 设计令牌：W3C Design Tokens（JSON）与生成的 CSS 自定义属性（--aw-*）。 / ArcticWorks design tokens — W3C Design Tokens (JSON) plus generated CSS custom properties (--aw-*).

0High
0Medium
0Low

bluefieldcreator

design-tokens tokens css-variables design-system

ArcticWorks Design

适用于所有 ArcticWorks 应用的设计系统。一种设计语言，四个产品，四十余个组件——同样的令牌、组件与规则，处处一致。

English · 简体中文

仓库结构

arcticworks-design/
├── tokens/               # 唯一事实来源（W3C Design Tokens 格式）
├── themes/
│   └── dark/
│       └── index.css     # 生成产物 — 请勿手动编辑
├── scripts/
│   └── build.mjs         # 零依赖构建（node 或 bun）
├── preview.html          # 组件参考 — 每个组件都由令牌驱动
├── preview.css           #   参考样式（仅用令牌，无裸值）
├── ui/                   # SvelteKit 组件库（@arcticworks/svelte）
│   ├── src/lib/          #   包本体：组件、图标、toast store
│   ├── src/routes/       #   交互式 demo 应用
│   ├── AGENTS.md         #   组件约定契约
│   └── dist/             #   构建产物（bun run package）
└── README.md

发布包（Packages）

以下两个包已发布到 npm，均为 MIT 许可：

@arcticworks/design — 设计令牌：tokens/ 中的 W3C Design Tokens（JSON），以及 themes/ 中生成的 CSS 自定义属性。
@arcticworks/svelte — ui/ 中的 Svelte 5 组件库。

规划中：icons/（SVG 源）、docs/。

Svelte 组件库 — `ui/`

Svelte 5（runes）+ TypeScript + SvelteKit。每个组件只消费 --aw-* 令牌，组件的 API 与样式均遵循 ui/AGENTS.md。

cd ui
bun install          # 首次安装
bun run dev          # 交互式 demo，http://localhost:5173
bun run check        # svelte-check
bun run build        # 静态 demo 构建 → ui/build
bun run package      # 库构建 → ui/dist（svelte-package）

在应用中使用

import '@arcticworks/design/themes/dark.css';
import { Button, Table, Dialog, toast, Toaster } from '@arcticworks/svelte';

在容器上设置 data-density="dense"（或 comfortable）即可应用密度档位——行高、控件与内边距会通过 var() 链自动重排。

组件列表

Actions（操作）：Button、IconButton、Segmented · Forms（表单）：Input、Textarea、Search、Checkbox、Radio、Switch、Select、Kbd · Feedback（反馈）：Badge、Spinner、Progress、Skeleton · Structure（结构）：Card、List、ListItem、Breadcrumbs、Pagination、NavItem、NavSection、Sidebar、Tabs、Tree · Data（数据）：Table、PropertyGrid、SplitPane、LineChart、BarChart · Overlays（浮层）：Dialog、Tooltip、Menu、MenuItem、MenuSeparator、Toaster + toast、CommandPalette、Calendar · Composite（复合）：FilePicker · Icons（图标）：Icon + icons 映射表。

三层令牌结构

组件绝不直接读取裸值。每个组件令牌都是一条穿过语义层的 var() 链：

palette.neutral.950  →  surface.1  →  surface.sidebar  →  nav.item-*

Palette（调色板） — 原始色阶（palette.neutral.950）。组件从不引用。
Semantic（语义） — 角色：surface.*、interactive.*、text.*、border.*、status.*。组件与主题实际覆盖的就是这一层。
Component（组件） — button.*、input.*、table.*、nav.*、tabs.*、card.* — 每个状态都有令牌。

由于引用会编译成活链接的 var() 链（例如 --aw-button-height: var(--aw-control-height)），密度档位和未来的主题无需改动任何组件即可级联到整个系统。

令牌分组

| 分组 | 前缀 | 示例 | |---|---|---| | palette | --aw-palette- | --aw-palette-blue-500 | | surface interactive text border status chart scrim | --aw-color-* | --aw-color-interactive-primary | | typography lineheight | --aw-font-* --aw-line-height-* | --aw-font-size-sm | | space | --aw-space-* | --aw-space-4 | | radius | --aw-radius-* | --aw-radius-md | | shadow | --aw-shadow-* | --aw-shadow-2 | | motion | --aw-motion-* | --aw-motion-fast | | control | --aw-control-* | --aw-control-height | | icon | --aw-icon-* | --aw-icon-stroke | | layout | --aw-layout-* | --aw-layout-sidebar-width | | button input card table nav tabs | --aw-<component>-* | --aw-table-row-selected-background | | zindex | --aw-z-* | --aw-z-dialog | | breakpoint | --aw-breakpoint-* | --aw-breakpoint-xl | | opacity focus | --aw-* | --aw-opacity-disabled |

密度（Density）

三档：dense（PLC 工程、DataExplorer、SecureNet）、compact（默认）、comfortable（Continuity、仪表盘）。

<html data-density="dense">

密度覆盖四个根变量——control.height、control.padding-x、card.padding、layout.page-gutter——其余一切（按钮、输入框、表格行、导航项）都通过 var() 链跟随变化。如果应用需要混合密度，可通过 data-density 按容器单独设置。

动效（Motion）

fast 120ms — hover、focus、微交互
normal 180ms — 面板、toast
slow 250ms — 对话框、大型浮层（上限，不再更慢）
easing-standard / easing-emphasized

prefers-reduced-motion 会在生成的 CSS 中把所有时长收敛为 0ms。

图标（Icons）

24px viewBox 网格，仅描边，stroke: 1.75px，圆角连接与端点（corner-radius: 2px）。尺寸：工具栏 16、默认 18、导航 20。默认无实心图标；不做逐图标描边变化。

表格（Tables）

企业软件活在表格里。每个状态都有令牌：

table.header.*、table.row.*（高度、分隔线、hover、选中、展开、斑马纹、focus）、table.cell.*（正文、次要文本、表格数字）、table.sort.*、table.resize.*、table.pinned.*。

无障碍（Accessibility）

文本对比度 ≥ 4.5:1，UI 组件 ≥ 3:1 — 所有随包发布的令牌组合均已验证。
焦点环：每个可交互元素上都有 --aw-focus-ring（2px outline + 2px offset）。
点击目标：所有密度下控件 ≥ 28px（WCAG 2.5.8）。
color-scheme: dark，原生控件以深色渲染。
减弱动效在生成的 CSS 中处理。

构建

node scripts/build.mjs        # 或：bun scripts/build.mjs

新主题是覆盖层文件：themes/light/tokens.json 重新映射语义分组（如 text.primary: #111111），node scripts/build.mjs light 生成 themes/light/index.css。调色板与所有组件令牌保持不动。

扩展

在正确的分组文件中添加令牌，通过 {group.name} 引用语义令牌。
重新生成。未知的顶层分组会映射到自己的 CSS 前缀。
绝不要在组件文件中引入新的颜色、圆角、阴影、时长或高度。如果还不存在，那就是还不存在。

路线图

ui/ — 已完成：SvelteKit 组件库（@arcticworks/svelte），唯一构建组件的地方。
icons/ — 与图标规范匹配的 SVG 源集（运行时映射表在 ui/src/lib/icons.ts）。
themes/light — 相同结构，仅语义覆盖（node scripts/build.mjs light + 一个 themes/light/tokens.json 覆盖文件）。
docs/ — 各组件用法指南。