@skyroc/scripts 2.5.1 → 2.5.2

package/templates/admin-root/.agents/skills/migrate-oxfmt/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: migrate-oxfmt
+description: Guide for migrating a project from Prettier or Biome to Oxfmt. Use when asked to migrate, convert, or switch a JavaScript/TypeScript project's formatter from Prettier or Biome to Oxfmt.
+---
+
+This skill guides you through migrating a JavaScript/TypeScript project from Prettier or Biome to [Oxfmt](https://oxc.rs/docs/guide/usage/formatter).
+
+## Overview
+
+Oxfmt is a high-performance, Prettier-compatible code formatter. Most Prettier options are supported directly.
+
+An automated migration tool is built into oxfmt, supporting both Prettier and Biome as migration sources.
+
+## Step 1: Run Automated Migration
+
+### From Prettier
+
+```bash
+npx oxfmt@latest --migrate prettier
+```
+
+This will:
+
+- Find and read your Prettier config (any format Prettier supports)
+- Create `.oxfmtrc.json` with migrated options
+- Migrate `.prettierignore` patterns to `ignorePatterns`
+- Migrate `prettier-plugin-tailwindcss` options to `sortTailwindcss`
+- Detect `prettier-plugin-packagejson` and enable `sortPackageJson`
+
+### From Biome
+
+```bash
+npx oxfmt@latest --migrate biome
+```
+
+This will:
+
+- Find and read `biome.json` or `biome.jsonc`
+- Create `.oxfmtrc.json` with migrated options
+- Migrate negated patterns from `files.includes` to `ignorePatterns`
+- Map Biome's two-level config (`formatter.*` and `javascript.formatter.*`) to oxfmt options
+
+Biome option mapping:
+
+| Biome                                                       | oxfmt                             |
+| ----------------------------------------------------------- | --------------------------------- |
+| `formatter.indentStyle` (`"tab"`/`"space"`)                 | `useTabs` (`true`/`false`)        |
+| `formatter.indentWidth`                                     | `tabWidth`                        |
+| `formatter.lineWidth`                                       | `printWidth`                      |
+| `javascript.formatter.quoteStyle`                           | `singleQuote`                     |
+| `javascript.formatter.jsxQuoteStyle`                        | `jsxSingleQuote`                  |
+| `javascript.formatter.quoteProperties` (`"asNeeded"`)       | `quoteProps` (`"as-needed"`)      |
+| `javascript.formatter.trailingCommas`                       | `trailingComma`                   |
+| `javascript.formatter.semicolons` (`"always"`/`"asNeeded"`) | `semi` (`true`/`false`)           |
+| `javascript.formatter.arrowParentheses` (`"asNeeded"`)      | `arrowParens` (`"avoid"`)         |
+| `formatter.bracketSameLine`                                 | `bracketSameLine`                 |
+| `formatter.bracketSpacing`                                  | `bracketSpacing`                  |
+| `formatter.attributePosition` (`"multiline"`)               | `singleAttributePerLine` (`true`) |
+
+Notes (both sources):
+
+- Fails if `.oxfmtrc.json` already exists. Delete it first if you want to re-run.
+- If no source config is found, creates a blank `.oxfmtrc.json` instead.
+- `overrides` cannot be auto-migrated for either source and must be converted manually.
+
+## Step 2: Review Generated Config
+
+After migration, review the generated `.oxfmtrc.json` for these key differences:
+
+### printWidth
+
+Prettier and Biome default is 80, oxfmt default is 100. The migration tool sets `printWidth: 80` if not specified in your source config. Decide whether to keep 80 or adopt 100.
+
+### Unsupported Options (Prettier only)
+
+These Prettier options are skipped during migration:
+
+| Option                         | Status                                           |
+| ------------------------------ | ------------------------------------------------ |
+| `endOfLine: "auto"`            | Not supported. Use `"lf"` or `"crlf"` explicitly |
+| `experimentalTernaries`        | Not supported in JS/TS files yet                 |
+| `experimentalOperatorPosition` | Not supported in JS/TS files yet                 |
+
+### sortPackageJson (Prettier only)
+
+Enabled by default in oxfmt, but the migration tool disables it unless `prettier-plugin-packagejson` was detected. Review whether you want this enabled.
+
+Note: Oxfmt's sorting algorithm differs from `prettier-plugin-packagejson`.
+
+### embeddedLanguageFormatting (Prettier only)
+
+Embedded language formatting (e.g., CSS-in-JS) generally works, but some formatting may differ from Prettier.
+
+### overrides
+
+The `overrides` field cannot be auto-migrated from either Prettier or Biome. Convert manually:
+
+```json
+{
+  "overrides": [
+    {
+      "files": ["*.md"],
+      "options": { "tabWidth": 4 }
+    }
+  ]
+}
+```
+
+### Nested Config
+
+Oxfmt does not support nested configuration files (e.g., a separate `.oxfmtrc.json` in a subdirectory). If your project used per-directory Prettier or Biome configs, consolidate them using `overrides` with file glob patterns, or run oxfmt separately per directory with different working directories.
+
+### Prettier-Compatible Options
+
+These options transfer directly with the same behavior:
+`tabWidth`, `useTabs`, `semi`, `singleQuote`, `jsxSingleQuote`, `quoteProps`, `trailingComma`, `arrowParens`, `bracketSpacing`, `bracketSameLine`, `endOfLine`, `proseWrap`, `htmlWhitespaceSensitivity`, `singleAttributePerLine`, `vueIndentScriptAndStyle`
+
+## Step 3: Configure Oxfmt Extensions
+
+Oxfmt offers features not available in Prettier:
+
+### sortImports
+
+Sort import statements, inspired by `eslint-plugin-perfectionist/sort-imports` (disabled by default):
+
+```json
+{
+  "sortImports": {
+    "partitionByNewline": true,
+    "newlinesBetween": false
+  }
+}
+```
+
+### sortTailwindcss
+
+Replaces `prettier-plugin-tailwindcss`. Auto-migrated with renamed options:
+
+| Prettier (top-level)         | oxfmt (`sortTailwindcss.*`) |
+| ---------------------------- | --------------------------- |
+| `tailwindConfig`             | `config`                    |
+| `tailwindStylesheet`         | `stylesheet`                |
+| `tailwindFunctions`          | `functions`                 |
+| `tailwindAttributes`         | `attributes`                |
+| `tailwindPreserveWhitespace` | `preserveWhitespace`        |
+| `tailwindPreserveDuplicates` | `preserveDuplicates`        |
+
+### Other Extensions
+
+| Option               | Default | Description                                                                  |
+| -------------------- | ------- | ---------------------------------------------------------------------------- |
+| `insertFinalNewline` | `true`  | Whether to add a final newline at end of file                                |
+| `sortPackageJson`    | `true`  | Sort `package.json` keys. Set `{ "sortScripts": true }` to also sort scripts |
+
+## Step 4: Update CI and Scripts
+
+Replace formatter commands with oxfmt:
+
+```bash
+# Before (Prettier)
+npx prettier --write .
+npx prettier --check .
+
+# Before (Biome)
+npx biome format --write .
+npx biome check .
+
+# After
+npx oxfmt@latest
+npx oxfmt@latest --check
+```
+
+### Common CLI Options
+
+| Prettier / Biome                                | oxfmt                                        |
+| ----------------------------------------------- | -------------------------------------------- |
+| `prettier --write .` / `biome format --write .` | `oxfmt` (default: cwd, `--write` mode)       |
+| `prettier --check .` / `biome check .`          | `oxfmt --check`                              |
+| `prettier --list-different .`                   | `oxfmt --list-different`                     |
+| `prettier --config path`                        | `oxfmt --config path`                        |
+| `prettier --ignore-path .prettierignore`        | `oxfmt --ignore-path .prettierignore`        |
+| `cat file \| prettier --stdin-filepath=file.ts` | `cat file \| oxfmt --stdin-filepath=file.ts` |
+
+### File Type Coverage
+
+- JS/TS: Formatted natively by oxfmt
+- TOML: Formatted natively (via taplo)
+- CSS, HTML, YAML, Markdown, GraphQL, etc.: Delegated to Prettier internally (when using `npx oxfmt`)
+
+## Tips
+
+- EditorConfig: Oxfmt reads `.editorconfig` automatically for `useTabs`, `tabWidth`, `endOfLine`, `insertFinalNewline`, and `printWidth`. Options in `.oxfmtrc.json` take precedence.
+- CI: Use `npx oxfmt@latest --check` to enforce formatting in CI.
+- LSP: Run `oxfmt --lsp` for editor integration via Language Server Protocol.
+- Schema support: Add `"$schema": "./node_modules/oxfmt/configuration_schema.json"` to `.oxfmtrc.json` for editor autocompletion.
+- Init: Run `npx oxfmt@latest --init` to create a default `.oxfmtrc.json` without migration.
+
+## References
+
+- [CLI Reference](https://oxc.rs/docs/guide/usage/formatter/cli.html)
+- [Config File Reference](https://oxc.rs/docs/guide/usage/formatter/config-file-reference.html)
+- [Unsupported Features](https://oxc.rs/docs/guide/usage/formatter/unsupported-features.html)

package/templates/admin-root/.agents/skills/migrate-oxlint/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: migrate-oxlint
+description: Guide for migrating a project from ESLint to Oxlint. Use when asked to migrate, convert, or switch a JavaScript/TypeScript project's linter from ESLint to Oxlint.
+---
+
+This skill guides you through migrating a JavaScript/TypeScript project from ESLint to [Oxlint](https://oxc.rs/docs/guide/usage/linter/).
+
+## Overview
+
+Oxlint is a high-performance linter that implements many popular ESLint rules natively in Rust. It can be used alongside ESLint or as a full replacement.
+
+An official migration tool is available, and will be used by this skill: [`@oxlint/migrate`](https://github.com/oxc-project/oxlint-migrate)
+
+## Step 1: Run Automated Migration
+
+Run the migration tool in the project root:
+
+```bash
+npx @oxlint/migrate
+```
+
+This reads your ESLint flat config (`eslint.config.js` for example) and generates a `.oxlintrc.json` file from it. It will find your ESLint config file automatically in most cases.
+
+See options below for more info.
+
+### Key Options
+
+| Option                      | Description                                                                                                                     |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `--type-aware`              | Include type-aware rules from `@typescript-eslint` (will require the `oxlint-tsgolint` package to be installed after migrating) |
+| `--with-nursery`            | Include experimental rules still under development, may not be fully stable or consistent with ESLint equivalents               |
+| `--js-plugins [bool]`       | Enable/disable ESLint plugin migration via `jsPlugins` (default: enabled)                                                       |
+| `--details`                 | List rules that could not be migrated                                                                                           |
+| `--replace-eslint-comments` | Convert all `// eslint-disable` comments to `// oxlint-disable`                                                                 |
+| `--output-file <file>`      | Specify a different output path (default: `.oxlintrc.json`)                                                                     |
+
+If your ESLint config is not at the default location, pass the path explicitly:
+
+```bash
+npx @oxlint/migrate ./path/to/eslint.config.js
+```
+
+## Step 2: Review Generated Config
+
+After migration, review the generated `.oxlintrc.json`.
+
+### Plugin Mapping
+
+The migration tool automatically maps ESLint plugins to oxlint's built-in equivalents. The following table is for reference when reviewing the generated config:
+
+| ESLint Plugin                                       | Oxlint Plugin Name |
+| --------------------------------------------------- | ------------------ |
+| `@typescript-eslint/eslint-plugin`                  | `typescript`       |
+| `eslint-plugin-react` / `eslint-plugin-react-hooks` | `react`            |
+| `eslint-plugin-import` / `eslint-plugin-import-x`   | `import`           |
+| `eslint-plugin-unicorn`                             | `unicorn`          |
+| `eslint-plugin-jsx-a11y`                            | `jsx-a11y`         |
+| `eslint-plugin-react-perf`                          | `react-perf`       |
+| `eslint-plugin-promise`                             | `promise`          |
+| `eslint-plugin-jest`                                | `jest`             |
+| `@vitest/eslint-plugin`                             | `vitest`           |
+| `eslint-plugin-jsdoc`                               | `jsdoc`            |
+| `eslint-plugin-next`                                | `nextjs`           |
+| `eslint-plugin-node`                                | `node`             |
+| `eslint-plugin-vue`                                 | `vue`              |
+
+Default plugins (enabled when `plugins` field is omitted): `unicorn`, `typescript`, `oxc`.
+Setting the `plugins` array explicitly overrides these defaults.
+
+ESLint core rules are usable in oxlint without needing to configure a plugin in the config file.
+
+### Rule Categories
+
+Oxlint groups rules into categories for bulk configuration, though only `correctness` is enabled by default:
+
+```json
+{
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn"
+  }
+}
+```
+
+Available categories: `correctness` (default: enabled), `suspicious`, `pedantic`, `perf`, `style`, `restriction`, `nursery`.
+
+Individual rule settings in `rules` override category settings.
+
+`@oxlint/migrate` will turn `correctness` off to avoid enabling additional rules that weren't enabled by your ESLint config. You can choose to enable additional categories after migration if desired.
+
+### Check Unmigrated Rules
+
+Run with `--details` to see which ESLint rules could not be migrated:
+
+```bash
+npx @oxlint/migrate --details
+```
+
+Review the output and decide whether to keep ESLint for those rules or not. Some rules may be mentioned in the output from `--details` as having equivalents in oxlint that were not automatically mapped by the migration tool. In those cases, consider enabling the equivalent oxlint rule manually after migration.
+
+## Step 3: Install Oxlint
+
+Install the core oxlint package (use `yarn install`, `pnpm install`, `vp install`, `bun install`, etc. depending on your package manager):
+
+```bash
+npm install -D oxlint
+```
+
+If you want to add the `oxlint-tsgolint` package, if you intend to use type-aware rules that require TypeScript type information:
+
+```bash
+npm install -D oxlint-tsgolint
+```
+
+No other packages besides the above are needed by default, though you will need to keep/install any additional ESLint plugins that were migrated into `jsPlugins`. Do not add `@oxlint/migrate` to the package.json, it is meant for one-off usage.
+
+## Step 4: Handle Unsupported Features
+
+Some features require manual attention:
+
+- Local plugins (relative path imports): Must be migrated manually to `jsPlugins`
+- `eslint-plugin-prettier`: Supported, but very slow. It is recommended to use [oxfmt](https://oxc.rs/docs/guide/usage/formatter) instead, or switch to `prettier --check` as a separate step alongside oxlint.
+- `settings` in override configs: Oxlint does not support `settings` inside `overrides` blocks.
+- ESLint v9+ plugins: Not all work with oxlint's JS Plugins API, but the majority will.
+
+### Local Plugins
+
+If you have any custom ESLint rules in the project repo itself, you can migrate them manually after running the migration tool by adding them to the `jsPlugins` field in `.oxlintrc.json`:
+
+```json
+{
+  "jsPlugins": ["./path/to/my-plugin.js"],
+  "rules": {
+    "local-plugin/rule-name": "error"
+  }
+}
+```
+
+### External ESLint Plugins
+
+For ESLint plugins without a built-in oxlint equivalent, use the `jsPlugins` field to load them:
+
+```json
+{
+  "jsPlugins": ["eslint-plugin-custom"],
+  "rules": {
+    "custom/my-rule": "warn"
+  }
+}
+```
+
+## Step 5: Update CI and Scripts
+
+Replace ESLint commands with oxlint. Path arguments are optional; oxlint defaults to the current working directory.
+
+```bash
+# Before
+npx eslint src/
+npx eslint --fix src/
+
+# After
+npx oxlint src/
+npx oxlint --fix src/
+```
+
+### Common CLI Options
+
+| ESLint                    | oxlint equivalent                              |
+| ------------------------- | ---------------------------------------------- |
+| `eslint .`                | `oxlint` (default: lints the cwd)              |
+| `eslint src/`             | `oxlint src/`                                  |
+| `eslint --fix`            | `oxlint --fix`                                 |
+| `eslint --max-warnings 0` | `oxlint --deny-warnings` or `--max-warnings 0` |
+| `eslint --format json`    | `oxlint --format json`                         |
+
+Additional oxlint options:
+
+- `--tsconfig <path>`: Specify tsconfig.json path, likely unnecessary unless you have a non-standard name for `tsconfig.json`.
+
+## Tips
+
+- You can run alongside ESLint if necessary: Oxlint is designed to complement ESLint during migration, but with JS Plugins many projects can switch over fully without losing many rules.
+- Disable comments work: `// eslint-disable` and `// eslint-disable-next-line` comments are supported by oxlint. Use `--replace-eslint-comments` when running @oxlint/migrate to convert them to `// oxlint-disable` equivalents if desired.
+- List available rules: Run `npx oxlint --rules` to see all supported rules, or refer to the [rule documentation](https://oxc.rs/docs/guide/usage/linter/rules.html).
+- Schema support: Add `"$schema": "./node_modules/oxlint/configuration_schema.json"` to `.oxlintrc.json` for editor autocompletion if the migration tool didn't do it automatically.
+- Output formats: `default`, `stylish`, `json`, `github`, `gitlab`, `junit`, `checkstyle`, `unix`
+- Ignore files: `.eslintignore` is supported by oxlint if you have it, but it's recommended to move any ignore patterns into the `ignorePatterns` field in `.oxlintrc.json` for consistency and simplicity. All files and paths ignored via a `.gitignore` file will be ignored by oxlint by default as well.
+- If you ran the migration tool multiple times, remove the `.oxlintrc.json.bak` backup file created by the migration tool once you've finished migrating.
+- If you are not using any JS Plugins and have replaced your ESLint configuration, you can remove all ESLint packages from your project dependencies.
+- Ensure your editor is configured to use oxlint instead of ESLint for linting and error reporting. You may want to install the Oxc extension for your preferred editor. See https://oxc.rs/docs/guide/usage/linter/editors.html for more details.
+
+## References
+
+- [CLI Reference](https://oxc.rs/docs/guide/usage/linter/cli.html)
+- [Config File Reference](https://oxc.rs/docs/guide/usage/linter/config-file-reference.html)
+- [Complete Oxlint rule list and docs](https://oxc.rs/docs/guide/usage/linter/rules.html)

package/templates/admin-root/.agents/skills/native-component-doc/SKILL.md

@@ -0,0 +1,245 @@
+---
+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 <div> 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 结构
+
+```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={[...]} />
+```
+
+#### Demo 引用规则（native 专属）
+
+- 格式：`<Demo src="@playground/$slug/$DemoName" />`，**没有 `modules/` 这一层**（那是 web-ui 的）
+- **不要在 `<Demo>` 后面贴内联代码块**。`<Demo>` 已经把整份 demo 源码渲染在预览下方了，内联代码是重复噪音
+- **覆盖率要求：`src/demos/$slug/index.tsx` 里串的每个子 demo，文档必须有且仅有一处 `<Demo>` 引用**。章节顺序也尽量对齐汇总页
+- demo 缺失时**必须补 demo**，不能因为没 demo 就只写文字
+
+写完用这条命令核对覆盖率（无输出即一一对应）：
+
+```bash
+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)
+```
+
+#### 新建 Playground Demo 的规范
+
+1. 路径：`apps/native-ui-playground/src/demos/$slug/$DemoName.tsx`，`$DemoName` 以组件名开头（`ButtonLoading`、`CellSize`）
+2. **必须具名导出，且导出名 === 文件名** —— `demo-preview.tsx` 是按模块名去取 `mod[exportName]` 的，写成 `export default` 或改名都会拿不到组件
+3. 模板：
+
+```tsx
+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 };
+```
+
+4. 约束：
+   - 不写 `'use client'`（RN，不是 Next 客户端组件）
+   - 从 `@skyroc/native-ui` 导入组件，不从内部路径导入
+   - 容器统一 `View` + uniwind 类名，带上 `bg-background p-4`，保证在文档预览的手机框里边距一致
+   - 每个 demo 只聚焦一个功能点，自包含，不依赖同目录 `shared.tsx`
+   - 需要文字就用 `@skyroc/native-ui` 的 `Text`，才能继承 `TextClassContext`
+5. **同步汇总页**：在 `src/demos/$slug/index.tsx` 里 import 并加一个 `<Section title description>`。汇总页只负责串场，不要把示例代码写回去
+6. **确认整页路由存在**：`apps/native-ui-playground/app/components/$slug.tsx`。它是文档右栏分栏预览的来源（`resolvePlaygroundPage` 按最后一段 slug 找同名文件），缺了文档就退回单栏
+
+#### PropsTable 书写规则
+
+- 短字面量联合**直接内联**到 `type` 字段，不要另起 PascalCase 类型名，也不要写 `<UnionType>`
+  - 例：`"'solid' | 'tonal' | 'outline' | 'ghost'"`、`"'sm' | 'md' | 'lg' | 'icon'"`、`"'horizontal' | 'vertical'"`
+- 对象类型、slot 配置、子组件 Props、外部大型类型才用 PascalCase 引用
+- `default` 用字符串写：`"'md'"`、`'false'`
+- `required: true` 仅必填时加
+- 表格开头或结尾说明透传关系：如「除下表外，`Button` 透传 `Pressable` 的全部属性」
+- `ref` 也写进表里（RN 的 ref 常用于 `measure` / 滚动定位）
+
+#### 类型完整性规则（严格遵循）
+
+**PropsTable / TypeTable 中出现的每一个非内置 PascalCase 类型名，都必须在当前页 `## 类型` 区域有定义，或在 `type-registry.ts` 注册跨页链接。**
+
+写完逐项核对：
+
+1. 收集所有 `<PropsTable>` 的 `type`、所有 `<TypeTable>` 的 `fields[].type` 里的 PascalCase 词
+2. 排除 `type-anchor.tsx` 的 `BUILTIN_TYPE_NAMES`（含 RN 原语：`PressableProps` / `ViewStyle` / `TextStyle` / `StyleProp` / `GestureResponderEvent` / `AccessibilityRole` / `View` / `Ref` 等）
+3. 剩下的每一个都要满足：当前页 `<TypeTable name>` 定义 ∨ 当前页 `<UnionType name>` 定义 ∨ `type-registry.ts` 注册
+4. 遗漏的如果只是短联合 → 改成内联，不补 `<UnionType>`
+5. 用到了 PascalCase 但它是 React / RN / TS 内置或三方类型 → 加进 `BUILTIN_TYPE_NAMES`，否则会生成错误的本页锚点
+6. 跨页引用格式：`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>` 在后
+
+### Phase 3：收尾核对
+
+1. 覆盖率命令跑一遍，`<Demo>` 与 demos 目录一一对应
+2. 分组 `meta.json` 的 `pages` 含 `$slug`
+3. 类型完整性清单逐条过
+4. 表格里的数值（高度、字号、间距、圆角）与 `*-variants.ts` 逐条对得上
+5. 最终回复里区分：本次改了哪些文件、发现但未处理的实现问题、未验证的部分及原因
+
+## 工作区边界
+
+- 默认只动：目标 `$slug.mdx`、缺失的 playground demo 及其汇总页、分组 `meta.json`
+- 不回滚、不格式化、不整理与本组件无关的用户改动
+- 组件源码有未提交改动时，基于当前工作区实现写文档
+- 只有实现问题导致文档无法正确描述组件时，才改组件源码或类型，且改之前先说明问题
+
+## 与 web-ui 文档规范的差异
+
+| 维度         | 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` 等）  |