组件规范

本页定义公开视觉组件、共享文本流层和核心交互规格。整体设计入口见设计导览，所有数值型 Token 见 Token 系统。

职责模型

类型	在本项目中的含义	是否进入组件清单
Block Component	直接承接块级节点或复杂媒体块	是
Mark Capability	承接行内标记的共享规则	否，不为每个 Mark 单独建视觉组件
Inline Node Component	承接复杂度较高的行内 / 嵌入式节点	视复杂度而定
Shell Component	承接状态、容器、全屏壳层等非语法能力	是

共享文本流层

以下能力存在于实现层，但不要求在设计稿中作为独立视觉组件逐个出图。

能力	负责内容	说明
`InlineTextFlow`	文本流拼接、软换行、转义、实体	负责把普通文本组织成稳定文本流
`InlineMarks`	`emphasis`、`strong`、`delete`、`mark`	统一行内标记样式，不拆成独立组件
`HardBreak`	`break`	作为共享文本流层中的换行节点处理，不单独出组件页

LinkRenderer 和 InlineCode 仍保留为独立组件，因为它们具备明确的交互或独立视觉样式，需要单独验收。

组件分组总览

分组	组件	说明
壳层与状态	`DocumentShell`、`LoadingSkeleton`、`StateRenderer`、`FullscreenViewer`	页面容器、状态页和全屏查看器
文本与列表	`HeadingRenderer`、`ParagraphRenderer`、`ListRenderer`、`TaskListRenderer`、`Blockquote`、`HanddrawnDivider`	正文、标题、列表、引用、分隔线
行内与轻交互	`InlineCode`、`LinkRenderer`	行内代码和链接交互
富媒体与扩展块	`CodeBlock`、`ImageRenderer`、`MermaidBlock`、`VideoRenderer`、`TableRenderer`、`HtmlRenderer`	代码、图片、图表、视频、表格、HTML

当前公开视觉组件共 18 个，不含 MarkdownRenderer 与共享文本流层。

壳层与状态

`DocumentShell`

背景使用 --scribdown-color-bg
正文文本列最大宽度 840px
左右内边距最少 48px
页面留白为顶部 64px、底部 96px
浅色主题可加入低噪声纸感纹理和轻量纸张外框；纹理只能作为背景层，不能降低正文、代码、表格的可读性

`LoadingSkeleton`

结构：大标题占位块 → 段落三行组 → 代码块占位 → 段落两行组
骨架色使用 --scribdown-color-border
透明度在 0.4–0.8 脉冲过渡，周期 1.4s
prefers-reduced-motion 开启时取消脉冲

`StateRenderer`

变体	颜色	说明
`Empty`	`--scribdown-color-text-secondary`	无可渲染内容
`Error`	`--scribdown-color-danger`	渲染失败，展示错误摘要
`Unsupported`	`--scribdown-color-warning`	语法或能力不支持

`FullscreenViewer`

结构：Overlay + TopBar + ContentStage
遮罩：rgba(45, 36, 31, 0.72)
顶栏：内容标题（左）+ 类型标签（中）+ 关闭按钮（右）
内容区四周安全留白至少 32px
承载图片、Mermaid、视频时共用同一壳层

文本与列表

`HeadingRenderer`

字体统一使用 --scribdown-font-heading
字号、行高、字重严格对应 Typography 规范
标题悬停时左侧出现低调 # 锚点图标
锚点入口使用 absolute 定位，不影响标题文本对齐
h2 可使用短横线涂抹感底线强化章节分隔；底线颜色来自 --scribdown-color-border 或 --scribdown-color-accent 的低透明度派生值

`ParagraphRenderer`

使用 body-md（18px / 1.75）
段间距 --scribdown-space-5
行内 emphasis、strong、delete、mark、break 由共享文本流层处理

`ListRenderer`

有序与无序列表都支持三级嵌套
无序标记使用手绘圆点或短横，不使用标准浏览器 bullet
每级缩进 24px
ListItem 行间距 8px

`TaskListRenderer`

继承 ListRenderer 的缩进、间距与嵌套规则
Marker 替换为手绘感方形复选框（16px）
已完成项使用 delete 样式并降为 --scribdown-color-text-secondary

`Blockquote`

左侧强调线宽 4px
颜色使用 --scribdown-color-accent
内边距 16px 20px
背景使用 --scribdown-color-surface
可加入手绘引用符号作为弱装饰，装饰颜色必须低于正文权重

`HanddrawnDivider`

不使用标准 <hr> 直线
颜色使用 --scribdown-color-border
上下留白 --scribdown-space-5

行内与轻交互

`InlineCode`

内边距 2px 6px
字体使用 --scribdown-font-code
背景比正文背景深一层
字号使用 inline-code

`LinkRenderer`

默认颜色 --scribdown-color-accent
区分 default / hover / visited / focus-visible 四态
focus-visible 使用 2px 实线轮廓，偏移 2px
visited 颜色略深于默认态

富媒体与扩展块

`CodeBlock`

结构：Header + ScrollArea
Header 高度 40px，内边距 12px 16px
复制按钮区分 default / hover / focus-visible / copied 四态
长代码行保留横向滚动，不折行
外观使用 --scribdown-radius-md 与 --scribdown-shadow-md
行号、语法高亮与行高亮需要同时可辨；行高亮使用浅色底，不使用高饱和整行色块

`ImageRenderer`

默认宽度 100%，最大展示宽度 720px
需要同时支持加载态、正常态、失败态
失败态展示固定高占位与 alt 文本
右上角提供低存在感媒体操作入口，至少覆盖全屏查看
caption 位于图片下方并居中，使用 body-sm 与 --scribdown-color-text-secondary

`MermaidBlock`

结构：Header + DiagramCanvas
DiagramCanvas 最小高度 240px
失败态展示错误摘要与源码入口
全屏入口含 focus-visible 态
正常态节点可使用柔和色块和手绘描边，箭头保持清晰方向；失败态使用语义色轻描边提示，避免呈现为原始报错堆栈

`VideoRenderer`

默认 16:9 比例容器，最大宽 720px
未播放态展示封面与居中播放按钮
播放按钮 focus-visible 轮廓偏移 3px
全屏入口位置与 ImageRenderer 保持一致
播放控件可近似真实播放器的时间轴、音量和全屏入口布局，但视觉权重必须低于视频内容

`TableRenderer`

结构：TableWrapper + TableHead + TableBody
TableWrapper 必须支持横向滚动
表头通过字重、底色或描边形成层级差异
单元格内边距 12px 16px

`HtmlRenderer`

块级与行内 HTML 共用 rehype-sanitize + DOMPurify 安全链路
白名单标签输出等效视觉效果，样式继承正文 Token
非白名单内容显示占位框，不暴露原始标签

`focus-visible` 规格

元素	轮廓规格
`LinkRenderer`	`2px` 实线，颜色 `--scribdown-color-accent`，偏移 `2px`
`CodeBlock` 复制按钮	`2px` 实线，颜色 `--scribdown-color-accent`，偏移 `2px`
`ImageRenderer` 全屏入口	`2px` 实线，颜色 `--scribdown-color-accent`，偏移 `2px`
`MermaidBlock` 全屏入口	`2px` 实线，颜色 `--scribdown-color-accent`，偏移 `2px`
`VideoRenderer` 播放按钮	`2px` 实线，颜色 `--scribdown-color-accent`，偏移 `3px`
`FullscreenViewer` 关闭按钮	`2px` 实线，颜色 `--scribdown-color-text-primary`，偏移 `2px`
标题锚点入口	`2px` 实线，颜色 `--scribdown-color-accent`，偏移 `2px`