メニュー
为 @skyroc/native-ui 组件编写文档。当用户说出 native 组件名（如 Button、Cell、ActionSheet）并要求写/补文档时触发。自动定位组件源码、playground demo、已有文档，按 native-ui-docs 的规范生成或更新 MDX。
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/Ohh-889/skyroc --skill native-component-docコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
UI/UX design intelligence for web, mobile, and desktop. This skill should be used when designing, building, reviewing, or fixing interfaces, including pages, components, design systems, accessibility, interaction, responsive layout, typography, color, charts, and stack-specific UI implementation. Searchable local data: 79 searchable styles (50 active), 192 product palettes and reasoning profiles, 74 font pairings, 119 UX guidelines, 105 icons, 17 GSAP presets, 25 chart types, and 22 stacks.
为 Skyroc Admin / RuoYi Plus Fast 模块编写来源可追溯的 PRD，并生成可独立打开、可交互、经过桌面端和移动端验收的 HTML 设计原型。仅在用户明确要求使用本 Skill 时启用。
面向复杂功能的代码库探索、架构决策、实现与质量审查工作流。仅在用户明确调用本 Skill，或功能明显涉及多个模块或系统、重要架构调整、兼容性决策、数据迁移或高风险实现时使用；不要用于范围清晰的小型或中型改动。
SKILL.md を表示中
| name | native-component-doc |
| description | 为 @skyroc/native-ui 组件编写文档。当用户说出 native 组件名（如 Button、Cell、ActionSheet）并要求写/补文档时触发。自动定位组件源码、playground demo、已有文档，按 native-ui-docs 的规范生成或更新 MDX。 |
| argument-hint | 组件名，如 Button、Cell、ActionSheet |
为 @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
，分组标题也因此丢掉全部样式类。 collapsible走默认的true时，trigger 渲染成 Base UI 的Collapsible.Trigger，函数 className 会被 useRenderElement 正常解析。defaultOpen: true已经能让分组默认展开，不需要collapsible: false`。
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 是否真的导出了你要写进文档的类型hitSlop、accessibilityRole / accessibilityState、Pressable 透传、TextClassContext 继承范围、Portal / Modal 挂载点发现类型/API 承诺与实现不一致时：先明确指出这是实现问题；能改就改实现或类型，不要在文档里绕过去；不能改就在最终说明里列为风险，并且不在文档中承诺未实现的能力。不允许靠降低文档表述来掩盖实现 bug。
---
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={[...]} />
<Demo src="@playground/$slug/$DemoName" />，没有 modules/ 这一层（那是 web-ui 的）<Demo> 后面贴内联代码块。<Demo> 已经把整份 demo 源码渲染在预览下方了，内联代码是重复噪音src/demos/$slug/index.tsx 里串的每个子 demo，文档必须有且仅有一处 <Demo> 引用。章节顺序也尽量对齐汇总页写完用这条命令核对覆盖率（无输出即一一对应）：
slug=button; group='(general)'
diff \
<(ls apps/native-ui-playground/src/demos/$slug | grep -v '^index' | sed 's/\.tsx$//' | sort) \
<(grep -o "@playground/$slug/[A-Za-z0-9]*" "docs/native-ui-docs/content/docs/components/$group/$slug.mdx" | sed 's|.*/||' | sort -u)
apps/native-ui-playground/src/demos/$slug/$DemoName.tsx，$DemoName 以组件名开头（ButtonLoading、CellSize）demo-preview.tsx 是按模块名去取 mod[exportName] 的，写成 export default 或改名都会拿不到组件import { Button } from '@skyroc/native-ui';
import { View } from 'react-native';
const ButtonLoading = () => {
return (
<View className="gap-3 bg-background p-4">
{/* ... */}
</View>
);
};
export { ButtonLoading };
'use client'（RN，不是 Next 客户端组件）@skyroc/native-ui 导入组件，不从内部路径导入View + uniwind 类名，带上 bg-background p-4，保证在文档预览的手机框里边距一致shared.tsx@skyroc/native-ui 的 Text，才能继承 TextClassContextsrc/demos/$slug/index.tsx 里 import 并加一个 <Section title description>。汇总页只负责串场，不要把示例代码写回去apps/native-ui-playground/app/components/$slug.tsx。它是文档右栏分栏预览的来源（resolvePlaygroundPage 按最后一段 slug 找同名文件），缺了文档就退回单栏type 字段，不要另起 PascalCase 类型名，也不要写 <UnionType>
"'solid' | 'tonal' | 'outline' | 'ghost'"、"'sm' | 'md' | 'lg' | 'icon'"、"'horizontal' | 'vertical'"default 用字符串写："'md'"、'false'required: true 仅必填时加Button 透传 Pressable 的全部属性」ref 也写进表里（RN 的 ref 常用于 measure / 滚动定位）PropsTable / TypeTable 中出现的每一个非内置 PascalCase 类型名，都必须在当前页 ## 类型 区域有定义，或在 type-registry.ts 注册跨页链接。
写完逐项核对：
<PropsTable> 的 type、所有 <TypeTable> 的 fields[].type 里的 PascalCase 词type-anchor.tsx 的 BUILTIN_TYPE_NAMES（含 RN 原语：PressableProps / ViewStyle / TextStyle / StyleProp / GestureResponderEvent / AccessibilityRole / View / Ref 等）<TypeTable name> 定义 ∨ 当前页 <UnionType name> 定义 ∨ type-registry.ts 注册<UnionType>BUILTIN_TYPE_NAMES，否则会生成错误的本页锚点TypeName: '/docs/components/target-slug#anchor'（注意 docsRoute = '/docs'，别漏 /docs 前缀）import type { ... } from '@skyroc/native-ui' 代码块，列出本组件对外导出的类型<UnionType>：联合类型（由 variants 推导出来的 XxxVariant / XxxSize / XxxSlots 等），一句话说明它控制什么<TypeTable>：对象类型（SlotClassNames、子组件 Props、Option / ItemData 之类）<UnionType> 在前（跟 Props 表顺序对应），<TypeTable> 在后<Demo> 与 demos 目录一一对应meta.json 的 pages 含 $slug*-variants.ts 逐条对得上$slug.mdx、缺失的 playground demo 及其汇总页、分组 meta.json| 维度 | web-ui (component-doc) | native-ui（本 skill） |
|---|---|---|
| Demo 路径 | @playground/$slug/modules/Name | @playground/$slug/Name（无 modules） |
| Demo 导出 | export default | 具名导出，名字 === 文件名 |
| 内联代码块 | 推荐，跟在 <Demo> 后 | 不写，<Demo> 已渲染完整源码 |
| Demo 运行时 | react-live 沙箱 + scope.ts | Turbopack 动态 import 真实 RN 组件，ssr: false |
| 整页预览 | 无 | 右栏手机框渲染 app/components/$slug.tsx 整页 |
'use client' | 需要 | 不需要 |
| 内置类型白名单 | DOM / React 为主 | 额外含 RN 原语（PressableProps / ViewStyle 等） |