develop

在应用中实现 Subframe 设计。对于同步相关问题，请在不修改文件的前提下说明以下边界。

选择事实来源

编写代码前，检查应用包中的 .subframe/sync.json、同步目录、组件导入、主题文件、路由和 package.json。说明现有证据支持哪种模式：

• Subframe 管理主题和组件。 同步配置以及应用中使用的生成组件表明采用此模式。使用这些组件构建页面。在 Subframe 中进行视觉更改，然后重新同步；在代码中处理应用行为。如果 Subframe 中缺少所需组件或令牌，请先在设计中添加，再引入代码。不要手工仿制相似外观，也不要修改生成的样式。
• 代码库管理主题和组件。 已有 MUI、shadcn 等成熟库或自定义组件，且没有 Subframe 同步配置，表明采用此模式。将 Subframe 页面视为视觉参考。使用应用的组件和令牌实现，并将样式转换为对应写法，而不是粘贴绕过这些组件和令牌的 Tailwind 类。除非用户选择采用 Subframe，否则不要初始化或同步 Subframe。如果用户要求将代码系统引入 Subframe，请使用 import，让后续设计能忠实沿用该系统。
• 混合或不明确。 说明这两种模式及各自的证据，包括项目不匹配之处。针对目标屏幕，遵循已确立的边界。只有当尚未确定的选择会影响要使用的组件、主题或文件时，才提出问题。

只有在应用尚未配置 Subframe，且用户希望使用 Subframe 组件，或 init/sync 失败时，才阅读 setup.md。

尽量少用令牌获取代码

只针对正在实现的页面调用一次 get_page_info，并检查 screenshot_page。将 files[].fileName 和 files[].contents 作为页面源文件。保留干净导出的默认设置；实现时不需要节点 ID 和编辑器元数据。页面导入路径遵循项目的导出设置，通常使用已配置的导入别名；请根据本地配置解析这些路径。

对于 Subframe 模式，缺少组件时使用 CLI sync，主题文件则使用 init：这些命令会直接将代码写入磁盘，不会经过上下文。只读取实现所需的本地组件 API。不要通过 get_component_info 获取已通过同步获得的组件代码。

按名称同步缺少的组件，例如 npx @subframe/cli@latest sync Button Alert。切勿自动重新同步已有组件；只有在用户要求更新设计时才刷新它们。避免例行运行 sync --all 或不带参数的 sync，这两种方式也会同步所有内容。指定名称的同步会包含依赖项；也要检查这些变更。

将页面代码转为应用代码

将实现放入应用的路由和布局结构中。沿用应用的外壳、路由和服务端／客户端约定。

• 将组件变体和属性类型与预期状态匹配。检查本地类型和现有用法，并映射到代码库模型中的等效 API。
• 通过已声明的属性或子元素填充插槽，并保留复合组件结构。围绕组件进行页面组合；不要为了插入内容而编辑生成的内部实现。
• 遵循本地的图标导入方式和属性类型。在 Subframe 模型中，使用 get_icon_info 创建缺失的、仅供页面使用的上传图标模块；不要为此同步整个库。在代码库模型中，使用应用的图标库和资源约定。
• 通过应用的资源管线解析图片 URL 和资源。保留裁剪方式、宽高比和有意义的替代文本，并确认资源可以加载。
• 将占位文案和重复的 JSX 替换为真实数据，并将列表项映射为带稳定键的元素。沿用现有的数据获取和格式化约定；对于不可用的数据，应明确指出，而不是臆造后端。

在 Subframe 模型中，不要改动生成的组件文件。将自定义组件逻辑放入 index.tsx，并在该封装文件中标记 // @subframe/sync-disable。保留生成的组件，以便进行视觉更新。手动合并对已禁用文件所做的更改。

实现交互行为

通过应用现有模式接入导航、表单、验证、选择、对话框，以及加载、空内容和错误状态。静态页面导出并不能确立运行时行为。

如果用户指出了用于说明预期行为的 Subframe 原型，只用 read_prototype_file 读取相关文件，并转译其中的行为；该原型是带有模拟数据的独立脚手架，不一定是要采用的代码。

对于动画或动效工作，先使用动效库的 search_motion_examples 和 get_motion_example 工具，并在从头构建动效前阅读 get_motion_guidance。

在应用中验证

使用宿主提供的 shell 和浏览器工具运行应用。在相同视口、主题、内容和状态下，与 screenshot_page 进行比较。检查页面下方的内容、响应式布局和交互，以及初始屏幕。修复差异后，运行相关的构建或检查。报告运行了哪些操作，以及未能完成哪些视觉或行为验证。

应用后续设计变更

对于 Subframe 模型中的更新，按名称重新同步受影响的组件。使用现有配置和禁用组件同步的设置，通过 init 刷新变更后的主题文件；单独同步不会刷新设计令牌。设计变更完成后，重新获取一次页面。在代码库模型中，将视觉差异转化为应用的组件和设计令牌。

如果有之前的导出版本，请与刷新后的导出版本比较；否则，与已实现的 JSX 和截图比较。检查导入、变体、插槽、布局类、资源和文案；查看本地组件的差异。

将变更区域合并到现有实现中，同时保留钩子、处理函数、状态、数据绑定和封装层自定义内容。不要用全新导出替换路由。重复进行视觉和行为验证。

说明画布与代码同步

CLI 通过 sync 将 Subframe 组件导入代码，并通过 init 导入主题文件。页面需要单独实现或复制；CLI sync 不会更新页面。本地编辑不会自动显示在画布上，画布编辑也不会自动更新已实现的页面。收到变更请求时，重新获取页面并进行合并。将代码导回 Subframe 是明确的设计或导入任务，并非持续的双向同步。