@microi.net/cli 4.9.6 → 4.9.7

package/skills/ui-design/references/progressive-04-/347/273/204/344/273/266/351/243/216/346/240/274/351/200/237/346/237/245.md

@@ -0,0 +1,152 @@
+# ui-design 详细参考 4
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=ui-design-014 sha256=abc0a2e1f26a1cfbfa5d73399e09479b7b71314a727bec8b0bf4258a5a3733dc -->
+## 组件风格速查
+
+### 卡片（通用）
+
+```scss
+.mci-card {
+  background: var(--mci-bg-card);
+  border: 1px solid var(--mci-border-color);
+  border-radius: var(--mci-radius-xl);
+  padding: var(--mci-space-6);
+  box-shadow: var(--mci-shadow-card);
+}
+```
+
+### 渐变按钮（主要操作）
+
+```scss
+.mci-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--mci-space-2);
+  min-height: var(--mci-touch-target);
+  padding: 0 var(--mci-space-6);
+  background: var(--mci-gradient-primary);
+  color: var(--mci-text-on-primary);
+  border: none;
+  border-radius: var(--mci-radius-md);
+  font-size: var(--mci-text-base);
+  font-weight: var(--mci-font-semibold);
+  cursor: pointer;
+  box-shadow: var(--mci-shadow-button);
+  transition: transform var(--mci-duration-fast) var(--mci-ease-out);
+
+  &:active { transform: scale(0.97); }
+  @media (hover: hover) {
+    &:hover { transform: translateY(-2px); box-shadow: var(--mci-shadow-button-hover); }
+  }
+
+  &--outline {
+    background: transparent;
+    color: var(--mci-color-primary-light);
+    border: 1.5px solid var(--mci-color-primary);
+    box-shadow: none;
+  }
+
+  &--ghost {
+    background: var(--mci-bg-card);
+    color: var(--mci-text-primary);
+    box-shadow: none;
+  }
+}
+```
+
+### 标签 / Badge
+
+```scss
+.mci-tag {
+  display: inline-flex;
+  align-items: center;
+  padding: 4px 10px;
+  border-radius: var(--mci-radius-full);
+  font-size: var(--mci-text-xs);
+  font-weight: var(--mci-font-medium);
+
+  &--hot {
+    background: linear-gradient(135deg, rgba(255,46,99,0.15), rgba(255,110,199,0.15));
+    color: var(--mci-color-accent-red);
+    border: 1px solid rgba(255, 46, 99, 0.2);
+  }
+  &--new {
+    background: linear-gradient(135deg, rgba(0,245,212,0.1), rgba(41,184,255,0.1));
+    color: var(--mci-color-accent-cyan);
+    border: 1px solid rgba(0, 245, 212, 0.2);
+  }
+  &--vip {
+    background: var(--mci-gradient-gold);
+    color: #1A1A2E;
+    font-weight: var(--mci-font-bold);
+  }
+}
+```
+
+### 输入框
+
+```scss
+.mci-input {
+  display: block;
+  width: 100%;
+  min-height: var(--mci-touch-target);
+  background: var(--mci-bg-surface);
+  border: 1px solid var(--mci-border-color);
+  border-radius: var(--mci-radius-md);
+  padding: 0 var(--mci-space-4);
+  color: var(--mci-text-primary);
+  font-size: var(--mci-text-base);
+  transition: border-color var(--mci-duration-fast) var(--mci-ease-out),
+              box-shadow var(--mci-duration-fast) var(--mci-ease-out);
+
+  &:focus {
+    border-color: var(--mci-color-primary);
+    box-shadow: 0 0 0 3px var(--mci-color-primary-glow);
+    outline: none;
+  }
+  &::placeholder { color: var(--mci-text-tertiary); }
+}
+```
+
+### Element Plus 主题整合（PC）
+
+```scss
+:root {
+  --el-color-primary: var(--mci-color-primary);
+  --el-color-success: var(--mci-color-success);
+  --el-color-warning: var(--mci-color-warning);
+  --el-color-danger: var(--mci-color-danger);
+  --el-color-info: var(--mci-color-info);
+
+  --el-bg-color: var(--mci-bg-elevated);
+  --el-bg-color-overlay: var(--mci-bg-surface);
+  --el-text-color-primary: var(--mci-text-primary);
+  --el-text-color-regular: var(--mci-text-secondary);
+  --el-text-color-secondary: var(--mci-text-tertiary);
+  --el-text-color-placeholder: var(--mci-text-disabled);
+
+  --el-border-color: var(--mci-border-color);
+  --el-border-color-light: var(--mci-border-color);
+  --el-border-color-lighter: var(--mci-border-color);
+  --el-border-radius-base: var(--mci-radius-md);
+
+  --el-box-shadow: var(--mci-shadow-md);
+  --el-box-shadow-light: var(--mci-shadow-sm);
+  --el-font-family: var(--mci-font-family);
+}
+
+.el-dialog {
+  border-radius: var(--mci-radius-2xl) !important;
+  background: var(--mci-bg-elevated) !important;
+  box-shadow: var(--mci-shadow-dialog) !important;
+  border: 1px solid var(--mci-border-color) !important;
+  overflow: hidden;
+}
+```
+
+---
+
+<!-- /microi-progressive:chunk -->

package/skills/ui-design/references/progressive-05-/347/247/273/345/212/250/347/253/257/344/270/223/347/224/250/350/247/204/350/214/203.md

@@ -0,0 +1,238 @@
+# ui-design 详细参考 5
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=ui-design-015 sha256=18e252a8b3e87b6522a9f434e7332afc9be1a5ab0797d7bd9e5d639bdcc9d240 -->
+## 移动端专用规范
+
+### 1. 视口设置
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no, viewport-fit=cover">
+```
+
+### 2. 状态栏 / 安全区适配
+
+移动端页面必须同时考虑 iPhone 刘海屏/Dynamic Island/Home Indicator、Android 状态栏/虚拟导航栏/手势条、不同 WebView 容器和横竖屏差异。不要用固定像素硬顶或硬底来“凑”安全区。
+
+```scss
+.mci-mobile-page {
+  min-height: 100vh;
+  padding-top: var(--mci-safe-top);
+  padding-bottom: var(--mci-safe-bottom);
+  padding-left: var(--mci-safe-left);
+  padding-right: var(--mci-safe-right);
+  background: var(--mci-bg-base);
+  background-image: var(--mci-gradient-bg);
+}
+```
+
+落地要求：
+
+- HTML/H5 必须设置 `viewport-fit=cover`，否则 iOS 的 `env(safe-area-inset-*)` 不会按预期生效。
+- uni-app 页面需要结合 `uni.getSystemInfoSync().statusBarHeight` 或平台导航栏高度，状态栏高度用于占位，内容安全边距仍使用 `env(safe-area-inset-*)` 兜底。
+- 微信小程序中 `env()` 可能返回 `0`，不得把它作为唯一安全区来源；优先读取 `uni.getWindowInfo()` 并把真实值注入页面壳变量。
+- 自定义导航必须读取微信胶囊矩形并预留右侧空间，任何标题、登录、分享或状态按钮都不能与胶囊区域重叠。
+- 全屏弹层、沉浸式工作台和独立工具页同样属于自定义导航场景。右侧存在两个以上操作按钮且无法在胶囊左侧完整容纳时，必须把整组标题与操作区放到 `capsule.top + capsule.height` 下方，禁止把关闭、新建、历史等按钮塞到胶囊背后。
+- 顶部 fixed/sticky 导航使用 `padding-top: max(var(--mci-safe-top), statusBarHeight)` 的等价实现；返回按钮触摸区域要随顶部安全区整体下移。
+- 底部 fixed 操作栏和 tabBar 使用 `padding-bottom: calc(var(--mci-safe-bottom) + 8px)` 或项目等价间距，页面主体同步预留底部高度，避免按钮遮挡列表最后一项。
+- 多层页面必须定义返回优先级：先关闭键盘/确认框，再关闭抽屉/筛选层，再退出全屏工具页，最后才返回底层业务路由。需要支持手机侧滑返回的全屏功能优先实现为独立路由，不能只做覆盖当前页的普通 `fixed` 蒙层。
+- 安卓三键导航、手势导航和 iOS Safari/PWA/WebView 都要截图验收；不能只在 PC 模拟器或单一 iPhone 尺寸上看起来正常。
+
+### 3. 底部 TabBar
+
+```scss
+.mci-tabbar {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  display: flex;
+  background: var(--mci-bg-elevated);
+  border-top: 1px solid var(--mci-border-color);
+  box-shadow: 0 -4px 20px rgba(0, 0, 0, 0.3);
+  padding-bottom: var(--mci-safe-bottom);
+  z-index: 100;
+}
+
+.mci-tabbar__item {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  min-height: var(--mci-touch-target);
+  padding: 8px 0;
+  color: var(--mci-text-tertiary);
+  font-size: var(--mci-text-xs);
+  transition: color var(--mci-duration-fast) var(--mci-ease-out);
+
+  &--active {
+    color: var(--mci-color-primary-light);
+  }
+  &:active {
+    transform: scale(0.92);
+  }
+}
+```
+
+### 4. 顶部导航栏
+
+```scss
+.mci-navbar {
+  position: sticky;
+  top: 0;
+  z-index: 50;
+  display: flex;
+  align-items: center;
+  height: 48px;
+  padding: 0 var(--mci-space-4);
+  padding-top: var(--mci-safe-top);
+  background: var(--mci-bg-elevated);
+  box-shadow: var(--mci-shadow-sm);
+}
+
+.mci-navbar__title {
+  flex: 1;
+  text-align: center;
+  font-size: var(--mci-text-lg);
+  font-weight: var(--mci-font-semibold);
+  color: var(--mci-text-primary);
+}
+```
+
+### 5. 列表项（cell）
+
+```scss
+.mci-cell {
+  display: flex;
+  align-items: center;
+  min-height: 56px;
+  padding: var(--mci-space-3) var(--mci-space-4);
+  background: var(--mci-bg-card);
+  border-bottom: 1px solid var(--mci-border-color);
+  transition: background var(--mci-duration-fast) var(--mci-ease-out);
+
+  &:active { background: var(--mci-bg-card-hover); }
+
+  &__title { flex: 1; color: var(--mci-text-primary); }
+  &__value { color: var(--mci-text-secondary); margin-right: var(--mci-space-2); }
+  &__arrow {
+    color: var(--mci-text-tertiary);
+    transition: transform var(--mci-duration-base) var(--mci-ease-out);
+  }
+}
+```
+
+### 6. 移动端禁用项清单
+
+- ❌ `:hover` 单独使用（用 `@media (hover: hover)` 包裹）
+- ❌ 大面积 `backdrop-filter: blur()`
+- ❌ JS 随机装饰点（Canvas/WebGL）
+- ❌ 实时阴影动画
+- ❌ 复杂的 `filter` 动画（`blur`, `drop-shadow` 不要在动画中切换）
+- ❌ 自动播放视频背景
+
+---
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-016 sha256=2c997040cef24fb5e8b6f2faab6d354473d4a962560fdaffd13f11294eb4cf1f -->
+## 装饰性背景（低性能消耗方案）
+
+### 结构化背景
+
+Microi 背景必须服务内容层级，不能喧宾夺主。优先使用网格、细线、低透明纹理、扫光和内容相关图片；不要使用离散光球、模糊色块堆叠、密集散点噪声作为主要视觉。
+
+```scss
+.mci-page-bg {
+  position: fixed;
+  inset: 0;
+  z-index: -1;
+  overflow: hidden;
+  pointer-events: none;
+  background:
+    linear-gradient(135deg, rgba(181,18,32,.06), transparent 32%),
+    linear-gradient(180deg, var(--mci-bg-base), var(--mci-bg-page));
+}
+
+.mci-page-bg::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background-image:
+    linear-gradient(rgba(31,41,55,.06) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(31,41,55,.06) 1px, transparent 1px);
+  background-size: 56px 56px;
+  mask-image: linear-gradient(180deg, rgba(0,0,0,.75), transparent 78%);
+}
+
+.mci-page-bg::after {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: -30%;
+  width: 38%;
+  height: 100%;
+  background: linear-gradient(90deg, transparent, rgba(255,255,255,.20), transparent);
+  transform: skewX(-18deg);
+  animation: mciBackgroundSweep 8s ease-in-out infinite;
+}
+
+@keyframes mciBackgroundSweep {
+  0%, 18% { transform: translateX(0) skewX(-18deg); opacity: 0; }
+  30% { opacity: .72; }
+  54%, 100% { transform: translateX(360%) skewX(-18deg); opacity: 0; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .mci-page-bg::after { animation: none; }
+}
+```
+
+### 背景层级排查
+
+- 装饰背景必须 `pointer-events:none` 且位于内容下方。全屏 `position:fixed` 背景如果 `z-index >= 0`，会覆盖无 z-index 的普通文字。
+- 如果标题/副标题发灰、按钮文字却正常，先临时隐藏背景层验证，不要只改文字颜色。
+- 推荐修复方式：背景 `z-index:-1`；页面根容器 `position:relative`；所有内容区域保持正常堆叠上下文。
+
+### 网格背景
+
+```scss
+.mci-grid-bg {
+  background-image:
+    linear-gradient(var(--mci-border-color) 1px, transparent 1px),
+    linear-gradient(90deg, var(--mci-border-color) 1px, transparent 1px);
+  background-size: 60px 60px;
+}
+```
+
+---
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-017 sha256=dfd5e3fe5ccef15772d0687dc031ce302cc9b2277e06f5c6dd0ad7113343f540 -->
+## 性能检查清单
+
+- [ ] 动画只使用 `transform` / `opacity`
+- [ ] `box-shadow` 变化用伪元素 opacity 切换
+- [ ] `backdrop-filter` 仅用于小面积元素，移动端有降级
+- [ ] `will-change` 未在静态元素上使用
+- [ ] 装饰性动画使用 CSS 而非 JS
+- [ ] 列表渲染使用虚拟滚动（超过 50 项时）
+- [ ] 图片使用 `loading="lazy"`
+- [ ] 复杂动画帧率 > 30fps
+- [ ] 提供 `prefers-reduced-motion` 无动画回退
+- [ ] 移动端：`:hover` 用 `@media (hover: hover)` 包裹
+- [ ] 移动端：所有可点击元素 ≥ 44×44px
+- [ ] 移动端：背景装饰不使用密集随机点或大面积模糊色块
+- [ ] 动态数据页：首屏使用骨架屏，不用 spinner/“加载中”文案代替
+- [ ] 移动端：使用 `env(safe-area-inset-*)` 适配安全区，顶部/底部 fixed 区域在 iOS 与 Android 均不遮挡内容
+- [ ] 官网/网站首页：导航栏背景、文字、搜索框与首屏背景截图检查，不能出现浅灰导航压在深色英雄区上导致不协调
+- [ ] 官网/网站首页：所有主按钮、胶囊按钮截图检查文字上下居中，长文字按钮不截断、不贴边、不漂移
+- [ ] 官网/网站首页：产品卡、助手卡、价格卡等展示卡与页面主背景一致，不能出现孤立的灰白卡片破坏整体视觉
+- [ ] 全自动化测试：涉及 UI/前端改动时必须生成并检查截图，覆盖关键按钮/胶囊按钮的上下左右居中、空态/未登录态、代表性卡片、安全区和底部栏；构建通过不等于视觉通过
+- [ ] 提示与确认：源码不存在原生 `alert/confirm/prompt`；长弹窗滚到顶部、中部、底部时，错误提示和确认层都在当前视口正中央且不被宿主遮挡
+- [ ] 组件复用：同类结构出现两处及以上时必须抽成 `Mci*` 或项目级 `mci-*` 组件，业务页只传文案、图标、状态、动作和少量变体
+
+---
+
+<!-- /microi-progressive:chunk -->

package/skills/ui-design/references/progressive-06-/344/270/273/351/242/230/345/210/207/346/215/242/345/256/236/347/216/260.md

@@ -0,0 +1,194 @@
+# ui-design 详细参考 6
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=ui-design-018 sha256=c83c67d0a4520a52e8933e5b8785fe3a725e1b47b675cf1f5aa945187c9cfd2c -->
+## 主题切换实现
+
+### 首选：Microi.UI 运行时
+
+```js
+import { initMciDesign, setMciPalette, setMciShape, setMciTheme } from '@microi/mci-ui/runtime';
+
+initMciDesign({
+  theme: 'light',     // light | dark
+  palette: 'red',     // black | white | red | orange | yellow | green | cyan | blue | purple
+  shape: 'rounded',   // rounded | flat
+  motion: 'full'      // full | reduced
+});
+
+setMciPalette('blue');
+setMciShape('flat');
+setMciTheme('dark');
+```
+
+业务页面只允许调用运行时或项目级主题服务，不要在页面里散写 `document.documentElement.setAttribute(...)`。
+
+### 原生 Web 降级实现
+
+```js
+const PALETTES = ['black','white','red','orange','yellow','green','cyan','blue','purple'];
+function setTheme(theme) {
+  document.documentElement.setAttribute('data-theme', theme);
+  try { localStorage.setItem('mci-theme', theme); } catch(e) {}
+}
+function setPalette(palette) {
+  const next = PALETTES.includes(palette) ? palette : 'red';
+  document.documentElement.setAttribute('data-mci-palette', next);
+  try { localStorage.setItem('mci-palette', next); } catch(e) {}
+}
+
+const saved = (() => { try { return localStorage.getItem('mci-theme'); } catch(e) { return null; } })();
+const savedPalette = (() => { try { return localStorage.getItem('mci-palette'); } catch(e) { return null; } })();
+const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+// 默认亮色多彩主题，仅当系统明确设置为深色或用户主动选择深色时启用 dark
+setTheme(saved || (prefersDark ? 'dark' : 'light'));
+setPalette(savedPalette || 'red');
+
+// 监听系统主题变化
+window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', e => {
+  if (!localStorage.getItem('mci-theme')) setTheme(e.matches ? 'dark' : 'light');
+});
+```
+
+### uni-app（H5/小程序通用）主题切换
+
+uni-app 中没有 `document` 对象（小程序端），所以推荐两套方案并存：
+
+**方案A · H5 只操作 html/body 安全外壳**
+
+H5 端只能把主题状态写到 `html`、`body` 的 `data-*` 属性、主题 class 和 CSS 变量，再让 `uni-page-body`、页面根和 fixed 组件通过变量继承。不要用 `querySelectorAll('.mci-page')`、`MutationObserver`、定时扫描或“延迟补 class”去修改 `.mci-page`、`uni-page-body`、`uni-page`、`RouterView` 下的节点，这些节点由 Vue/uni-app 管理，切主题后导航时可能触发 `Cannot assign to read only property '_'`、`Cannot read properties of null (reading 'type')`、`parentNode`、`scheduler flush` 等错误。
+
+```scss
+/* 在 mci-design.scss 加暗色定义 */
+html.theme-dark,
+body.theme-dark,
+html.theme-dark uni-page-body,
+body.theme-dark uni-page-body,
+page.theme-dark,
+.theme-dark {
+  --mci-color-primary: #8B5CF6;
+  --mci-bg-base: #0B0B1F;
+  --mci-bg-card: rgba(28, 28, 60, 0.85);
+  --mci-text-primary: #F5F5FF;
+  --mci-text-secondary: #B8B8D8;
+  --mci-border-color: rgba(255, 255, 255, 0.08);
+  --mci-shadow-md: 0 8rpx 24rpx rgba(0, 0, 0, 0.5);
+}
+@media (prefers-color-scheme: dark) {
+  page.theme-auto, :root.theme-auto {
+    /* 同上，跟随系统 */
+  }
+}
+```
+
+```js
+// utils/theme.js（无 Microi.UI 运行时时的降级写法）
+const THEME_KEY = 'mci_theme';
+const PALETTE_KEY = 'mci_palette';
+const PALETTES = ['black','white','red','orange','yellow','green','cyan','blue','purple'];
+function applyClass(theme) {
+  if (typeof document !== 'undefined' && document.documentElement) {
+    [document.documentElement, document.body].forEach(function(el) {
+      if (!el) return;
+      el.classList.remove('theme-light', 'theme-dark', 'theme-auto');
+      el.classList.add('theme-' + theme);
+      el.setAttribute('data-mci-theme', theme);
+    });
+  }
+}
+function applyPalette(palette) {
+  if (typeof document !== 'undefined' && document.documentElement) {
+    document.documentElement.setAttribute('data-mci-palette', palette);
+  }
+}
+export function getTheme() { try { return uni.getStorageSync(THEME_KEY) || 'light'; } catch (e) { return 'light'; } }
+export function getPalette() { try { return uni.getStorageSync(PALETTE_KEY) || 'red'; } catch (e) { return 'red'; } }
+export function setTheme(theme) {
+  if (!['light','dark','auto'].includes(theme)) theme = 'light';
+  try { uni.setStorageSync(THEME_KEY, theme); } catch(e) {}
+  applyClass(theme); return theme;
+}
+export function setPalette(palette) {
+  if (!PALETTES.includes(palette)) palette = 'red';
+  try { uni.setStorageSync(PALETTE_KEY, palette); } catch(e) {}
+  applyPalette(palette); return palette;
+}
+export function toggleTheme() { return setTheme(getTheme() === 'dark' ? 'light' : 'dark'); }
+export function initTheme() { applyClass(getTheme()); applyPalette(getPalette()); }
+```
+
+```vue
+// App.vue
+<script>
+import { initTheme } from '@/utils/theme.js';
+export default { onLaunch() { initTheme(); } };
+</script>
+```
+
+```vue
+// 页面里加切换按钮
+<button @click="toggle">切换主题</button>
+<script setup>
+import { toggleTheme, getTheme } from '@/utils/theme.js';
+const cur = ref(getTheme());
+function toggle() { cur.value = toggleTheme(); uni.showToast({ title: '已切换为' + (cur.value==='dark'?'暗色':'亮色') }); }
+</script>
+```
+
+**方案B · 小程序端通过 `<page-meta>` + `root-font-size`**（如需小程序原生暗色，否则推荐 wx 的 `themeChange` 事件）
+
+```vue
+<template>
+  <page-meta :root-class="themeClass">
+    <view class="content">...</view>
+  </page-meta>
+</template>
+```
+
+### 主题切换 UI 入口规范
+
+- 入口位置：「我的」页面服务菜单 / 顶部状态栏图标 / 设置页第一项
+- 形式：明暗模式用图标 + 文案（暗色 / 亮色 / 跟随系统），主色用色板按钮（黑、白、红、橙、黄、绿、青、蓝、紫），点击后立即生效，弹 Toast 反馈。
+- 色板必须有选中态、无障碍名称和足够触摸面积；白色色板必须有边框，黄色色板文字必须深色。
+- 切换后立刻持久化（uni.setStorageSync），下次启动 App 在 `onLaunch` 自动 `initTheme()` 应用
+- H5 fixed 底部导航、固定提交栏和悬浮操作条优先吃 `--mci-*` CSS 变量，不要在主题切换时让组件自己订阅 store 后动态切换根 class。若切主题后点击导航报 Vue scheduler、`parentNode`、`read only property '_'` 或 `null (reading 'type')`，说明主题实现改动了 Vue/uni 托管节点，必须改为 html/body 变量方案。
+- 骨架屏、加载过渡、报告详情、英文小标题、印章/水印、状态胶囊、摘要卡和富文本容器也属于主题范围。每个主题切换后都要重新触发 loading 态并打开至少一个详情页截图，不能只看首页。
+
+### 主题颜色变量必须用 var(--mci-*) 而非硬编码
+
+设计页面时所有颜色、阴影、边框 **强制用变量**，否则切到暗色后只换底色不换文字，会出现"白底白字"。常见违规：
+
+```scss
+/* ❌ 错误 */
+.card { background: #fff; color: #333; box-shadow: 0 8rpx 20rpx rgba(0,0,0,0.05); }
+
+/* ✅ 正确 */
+.card {
+  background: var(--mci-bg-card);
+  color: var(--mci-text-primary);
+  box-shadow: var(--mci-shadow-md);
+}
+```
+
+### 渐变色处理
+
+渐变色在暗色下需要重新调色（亮色用 #FF8A5C → 暗色 #B14CA0 之类），定义 `--mci-gradient-*` 变量并在 `.theme-dark` 下覆盖。
+
+---
+
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-019 sha256=535f58f5173e164ebe23480d3a65ce894fcf0aab65dddc209dabd86c939cf9b6 -->
+## 命名规范
+
+- CSS 变量前缀：`--mci-`
+- 组件类名前缀：`.mci-`
+- 动画 keyframe 前缀：`mci`（如 `mciFadeUp`、`mciNeonPulse`）
+- Vue Transition name 前缀：`mci-`
+- 修饰符使用 BEM：`.mci-card--active`、`.mci-btn--outline`
+- JS 全局变量前缀：`MCI_`（如 `MCI_THEME`）
+
+---
+
+<!-- /microi-progressive:chunk -->