Vibe Coding 执行可落地设计系统

不是让 AI 多写代码，而是让设计资产变成可执行能力。核心是一次 Vibe Coding 交流：围绕 XMax，把设计系统、组件库和页面组合规则整套装进一个 npm 包里，再交给 Codex 当成“原子手册”调用。这个案例里，我负责把设计判断、组件资产和 AI 协作方式组织成一套可复用交付系统：定义组件分层、页面模板、状态规则和 useWhen；用自然语言与 Codex 纠偏页面结构；把成功经验沉淀进 manifest、rules、recipes 和 npm 包，让 AI 先读规则，再用真实组件拼出风格统一的后台页面。

我的角色AI 协作设计系统方案负责人

负责组件分层、页面模板、规则表达、提示语纠偏和可复用交付方式组织。

业务问题AI 能生成页面，但不知道组件边界和验收标准

如果设计资产只停留在文档和视觉稿里，AI 与研发仍然要逐页猜组件、状态和页面结构。

关键动作把设计系统包装成 AI 可调用的原子手册

将组件、tokens、recipes、rules 和 starter 打包，让 AI 先读规则，再用真实组件拼页面。

产出价值让多页面产出风格统一、返工更少

把一次成功对话沉淀为后续项目可复用的规则资产，提升 AI 时代设计到开发的交付稳定性。

设计资产没产品化

设计系统如果只停留在 Pixso 和文档里，AI 只能靠描述猜；研发也仍然要逐页确认组件、状态和边界。

AI 不知道选择边界

同样是“做一个后台总览页面”，AI 需要知道该用 PageHeader、FilterPanel、DataGrid，还是普通 Table。

沟通需要共同手册

Vibe Coding 的有效交流不是“你随便发挥”，而是让人和 AI 共享同一套原子、组合和验收标准。

02 · XMax 概览

XMax · 给 AI 的原子手册

一个 workspace · 三个独立责任
组件包 / 展示场 / 起手模板

DEFINITION

把 设计系统/组件库/页面组合 整套装进一个 npm 包 —— AI 编码工具一键调，拼出来的页面 风格统一。

MODULE · 01
PUBLISHABLE

组件包

可发布的 @Xmax 包 · 对外暴露组件 / Provider / 样式入口。

组件 120+ 基础 · 60+ 区块 →

像 Pixso 里建好的组件库—— 按钮 / 表单 / 表格 / 图表 / Tabs / 详情头全封装好了。AI 拼页面时直接 import，不重新造。

主题 adaptive · Glass / Navy 双皮肤 →

一套 设计 token + 两种皮肤（Glass 玻璃 / Navy 商务）。切换整页同步换色，组件代码一行不改 —— 跟 Pixso Variables 切 Mode 一样。

文档 14 recipes + 5 rules →

给 AI 读的使用手册：14 篇组件选型决策表（按钮分级 / 弹层选 Dialog 还是 Drawer / 表格选 Table 还是 DataGrid …）+ 5 篇页面组合铁律（dashboard / data-table / form / layout / theme）。

CLI sync-rules · starter →

一行命令把规则同步到新项目（让 AI 在项目里也能读到 XMax 用法约束），另一行命令一键创建新项目—— 从 starter 模板出货。

MODULE · 02
SHOWCASE

Showcase 场

仓库内置展示站 · 验证组件组合效果 · 本地开发 即开即看。

Demos 7 个整页样例 →

真实业务场景的整页组合：工作台 / 财务 / 报表 / 权限 / 登录 / 资产详情 / 业务详情。全用 XMax 自己的组件搭出来，照搬当模板。

Pages 组件 catalog · 主题预览 →

一个目录式预览站 —— 所有组件分类摆出来 · 每个组件都有 demo + 用法说明。像 Pixso 里翻库组件那种体验，也能切主题看效果。

Docs recipes + rules 浏览器渲染 →

recipes 和 rules 的 md 文档在站点里直接渲染查看 —— 设计师 / 开发者直接在浏览器翻文档，不用去 GitHub 翻 md 源码。

Registry manifest.json 注册表 →

一个 manifest.json 文件，列出所有组件的身份信息：叫啥 / 用在哪 / 不用在哪 / 关联哪些规则。AI 接到任务时先查这个表挑组件，不靠猜。

MODULE · 03
TEMPLATE

Starter 模板

创建新项目的起手模板 · 一条命令 npm run create:starter 出货。

骨架 Vite + React + 路由 →

一个已经配好脚手架的空项目——路由、入口、构建、TypeScript 都准备就绪。新项目就在这上面盖楼，不用从零搭脚手架。

主题 adaptive-theme.ts →

项目级的自适应主题文件——由 AI 根据 PRD 调研（行业 / 品牌色 / 调性）自动填，生成项目专属 token + 设计画像。每个项目都有自己的皮肤。

示例 XMax 调用样例页 →

几个调用 XMax 的样例页（首页 / dashboard 等）——告诉开发者：怎么 import 组件、怎么包 Provider、一个标准 XMax 页面长什么样。

规则同步 AI 编码规则 →

把组件库的所有规则文档（XMAX-KIT.md + 14 recipes + 5 rules）同步到项目根目录，AI 在新项目里编码就能直接读 —— 不会跑偏写出违反约束的代码。

03 · 打开 NPM 包 · 架构

组件包 · 架构

点任一层展开看真实内容 + 它管的规则

7 页

真实业务 demo

60+

区块组件

120+

Codesign 原子

4 类

token 共用

2 主题

Glass / Navy

19 条

规则约束

地基TOKENS

Button

输入...

范

已通过

原子ATOMS

MetricCard

PageHeader

DataSection

ChartCard

区块BLOCKS

页面PAGES

04 · npm 包 · 完整清单

包里 · 都装了什么

@Xmax · v0.3.0
8 CATS · 14 RECIPES · 5 RULES

121 组件
8 大分类

23 AI 文档
4 手册 + 14 + 5

4 Provider
全局体系

2 分包入口 + CLI
按需引入

📦 @Xmax v0.3.0

├ ▾ src/

│ ├ ▾ kit/ ★ 核心目录 · AI 入口

│ │ ├ M AGENTS.md 构建指南 · UI/token 唯一来源

│ │ ├ M DEMO-KIT.md AI 使用规则 · 接入流程

│ │ ├ M DESIGN-SYSTEM.md 设计系统规范

│ │ ├ M AI-USAGE.md 组件选型手册

│ │ ├ { } components-manifest.json 组件注册表 · AI 挑组件的入口

│ │ ├ ▾ components/ 121 8 大分类

│ │ │ ├ ▸ composite/ 62 复合区块 · PageHeader / MetricCard ...

│ │ │ ├ ▸ form/ 16 表单 · Button / Input ...

│ │ │ ├ ▸ data-display/ 13 Table / DataGrid / AdvancedDataGrid ...

│ │ │ ├ ▸ feedback/ 12 Dialog / Drawer / Sheet / Toast ...

│ │ │ ├ ▸ navigation/ 7 Tabs / Breadcrumb / Pagination ...

│ │ │ ├ ▸ layout/ 6 Layout / Grid / Stack ...

│ │ │ ├ ▸ decorative/ 4 Separator / Divider ...

│ │ │ └ ▸ chart/ 1 ChartCard

│ │ ├ ▸ recipes/ 14 选型决策表 · button-hierarchy / table-vs-data-grid ...

│ │ ├ ▸ rules/ 5 拼装铁律 · dashboard / form / layout / theme / data-table

│ │ └ ▸ tokens/ chart-palette · token 定义

│ ├ ▾ app/ 4 应用壳层 · 项目"开箱即用"骨架

│ │ ├ ⌜⌝ demo1-shell.tsx ★ 后台 Shell · sidebar + topbar + 内容区

│ │ ├ ⌜⌝ container.tsx 标准页内容容器 · flex / gap / padding

│ │ ├ ⌜⌝ background-decor.tsx 背景装饰层 · 渐变 / 网格 / 玻璃质感

│ │ └ ⌜⌝ tweak-panel.tsx 主题调色面板 · 用户人工微调入口

│ ├ ▾ providers/ 4 全局 Provider 体系

│ │ ├ ⌜⌝ xmax-provider.tsx 主 Provider · 应用入口包一层

│ │ ├ ⌜⌝ settings-provider.tsx 设置状态 + 主题持久化

│ │ ├ ⌜⌝ theme-provider.tsx 主题占位 (pass-through)

│ │ └ ⌜⌝ tooltips-provider.tsx Radix Tooltip 全局 (delay=0)

│ ├ ▾ cli/

│ │ └ JS xmax.js CLI · sync-rules / create:starter

│ ├ ▸ css/ styles.css · components/ · demos/

│ ├ ▸ config/ settings.config.ts + types.ts

│ ├ ▸ lib/ utils.ts

│ ├ TS index.ts ★ 主入口 · @Xmax

│ └ TS enterprise.ts ★ 企业级分包入口 · /enterprise

├ ▸ dist/ 构建产物

├ { } package.json name / exports / bin · 分包入口在这里声明

REPO SIBLING · CLI 引用

└ ▾ templates/starter/ ★ 起手模板 · create:starter 复制的就是这个

📂

composite/

复合业务区块

这是什么

大块业务组件 — 业务页面直接拼这些，不用从原子组装。

类比 Pixso

像 Pixso 设计稿里 "页面头部 / 卡片组 / 筛选面板 / 看板" 这种已经组好的 frame。

代表组件

PageHeader · MetricCard · FilterPanel · DataSection · DetailHeader · KanbanBoard · LoginCard · ApprovalFlow · ContractCreationForm · ...

05 · 一个场景 · 看清整条路径

做一个后台总览页

每一步 AI 读什么 · 决定什么 · 直到生成代码
AGENTS.md → MANIFEST → RULES → RECIPES → IMPORT

PROMPT → 做一个 后台总览页面 · 含筛选+图表

01 读 AGENTS.md 入口手册 AGENTS.md

# XMax · 构建指南## 总览页流程1. PageHeader（标题 + 时间范围） 2. FilterPanel / MetricCard 3. DataSection + ChartCard / MapChart

↳ AI 识别 · 这是后台总览页 archetype · 套用指标 + 图表骨架

02 扫 manifest.json 看全景 components-manifest.json

{ "name": "PageHeader", useWhen: ["页面标题", "时间范围"] } { "name": "FilterPanel", useWhen: ["多字段筛选"] } { "name": "MetricCard", useWhen: ["核心指标概览"] } { "name": "ChartCard", useWhen: ["趋势图表","地区分布"] }

↳ AI 候选 · 4 个组件命中 useWhen · 进入图表布局选型

03 查 rules/layout.md 定骨架 rules/layout.md

## 后台总览骨架1. PageHeader 2. FilterPanel 或 FilterToolbar 3. MetricCard 指标区 4. DataSection + ChartCard / MapChart

↳ AI 组合顺序 · Header → Filter → Metrics → Charts

04 查 recipes/dashboard-charts.md 选型 recipes/dashboard-charts.md

## 总览图表组合- KPI 用 MetricCard - 趋势用LineChart / BarChart - 区域分布用MapChart

↳ AI 决策 · 重点是扫数据趋势 → 选 ChartCard（不是表格）

05 barrel import 真模块 · 拼 JSX @Xmax

// 从 npm 包一次性 import 总览组件 // 类型 / Provider / token 自动接上 import { PageHeader, FilterPanel, MetricCard, ChartCard, MapChart } from \'@Xmax\'

↳ AI 输出 · 完整 tsx 文件 · 编译即可运行 →

overview-page.tsx AI 生成 · 直接 import 真组件

import {
            PageHeader,
            FilterPanel,
            MetricCard,
            ChartCard,
            MapChart,
          } from \'@Xmax\'
          
          export const OverviewPage = () => (
            <Layout>
          
              <PageHeader
                title="后台总览"
                actions={<Button>导出报表</Button>}
              />
          
              <FilterPanel>
                {/* 区域 / 产品线 / 时间范围 */}
              </FilterPanel>
          
              <MetricCard.Group
                items={overviewMetrics}
              />
          
              <ChartCard
                title="销售趋势"
                series={salesTrend}
              />
          
              <MapChart
                title="区域概览"
                data={regionData}
              />
          
            </Layout>
          )

06 · 设计系统 · 从 0 搭

设计系统 · 从 0 怎么搭

6 步流水线 · 悬停看每一站在做什么
DEFAULT · 01 · CODESIGN

01 · FOUNDATION · CODESIGN

原子件 · 直接用 Codesign

Button Input Select Dialog Drawer Switch Checkbox Radio Tabs Avatar Badge Tooltip Popover Toast Calendar Slider Progress Skeleton Separator Accordion … +100

$npx Codesign@latest add button input

不亲手写 · AI 一行命令 generate
变体接 token · 跟主题联动
能改 · 代码在项目里 · 不是黑盒

02 · TOKENS · 变量

一套变量 · 串起原子 / 组件 / 页面

颜色 · COLOR

6 语义色 · 各 5 阶

primary#009ef7

info#8950fc

success#1bc5bd

warning#ffa800

danger#f64e60

字号 · TYPE

4 级 · 字号 + 行高

Aatitle-128 / 36

Aatitle-222 / 30

Aabody14 / 22

Aacaption12 / 18

间距 / 圆角 · SPACING

8 的倍数 · 守 grid

sp-14 px

sp-28 px

sp-416 px

sp-624 px

radius-md8 px

03 · COMPOSITE · 核心

复合组件 · 3 个来源拼进 XMax

直接聊 AI

从 0 起 prompt · 现做现要

做一个后台总览页面

好的 · 生成中 OverviewPage.tsx · 已接 token

Pixso 还原

设计稿 · 1:1 落地

PIXSO · FRAME

→

REACT · JSX

开源包装

站在巨人肩膀 · 包一层

AG Grid React Hook Form Recharts

↓ 包装 ↓ @Xmax · DataGrid / Form / Chart

04 · PAGES

用原子 · 拼 7 个真实 demo

工作台

财务

报表

权限

资产详情

业务详情

+ next

05 · RULES · 3 来源

规则 · 3 个来源沉淀进 XMax

AI 自己写出

生成过程中 · 把决策路径写回 .md

AI 选了组件 / 拼了结构 · 把"为什么这么选"记下来

跨页面通用的决策 · 提炼成 recipe 草稿

例 · button-hierarchy.md / table-vs-data-grid.md 的初稿

自我沉淀 · 下次 AI 读到自己写的

拼页面过程中沉淀

7 个 demo · 反复踩坑 · 实战驱动

列表页总漏空态 → empty-loading-error.md

详情页布局乱 → layout.md / 详情页骨架

Dashboard 指标过多 → dashboard.md (3-5 个上限)

来自问题 · 不是闭门造车

我直接给

设计师 / 项目负责人 · 硬约束

项目契约 → AGENTS.md (import 路径 / 禁用清单)

禁止 hex 颜色 · 走 token → theme.md

禁用 raw <table> / <canvas> → 入口手册

价值观 · 顶层约束 · 不可改

06 · DELIVERY · NPM

整套打成包 · 一行 install 就齐

@Xmax

v0.1.x ESM only React 18+ 2.4 MB gzip

$npm install @Xmax

$npx xmax sync-rules

INCLUDED

组件 · 120+ 原子 / 60+ 区块
主题 · Glass / Navy 双皮肤
文档 · 14 recipes + 5 rules
CLI · sync-rules · starter

主页示例效果·0手搓

06 · AI 用组件库 · 两种路径

知识 · 还是 · 能力

Skills 路径 · 把组件说明书、示例、源码片段放进资料库，让 AI 看着资料自己搭
XMax 路径 · 把组件做成真实原子装进工程，再给 AI 一份搭建手册

点击切换视图

维度

PATH A Skills 路径

PATH B XMax · NPM + AGENTS.md

加载模型

触发式 · 关键词命中后才进上下文

入口式 · 先读 AGENTS.md，再按 manifest 找组件

组件身份

文本片段 · usage 文档 + 源码示例

真实模块 · 可 import 的运行时组件

组件发现

AI 根据 prompt + skill 内容推理该用什么

AI 先扫 manifest 看组件全景，再按场景挑

页面组合

主要靠 AI 自己判断页面结构

rules / recipes 显式指定组合顺序

规则强度

软约束 · 文档建议，AI 看着办

工程约束更强 · TypeScript / Provider / 编译能暴露问题

跨项目分发

拷贝 skill 文件 / 配置

npm install 一行接入 · 版本化维护

主要价值

告诉 AI 规则、流程、判断方法

给 AI 可调用、可运行、可维护的组件能力

PATH A Skills 路径

AI 从内置经验起手 根据 prompt 推理页面结构

关键词触发 skill 加载 命中的 skill 进入上下文

基于已加载内容组合 layout 页面结构主要靠 AI 自己判断

参考 skill 文档描述选组件 用法、边界、组合依赖文档理解

以源码片段为参考生成代码 可能模仿组件，也可能重新写

PATH B XMax · NPM 路径

AI 先读 AGENTS.md 入口手册 明确生成流程、组件来源、使用边界

扫 manifest.json 看全景 121 组件中识别 4 个候选（PageHeader / FilterPanel / DataSection / DataGrid）

查 rules/layout.md 显式结构：Header → Filter → Section → Grid

查 recipes/table-vs-data-grid.md 决策表给出选型结果

barrel import 真实模块 从 @Xmax 调用真实组件