atai-design-system

Archetype AI 设计系统 — 搭建脚手架，而非重复造轮子

npm 上已有一个真实发布且采用 MIT 许可证的设计系统。前端通过安装它来组装，而不是手动抄写令牌或复制粘贴组件标记。ds CLI 会搭建 SvelteKit + Tailwind v4 项目、安装软件包、配置对顺序有要求的 CSS，并将设计系统自带的 Agent 配置（CLAUDE.md/AGENTS.md + ds-manifest.json）放入你的代码仓库。之后，请遵循随包提供的配置——组件、字体、回退行为和样式均由它决定。此文件只负责帮你搭好脚手架。

当前随包提供的组件适用于 Svelte 5——Svelte 5 + SvelteKit + Tailwind v4 + DS 软件包，正是 ds create 搭建的技术栈；React 移植版正在开发中。Newton 演示前端优先使用此技术栈。在其他技术栈（React、Flask、纯 HTML）中，@archetypeai/ds-lib-tokens 是纯 CSS，可用于任何框架——仅包含令牌和基础样式，不包含组件。

何时使用

• 用户想要创建新的 Newton 演示前端 / 仪表板 / 监控 UI
• 用户想要在现有 SvelteKit 应用中添加 Archetype AI 品牌标识和令牌
• 用户想要使用品牌组件：菜单栏、徽标、卡片、徽章、表格、对话框、传感器图表 / 散点图 / 面积图、视频播放器、代码块、提示消息

以下情况请勿使用此技能：

• 任务涉及 Newton API / 模型工作——文本·图像·视频推理、嵌入、KNN、数据准备。请使用 atai-newton-fusion-model、atai-newton-omega-model 或 atai-newton-omega-model-data-prep 技能（来源）。

系统（MIT）

@archetypeai/ 命名空间下的四个软件包：

软件包	作用	提供内容
@archetypeai/ds-lib-tokens	Tailwind v4 主题	OKLCH 语义令牌（background、foreground、card、primary、muted、destructive、border、ring、chart-1..5、sidebar、atai-{neutral,good,warning,critical}）+ 品牌颜色（brand-{babyblue,yellow,black,white}）+ 完整色阶调色板（Tailwind 色阶以及自定义的 mauve/olive/mist/taupe，50–950）+ 间距 / 圆角 / 图标描边色阶 + .dark 变体 + 带系统回退字体的字体系列 + 可为裸 h1–h6/p/code 添加品牌样式的语义 HTML 基础层。纯 CSS——无 JS。
@archetypeai/ds-ui-svelte-console	稳定的基础组件	约 24 个 Svelte 5 组件：alert、badge、button、card、checkbox、codeblock、collapsible、dialog、dropdown-menu、dropzone、empty-state、input、input-group、item、label、progress、select、separator、sonner、spinner、table、tabs、textarea、tooltip——另有 theme 助手和 utils（cn）。
@archetypeai/ds-ui-svelte-labs	实验性基础组件（组合 console）	aspect-ratio、chart、kbd、logo、menubar、scatter-chart、sensor-chart、slider、switch、toggle、video-player。图表基于 layerchart 构建（固定为一个确切的预发布版本）。
@archetypeai/ds-cli（ds）	脚手架 + Agent 配置	create / init / add。安装软件包及其对等依赖，写入对顺序有要求的 layout.css，配置 shadcn-svelte，并安装设计系统自带的 Agent 配置。

导入子路径按组件划分，例如 import { Button } from "@archetypeai/ds-ui-svelte-console/primitives/button"、import { Menubar } from "@archetypeai/ds-ui-svelte-labs/primitives/menubar"。所有组件的权威目录——包含导入路径、说明、usage 用法示例以及带默认值的变体维度——位于 ds-manifest.json（由 CLI 安装）。请查阅该文件，不要猜测。

Assembly Path — ds CLI

这是组装前端的方式。优先使用它，而非手动安装。

始终使用 @latest 标签调用 CLI（npx @archetypeai/ds-cli@latest …）。不加该标签时，npx 会静默复用缓存中的 ds-cli 版本，这可能导致项目基于过时的软件包、旧版 ds-manifest.json 或已被取代的 layerchart 固定版本进行搭建。@latest 会强制 npx 在每次运行时解析最新发布的 CLI。

运行 create 前，先确认脚手架的创建位置。 ds create <name> 会在当前工作目录中创建一个名为 <name> 的新文件夹，不会提示你选择位置。运行前，请检查当前工作目录，并与用户确认父目录和项目名称，避免应用被放到意料之外的位置（例如某个技能目录或其他代码仓库中）。若要将系统添加到现有项目，请先 cd 进入该项目，再使用 init，不要使用 create。

搭建脚手架前，先询问品牌字体。 品牌字体（PP Neue Montreal + PP Neue Montreal Mono）需要授权，且不会随 npm 一同发布——只有通过 --fonts <path-to-font-files> 传入字体文件（复制到 static/fonts/，供 tokens 的 fonts.css 使用）时，CLI 才会安装这些字体。没有这些文件时，应用会静默回退到系统字体，品牌视觉效果会明显变差。询问用户是否拥有授权字体文件，并通过 --fonts 传入其所在文件夹；只有在用户没有字体文件时才使用 --no-fonts，并告知用户这会对视觉效果造成什么影响。切勿自行下载或替换字体。由于这些字体需要商业授权，切勿将字体文件提交到公共代码仓库——如果使用了 --fonts，且项目已公开或将公开，请将 static/fonts/ 添加到 .gitignore。

# New project: SvelteKit (TS) + Tailwind v4 + tokens + console + labs + a demo page
npx @archetypeai/ds-cli@latest create my-app --codeagent claude

# Existing SvelteKit project: add the system in place (no demo page)
cd my-existing-app && npx @archetypeai/ds-cli@latest init --codeagent claude

# Granular adds
npx @archetypeai/ds-cli@latest add ds-ui-svelte          # editable component SOURCE (modify workflow)
npx @archetypeai/ds-cli@latest add ds-lib-tokens         # tokens + CSS imports only
npx @archetypeai/ds-cli@latest add ds-config-codeagent --claude   # (re)install agent config only

create 会完成全部工作：搭建 SvelteKit 应用，修改 svelte.config.js 以便 Svelte 5 runes 能在第三方软件包中正常工作，安装全部三个 DS 软件包及其对等依赖（将 layerchart 固定到 labs 图表所需的确切预发布版本），初始化 components.json 和 src/lib/utils.ts（整个目录树中只有一个 cn），写入顺序至关重要的 src/routes/layout.css，安装 Agent 配置，并编写演示用的 +page.svelte。

CLI 支持 Agent：在没有 TTY 或使用 --defaults 时，它会列出仍需指定的选项（--pm、--fonts/--no-fonts、--codeagent）并退出，因此你应先询问用户再继续，而不是自行猜测。请将目标目录和项目名称一并纳入确认。

两种安装模式

• 从 npm 软件包组合（默认）。 create/init 会从已安装的软件包导入组件；升级通过 npm update 完成。除非用户需要编辑组件内部实现，否则应使用此模式。
• 源码安装／“修改”工作流。 ds add ds-ui-svelte 通过 shadcn-svelte 将可编辑的组件源码引入项目，源码来自两个注册表（labs：https://design-system-labs.archetypeai.workers.dev，console：https://design-system-console.archetypeai.workers.dev）。单个组件：npx shadcn-svelte@latest add <registry>/r/<name>.json。

脚手架搭建完成后，以随附配置为准

--codeagent claude 会在项目根目录准确写入两个文件（--codeagent cursor 会写入 AGENTS.md，而不是 CLAUDE.md）：

• ds-manifest.json — 以机器可读格式列出所有组件，统一放在一个扁平列表中：导入子路径、注册表源 URL、一行描述、从真实产品用法中提炼的 usage 用法，以及带默认值的变体维度。这是组件的权威来源。 构建 UI 时，请查阅相应组件条目，不要自行臆造属性或变体名称。
• CLAUDE.md — 介绍如何使用这套系统：技术栈、顺序不可颠倒的 CSS 接线、语义／状态／品牌令牌、排版规则（仅在系统本身已使用等宽字体的位置使用等宽字体，此外用于 ID 和容易发生偏移的数字）、深色模式、页面外壳模式、API 密钥处理、图表指南、自定义组件规范、无障碍要求，以及硬性规则（绝不编辑 node_modules、仅控制台产品使用的变体名称不得使用、layerchart 必须保持固定版本）。

不属于独立基础组件的组合演示部件——例如回放／拖动条、各子系统的阶段面板、日志行项目、状态徽章网格——应基于基础组件（slider + button + card + badge）构建，并遵循清单中每个组件的 usage 用法和 CLAUDE.md 模式。不要期待能通过导入使用它们；应复用基础组件层，而不是直接编写原始标记。

技术栈

当前打包的组件面向 Svelte 5 + SvelteKit + Tailwind v4 + bits-ui 发布；ds create 脚手架搭建的正是这套技术栈，React 版本则仍在开发中。Newton 演示前端应优先使用这套技术栈，并使用已发布的基础组件，而不是基于原始令牌手工构建或将资源复制到仓库中。演示所需的一切（徽标、图表、菜单栏等）都以基础组件的形式提供。对于非 Svelte 技术栈，@archetypeai/ds-lib-tokens 仍然适用——它是纯 CSS，可与任何框架配合使用。

常见陷阱

• **不要手动转录设计令牌、字体或组件样式。**它们位于软件包和 ds-manifest.json 中。手动复制会产生第二份事实来源，并在不知不觉中逐渐偏离。请读取清单并安装软件包。
• **优先使用 CLI，而不是手动安装。**它会应用 svelte.config.js 的 runes 补丁，将 layerchart 固定到确切的预发布版本，并确保整个项目中只有一个 cn——如果手动安装，请一并复现这三项设置，否则软件包组件将无法编译／图表会出问题。
• **优先使用 Svelte 技术栈。**目前这些基础组件仅适用于 Svelte 5（React 移植工作正在进行中）——请在 SvelteKit 上使用 ds-ui-svelte-* 基础组件，而不是手写标记。在其他技术栈中，请使用 ds-lib-tokens（纯 CSS，与框架无关），而不是转录设计令牌。
• **始终在 CLI 命令中指定 @latest。**运行 npx @archetypeai/ds-cli@latest …，不要直接运行 npx @archetypeai/ds-cli。裸用 npx 会复用缓存中的 CLI，可能基于过时的软件包、清单或错误的 layerchart 版本进行脚手架搭建。
• 确认脚手架搭建的位置。ds create <name> 会在当前工作目录中直接创建一个新的 <name>/ 文件夹，不会提示确认。先检查 cwd，并与用户确认父目录和项目名称；要将系统添加到现有项目，请先 cd 进入项目，再使用 init。
• 裸的行内元素不会继承其字体大小。ds-lib-tokens/theme.css 会在 @layer base 中为 span、strong、em、a 和 code（均为 text-sm）显式设置字号，同时也会为块级基础组件设置字号。显式值优先于继承值，而类规则也无法补救——.badge { color; border } 的优先级更高，但没有声明 font-size，因此基础规则仍然生效，10px 行内的 <span> 会以 14px 渲染。当你单独使用设计令牌并采用自定义字号体系，而不是使用会为自身元素设置字号的已发布基础组件时，就会遇到这个问题。你可以直接设置元素字号，或者恢复继承一次——将规则放在未分层样式中，使其优先级高于 @layer base；同时将规则放进 :where()，使其不带任何优先级，其他规则仍可覆盖它：:where(span, strong, em, b, i, code, a) { font-size: inherit; }。
• **不要默默跳过字体。**使用 --no-fonts 搭建脚手架意味着不会加载授权的品牌字体（fonts.css 会从 static/fonts/ 请求 /fonts/PPNeueMontreal-*），UI 会回退到系统字体。如果脚手架搭建的应用看起来不像品牌风格，请先检查 static/fonts/——并务必告知用户当前使用的是回退字体。

文件布局

skills/atai-design-system/
└── SKILL.md   ← this file (delegates to the published packages + the CLI-installed CLAUDE.md/ds-manifest.json)

这里有意不包含参考脚本：设计系统由已发布的 npm 软件包和 ds CLI 构成，组件用法、字体和样式则由 CLI 安装到项目中的 CLAUDE.md + ds-manifest.json 管理。本技能会指向这些文件，而不是重复其中的内容。