Astryx Charts 发布就绪度审计astryxdesign/charts 的 12 个 Marks、6 个 Chrome 组件与 Canary 首切方案【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx导读astryxdesign/charts是 Astryx 设计系统基于 d3 构建的配置模型数据可视化库目前仅在canarydist-tag 下发布包级说明。本文以仓库内的 CHARTV2_READINESS.md 发布就绪度审计为核心骨架逐项盘点 12 个 Marks、6 个 Chrome 组件与调色板/格式化工具的真实就绪状态并对照 源码实现、验证清单 与 阶段设计文档 给出证据链。读完你可以掌握如何判断该库每个图元能否投入 canary 使用、官方推荐的首个可发布切片由哪些组件组成、以及后续 fast-follow 的优先级路线图。一、背景什么是发布就绪度审计astryxdesign/charts从实验性的ChartV2原位于astryxdesign/lab抽取而来d3 作为直接依赖d3-array、d3-scale、d3-shape见 package.json。由于 API 与视觉效果仍在打磨中包级元数据明确标记private: true与astryx: { canaryOnly: true }发布工作流的 stable 任务会跳过这类包因此永远不会存在latest版本——这是 npm 层面防止误发稳定版的硬保证。在发布之前团队需要回答一个务实的问题当前仓库里到底哪些部分能立刻以 canary 质量放出去哪些还需要打磨这就是 CHARTV2_READINESS.md 的作用——它是基于 API 审计、验证清单和已落地的 Stage 1 修复生成的全量清单快照目标是在与 vega 发布协调的时间窗口内挑选出第一块值得发布的切片。就绪度图例文档为每一项定义了三级评估标准Ship-ready可发布已验证可用、修复已落地canary 发布风险低。Minor polish小幅打磨功能可用但还需要 12 个小修复和/或一个 story 才能拿得出手。Needs work需要工作存在架构性缺口或未经验证的交互不适合放进首切。所谓ready的基准线是canary 质量功能正常、在亮色 暗色模式下观感正确、API 合理、有 story 覆盖。请注意这不是完整的 stable/a11y 标准——那是更后面的阶段。二、Marks 全景12 个图元的状态盘点Marks 是库的核心抽象它们是工厂函数bar(...)、line(...)等返回配置对象后通过series属性交给图表根组件。正如 marks/index.ts 所示共导出 12 个图元工厂函数每个都带自己的 Options 类型。2.1 Ship-ready 组bar / line / area / dot这四类是所有人在基础图表诉求中最常问到的图元也是首切的核心Mark能力就绪度备注bar简单/堆叠/分组/分组堆叠/负值Ship-ready全变体在亮暗双模式下验证通过_uid与颜色修复已落地line折线系列曲线、可选数据点Ship-ready边缘裁剪edge-clip与顶部留白headroom已修复area面积填充渐变、堆叠Ship-ready渐变 id 冲突已修复dotSVG 散点Ship-readydodge已实现已补充 story从源码角度看Chart.tsx 中图表根组件对 Marks 类型是零知识的它运行布局引擎scales stacking grouping调用每个系列的resolve()与render()方法再提供一个统一的事件层。这种marks 单一共享 scale的架构在 STAGE1 设计文档 中被评价为对标 Observable Plot 的现代正确选择。2.2 Minor polish 组band / candlestick / errorBar / referenceLine / dotGL / streamGLMark能力就绪度阻塞点band置信区间带Minor polish工具类图元不占图例半透明填充在暗色下发虚candlestickOHLC 金融蜡烛图Minor polish已有语义默认色默认不进图例tooltip 只显示open值errorBar误差须/误差棒Minor polish工具类暗色下自定义深色#1e3a5f发虚referenceLine固定 x/y 的注释线/带Minor polish标签钳制已修复缺独立 storyx仅支持线性刻度dotGLWebGL 散点大 NMinor polish可用仅支持 hex 颜色未集成调色板/tokenstreamGLWebGL 流式折线命令式 pushMinor polish带 domain 窗口可渲染场景较 niche需要文档化的用法模式以candlestick为例其 tooltip 值语义缺陷在验证清单中有明确根因tooltip 取值逻辑是datum[dataKeys[0]]导致只显示open而看不到 high/low/close——这类问题正是Minor polish级别的典型。2.3 Needs work 组dotGLInteractive / heatmapGLMark能力就绪度阻塞点dotGLInteractiveWebGL 散点 GPU-picking 悬停Needs work悬停交互从未被 story 覆盖 / 未验证heatmapGLWebGL 2D 热力图Needs work自建分类 y 刻度破坏共享刻度规则顶行裁剪hex ramp 非 token 感知heatmapGL的自建分类 y 刻度是架构性例外它自己构建了一个scaleBand而不是读取图表根的共享刻度。types.ts 中虽然已经定义了yBandScale当系列声明layout.yBandKey时图表的 y 轴变为由该数据键唯一值构建的分类 band 刻度供热力图行与左侧ChartAxis对齐但这一能力尚未被heatmapGL采用——这直接解释了它被列为架构性修复项的原因。三、Chrome 组件6 个外围构件Chrome 指图表的外围 UI 构件。它们与 Marks 解耦属于可组合的基础组件。组件职责就绪度备注Chart根组件布局、刻度、domain、裁剪、调色板、事件Ship-ready能力强domain/baseline/streaming/palette 均已落地ChartAxis坐标轴ticks、格式化器、密度Ship-ready标签自动密度已修复时间轴 top/right/showTicks组合测试较少ChartGrid网格线水平/垂直Ship-ready—ChartLegend图例位置、对齐Ship-readyaccessor/自动着色系列现在能出现在图例中ChartSwatch颜色色块原语Ship-ready组件本身没问题story 展示不足外观性问题ChartTooltip分组悬停 tooltip 十字线Minor polish核心可用但悬停交互未经截图验证对 candlestick/streamGL/GL 的值语义错误Chart根组件的实现印证了Ship-ready的判定它在渲染期通过useChartColors()获取调色板把所有未指定静态颜色的主系列band/errorBar/referenceLine 等工具类图元不占调色板槽位按索引自动分配categorical(n)颜色并写入_resolvedColor布局阶段则通过computeLayout计算共享的xScale/yScale/yBandScale。渲染顺序固定为网格 → 裁剪后的 Marks 层clipPath防止曲线过冲逃逸进边距→ 坐标轴 → 事件捕获层 → tooltip → 逃生舱childrenChart.tsx。另外值得注意的可访问性细节SVG 以roleimg暴露title作为 aria-label当数据量较小行数 × 数据键 ≤ 100时还会在视觉隐藏的table中镜像数据供屏幕阅读器读取MAX_TABLE_POINTS 100。四、工具集调色板与格式化器4.1 调色板useChartColors / getChartColors— Ship-ready调色板 API 是 v1 时代就沉淀下来的强项被原样引入 charts 包。从 getChartColors.ts 源码看完整 API 包括categorical(n)10 个分类色blue/orange/purple/green/pink/cyan/red/teal/brown/indigon超过 10 时环绕复用保证任意系列数都有确定颜色sequentialhue9 个顺序 ramp × 5 阶5最深 → 1最浅n ≤ 5时取最近的手调 token 停靠点n 5时在 sRGB 中插值扩展n 1取中间代表色divergingpositiveNegativeshamrock→red、coldHotblue→red、custom(neg, pos, n, midpoint?)semanticpositive/negative/warning/neutralstructuralaxis / grid / tick / label供图表 chrome 使用主题感知alpha(hex, opacity)对具体 CSS 颜色施加透明度。审计文档特别指出调色板解析的是--color-data-*这类JS-only token通过useChartColors解析并非 CSS 自定义属性因此var(--color-data-*)在 CSS 中渲染不出任何东西。types.ts 中的DEFAULT_SERIES_COLOR注释也印证了这一点——它回退到已发射的核心 token--color-accent。getChartColors(theme, mode)变体则面向非 React 场景WebGL 初始化、SSR、测试、Node 脚本经由resolveThemeTokens统一解析并处理light-dark()字符串与[light, dark]元组。4.2 格式化器工具就绪度说明currencyShip-ready已在坐标轴上验证$ 值percent/compactNumber/shortDate/monthYearMinor polish尚未在 story 中验证formatters.ts 的实现采用按 locale 惰性缓存的Intl.NumberFormat/Intl.DateTimeFormat。几个值得写进文章的工程细节compactNumber1200 → 1.2K、1e12 → 1T非数值与非有限数原样透传可安全用作通用 tick 格式化器currency符号前缀在数量级之前、负号在符号之前-$1.5K而非$-1.5K≥1000 用紧凑记法shortDate处理YYYY-MM-DD时按本地午夜构造而非规范的 UTC 午夜避免负时区下日历日漂移一天2024-01-05保持 Jan 5 而非 Jan 4且会拒绝如2024-02-31这类越界日期percent输入是比值0.45 → 45%最多保留一位小数。五、推荐首切与 vega 同步发布的第一块切片审计文档给出的结论非常明确首切集合内的所有项都是Ship-ready恰好覆盖大家反复在问的几个基础图表Marksbar、line、area、dotChromeChart、ChartAxis、ChartGrid、ChartLegend、ChartSwatch、ChartTooltip*Utilities颜色调色板 currency* 注Tooltip 的静态渲染没问题但发布前需要做一轮悬停验证——这是唯一未经截图测试的交互。Stretch低成本的加分项candlestick是一个很有说服力的金融展示场景只需补齐图例/tooltip 值语义的打磨即可。另外需要确认剩余的格式化器在 story 中能正常渲染。落地首切所需的收尾工作审计文档列出 4 步验证 tooltip 悬停用 Playwright 驱动一次 hover——最后一个未验证的交互在 story 中确认percent/日期格式化器渲染正常把/charts接入 docsite作为依赖加入、填充空的.doc.mjs文件让它出现在文档中对切片做最后一轮亮色 暗色截图走查。这套流程与 PHASE1 计划 中的验证方法论一脉相承Playwright 截图 harness 以iframe.html?idstoryIdglobalscolorMode:{light|dark}的方式对每个 story 拍摄亮暗双模式截图配合 vitest 单元测试、可手动驱动的悬停/键盘/缩放交互以及 render-to-string 的 SSR 冒烟测试。六、Fast-follow 路线图首切之后的优先级审计文档把剩余工作排成了清晰的后续清单heatmapGL分类 y 共享刻度修复架构性例外项dotGLInteractive悬停 story 验证模式感知的半透明填充让 band/errorBar 在暗色模式下可读candlestickOHLC/ streamGL / GL 图元的 tooltip 值语义dotGL调色板/token 颜色集成时间刻度 日期轴格式化types.ts 的 axis 类型中已引入ScaleTime但根组件尚未构建时间刻度referenceLine独立 story边界 story空数据/单点/全零/离群点测试单元 导出面 SSR与 a11y 走查跨图表交互中介interactivity broker——由 indigo 负责保持Chart的容器 context 与 pointer 流干净作为集成接缝。值得注意的是上述每一条都能在 验证清单 中找到对应的[BUG]/[?]/[new]条目。例如translucent fills wash out on dark对应验证清单 §3 中记录的根因分析band 的 0.10.2 透明度、reference band 的 amber 0.15 / green 0.08、errorBar 的#1e3a5f、financial volume bars 的 gray 0.3——这些颜色/透明度都是针对亮色背景挑选常为硬编码 hex而非模式感知修复应落在调色板/语义层而不是逐个图元打补丁。七、判断就绪度的证据方法论最后总结这套审计的方法论它本身对工程团队同样有复用价值三层证据API 审计源码层面、验证清单行为层面、截图走查视觉层面三线并进明确的评级标准Ship-ready / Minor polish / Needs work 三级且canary 质量与stable/a11y 标准刻意区分避免过度工程化阻塞发布节奏首切以小切口验证发布链路先发布 4 个 Marks 6 个 Chrome 调色板/货币格式化器把工具链docsite 接入、story 验证、截图走查跑通再以 fast-follow 消化架构性难题可回放所有判定都能在 验证清单[ok]/[BUG]/[?]/[new]四态与 阶段设计文档channel 模型、刻度提案、失败模式矩阵中找到出处。对于想要在自有项目中试用该库的读者README 给出的安装方式需要显式指定 canary 标签因为不存在latest版本npm install astryxdesign/chartscanary astryxdesign/corecanary注意canary 构建跟踪main分支最新提交版本形如0.x.y-canary.sha任意两个版本之间都可能发生破坏性变更——需要稳定性时请固定精确版本。这也正是审计文档反复强调先发小切片、把 API 打磨成不易后悔的形状再谈 stable的根本原因。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考