基于 diagram-design 的柱状图设计规范布局语法、Dumbbell 对比图变体与可执行校验【免费下载链接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design柱状图Bar / Column Chart是 diagram-design 技能体系中负责跨类别离散量对比的核心图型无论是迭代速度、月度营收、功能采纳率还是队列计数只要每个类别携带单一数值、且条与条之间的对比就是信息本身就该选用这一类型。本文以仓库中的类型参考文档 type-bar.md 为主干结合 SKILL.md 的设计系统约束、assets/下的三套成品示例与 verify-dumbbell.py 源码完整讲解柱状图的布局约定、SVG 元素写法、反模式、三大变体分组、堆叠、Dumbbell以及 Dumbbell 变体特有的轴域解析与非文本对比度两条可执行诚实性规则。读完你既能手写一份符合编辑级审美的柱状图 HTML/SVG也能理解为什么这套规范把部分规则写进了校验脚本而不是停留在散文里。适用场景与选型判断type-bar.md开篇即给出该类型的定位比较跨类别或时间区间的离散数量——sprint 速率、月度收入、功能采纳、队列计数。使用前提是每个类别只有一个数值条与条之间的对比是主要信息在 Dumbbell 变体下则是恰好两个数值二者之差才是信息。与之对照SKILL.md 的选型表见 SKILL.md把连续趋势随时间变化分给 Line chart、面积即整体占比分给 Treemap、两变量分布与相关分给 Scatter。如果你的诉求是部分占整体或连续趋势就不该选柱状图。同时遵循 SKILL.md 的整体哲学能用一个表格讲清楚的对比就不要画图超过 8 个类别且无法分组时应拆成两张图而不是硬塞。布局约定坐标、留白、条数与网格文档为柱状图定义了严格的画布语法全部数值落在0 0 1000 500的 viewBox 内约定项规范值默认朝向垂直柱columns类别标签较长或类别数 8 时改用水平条绘图区边距左 80pxy 轴刻度标签、下 60pxx 轴类别标签、上 40px、右 40px条数上限4–8 条超过 8 条 → 按周期分组或拆成两张图条宽≥ 列距pitch的 50%间隙绝不能大于条本身。典型pitch110px、bar72pxy 轴网格线4–6 条等距水平线rgba(45,49,66,0.08)极淡0.8pxx 轴基线rgba(45,49,66,0.25)1pxy 轴刻度标签右对齐 Geist Mono 8px muted位于 x72绘图区左缘 8px 处x 轴类别标签每条柱正下方居中Geist sans 11px 600数值标签每条柱上方 Geist Mono 8px焦点柱用 accent 色其余 muted焦点柱最多 1 根accent 填充/描边其余柱muted 0.15填充 muted描边y 轴竖线x80 处从 y40 到 y420 的细line这些数值与 style-guide.md 的 token 体系一一对应#f5f5f5即 light 皮肤paper#2d3142是ink#4f5d75是muted#eb6c36是accent。所有坐标、字号、间距必须满足 4px 网格SKILL.md §7 的硬规则而描边宽度0.8/1/1.2、透明度属于豁免项——这正是示例文件中坐标全部为 4 的倍数、而 stroke-width 可以用 0.8 的原因。在 example-bar.html 中可以看到这条语法的完整落地8 根柱 pitch110、bar72、pad19S1–S8 的 x 坐标依次为 99、209、319…y 轴基线在 y420x 轴类别标签在 y440图例条在 y462/488/497。焦点柱 S5 用rgba(235,108,54,0.12)填充 #eb6c36描边数值标签加font-weight600x 轴标签同样切换为 accent 色——整个图例、网格、坐标形成一个自洽的层级。Bar 元素模式文档给出了可直接复制的单柱 SVG 模式!-- Opaque paper mask prevents bleed from background -- rect xX yY widthW heightH fill#f5f5f5/ !-- Bar body -- rect xX yY widthW heightH fillrgba(79,93,117,0.15) stroke#4f5d75 stroke-width1/ !-- Value label above bar -- text xXW/2 yY-8 fill#4f5d75 font-size8 font-familyGeist Mono, monospace text-anchormiddleVALUE/text要点有二第一层不透明 paper 色矩形是遮罩防止半透明填充下的背景如点状纹理、网格线透出形成渗色焦点柱则把填充换成rgba(235,108,54,0.12)、描边换成#eb6c36、标签 fill 换成#eb6c36。这条双层矩形技巧与 SKILL.md §6 的节点盒模式paper 遮罩 样式盒是同一套思想先画不透明底再画带透明度的视觉层。反模式清单文档用五条反模式划出底线其中前两条直接对应统计学常识后三条是视觉纪律超过 8 条不分组——常规比例下不可读y 轴截断不从 0 开始——扭曲数值对比这是柱状图最常见的说谎方式超过 1 根焦点柱——处处重要等于处处不重要3D 立体柱——无阴影、无纵深是这套设计系统的铁律见 SKILL.md §4 通用反模式Shadow on any element. Shadows are out类别标签旋转超过 45°——优先换短标签或直接改横向图。三大变体分组、堆叠与 Dumbbell分组柱Grouped bars每类别两根柱并排最多 2 组。主序列用accent次序列用series-1sage 色见 style-guide.md 的 series 调色板light 下为#7c8f6f。分组柱是少数获准使用 series 调色板的场景之一——该调色板只在多个重叠实体确实需要区分时启用绝不能反哺给架构图等其他类型。堆叠柱Stacked bars段与段堆叠至总量。焦点段用accent其余段用 muted 色系的不同深浅每根堆叠柱顶部必须标注总量否则读者无法快速读出整体对比。Dumbbell哑铃图每类别一行、两根点位于同一共享水平刻度、以发丝线相连。它专用于两端之间的距离才是信息的两态比较——前后对比、两个队列、目标 vs 实际。硬性限制只能有两个序列第三个点会让连接线失去意义图形退化为点图dot plot。Dumbbell 是本文档篇幅最大、约束最细的变体下面单独展开。Dumbbell 布局语法画布与行高仅横向行向下堆叠、数值轴从左到右垂直方向的哑铃图会迫使类别标签旋转违反标签纪律。绘图区左留白 200px 让位给行标签替代基础柱状图的 80px所以 x 从 200→960、y 从 40→420仍在0 0 1000 500内。行标签在 x188 右对齐Geist 11px 600 ink。行数沿用 4–8 行上限。行距pitch与首行 y 按行数固定确保整块图形落在绘图带内——文档特别指出64px 的 pitch 从 y96 起到第 7 行会溢出 y420rowspitchfirst rowylast rowy4889636056496352664763967527238484868404轴线与标签网格线每个刻度一条竖线rgba(45,49,66,0.08)0.8px跨 y 56→408。域下限处由轴线替代网格线而非叠加rgba(45,49,66,0.25)1pxy 40→420。刻度标签每条网格线正下方 y440 居中Geist Mono 8px muted。轴标题数值轴承载该族系的轴标签——Geist Mono 7px muted、letter-spacing0.14em、居中于 x580、y456位于刻度标签之下、图例分隔线之上。水平轴采用散点图 x 轴那种未旋转形式而不是柱状图 y 轴所用的rotate(-90 24 230)形式。类别轴不需要标题——行标签自己就是名称。端点、连接线与标签点r6按值定位。样式按序列区分参考端空心paper 填充、muted描边 1.5px焦点端实心accent填充 1pxink描边。两个标记因此都有高于 3:1 的边界即使 accent 填充本身达不到。Accent 标记的是序列而非焦点行实心点出现在每一行上——这是该变体对单 accent规则的唯一让步因为每一对的两端必须能区分。不要再额外 accent 一行变化最大的行排序已经承载了排名。连接线rgba(45,49,66,0.55)1px先声明再画点让点盖住线头。它不是轴线发丝线连接线传达这两个点属于同一行所以必须达到 3:10.55 给出 3.19:1轴线用的 0.25 只有 1.60:1。端点取整但不吸附x 200 (v − floor) ÷ (ceil − floor) × 760floor/ceil 由下面的轴规则决定结果四舍五入到最近整数像素——误差至多 0.5px不足一个渲染像素。数据坐标豁免于 4px 网格吸附会移动数据本身。数值标签放在对的外侧按几何而非序列放置焦点值若在参考值之下点序会反转因此取x_left min(x_ref, x_focal)、x_right max(x_ref, x_focal)左侧标签以x_left − 12右锚定右侧标签以x_right 12左锚定基线均为y 4Geist Mono 8px muted各带自己序列的值。若按起点/终点作偏移每个下降行都会让两个标签落到对的内侧。下限特例落在域下限的值其标签放 x188、以基线y 4右锚定——这与类别标签的锚点、基线完全相同两段文本会重叠。当x_left − 12 200时改为把该标签移到其点的上方居中基线y − 10。图例图例行放两个键——空心点、实心点各带序列名。圆形键心在cy493即柱状图 10px 键矩形y488的中心二者都落在 497 文本基线上。行排序写在图例或来源行中同行右对齐。Dumbbell 元素模式!-- One row. Connector first so the dots cap it; labels outside the pair. -- line x1458 y196 x2740 y296 strokergba(45,49,66,0.55) stroke-width1/ circle cx458 cy96 r6 fill#f5f5f5 stroke#4f5d75 stroke-width1.5/ circle cx740 cy96 r6 fill#eb6c36 stroke#2d3142 stroke-width1/ text x446 y100 fill#4f5d75 font-size8 font-familyGeist Mono, monospace text-anchorend34/text text x752 y100 fill#4f5d75 font-size8 font-familyGeist Mono, monospace71/text text x188 y100 fill#2d3142 font-size11 font-weight600 font-familyGeist, sans-serif text-anchorendPlatform/text文档给出的计算示例值 34 和 71 在 0–100 域上算出 458.4 与 739.6取整为 458 和 740。若这一行翻转焦点值更小accent 点会落到左侧两个锚点始终绑定左右两侧每个标签仍携带自己序列的值。为什么点按填充区分而不是按色相区分这是一个很容易被忽略的设计判断。焦点柱的12% 淡色 accent 描边模式无法移植到 6px 的点上12% 淡色摊在半径 6px 的圆盘上只贡献约 14 平方像素的颜色标记读起来只剩描边配对只能靠色相区分。而实心 accent 点 vs 空心点是形状区分在灰度打印与色觉缺陷下依然成立色相退化为冗余编码。非文本对比度靠边界而不是靠填充Accent 在 paper 上全域只有 2.86:1低于 WCAG 1.4.11 对理解内容所必需的图形对象要求的 3:1——而形状冗余并不能豁免它因为读者仍要看到标记的边界和连接配对的那条线。因此两者都不能交给 accent实心端点加 1pxink描边对 paper 11.82:1、对其自身填充 4.13:1连接线在浅色取 55% ink、深色取 40%3.19:1 与 3.24:1。空心端靠muted描边本就达标浅色 6.11:1、深色 7.07:1。[verify-dumbbell.py](https://link.gitcode.com/i/4b4650dd960514b577f949912ffffe61)对全部四项断言后续若有人改淡色不会悄悄把某项压到线以下。空心/实心的形状差异保留为灰度与色觉缺陷下的冗余编码——不要把两个点合并成单一填充。最小绘制间距——绝不钳制两个点都带r6空心点的 1.5px 描边横跨路径实际画到 6.75所以两标记在中心距 12.75px 处相触低于约 16px 时整对会读成一团——在 0–100 域、760px 宽上这对应 2.1 个数据单位的差距。文档明确禁止拉大间距来避开它把点移离缩放位置会破坏共享刻度规则。正确做法是保持真实位置并缩小标记r4 时 8.75px 相触或者直接打印两个值并把该行标记为间距过近、无法分辨。深色主题发丝线必须一起反转深色皮肤下点与标签按预期互换——空心填充#2d3142#bfc0c0描边、实心#f08a59#f5f5f5描边、标签#bfc0c0。但发丝线也必须反转网格线rgba(245,245,245,0.08)、轴线rgba(245,245,245,0.20)、连接线rgba(245,245,245,0.40)——连接线依然重于轴线理由同样是 3:1。这里有一条致命陷阱rgba(45,49,66,…)在任何透明度下都是深色 paper 的颜色把浅色皮肤下的连接线、网格线或轴线原样搬进深色图会合成到精确的 1.000:1——间距编码和刻度会一起消失。这一点与 style-guide.md 的反演规则RGB 翻转、透明度不变、accent 微调变亮互相印证。Dumbbell 诚实性规则四条轴域规则 三条叙事纪律这一节是文档最有技术分量的部分——它定义了哑铃图如何不说谎。永不截断数值轴floor与ceil必须跟随数据的取值范围绝不能跟随观测极值——直接拿min/max当边界就是截断。设lo、hi为最小、最大值四种情况穷尽lo 0锚定floor 0ceil向上取整越过hihi 0锚定ceil 0floor向下取整越过lolo 0 hi两侧括住零点落在绘图区内——必须在其缩放位置画一条轴线权重0.25 ink的零线因为每个间距都是对着它读的全员为零lo hi 0这是符号型规则必然漏掉的第四种情况。此时ceil − floor为 0位置公式会除零。取有限回退跨度floor 0、ceil 1按数据单位让每个点都落在下限上——这就是事实。数据只是触及零的情况由前两种情况覆盖不需要特例。绘图宽度固定因此收窄域会抬高每单位像素数、把每个间距画得更宽同样的 760px8 点的差距在 0–100 轴上画 61px在 40–80 轴上却画 152px。行与行之间的比例关系在缩放中幸存——被放大的只是每个间距相对画面的大小而读者正是靠这个判断间距大不大。间距是哑铃图的全部主张这也是哑铃图最常见的说谎方式。verify-dumbbell.py 中的resolve_domain()正是这套规则的代码实现从 1/2/2.5/5/10 阶梯取整幅度_nice_magnitude穷尽四种符号情形并在ceil floor不成立时抛DomainError。scale()镜像文档公式is_truncated()把边界紧贴数据判定为截断——这是对诚实性规则可执行化的直接落地。共享刻度与标签纪律两个点共享一条刻度、一个单位。两端都要标真实值——只标焦点端等于要求读者凭空相信几何位置。连接线是间距不是轨迹。它编码两个值之间的距离与中间发生什么无关——没有中间点、没有速率、不保证变化是单调的。不要把它叙述成运动。必须声明行排序写进图例或来源行——按一端排序、按带符号变化、按绝对值变化或按主题给定的顺序时间、地理、序数。只写按间距是歧义的要说带符号还是绝对。不允许的是未声明排序那读起来就是随意的。缺失端点的行要披露不能补值、不能静默丢弃。不说明就移除不完整类别会改变被比较的总体。要么画出已知端并注明缺失值要么丢弃该行并记录丢了哪些行、为什么——孤点与两个重合点即真实的零间距无法区分。两条规则住在公式里所以可执行文档明确写道这些规则中有两条住在公式而非画图里因此是可执行的[verify-dumbbell.py](https://link.gitcode.com/i/4b4650dd960514b577f949912ffffe61)在每种符号情形下解析域断言有限坐标与 3:1 标记[test-verify-dumbbell.py](https://link.gitcode.com/i/084174a51f62640439aaab023d7c04a9)双向锤炼两个极性——包括全员为零、触及零的数据以及被替换掉的 sub-3:1 旧处理。校验器的设计有两个值得注意的细节Fail-closed解析不了的参考文件、找不到的 token 都算 finding绝不算静默通过check_reference会确认type-bar.md实际写有rgba(45,49,66,0.55)与rgba(245,245,245,0.40)两个连接线 token 以及floor/ceil字样——散文与阈值不能漂移。对抗式测试测试文件覆盖 8 组域解析用例全员为零、零触正、零触负、全正、全负、跨零、相同值对、亚单位小值并验证空输入/NaN/无穷被拒绝、以观测极值作边界被is_truncated识别、双倍数据间距画出恰好两倍宽的间距、以及旧的 25% 发丝线连接线和未描边 accent 端点确实低于 3:1。这套好用例通过 坏用例必须失败的双极性结构与仓库中test-verify-*.py系列如 treemap、polar、sankey 的验证器是同一工程模式能把规则写进公式的就不只写在散文里。运行方式python3 scripts/verify-dumbbell.py # 退出码 0 干净 / 1 有 finding / 2 用法错误 python3 scripts/verify-dumbbell.py --reference path/to/type-bar.md python3 scripts/test-verify-dumbbell.py # 对抗式测试全部通过输出 OK示例文件与实战起点文档末尾列出三种成品全部存在于仓库skills/diagram-design/assets/下可直接在浏览器打开example-bar.html — 最小化浅色Sprint 速度 · 8 迭代视图example-bar-dark.html — 最小化深色example-bar-full.html — 完整编辑版含标题、副标题、三张差异化摘要卡与页脚 colophon实际动手时可按 SKILL.md 的流程复制skills/diagram-design/assets/template.html或template-full.html替换 eyebrow、h1 与 SVG 主体按本文的布局表计算每根柱的x/y/width/height然后跑 §9 的 Taste Gate。若新增的是柱状图示例仓库 CI 还会用scripts/lint-skin.py、scripts/lint-render.py与scripts/verify-geometry.py把关皮肤与几何见 README.md 的 Contributing 章节。上图来自仓库 docs/screenshots/bar.png——该图是柱状图类型的规范渲染可在动笔前先打开它直观感受一条焦点柱、其余 muted、发丝线网格的编辑级比例。小结柱状图在 diagram-design 中远不止画几根矩形从0 0 1000 500画布上的留白矩阵、4–8 条上限与 pitch/bar 比例到焦点柱的单一 accent 纪律再到 Dumbbell 变体围绕间距即主张建立的一整套布局与诚实性规则它把图表设计沉淀为可复制的语法和可校验的公式。最值得借鉴的工程实践是凡能写成公式的规则轴域解析、非文本对比度就写成脚本并配对抗式测试让文档散文与代码阈值互为约束永不漂移。【免费下载链接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考