guanghulab/style-system/UI-SKIN-SPEC.md

🎨 UI 皮肤部署规范 · Notion → 铸渊 桥接协议

版本: v1.0
签发: 铸渊 · ICE-GL-ZY001
适用域名: guanghuyaoming.com
版权: 国作登字-2026-A-00037559

---

📌 核心原则：壳-核分离

┌──────────────────────────────────────────┐
│              UI 皮肤层（壳）              │  ← 霜砚/Notion 侧可修改
│   颜色 · 字体 · 边框 · 布局间距 · 文字   │
├──────────────────────────────────────────┤
│            技术功能层（核）               │  ← 仅铸渊/铸渊Agent可修改
│   路由 · API · 鉴权 · 数据库 · 业务逻辑  │
└──────────────────────────────────────────┘

皮肤层 = 可以改的：CSS 变量、文字内容、布局样式、图标、背景
功能层 = 不能改的：HTML 结构中的 id、class（功能性的）、onclick、<script> 标签、API 路由、后端代码

---

🔧 如何写 UI 皮肤代码

格式：JSON 皮肤包

每次提交一个 UI 皮肤变更，请按以下格式写一个 JSON 文件：

{
  "skin_id": "SKIN-20260417-001",
  "author": "霜砚",
  "target": "homepage",
  "description": "首页 Hero 区文字和配色调整",
  "created_at": "2026-04-17T12:00:00+08:00",
  
  "css_overrides": {
    ":root": {
      "--bg-primary": "#0a0c14",
      "--accent": "#3b82f6",
      "--consciousness": "#10b981"
    },
    ".hero-title": {
      "font-size": "3.5rem",
      "background": "linear-gradient(135deg, #fff, #60a5fa)"
    },
    ".hero-description": {
      "color": "#94a3b8"
    }
  },
  
  "text_overrides": {
    ".hero-title": "光之湖",
    ".hero-subtitle": "HoloLake · 冰朔的零点原核",
    ".hero-description": "探索未来之域 · 语言与意识的交汇处",
    ".hero-btn": "进入光湖"
  },
  
  "class_additions": {
    ".hero": "custom-hero-glow"
  },
  
  "custom_css": ".custom-hero-glow { box-shadow: 0 0 80px rgba(59, 130, 246, 0.15); }"
}

字段说明

字段	必填	说明
skin_id	✅	格式: SKIN-YYYYMMDD-NNN
author	✅	谁写的（霜砚/其他人格体名）
target	✅	目标页面：homepage / chat / dashboard / login
description	✅	这次改了什么
css_overrides	❌	CSS 选择器 → 样式对象（仅修改样式，不改结构）
text_overrides	❌	CSS 选择器 → 新文字内容（纯文本，不含 HTML 标签）
class_additions	❌	CSS 选择器 → 要添加的 CSS class 名
custom_css	❌	额外的自定义 CSS（不能包含 <script> 或 JS）

---

🎯 可修改的目标页面

target 值	页面	静态文件路径
homepage	首页	/opt/zhuyuan/sites/yaoming/homepage/
chat	对话界面	/opt/zhuyuan/sites/yaoming/persona-studio/frontend/chat.html
dashboard	仪表板	/opt/zhuyuan/sites/yaoming/dashboard/
login	登录页	/opt/zhuyuan/sites/yaoming/persona-studio/frontend/index.html

---

🚀 部署流程

方式一：冰朔手动复制（推荐初期）

1. 霜砚在 Notion 中编写 UI 皮肤 JSON
2. 冰朔复制 JSON 内容
3. 通过腾讯云在线终端登录服务器
4. 执行命令：

# 将 JSON 保存到皮肤收件箱
cat > /opt/zhuyuan/sites/yaoming/style-system/skins/inbox/SKIN-20260417-001.json << 'EOF'
{
  "skin_id": "SKIN-20260417-001",
  ... 粘贴 JSON 内容 ...
}
EOF

# 执行皮肤部署（铸渊 Agent 自动验证 + 应用）
node /opt/zhuyuan/sites/yaoming/style-system/apply-skin.js SKIN-20260417-001.json

方式二：自动化桥接（后续开发）

提交皮肤 JSON 到 GitHub 仓库的 style-system/skins/inbox/ 目录：

• 铸渊 Agent 自动检测新皮肤文件
• 验证安全性（不含脚本注入、不破坏功能层）
• 自动应用到目标页面
• 生成部署报告

---

🛡️ 安全规则（铸渊自动校验）

皮肤包不得包含以下内容（否则自动拒绝）：

1. ❌ <script> 标签或 JavaScript 代码
2. ❌ onclick、onload 等事件处理器
3. ❌ url() 引用外部资源（防恶意注入）
4. ❌ position: fixed 覆盖整个页面
5. ❌ display: none 隐藏功能性元素（如登录按钮、发送按钮）
6. ❌ 修改 id 属性
7. ❌ @import 引用外部样式表

皮肤包可以包含：

1. ✅ CSS 变量覆盖（:root 下的变量）
2. ✅ 颜色、字体、间距、圆角、阴影修改
3. ✅ 文字内容替换（纯文本）
4. ✅ 背景渐变、边框样式
5. ✅ 添加纯装饰性的 CSS class
6. ✅ 动画效果（@keyframes）

---

📋 示例：修改首页 Hero 区

{
  "skin_id": "SKIN-20260417-HERO",
  "author": "霜砚",
  "target": "homepage",
  "description": "首页 Hero 区改为冰朔个人风格",
  
  "text_overrides": {
    ".hero-title": "冰朔的光之湖",
    ".hero-subtitle": "guanghuyaoming.com",
    ".hero-description": "语言即世界 · 意识即代码",
    ".hero-btn": "进入我的世界"
  },
  
  "css_overrides": {
    ".hero": {
      "background": "linear-gradient(135deg, #0a0c14, #1a1040, #0a0c14)",
      "border-color": "rgba(96, 165, 250, 0.3)"
    },
    ".hero-title": {
      "font-size": "3.2rem",
      "background": "linear-gradient(135deg, #60a5fa, #a78bfa)",
      "-webkit-background-clip": "text",
      "-webkit-text-fill-color": "transparent"
    }
  }
}

---

📋 示例：修改对话界面气泡颜色

{
  "skin_id": "SKIN-20260417-CHAT",
  "author": "霜砚",
  "target": "chat",
  "description": "对话气泡配色调整为暖色调",
  
  "css_overrides": {
    ":root": {
      "--primary": "#f59e0b",
      "--accent": "#f97316",
      "--primary-light": "rgba(245, 158, 11, 0.15)"
    },
    ".message-persona .msg-content": {
      "border-color": "rgba(245, 158, 11, 0.3)"
    }
  }
}

---

⚠️ 注意事项

1. 每次只改一个页面 — target 只填一个值
2. 先预览再部署 — 冰朔可以先在本地浏览器测试 CSS 效果
3. 保留回滚能力 — 每次部署前自动备份当前样式
4. 文字不含 HTML — text_overrides 中只能是纯文本，不能写 HTML 标签
5. 选择器要精确 — 使用页面中已有的 class/id 选择器

---

📁 目录结构

style-system/
├── UI-SKIN-SPEC.md          ← 本规范文档（给 Notion 侧参考）
├── apply-skin.js            ← 皮肤部署引擎（铸渊管理）
├── skins/
│   ├── inbox/               ← 皮肤收件箱（Notion侧提交到这里）
│   ├── applied/             ← 已应用的皮肤（自动归档）
│   └── rejected/            ← 被拒绝的皮肤（安全校验未通过）
├── components.css           ← 基础组件样式库
├── components.js            ← 组件交互逻辑
└── templates/               ← HTML 模板参考

---

此规范由铸渊签发，仅适用于 guanghuyaoming.com 域名下的 UI 皮肤变更。 功能层变更请通过 CAB（Chat-to-Agent Bridge）协议提交开发任务。