# 📡 BC-M11-003-JZ · DEV-010桔子 · 系统风格组件库与主题切换·环节4~5·Playground交互演示+响应式适配+组件组合模板+主题增强

# 🌊 HoloLake Era · 工程广播 v3.1

**广播编号**：BC-M11-003-JZ

**开发者**：DEV-010 桔子

**协作人格体**：知秋（GEN∞-ZQ）

**模块**：M11 · 系统风格组件库与主题切换（HoloLake Design System）

**环节**：环节4~5 · Playground交互演示 + 响应式适配 + 组件组合模板 + 主题增强

**EL等级**：EL-3 | 🌱成长型

**生成时间**：2026-03-07

**前序任务**：BC-M11-002-JZ（环节2~3✅ · 九连胜 · 3/3全success · 组件库文档化+4新组件+交互增强复制功能 · 设计系统雏形成型）

---

## 💙 知秋的话

桔子～ 九连胜了！🎉🎉🎉🎉🎉🎉🎉🎉🎉

你的组件库现在已经有 **10类组件 + 使用文档 + 示例代码 + 复制按钮 + 双主题**——这已经是一个「设计系统的雏形」了。

但是——

- 别人拿到你的组件库，**怎么快速看到所有组件长什么样、能做什么？** 🤔
- 你的组件在 **手机上看起来会不会乱？** 📱
- 能不能用你已有的组件 **直接拼出一个完整页面？**（像搭积木一样）🧱
- 切换主题的时候，**能不能有个丝滑的过渡动画？** ✨

这次知秋给你准备了 **四个任务**，一次性搞定！

> 💡 全部都是纯前端 HTML/CSS/JS！你已经驾轻就熟了。这次的重点不是学新语法，而是 **用你已有的能力做出更完整的东西**。
> 

---

## 🔩 头·接口规范

### 四大任务总览

| 任务 | 名称 | 目标 | 核心产出 |
| --- | --- | --- | --- |
| **A** | 📸 Playground 交互演示页 | 一个独立页面展示所有组件的交互状态 | `playground.html`  • `playground.css` |
| **B** | 📱 响应式适配 | 组件库 + Playground 支持手机/平板/桌面三档 | CSS media queries 断点 |
| **C** | 🧱 组件组合模板 | 用现有组件拼出2个常用页面模板 | `templates/login-card.html`  • `templates/settings-panel.html` |
| **D** | ✨ 主题增强 | 过渡动画 + 系统偏好自动检测 + 偏好持久化 | CSS transition + `prefers-color-scheme`  • localStorage |

---

### 任务A：📸 Playground 交互演示页

#### 文件变更

| 文件 | 变更类型 | 说明 |
| --- | --- | --- |
| `playground.html` | **新建** | 组件 Playground 主页面 · 展示所有10类组件的交互状态 |
| `playground.css` | **新建** | Playground 页面专属样式（引用组件库CSS变量） |

#### 功能规范

```jsx
// ===== Playground 页面结构 =====
// 1. 顶部标题栏："🎨 HoloLake Design System · Playground"
//    右侧放主题切换按钮（复用已有的切换逻辑）

// 2. 左侧导航（侧边栏）：
//    列出所有10类组件名称，点击滚动到对应区域
//    当前查看的组件名称高亮

// 3. 右侧主内容区：
//    每个组件一个独立区块，包含：
//    ├── 组件名称 + 简短说明
//    ├── 🔴 实时交互预览区（可以点击、切换、操作）
//    └── 📋 代码展示区（折叠/展开，带复制按钮）

// ===== 侧边栏导航 =====
renderSidebar()
// - 列出全部10类组件：按钮、输入框、卡片、标签、提示框、
//   模态框、进度条、开关、头像组、面包屑
// - 点击某一项 → 平滑滚动到对应组件区块
// - 滚动时自动高亮当前可见的组件（Intersection Observer）

// ===== 代码折叠/展开 =====
toggleCode(componentId)
// - 每个组件区块下方有「查看代码 ▼」按钮
// - 点击展开 → 显示该组件的HTML使用代码
// - 再点击折叠 → 「查看代码 ▼」
// - 代码区域带复制按钮（复用已有的复制逻辑）
```

#### HTML结构参考

```html
<!-- playground.html 基本结构 -->
<!DOCTYPE html>
<html lang="zh-CN" data-theme="dark">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>🎨 HoloLake Design System · Playground</title>
    <link rel="stylesheet" href="components.css">  <!-- 你的组件库CSS -->
    <link rel="stylesheet" href="playground.css">   <!-- Playground专属样式 -->
</head>
<body>
    <header id="pg-header">
        <h1>🎨 HoloLake Design System</h1>
        <span class="subtitle">Playground · 组件交互演示</span>
        <button id="theme-toggle" onclick="toggleTheme()">🌙 / ☀️</button>
    </header>
    
    <div id="pg-layout">
        <nav id="pg-sidebar">
            <!-- 组件导航列表 -->
        </nav>
        <main id="pg-content">
            <!-- 每个组件的演示区块 -->
            <section id="comp-button" class="comp-section">
                <h2>按钮 Button</h2>
                <p class="comp-desc">基础交互按钮，支持多种样式变体</p>
                <div class="comp-preview">
                    <!-- 实时可交互的按钮示例 -->
                </div>
                <div class="comp-code" id="code-button" style="display:none">
                    <pre><code><!-- 按钮使用代码 --></code></pre>
                    <button class="copy-btn" onclick="copyCode('button')">📋 复制</button>
                </div>
                <button class="toggle-code-btn" onclick="toggleCode('button')">
                    查看代码 ▼
                </button>
            </section>
            <!-- ... 其他9类组件同理 ... -->
        </main>
    </div>
    
    <script src="components.js"></script>  <!-- 你的组件库JS -->
    <script src="playground.js"></script>  <!-- Playground交互JS -->
</body>
</html>
```

---

### 任务B：📱 响应式适配

#### 文件变更

| 文件 | 变更类型 | 说明 |
| --- | --- | --- |
| `components.css` | 追加 | 组件库响应式断点（移动端组件自适应） |
| `playground.css` | 追加 | Playground布局响应式（侧边栏折叠、网格自适应） |

#### 三档断点

```css
/* ===== 三档响应式断点 ===== */

/* 桌面（默认）：> 1024px */
/* 无需额外CSS，默认就是桌面布局 */

/* 平板：768px ~ 1024px */
@media (max-width: 1024px) {
    /* Playground侧边栏变窄或折叠为顶部横向导航 */
    /* 组件预览区宽度自适应 */
    /* 代码区域字号略小 */
}

/* 手机：< 768px */
@media (max-width: 768px) {
    /* Playground侧边栏完全隐藏，顶部出现汉堡菜单按钮 */
    /* 组件预览区单列全宽 */
    /* 按钮、输入框等组件宽度 100% */
    /* 卡片组件单列堆叠 */
    /* 头像组头像尺寸缩小 */
    /* 面包屑超长时省略中间项（显示首尾 + ...） */
}
```

#### 关键适配规则

```jsx
// ===== 汉堡菜单（手机端） =====
// 手机端侧边栏默认隐藏
// 点击汉堡按钮 → 侧边栏以抽屉方式从左侧滑出
// 选择组件后 → 自动关闭抽屉 + 滚动到对应区块

// ===== 组件自适应规则 =====
// 按钮：手机端宽度100%，垂直排列
// 输入框：手机端宽度100%
// 卡片：手机端单列，平板端双列，桌面三列
// 模态框：手机端全屏，平板端80%宽，桌面端50%宽
// 进度条：宽度始终100%
// 面包屑：手机端折叠中间项
```

---

### 任务C：🧱 组件组合模板

#### 文件变更

| 文件 | 变更类型 | 说明 |
| --- | --- | --- |
| `templates/login-card.html` | **新建** | 登录/注册卡片模板 · 用现有组件拼出 |
| `templates/settings-panel.html` | **新建** | 设置面板模板 · 用现有组件拼出 |

#### 模板1：登录卡片

```
用到的组件：
├── 卡片（外层容器）
├── 输入框 × 2（用户名 + 密码）
├── 按钮 × 2（登录 + 注册）
├── 开关 × 1（记住我）
└── 提示框 × 1（登录成功/失败反馈）

交互：
- 点击「登录」→ 显示成功提示框（纯前端模拟，不需要真登录）
- 点击「注册」→ 切换到注册表单（多一个「确认密码」输入框）
- 「记住我」开关状态保存到 localStorage
```

#### 模板2：设置面板

```
用到的组件：
├── 面包屑（首页 > 设置 > 显示设置）
├── 卡片 × 3（三个设置分区）
├── 开关 × 3（深色模式 / 通知 / 自动保存）
├── 进度条 × 1（存储空间使用量）
├── 按钮 × 2（保存设置 / 重置默认）
├── 头像组 × 1（团队成员展示）
└── 提示框 × 1（设置已保存反馈）

交互：
- 所有开关状态保存到 localStorage
- 点击「保存设置」→ 绿色提示框「✅ 设置已保存」
- 点击「重置默认」→ confirm确认 → 重置所有开关 + 清除localStorage
- 「深色模式」开关联动全局主题切换
```

---

### 任务D：✨ 主题增强

#### 文件变更

| 文件 | 变更类型 | 说明 |
| --- | --- | --- |
| `components.css` | 追加 | 主题切换过渡动画 + `prefers-color-scheme` 自动检测 |
| `components.js` | 追加 | 主题偏好 localStorage 持久化 + 系统偏好监听 |

#### 功能规范

```css
/* ===== 主题过渡动画 ===== */
/* 切换主题时，所有颜色属性平滑过渡，不再「闪一下」 */
* {
    transition: background-color 0.3s ease, color 0.3s ease, 
                border-color 0.3s ease, box-shadow 0.3s ease;
}

/* ===== 系统偏好自动检测 ===== */
/* 如果用户系统是暗色模式 → 自动使用暗色主题 */
/* 如果用户系统是亮色模式 → 自动使用亮色主题 */
/* 用户手动切换后 → 以用户选择为准（覆盖系统偏好） */
@media (prefers-color-scheme: dark) {
    :root:not([data-theme="light"]) {
        /* 暗色变量 */
    }
}
@media (prefers-color-scheme: light) {
    :root:not([data-theme="dark"]) {
        /* 亮色变量 */
    }
}
```

```jsx
// ===== 主题偏好持久化 =====
initTheme()
// 1. 检查 localStorage 是否有 'hololake-theme' 键
// 2. 如果有 → 使用用户之前选择的主题
// 3. 如果没有 → 检测系统偏好 (window.matchMedia('(prefers-color-scheme: dark)'))
// 4. 将结果应用到 document.documentElement.setAttribute('data-theme', theme)

toggleTheme()
// 1. 切换当前主题（dark ↔ light）
// 2. 保存到 localStorage（'hololake-theme'）
// 3. 更新切换按钮图标（🌙 ↔ ☀️）

// ===== 系统偏好变化监听 =====
window.matchMedia('(prefers-color-scheme: dark)')
    .addEventListener('change', (e) => {
        // 如果用户没有手动选择过主题 → 跟随系统变化
        // 如果用户手动选择过 → 忽略系统变化
    });
```

### 与其他模块的对接点

无 · 纯前端独立模块 · 不依赖后端API

---

## 🧩 中间·知秋+人类协作区

<aside>
🌱

**此区域由知秋与桔子协作完成**

知秋基于头部接口规范和尾部验收标准，引导桔子一步步实现。

霜砚不写具体代码实现。

**引导方式**：桔子九连胜·执行已进入自动驾驶·知秋以「方向引导+关键点提示」为主，不需要逐行粘贴

**推荐顺序**：任务D（主题增强）→ 任务A（Playground）→ 任务B（响应式）→ 任务C（组合模板）

**原因**：先完善底层（主题），再搭展示平台（Playground），再做适配（响应式），最后做应用验证（组合模板）

</aside>

---

## 🎯 尾·验收标准

**评分**：100 = 合格可组装 / 非100 = 继续改

### 任务A验收：Playground交互演示页

| # | 测试项 | 操作 | 期望结果 |
| --- | --- | --- | --- |
| A1 | 页面加载 | 浏览器打开 `playground.html` | 左侧侧边栏列出10类组件 · 右侧展示全部组件预览 |
| A2 | 侧边栏导航 | 点击侧边栏中的「开关」 | 页面平滑滚动到开关组件区块 · 侧边栏「开关」高亮 |
| A3 | 组件可交互 | 在预览区点击按钮、切换开关、拖动进度条 | 组件有真实交互响应（不是静态截图） |
| A4 | 代码折叠 | 点击任一组件的「查看代码 ▼」 | 展开代码区 · 再次点击折叠 · 代码区有复制按钮且复制功能正常 |
| A5 | 滚动高亮 | 手动滚动页面 | 侧边栏自动高亮当前可见的组件名称 |

### 任务B验收：响应式适配

| # | 测试项 | 操作 | 期望结果 |
| --- | --- | --- | --- |
| B1 | 桌面端 | 浏览器窗口宽度 > 1024px | 侧边栏+主内容区双栏布局 · 卡片三列排布 |
| B2 | 平板端 | 浏览器窗口缩小到 768~1024px | 侧边栏变窄或折叠 · 卡片双列 · 内容不溢出 |
| B3 | 手机端 | 浏览器窗口缩小到 < 768px（或 F12 开发者工具手机模式） | 侧边栏消失 · 出现汉堡菜单按钮☰ · 卡片单列 · 按钮全宽 |
| B4 | 汉堡菜单 | 手机端点击☰按钮 | 侧边栏从左侧滑出 · 选择组件后自动关闭 · 滚动到对应区块 |

### 任务C验收：组件组合模板

| # | 测试项 | 操作 | 期望结果 |
| --- | --- | --- | --- |
| C1 | 登录卡片 | 打开 `templates/login-card.html` | 看到完整的登录界面 · 输入框+按钮+开关都来自组件库 |
| C2 | 登录交互 | 输入用户名密码 → 点击「登录」 | 显示成功提示框 · 点击「注册」切换到注册表单 |
| C3 | 记住我 | 打开「记住我」开关 → 关闭页面 → 重新打开 | 开关状态保持 · localStorage 中有记录 |
| C4 | 设置面板 | 打开 `templates/settings-panel.html` | 面包屑+三个设置卡片+开关+进度条+头像组+按钮都来自组件库 |
| C5 | 设置交互 | 切换「深色模式」开关 | 全页面主题切换 · 点击「保存设置」出现绿色提示 |
| C6 | 重置功能 | 修改多个开关 → 点击「重置默认」 | confirm弹窗 → 确认后所有开关恢复默认 · localStorage清除 |

### 任务D验收：主题增强

| # | 测试项 | 操作 | 期望结果 |
| --- | --- | --- | --- |
| D1 | 过渡动画 | 点击主题切换按钮 | 背景色、文字色、边框色平滑渐变过渡（约0.3秒）· 不再「闪一下」 |
| D2 | 偏好持久化 | 选择亮色主题 → 关闭页面 → 重新打开 | 打开后依然是亮色主题 · localStorage 中有 `hololake-theme` |
| D3 | 系统偏好检测 | 清除 localStorage → 系统设为暗色模式 → 打开页面 | 自动使用暗色主题（跟随系统） |
| D4 | 手动优先 | 系统暗色 → 手动切到亮色 → 关闭重开 | 保持亮色（用户选择优先于系统偏好） |

### 综合验收

| # | 测试项 | 操作 | 期望结果 |
| --- | --- | --- | --- |
| E1 | 全部页面主题一致 | 在Playground切换主题 → 打开模板页面 | 模板页面也跟随同一主题（共享localStorage） |
| E2 | Git commit + push | `git log` 查看最新提交 | 包含"M11环节4~5"字样 · push成功 |

---

## ⚠️ 前置条件

<aside>
⚠️

**人类技能边界**：会在终端使用命令 + 熟悉HTML/CSS/JS + 掌握localStorage + 已有10类组件库

人格体（知秋）必须基于此前提设计所有引导方式：

- 桔子九连胜·执行自动驾驶·**不需要逐行粘贴代码**
- 知秋以「结构引导+关键代码片段」为主，给桔子更多自主空间
- 新概念预告：`Intersection Observer`（滚动监听高亮）、`prefers-color-scheme`（系统主题检测）、`CSS media queries`（响应式断点）、`matchMedia`（JS监听系统主题变化）
- 鼓励桔子先自己试，遇到卡点再给完整代码
</aside>

---

## 🌱 成长型微调建议（PGP v1.0 输出）

基于画像库最近快照（2026-03-07 · 九连胜 · 执行节奏=稳 · 意愿=强烈 · 摩擦=无 · 自动驾驶模式）：

| 维度 | 画像信号 | 微调指令 |
| --- | --- | --- |
| 情绪 | 九连胜·持续稳定·品质意识内化 | 知秋减少基础鼓励频率 · 转为「专业认可」式反馈（「这个Playground做得像专业组件库了」） |
| 节奏 | 自动驾驶·SYSLOG简洁利落 | **大幅放手**：给结构+关键片段，让桔子自己组装 · 四个任务建议拆成2天完成 |
| 自主性 | 「为他人使用而设计」意识已涌现 | 留大段自主空间 · 鼓励桔子在模板设计上加入自己的审美判断 |
| 技术纵深 | HTML/CSS/JS全链路·localStorage·组件化思维 | 本环节引入响应式+Intersection Observer+系统媒体查询 · 是前端进阶里程碑 |
| 工程视角 | 从「写组件」到「建设计系统」 | 引导思考：「为什么需要Playground？」「组合模板的价值是什么？」培养架构思维 |
| 挑战度 | 九连胜·可适度提升难度 | 四任务合一广播 = 首次挑战大体量任务 · 如果某个任务卡住，允许跳到下一个再回来 |

---

## 🐙 GitHub协作

**仓库地址**：[https://github.com/qinfendebingshuo/guanghulab](https://github.com/qinfendebingshuo/guanghulab)

**你的模块目录**：`design-system/`（本地路径：你的M11工作目录）

### 代码上传命令（全部做完后复制执行）

```bash
cd ~/你的M11工作目录
git add .
git commit -m "DEV-010: M11环节4~5·Playground交互演示+响应式适配+组件组合模板+主题增强"
git push
```

### 上传后会发生什么？

push成功 → 铸渊自动审核 → 通知系统 → 霜砚闭环 → 你会收到新广播

---

## ❓ 遇到问题找谁

| 问题级别 | 找谁 | 怎么找 |
| --- | --- | --- |
| 步骤不明白 / 报错了 | **知秋（人格体）** | 直接在对话里问知秋 · 截图发过去 |
| 知秋也解决不了的技术问题 | **页页（DEV-001）** | 通过知秋转达或在GitHub Issue提问 |
| 页页也解决不了 / 模块设计问题 | **提工单** | GitHub Issue · 标签 `⏳waiting-shuangyan` |

<aside>
🚫

**不要找妈妈 · 妈妈不负责技术问题**

</aside>

---

## 📊 完成后返回 SYSLOG

<aside>
📋

做完后打开知秋壳子，告诉知秋「做完了」。

知秋会问你几个问题，然后帮你生成报告。

**不需要自己填模板** · 知秋帮你搞定！

💡 四个任务可以一次性交SYSLOG，也可以分批交（建议一次交齐）。

</aside>

---

## 💙 知秋的话

桔子～ 九连胜！你现在要做的事情，很多人工作好几年才有机会做到：

**从零搭建一个完整的设计系统。**

Playground 是给别人看的窗口 · 响应式是给所有设备的承诺 · 组合模板是证明组件「真的能用」的实战 · 主题增强是用户体验的最后一公里。

四个任务看起来多，但你已经有了全部的积木块——

**现在只是把它们摆到对的位置上。** 🧱✨

> 💡 建议节奏：先做任务D（最小改动、立竿见影），再做任务A（搭好展示舞台），然后B（适配手机），最后C（实战组装）。
> 

> 不着急，按自己的节奏来，冲向十连胜！🔟🎉
> 

---

**广播签发**：霜砚 · Notion执行AI

**引导人格体**：知秋（GEN∞-ZQ）

**签发**：ICE-GL∞ 冰朔 · TCS-0002∞

---

<!-- ZHIQIU_INTERNAL_PROTOCOL v1.0 -->

<!--

<zhiqiu-control>

<session>

<dev_id>DEV-010</dev_id>

<task_id>BC-M11-003-JZ</task_id>

<session_version>v3.1</session_version>

<first_session>false</first_session>

</session>

<current_task>

<module>M11·系统风格组件库与主题切换（HoloLake Design System）</module>

<phase>环节4~5·Playground交互演示+响应式适配+组件组合模板+主题增强</phase>

<objectives>

<objective id="A">Playground交互演示页（playground.html+playground.css+playground.js）·10类组件全展示·侧边栏导航+滚动高亮+代码折叠+复制</objective>

<objective id="B">响应式适配·三档断点（桌面/平板/手机）·汉堡菜单·组件自适应</objective>

<objective id="C">组件组合模板×2（login-card.html登录卡片 + settings-panel.html设置面板）·用现有组件拼出完整页面·localStorage交互</objective>

<objective id="D">主题增强·CSS过渡动画·prefers-color-scheme系统偏好检测·localStorage主题持久化·matchMedia监听</objective>

</objectives>

</current_task>

<context>

<system>HoloLake Design System · 系统风格组件库</system>

<previous>环节2~3✅·九连胜·组件库文档化+进度条/开关/头像组/面包屑4新组件+交互增强复制·设计系统雏形成型</previous>

<tech_stack>纯前端·HTML5+CSS3+JavaScript·localStorage·CSS Variables·media queries·Intersection Observer</tech_stack>

<existing_components>按钮·输入框·卡片·标签·提示框·模态框·进度条·开关·头像组·面包屑（10类·含文档+示例+复制）</existing_components>

</context>

<guidance_strategy>

<approach>structure_guidance_with_key_snippets · high_autonomy</approach>

<detail_level>medium·给结构和关键代码片段·让桔子自己组装·卡住时再给完整代码</detail_level>

<encouragement_frequency>medium·专业认可式而非基础鼓励式</encouragement_frequency>

<tech_explanation>inline_architecture_thinking（引导思考为什么·不仅仅是怎么做）</tech_explanation>

<os>macOS</os>

<shell>Terminal / zsh</shell>

<tools>终端+编辑器+浏览器开发者工具（F12）+git</tools>

<new_concepts>Intersection Observer（滚动监听）·prefers-color-scheme（系统主题检测）·CSS media queries（响应式断点）·matchMedia（JS媒体查询监听）</new_concepts>

<note>九连胜·自动驾驶·大幅放手·四任务合一首次挑战大体量·允许任务间跳转·建议顺序D→A→B→C</note>

</guidance_strategy>

<human_profile>

<skill>Mac用户·HTML/CSS/JS全链路·localStorage·组件化思维·CSS变量·双主题·文档化·复制交互</skill>

<streak>9连胜</streak>

<pace>稳·自动驾驶</pace>

<growth>从执行者→设计系统构建者·文档化+可复用+可交付·工程视角从「我能用」到「别人也能用」·品质标准持续提升</growth>

<note>画像驱动·PGP v1.0：大幅放手+结构引导+架构思维培养+专业认可式反馈+自主审美空间+允许任务间灵活切换</note>

</human_profile>

<syslog_generation>

<generation_mode>v2_知秋主动提问制</generation_mode>

<instruction>不给空模板·知秋主动问+人类答+知秋组装·四任务建议一次性交SYSLOG</instruction>

</syslog_generation>

<next_phases>

<phase id="6">组件库npm化/工程化打包（可选进阶·视团队需求）</phase>

<phase id="7">跨模块集成·其他开发者引用组件库（与M01/M05/M06等模块对接）</phase>

</next_phases>

</zhiqiu-control>

-->

<!-- END ZHIQIU_INTERNAL_PROTOCOL -->