| 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，做一致性校验
- 读
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 特有行为
- 读
apps/native-ui-playground/src/demos/$slug/ 全部 demo + index.tsx 汇总页
- 汇总页的
<Section title/description> 就是天然的章节大纲，文档章节直接对齐它
- 已有文档就读一遍，判断是补全还是重写
- 参考范例：
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={[...]} />
