markdown-graphs

用途

markdown-graphs 是用于在 MDX 文档中设计与实现“以文字为主”的技术图解的技能。它明确说明：“markdown graph”只是 MDX 中自定义可视化组件的简称，并不是 Markdown 原生的图表格式。它强调应保留用户的发布媒介：如果目标渠道只接受纯 Markdown，就应产出静态 SVG 或图片；当可移植性比艺术效果更重要时，也可以改用 Mermaid。

设计方法

该技能建议先设计解释，再动手绘制：

把视觉内容压缩为一个主张、一次对比、一个序列或一种关系。
选择能解释它的最小拓扑：表格、嵌套几何、从左到右的变换或循环。
在画连接线之前先写好标签和数值。
在严格的类似字符网格或 8px 网格上布局内容。
只有当装饰有助于说明分组、方向或状态时才添加。
如果一个图需要一整段文字才能解释清楚，应简化图本身，而不是继续增加结构。

渲染原语的选择

技能根据内容类型给出了首选原语：

行列数据：语义化 HTML <table>，保持数据可访问且响应式。
需要精确线性化的文本：使用带样式的 span 的 <pre>，保留字符单元式排版。
标签、公式与简单对比：CSS Grid，让实时文本易于对齐与换行。
连接线、嵌套几何或精确路径：内联 SVG，提供精确且响应式的几何。
移动的轨迹线或芯片：SVG path 配合 CSS 或 <animateMotion>，复用解释路径作为运动轨道。

技能建议尽量使用实时 HTML 文本，并加一层 aria-hidden 的 SVG 连接线层。它明确反对默认使用 Mermaid：Mermaid 的自动布局适合可移植的架构文档，但与这种刻意编排的视觉语言相冲突。

视觉语法

优先沿用项目已有的字体与颜色令牌；若项目没有既定系统，资料给出了以下采样值作为起点（并非规范值）：

--graph-bg: #11110f;
--graph-ink: #c9c5bb;
--graph-muted: #343632;
--graph-accent: #3296f9;

其他视觉规则包括：

使用一种常规字重的等宽字体，Commit Mono 或良好的 ui-monospace 字体栈符合参考风格。
保持四种视觉角色：背景、可读文字、弱化结构和一个鲜明强调色。
强调色只用于标题、激活状态或移动的轨迹线，用于指示“该看哪里”。
使用带方括号的大写标题，如 [ THE PROMPT LOOP ]，字距适度。
用安静的虚线、+ 角标、括号和箭头字形构成边框，边框应明显弱于内容。
留出充足负空间与一致的外边距，不要填满网格的每一个单元格。
避免渐变、发光、阴影、装饰性填充卡片、多个强调色和不必要的圆角容器。
对齐的测量值与表格使用等宽数字（tabular numerals）。

动效原则

动效是可选的，仅在用户要求、参考素材包含或交付物本身就是解释性动画时加入。加入时，只应动序列、方向、传播或状态变化，标签与基础结构保持静止。

移动的连线高亮通过画两遍路径实现：一条完整的弱化底线，和上方一段短强调线段。用 pathLength="1" 归一化路径并动画 stroke-dashoffset：

.trace {
  stroke: var(--graph-accent);
  stroke-dasharray: 0.08 0.92;
  animation: graph-travel 4s linear infinite;
}

@keyframes graph-travel {
  to {
    stroke-dashoffset: -1;
  }
}

当字形或编号芯片需要沿已有路径运动时，使用 SVG <animateMotion> 配合 <mpath>。常量遍历用线性运动，状态间刻意移动用强 ease-in-out 曲线。解释性循环应保持约 3–5 秒的舒缓节奏，便于跟随。循环动效在组件离屏时应暂停，且这一行为应实现在交付的组件中，而不是留作后续建议。需遵守 prefers-reduced-motion，并保留有意义的静态高亮状态。绝不能让动画成为读懂信息的必要条件。

在 MDX 中使用

文章中的调用应保持简短，组件在边框与令牌层面可复用，不要强行把不相关的图塞进一个通用 schema：

import { PromptLoop } from "@/components/PromptLoop";

<PromptLoop />

实现要点：

使用 SVG viewBox 与 vector-effect="non-scaling-stroke" 保证响应式且清晰的线条。
当标题需要“切开”身后的边框时，使用 paint-order: stroke 配合背景色。
有意义的标签应保持为文本，而不是轮廓化路径或烘焙像素。
将视觉内容包在 <figure> 中，并提供可访问名称或可见的 <figcaption> 说明其要点。
源文件保持为实时组件，仅在需要静态资源的渠道导出高分辨率 SVG、PNG 或视频。

验收检查

技能建议在宣布完成前确认：

关闭动画后要点依然清晰。
强调色只有一个语义职责，弱化结构确实退居背景。
标签对齐到一致网格，没有连接线穿过可读文字。
在最窄目标宽度下组件仍然可读且不被裁切。
减少动效行为保留了解释内容。
渲染截图匹配目标 MDX 界面，而不只是孤立的组件预览。

参考

资料列出的主要参考包括：Emil Kowalski 的原始示例、关于这些是自定义 MDX 视觉的说明、SVG animateMotion 技术、MDX 组件模型以及 MDN 的 SVG <animateMotion> 文档。

限制

资料未提供该技能的安装命令、版本号、许可证或具体平台支持信息；上述内容均依据技能说明整理，未对功能或效果做额外推断。