native-component-doc

name	native-component-doc
description	为 @skyroc/native-ui 组件编写文档。当用户说出 native 组件名（如 Button、Cell、ActionSheet）并要求写/补文档时触发。自动定位组件源码、playground demo、已有文档，按 native-ui-docs 的规范生成或更新 MDX。
argument-hint	组件名，如 Button、Cell、ActionSheet

Native UI 组件文档工作流

为 @skyroc/native-ui（React Native + Uniwind）编写文档的专用工作流。

这不是 web-ui 那套。native 的 <Demo> 会把 demo 源码整份渲染出来、右栏还有整页手机预览， 因此不写内联代码块、demo 一律具名导出、每个 demo 都要在汇总页里串一遍。 与 component-doc（web-ui 用）的差异见文末「与 web-ui 文档规范的差异」。

文件定位规则

给定组件名 $COMPONENT（如 ActionSheet），转 kebab-case $slug（如 action-sheet）：

用途	路径
组件源码	packages/native/ui/src/components/$slug/
Playground 单点 demo	apps/native-ui-playground/src/demos/$slug/*.tsx
Playground 汇总页	apps/native-ui-playground/src/demos/$slug/index.tsx
Playground 路由页	apps/native-ui-playground/app/components/$slug.tsx
文档 MDX	docs/native-ui-docs/content/docs/components/($group)/$slug.mdx

文档基础设施（了解即可，不必每次都读）：

文件	作用
docs/native-ui-docs/components/mdx.tsx	MDX 组件注册，只有 Demo / PropsTable / TypeTable / UnionType
docs/native-ui-docs/components/demo/index.tsx	<Demo>：读 demo 源码 + 渲染预览 + 「在 playground 打开」
docs/native-ui-docs/components/demo/demo-preview.tsx	动态 import demos 目录，按模块名取具名导出
docs/native-ui-docs/components/props-table.tsx	<PropsTable> API 属性表
docs/native-ui-docs/components/type-table.tsx	<TypeTable> + <UnionType> 类型区
docs/native-ui-docs/components/type-anchor.tsx	PascalCase 类型 → 锚点链接，BUILTIN_TYPE_NAMES 白名单
docs/native-ui-docs/components/type-registry.ts	跨页面类型链接注册表
docs/native-ui-docs/lib/playground-demo.ts	文档页 slug → playground 整页路由，决定是否分栏

侧边栏分组

content/docs/components/ 下按 fumadocs 路由组分组，路由组不进 URL（(general)/button.mdx → /docs/components/button）。 写完文档后必须把 $slug 加进对应分组的 meta.json 的 pages 里（meta.json 已预置全部规划中的 slug，通常只需确认位置正确）。

目录	标题	组件
(general)	通用	button, floating-button, text, text-ellipsis, divider, image
(layout)	布局容器	space, grid, cell, collapse
(input)	输入	form, field, input, password-input, search, checkbox, radio, switch, slider, stepper, rate, signature, picker, picker-group, date-picker, time-picker, calendar, number-keyboard, tree-select
(data-display)	数据展示	avatar, badge, tag, count-down, rolling-text, swipe-cell
(navigation)	导航	navbar, tabs, sidebar, anchor-nav, index-bar, back-top, pagination, dropdown-menu
(overlay)	弹层覆盖	popup, dialog, sheet, action-sheet, share-sheet
(feedback)	反馈	toast, notify

meta.json 里列了但文件还不存在的 slug 会被 fumadocs 静默跳过（resolveFolderItem 找不到 node 直接 return），所以预置清单不会报错。

meta.json 里不要写 "collapsible": false。fumadocs-ui 16.14.4 的 SidebarFolderTrigger 在 collapsible: false 分支直接渲染成 jsx("div", { ...props })，而上层 （layouts/docs/slots/sidebar.js:220）传下来的 className 是个 (state) => string 函数 —— 函数原样落到 DOM 上，React 报 Invalid value for prop \className` on

tag，分组标题也因此丢掉全部样式类。 collapsible走默认的true时，trigger 渲染成 Base UI 的Collapsible.Trigger，函数 className 会被 useRenderElement 正常解析。defaultOpen: true已经能让分组默认展开，不需要collapsible: false`。

执行流程

Phase 1：读源码与 demo，做一致性校验

1. 读 packages/native/ui/src/components/$slug/ 全部文件
   • index.ts：实际导出了哪些组件、哪些类型
   • types.ts：public props 与类型别名
   • *-variants.ts：slots / variants / compoundVariants / defaultVariants —— 表格里的每一行数值都从这里抄，不要凭印象写
   • 主组件 *.tsx：props 实际怎么解构、默认值在哪、有没有 hitSlop / accessibilityState / TextClassContext / Portal 之类的 RN 特有行为
2. 读 apps/native-ui-playground/src/demos/$slug/ 全部 demo + index.tsx 汇总页
   • 汇总页的 <Section title/description> 就是天然的章节大纲，文档章节直接对齐它
3. 已有文档就读一遍，判断是补全还是重写
4. 参考范例：docs/native-ui-docs/content/docs/components/(general)/button.mdx（当前唯一的完整样板）

实现一致性校验（必须执行）

文档不是 API 想象稿，从源码 / 类型 / variants / demo 四者交叉验证：

• types.ts 声明的 props，主组件是否真的解构并使用
• 默认值实际在哪里设置（defaultVariants vs 组件内 = false），两处不一致时以运行时为准
• classNames 的每个 slot 是否真的接到了对应节点上
• index.ts 是否真的导出了你要写进文档的类型
• RN 特有：hitSlop、accessibilityRole / accessibilityState、Pressable 透传、TextClassContext 继承范围、Portal / Modal 挂载点

发现类型/API 承诺与实现不一致时：先明确指出这是实现问题；能改就改实现或类型，不要在文档里绕过去；不能改就在最终说明里列为风险，并且不在文档中承诺未实现的能力。不允许靠降低文档表述来掩盖实现 bug。

Phase 2：写文档

MDX 结构

---
title: $COMPONENT
description: 一句话描述组件用途
---

概述段落：组件做什么、基于什么 RN 原语封装、有什么与众不同的行为。

\`\`\`tsx
import { $COMPONENT } from '@skyroc/native-ui';
\`\`\`

## 基础用法

<Demo src="@playground/$slug/$DemoBasic" />

## 何时使用

- 使用场景 / 移动端取舍
- 与相似组件的区分（如 Popup vs Sheet vs ActionSheet）

## 功能章节（variant / color / size / shape / ...）

说明文字 +（枚举类的）表格

<Demo src="@playground/$slug/$DemoName" />

补充说明：容易踩的坑、和 web 端行为不同的地方

## 无障碍

role / accessibilityState / 热区 等 RN 专属说明（有就写）

## API

### $COMPONENT

<PropsTable data={[...]} />

## 类型

\`\`\`ts
import type { ... } from '@skyroc/native-ui';
\`\`\`

<UnionType ... />
<TypeTable data={[...]} />