企业官网建设流程全解析

Astryx 设计规范体系（Design Specifications）完全指南：从状态分类学到组件视觉契约的权威入口

【免费下载链接】astryxAn open source design system that's fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx

设计规范（Design Specs）是 Astryx 开源设计系统中记录人类视觉与交互意图的权威知识载体。它负责沉淀层级（hierarchy）、解剖结构（anatomy）、状态表达（state representation）、允许的变化范围（allowed variation）以及代表性示例（representative examples），既可描述单个组件，也可描述跨组件的模式。本文将围绕仓库根目录下的 docs/design/README.md 展开，系统梳理该目录下的完整设计记录体系：三份状态分类学记录、九份其他设计记录，以及它们与架构记录、组件契约、模板、审批门禁之间的关系。读完本文，你将掌握 Astryx 设计规范的分类逻辑、每条记录的具体内容边界、起草与提升（promotion）流程，以及如何在贡献时正确引用稳定设计需求 ID，而不是复制其论证过程。

一、设计规范在 Astryx 知识体系中的定位

Astryx 将"人的意图"与"机器的实现"严格分离。设计规范只记录人类拥有的视觉与交互意图，而实现机制（implementation mechanics）、公共 prop 语法（public prop syntax）、当前审计结果（audit results）与消费方使用指南（consumer usage guidance）一律不属于设计规范的所有权范围——这些内容应链接到各自的规范所有者（canonical owners）。

这一点在每条设计记录末尾的 "Content boundary"（内容边界）一节中被反复强调。例如：

• user-states.md 明确"不定义 prop 名、选择器、ARIA 属性、焦点管理机制、token 名、组件行为、审计结果或消费方指南"；
• system-states.md 明确"不定义 prop 名、ARIA 属性、加载语义、关闭或定时行为、token 名、审计检查或消费方用法"。

同时，组件契约（component contracts）与家族契约（family contracts）只链接到稳定的设计需求 ID（如design:user-states/DR1），而不会复制其论证过程。这意味着设计规范是整个知识图谱中"视觉意图"的唯一事实源，其他记录通过引用而非复制来复用它。

每条记录都遵循统一的 design-spec.md 模板 结构：YAML 前置元数据（schema_version、kind、id、authority、owners、review_triggers、architecture、components、families 等）加固定章节（User intent、Design principles、Anatomy and hierarchy、State representation、Responsive and input behavior、Accessibility intent、Representative examples、Visual references、Component contract links、Decision log、Open questions、Content boundary）。模板版本由 docs/templates/knowledge/versions.json 登记，其中design模板的当前版本号为1；而 docs/schemas/knowledge/v1.json 定义了kind: design记录必须遵守的元数据与章节约束。

二、状态分类学（State Taxonomy）：三条记录划定全部状态所有权

设计目录中状态记录按驱动者是谁来切分，且整个仓库只有三种状态分类学记录：

2.1 User states：人驱动的完整交互闭环

user-states.md 要求每个可交互组件必须完整覆盖 rest（静止）、hover（悬停，如可用）、focus（焦点）、press/activation（按压/激活）以及相关选中状态。其四条设计原则中，DR1 强调"每个意图必须先复用既有表达，然后才允许引入新视觉"；DR2 要求设计完整的用户驱动交互循环；DR3 主张家族一致性优先于系统级表面统一——组件应选择契合其交互原型（archetype）的表达，并与兄弟组件保持一致；DR4 规定选中（selection）是同一个意图但允许按原型差异化表达（toggle、segment、导航、卡片、行各有各的表达）。

解剖结构表定义了 5 个稳定角色：base surface（基础表面，在任何瞬时状态处理下仍可识别）、interaction overlay or ring（交互覆盖层或环，只添加反馈、不替换内容或语义）、focus indicator（焦点指示器，有且只有一个清晰所有者，且与 hover、selection 区分）、selection indicator（选中指示器，契合原型并在交互结束后保持稳定）、content（内容，在瞬时与持久状态下保持可读）。

状态表达表则按原型细分了允许的变化：

• rest：使用基础角色 token，主题控制视觉性格；
• hovered（surface 原型）：安静覆盖层改变表面但保留基底；hovered（field 原型）：边框或内嵌处理让字段边界更明显；
• pressed：即时的触觉压缩或更强的表面反馈；
• focused（action 原型）：清晰分离的外部指示器；focused（field 原型）：强调边框 + 内嵌处理，复合字段可绘制在拥有者包装器上；
• selected 有五种原型表达：filled（紧凑二进制控件填充，用于 checkbox/radio/switch）、surface（活动段从轨道中分离，用于分段选择）、edge（边缘或下划线标记当前目标/步骤，用于 tab、条目、有序进度）、border（选中容器获得清晰边界，用于可选卡片）、depressed（持久安静填充，用于导航行、列表行、切换按钮）；
• reordering 状态由design:ordered-collection-reordering拥有，仅适用于带专用手柄的有序集合。

该记录还提出三个开放问题（OQ1：每种 hover/focus/selection 原型的规范示例组件；OQ2：哪些已发布组件有意使用不同状态表达，以及例外归家族还是归本记录所有）。

2.2 System states：系统驱动反馈的五条铁律

system-states.md 面向不可用、等待、处理、成功、警告、信息与错误等条件。DR1 要求加载/处理/状态表达必须保留受影响组件足够的几何与身份；DR2 要求每个语义状态必须给颜色配上图标、标签或其他非颜色信号；DR3 规定突出度（prominence）跟随持久性与紧急性——持久流内反馈保持安静紧凑，紧凑或紧急反馈可用实心处理，短暂瞬时反馈可用反转覆盖层；DR4 强调改变突出度不得改变底层语义；DR5 要求忙碌状态不得造成布局位移。

解剖角色包括 affected surface（保留足够几何以维持上下文）、progress representation（匹配等待的范围与时长）、semantic indicator（颜色 + 图标/标签成对）、supporting message（解释原因、后果或下一步）、prominence container（把反馈从流内缩放到瞬时，且不改变语义）。

状态表达表给出：

• disabled：弱化、明显不可用且不可交互，需要时保留原因；
• loading/placeholder：稳定的骨架或结构占位；
• processing/in place：进度指示器不改变控件尺寸；
• status/muted：安静的语义表面（颜色 + 图标/文本），用于持久 banner、字段、流内反馈；
• status/solid：高突出语义填充 + 对比内容，用于紧凑标签或紧急反馈；
• temporal overlay：短暂反转表面叠加在当前内容之上并自动消失。

三条行为原则强调：反馈在重排（reflow）下保持附着（DR6）；瞬时反馈的可操作性不被响应式布局破坏（DR7）；减少动效模式下忙碌反馈仍要表达"工作未完成"（DR8）。

2.3 Agentic states：面向 Agent 的待决设计面

agentic-states.md 是最特殊的一条记录——它有意不批准任何单独的 Agent 状态视觉处理，只命名未解决的设计面。其用户意图是：与 Agent 协作的人应能理解它正在推进、等待、检查、同步还是呈现结果，而无需学习第二套无关的状态语言；Agent 反馈应传达可操作的系统状态，不得暴露私有或隐藏推理。

它目前只批准了一条原则：DR1 — 先扩展现有状态语言。当底层意图相同时，Agent 状态应复用design:user-states与design:system-states的表达。它提出的 8 个开放问题是理解 Agent 化界面设计的关键清单：

• OQ1 — Thinking or processing：Agent 工作何时需要区别于普通系统处理的表达？
• OQ2 — User-visible rationale：什么处理能区分"有意撰写的解释"与普通输出，又不暗示访问隐藏推理？
• OQ3 — Streaming：增量文本如何保持"可见地未完成"而不干扰已有文本？
• OQ4 — Tool execution：后端工作的哪些信息对人有价值，何时应保持折叠？
• OQ5 — Awaiting input：必需的人类响应如何超越被动进度，同时保留任务上下文？
• OQ6 — Synchronizing and synchronized：待同步与已同步如何区别于泛化处理与成功？
• OQ7 — Inspecting：Agent 检查是否需要独立状态，还是普通进度 + 限定上下文就足够？
• OQ8 — Rendering：生成的 UI 如何沟通部分挂载与完成，而不暴露实现抖动？

该记录明确不要求披露隐藏的 chain-of-thought；任何用户可见的推理内容都属于产品内容，须遵守各自的隐私、安全与内容契约。

三、其他九条设计记录：跨组件模式的视觉意图

3.1 Spatial hierarchy（空间层级）

spatial-hierarchy.md 主张"先读标签之前人就应理解什么属于一组"——密度高的表面靠邻近度表达关系而非靠更多容器包裹。四条原则：邻近传达关系（DR1）、间距随分组层级增长（DR2）、空间先于容器（DR3，先靠间距与对齐分组，再考虑加卡片/边界）、变化是有意的（DR4，用足够空间对比揭示层级）。解剖角色按 gap 层级划分：local gap（标签-值-图标到相邻内容）、group gap（同级控件或内容组）、section gap（不同关注区，必须强到能通过"眯眼测试"）、alignment edge（跨行跨区连接相关内容）。

3.2 Control rhythm（控件节奏）

control-rhythm.md 解决混合控件组合的观感问题。DR1 要求同行固定高度与内容自适应控件共享有意的基线与非表观高度；DR2 要求外部尺寸与内部内边距作为一个整体节奏来评估；DR3 要求文本与图标保留足够呼吸空间；DR4 是精髓——视觉尺寸与目标尺寸服务不同需求：控件可以看起来紧凑，同时保留与输入上下文匹配的可操作目标。解剖角色有 fixed control、content-sized control、content lane、target area（可超出可见轮廓而不破坏布局）。

3.3 Shape relationships（形状关系）

shape-relationships.md 要求嵌套表面读起来是同一个有意识形状的一部分。DR1 角特征必须反映元素角色（内部内容/控件/容器/页面区域/全圆角表单）；DR2嵌套曲线保持同心——内外角在计入间距后应读作平行形状；DR3 形状特征应是系统性的（主题整体调尖锐/圆润，而非逐个覆盖）；DR4 强调边框与边缘强调必须与角形状整合而非碰撞。

有趣的是，仓库中的圆角 token 正是按角色分层设计的。tokens.stylex.ts 定义了从内到外的完整半径梯度：--radius-none: 0px、--radius-inner: 4px、--radius-element: 8px、--radius-container: 12px、--radius-page: 28px、--radius-chat: 28px（聊天表面刻意比同视图卡片更圆，独立 token 以便独立主题化，见注释引用的 #2072）、--radius-full: 9999px。这套"内层内容 < 控件 < 容器 < 页面 < 全圆角"的角色化半径正是 DR1 在 token 层的落地。

3.4 Elevation hierarchy（高程层级）

elevation-hierarchy.md 要求"看起来更高的表面必须在行为上也作为更高层"。DR1 感知与实际顺序一致；DR2 深度保持安静（阴影/边缘不应成为主导视觉）；DR3 每个表面应优先采用一种边界语言（明确边缘或柔和抬升，而不是两者全强度叠加）；DR4 状态环不是抬升——输入与焦点环必须与传达层深的阴影视觉上区分。解剖角色包括 base content、floating surface、boundary cue、escape path（让浮动表面保持可见，防止被下层容器意外裁剪）。该记录将堆叠机制委托给 architecture:layer-runtime，后者是current权威记录，管辖 packages/core 下 Layer、Popover、Dialog、DropdownMenu、Tooltip、HoverCard、Toast、CommandPalette 等浮层组件及其焦点陷阱与菜单悬停逻辑。

仓库中的阴影 token 同样按强度分层（tokens.stylex.ts）：外置抬升阴影--shadow-low→--shadow-med→--shadow-high强度递增；而--shadow-inset-hover/selected/success/warning/error是一组内嵌阴影，专用于输入框状态环（交互与校验状态）——这与 DR4"状态环不是抬升"的设计意图完全对应：状态环走 inset 通道，层深走 outer 通道，两条视觉通道互不混淆。

3.5 Typography hierarchy（排版层级）

typography-hierarchy.md 要求标题、正文、标签、代码与辅助文本"明显不同"，让人能快速对表面做分诊。DR1 类型角色传达目的；DR2 相邻角色保持可区分（靠尺寸、字重、位置或有意的组合）；DR3 多行文本保留舒适行高与行长；DR4 主题个性保留语义——主题可以调刻度与密度，但标题/正文/标签/辅助角色的相对意义必须保留。解剖角色表定义了 display or page heading、section heading、body、label、supporting text、code or data text 六个角色的目的与关系要求。开放问题 OQ1 指出源材料的默认刻度与相邻步进层级"气味"使用了不同比例，提升前需协调意图与审计检查。

3.6 Color emphasis（颜色强调）

color-emphasis.md 关注"主操作在哪里"与"表面/状态角色是什么"。DR1 前景与背景是同一个决策；DR2 中性色跟随语义角色；DR3强调保持稀缺——局部操作组应暴露一个清晰主强调，而不是让每个操作同等竞争；DR4 状态遵循design:system-states的规范反馈契约；DR5 交互覆盖层保留上下文（hover/press 与底层表面视觉融合而非替换）。解剖角色：base surface、foreground、interaction tint、primary accent（必须视觉上强于同级操作）。仓库主题 token 中可见其落地痕迹：例如 tokens.stylex.ts 的颜色阴影使用light-dark()双模式值，保证浅色/深色模式下前景-背景对比保持。

3.7 Motion（动效）

motion.md 要求"动效解释变化，而不是装饰"。DR1 动效携带意义；DR2 重量决定时长（小的局部反馈应比大的进场/离场/连续运动更快）；DR3 运动自然收敛（缓动传达受控减速而非装饰性回弹）；DR4 稳定内容保持稳定；DR5减少动效保留意义——每个动画过渡都必须有立即或极小运动的等价形式。

仓库主题把动效意图编码为 token 化的时长档位。各主题在motion域中定义fast/medium/slow/ratio（butterTheme.ts、neutralTheme.ts 等为{fast: 125, medium: 300, slow: 700, ratio: 0.75}）；gothicTheme.ts 注释直言"更慢、更戏剧化的动效——哥特不赶时间"，取{fast: 150, medium: 350, slow: 800, ratio: 0.75}；y2kTheme.ts 则取{fast: 100, medium: 250, slow: 600, ratio: 0.8}。这印证了 DR2 的"重量决定时长"与 DR3 的"主题可调个性"——时长不是硬编码散落在组件中，而是随主题统一定义的意图层。

3.8 Ordered collection reordering（有序集合重排）

ordered-collection-reordering.md 专门定义列表/行集合内的顺序调整交互（自由画布摆放与文件拖放目标需另行起草）。五条原则：DR1 从显式手柄开始（激活是有意的，其他行操作保持可用）；DR2 移动中的条目保持可识别但不显得被抬升（源与预览是同一临时移动态，不得暗示悬浮卡片）；DR3 落点前先预览（插入提示线标记候选位，周围条目在提交前保持稳定）；DR4只提交一次（drop/release 时才采纳新序，而非指针划过条目时反复提交）；DR5 完成后恢复正常层级（拖拽临时处理立即消失）。

解剖角色包括 reorder handle、stationary source、moving preview、insertion cue、surrounding items、settled collection。状态表达表定义了 rest / dragging / candidate position / dropped / cancelled 五种状态，其中 cancelled 即使在启用动效时也允许立即还原。交互要求强调：候选顺序按集合的排序轴计算（DR6）、键盘与指针共享同一插入提示（DR7）、减少动效时最终顺序直接更新不带动画行程（DR8）。

3.9 Template composition（模板组合）

template-composition.md 要求页面模板或可复用块"看起来像有意的产品表面，而不是组件的合法堆叠"。DR1 布局传达目的；DR2 视觉层级引导视线；DR3 间距与对齐表达关系；DR4 组件保留其可供性（按操作/导航/数据/状态角色选择匹配的组件与变体）；DR5 颜色与主题化保留层级。解剖角色：page context、structural region、primary content、primary action（在其操作组内保持单一且易识别）、supporting content、repeated item（列表/网格/表格/卡片集合在真实内容变化下保持对齐与节奏）。

状态表达表覆盖五种情形：populated（真实内容下区域与层级清晰）、sparse（空空间保留有意分组而非塌缩结构）、constrained（区域重排不丢阅读顺序与主操作）、light or dark mode（表面层级、对比、强调意义完整）、interactive（组件状态在大组合内仍可识别）。它与 spatial-hierarchy.md 共享family:layout-primitives与family:layout-regions候选家族关系。

四、记录间的职责边界与权威仲裁

设计记录的创建有明确判定标准：当主体拥有不同的所有者、批准生命周期、需求集、证据集或独立变更理由时，才创建单独记录。实现机制、公共 API 语法、审计结果与消费方用法必须放在记录之外，并链接到各自的规范所有者。

授权与提升（promotion）流程同样明确：

1. 新设计规范以draft（草稿）权威级别起步；
2. 首次提升为current、后续变更以及规范性资产更新，都需要来自cixzhang、imdreamrunner或 .github/DESIGNOWNERS 中任意当前成员的精确 PR head 批准（exact-head approval）；
3. 混合 PR（mixed PR）中非设计记录仍需cixzhang或imdreamrunner批准；DESIGNOWNER 作者可通过将 PR 标记为 ready for review 来证明设计批准组所需的精确 PR head；
4. 现有门禁只在每个变更路径都是被识别的规范记录、每个必需组都已批准且所有分支检查通过时，才允许 squash 自动合并；规范性资产与索引不在该范围内，任何代码路径都会阻断"仅规范"自动合并路径。

.github/DESIGNOWNERS 还强调：这不是通用合并权限——设计证明单独从不授权非设计记录或混合代码/规范变更。

视觉参考资产（Visual references）有专门约定：公开安全的规范性截图、图表与视觉状态参考存放在docs/design/assets/<design-id>/下，每条资产必须记录 alt 文本、状态、主题/模式、相关视口以及它演示的决策。生成的审计截图只是审计证据而非设计权威；私有设计源保持私有，永不在此命名或链接。当前所有记录均处于draft状态且未包含规范性资产，因此在对应开放问题得到拟定处理前不得添加候选证据。

五、知识图谱中的锚点：谁引用这些设计记录

设计记录通过architecture、families、components等前置元数据字段与知识图谱其他层级挂钩。从现有记录看：

• 状态类记录普遍链接architecture:theme-tokens（theme-tokens.md 是current权威，管辖 packages/core/src/theme 下的 tokens.stylex.ts、tokens.ts、localTokens.ts、domainTokens/、syntax/ 以及 packages/cli/assets/theme.template.ts）与architecture:interaction-modality；
• 高程相关记录额外链接architecture:layer-runtime与family:overlay-dismissal；
• 空间与模板组合记录链接architecture:container-padding、architecture:component-theming-surface与family:layout-primitives、family:layout-regions；
• 颜色与排版记录链接architecture:theme-authoring-contract、architecture:component-theming-surface。

这种"设计记录（意图）→ 架构记录（机制）→ 家族契约（组合语义）→ 组件契约（实现）"的引用链，正是 Astryx 知识图谱的设计精髓：视觉意图只在一处被权威定义，其余层级引用而非复制。

六、如何阅读与维护这些记录

作为读者或贡献者，你可以遵循以下路径深入：

1. 入口：docs/design/README.md 是全目录的索引与治理规则；
2. 模板：design-spec.md 模板 展示每条记录应有的完整结构；
3. 状态分类：依次读 user-states.md → system-states.md → agentic-states.md；
4. 模式记录：按需读 spatial-hierarchy、control-rhythm、shape-relationships、elevation-hierarchy、typography-hierarchy、color-emphasis、motion、ordered-collection-reordering、template-composition 九份记录；
5. 机制佐证：把视觉意图对照 theme-tokens 架构、layer-runtime 架构 与 packages/core/src/theme 下的 token 定义理解；
6. 治理与审批：查看 DESIGNOWNERS 与 schema v1 了解权限与结构约束。

维护时必须牢记：每条记录的 "Content boundary" 定义了它不拥有什么。把实现细节、审计结果与消费指南留在各自所有者处，只在本记录中沉淀人类视觉意图——这是 Astryx 设计规范体系能够长期保持单一事实源、避免多份文档互相漂移的根本原因。

【免费下载链接】astryxAn open source design system that's fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx