Merge branch 'master' into feat-mpx-skyline-adaptation

Author: wenwenhua

.agents/skills/mpx2rn/SKILL.md

@@ -40,6 +40,7 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展
 | [跨端输出 RN 脚本能力参考](./references/rn-script-reference.md) | 脚本部分跨端能力详情：构造选项、生命周期、实例方法/属性、组合式 API、运行时导出、状态管理 |
 | [跨端输出 RN 样式能力参考](./references/rn-style-reference.md) | 样式部分跨端能力详情：选择器、单位、颜色、文本继承、CSS 变量、媒体查询、动画、背景图与逐项样式属性支持情况 |
 | [跨端输出 RN 样式开发最佳实践](./references/rn-style-practice.md) | 常用选择器与样式属性的跨端兼容方案，遇到 RN 不支持或表现不一致的样式写法时优先查阅 |
+| [Mpx2RN 原子 CSS 能力参考](./references/rn-atomic-css.md) | 基于 UnoCSS 的 RN 原子类接入、工具类、variants、directives 与 variant groups 支持范围、颜色透明度约束及编译排查；项目启用原子类或任务涉及 utility class 时读取 |
 | [跨端输出 RN 环境 API 参考](./references/rn-api-reference.md) | `@mpxjs/api-proxy` 提供的环境 API 跨端支持情况，涉及网络、存储、界面、设备、媒体、位置等 |
 | [跨端输出 RN JSON 配置参考](./references/rn-json-reference.md) | 应用、页面、组件三层 JSON 配置在 RN 平台的支持范围与差异 |
 | [Mpx 与 RN 混合开发](./references/rn-hybrid-dev.md) | 在 `.mpx` 内直接使用 React Native 组件、Hooks 的方式与跨端隔离方案 |
@@ -54,6 +55,7 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展
    - 已有组件 RN 跨端适配改造：识别问题维度后再读对应能力参考的相关小节，通常 1–2 份足够（如样式改造主要查 `rn-style-practice.md`）。
    - 新建 RN 跨端兼容组件：先按本 SKILL.md 的通用约束起手，遇到能力存疑（某属性是否支持、某 API 是否存在）时再点查对应参考。
    - 排查特定编译报错：直接定位到报错维度的能力参考相关小节。
+   - 使用或排查原子类：读取 `rn-atomic-css.md`；仅需核对底层样式属性时再补读 `rn-style-reference.md`，不要预读全部样式参考。
 4. **何时读取 `single-file-component.md`**：仅当不熟悉 Mpx SFC 基本结构时读取；已熟悉 SFC 写法可跳过。
 
 ## 通用约束与适配原则
@@ -94,6 +96,7 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展
    - **Bad Example**: `.list .item { color: red; }`
    - **Good Example**: `.list-item { color: red; }`
    - **注意**：用逗号分隔的并列形式（如 `.classA, .classB { ... }`）等价于多条单类选择器规则共享同一样式块，仍属于**单类选择器**范畴，无需拆分或合并为新单类，可直接使用。
+   - **UnoCSS 例外**：原子类的 `hover:` variant 由编译器转换为组件 hover style，不等同于在 `<style>` 中编写 `.button:hover`；普通 CSS 伪类仍不支持。
 3. **优先使用模板指令进行动态样式绑定**：使用 `wx:class` / `wx:style` 指令，避免在 `class` / `style` 属性内拼接 `{{}}` 插值表达式。
    - **Bad Example**: `<view class="item {{isActive ? 'active' : ''}}">`
    - **Good Example**: `<view class="item" wx:class="{{ {active: isActive} }}">`
@@ -112,6 +115,7 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展
      - 1rpx 极细线：原平台保留 `1rpx` 边框写法（用样式条件编译），RN 侧用 `hairlineWidth` 等效
 
 5. **保留单位注释**：保留原始样式中的 `/*use rpx*/` 与 `/*use px*/` 注释，编译期会据此批量切换样式单位。
+6. **原子 CSS**：项目启用 UnoCSS 或模板使用原子类时，读取 [Mpx2RN 原子 CSS 能力参考](./references/rn-atomic-css.md)。只使用 RN preset 与 Mpx2RN 样式编译器共同支持的工具类和 variants；不支持项会作为编译错误且不会进入产物。颜色透明度统一使用 `bg-red-500/50` 等斜杠 alpha 语法，不要使用 `bg-red-500 bg-opacity-50` 等独立 opacity 组合。
 
 ### JSON 配置约束
 
@@ -179,7 +183,8 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展
      ```
 2. **选择器适配改造**：读取 [样式开发最佳实践 · 选择器使用建议](./references/rn-style-practice.md#选择器使用建议)，将 RN 不支持的选择器改造为跨端兼容的单类等效实现，并同步更新 `<template>` 与 `<script>` 中的类名引用。
 3. **样式属性适配改造**：读取 [样式能力参考](./references/rn-style-reference.md) 检查 `<style>`、`<template>`、`<script>` 中所有出现的样式属性的 RN 支持情况；读取 [样式开发最佳实践](./references/rn-style-practice.md) 改造为跨端兼容的等效实现。
-4. **不可兼容部分使用条件编译**：对无法跨端等效实现的选择器或样式属性，使用 [样式条件编译](./references/conditional-compile.md#样式条件编译) 对**整条规则**进行最小包裹，保留在原平台输出产物中，添加 `todo` 注释记录差异原因。
+4. **原子类适配改造**：项目已启用 UnoCSS 时，读取 [Mpx2RN 原子 CSS 能力参考](./references/rn-atomic-css.md)，检查模板中的工具类、variants、动态类提取与颜色透明度写法；将 RN 不支持的工具类改为支持的原子类组合或普通跨端样式。
+5. **不可兼容部分使用条件编译**：对无法跨端等效实现的选择器、样式属性或原子类，使用 [样式条件编译](./references/conditional-compile.md#样式条件编译) 对**整条规则**进行最小包裹，保留在原平台输出产物中，添加 `todo` 注释记录差异原因。
    - **Good Example (整条规则一并条件编译，避免空选择器)**:
      ```css
      /* @mpx-if (__mpx_mode__ === 'wx' || __mpx_mode__ === 'ali' || __mpx_mode__ === 'web') */
@@ -217,6 +222,7 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展
 **样式（style）**
 - [ ] `<style>` 中不存在嵌套选择器写法。
 - [ ] `<style>`、`<template>`、`<script>` 中使用的选择器和样式属性均在 [样式能力参考](./references/rn-style-reference.md) 标注为 RN 支持，或已通过样式条件编译进行平台隔离。
+- [ ] 项目启用 UnoCSS 时，模板中的工具类与 variants 均在 [原子 CSS 能力参考](./references/rn-atomic-css.md) 标注的 RN 支持范围内；动态类可被静态提取或已加入 `safelist`；颜色透明度未使用独立 `*-opacity-*` 组合。
 - [ ] `/*use rpx*/` / `/*use px*/` 单位注释已保留。
 
 **JSON 配置**
@@ -258,7 +264,7 @@ Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展
 - **`<script>`**：读取 [逻辑能力参考](./references/rn-script-reference.md) 与 [环境 API 参考](./references/rn-api-reference.md)，仅使用 RN 支持的生命周期、构造选项与 API；统一通过 `mpx.xxx` 调用环境能力。
   - **优先使用组合式 API**：新建组件优先使用 `<script setup>` 风格的组合式 API 编写逻辑，生命周期须在 `<script setup>` 顶层同步注册，详见 [逻辑能力参考 · 组合式 API](./references/rn-script-reference.md#组合式-api)。
   - **状态管理优先使用 `@mpxjs/pinia`**：新项目、新状态域或与组合式 API 协同时，使用 `@mpxjs/pinia`（Pinia 风格）；仅当工程已深度使用 `@mpxjs/store`（Vuex 风格）时继续维护沿用，避免同一业务域两套方案并存。详见 [逻辑能力参考 · 状态管理](./references/rn-script-reference.md#状态管理)。
-- **`<style>`**：读取 [样式能力参考](./references/rn-style-reference.md) 与 [样式开发最佳实践](./references/rn-style-practice.md)，从一开始就使用单类选择器、Flex 布局、`rpx` 单位、`hover-class` 等跨端兼容写法。
+- **`<style>`**：读取 [样式能力参考](./references/rn-style-reference.md) 与 [样式开发最佳实践](./references/rn-style-practice.md)，从一开始就使用单类选择器、Flex 布局、`rpx` 单位、`hover-class` 等跨端兼容写法；项目启用 UnoCSS 时再读取 [Mpx2RN 原子 CSS 能力参考](./references/rn-atomic-css.md)，只使用 RN 支持的工具类与 variants。
 - **JSON 配置**：读取 [JSON 配置参考](./references/rn-json-reference.md)，仅使用 RN 支持的字段；当需要分平台注册组件或差异化配置时，使用 `<script name="json">` 形式动态生成。
 
 #### 3. 编译校验