arena

Dravensoft Arena

一套设计系统，通过一份契约同时支持 React 和 Angular。

MIT 许可证 · 由设计令牌驱动，适用于 React、Angular 和 Tailwind 的设计系统。

你将获得

拥有契约化 API 的组件。 两种框架中的组件名称相同，渲染出的像素也相同，并共享一个 Tailwind 层。成员的名称、接收的参数、默认值和含义都记录在 contracts/api/ 中；各层的类型和表格均由此生成，因此两层不会在不知不觉中出现偏差。组件绘制的每个值都会通过设计令牌解析，因此组件内部不会出现十六进制颜色值或裸像素值。

每个组件都落实无障碍要求，而非每次发布时才进行审查。 每个组件都会声明其实现的模式，其中大多数来自 WAI-ARIA 创作实践：它具有哪些角色、响应哪些按键、焦点落在哪里，以及如何将其关闭。尚未满足的要求及其原因会记录在组件旁边；如果某个组件不再符合其声明的模式，bun run check:behaviour 就会立即报错。

样式内核，让项目呈现自身风格。 关于形状、空间、粗细和深度的问题由 Arena 提出，项目通过编写样式插件给出答案。Arena 自带的外观也只是其中一种插件，而非其他插件的基础。配色和字体存放在 arena.config.json 中，每个包附带的 arena 命令会将其转换为包无法自带的那一份样式表：Arena 提供语言，绝不提供皮肤，其自身的颜色也不会进入你的构建。想要沿用现有风格的项目，可以从 plugin-style-store/catalogue/INDEX.md 中选择一项：目录列出了经过真实产品验证的样式插件，每项占一行。

为那些必须被找到、但大多数产品都不会处理的产品提供元数据。 Angular 层会根据传入的路由写入文档的 <head>，入口为 @dravensoft/arena-angular/metadata：包含标题组合、描述、canonical 和 og:* 属性对；只有明确允许索引的路由才会被索引。该导入路径是第二个入口点，因此从不需要元数据的项目无需安装其背后的路由器。React 不会写入任何 <head> 内容，而两个层都会以 schema.org 术语发布所绘制的面包屑导航。

Agent 为什么能够操作它

API 是一份契约文件，而不是一段文字；组件绑定的模式和样式插件响应的角色也是如此。门禁会检查代码、文档和已发布的软件包是否符合这些契约。拿到这个仓库的 Agent 不会猜测 Arena 的规则：它会读取约束即将编写内容的契约，而门禁会告诉它哪里出错了。

这也正是这些规则能够被强制执行，而非停留在愿景中的原因。每条规则都在 contracts/design/AGENTS.md 中确定，并由 skills/design/SKILL.md 交给构建者。该文件完整列出每条规则，并说明门禁会从你自己的源代码中读取哪些规则。

• Tokens 是唯一的样式层。
• Arena 组件上只能使用词汇表中的类名。
• 外观必须是词汇表中的类，而不能是成员。
• 危险状态使用轮廓样式，而非填充样式。
• 每个视图只能有一个主要强调色。
• 任何表面都不得使用渐变。
• 产品或文案中不得使用表情符号。
• 图标使用 Phosphor 类名字符串，由 Arena 的组件或 ArenaIcon 绘制；原始的 ph-* 元素不会绘制任何内容。
• 绝不要用路由器自己的链接包装 Arena 组件。
• Arena 绘制的锚点会拆分其激活操作。
• 从控件上开始的按压操作必须始终作用于该控件。
• 两种主题，优先深色主题。
• 图表承载身份或含义，不能两者兼具。
• 文案应使用产品的语言，保持正式、直接。
• 缺少必需成员是调用方的错误。
• 是否绑定监听器或填充插槽，不应影响是否进行渲染。
• 少数组件通过方法而非成员进行响应。

安装

bun add @dravensoft/arena-react     # or @dravensoft/arena-angular

安装过程就这些。 Bun 会安装项目缺少的对等依赖。不安装对等依赖的包管理器（包括 Yarn）需要显式指定这些依赖，install.md 中的命令就是如此。图标字体不是对等依赖：arena build 会生成供 ArenaIcon 绘制的精灵图。 install.md 按层列出了相应命令，下方的层级页面则说明了每个包声明了哪些对等依赖。

然后运行 npx --no-install arena init（或 pnpm exec arena init，或 bunx --no-install arena init），该命令会复制示例 arena.config.json 并接入构建脚本，然后导入 arena build 生成的内容。 skills/design/references/install.md 是 React 和 Angular 的入门文档，其中也链接到了配置说明和命令。npm 展示的页面提供入门介绍和问题目录，这些问题链接到相同的参考文档。

通过 MCP

{
  "mcpServers": {
    "arena": { "command": "npx", "args": ["-y", "@dravensoft/arena-mcp"] }
  }
}

@dravensoft/arena-mcp 负责传递这些内容。它会将路由器、参考文档和每个组件文档作为资源和工具，提供给使用 Model Context Protocol 的 Agent；它提供的层级与你的项目所安装的层级一致。组件包包含代码、样式表以及你自己的标记所遵循的契约，不包含任何说明文字。

语料库和它描述的组件是两个包，有两个版本号，因此两者可能不一致。arena_start 会读取项目中的 Arena 包版本，将其与服务端版本进行比较，并在两者不同时告知你。如果版本不一致，应以组件为准，文字内容已经过时。

作为 Claude Code 插件

/plugin marketplace add dravensoft-dev/arena
/plugin install arena@dravensoft
/reload-plugins

更新

/plugin marketplace update dravensoft   # refresh the catalog: learns a new version exists
/plugin update arena@dravensoft         # update the plugin you actually have
/reload-plugins                         # apply it to the running session

一个版本对应一个提交。 每个发行版都从其 git 标签提供，市场条目将 source.ref 固定为 vX.Y.Z。

作为独立的 Agent Skill

将 skills/design/SKILL.md 交给任意 Agent。它是路由入口，会用一个文件回答每个问题。它会在这棵目录树中进行路由，因此，只拿到这个文件的 Agent 会看到问题，并通过 URL 找到答案；拿到仓库克隆或插件的 Agent 则会通过路径找到答案。

**组件包是代码，而 Agent 可通过上述三种方式之一获取设计语言。**安装 MCP 服务、安装插件，或交付这个 Skill，Agent 就能获得指南、规范以及每个组件的用法文档；这些内容能让“集成 Arena”成为一项 Agent 可以独立完成的任务。

查看效果

arena.dravensoft.org 提供设计指南、全量示例，以及每个组件的 Playground 页面，无需克隆仓库，也无需安装任何内容。

使用同一份组件列表，通过 bun run demos 也能在本地打开这些页面；scripts/build/AGENTS.md 说明了全新克隆的仓库需要构建哪些内容，才能让这些页面正常显示。

Agent 会先读取 llms.txt，该文件会先指向设计语言规则，再指向每个框架各自的语料库：React 和 Angular。它们有意分开：每个组件都同时以两种名称发布，两个文档不能互换使用。

依赖项

• 字体由项目自行托管，不会发送 CDN 请求。 Arena 在 assets/fonts/ 中提供 Archivo、Familjen Grotesk 和 Spline Sans Mono 的 .woff2 文件，并由 contracts/design-generated/fonts.generated.css 通过 @font-face 声明，因此字体会从读取它们的页面所在源加载。组件包的使用者在自己的 arena.config.json 中指定三个字体系列；其中 src 可以是字体文件（arena build 会从中提取产品实际使用的内容），也可以是样式表 URL。
• 图标使用 Phosphor Icons（MIT），且不会捆绑图标字体。每个组件都接受一个 Phosphor 类名字符串，并通过 ArenaIcon 从 arena build 生成的精灵图中绘制字形。原始的 ph-* 元素需要项目安装 @phosphor-icons/web。请参阅图标设计。

我会获取哪个版本？

两个包和插件的版本号不一定相同，因为只有在包内内容发生变化时，包才会发布。 skills/design/references/versioning.md 解释了这意味着什么。

最新项目制品

• 仓库／Claude Code 插件：13.0.0
• npm React 包
• npm Angular 包
• npm contracts 包

接下来去哪里

这是哪类工作？ 两类受众阅读的文件几乎完全不同，从错误的分支开始，就会让一个简短的问题变成漫长的阅读。

使用 Arena 构建内容。 skills/design/SKILL.md 是导航入口。从这里开始：frameworks/INDEX.md 汇总了所有组件，可一次读完；frameworks/<layer>/INDEX.md 则用你所用框架的名称列出相同的组件；每个组件的 .prompt.md 介绍如何使用该组件；skills/design/references/install.md 介绍如何安装。

参与 Arena 项目本身。 AGENTS.md 是这一分支的入口，后续内容都可以从中找到。

• scripts/build/AGENTS.md：首次编译 Arena，说明机器需要预先具备什么、全新克隆后必须先构建什么，bun run demos 或 bun run check 才有意义，以及为什么有些生成文件会被纳入版本控制、有些则不会。支持的平台为 Linux 和 macOS；在 Windows 上，支持的路径是 WSL2，并且克隆仓库时应将其放在 Linux 文件系统中。
• frameworks/PACKAGING.md：npm 发布渠道，说明如何从当前目录树组装这两个包、为什么发布的 Arena 不带皮肤，以及使用者应如何声明依赖。
• contracts/AGENTS.md：Arena 的三个契约层级，以及本仓库所有内容的导航图。
• contracts/design/AGENTS.md：规范性设计规范，涵盖风格、字体、颜色、间距、动效、危险状态约定、图标和主题。 其旁边的 contracts/design/TokenTypes.md 提供 DTCG 令牌类型映射，供令牌编写者参考。
• frameworks/react/AGENTS.md：React 层。
• frameworks/angular/AGENTS.md：Angular 层，其最后一节会引导你前往上方的包说明页面，了解如何采用。
• frameworks/tailwind/AGENTS.md：共享的 Tailwind 层。
• frameworks/demos/AGENTS.md：每个组件的演示页面所依赖的测试样例；页面中只有这一部分需要由人编写。
• DOUBTS.md：说明 Arena 中何谓技术债，以及相关记录存放在哪里。

贡献与安全

Arena 欢迎任何人提交拉取请求。 CONTRIBUTING.md 说明哪些更改可以直接提交，哪些需要先提出提案，以及更改不得破坏什么。 SECURITY.md 说明如何报告漏洞；CODE_OF_CONDUCT.md 则是本项目遵循的 Contributor Covenant。

关于

Arena 是 Dravensoft 所有软件产品赖以构建的统一界面语言，并以 MIT License 发布，让其他人也能基于它进行构建。