104 lines
5.4 KiB
Markdown
104 lines
5.4 KiB
Markdown
# 组件使用政策（reacticle 协议）
|
||
|
||
文章用 `reacticle` 组件协议写：**不手写裸 `div` / `className` / 行内 `style` / CSS**。
|
||
结构走语义组件，正文走段落，自定义视觉走 `Raw`。从包入口导入：
|
||
|
||
```tsx
|
||
import { ThemeProvider, Article, Hero, Lead, Section, Aside, Table, Raw } from "reacticle";
|
||
```
|
||
|
||
## 核心规则（始终适用）
|
||
|
||
1. **Prose-first，组件按需，Raw 自由。**
|
||
- **正文是主体**：普通段落写成 `Section` 的 children，应占文章绝大部分。
|
||
- **语义组件是点睛，只在内容确实"是"那个结构时才用**：`Summary` / `Aside` /
|
||
`Quote` / `Table` / `RiskList` / `Decision` 等。不要堆叠当装饰 —— 堆卡片会让
|
||
文章显得做作、零碎。litmus test：若一句话 / 一个列表 / 一张表 / 一块 Raw 读起来
|
||
更好，就用那个。
|
||
- **Raw 相反：鼓励多用。** 交互、动画、自定义可视化、新颖排版 —— Markdown 做不到的
|
||
东西，才是把文章从"能读"变成"值得读"的关键。Raw 不打断阅读，它给密集文本节奏与
|
||
呼吸。
|
||
2. **表达语义，不表达布局。** 说"这是 insight / risk / decision"，别说"蓝卡片、24px 边距"。
|
||
3. **Props 即协议。** 填齐必填字段；确实没有就留空 —— 组件会渲染显式的 `⚠ 未指定xxx`
|
||
标记，让缺口可见。**绝不为掩盖缺口而编造。**
|
||
4. **主题，不写样式。** 作者只通过 `ThemeProvider` 选一个主题，从不写组件样式。
|
||
5. **始终用 `<ThemeProvider theme="...">` 包住 `<Article>`。**
|
||
6. **版式与主题解耦。** `Article` 的 `width`（`narrow` / `regular` / `wide` / `full`，默认
|
||
`regular`）决定阅读列宽，`toc`（默认在本 Skill 开启）决定是否有左侧目录 —— 都按内容选、
|
||
经 Plan Checkpoint 确认，**不由主题决定**。详见 `references/layout.md`。
|
||
7. **一个 Section = 一个文件。** 每个 Section 必须是独立组件（`article/sections/NN-*.tsx`），
|
||
**坚决不允许**把多个 Section 写进一个组件；`Article.tsx` 只做组装（assembler）。这是
|
||
多 Agent 并行开发的前提，详见 `references/section-build.md`。
|
||
|
||
## 组件分两层：默认核心 + 领域特例
|
||
|
||
**默认核心组件（绝大多数文章只用这些 + 正文 + Raw）：**
|
||
|
||
- 结构：`Article`、`Hero`、`Lead`、`Section`、`Subsection`、`Conclusion`、`TOC`
|
||
- 观点：`Summary`、`Aside`、`Quote`
|
||
- 数据：`Table`
|
||
- 技术：`CodeBlock`（写代码**只用它**）、`Formula`
|
||
- 媒体：`Image`
|
||
- 自由层：`Raw`
|
||
|
||
**领域特例组件（仅当内容"确实是"该结构时按需取用，不要因为属于某类文章就全用上）：**
|
||
|
||
- 决策 / 审阅：`RiskList`、`Decision`、`ActionList`、`Checkpoint`、`Tradeoff`、`Incident`
|
||
- 代码评审：`DiffReview`
|
||
- 交互壳：`Detail`、`Tabs`
|
||
- 富媒体：`Video`、`Audio`
|
||
|
||
> **不要暴露给作者**：`HighlightedCode` 是 `CodeBlock` 的内部底层，写代码一律用
|
||
> `CodeBlock`，不直接使用 `HighlightedCode`。
|
||
|
||
选组件前先过 litmus test（规则 1）：若正文 / 列表 / 表格 / Raw 读起来更好，就不要为了
|
||
用组件而用组件。领域特例组件每多用一个，都要能回答"这块内容本质上就是它"。
|
||
|
||
完整组件 API（属性、用法）见组件库本身的 reference：
|
||
`skill/references/{structure,insight,structured,decision,technical}.md`（reacticle-authoring
|
||
skill），按需读取，不要一次全读。
|
||
|
||
## 使用原则
|
||
|
||
- 正文是主体。组件是语义，不是装饰。
|
||
- Raw 是文章表现力，不是应用开发入口（边界见 `raw-policy.md`）。
|
||
- `Table` 负责二维信息；`Image` 负责真实或生成配图；`Raw` 是自由的 Web 层 —— 任意
|
||
HTML / CSS / JS / React：交互、自定义布局排版、动效、嵌入小工具，以及按需的图解（SVG /
|
||
canvas），SVG 只是其中一种手段，不是默认。
|
||
- **`Raw` 与 `Image` 正交，不是二选一**：`Raw` 始终默认存在、照常使用；`Image` 是否使用、
|
||
用哪种来源由 Plan Checkpoint 的配图策略决定（见 `references/asset-policy.md`）。选配图
|
||
`none` 只表示不用外部图片，`Raw` 不受影响。
|
||
|
||
## 信息密度与组件比例
|
||
|
||
见 `information-density.md`：100% 时长文优先、Raw 点亮关键概念；密度越低，视觉块比例
|
||
越高，但**仍必须保持文章形态**。
|
||
|
||
## 最小骨架（注意比例：大量正文 + 一个点睛组件 + 一块 Raw）
|
||
|
||
```tsx
|
||
import { ThemeProvider, Article, Hero, Lead, Section, Aside, Raw } from "reacticle";
|
||
|
||
export function Article_() {
|
||
return (
|
||
<ThemeProvider theme="tufte">
|
||
<Article>
|
||
<Hero title="标题" subtitle="副标题" meta={[{ label: "日期", value: "2026-06-08" }]} />
|
||
<Lead>导语，框定主题。</Lead>
|
||
<Section index="01" title="第一节">
|
||
<p>正文段落用 children —— 这应是文章主体，尽量多写正文。</p>
|
||
<p>再写一段，把背景、推理、结论用文字讲清楚。</p>
|
||
<Aside tone="principle" label="核心判断">一句话的核心判断。</Aside>
|
||
<Raw title="为本段现写的内联 SVG">
|
||
<svg viewBox="0 0 240 60" width="100%">
|
||
<polyline points="0,50 40,42 80,46 120,20 160,28 200,8 240,14"
|
||
fill="none" stroke="var(--ra-color-accent)" strokeWidth="2" />
|
||
</svg>
|
||
</Raw>
|
||
</Section>
|
||
</Article>
|
||
</ThemeProvider>
|
||
);
|
||
}
|
||
```
|