hd-garden 0.13.2 → 0.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (220) hide show
  1. package/.agents/skills/garden-compose/SKILL.md +24 -0
  2. package/.agents/skills/garden-compose/references/colors.md +11 -0
  3. package/.agents/skills/garden-compose/references/composition-patterns.md +162 -0
  4. package/.agents/skills/garden-compose/references/examples.md +55 -0
  5. package/.agents/skills/garden-compose/references/frames.md +7 -0
  6. package/.agents/skills/garden-compose/references/layout-recipes.md +84 -0
  7. package/.agents/skills/garden-compose/references/rendering-model.md +120 -0
  8. package/.agents/skills/garden-compose/references/static-play.md +19 -0
  9. package/.agents/skills/garden-compose/references/visual-selection.md +38 -0
  10. package/.agents/skills/garden-compose/references/workflow.md +27 -0
  11. package/.agents/skills/garden-compose/scripts/_cli.mjs +12 -0
  12. package/.agents/skills/garden-compose/scripts/apply.mjs +2 -0
  13. package/.agents/skills/garden-compose/scripts/check.mjs +2 -0
  14. package/.agents/skills/garden-compose/scripts/prompt.mjs +2 -0
  15. package/.agents/skills/garden-compose/scripts/scan.mjs +2 -0
  16. package/.agents/skills/garden-post-review/SKILL.md +5 -16
  17. package/Makefile +12 -3
  18. package/README.en.md +10 -5
  19. package/README.md +10 -5
  20. package/app/admin/preview/[...path]/page.tsx +3 -15
  21. package/app/api/admin/ui/blocks/route.ts +1 -1
  22. package/app/components/AdminUiPanels.tsx +6 -3
  23. package/app/components/GardenContentGuide.tsx +7 -8
  24. package/app/components/MarkdownArticle.tsx +6 -47
  25. package/app/components/TableOfContents.tsx +0 -1
  26. package/app/components/UiStudio.tsx +29 -32
  27. package/app/components/garden/AuthorRich.tsx +5 -0
  28. package/app/components/garden/ComposePreview.tsx +9 -0
  29. package/app/components/garden/GardenBlock.tsx +12 -10
  30. package/app/components/garden/GardenFile.tsx +1 -1
  31. package/app/components/garden/blocks.tsx +9 -197
  32. package/app/components/garden/file-icons.tsx +1 -1
  33. package/app/components/garden/patterns.tsx +7 -65
  34. package/app/lib/content.ts +5 -22
  35. package/app/lib/heading-number.ts +2 -7
  36. package/app/lib/rehype-garden-blocks.mjs +30 -0
  37. package/app/lib/remark-garden.mjs +0 -4
  38. package/app/lib/ui-model.ts +8 -9
  39. package/app/styles/a2.css +17 -1
  40. package/bin/garden.mjs +43 -36
  41. package/docs/handbook/ai-writing.md +19 -22
  42. package/docs/handbook/components/compose.md +16 -7
  43. package/docs/handbook/components/image.md +1 -1
  44. package/docs/handbook/components/link-card.md +2 -2
  45. package/docs/handbook/components.md +5 -213
  46. package/docs/handbook/deploy.md +11 -0
  47. package/docs/handbook/en/ai-writing.md +17 -20
  48. package/docs/handbook/en/components/compose.md +15 -6
  49. package/docs/handbook/en/components/image.md +1 -1
  50. package/docs/handbook/en/components/link-card.md +2 -2
  51. package/docs/handbook/en/components.md +7 -215
  52. package/docs/handbook/en/deploy.md +11 -0
  53. package/docs/handbook/en/index.md +29 -53
  54. package/docs/handbook/en/reference/compose.md +77 -148
  55. package/docs/handbook/en/reference.md +6 -22
  56. package/docs/handbook/en/start.md +1 -1
  57. package/docs/handbook/en/workflow.md +20 -16
  58. package/docs/handbook/en/writing.md +2 -2
  59. package/docs/handbook/index.md +26 -47
  60. package/docs/handbook/reference/compose.md +79 -148
  61. package/docs/handbook/reference.md +6 -22
  62. package/docs/handbook/start.md +1 -1
  63. package/docs/handbook/workflow.md +20 -16
  64. package/docs/handbook/writing.md +2 -2
  65. package/editors/dist/typora/main.js +324 -330
  66. package/editors/dist/typora/style.css +4299 -11
  67. package/editors/dist/vscode/garden-ui-0.1.1.vsix +0 -0
  68. package/eslint.config.mjs +3 -0
  69. package/package.json +3 -2
  70. package/public/images/compose-resources/resource-015b41eb0f32.svg +1 -0
  71. package/public/images/compose-resources/resource-ecee6b47f015.svg +1 -0
  72. package/public/images/compose-resources/resource-fd51121b5e8c.svg +1 -0
  73. package/scripts/build-content.mjs +59 -141
  74. package/scripts/build-ui-preview.mjs +7 -5
  75. package/scripts/check-post.mjs +8 -104
  76. package/scripts/check-site.mjs +80 -0
  77. package/scripts/compose-style-reference.mjs +22 -0
  78. package/scripts/dev-server.mjs +114 -0
  79. package/scripts/editor-preview-css.mjs +14 -0
  80. package/scripts/file-preview.mjs +1 -1
  81. package/scripts/file-sizes.mjs +7 -7
  82. package/scripts/generated-cache.mjs +36 -0
  83. package/scripts/handbook-facts.mjs +10 -3
  84. package/scripts/image-sizes.mjs +6 -12
  85. package/scripts/link-assets.mjs +35 -10
  86. package/scripts/managed-skills.mjs +56 -0
  87. package/scripts/prepare-pages-output.mjs +1 -1
  88. package/scripts/site-guide.mjs +19 -0
  89. package/scripts/ui-cli.mjs +26 -33
  90. package/templates/garden-blocks.md +4 -180
  91. package/templates/garden-snippets.plist +2 -183
  92. package/templates/site/AGENTS.en.md +89 -0
  93. package/templates/site/AGENTS.md +72 -0
  94. package/templates/site/Makefile +12 -3
  95. package/templates/site/Makefile.en +12 -3
  96. package/templates/site/README.en.md +8 -1
  97. package/templates/site/README.md +8 -1
  98. package/templates/skills-en/garden-compose/SKILL.md +24 -0
  99. package/templates/skills-en/garden-post-review/SKILL.md +5 -16
  100. package/templates/workflows/pages.en.yml +11 -0
  101. package/templates/workflows/pages.yml +11 -0
  102. package/ui/compose/compose.css +54 -14
  103. package/ui/compose/contracts.mjs +16 -0
  104. package/ui/compose/dil.mjs +109 -48
  105. package/ui/compose/distribution.mjs +7 -0
  106. package/ui/compose/features.mjs +90 -0
  107. package/ui/compose/icons.mjs +8 -0
  108. package/ui/compose/index.mjs +2 -0
  109. package/ui/compose/inspect.mjs +11 -0
  110. package/ui/compose/markup.mjs +80 -23
  111. package/ui/compose/preview.mjs +13 -0
  112. package/ui/compose/prompt-catalog.mjs +15 -3
  113. package/ui/compose/render.mjs +46 -11
  114. package/ui/compose/scenes.mjs +10 -0
  115. package/ui/core/apply.mjs +12 -45
  116. package/ui/core/catalog.mjs +22 -32
  117. package/ui/core/cli-locale.mjs +8 -18
  118. package/ui/core/color.mjs +34 -0
  119. package/ui/core/compile.mjs +1 -8
  120. package/ui/core/demos.mjs +138 -108
  121. package/ui/core/fence.mjs +14 -70
  122. package/ui/core/fix-prompt.mjs +1 -3
  123. package/ui/core/garden-fence.mjs +3 -63
  124. package/ui/core/index.mjs +3 -5
  125. package/ui/core/parse.mjs +22 -8
  126. package/ui/core/scan.mjs +31 -43
  127. package/ui/core/starters.mjs +3 -3
  128. package/ui/core/static.mjs +36 -6
  129. package/ui/core/transform.mjs +64 -149
  130. package/ui/core/validate.mjs +20 -9
  131. package/ui/garden/article-content.mjs +98 -0
  132. package/ui/garden/catalog.mjs +21 -427
  133. package/ui/garden/check.mjs +18 -60
  134. package/ui/garden/file-block.mjs +1 -1
  135. package/ui/garden/file-paths.mjs +8 -6
  136. package/ui/garden/markdown-syntax.mjs +1 -1
  137. package/ui/garden/parse.mjs +19 -182
  138. package/ui/garden/relations.mjs +1 -1
  139. package/ui/garden/snippets.mjs +12 -153
  140. package/ui/garden/source-icon.mjs +17 -9
  141. package/ui/garden/word-count.mjs +16 -85
  142. package/ui/index.mjs +1 -5
  143. package/ui/preview/dist/garden-ui.css +4300 -11
  144. package/ui/preview/dist/garden-ui.esm.js +446 -418
  145. package/ui/preview/dist/garden-ui.iife.js +446 -418
  146. package/ui/preview/index.tsx +31 -98
  147. package/ui/preview/site-config.ts +4 -0
  148. package/ui/prompt/build.mjs +1 -4
  149. package/ui/prompt/recipes/code-walkthrough.md +17 -12
  150. package/ui/prompt/recipes/compare.md +14 -10
  151. package/ui/prompt/recipes/compose.md +3 -3
  152. package/ui/prompt/recipes/converter.md +17 -14
  153. package/ui/prompt/recipes/data-chart.md +9 -8
  154. package/ui/prompt/recipes/inspect-grid.md +9 -8
  155. package/ui/prompt/recipes/param-bench.md +17 -12
  156. package/ui/prompt/recipes/plan.md +4 -3
  157. package/ui/prompt/recipes/stepper.md +18 -16
  158. package/ui/prompt/recipes/trace.md +20 -18
  159. package/ui/prompt/rules.md +26 -133
  160. package/ui/prompt/studio.md +3 -18
  161. package/ui/react/CatalogPage.tsx +19 -21
  162. package/ui/react/recipes.ts +3 -3
  163. package/ui/react/runtime.tsx +23 -2
  164. package/ui/react/ui.css +17 -11
  165. package/vite.config.ts +46 -8
  166. package/.agents/skills/garden-interactive-chart/SKILL.md +0 -84
  167. package/.agents/skills/garden-interactive-chart/references/shell.html +0 -49
  168. package/.agents/skills/garden-interactive-chart/references/style.md +0 -61
  169. package/.agents/skills/garden-ui/SKILL.md +0 -125
  170. package/app/components/UiBlock.tsx +0 -23
  171. package/app/components/WidgetChart.tsx +0 -224
  172. package/app/lib/generated-content.ts +0 -385
  173. package/docs/handbook/components/card.md +0 -67
  174. package/docs/handbook/components/chart.md +0 -38
  175. package/docs/handbook/components/choice.md +0 -42
  176. package/docs/handbook/components/compare.md +0 -53
  177. package/docs/handbook/components/file.md +0 -29
  178. package/docs/handbook/components/html.md +0 -49
  179. package/docs/handbook/components/interactive.md +0 -48
  180. package/docs/handbook/components/list.md +0 -65
  181. package/docs/handbook/components/relations.md +0 -95
  182. package/docs/handbook/components/stat.md +0 -39
  183. package/docs/handbook/components/timeline.md +0 -37
  184. package/docs/handbook/en/components/card.md +0 -67
  185. package/docs/handbook/en/components/chart.md +0 -38
  186. package/docs/handbook/en/components/choice.md +0 -42
  187. package/docs/handbook/en/components/compare.md +0 -53
  188. package/docs/handbook/en/components/file.md +0 -29
  189. package/docs/handbook/en/components/html.md +0 -49
  190. package/docs/handbook/en/components/interactive.md +0 -44
  191. package/docs/handbook/en/components/list.md +0 -65
  192. package/docs/handbook/en/components/relations.md +0 -95
  193. package/docs/handbook/en/components/stat.md +0 -39
  194. package/docs/handbook/en/components/timeline.md +0 -37
  195. package/docs/handbook/en/reference/card.md +0 -85
  196. package/docs/handbook/en/reference/chart.md +0 -68
  197. package/docs/handbook/en/reference/choice.md +0 -69
  198. package/docs/handbook/en/reference/compare.md +0 -59
  199. package/docs/handbook/en/reference/file.md +0 -50
  200. package/docs/handbook/en/reference/html.md +0 -62
  201. package/docs/handbook/en/reference/interactive.md +0 -71
  202. package/docs/handbook/en/reference/list.md +0 -72
  203. package/docs/handbook/en/reference/relations.md +0 -113
  204. package/docs/handbook/en/reference/stat.md +0 -60
  205. package/docs/handbook/en/reference/timeline.md +0 -56
  206. package/docs/handbook/reference/card.md +0 -85
  207. package/docs/handbook/reference/chart.md +0 -68
  208. package/docs/handbook/reference/choice.md +0 -69
  209. package/docs/handbook/reference/compare.md +0 -59
  210. package/docs/handbook/reference/file.md +0 -50
  211. package/docs/handbook/reference/html.md +0 -62
  212. package/docs/handbook/reference/interactive.md +0 -71
  213. package/docs/handbook/reference/list.md +0 -72
  214. package/docs/handbook/reference/relations.md +0 -113
  215. package/docs/handbook/reference/stat.md +0 -60
  216. package/docs/handbook/reference/timeline.md +0 -56
  217. package/templates/skills-en/garden-interactive-chart/SKILL.md +0 -84
  218. package/templates/skills-en/garden-interactive-chart/references/shell.html +0 -49
  219. package/templates/skills-en/garden-interactive-chart/references/style.md +0 -61
  220. package/templates/skills-en/garden-ui/SKILL.md +0 -125
@@ -1,182 +1,113 @@
1
1
  ---
2
- title: 组件参考 · compose
2
+ title: 组件参考 · Compose
3
3
  navTitle: compose
4
- description: 全部 compose 标签一览、共用 token,以及图标目录入口。
4
+ description: 单一作者入口、可执行渲染契约与验证。
5
5
  section: reference
6
6
  order: 6
7
7
  badge: compose
8
8
  ---
9
9
 
10
- [← 组件参考](/garden/reference) · [用法](/garden/components/compose) · [图标目录](/garden/reference/compose-icons)
10
+ ZH: 统一使用 `garden compose`;以下按真实实现解释组合机制、内容边界与检查方法。完整属性按需运行 `npx garden ui schema`,不复制易过期的目录。
11
11
 
12
- 围栏写 ` ```garden compose `。作者原话放 `<intent>`(不绘制)。未知标签报 `compose-invalid`。
12
+ ## One entry, component selection inside it
13
13
 
14
- 当前 **68** 个标签(见下方目录)。图标 **690** 个名字 —— 见 [图标目录](/garden/reference/compose-icons)。
14
+ Use `garden compose`. Select by the reader's task, not by another fence name:
15
15
 
16
- ## 共用 token
16
+ | Need | Compose structure |
17
+ | :--- | :--- |
18
+ | Reference material and takeaways | `resources/resource`, nested `point`, `reference` |
19
+ | Key results | `metric` with label, value, unit, caption, paragraphs and references |
20
+ | Time or stages | `timeline/event` |
21
+ | Alternatives and verdicts | `compare/item` |
22
+ | Icon-led editorial paragraphs | `icon-list/entry` or a small `icon` beside one shared text container |
23
+ | Download and preview | `files/file` or one `file src="…"` |
24
+ | Connected concepts | `relations/entity/edge`, stable ids; 3–6 entities |
25
+ | Rich selectable cards and replies | `choices/choice-option`, optional `none` option |
26
+ | Discrete bars and exact values | `plot/datum`; expandable data table |
27
+ | Parameter-dependent results | Play declarations, controls, `chart/bar/line`, `pie`, `table` |
28
+ | Article text and useful HTML | `markdown` and `html` content islands |
29
+ | Independent executable illustration | Play `sandbox` with literal html/css/js; isolated offline iframe |
17
30
 
18
- 多数布局标签共用;颜色只走 Garden 主题变量(Claude 纸色)。
31
+ The authoritative, demand-loaded catalog is `npx garden ui schema`: actual semantic fields, Play props/defaults/child contracts, icon names, safe HTML tags/attributes/CSS properties. `npx garden ui prompt` adds working recipes. `styleReference` also extracts current font/layout declarations, selectors, responsive conditions and source order from the installed stylesheets; it reports source defaults, not universal computed values. These are generated from the validators and actual styles; do not maintain a second exhaustive tag list. Static layout normalization is not a universal HTML/CSS API: inspect the normalized tree and output because some unsupported static layout attributes are ignored. Semantic unknown fields fail validation.
19
32
 
20
- | Token | 取值 |
21
- | :--- | :--- |
22
- | `padding` / `gap` | `0`–`4`(4px × n) |
23
- | `background` | `surface` `surface-secondary` `surface-accent` `surface-tip` `surface-muted` `transparent` |
24
- | `radius` | `none` `sm` `md` `lg` `xl` `full` |
25
- | `border` | `subtle` `strong`/`true` `none`/`false` |
26
- | `size` | `sm` `md` `lg` `xl` |
27
- | `tone` | `plain` `accent` `tip` `muted`(callout 另有 `note`/`warn`) |
28
- | `align` | `start` `center` `end` `stretch` |
29
- | `justify`(row) | `start` `center` `end` `between` `around` |
30
- | `wrap`(row) | `wrap` `nowrap` |
33
+ 图表的可运行示例见[Compose 活跃时段图](/garden/components/compose#ui-compose-chart-active-hours)。
31
34
 
32
- ## 高频属性
35
+ ## Relationships → hierarchy → layout → style → actual output
33
36
 
34
- ### `box` / `card`
37
+ First identify what belongs together. A heading and all its paragraphs must share a container. Next choose columns and proportions, then alignments and typography. Only then add surfaces and decorative details.
35
38
 
36
- | 属性 | 说明 |
37
- | :--- | :--- |
38
- | `frame` | `card`(默认)`band` `pill` `text`;也可用糖标签 `<band>` / `<pill>` |
39
- | `padding` `gap` `radius` `border` `background` `size` `align` `tone` `id` `mark` | 共用 token;`mark="shield"` 画盾牌 |
39
+ A static `row` wraps by default. Its direct text/title/stack/card children share available width (`flex: 1 1 0`), whereas an icon is content-sized. A heading placed directly in that row is a sibling column, not the heading of a paragraph below the row. `align="center"` on a row changes more than vertical placement: theme rules also center text. A centered stack propagates text alignment. For an editorial list use explicit start alignment on children of a shared right-hand group; do not center each title independently.
40
40
 
41
- ### `row` / `stack` / `grid`
41
+ Direct `row > stack` has 12px top padding in the current theme. A `group` is a width:100%, min-width:0 vertical container that shrinks beside the fixed icon and reads gap without that contextual padding; use it when icon and heading must begin on the same top line. Explicit `align="start"` survives normalization and emits data-align.
42
42
 
43
- | 属性 | 说明 |
44
- | :--- | :--- |
45
- | `gap` `align` | 共用 |
46
- | `justify` `wrap` | 仅 `row` |
47
- | `cols` | 仅 `grid`,1–6 |
48
- | `span` | 仅 `grid-item`,1–6 |
43
+ Nested paragraphs need separate `text` leaves or an article content island. Two unrelated top-level leaves do not establish a shared right column. Put a full-width divider **between rows**, not inside the right text container, if the rule must span the icon column too. `divider` and `separator` are real primitives, not text lines.
44
+
45
+ ```garden compose
46
+ <figure frame="none">
47
+ <row wrap="nowrap" align="start" gap="4">
48
+ <icon name="book-open" size="xl"/>
49
+ <group gap="2">
50
+ <title align="start">Test heading — not article content</title>
51
+ <text align="start">Explicit test paragraph: the heading and this body share the same right column. Keep the author's complete text; do not shrink or summarize it to fit.</text>
52
+ <text align="start">A second independent test paragraph stays in that column.</text>
53
+ </group>
54
+ </row>
55
+ <divider/>
56
+ <row wrap="nowrap" align="start" gap="4">
57
+ <icon name="users" size="xl"/>
58
+ <group gap="2">
59
+ <title align="start">Second test heading</title>
60
+ <text align="start">Another test body, aligned with its heading rather than spanning the icon column.</text>
61
+ </group>
62
+ </row>
63
+ </figure>
64
+ ```
49
65
 
50
- ### `text` / `title` / `caption`
66
+ For a native editorial list the same relationship is expressed with `icon-list` containing `entry icon="…" title="…"`, and multiple `text` children per entry. Native paragraph children are lowered to text strings: their nested text size/alignment/layout properties are not carried into the native scene. Use a generic layout with text size controls for such precision; do not assume identical nested styling contracts. Native scenes preserve the app's keyboard/selection/detail/file-preview behavior when rendered by the Garden article host. A standalone static export is a readable fallback, not an identical interactive host.
51
67
 
52
- | 属性 | 说明 |
53
- | :--- | :--- |
54
- | `size` `align` | 共用 |
55
- | `tone` | `text`:`plain` `muted` `accent` `tip`。`caption` 固定 muted。 |
68
+ ## Typography and complete-theme context
56
69
 
57
- ### `icon`
70
+ Default body text inherits the **actual article's** family, size and line height. There is no universal pixel baseline. This includes ordinary static text, list bodies and native readable prose; changing the article typography configuration must propagate. Semantic headings, graph labels, values, captions and controls intentionally retain their hierarchy.
58
71
 
59
- | 属性 | 说明 |
72
+ | Element/context | Actual source rule / intentional variation |
60
73
  | :--- | :--- |
61
- | `name` | 必填;须在 [图标目录](/garden/reference/compose-icons) |
62
- | `size` | `sm` `md` `lg` `xl` |
63
- | `inline` | 与文字同行 |
74
+ | Static `text` and `title` | Inherit body size; title weight 600, line height 1.4. `size="sm"` .875em; `lg` 1.125em; `xl` 1.25em. `md` keeps the baseline. |
75
+ | Static outer figure title/caption | Source defaults 18px/14px, not ordinary body; actual cascade still matters. |
76
+ | Static inline caption | Own semantic style; `sm` 11px, `lg` 16px. Not a body substitute. |
77
+ | Native icon-list entry title/body | Title weight 600; body inherits article. Group heading uses `--fs-small`. |
78
+ | Native choice value | 22px; narrow rule 20px. Option body inherits article. |
79
+ | Native relation ring | Compact/context-dependent labels and line clamps; detail prose inherits article. Do not treat a ring label as a long paragraph. |
80
+ | Play components | Query schema defaults and complete theme. Their controls/KPI/graph semantics are not globally changed to body size. |
64
81
 
65
- ## 标签目录
82
+ Use explicit variation only for a meaningful hierarchy. Never shrink body text globally to fit a screenshot or discard facts to avoid wrapping. Inspect actual computed styles with globals → tokens → article theme → shell in the real order, on desktop and narrow widths; base component CSS alone does not prove the final result.
66
83
 
67
- 每组一个迷你样例,下面一张一句话表;不写长文。
84
+ ## Markdown, safe HTML, and execution
68
85
 
69
- ### 布局
70
-
71
- ```garden compose
72
- <row gap={2}><box padding={2} radius="md" border="subtle"><title size="sm">甲</title></box><box padding={2} radius="md" background="surface-accent"><title size="sm">乙</title></box></row>
73
- ```
86
+ `text`, `title` and captions are inline contexts: `**bold**`, `_emphasis_`, backticks, `[links](https://example.com)`, `~~strike~~` and safe inline HTML such as `<u>underline</u>`. `<u>` is HTML, not standard Markdown.
74
87
 
75
- | 标签 | 用途 |
76
- | :--- | :--- |
77
- | `box` | 通用容器;可设 padding / gap / background / radius |
78
- | `card` | box 的卡面别名 |
79
- | `stack` | 竖排 |
80
- | `row` | 横排 |
81
- | `columns` | 多列横排(默认可换行) |
82
- | `grid` | 等分网格;cols 1–6 |
83
- | `grid-item` | 网格格;span 跨列 |
84
- | `group` | 语义分组容器 |
85
- | `field` | 表单项分组 |
86
- | `header` | 页眉区 |
87
- | `footer` | 页脚区 |
88
- | `figure` | 图示区 |
89
- | `prose` | 长文段落区 |
90
- | `divider` | 分隔线(自闭合) |
91
- | `separator` | divider 别名 |
92
- | `spacer` | 空白间距 |
93
- | `band` | 通栏强调条(box frame=band) |
94
- | `pill` | 胶囊(box frame=pill) |
95
-
96
- ### 文字
88
+ Use `markdown` or `html` islands for full paragraphs, lists, headings, blockquotes, code blocks, tables, images, details/summary and other allowlisted article content. The islands share the article Markdown/GFM and safe-HTML renderer; they are not arbitrary component trees. Static text outside islands is a lightweight layout shorthand, **not** the whole article block grammar. Play islands are literal content, not interpolated expressions. Keep state and expressions in Play component nodes outside them.
97
89
 
98
90
  ```garden compose
99
- <stack gap={1}><title size="sm">标题</title><text size="sm">正文</text><caption size="sm">说明</caption><badge>徽标</badge></stack>
100
- ```
91
+ <figure frame="none">
92
+ <markdown>
93
+ ### Explicit test content
101
94
 
102
- | 标签 | 用途 |
103
- | :--- | :--- |
104
- | `title` | 短标题 |
105
- | `text` | 正文 |
106
- | `caption` | 次要说明(默认 muted) |
107
- | `label` | 控件标签 |
108
- | `badge` | 胶囊徽标 |
109
- | `kpi` | 指标数字(自闭合) |
110
- | `stat` | kpi 别名 |
111
- | `icon` | 具名描边图标(自闭合) |
112
- | `callout` | 提示条 |
113
- | `kbd` | 键盘键帽 |
114
- | `link` | 行内链接 |
115
- | `intent` | 作者原话(不绘制) |
116
-
117
- ### 控件
95
+ **Bold**, _emphasis_, `code`, [link](https://example.com), ~~strike~~ and <u>underline</u>.
118
96
 
119
- ```garden compose
120
- <stack gap={2}><row gap={2}><avatar label="甲" size="sm"/><badge>好</badge><kbd>⌘K</kbd></row><list><list-item>一项</list-item><list-item>二项</list-item></list><progress value={40} max={100} label="40%"/></stack>
97
+ - A full Markdown list
98
+ - Another test item
99
+
100
+ <details><summary>Safe HTML details</summary><p>Useful article HTML can coexist with Markdown.</p></details>
101
+ </markdown>
102
+ </figure>
121
103
  ```
122
104
 
123
- | 标签 | 用途 |
124
- | :--- | :--- |
125
- | `button` | 按钮快照 |
126
- | `slider` | 滑杆快照 / play 可调 |
127
- | `progress` | 进度条 |
128
- | `meter` | 计量条 |
129
- | `checkbox` | 复选框快照 |
130
- | `radio` | 单选快照 |
131
- | `toggle` | 开关快照 |
132
- | `switch` | toggle 别名 |
133
- | `input` | 单行输入快照 |
134
- | `textarea` | 多行输入快照 |
135
- | `select` | 下拉快照 |
136
- | `tabs` | 选项卡容器 |
137
- | `tab` | 单个选项卡 |
138
- | `list` | 列表 |
139
- | `list-item` | 列表项 |
140
- | `table` | 表格 |
141
- | `thead` | 表头 |
142
- | `tbody` | 表体 |
143
- | `tr` | 表行 |
144
- | `th` | 表头格 |
145
- | `td` | 表数据格 |
146
- | `image` | 图片 |
147
- | `avatar` | 头像占位 |
148
- | `empty` | 空状态 |
149
- | `option` | 分段选项快照 |
150
-
151
- ### 连接糖
105
+ Safe HTML supports allowlisted local `style` properties, including useful layout and typography; inspect the generated schema for the actual set. Unsupported tags/properties, events, unsafe URLs, executable scripts and network CSS functions report diagnostics. Do not expand the article allowlist into arbitrary execution. An intentional executable demo uses `sandbox` inside the **same Compose entry**, with literal html/css/js and no parent origin access. Sandbox layout is its own document, not inherited article prose.
152
106
 
153
- ```garden compose
154
- <stack align="center" gap={1}><pill>起点</pill><arrow dir="down"/><band tone="accent" align="center"><title size="sm">枢纽</title></band></stack>
155
- ```
107
+ ## Verification levels
156
108
 
157
- | 标签 | 用途 |
158
- | :--- | :--- |
159
- | `arrow` | 箭头 |
160
- | `fan` | 向下分叉箭头 |
161
- | `join` | V 形汇合 |
162
- | `lanes` | 泳道图 |
163
- | `actor` | 泳道角色 |
164
- | `message` | 泳道消息 |
165
- | `steps` | 分步容器 |
166
- | `step` | 一步 |
167
- | `note` | 步骤展开说明 |
168
- | `compare` | 对照卡组 |
169
- | `item` | 对照项 |
170
- | `code` | 代码快照 |
171
- | `pre` | 预格式文本 |
172
-
173
-
174
- ## 图表示例
175
-
176
- 玩法级图表示例(静态八柱、融合权重滑杆)见 [说明图 · compose](/garden/components/compose#ui-compose-chart-active-hours)。
177
-
178
- ## 限制
179
-
180
- - 嵌套约 10 层 / 约 220 节点。
181
- - 只有白话、没有标签时报 `compose-uncompiled`。
182
- - Play(`{@body}`、`{#if}` …)见仓库 `docs/compose-dil.md`;静态围栏里的控件标签画成默认态快照。
109
+ 1. Run `npx garden ui check <file>` (and `npx garden check <file>` for real file paths). Preserve original text/resources and inspect diagnostics.
110
+ 2. Parse/render the actual scene; confirm accepted properties survive normalization and meaningful content appears.
111
+ 3. Inspect the complete-theme render: icon rail fixed, heading and **all** paragraphs share the same right edge/left edge, no centered headings or full-width body beneath a detached icon row, dividers outside rows, no unintended cards/arrows, no horizontal overflow.
112
+ 4. Check desktop and narrow screenshots plus geometry/computed styles; exercise choices, relations, file previews, state updates and sandbox behavior when used.
113
+ 5. A hand-authored passing scene proves engine capability, not that an independent model reliably produces it from a short prompt. Report those claims separately.
@@ -1,29 +1,13 @@
1
1
  ---
2
2
  title: 组件参考
3
- navTitle: 总览
4
- description: garden 围栏组件的字段、默认值、取值限制和报错代码。
3
+ navTitle: 组件参考
4
+ description: 组件参考
5
5
  section: reference
6
6
  order: 0
7
7
  ---
8
8
 
9
- 每页左边是代码,右边是同一段代码渲染出的真实效果;窄屏下用「效果 / 代码」切换。用法和什么时候用,见各组件的用法页。
9
+ 文章布局、富文本、语义场景与交互说明统一使用一个 `garden compose` 围栏。在入口内部选择并组合组件;普通 Markdown 已能表达清楚时不用增加组件。
10
10
 
11
- 链接卡片、来源胶囊和本地图片没有字段页,用法在 [组件总览](/garden/components)。
12
-
13
- 所有组件通用:YAML 语法错误,或顶层出现不支持的键名,整块报 `garden-yaml`;围栏名写错报 `garden-name`。
14
-
15
- | 组件 | 用途 |
16
- | :--- | :--- |
17
- | [`card`](/garden/reference/card) | 介绍一篇论文、一个项目或一组值得参考的公开工具。 |
18
- | [`stat`](/garden/reference/stat) | 把 2~4 个关键数字、单位与一句说明并排摆出来。 |
19
- | [`compare`](/garden/reference/compare) | 把两三种方案左右并列,或把不好的做法与更好的做法上下对照。 |
20
- | [`timeline`](/garden/reference/timeline) | 按时间或阶段顺序排开版本演进、排查经过或关键节点。 |
21
- | [`chart`](/garden/reference/chart) | 把一组算好的数字画成比例条形图,下方自带可展开的数据表。 |
22
- | [`compose`](/garden/reference/compose) | 用卡片、箭头和注释画一张说明图;标签全表与共用 token。 |
23
- | [`compose 图标`](/garden/reference/compose-icons) | 全部具名描边图标:字形 + 名字,按 A–Z 可扫。 |
24
- | [`html`](/garden/reference/html) | 在沙盒中运行一段独立的网页小工具、画布动画或演示。 |
25
- | [`interactive`](/garden/reference/interactive) | 让读者拖动滑杆或切换选项,实时看到公式和图表的计算结果。 |
26
- | [`file`](/garden/reference/file) | 给读者提供一份或一组可下载的文件,支持在当前页展开预览。 |
27
- | [`relations`](/garden/reference/relations) | 把三到六个要素排成环或中心辐射结构,画出谁影响谁、哪些是双向的。 |
28
- | [`list`](/garden/reference/list) | 用线条图标配短句列出几条并列动作,或带小标题列出分步做法。 |
29
- | [`choice`](/garden/reference/choice) | 给出两三个具体选项卡片,读者点选后看到对应的回应。 |
11
+ - [Compose](/garden/components/compose)
12
+ - [Compose reference](/garden/reference/compose)
13
+ - [Icons](/garden/reference/compose-icons)
@@ -93,7 +93,7 @@ make check
93
93
 
94
94
  ## 5. 编辑器插件
95
95
 
96
- 写交互组件时,可以在 VS Code、Cursor 或 Typora 里插入想法、预览组件、打开清单,再把编译交给 `garden-ui` skill。插件随 `hd-garden` 发布,不用自己编译。
96
+ 写交互组件时,可以在 VS Code、Cursor 或 Typora 里插入想法、预览组件、打开清单,再把编译交给 `garden-compose` skill。插件随 `hd-garden` 发布,不用自己编译。
97
97
 
98
98
  `npx hd-garden init` 会把产物放到 `.garden/editors/`。终端可交互时分别询问是否安装 VS Code / Cursor 和 Typora。第一次 `npx garden sync` 如果还没问过,会再问一次。没有 TTY、`CI=1` 或 `GARDEN_SKIP_EDITORS=1` 时只打印提示。之后运行:
99
99
 
@@ -41,22 +41,17 @@ order: 40
41
41
  | `missing-title` / `missing-description` | 错误 | Front Matter 缺少有效的 `title` 或 `description` |
42
42
  | `unexpected-slug` | 错误 | Front Matter 中手写了 `slug` 字段(文件名即标识,删掉 `slug`) |
43
43
  | `date-format` | 错误 | `date` 不是合法的 `YYYY-MM-DD`、`YYYY-MM-DD HH:mm:ss` 或带时区的 ISO 时间 |
44
- | `missing-cover` / `missing-asset` | 错误 | `cover` 封面图、正文图片或 `garden file` 引用的本地文件不存在 |
44
+ | `missing-cover` / `missing-asset` | 错误 | `cover` 封面图、正文图片或 Compose `file` 引用的本地文件不存在 |
45
45
  | `heading-h1` / `heading-skip` | 错误 | 正文使用了 `#` 一级标题,或标题层级跳级(例如从 `##` 直接跳到 `####`) |
46
46
  | `reference-heading` | 错误 | 正文写了 `## 参考` 或 `## 参考资料` 标题(应改放到 Front Matter 的 `references` 列表) |
47
47
  | `callout-type` | 错误 | `> [!TYPE]` 使用了不支持的提示框类型 |
48
48
  | `title-split` | 警告 | 标题包含 `丨` 分隔符,但分隔符左边或右边为空(应写成「主题丨副题」) |
49
49
  | `diff-orphan` | 错误 | `diff` 代码块前面没有紧挨着的完整代码块 |
50
- | `legacy-fence` | 错误 | 使用了旧版围栏名(如 `garden:stat`、`widget`、`embed`、`html garden`),需改为 `garden <name>` |
51
- | `garden-idea` | 错误 | 非草稿文章里还有未编译的空白 `garden` 想法块 |
52
50
  | `compose-uncompiled` | 错误 | 非草稿里的 `garden compose` 还是白话,没有编译成标记 |
53
51
  | `compose-invalid` | 错误 | `garden compose` 的标记不合法:未知标签、没闭合,或写成了 YAML 槽 |
54
- | `garden-name` | 错误 | 未知的 `garden` 组件名(支持 `card`、`stat`、`compare`、`timeline`、`chart`、`compose`、`html`、`interactive`、`file`、`relations`、`list`、`choice`) |
55
- | `garden-yaml` | 错误 | `garden` 围栏内 YAML 语法错误、顶层不是键值/列表,或包含该组件不支持的键名 |
56
- | `garden-relations` | 错误 | `garden relations` 的要素数量不在 3~6 个之间,或 `links` 配置不合法(要素更多或有分支改用 `mermaid` 流程图,只走一遍的步骤用 `garden list`) |
57
- | `garden-file` / `file-outside` | 错误 | `garden file` 手写了 `resolved`、缺少有效的 `src` / `files`,或本地路径越出了 `content/` 目录 |
58
- | `file-large` | 警告 | `garden file` 引用的单个本地文件体积超过 `5 MB` |
59
- | `compare-long` | 错误 | `garden compare` 并排模式下单个对比格的正文超过约 60 字(带 `verdict` 的上下对照不受此限) |
52
+ | `garden-name` | 错误 | 作者组件围栏统一使用 `garden compose`。 |
53
+ | `compose-file` / `file-outside` | 错误 | Compose `file` 手写了 `resolved`、缺少有效的 `src` / `files`,或本地路径越出了 `content/` 目录 |
54
+ | `file-large` | 警告 | Compose `file` 引用的单个本地文件体积超过 `5 MB` |
60
55
  | `interactive-trivial` / `steps-prose` | 错误 | `garden compose` 只有一次简单乘法,或步骤只是散文而没有状态变化 |
61
56
 
62
57
  ## 3. Git 提交前钩子与组件画廊
@@ -77,15 +72,14 @@ Garden 通过以下三种方式提供组件模板与智能辅助:
77
72
  1. **新建文章自动附带速查表**:运行 `make new SLUG=xxx TITLE="..."` 创建文章时,生成的 `.md` 文件底部会自动带有一段 `<!-- 组件速查 ... -->` HTML 注释,列出想法块和各个组件的示例写法,复制需要的那块即可。这段注释不会显示在页面上,写完可以删掉。
78
73
  2. **代码片段模板文件**:`hd-garden` 包内的 `templates/` 目录自带两份模板文件:
79
74
  - `templates/garden-blocks.md`:想法块和内置组件的可复制 Markdown 模板。
80
- - `templates/garden-snippets.plist`:macOS 系统文本替换词条(可拖入「系统设置 → 键盘 → 文本替换」),触发词是 `;gidea`(也可以输入 `;garden想法`)、`;gcard`、`;gstat`、`;gcompare`、`;gtimeline`、`;gchart`、`;gcompose`、`;ghtml`、`;ginteractive`、`;gfile`、`;grel`、`;glist`、`;gchoice`。`;gcompose` 展开成带一句白话的 `garden compose`;其余展开成对应围栏。
81
- 3. **安装 AI Agent 技能(`npx garden skill`)**:在站点目录运行 `npx garden skill`(`npx hd-garden init` 时也会自动执行),会把三个技能复制到站点根目录下的 `.agents/skills/`:
82
- - `garden-ui`:把文章里的 `garden` 想法描述编译成具体的组件围栏。
83
- - `garden-interactive-chart`:根据文章数据编写 `interactive`、`chart`、`compose` 与 `html` 组件。
75
+ - `templates/garden-snippets.plist`: one Compose author entry; choose components inside the scene.
76
+ 3. **安装 AI Agent 技能(`npx garden skill`)**:在站点目录运行 `npx garden skill`(`npx hd-garden init` 时也会自动执行),会把两个技能复制到站点根目录下的 `.agents/skills/`:
77
+ - `garden-compose`:把文章里的 Compose 意图编译成同一入口内的布局、内容与交互。
84
78
  - `garden-post-review`:按排版与组件规范审阅整篇文章。
85
79
 
86
80
  ## 5. VS Code、Cursor 与 Typora 插件
87
81
 
88
- Intelligent UI 插件是写交互组件的编辑器入口:插入一句想法、在编辑器里预览、打开组件清单,再把编译交给 `garden-ui` skill。插件随 `hd-garden` 发布,站点不用从 `editors/vscode` 或 `editors/typora` 源码编译。
82
+ Intelligent UI 插件是写交互组件的编辑器入口:插入一句想法、在编辑器里预览、打开组件清单,再把编译交给 `garden-compose` skill。插件随 `hd-garden` 发布,站点不用从 `editors/vscode` 或 `editors/typora` 源码编译。
89
83
 
90
84
  ### 安装
91
85
 
@@ -110,7 +104,7 @@ Obsidian 插件这一轮不随包安装。
110
104
 
111
105
  ### 在编辑器里怎么用
112
106
 
113
- 1. **插入想法。** VS Code / Cursor:macOS 用 `Cmd+Alt+I`,Windows / Linux 用 `Ctrl+Alt+I`,或命令「插入 Garden 块」。Typora:输入 `/` 后选 `/garden`(下一层列表每一项有一张小预览图),或命令「插入 Garden 块」直接打开组件列表(Windows / Linux 默认 `Ctrl+Alt+I`,macOS 请到「设置 → 快捷键」里自己录,因为 Option 会改写按键)。插入的是不带组件名的 `garden` 围栏,正文说明要写成哪种组件、写上哪些事实,交给 `garden-ui` skill 编译。
107
+ 1. **插入想法。** VS Code / Cursor:macOS 用 `Cmd+Alt+I`,Windows / Linux 用 `Ctrl+Alt+I`,或命令「插入 Garden 块」。Typora:输入 `/` 后选 `/garden`(下一层列表每一项有一张小预览图),或命令「插入 Garden 块」直接打开组件列表(Windows / Linux 默认 `Ctrl+Alt+I`,macOS 请到「设置 → 快捷键」里自己录,因为 Option 会改写按键)。插入的是不带组件名的 `garden` 围栏,正文说明要写成哪种组件、写上哪些事实,交给 `garden-compose` skill 编译。
114
108
  2. **预览。** 打开 Markdown 预览(Typora 里光标离开围栏即可)。`ui` 块画成和博客一样的组件,`intent` 块显示成想法卡片。点滑杆、按钮不会跳回源码。
115
109
  3. **看组件清单。** VS Code / Cursor 里用「查看组件清单」,点「用它开始」把配方插进当前稿件。终端里的同一份清单:
116
110
 
@@ -119,4 +113,14 @@ Obsidian 插件这一轮不随包安装。
119
113
  ```
120
114
 
121
115
  生成 `.garden/ui-catalog.html`。
122
- 4. **交给 skill 编译。** 「复制编译提示词」在中文站点得到 `编译这篇:<相对路径>`,在 `locale: en_US` 的站点得到 `Compile this post: <相对路径>`。把这句话发给装了 `garden-ui` skill 的 Agent。它会运行 `npx garden ui scan`,阅读 `npx garden ui prompt`,再用 `npx garden ui apply` 只替换这一块。插件本身不调用模型。写完用 `npx garden ui check` 或提交前钩子再查一遍。
116
+ 4. **交给 skill 编译。** 「复制编译提示词」在中文站点得到 `编译这篇:<相对路径>`,在 `locale: en_US` 的站点得到 `Compile this post: <相对路径>`。把这句话发给装了 `garden-compose` skill 的 Agent。它会运行 `npx garden ui scan`,阅读 `npx garden ui prompt`,再用 `npx garden ui apply` 只替换这一块。插件本身不调用模型。写完用 `npx garden ui check` 或提交前钩子再查一遍。
117
+
118
+
119
+ ## 本地严格检查
120
+
121
+ 运行 `make check`:检查工作区所有文章的结构和全部 Compose/UI 块,包含草稿与未跟踪的新稿,不必先暂存。结构错误不会阻止 Compose 检查;有待编译/错误块时显示诊断和调用项目 `garden-compose` skill 的短指令,默认不生成提示词文件。不会调用 AI 或复制剪贴板。
122
+
123
+ `make check FILE=content/posts/文章.md` 只限制内容预检范围;通过后仍执行原来的全站 sync/build(引擎仓库保留 lint/test)。预检失败返回非零并跳过后续阶段。这是编译/校验,不是自动格式化或自动改稿。
124
+
125
+
126
+ `make check diff` 只检查 `content/` 下相对 HEAD 有改动的 Markdown(含已暂存、未暂存)和未跟踪新稿,读取工作区当前内容,去重、取重命名后的路径、跳过已删除文件。不会继续运行全站 sync/build/lint/tests,`make -j check diff` 也只执行一次改动检查。没有改动则成功退出;不在 Git 仓库或没有 HEAD 时明确报错,不回退全量。底层命令是 `garden verify --diff`。diff 模式优先于 FILE;不带 diff 的 `make check` 不变。
@@ -62,12 +62,12 @@ func openStore(path string) (*Store, error) {
62
62
  }
63
63
  ```
64
64
 
65
- ```garden
65
+ ```garden compose
66
66
  和上一版比:打开存储时的模式从 ModeJournal 改成了 ModeWAL。
67
67
  ```
68
68
  ````
69
69
 
70
- Agent 按 `garden-ui` skill 会通过 `npx garden ui apply` 把这段想法替换成紧挨着完整代码的 `diff` 围栏(详见 [用 AI 写作](/garden/ai-writing))。页面渲染时会把这两段合成一个可切换 **「代码」** 和 **「对比上一版」** 的代码框,右上角的复制按钮始终复制新版完整代码:
70
+ Agent 按 `garden-compose` skill 会通过 `npx garden ui apply` 把这段想法替换成紧挨着完整代码的 `diff` 围栏(详见 [用 AI 写作](/garden/ai-writing))。页面渲染时会把这两段合成一个可切换 **「代码」** 和 **「对比上一版」** 的代码框,右上角的复制按钮始终复制新版完整代码:
71
71
 
72
72
  ```go
73
73
  func openStore(path string) (*Store, error) {