Storybook 文档风格规范docs-review Skill 的 storybook-style.md 规则与自动校验实现全解【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文深入讲解 Storybook 仓库中docs-reviewAgent Skill 的核心参考文件 storybook-style.md。该文件定义了 Storybook 官方文档/docs目录下的 MDX 页面的编辑语气、标题、链接、MDX 自定义组件、frontmatter 与块级 JSX 排版规则。读完后你将掌握这套文档风格规范的每一条规则与正反示例并能理解规则中标注[auto]的检查项是如何被 check-docs.ts 逐条实现、通过yarn docs:check自动校验的。这套风格指南在整个 Skill 体系中的位置storybook-style.md是 SKILL.md 定义的docs-review文档审查技能下的四个参考文件之一它拥有ownsStorybook 特有的编辑、MDX 组件、frontmatter 与校验规则但不拥有文档类型识别、模式路由或干预逻辑——那些属于 docs-strategy.md。按 SKILL.md 的加载表参考文件负责内容加载时机docs-principles.md北极星目标、质量维度、双读者要求总是最先读取docs-strategy.md模式、文档类型、干预阈值、页面形态指导总是第二读取docs-antipatterns.md诊断模式与纠正手段诊断薄弱或混乱草稿时storybook-style.md编辑、MDX 组件、frontmatter、格式、校验规则maintenance模式或各编辑模式的最后收尾所有权规则Ownership Rules明确划界策略类参考文件不拥有格式或组件规则storybook-style.md不拥有文档类型或干预逻辑SKILL.md本身只拥有工作流与交接。对应地在 SKILL.md 的工作流中第 6 步应用 Storybook 风格永远位于结构性、编辑性工作之后——这一步永远不是第一遍。语气与文风Voice and Tone人称Point of View第二人称you——面向读者的默认形式。第一人称复数we——代表 Storybook 团队发言时使用如 We recommend…或表示我们一起看看如 Lets take a look…。禁用第一人称单数I和以第三人称称呼读者the user。语气Tone专业但口语化——像给同事讲解而非写教科书。鼓励但不夸张——偶尔一句 Thats great! 可以避免过度热情的表达。解决方案导向——强调读者能做什么而非限制。直接且自信——清晰给出建议We recommend…不做不必要的含糊。句式Sentence Structure优先主动语态写 Storybook renders the component而不是 The component is rendered by Storybook。用短而直接的句子做强调和引入。解释复杂关系时允许长句但避免冗长的连缀句run-ons。以目的开头——章节开篇先说清这是什么、为什么重要而不是铺陈背景。指令措辞Instructions分步指令用祈使句Run this command、Add the following、Create a new file。可选或替代方案用建议式措辞You can also…、You might want to…。引入代码示例时用陈述句带上下文To define the args of a single story, use theargsCSF story key:。缩写Contractions自然地使用缩写dont, cant, wont, youll, its, were——它们强化口语化语气。在 callout 警告等需要精确表达的严肃/警示语境中避免缩写。技术术语Technical Terms关键术语首次出现时给出定义之后可自由使用例如先写 Component Story Format (CSF)之后直接用 CSF。链接到相关概念而不是在正文中重复解释。假定读者具备基础 Web 开发知识HTML、CSS、JavaScript、组件不过度解释 fundamentals。所有代码性质的术语使用反引号包裹对应下文行内格式一节。措辞的确定性Hedging表达能力用 can表达可能结果用 may 或 might。表达建议用 should表达硬性要求用 must。描述存在例外的常见模式时用 typically 或 generally。陈述本身直接时不要加缓冲——写 This adds… 而不是 This should add…。选词Word Choice避免弱化语simply、just、easily、obviously——对一位读者简单的事对另一位读者未必如此。powerful、useful、great 要节制使用且仅在确实成立时使用。具体优于模糊——写 renders in under 2 seconds 而不是 renders quickly。引入示例Introducing Examples先交代为什么再展示怎么做——代码块之前给一句简短的上下文。常用句式Heres how you could…、For example, if you…、To do X, use Y:。当代码块紧随其后时引导句以冒号结尾。章节开头Section Openings用 1–2 句总结本章讲什么、为什么重要。快速进入正题把铺垫压到最小。第一句应当能独立成立本身就是一个定义或价值陈述。段落长度Paragraph Length段落保持 2–4 句保证可扫读性。引导段应为 1–2 句。较长的解释用标题、列表或 callout 切分。标题、链接、列表与行内格式标题HeadingsH1 只能来自 frontmatter 的title正文中绝不使用# Heading。[auto]H2/H3 使用句子式大小写sentence case仅首字母和专有名词大写。不得跳级使用标题例如 H2 后直接 H4。[auto]链接Links内部链接指向.mdx文件的相对路径例如text。[auto]外部链接完整 URL必须始终包裹在 Markdown 链接语法中正文中不允许裸 URL。[auto]列表Lists无序列表使用-不要用*或。[oxfmt]行内格式Inline Formatting文件路径、函数名、变量名、组件名、CLI 命令、配置键、类型名一律用反引号。UI 标签和强调用粗体斜体节制使用。自定义 MDX 组件Callout 组件必须指定variantinfo或warning裸写Callout不允许。图标使用有标准化映射——技巧与有用信息variantinfo——实验性/预览功能variantinfo或variantwarningℹ️——补充背景variantinfo——公告需配合title属性variantinfo♿——可访问性无障碍专用variantinfo⚠️——必须配variantwarning不得配variantinfo。[auto]图标本身是可选的若使用必须遵循上述映射。variantpositive是非标准写法应改用variantinfo。[auto]其他组件If renderer{[...]}/If notRenderer{[...]}——按渲染器条件渲染替代已废弃的IfRenderer。CodeSnippets path... /——path必须真实存在于docs/_snippets/目录。[auto]Video src... /——嵌入视频。YouTubeCallout id... title... /——YouTube 嵌入。Frontmatter 规则值不加引号除非值包含需要加引号的特殊字符如、|、:、逗号。[auto]需要加引号时使用单引号。仅当sidebar.title与title不同时才写sidebar.title两者相同则省略。[auto]正例--- title: Component Story Format (CSF) sidebar: title: CSF order: 2 ---反例--- title: ArgTypes sidebar: title: ArgTypes order: 2 ---块级 JSX 元素的换行规则块级 JSX 元素如Callout、details、If遵循三条排版规则元素前后要各空一行——除非前后紧邻的内容是注释此时注释与元素之间不空行。元素内部内容的前后要各空一行——summary是例外details开始标签与summary标签之间不空行。内部内容不缩进——除非内容本身应当缩进如嵌套列表项、代码块内部。正例If renderer{[react]} Other content. Callout variantinfo This is a callout. - This is a list item inside the callout - This is a nested list item inside the callout json { key: value } /Callout More other content. details summaryThis is a summary/summary This is content inside the details element. /details More other content. /If {/* End supported renderers */}反例对比可见元素前后未空行、Callout缺少variant、summary与内容之间未空行、注释前多空了一行等If renderer{[react]} Other content. Callout This is a callout. - This is a list item inside the callout - This is a nested list item inside the callout json { key: value } /Callout More other content. details summaryThis is a summary/summary This is content inside the details element. /details More other content. /If {/* End supported renderers */}校验yarn docs:check与[auto]/[oxfmt]标记的实现文档末尾声明标记[auto]的条目由yarn docs:check检查实现在 check-docs.ts标记[oxfmt]的条目由yarn fmt:write处理。并强调这些是最终阶段的校验工具——应在结构性与编辑性工作完成后再运行而不是第一步。命令链路根目录 package.json 中定义了根级入口docs:check: yarn --cwd scripts docs:check——转发到 scripts 工作区在 scripts/package.json 中docs:check: jiti ./docs/check-docs.ts即通过 jiti 直接执行 TypeScript 校验脚本fmt:check: oxfmt --check .与fmt:write: oxfmt .——由 oxfmt 完成格式归一化包括列表符号等[oxfmt]规则。check-docs.ts的 CLI 入口会以仓库docs/目录为目标运行runAllChecks汇总所有检查发现任何错误即以退出码 1 结束使检查可接入 CI。[auto]标记与代码实现的逐条对应将文档中各[auto]标记与check-docs.ts导出的检查函数对照可以看到规则与实现的一一映射规则来自 storybook-style.md检查函数实现要点H1 仅来自 frontmattertitle正文禁用#checkNoBodyH1仅在content上下文中匹配^#\s代码块内不误报不跳级使用标题checkHeadingHierarchy从 H1frontmatter 标题起跟踪prevLevellevel prevLevel 1即报错同时识别h2等 HTML 标签内部相对链接指向.mdx文件checkRelativeLinks校验目标文件存在并进一步校验#anchor片段能否在目标文件标题 slug 中找到外部链接必须包裹在链接语法中无裸 URLcheckBareUrls跳过 import/export、引用链接定义、表格行、反引号内、JSX 属性值等场景后检测正文裸http(s)://URL无序列表用-[oxfmt]非 auto—由oxfmtyarn fmt:write负责归一化CodeSnippets path... /路径必须存在于docs/_snippets/checkCodeSnippetPaths以docs/_snippets/为基准解析 path缺失即报Missing snippet裸Callout不允许必须带variantcheckCalloutVariant收集可能跨多行的完整开标签缺少variant即报错variantpositive非标准checkCalloutVariantPositive匹配variantpositive并提示改用variantinfo⚠️ 图标不得配variantinfocheckCalloutIconMismatch同行同时出现Callout、⚠️ 与variantinfo即报错frontmatter 值不必要的引号checkFrontmatterQuotes仅当title值不含、|、:、逗号等字符却加了引号时报错与文档特殊字符才引号规则一致与title相同的sidebar.title应省略checkRedundantSidebarTitle解析 frontmatter 中title与sidebar.title去引号后相等即报冗余此外runAllChecks还会执行一个文档正文未直接列出的检查 checkDeprecatedIfRenderer检测到已废弃的IfRenderer用法即提示改用If——这与其他组件一节推荐的If renderer{[...]}写法互为印证。值得注意的源码实现细节从源码结构看有两处细节让校验更健壮跨版本链接豁免checkRelativeLinks中定义了crossVersionRegex /^(?:\.\.\/)release-[\w.-]\//见 check-docs.ts指向其他发布分支如../../../release-8-6/docs/...的跨版本文档链接无法在本地验证会被直接跳过。行上下文感知多个检查依赖 utils.ts 中的getLineContextsgetLineContexts它把每一行标注为frontmatter、codeblock或content因此正文 H1、裸 URL等检查不会误伤代码块与 frontmatter 内的内容而slugifyslugify模拟了 rehype-slug 的标题 slug 行为支撑锚点片段校验。实践流程规则如何落到一次文档编辑上结合 SKILL.md 定义的工作流storybook-style.md的正确使用时机是先完成模式判定maintenance/improve/rewrite/author/strategy、主文档类型判定与草稿诊断这些由 docs-strategy.md 与 docs-principles.md 指导完成结构性与编辑性修改后加载storybook-style.md按本文语气与文风 → 标题/链接/列表/行内格式 → 自定义组件 → frontmatter → 块级 JSX 换行的顺序做风格收尾运行yarn fmt:write与yarn docs:check修复报告中的错误后再跑一次确认。注意不要在strategy模式或没有编辑任何文件时运行校验。这套风格规则文件 自动校验脚本的组合让 Storybook 仓库中docs/下数千个 MDX 页面与docs/_snippets/下的代码片段示例保持统一语感、统一组件用法和可机器验证的链接/格式合规性——写文档或为 Agent 编写文档审查规则时都值得借鉴这一规则即代码的做法。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Storybook 文档风格规范：docs-review Skill 的 storybook-style.md 规则与自动校验实现全解
Storybook 文档风格规范docs-review Skill 的 storybook-style.md 规则与自动校验实现全解【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文深入讲解 Storybook 仓库中docs-reviewAgent Skill 的核心参考文件 storybook-style.md。该文件定义了 Storybook 官方文档/docs目录下的 MDX 页面的编辑语气、标题、链接、MDX 自定义组件、frontmatter 与块级 JSX 排版规则。读完后你将掌握这套文档风格规范的每一条规则与正反示例并能理解规则中标注[auto]的检查项是如何被 check-docs.ts 逐条实现、通过yarn docs:check自动校验的。这套风格指南在整个 Skill 体系中的位置storybook-style.md是 SKILL.md 定义的docs-review文档审查技能下的四个参考文件之一它拥有ownsStorybook 特有的编辑、MDX 组件、frontmatter 与校验规则但不拥有文档类型识别、模式路由或干预逻辑——那些属于 docs-strategy.md。按 SKILL.md 的加载表参考文件负责内容加载时机docs-principles.md北极星目标、质量维度、双读者要求总是最先读取docs-strategy.md模式、文档类型、干预阈值、页面形态指导总是第二读取docs-antipatterns.md诊断模式与纠正手段诊断薄弱或混乱草稿时storybook-style.md编辑、MDX 组件、frontmatter、格式、校验规则maintenance模式或各编辑模式的最后收尾所有权规则Ownership Rules明确划界策略类参考文件不拥有格式或组件规则storybook-style.md不拥有文档类型或干预逻辑SKILL.md本身只拥有工作流与交接。对应地在 SKILL.md 的工作流中第 6 步应用 Storybook 风格永远位于结构性、编辑性工作之后——这一步永远不是第一遍。语气与文风Voice and Tone人称Point of View第二人称you——面向读者的默认形式。第一人称复数we——代表 Storybook 团队发言时使用如 We recommend…或表示我们一起看看如 Lets take a look…。禁用第一人称单数I和以第三人称称呼读者the user。语气Tone专业但口语化——像给同事讲解而非写教科书。鼓励但不夸张——偶尔一句 Thats great! 可以避免过度热情的表达。解决方案导向——强调读者能做什么而非限制。直接且自信——清晰给出建议We recommend…不做不必要的含糊。句式Sentence Structure优先主动语态写 Storybook renders the component而不是 The component is rendered by Storybook。用短而直接的句子做强调和引入。解释复杂关系时允许长句但避免冗长的连缀句run-ons。以目的开头——章节开篇先说清这是什么、为什么重要而不是铺陈背景。指令措辞Instructions分步指令用祈使句Run this command、Add the following、Create a new file。可选或替代方案用建议式措辞You can also…、You might want to…。引入代码示例时用陈述句带上下文To define the args of a single story, use theargsCSF story key:。缩写Contractions自然地使用缩写dont, cant, wont, youll, its, were——它们强化口语化语气。在 callout 警告等需要精确表达的严肃/警示语境中避免缩写。技术术语Technical Terms关键术语首次出现时给出定义之后可自由使用例如先写 Component Story Format (CSF)之后直接用 CSF。链接到相关概念而不是在正文中重复解释。假定读者具备基础 Web 开发知识HTML、CSS、JavaScript、组件不过度解释 fundamentals。所有代码性质的术语使用反引号包裹对应下文行内格式一节。措辞的确定性Hedging表达能力用 can表达可能结果用 may 或 might。表达建议用 should表达硬性要求用 must。描述存在例外的常见模式时用 typically 或 generally。陈述本身直接时不要加缓冲——写 This adds… 而不是 This should add…。选词Word Choice避免弱化语simply、just、easily、obviously——对一位读者简单的事对另一位读者未必如此。powerful、useful、great 要节制使用且仅在确实成立时使用。具体优于模糊——写 renders in under 2 seconds 而不是 renders quickly。引入示例Introducing Examples先交代为什么再展示怎么做——代码块之前给一句简短的上下文。常用句式Heres how you could…、For example, if you…、To do X, use Y:。当代码块紧随其后时引导句以冒号结尾。章节开头Section Openings用 1–2 句总结本章讲什么、为什么重要。快速进入正题把铺垫压到最小。第一句应当能独立成立本身就是一个定义或价值陈述。段落长度Paragraph Length段落保持 2–4 句保证可扫读性。引导段应为 1–2 句。较长的解释用标题、列表或 callout 切分。标题、链接、列表与行内格式标题HeadingsH1 只能来自 frontmatter 的title正文中绝不使用# Heading。[auto]H2/H3 使用句子式大小写sentence case仅首字母和专有名词大写。不得跳级使用标题例如 H2 后直接 H4。[auto]链接Links内部链接指向.mdx文件的相对路径例如text。[auto]外部链接完整 URL必须始终包裹在 Markdown 链接语法中正文中不允许裸 URL。[auto]列表Lists无序列表使用-不要用*或。[oxfmt]行内格式Inline Formatting文件路径、函数名、变量名、组件名、CLI 命令、配置键、类型名一律用反引号。UI 标签和强调用粗体斜体节制使用。自定义 MDX 组件Callout 组件必须指定variantinfo或warning裸写Callout不允许。图标使用有标准化映射——技巧与有用信息variantinfo——实验性/预览功能variantinfo或variantwarningℹ️——补充背景variantinfo——公告需配合title属性variantinfo♿——可访问性无障碍专用variantinfo⚠️——必须配variantwarning不得配variantinfo。[auto]图标本身是可选的若使用必须遵循上述映射。variantpositive是非标准写法应改用variantinfo。[auto]其他组件If renderer{[...]}/If notRenderer{[...]}——按渲染器条件渲染替代已废弃的IfRenderer。CodeSnippets path... /——path必须真实存在于docs/_snippets/目录。[auto]Video src... /——嵌入视频。YouTubeCallout id... title... /——YouTube 嵌入。Frontmatter 规则值不加引号除非值包含需要加引号的特殊字符如、|、:、逗号。[auto]需要加引号时使用单引号。仅当sidebar.title与title不同时才写sidebar.title两者相同则省略。[auto]正例--- title: Component Story Format (CSF) sidebar: title: CSF order: 2 ---反例--- title: ArgTypes sidebar: title: ArgTypes order: 2 ---块级 JSX 元素的换行规则块级 JSX 元素如Callout、details、If遵循三条排版规则元素前后要各空一行——除非前后紧邻的内容是注释此时注释与元素之间不空行。元素内部内容的前后要各空一行——summary是例外details开始标签与summary标签之间不空行。内部内容不缩进——除非内容本身应当缩进如嵌套列表项、代码块内部。正例If renderer{[react]} Other content. Callout variantinfo This is a callout. - This is a list item inside the callout - This is a nested list item inside the callout json { key: value } /Callout More other content. details summaryThis is a summary/summary This is content inside the details element. /details More other content. /If {/* End supported renderers */}反例对比可见元素前后未空行、Callout缺少variant、summary与内容之间未空行、注释前多空了一行等If renderer{[react]} Other content. Callout This is a callout. - This is a list item inside the callout - This is a nested list item inside the callout json { key: value } /Callout More other content. details summaryThis is a summary/summary This is content inside the details element. /details More other content. /If {/* End supported renderers */}校验yarn docs:check与[auto]/[oxfmt]标记的实现文档末尾声明标记[auto]的条目由yarn docs:check检查实现在 check-docs.ts标记[oxfmt]的条目由yarn fmt:write处理。并强调这些是最终阶段的校验工具——应在结构性与编辑性工作完成后再运行而不是第一步。命令链路根目录 package.json 中定义了根级入口docs:check: yarn --cwd scripts docs:check——转发到 scripts 工作区在 scripts/package.json 中docs:check: jiti ./docs/check-docs.ts即通过 jiti 直接执行 TypeScript 校验脚本fmt:check: oxfmt --check .与fmt:write: oxfmt .——由 oxfmt 完成格式归一化包括列表符号等[oxfmt]规则。check-docs.ts的 CLI 入口会以仓库docs/目录为目标运行runAllChecks汇总所有检查发现任何错误即以退出码 1 结束使检查可接入 CI。[auto]标记与代码实现的逐条对应将文档中各[auto]标记与check-docs.ts导出的检查函数对照可以看到规则与实现的一一映射规则来自 storybook-style.md检查函数实现要点H1 仅来自 frontmattertitle正文禁用#checkNoBodyH1仅在content上下文中匹配^#\s代码块内不误报不跳级使用标题checkHeadingHierarchy从 H1frontmatter 标题起跟踪prevLevellevel prevLevel 1即报错同时识别h2等 HTML 标签内部相对链接指向.mdx文件checkRelativeLinks校验目标文件存在并进一步校验#anchor片段能否在目标文件标题 slug 中找到外部链接必须包裹在链接语法中无裸 URLcheckBareUrls跳过 import/export、引用链接定义、表格行、反引号内、JSX 属性值等场景后检测正文裸http(s)://URL无序列表用-[oxfmt]非 auto—由oxfmtyarn fmt:write负责归一化CodeSnippets path... /路径必须存在于docs/_snippets/checkCodeSnippetPaths以docs/_snippets/为基准解析 path缺失即报Missing snippet裸Callout不允许必须带variantcheckCalloutVariant收集可能跨多行的完整开标签缺少variant即报错variantpositive非标准checkCalloutVariantPositive匹配variantpositive并提示改用variantinfo⚠️ 图标不得配variantinfocheckCalloutIconMismatch同行同时出现Callout、⚠️ 与variantinfo即报错frontmatter 值不必要的引号checkFrontmatterQuotes仅当title值不含、|、:、逗号等字符却加了引号时报错与文档特殊字符才引号规则一致与title相同的sidebar.title应省略checkRedundantSidebarTitle解析 frontmatter 中title与sidebar.title去引号后相等即报冗余此外runAllChecks还会执行一个文档正文未直接列出的检查 checkDeprecatedIfRenderer检测到已废弃的IfRenderer用法即提示改用If——这与其他组件一节推荐的If renderer{[...]}写法互为印证。值得注意的源码实现细节从源码结构看有两处细节让校验更健壮跨版本链接豁免checkRelativeLinks中定义了crossVersionRegex /^(?:\.\.\/)release-[\w.-]\//见 check-docs.ts指向其他发布分支如../../../release-8-6/docs/...的跨版本文档链接无法在本地验证会被直接跳过。行上下文感知多个检查依赖 utils.ts 中的getLineContextsgetLineContexts它把每一行标注为frontmatter、codeblock或content因此正文 H1、裸 URL等检查不会误伤代码块与 frontmatter 内的内容而slugifyslugify模拟了 rehype-slug 的标题 slug 行为支撑锚点片段校验。实践流程规则如何落到一次文档编辑上结合 SKILL.md 定义的工作流storybook-style.md的正确使用时机是先完成模式判定maintenance/improve/rewrite/author/strategy、主文档类型判定与草稿诊断这些由 docs-strategy.md 与 docs-principles.md 指导完成结构性与编辑性修改后加载storybook-style.md按本文语气与文风 → 标题/链接/列表/行内格式 → 自定义组件 → frontmatter → 块级 JSX 换行的顺序做风格收尾运行yarn fmt:write与yarn docs:check修复报告中的错误后再跑一次确认。注意不要在strategy模式或没有编辑任何文件时运行校验。这套风格规则文件 自动校验脚本的组合让 Storybook 仓库中docs/下数千个 MDX 页面与docs/_snippets/下的代码片段示例保持统一语感、统一组件用法和可机器验证的链接/格式合规性——写文档或为 Agent 编写文档审查规则时都值得借鉴这一规则即代码的做法。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考