docs: define style preset UI-only behavior

RuoYi-Vue/docs/superpowers/specs/2026-07-03-style-preset-ui-only-design.md

@@ -0,0 +1,42 @@
+# 页面风格仅影响 UI 设计
+
+## 背景
+
+当前项目生成时，`stylePreset` 不只写入颜色、圆角、阴影等视觉 token，还会在 `PageCompositionService.applyStylePreset()` 中覆盖页面 `canvas`。这会导致用户选择“卡片门户”“高密后台”“分类浏览”后，页面布局从表格、卡片、分栏等结构之间切换。
+
+用户期望页面风格只影响 UI 观感，不影响页面布局。布局应继续由页面类型、字段语义、字段数量、图片字段、分类字段等业务特征自动判断。
+
+## 目标
+
+- `stylePreset` 可以影响视觉 token：颜色、强调色、背景、边框、文字色、圆角、阴影、内容宽度、密度等。
+- `stylePreset` 不再覆盖 `canvas`。
+- 同一组页面输入在不同风格下应得到同一个 `canvas`。
+- 生成结果仍保留 `layout.stylePreset`、`layout.styleTokens` 和 `composition.stylePreset`，方便模板渲染不同 UI 风格。
+
+## 非目标
+
+- 不移除前端页面上的“页面风格”选项。
+- 不改变页面设计器的组件能力。
+- 不改变自动布局算法本身。
+- 不重做模板视觉样式，只调整风格选择与布局选择的边界。
+
+## 设计
+
+`PageCompositionService` 仍先调用 `chooseLayout()` 生成布局决策。之后如果传入 `stylePresetCode`，只解析 preset 并写入布局 JSON 的视觉字段，不再调用会修改 `decision.canvas` 的覆盖逻辑。
+
+`PageStylePresetRegistry` 可以继续保留风格 token 和密度信息。和 canvas 相关的映射不再由页面组合服务消费；如果清理范围可控，可以删除 registry 内的 canvas 映射方法，避免未来误用。
+
+测试改为覆盖新的不变量：
+
+- 前台普通列表选择 `card_portal` 后，`canvas` 仍保持自动布局判断出的 `frontend-list-v1`，同时写入 `stylePreset=card_portal` 和 `styleTokens`。
+- 后台普通列表选择 `data_dense` 后，`canvas` 仍保持自动布局判断出的 `admin-list-v1`，同时写入 `stylePreset=data_dense`。
+- registry 测试聚焦 token、density、非法 code 回退，不再断言风格会返回某个 canvas。
+
+## 验证
+
+运行后端相关单元测试：
+
+- `PageCompositionServiceStylePresetTest`
+- `PageStylePresetRegistryTest`
+
+必要时补跑包含页面设计初始化的一键生成相关测试，确认 `stylePreset` 仍能从前端请求传到页面布局 JSON。