Astryx 设计规范体系Design Specifications完全指南从状态分类学到组件视觉契约的权威入口【免费下载链接】astryxAn open source design system thats 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三条记录划定全部状态所有权设计目录中状态记录按驱动者是谁来切分且整个仓库只有三种状态分类学记录记录拥有者OwnsUser states人驱动的静止、悬停、按压、焦点、选中与操作状态Person-driven rest, hover, press, focus, selection, manipulationSystem states系统驱动的禁用、加载、处理、状态与瞬时反馈状态System-driven disabled, loading, processing, status, transient feedbackAgentic states智能体驱动的思考、流式输出、工具执行、等待、同步、检查与渲染状态Agent-driven thinking, streaming, tool execution, waiting, synchronization, inspection, rendering2.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主题控制视觉性格hoveredsurface 原型安静覆盖层改变表面但保留基底hoveredfield 原型边框或内嵌处理让字段边界更明显pressed即时的触觉压缩或更强的表面反馈focusedaction 原型清晰分离的外部指示器focusedfield 原型强调边框 内嵌处理复合字段可绘制在拥有者包装器上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 processingAgent 工作何时需要区别于普通系统处理的表达OQ2 — User-visible rationale什么处理能区分有意撰写的解释与普通输出又不暗示访问隐藏推理OQ3 — Streaming增量文本如何保持可见地未完成而不干扰已有文本OQ4 — Tool execution后端工作的哪些信息对人有价值何时应保持折叠OQ5 — Awaiting input必需的人类响应如何超越被动进度同时保留任务上下文OQ6 — Synchronizing and synchronized待同步与已同步如何区别于泛化处理与成功OQ7 — InspectingAgent 检查是否需要独立状态还是普通进度 限定上下文就足够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/ratiobutterTheme.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流程同样明确新设计规范以draft草稿权威级别起步首次提升为current、后续变更以及规范性资产更新都需要来自cixzhang、imdreamrunner或 .github/DESIGNOWNERS 中任意当前成员的精确 PR head 批准exact-head approval混合 PRmixed PR中非设计记录仍需cixzhang或imdreamrunner批准DESIGNOWNER 作者可通过将 PR 标记为 ready for review 来证明设计批准组所需的精确 PR head现有门禁只在每个变更路径都是被识别的规范记录、每个必需组都已批准且所有分支检查通过时才允许 squash 自动合并规范性资产与索引不在该范围内任何代码路径都会阻断仅规范自动合并路径。.github/DESIGNOWNERS 还强调这不是通用合并权限——设计证明单独从不授权非设计记录或混合代码/规范变更。视觉参考资产Visual references有专门约定公开安全的规范性截图、图表与视觉状态参考存放在docs/design/assets/design-id/下每条资产必须记录 alt 文本、状态、主题/模式、相关视口以及它演示的决策。生成的审计截图只是审计证据而非设计权威私有设计源保持私有永不在此命名或链接。当前所有记录均处于draft状态且未包含规范性资产因此在对应开放问题得到拟定处理前不得添加候选证据。五、知识图谱中的锚点谁引用这些设计记录设计记录通过architecture、families、components等前置元数据字段与知识图谱其他层级挂钩。从现有记录看状态类记录普遍链接architecture:theme-tokenstheme-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 知识图谱的设计精髓视觉意图只在一处被权威定义其余层级引用而非复制。六、如何阅读与维护这些记录作为读者或贡献者你可以遵循以下路径深入入口docs/design/README.md 是全目录的索引与治理规则模板design-spec.md 模板 展示每条记录应有的完整结构状态分类依次读 user-states.md → system-states.md → agentic-states.md模式记录按需读 spatial-hierarchy、control-rhythm、shape-relationships、elevation-hierarchy、typography-hierarchy、color-emphasis、motion、ordered-collection-reordering、template-composition 九份记录机制佐证把视觉意图对照 theme-tokens 架构、layer-runtime 架构 与 packages/core/src/theme 下的 token 定义理解治理与审批查看 DESIGNOWNERS 与 schema v1 了解权限与结构约束。维护时必须牢记每条记录的 Content boundary 定义了它不拥有什么。把实现细节、审计结果与消费指南留在各自所有者处只在本记录中沉淀人类视觉意图——这是 Astryx 设计规范体系能够长期保持单一事实源、避免多份文档互相漂移的根本原因。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
