用途
remix-ui 用于构建 Remix 应用的 UI。当需要编写应用界面时使用该技能，它基于 Remix Component 作为页面、布局、交互和客户端行为背后的 UI 模型。
适用时机
- 创建或更新页面、布局和展示型组件
- 添加交互性、状态、事件处理或响应式 DOM 操作
- 使用 css(...)、style、refs、键盘辅助函数或按压辅助函数进行样式编写
- 添加或重构 clientEntry(...)、run(...)、frames 或 UI 导航
- 实现进入/退出/布局动画
- 使用 createMixin(...) 编写可复用 mixin
- 编写或更新面向 UI 的组件测试
主要实践规范
- 遵循两阶段组件形态：setup 只运行一次；返回的 render 函数在每次更新时运行。
- 将状态保存在 setup 作用域中，作为普通 JavaScript 变量，并显式调用 handle.update()。
- 优先使用 host-element mixins 而非旧式 host props：mix={[on(...)]}、mix={[css(...)]}、mix={[ref(...)]}、mix={[link(href, options)]}。
- 使用 addEventListeners(target, handle.signal, listeners) 处理全局监听器。
- 使用 queueTask(...) 处理渲染后的 DOM 工作、响应式副作用或对水合敏感的设置。
- 在文档或布局代码中保持显式的 <head>。
- 使用真实交互进行测试；当单元测试需要同步断言时使用 root.flush()。
参考文档
按需加载以下参考：
- ./references/component-model.md：用于组件形态、状态、handle 用法和全局监听器。
- ./references/mixins-styling-events.md：用于 host-element 事件、refs、样式和内置行为辅助函数。优先使用这些辅助函数，而不是自行重新实现键盘、按压、链接或动画行为。
- ./references/hydration-frames-navigation.md：用于 clientEntry、run、frames、SSR frame 上下文、导航 API 和显式 <head> 管理。
- ./references/testing-patterns.md：用于组件测试、root.flush() 和高价值测试启发式。
- ./references/animate-elements.md：当任务涉及进入/退出过渡、FLIP 重排序、共享布局切换或动画密集型交互时使用。
- ./references/create-mixins.md：在编写或审查可复用 mixin、涉及 createMixin(...)、使用 handle.addEventListener('insert' | 'remove', ...)，或推理 mixin 生命周期语义与类型流转时使用。
- packages/ui/docs：当本地参考不足、需要选择最相关的 Component 文档打开时，作为通用上游文档目录使用。