Vlak

Vlak

一套用于产品探索、遵循固定视觉规则的设计系统。包含 React 组件、CSS、可编辑的 StyleX 源码、兼容 shadcn 的注册表、CLI 工具，以及面向编码 Agent 的组件文档。

浏览组件 · 探索界面 · 与编码 Agent 配合使用

使用导航栏搜索，或按 ⌘K / Ctrl+K 查找组件、AI 参考资料、指南和界面。使用方向键选择结果，按 Enter 打开，按 Escape 返回页面。搜索在本地运行，并可识别常见的 API 别名。

_{▶ 观看 ChatGPT 发现 Vlak 并使用其组件系统——50 秒。}

Vlak 在荷兰语中意为平面或表面：字体、控件和内容排列其上的场域。模块化网格为这个场域提供结构。

vlak.dev · github.com/Noord-Ventures/vlak

由位于阿尔克马尔的 Noord Applied Design Lab 设计并构建。

安装

选择适合项目的所有权方式。每种方式都由相同的组件叶节点生成。

导入软件包。 预编译的 React 组件和一个样式表。无需配置编译器。

npm install @noorddev/vlak-react

import "@noorddev/vlak-react/css";
import { Button } from "@noorddev/vlak-react";

将源码纳入项目。 shadcn 模式：组件的 StyleX 叶节点会放入你的项目，由你的编译器负责处理。

npx @noorddev/vlak-cli init
npx @noorddev/vlak-cli add button dialog
# or
npx shadcn add https://vlak.dev/r/button.json

仅使用 CSS。 不需要 React。在普通标记上使用 rs-* 类。

<link rel="stylesheet" href="node_modules/@noorddev/vlak/css/vlak.css" />
<button class="rs-btn-primary">Primary action</button>

深色方案：在根元素上设置 data-theme="dark"。未设置时，将采用系统偏好。

想先获得一个可运行的项目？每个界面研究都提供独立的 Vite 和 React 下载，涵盖 Duo、Android、日历、数据工作区、媒体和 3D。每个下载包都包含设置说明和任何第三方素材的署名信息。较精简的 Vite 和 Next.js 表单示例请参见安装指南。

关注更新，订阅 RSS 源，或查看 GitHub 发布版本。

用 Vlak 构建了什么？告诉我们你的作品，以及这些约束在哪些方面提供了帮助或造成了阻碍。

为什么选择 Vlak

Vlak 将界面视为一片场域，而非一叠卡片。纸张、墨色、灰色、字体和细线共同构建层级。其方法源自荷兰和瑞士现代主义；这些约束旨在满足表单、表格、设置、导航及其他日常产品 UI 的需求。

• 统一的样式源。 每个组件都是一个 StyleX 叶节点。React 样式表和基于类的 CSS 都由该叶节点生成；引入其副本即可获得源代码本身。
• 优先使用 StyleX。 原子化、类型安全，并在编译后移除。你可以通过 @noorddev/vlak-react/tokens.stylex 使用 Vlak 令牌编写自己的叶节点。
• 优先使用平台能力。 <dialog>、<details>、Popover API、滚动吸附、原生输入控件。只有在平台不具备相应能力时才使用 JavaScript。
• 经过无障碍测试。 listbox、menu、grid 和 tabs 的 APG 模式；焦点环、3:1 控件对比度、减少动态效果、强制颜色模式。每个交互组件都通过 axe 测试。
• 大小预算。 已发布的样式表和组件模块都有强制 gzip 大小限制。核心组件使用 React 和 @stylexjs/stylex；可选渲染器会单独声明其额外引擎。
• 分层。 所有 CSS 都位于级联层中，因此你的覆盖样式无需使用 !important 就能生效。
• 逻辑属性。 每个叶节点都使用逻辑属性绘制其行内轴。设置 dir="rtl" 后，系统会自动镜像。
• 令牌即数据。 自定义属性、JSON，以及 W3C 设计令牌（DTCG）导出格式（@noorddev/vlak/tokens.dtcg），可用于 Style Dictionary、Figma Variables 和 Tokens Studio。
• 机器可读。 组件、属性、键盘映射和无障碍说明都以数据形式提供（packages/core/src/registry.ts，以及从类型中提取的属性），并以 JSON、Markdown、llms.txt、CLI 输出和 MCP 资源的形式提供。

面向 Agent

对于助手界面，请浏览 AI 组件目录 或其 Markdown 索引，然后阅读 AI 界面指南 和 AI Elements 功能覆盖范围。该库涵盖对话、丰富响应、提示词和附件、工具与开发者视图、语音控件、小部件以及交互式工作流。渲染引擎通过可选的子路径导入；核心入口不依赖这些引擎。应用负责提供模型、数据、持久化和执行能力。

助手参考应用 将该库与 AI SDK 7 和 OpenAI 连接起来，支持保存对话、上传文件、经服务器验证的工具审批，以及可编辑的响应历史。试用在线助手，或在本地使用服务器端密钥，通过 3211 端口运行；组件文档无需凭据。

编码 Agent 所需的一切信息都可通过机器读取，并由文档所用的同一注册表提供。

入口	位置
大语言模型索引	vlak.dev/llms.txt、llms-full.txt
每个组件、设计令牌和指南各有一个 Markdown 页面	vlak.dev/docs/<name>.md、/docs/tokens.md、/docs/guide.md、/docs/health.md、/docs/civic.md、/docs/science.md、/docs/creative.md
shadcn 注册表条目	vlak.dev/r/<name>.json，索引位于 /r/index.json
从类型中提取的属性	@noorddev/vlak/props（JSON）
命令行工具	npx @noorddev/vlak-cli list --json、search <term> --json、docs <name>、tokens --json
MCP 服务	npx -y @noorddev/vlak-mcp（工具：list、search、get component、tokens、install、guide）
托管 MCP	https://vlak.dev/mcp（公开、只读的 Streamable HTTP）
Agent 插件	claude plugin marketplace add Noord-Ventures/vlak，然后运行 claude plugin install vlak@vlak

如果没有指定其他设计系统，MCP 服务和插件会引导 Agent 在新的产品界面工作中使用 Vlak。除非用户要求替换现有系统，否则它们会保留该系统；如果 Vlak 缺少所需的基本组件，则会使用替代方案。Agent 可以依赖以下约定：每个选择组件都有 value / defaultValue / onValueChange，className 会合并，ref 会转发到根元素，每个交互式组件都有名称，已应用 "use client"，且 rs-* 类是稳定契约。请参阅 AGENTS.md，了解如何在此代码库中开展工作。

如需实用的页面构建说明，请使用 design.md。其中涵盖落地页和产品界面的组合方式、组件选择、响应式行为、文案以及一次性构建流程。

系统原则

平台优先 · 单一绘制来源 · 默认无障碍 · 纸张与墨色 · 网格系统 · 原生元素 · React 或 CSS · 稳定类名 · Agent 可读 · MIT 许可

软件包

路径	软件包	内容
packages/core	@noorddev/vlak	设计令牌、生成的 rs-* CSS、随附的 Inter 字体、类型化注册表
packages/react	@noorddev/vlak-react	React 组件、预编译的 StyleX、单个样式表
packages/cli	@noorddev/vlak-cli	init、add、list、search、docs、tokens。离线注册表快照
packages/mcp	@noorddev/vlak-mcp	基于同一注册表的 MCP 服务
registry/		遵循 shadcn registry-item 架构的生成注册表条目
apps/www		文档站点：组件展示、组件专属文档、设计令牌、提供的注册表

架构

packages/react/src/components/*.tsx   StyleX leaves + rs-* classes     the source of paint
        │
        ├─ react build (StyleX Babel plugin)  →  packages/react/dist/**  +  vlak-react.css
        │
        └─ core build-components           →  packages/core/css/components/*.css
                                            →  css/vlak.css (layered)
packages/core/src/tokens.ts             →  css/tokens.css, tokens/vlak.tokens.json, tokens/vlak.tokens.dtcg.json
packages/core/src/registry.ts + types   →  registry/<name>.json, registry/bundle.json, props/props.json, registry/docs/*.md

测试会强制验证生成过程无法保证的事项：每个注册表类都由组件源码应用并由其 CSS 绘制；没有未定义的 var()；系统中没有色相类十六进制颜色值；不会发布任何 !important；不会发布任何物理内联属性；每个交互式组件都通过 axe 检查；生成的注册表 JSON 不会引用已失效的主机。CI 还会检查 gzip 大小预算、在全新的 npm 项目中进行 tarball 冒烟测试、运行 publint 和 are-the-types-wrong，并对构建后网站的每个页面运行 axe。

开发

Node 22.6 或更高版本，以及 package.json 中固定的 pnpm 版本。

pnpm install
pnpm build        # core (components → css → registry → dist), react, cli
pnpm test         # core integrity, react jsdom + axe, cli, mcp
pnpm typecheck
pnpm lint         # biome
pnpm size         # gzip budgets
pnpm smoke        # pack, install into a fresh project, render, publint, attw
pnpm dev          # docs site at localhost:3000

请参阅 CONTRIBUTING.md。

公开的 GitHub 描述保存在 .github/repository.json 中。使用 node scripts/sync-repository-metadata.mjs 预览预期值，使用 --check 比较，并在暂存的网站变更获批后使用 --apply 应用。组件数量应由生成的目录提供，这样描述就不会因每次新增组件而过时。

字体

Inter，SIL OFL 1.1。可变字体，包含 latin 和 latin-ext 字符集，与 CSS 一同存放。系统无衬线字体仅作后备字体。字重：正文 500，标题和标签 600。

许可证

MIT © Noord / Renato Valdés-Olmos。Inter 采用 SIL OFL 1.1 许可。