说明目录
Garden 使用说明组件参考

组件参考 · compose

用 YAML 树画一张说明图。卡片、箭头和注释在构建期变成静态 HTML。

← 组件参考 · 用法：说明图

1示例

代码

```garden compose
title: 站点发布流水线
caption: 三步串起来，点哪步看哪步
intent: |
  用三张卡加向下箭头讲清 sync → build → validate；读者点每一步，下面展开对应说明。
steps:
  - id: sync
    title: sync
    text: 同步内容与配置
  - id: build
    title: build
    text: 生成静态 HTML
  - id: validate
    title: validate
    text: 检查后再上线
notes:
  - for: sync
    text: 先对齐远程与本地材料
  - for: build
    text: 构建期把 compose 渲进正文
  - for: validate
    text: 钩子拦住未编译的想法块
```

效果

站点发布流水线

三步串起来，点哪步看哪步

sync同步内容与配置

先对齐远程与本地材料

build生成静态 HTML

构建期把 compose 渲进正文

validate检查后再上线

钩子拦住未编译的想法块

要并排、加徽标和指标时，把节点写进 tree。窄屏仍是一列。

代码

```garden compose
title: 同步然后构建
caption: 点一张卡，看对应说明
intent: |
  两张卡用向右箭头连起来，每张卡上有徽标和指标。
tree:
  - row:
      - card:
          id: sync
          tone: accent
          title: sync
          badge: "1"
          kpi:
            value: 12
            unit: ms
            label: 对齐
          text: 同步内容与配置
      - arrow: right
      - card:
          id: build
          title: build
          text: 生成静态 HTML
  - notes:
      - for: sync
        text: 先对齐远程与本地材料
      - for: build
        text: 构建期把 compose 渲进正文
```

效果

同步然后构建

点一张卡，看对应说明

1sync12ms对齐同步内容与配置

先对齐远程与本地材料

build生成静态 HTML

构建期把 compose 渲进正文

2字段

围栏写 ```garden compose。正文还是白话时报 compose-uncompiled。YAML 树不合法时报 compose-invalid。

字段是否必填默认值取值与限制说明
title可选无字符串图内标题，不进入目录
caption可选无字符串标题下的一句说明
intent可选无字符串作者原话，不画出来
steps与 tree 二选一无1–8 项纵向或横向的步骤卡
notes跟 steps 一起写无1–8 项for 指向某个 id
tree与 steps 二选一无零件列表嵌套树。children 是别名
steps[].id有注释时必填无字母开头给注释点选用
steps[].title必填无字符串卡片标题
steps[].text可选无字符串卡片里的一句说明
steps[].badge可选无字符串或 { text, tone }徽标
steps[].kpi可选无{ value, label?, unit? }一个指标
steps[].tone可选plainplain、accent、tip、muted卡片底色。accent 和 tip 是两种强调色
notes[].for必填无已有的 id点哪张卡展开这条
notes[].text必填无字符串展开后的说明

tree 里的零件只有这些：stack、row、card、title、text、steps、compare、callout、divider、badge、kpi、arrow、fan、join、lanes、notes。

拼法跟说明图的骨架一致，不按某一张图单独改样式。

要画的东西写法
浅底通栏card + frame: band。tone: accent 和 tone: tip 是两种强调底，和泳道的 forward / back 同一对颜色
小胶囊card + frame: pill。tone: accent 是浅底胶囊
无框标题card + frame: text
带边框的卡card
圆圈序号badge: "①"
盾牌mark: shield
向下的箭头arrow: down
并排的几根向下箭头fan: 3，下一行 row 的格数相同
V 形连接，字写在缺口里join: 一句说明。两臂和短竖线是一条折线，开口朝上
泳道lanes。表头胶囊按内容收缩。说明在箭头上方。tone: forward 和 back 用两种强调色
脚注text + tone: muted
两列两行两个 row，每个两格

frame: band 和 frame: text 标题下的那一句是灰色说明。居中 stack 里的脚注要靠左，写 align: start。

  • arrow 的方向是 down 或 right。窄屏上向右的箭头会改成向下。
  • callout 的 tone 是 note、tip、warn。
  • compare 写 2–4 项，每项有 title 和可选的 text。
  • 不要写 HTML、脚本、色值或宽度。颜色只来自主题变量。
  • 嵌套最多 8 层，整张图最多 80 个零件。被点选的卡片不要再套一张被点选的卡片。

3限制与报错

  • 点开一步时，说明出现在这一步下面。同一张图里同时只展开一条。不打开 JavaScript 也能点开。
  • 正文不是 YAML 树（还是一句想法）时报 compose-uncompiled。草稿里可以留着，发布前必须编译。
  • 树的形状、未知零件、对不上的 for 或重复的 id 报 compose-invalid。
目录