Astryx AvatarStatusDot 组件契约解析尺寸感知的状态指示点、无障碍合成与主题化扩展【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxAvatarStatusDot 是 Astryx 设计系统中内置于 Avatarstatus插槽的紧凑型状态指示点它从上下文中读取头像尺寸并按离散尺寸档位等比缩放同时将变体颜色与内置形状实心点、圆环、横杠配对确保状态信息绝不只依赖颜色传达WCAG 2.1 SC 1.4.1。本文以仓库中的组件契约文档 AvatarStatusDot.spec.md 为主干结合 AvatarStatusDot.tsx 源码、AvatarStatusDot.test.tsx 测试以及 Avatar 集成实现系统性讲解其行为契约、尺寸解析、无障碍合成、主题化扩展边界与验证方式。读完本文你将能正确使用并深度定制该组件理解其内部变换顺序并掌握如何通过模块扩展与主题规则扩展新变体。1. 契约定位这是一份“观察性记录”而非新设计1.1 文档意图IntentAvatarStatusDot.spec.md的头部元数据将其定义为一份处于authority: draft状态的组件契约遵循schema_version: 3、template_version: 4的知识契约格式。文档意图明确写道AvatarStatusDot renders the compact status indicator currently composed through Avatarsstatusslot. This draft records verified shipped behavior only. It does not change runtime behavior, public API, compatibility, target names, defaults, or visual meaning.也就是说这份契约只记录已经发布并验证过的行为不引入任何新的运行时行为、公开 API、兼容性承诺或视觉语义变更。它属于仓库内部 Night Watch夜巡观察性回填计划的一部分对应规格 spec:AST-029并由 spec:AST-002 约束 API 准入——未来任何公开行为或默认值的变更都必须先更新当前权威契约。1.2 兼容性与迁移状态文档记录了明确的兼容性结论Released default preserved:yes——已发布默认值被完整保留Compatibility class: 增量的观察性文档与 story 覆盖运行时行为、DOM、targets、默认值与公开 API 均不变Controlled/uncontrolled behavior: 不适用该组件是无状态的展示型组件Migration decision: 无——消费者迁移指引属于消费者文档与发布说明release notes的职责不在本契约内。1.3 所有权边界Ownership boundary契约严格划定了组件“拥有”与“不拥有”的范围这对于判断主题化与扩展责任非常关键拥有Owns状态点根元素及其当前的avatar-status-dot主题目标当前内置的 filled实心、ring圆环、minus横杠三种视觉分支从 Avatar 解析出的数字尺寸到离散尺寸档位的换算将可选的状态标签上报进 Avatar 的无障碍名称。不拥有 / 非目标Does not own / non-goalsAvatar 的身份、图片回退、形状、状态放置与交互行为——这些归属于component:Avatar契约调用方提供的 icon 内容的意义与图样——由调用方负责任何新的状态词汇、视觉默认值或兼容性承诺。2. 公开概念Public concepts与 Props 参考契约指出消费者的书写语法consumer syntax以 AvatarStatusDot.doc.mjs 为准契约表格记录的是“当前可观察概念”而非替代那份 prop 参考。以下将两者合并整理成一份完整可用的参数表。Prop类型默认值含义与关键行为variantsuccess \| neutral \| error可扩展success选择当前盘面颜色与内置非颜色标记success 绿色实心点neutral 灰色圆环error 红色盘面加横杠。labelstring可缺省缺省absent为独立使用的状态点命名并上报进所属 Avatar 的名称如 Jane Doe, Online。空或缺失时不产生 role / accessible name。iconReactNode可缺省缺省在中、大尺寸档位替换内置字形小尺寸档位不渲染。布尔值与空字符串会被忽略渲染但无 DOM 输出的组件仍会抑制内置字形。DOM 扩展BaseProps 支持项 ref无额外输入扩展当前根元素并组合消费者样式遵循 public-component-api 架构。对应到源码AvatarStatusDot.tsx 中的AvatarStatusDotProps接口声明了variant、label、icon三个属性全部继承自BasePropsHTMLDivElement并通过xstyle、className、style支持消费者样式注入。契约中的概念表格还记录了各概念的稳定度与非法值行为Status variant内置三种变体外已发布的AvatarStatusDotVariantMap还允许通过模块增强module augmentation添加名称。对没有匹配内置规则的增强名称根几何与data-variant会保留但没有可靠的“颜色图标”兜底被记录为历史遗留债务详见第 6 节Status label由调用方提供含义组件负责暴露与上报Custom icon图样归调用方所有组件负责放置与抑制规则DOM extensionBaseProps 遗漏项仍不受支持。3. 行为与布局契约五个已验证不变量契约以表格形式给出了 6 条候选不变量FR1–FR6其中 FR1–FR5 标注为 “Verified shipped geometry / behavior”已验证的已发布行为。下面结合源码逐一展开。FR1 — 离散尺寸档位解析Avatar sizes up to 36px currently resolve a 10px dot with 1px border and no custom icon; 40–72px resolve 20px/2px/12px; 96px and above resolve 32px/4px/18px. Standalone use reads AvatarSizeContexts current 36px default.源码中的 resolveStatusDotSize 精确实现了这一档位表Avatar 尺寸档位状态点直径边框图标尺寸内部 field字形描边≤ 36pxsmall10px1px—不渲染8px1px40–72pxmedium20px2px12px16px1.5px≥ 96pxlarge32px4px18px24px2px其中 “field” 指状态点减去两侧边框后的内场dot minus both borders内置字形就绘制在这个内场中。关键设计意图见源码注释采用离散档位而非连续比例这样在每个头像尺寸下状态点都显得经过刻意设计而small 档位不渲染自定义 icon是因为 10px 的点内没有足够的空间保证图标可读——但内置字形仍会渲染因此任何尺寸下状态都不会只靠颜色区分。该尺寸从 AvatarSizeContext 读取其默认值 36 与 Avatar 默认的md36px一致。Avatar 通过 resolveSize 将命名尺寸解析为数字xsm20、sm24、md36、lg48、xl128也支持直接传入数字像素值16–180 的既定档位。FR2 — 内置变体的颜色 形状配对successcurrently paints a filled semantic-success plate without an inner glyph;neutralpaints a surface plate with a ring;errorpaints a semantic-error plate with a minus.源码中的 styles 与glyphShapeMap第 197-202 行共同实现了这一行为success--color-success背景 surface 文字色无内置字形——实心点本身就是参考形状neutral颜色反转设计——盘面为 surface、墨色为--color-text-secondary。源码注释解释圆环只有在内腔不是变体颜色时才读作“空心”同时这也保证了用户 icon 在浅色盘面上可读error--color-error背景 横杠字形。所有绘制在状态点上的内容字形与用户 icon都通过currentColor取墨因此盘面与墨色永远不可能漂移出对比度范围见样式注释。FR3 — 自定义 icon 的替换与抑制规则At medium and large tiers, renderableiconcontent replaces the built-in glyph and is centered in an assistive-technology-hidden wrapper. At the small tier the icon is omitted and the built-in glyph branch remains.实现逻辑在组件主体AvatarStatusDot.tsx中showsIcon isRenderable(icon) iconSize 0——只有“可渲染”且档位允许iconSize 0时才显示图标图标渲染在aria-hiddentrue的 span 包裹层内向辅助技术隐藏AR2图标显示时glyphShape被置为undefined内置字形被抑制——因为一个已渲染的图标本身就是非颜色标记两者叠加在狭小的内场中都会变得难以辨认在 small 档位图标被省略、内置字形分支保留。测试 AvatarStatusDot.test.tsx 的 “glyph and icon interplay” 组覆盖了这三种情形图标渲染时抑制字形、最小档位保留字形、true/false/等不可渲染值不抑制字形。FR4 — label 的无障碍上报A non-emptylabelcurrently addsroleimgandaria-labelto the dot. The callback ref reports the same label through AvatarStatusLabelContext before paint and withdraws it on detach.这是组件最精妙的设计之一涉及三条路径独立使用非空 label 时状态点根元素获得roleimgaria-label{label}源码第 351 行状态点成为自己的无障碍名称在 Avatar 内Avatar 根元素是roleimg会剪除所有后代语义prune descendant semantics状态点永远不会成为自己的停靠点。因此状态点通过 AvatarStatusLabelContext 将自己的 label 写入 Avatar 共享的 ref 目标label字段由 Avatar 合成进自己的无障碍名称例如 Jane Doe, Online对应 i18n 键astryx.avatar.nameWithStatus上报机制通过回调 refcallback ref在 commit 阶段写入而非使用 Effect。回调 ref 在提交阶段运行因此名称在绘制前就已合成ref 写入不产生额外渲染、不引入 state 镜像、Effect、观察器、监听器或计时器契约 PR1。reportRef依赖statusLabelRef与label并在卸载清理函数中target.label undefined; target.update?.()撤回标签。值得注意的集成细节见 Avatar.tsxcontext 上报路径能穿透消费者自建的任何层级包装组件——测试 Avatar.test.tsx 的 “status label through a consumer wrapper (P14)” 组验证了包装组件、任意嵌套深度、挂载后 label 变化、状态元素卸载后撤回、包装状态在装饰性头像上仍被播报等场景。作为对比Avatar 的getStatusLabel只能在消费者直接传入AvatarStatusDot时内省到字面labelprop用于首帧渲染兜底。FR5 — 根目标、字形目标与 DOM 面The root currently carriesavatar-status-dotwithvariant; ring and minus SVGs carryavatar-status-dot-glyphwithshape. Supported consumer styling and ref inputs reach the root.源码通过 themeProps 挂载主题目标根元素astryx-avatar-status-dotclass data-variant属性测试断言data-variantneutral字形 SVGastryx-avatar-status-dot-glyphclass data-shape属性ring/minus消费者 ref、xstyle、className、style全部到达根元素。契约文档关联了架构规则 component-theming-surface 与 theme-tokens主题包可通过.astryx-avatar-status-dot[data-variant...]与.astryx-avatar-status-dot-glyph[data-shape...]进行样式定位。FR6 — 增强变体augmented variant的已知差距The releasedAvatarStatusDotVariantMapcurrently admits augmented names. For an unmatched name, root geometry and reflecteddata-variantremain while built-in fill, ink, and glyph are absent. The current surface provides no reliable caller-configurable path that supplies both color and icon fallback.AvatarStatusDotVariantMap在 index.ts 中定义并支持模块增强例如declare module astryxdesign/core/Avatar { interface AvatarStatusDotVariantMap { away: true; } }增强变体不渲染背景填充、不提供墨色、也不提供内置字形——主题必须自行供应填充色并在传入icon时提供颜色。同时必须提供非颜色标记如通过data-variant主题化一个::before形状否则状态只靠颜色区分即构成 WCAG 1.4.1 失败。该契约明确将此记录为当前权威一致性的既有差距pre-existing current-authority conformance gap并引用component-theming-surface/INV14本审计只记录、不修复公开表面保持不变。4. 变换与优先级顺序Transformation and precedence order契约定义了三条严格有序的变换规则ORD1 — Resolve size读取AvatarSizeContext选择离散尺寸档位与维度ORD2 — Resolve mark档位允许时可渲染的 icon 优先否则选择存在的内置变体字形ORD3 — Resolve root组件自身的 target/style 输出与受支持的消费者 StyleX、class、style 输入在根元素上组合。这与源码的执行顺序一一对应resolveStatusDotSizeORD1→showsIcon/glyphShape决策ORD2→mergeProps(themeProps(...), stylex.props(...), className, style)ORD3。5. 允许的变化Allowed variation与代表性状态Representative states5.1 允许的变化AV1 — 身份与含义状态 label 与调用方提供的 icon 图样可以变化AV2 — 主题输出当前 targets 与反射轴可通过公开主题系统变化但不转移 target 所有权AV3 — 消费者样式受支持的 BaseProps 输入可在当前根元素上变化组件拥有的尺寸与上报行为保持不变。5.2 代表性状态矩阵状态必需不变量允许的变化内置变体当前的 fill/ring/minus 分支与反射的variant保持label、Avatar 内容、尺寸、主题、方向可变化小尺寸档位状态点与内置形状保留自定义 icon 省略内置变体与 label 可变化中/大尺寸档位当前尺寸生效可渲染的自定义 icon 替换字形icon 图样、变体、label、主题可变化带标签状态点暴露 label 并上报给 Avatar调用方撰写的 label 可变化无标签状态点无当前 role/name不上报状态 label视觉变体与 icon 仍可渲染增强变体根几何与反射的data-variant渲染未匹配的内置填充、墨色、字形保持缺失当前发布表面没有同时提供颜色与 icon 的可靠兜底路径RTL状态点内容方向中立Avatar 负责逻辑角放置主题、变体、尺寸、label、icon 可变化RTL 相关不变量在源码中亦有印证Avatar 通过insetInlineEndtransform的:is([dirrtl] *)镜像规则定位状态点Avatar.tsx而状态点自身内容方向中立。6. 无障碍契约Accessibility contractAR1 — 当前无障碍名称非空label为独立状态点命名并通过 context 上报合成进 Avatar 名称AR2 — 装饰性视觉标记内置 SVG 与自定义 icon 包裹层均通过aria-hiddentrue向辅助技术隐藏因为根元素或 Avatar 名称已携带状态AR3 — 内置非颜色线索三种内置变体在语义色之外分别使用实心、圆环、横杠拓扑。用调用方内容替换该标记可能改变非颜色区分度——契约记录而非解决这一公开接缝。此外AvatarStatusDot.doc.mjs 中补充了一个重要细节若状态点独立使用直接以roleimg暴露 label而在 Avatar 内则依赖合成名称。测试对无 label 状态点断言了“无 role、无 aria-label”见 AvatarStatusDot.test.tsx 的 existing contract 组与 Avatar.test.tsx 的 “status in the accessible name (WCAG 4.1.2)” 组。7. 设计关系Design relationships契约将状态点各组成部分的设计职责映射如下解剖结构 / 状态设计要求代表权威层级角色组件契约状态点根Avatar 边缘的紧凑语义状态盘面当前源码与消费者文档辅助性指示器FR1, FR2, FR5内置字形圆环/横杠为 neutral/error 补充颜色之外的信息WCAG 2.2 SC 1.4.1 当前发布表示有意义的非文本线索FR2, AR3自定义 icon空间允许时由调用方图样替换内置标记图样归调用方位置归当前源码条件性有意义线索FR3, AR2, AR3文档同时强调本观察性草稿不选择新的字形、比例、密度、状态语义或显著性处理方式。8. 系统与家族关系Family and system relationships组件契约所在的仓库知识体系中各架构契约各司其职knowledge-contracts 负责 draft/current 权威判定、冲突路由与观察性记录边界component-theming-surface 负责绘制目标资格、反射轴与可扩展视觉轴所需的可靠、与主题无关的兜底——本审计记录了当前违规但保持公开表面不变component-style-authoring 负责 StyleX 降级并允许组件自有非字形 SVG 形状即 ring/minus 内联 SVGpublic-component-api 负责发布子路径、BaseProps 透传、样式组合、ref 可达性与兼容性边界theme-tokens 负责语义色与圆角词汇源码中状态点使用--radius-full与--color-success、--color-error、--color-background-surface、--color-text-secondary等 tokenspec:AST-002 负责 API 准入spec:AST-029 负责本次 Night Watch 观察性回填。9. 验证地图Verification map与实操示例契约给出了逐项验证映射便于读者对照仓库继续深入契约验证方式代表性状态失败预期FR1–FR3, AR2, AR3AvatarStatusDot.test.tsx 专用 Storybook 浏览器矩阵三个尺寸档位、三种内置变体、icon 有无尺寸档位、标记选择、隐藏图标或内置形状漂移会失败断言或渲染凭据FR4, AR1Avatar.test.tsx 状态名称套件 AvatarStatusDot.test.tsx直接/包装/变化/移除的 label带标签与无标签丢失独立或合成状态名称、commit 阶段更新或清理失败FR5主题目标与可扩展轴测试 源码检查内置与增强变体、ring/minus 字形、消费者样式目标元数据/反射缺失、目标移动、受支持的 DOM/样式输入被丢弃FR6增强变体专项单元测试 源码/文档检查无匹配内置规则的增强名称仅基础输出保持可见缺失的可靠颜色icon 兜底继续记录为既有债务RTL专用 RTL 审计覆盖 LTR/RTL 浏览器帧各尺寸下的内置变体新方向性字形、物理定位或未匹配变换产生覆盖或渲染差异文档与表面消费者文档、blocks、专用 stories、导出检查与 check-knowledge.mjsprops、包子路径、blocks、story 状态与本草稿缺失/过期文档、导出、必要结构、关系或 story 覆盖失败仓库检查9.1 完整使用示例独立使用状态点自己承担无障碍名称AvatarStatusDot variantsuccess labelVerified icon{CheckIcon /} /作为 Avatar 的状态插槽使用label 合成进头像名称Avatar nameJohn Doe sizelg status{AvatarStatusDot variantsuccess labelOnline /} / Avatar nameJane Smith sizexl status{AvatarStatusDot varianterror labelDo not disturb /} /带自定义 icon中/大档位替换内置字形请为不同状态使用不同图标Avatar nameAda Lovelace sizexl status{ AvatarStatusDot variantneutral labelPending icon{ClockIcon /} / } /以上用法与 AvatarStatusDot.stories.tsx 中的Core/AvatarStatusDotstory 保持一致后者覆盖了success/neutral/error三种变体在xsm/lg/xl尺寸下的组合以及 CheckIcon、ClockIcon、XMarkIcon 三个 icon 变体。10. 性能与资源Performance and resources契约只记录了一条性能不变量PR1 — Commit-phase label reporting当前回调 ref 路径负责上报与撤回 label不引入state 镜像、Effect、观察器、监听器、计时器或第二次渲染。源码实现印证了这一点reportRef是useCallback返回的清理函数式 refrootRef通过useMemo合并消费者 ref 与上报 ref——只有当被上报的 label 实际变化时 React 才会分离并重新挂载内联合并会在 Avatar 每次渲染时反复撤回再上报。对react-compiler的 eslint 豁免eslint-disable react-compiler/react-compiler也有注释说明Avatar 通过 context 共享自身 refcontext 读取在编译器看来不可变因此豁免是必要且被记录的。11. 决策日志与开放问题Decision log无。本草稿只记录当前事实不引入任何组件局部的 API、行为、无障碍、布局、主题或设计决策Open questions无Content boundary本文件不重复消费者示例、当前审计分数、截图、运行清单、资格数据或共享 API/主题规则仅链接到其所有者。参考资源汇总组件契约AvatarStatusDot.spec.md组件实现AvatarStatusDot.tsx组件测试AvatarStatusDot.test.tsx集成测试Avatar.test.tsxProps 参考AvatarStatusDot.doc.mjs上下文AvatarSizeContext.ts、AvatarStatusLabelContext.ts变体映射与导出index.tsStorybook 覆盖AvatarStatusDot.stories.tsx关联架构契约component-theming-surface、component-style-authoring、public-component-api、theme-tokens关联规格spec:AST-002、spec:AST-029【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考