expo-design-system-scaffolder

Expo Design System Scaffolder

参数化模板，用于生成从一开始就正确构建、无需事后改造的 Expo / React Native 设计系统组件。每个模板都使用 Unistyles v3 variants（绝不使用 style 逃生口）、ref 作为 prop、设计令牌和内置无障碍支持，并确保 Web/iOS 一致性（交互式基础组件支持 _web hover/focus/cursor），同时注明其满足的 expo-design-system 规则 ID。

适用场景

当用户希望进行以下操作时，使用此技能：

• 创建或添加新的共享组件——按钮、卡片、文本、输入框或其他基础组件
• 搭建一个用于列出领域实体（预约、患者、笔记）的新屏幕
• 在 Unistyles 主题中添加新的设计令牌组（颜色等）
• 添加一个用于展示组件各个变体的 Storybook story
• 开始一项新功能，并希望其组件从首次提交起就遵循设计系统
• 设置或更新设计系统的索引，以便 Agent 在构建新组件前发现并复用现有组件

可用模板

要搭建模板：读取模板，替换占位符，并将结果写入设计系统包（屏幕模板则写入 app/）。占位符是单花括号标识符令牌（例如 {ComponentName}）；字面 TSX 和 Unistyles 花括号（例如 { variant }、{item.title}）保持不变。

模板	生成内容	占位符
variant-component.tsx.template	带有 variant/size 变体、按压/禁用状态、Web hover/focus/cursor、无障碍支持和 ref prop 的 Pressable 基础组件	{ComponentName} {file_path}
card-surface.tsx.template	复合表面组件，包含 leading/trailing/children 插槽、tone/inset 变体和 elevation 令牌	{ComponentName} {file_path}
text-primitive.tsx.template	类型化文本组件，支持 variant/tone，不使用原始 style，限制字体缩放	{ComponentName} {file_path}
form-field.tsx.template	带标签的输入框：受控/非受控、ref prop、错误变体、Web 焦点环和无障碍支持	{ComponentName} {file_path}
list-screen.tsx.template	由基础组件组合而成的实体列表：FlashList、记忆化行、Web 行 hover/cursor、安全区域内边距	{ScreenName} {Entity} {entity} {entity_plural} {route_path} {file_path}
token-group.ts.template	原始 → 语义 → 组件令牌组，可合并到 Unistyles 主题中	{token_group} {file_path}
component-story.tsx.template	并排渲染所有变体的 Storybook story	{ComponentName} {file_path}
component-index.ts.template	设计系统唯一的公开入口兼清单目录——Agent 在设置样式前会读取它，以复用已有内容（优先复用）	{file_path}

常用占位符：

• {ComponentName} — PascalCase 组件名，例如 AppButton、AppCard、AppText、AppTextField
• {ScreenName} — 以 Screen 为后缀的 PascalCase 屏幕名，例如 AppointmentsScreen
• {Entity} / {entity} / {entity_plural} — PascalCase、camelCase 和复数形式，例如 Appointment / appointment / appointments
• {route_path} — 行跳转到的路由段，例如 appointments
• {token_group} — camelCase 令牌组名称，例如 statusBadge
• {file_path} — 目标路径，会写入头部注释中

使用方法

1. 选择与你要构建的内容相匹配的模板。
2. 为模板的占位符选择值（请参阅表格和各模板的头部注释）。
3. 替换标记，并将文件写入 design_system_dir（屏幕模板则写入 app_dir）。
4. 使用 component-story.tsx.template 生成对应的 Story，以便将各个变体编入目录。
5. 将新组件添加到设计系统索引（component-index.ts.template）中——添加一个 export 和一条单行目录项——这样下一个 Agent 就能找到并复用它，而不必重新构建。
6. 填充屏幕导入的数据层（use{Entity}List、domain 类型）——脚手架负责视图；数据由你负责。
7. 阅读 references/conventions.md，了解各模板遵循的规则以及何时可以偏离这些规则。

设置

config.json 是可选的。如果项目有所不同，请在首次使用时覆盖默认值：

• design_system_dir — 设计系统包的源目录（默认值：packages/design-system/src）
• app_dir — 屏幕模板使用的 Expo Router 路由目录（默认值：app）

相关技能

• expo-design-system — 这些模板遵循的规则集；每个生成的文件都会注明它。
• expo-react-native-coder — 围绕脚手架组件进行功能开发。