# Cursor Rules 配置教程：让多页面主题统一使用设计令牌

## 身份和范围

本站原创 fixture 与人工参考；实际运行：三页与弹窗实际主题/持久化。目标代理模型、账号会话、付费 API、第三方 PR、推送和发布均未执行。公开包不含 .env；需要时仅在自己的临时练习目录从文本模板创建。

## 本地命令

```sh
python3 -m http.server 4384 --bind 127.0.0.1
```

## 七步原生操作

### 1. 先看三页和弹窗的共同主题结构

先打开 before/page1.html、before/page2.html、before/page3.html 的错误样稿：深色页面仍有白色卡片/弹窗，选择浅色后刷新又回系统。根目录 page1/page2/page3 是已验证的人工修复参考；实际代理应先改错误样稿，再对照参考验收。

### 2. 建立正确的 mdc 项目规则

放入 .cursor/rules/theme.mdc，填写 description、globs 与 alwaysApply:false。普通 .md 不是等价配置；alwaysApply:true 会忽略 globs，不能一边写全局始终附加，一边声称只作用于样式文件。

### 3. 在匹配上下文中明确调用规则

在对应前端文件上下文中让 Cursor 读取 theme 规则，要求组件用 token、不新增字面颜色、保持用户偏好。检查实际附加规则和 diff，规则是指导上下文，并不自动变成不可绕过的 lint。

### 4. 实现用户选择优先于系统

用户选 light/dark 时使用固定值，选 system 才跟随 matchMedia；localStorage 存用户选择而不是解析后的颜色。这样下次系统变化仍可正确响应，刷新也不会丢用户意图。

### 5. 把弹窗纳入同一令牌系统

dialog、main、card 使用相同 surface/text。打开真实弹窗检查背景、文字与按钮；只改 body 背景会留下白色弹窗，这是本题明确要覆盖的边界。

### 6. 跨页刷新与系统切换实测

本站 Playwright 设系统深色，验证 system 解析为 dark；用户选 light 后刷新和跳到第二、第三页仍为 light；再选 system 切换系统偏好，查看页面和弹窗实际计算样式。

### 7. 交付规则、diff 和主题证据

保存 .mdc、三个页面与弹窗明暗截图及 browser-result.json。不能把规则文件存在当作改造通过；验收要落到实际背景/文字、偏好优先级和刷新结果。

## 验收产物

按 globs 限定的 .cursor/rules/*.mdc 规则；令牌替换 diff、三页与弹窗明暗主题实际截图、用户选择与系统偏好优先级验收表

## 门槛

- 项目规则必须是 .mdc；alwaysApply=true 会忽略 globs，需按任务选择附加方式。
- 规则是上下文指导，不是不可绕过的静态检查器；仍需 diff 审查和实际渲染。
- 模型访问与计费依当前 Cursor 订阅；不复用旧 Pro 固定价格描述。

## 官方来源

- https://cursor.com/docs/rules

静态配图冻结于本次输入。修改输入需重新运行并自行重渲染；不把旧截图当新结果。

## 可重复的浏览器检查

需 Node >=24。运行 `npm ci`，若缺少 Chromium，再按 Playwright 提示安装浏览器，然后 `npm run check`。只启动本地练习 HTTP 服务，不连接任何模型或账号。PDF 页数/中文需结合包内原生 PDF 逐页人工看。