文档 · 组件管理

组件资产管理规范

轻量契约：状态机、注册上架下架更新调用，以及详情页模板最小集。开源使用者按此理解 Daren Design 如何规范管理组件。

这篇文档解决什么问题

开源项目或二次分发时，需要说清：组件在 Daren Design 里如何从候选变成可调用资产，设计站又扮演什么角色。本文给出一套轻量契约——一张状态机 + 详情页模板最小集——对齐 UI Distiller 的「入库 ≠ 上架」分权，避免站点手改上下架成为第二真源。

本文是管理约定。实现细节以仓内 Registry、技能真源（SKILL.md）与设计站投影代码为准；若与机器可读清单冲突，以真源与回执为准。

权威边界（先立规矩）

角色	做什么	不做什么
组件库真源（`daren-design` 源码 + Registry）	代码实现、清单字段、成熟度	不当成页面 CMS
UI Distiller	拆解 → 复刻 → 适配 → 入库 → 上架；分权、分回执	不默认公网部署
设计站	投影目录、详情页、预览	不手改「上下架」当权威；不反向改真源

一句话：站点只展示；注册与上架以 Registry 写入与 Distiller 回执为准。

状态机（五档）

状态描述的是资产在治理上的位置，不是 npm 版本号。版本发布仍走常规 SemVer / 发行说明。

candidate → registered → published → stable → deprecated
 蒸馏中      已入库        设计站可见    黄金样板门过   下架可见但禁新用

状态	含义	谁推进	设计站表现（约定）
`candidate`	蒸馏 / 适配中的候选，尚未完成入库门	Distiller 生产链	默认可不进公开目录
`registered`	已写入 Registry，持有入库回执	`design-asset-registrar`（入库技能）	真源可读；未上架则站点可不生成详情
`published`	持有上架回执，设计站已投影	`design-asset-publisher`（上架技能）	目录与详情页可见
`stable`	通过黄金样板门（方案 B 硬门绿：矩阵 + 轻量 check；`code↔preview` 就绪后并入）	人工 + 机读门禁	可作为默认推荐与对外范例
`deprecated`	下架：保留页与迁移说明，禁止新调用	治理决策 + 清单更新	侧栏可筛选；页保留并标废弃

与 Distiller 阶段的对齐

生产动作本身是：dissect → replicate → adapt → register → publish（质检可横向插入）。其中：

register 只推进到 registered，交付入库凭证。
publish 才推进到 published，接入指定站点的目录、详情与预览。
入库与上架必须分别授权、分别出具回执——禁止「写进仓库就当已上架」。

当前清单字段的关系

Registry 里已有 maturity 等字段（例如 candidate、source-ready、captured），描述的是资产成熟/来源档，与上表的治理状态相关但不必一一同名。落地时建议：

治理状态（本文五档）作为对外管理语言与站点 badge 的主轴；
清单 maturity 继续服务机器可读投影；
映射表在实现门禁时单列，避免两套词混用。

流程：注册 / 上架 / 更新 / 下架 / 调用

注册（Register）

候选通过适配与约定校验。
写入 Registry（及相关源码归位）。
产出入库回执（Registration Receipt）。
状态 → registered。

失败场景：只有 PR、没有回执却宣称「已入库」——下游无法审计，禁止。

上架（Publish）

以新鲜入库凭证为输入（无凭证不上架）。
接入设计站目录、详情路由与预览构建。
产出上架回执（Publication Receipt）。
状态 → published。

失败场景：只在侧栏加链接、不改 Registry / 无回执——站点与真源漂移。

上架不默认等于公网部署或 npm 发版。

更新（Update）

在真源改实现与契约。
重建设计站预览 / 详情运行时产物。
必要时更新清单字段与治理状态（例如从 published 回到待验，或 bump 至 stable）。
Breaking 变更走发行说明与迁移指引，不静默改 stable 语义。

下架（Deprecate）

状态 → deprecated。
详情页保留，写清替代组件与迁移步骤。
侧栏可过滤「已废弃」；不删历史页（外链与书签仍可抵达）。
文档与类型层面标记禁新用；运行时警告按宿主能力可选。

失败场景：直接删路由当「下架」——外链 404，迁移不可追溯。

调用（Consume）

通道	做法
应用代码	从 `@daren-design/...`（或项目公布的包入口） import / `add`
设计站	只浏览、复制示例；不是安装源
Agent / Lattice	消费已注册资产与契约；以清单与回执为准

详情页模板最小集

published 即可上站；升到 stable 必须过黄金样板门。区块分两类：给人看的投影，和给机器拦漂移的门。

区块	`published`	`stable`（黄金样板）	性质
标题 + 一句话职责	必填	必填	人读
基础样式	必填	必填	人读；主样式轴矩阵，须对齐机读声明
样式变体	可选	可选（有次轴才写）	人读；扩展样式轴，见下节「何时拆分」
尺寸变体	可选	可选（有尺寸轴才写）	人读；`size` 等尺度轴，有才成区
状态矩阵	建议	必填；关键格可附白话脚注	人读；交互态（含禁用等）
场景示例	建议	必填	人读；示例 id 须登记在矩阵里
验收矩阵 schema（机读）	建议有草稿	必填且门禁绿（stable 硬门）	机器校验；见下节

形态变体若组件有独立轴，同样作为建议区（与现网详情页对齐），不抬升为 stable 硬门，除非该组件的主消费路径依赖它。

试点组件（Button / Input / Select / ColorPicker，下称四金刚）优先按 stable 硬门验收；其他组件可先 published，再按需抬门。

基础样式 vs 样式变体：要不要拆

要拆，但只在「样式轴变多」时拆——不是每个组件都开两个区。

	基础样式（必填）	样式变体（可选）
装什么	主样式轴——用户选组件时最先要认的那一维（多数是 `variant`：主按钮 / 次级 / 危险…）	次样式轴或扩展皮肤——主轴之外还会改「长什么样」的维度（如语气 tone、密度、线框/填充二级皮肤、品牌扩展色…）
矩阵怎么排	主轴 ×（必要时尺寸）的紧凑矩阵，默认进首屏	按次轴单独成区；禁止把所有轴做全笛卡尔积塞进「基础样式」
何时出现	凡上架组件都有	仅当存在第二（及以上）样式轴，或主轴格子已经很多、需要把扩展皮肤挪出首屏时

判断口诀：

只有一维样式（例如就 variant 五六个）→ 只写「基础样式」，不要空挂「样式变体」。
两维及以上样式（variant + tone / appearance / …）→ 主轴进基础样式，其余进样式变体。
主轴格子已经很多（经验阈值：单区 roughly > 8～12 格就难扫）→ 保留主轴核心格在基础样式，扩展组合挪到样式变体，并在矩阵里对未展出的组合显式 waive 或指向场景示例。

失败场景（不拆清）：

把「基础样式」写成万能筐，Button 主轴和各种皮肤挤一屏 → 黄金样板不可扫，Agent 也不知道哪维是契约主轴。
每个组件都强制开「样式变体」空区 → 噪音，和「可选」矛盾。

与现网详情页用语的关系：现网「基础样式 / 状态变体 / 形态变体 / 尺寸变体」可渐进对齐——状态变体 → 状态矩阵（本文）；「样式变体」是新增可选区，有次轴再加，不要求立刻改所有旧页标题。详情页不设「用法要点」「验收散文」区块——约束进验收矩阵，说明进标题/场景，不另开散文门。

验收矩阵 schema（建议方向）

目标：一份组件级、可机读的「该页声称什么」清单，用来校验详情页与示例是否放漂移——不是再写一篇验收说明文。

最小字段建议（落地时可 JSON / YAML，与 Registry 或详情元数据同仓）：

字段	作用
`component`	组件 id / 路由 slug
`sections`	区块声明：`basic`（必）/ `styleVariants`（可）/ `sizes`（可）/ `states` / `scenes`…
`basicAxis`	基础样式主轴取值列表（须与页面「基础样式」格子对齐）
`styleAxes[]`	样式变体次轴（可选；有区才有）
`sizes[]`	尺寸变体轴（可选；有区才有）
`states[]`	状态矩阵轴声明
`examples[]`	`{ id, section, covers?: { basic?, style?, state? } }`
`nonGoals[]`（可选）	短标签级「不做」——给 Agent/人扫一眼，不作长文
`gates`	引用既有门与 stable 硬门：轻量矩阵 check →（就绪后）`code-preview`；以及 `tokens:lint` / `conformance` 等

校验规则（先做能自动的，再扩）：

声明覆盖：basicAxis（及可选 styleAxes / sizes）与 states 在对应 section 有格子或显式 waive。
示例登记：页面每个场景示例有 id，且出现在 examples[]。
与真源对齐：轴取值不得超出组件 cva / props 契约（有则对；无则先对页面自洽）。
code↔preview：优先「preview 派生 code」或专用一致性 lint；纳入 hard gate 前，矩阵至少锁住「有哪些示例、覆盖哪一格」。

失败场景（若不做矩阵）：

加了一个场景示例，页上好看，门全绿，但没人发现缺了 disabled 格或 code 写了不存在的 prop。
用长文「验收说明」顶替机读矩阵 → 约束不可执行，stable 名存实亡。

与现有门的关系：矩阵补洞，不取代 tokens:lint / conformance / design-harness。章程口径仍是——规则没配门 = 只是建议；配进本节硬门清单后 = 拦 stable。

stable 硬门（方案 B，已拍板）

升到 stable 必须走完下列节奏；未完成不得宣称黄金样板 / stable。

阶段	交付	是否硬门
1. 契约	本页模板最小集 + 矩阵字段约定（已落文）	契约真源
2. 四金刚矩阵 + 轻量门	Button / Input / Select / ColorPicker 各一份矩阵草稿；机器 check：`pnpm acceptance:check`（缺必填 section、缺 `data-example-id` / 契约 id 互缺）→ fail	是（stable 必绿；Button 已接线）
3. code↔preview	从 preview 派生 code，或专用一致性 lint	是（就绪后并入 stable 必绿；未就绪前不得用散文顶替）

执行约定：

published 可以没有绿门，但不能标 stable。
四金刚是第一条纵切：先把门跑通，再扩到其他组件。
轻量门只拦「声称与登记」；视觉回归、交互 UAT 仍按既有流程，不塞进这一道。
code↔preview 未上线前，stable 仍以阶段 2 为准；阶段 3 一旦合入主链，自动成为 stable 硬门增量，无需再改治理叙事。
禁止用用法要点、验收散文等叙述顶替阶段 2 / 3 的机读门。

站点投影规则（给实现者）

目录与详情页由 Registry + 上架回执生成或校验，禁止纯手写「上下架开关」当权威。
Badge / 筛选标签映射治理状态（可用 Storybook 式 tag，但 tag ≠ 发布系统）。
设计站不得 import Distiller / Lattice 实现细节冒充真源；只读投影约定。

开源使用者怎么用这套规范

只消费：按「调用」一节从包入口使用；看设计站了解 API 与场景，不把站点当安装源。
贡献组件：走 Distiller 或等价流水线 → 入库回执 →（可选）上架回执 → 再谈 stable。
** fork / 自建设计站**：可复用本状态机与模板最小集；上下架权威仍放在你的 Registry，而不是页面配置。
不要：在文档站 CMS 里单独维护一套「已上架列表」而不同步清单。

刻意不采纳的做法

做法	原因
独立组件云市场 + 软删除 API（类 Bit 全量）	成本高，与「仓内真源、站点投影」冲突
站点手改可见性 = 上架	必漂移
八级以上状态	难执行；五档已覆盖 Distiller 分权