Menu
Use when writing or editing a leaf apps/docs concept page to explain a module-specific mental model, boundary, or architecture.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when changing any retikz apps/docs content, route data, i18n, demo, SourceLinks, or schema reference before loading the matching page-type skill.
Use when retikz needs multiple independent LLMs to review the same fixed code, ADR, implementation plan, test contract, commit, or working-tree snapshot before a gate or delivery decision.
Use when an Alpha ADR needs a pre-implementation capability gate, or a Beta milestone needs code-based completeness and package-boundary auditing.
Use when planning a retikz architecture direction, version roadmap, or alpha feature that may need a long-lived ADR before implementation.
Use when retikz work is primarily refactoring, reorganization, renaming cleanup, modularization, or internal simplification and should start from a reviewed implementation plan before code changes.
Use when retikz implementation, adversarial testing, and docs are complete, and an ADR or beta TODO needs changelog, contract consistency review, roadmap status updates, or final human acknowledgement.
| name | docs-doc-concept |
| description | Use when writing or editing a leaf apps/docs concept page to explain a module-specific mental model, boundary, or architecture. |
apps/docs/src/modules/docs/contents/<module>/concepts/** 下加 / 改叶子概念页（如 kernel 的坐标系 / anchor / 分层；viz 的 scale / encoding / mark；renderer 的 backend / animation……）docs-doc-principle 拿通用规则本 skill 只覆盖概念页特有的页面结构与写法。其它一切（三处协同、双语、写作风格、Comparison、宽度、不引外链等）以 principle 为准；配图画法走 docs-figure-contract，本 skill 不重复画法细节。
不归本 skill：
| 页 | 去哪 |
|---|---|
分组落地页（带 children，如 concepts/design、concepts/basic-concepts） | docs-doc-group——它们是「职责一览表 + LinkedCard 子项」骨架，不是概念叶子页 |
入口页（introduction / get-start） | docs-doc-principle 的「入口页例外」节 |
配图的 stroke="none" / 配色 / y 轴 / 双语拆分等画法 | docs-figure-contract |
概念页讲抽象概念 / 心智模型 / 架构——读者不是来查 API，是来「搞懂这套模型怎么运作、什么时候该用哪一层」。与其它 section 的边界：
| Section | 服务什么 |
|---|---|
components/ | 单组件 API 字典 + 该组件的 demo |
examples/ | 多组件组合成完整图，按 step 教 |
reference/ | schema 字段查询入口 |
concepts/（本 skill） | 模块的抽象概念 / 心智模型 / 架构（core: 坐标系·anchor·分层；plot: scale·encoding；…） |
不是什么：
components/ 或 reference/）examples/）概念页不绑定 core 的术语。动笔前先识别当前模块的核心模型，再用它组织页面——同一套写法服务所有模块：
| 模块类型 | 概念页重点 | 该模块的内部模型（示例） |
|---|---|---|
| core / 基础绘图 | 图元、坐标、关系、渲染链路 | Node / Path / Anchor、IR / Scene / compile |
| plot / 图表语义 | 数据到视觉的映射 | scale / domain / encoding / mark / axis / lowering |
| renderer / runtime | 输出目标与执行行为 | backend / animation / hydration / measurement |
| 扩展 / composite | 上层抽象如何下沉到底层能力 | lowering / adapter / registry |
本 skill 后文出现的 IR / Scene / Sugar / Kernel / anchor 等都是 core 语境下的举例，不是规则本身——换模块时替换成该模块对应的模型词。
写作主线（模块无关）：先说为什么需要这个概念 → 再给模块内的心智模型 → 用图 / 表 / 小 demo 支撑 → 说清边界·选择·常见误解 → 链到 API / reference / example。
概念页没有固定段序（不像示例页的 6 段）；按概念拆 H2，顺序因主题而异。下面是一份推荐小节菜单——按需取用、不强凑：
| 小节类型 | 作用 | 语料里的例子 |
|---|---|---|
| 总览 / 一张图看懂 | 开篇给一张全局图或职责框架表 | primitive-model 的「一张图看懂」、layers 的 hero 管线图 |
| 子概念分节 | 每个 H2 讲一个子概念 | coordinate-system 的 笛卡尔 / 极坐标 / user units / viewBox |
| 选择 / 决策 | 帮读者在变体间选 | 「怎么选择」「选择建议」「什么时候手写 viewBox」 |
| 边界 / 区别 | 和相邻概念划清界限 | composite「与 Sugar 的区别」、primitive-model「和扩展形状的关系」 |
| 约束 / 陷阱 | 易错点、硬性要求 | position「前向引用要求」、animation「触发与降级」 |
| 延伸阅读 | LinkedCard 网格收尾 | layers「延伸阅读」 |
开头约定：
title / description 写 frontmatter，正文不写 H1<ComponentAlert type="tip">，让只想先画图的人先去 get-start / components结尾约定：
## 延伸阅读 + <LinkedCard> 网格（见下文「跨链接」）H2 进右侧 TOC；同一概念下的细分点用 H3。
概念页优先用能解释模型的图，多数是 <ComponentPreview hideCode> 自绘的叙述插图（看懂概念，不是复制源码）。但 hideCode 不是死规则，按图的性质定：
| 图的性质 | hideCode | 例 |
|---|---|---|
| 架构 / 模型 / 流程图 | 默认 true（隐藏代码） | 分层管线、依赖图、anchor 结构 |
| 用户可直接书写的概念语法 | 可 false，让读者看写法 | 坐标 / 定位语法、plot 的 encoding 写法 |
| 结果解释型（可视化模块常见） | demo code 与图并列 | plot 的 scale / mark 效果，代码 + 渲染结果对照 |
多画图、图文结合——概念页是 retikz 的活体演示，一个抽象概念配一张图，往往胜过三段文字。判断一页概念文档好不好，先看它有没有把模型「画」出来。配图风格走学术、简约（节点默认无描边、克制用色、不堆装饰）——细则见 docs-figure-contract。
哪种概念配哪种图（图型通用，例子是 core 口味，换模块照搬图型即可）：
| 概念 | 图型 |
|---|---|
| 分层 / 管线 / 编译 / lowering 流程 | 横向或纵向流水线，箭头表数据流 |
| 包 / 依赖关系 | 依赖图（实线主依赖、虚线次依赖） |
| 单实体结构（core anchor / boundary、plot mark 等） | 单个实体放大 + 锚点 / 通道标注 |
| 引用 / 关系 / 数据→视觉映射 | 靠 id 连线的关系图 / 编码映射图 |
硬约束：
anchors 代表的依赖」），否则图是孤儿<Draw> 的 { label: { text, side, textColor } } 在箭头中点标注每段处理 / 中间产物docs-figure-contract：stroke="none" 当文字锚点、配色、y 轴朝下、宽度自适应、双语拆分条件、验证规则——本 skill 不重复概念页是表格密集型，四类主力表（列名通用，不绑模块）：
| 类型 | 列 | 用途 |
|---|---|---|
| 模型表 | 概念 / 角色 / 影响 | 摆清一套模型里各部分的职责 |
| 决策表 | 场景 / 推荐 / 原因 | 帮读者在变体间选 |
| 映射表 | 用户写法 / 内部模型 / 输出效果 | 把「写什么」对到「内部怎么表示 / 渲染出什么」 |
| 对照表 | 概念 A / 概念 B / 何时用 | 划清相邻概念边界 |
宽度沿用 principle：≤3 列、单元格 ≤12 中文字；过长用 <br /> 软断或拆段；cell 内 | 写 \|。
principle 规定普通用法页隐藏内部表示；概念 / 设计页是例外——可以解释模块的内部模型，但不默认展开内部实现。把握分寸：
<Draw way> ↔ <Path><Step/> 是一例；plot 的高层 mark ↔ 下沉后的 Tier 1 同理），而不是只下断言reference/ 或专页概念页描述架构面，最容易随版本漂移过期——本 skill 把「保鲜」列为硬要求：
0.x 不写兼容 / 迁移：0.x 破坏性变更是常态，不留 v0.1→v0.x 迁移说明reference/，看用法 → components/，看综合图 → examples/，相邻概念 → sibling concept。plot 等模块可能跳到 examples/ 或模块自己的 reference——按该模块实际页型走，不照搬 core 的去向## 延伸阅读 + LinkedCard 网格：## 延伸阅读
<div className="my-6 grid grid-cols-1 gap-4 sm:grid-cols-2">
<LinkedCard href="/kernel/reference/schema">
<span className="font-semibold">结构</span>
<span className="mt-1 text-center text-sm text-muted-foreground">查 IR 各实体的字段</span>
</LinkedCard>
{/* 2-4 张，2 列网格 */}
</div>
title；href 必须命中 data/<module>.ts 注册的 id<LinkedCard> 是全局 MDX 组件，不用 import<ComponentAlert type="tip">| 任务 | skill |
|---|---|
| 通用规则 / 三处协同 / 双语 / 页型分流 | docs-doc-principle |
| 概念页结构与写法（本 skill） | docs-doc-concept |
| 叙述性插图画法 | docs-figure-contract |
| 组件 API 页 | docs-doc-component |
| 示例 step 页 | docs-doc-example |
| 分组落地页 | docs-doc-group |
| schema 词典页 | Reference 按需契约 |
components/ / reference/ 的活；概念页讲模型，具体 API 用 link 跳出去docs-figure-contract）hideCode） —— 概念页配图是「看懂概念」，显源码会被误当成「复制学写」的 demohref 没命中注册 id，或 zh / en 目标 slug 不同没分别核concepts/design）走 docs-doc-grouppackages/kernel 源码核实；冲突时要么修正、要么把「例外」写清楚（如 margin 对参数驱动 shape 无效、compass anchor 走 bbox），不让文档和实现打架按 docs-doc-principle 的分级验证规则选择命令：纯 MDX 文案只需 git diff --check + 页面 / 链接检查；新增或修改 demo / data / import 时再跑 pnpm --filter @retikz/docs exec tsc --noEmit。概念页有插图时仍要用浏览器打开页面，确认中英、插图、TOC、菜单都对。
逐项核：
packages/kernel 当前实现一致，冲突处的「例外」已写清id；LinkedCard href 可达；zh / en 两份分别点；CJK / 带符号锚链接用 github-slugger 核 slug