wizz-method 1.0.3 → 1.2.0

package/src/skills-lib/huashu-design/references/tweaks-system.md

@@ -0,0 +1,313 @@
+# Tweaks：设计变体实时调参
+
+Tweaks是这个skill里很核心的能力——让用户不改代码就能实时切换variations/调整参数。
+
+**跨 agent 环境适配**：某些 design-agent 原生环境（如 Claude.ai Artifacts）依赖 host 的 postMessage 把 tweak 值回写源码做持久化。本 skill 采用**纯前端 localStorage 方案**——效果一致（刷新保留状态），但持久化发生在浏览器 localStorage 而不是源码文件。这个方案在任何 agent 环境（Claude Code / Codex / Cursor / Trae / etc.）都能工作。
+
+## 何时加 Tweaks
+
+- 用户明确要求"能调参"/"多个版本切换"
+- 设计有多个variations需要对比时
+- 用户没明说，但你主观判断**加几个有启发性的tweaks能帮用户看到可能性**
+
+默认推荐：**每个设计都加2-3个tweaks**（颜色主题/字号/layout变体）即使用户没要求——让用户看到可能性空间是设计服务的一部分。
+
+## 实现方式（纯前端版）
+
+### 基本结构
+
+```jsx
+const TWEAK_DEFAULTS = {
+  "primaryColor": "#D97757",
+  "fontSize": 16,
+  "density": "comfortable",
+  "dark": false
+};
+
+function useTweaks() {
+  const [tweaks, setTweaks] = React.useState(() => {
+    try {
+      const stored = localStorage.getItem('design-tweaks');
+      return stored ? { ...TWEAK_DEFAULTS, ...JSON.parse(stored) } : TWEAK_DEFAULTS;
+    } catch {
+      return TWEAK_DEFAULTS;
+    }
+  });
+
+  const update = (patch) => {
+    const next = { ...tweaks, ...patch };
+    setTweaks(next);
+    try {
+      localStorage.setItem('design-tweaks', JSON.stringify(next));
+    } catch {}
+  };
+
+  const reset = () => {
+    setTweaks(TWEAK_DEFAULTS);
+    try {
+      localStorage.removeItem('design-tweaks');
+    } catch {}
+  };
+
+  return { tweaks, update, reset };
+}
+```
+
+### Tweaks面板UI
+
+右下角浮动面板。可折叠：
+
+```jsx
+function TweaksPanel() {
+  const { tweaks, update, reset } = useTweaks();
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div style={{
+      position: 'fixed',
+      bottom: 20,
+      right: 20,
+      zIndex: 9999,
+    }}>
+      {open ? (
+        <div style={{
+          background: 'white',
+          border: '1px solid #e5e5e5',
+          borderRadius: 12,
+          padding: 20,
+          boxShadow: '0 10px 40px rgba(0,0,0,0.12)',
+          width: 280,
+          fontFamily: 'system-ui',
+          fontSize: 13,
+        }}>
+          <div style={{ 
+            display: 'flex', 
+            justifyContent: 'space-between', 
+            alignItems: 'center',
+            marginBottom: 16,
+          }}>
+            <strong>Tweaks</strong>
+            <button onClick={() => setOpen(false)} style={{
+              border: 'none', background: 'none', cursor: 'pointer', fontSize: 16,
+            }}>×</button>
+          </div>
+
+          {/* 颜色 */}
+          <label style={{ display: 'block', marginBottom: 12 }}>
+            <div style={{ marginBottom: 4, color: '#666' }}>主色</div>
+            <input 
+              type="color" 
+              value={tweaks.primaryColor} 
+              onChange={e => update({ primaryColor: e.target.value })}
+              style={{ width: '100%', height: 32 }}
+            />
+          </label>
+
+          {/* 字号slider */}
+          <label style={{ display: 'block', marginBottom: 12 }}>
+            <div style={{ marginBottom: 4, color: '#666' }}>字号 ({tweaks.fontSize}px)</div>
+            <input 
+              type="range" 
+              min={12} max={24} step={1}
+              value={tweaks.fontSize}
+              onChange={e => update({ fontSize: +e.target.value })}
+              style={{ width: '100%' }}
+            />
+          </label>
+
+          {/* 密度选项 */}
+          <label style={{ display: 'block', marginBottom: 12 }}>
+            <div style={{ marginBottom: 4, color: '#666' }}>密度</div>
+            <select 
+              value={tweaks.density}
+              onChange={e => update({ density: e.target.value })}
+              style={{ width: '100%', padding: 6 }}
+            >
+              <option value="compact">紧凑</option>
+              <option value="comfortable">舒适</option>
+              <option value="spacious">宽松</option>
+            </select>
+          </label>
+
+          {/* 暗黑模式toggle */}
+          <label style={{ 
+            display: 'flex', 
+            alignItems: 'center',
+            gap: 8,
+            marginBottom: 16,
+          }}>
+            <input 
+              type="checkbox" 
+              checked={tweaks.dark}
+              onChange={e => update({ dark: e.target.checked })}
+            />
+            <span>暗黑模式</span>
+          </label>
+
+          <button onClick={reset} style={{
+            width: '100%',
+            padding: '8px 12px',
+            background: '#f5f5f5',
+            border: 'none',
+            borderRadius: 6,
+            cursor: 'pointer',
+            fontSize: 12,
+          }}>重置</button>
+        </div>
+      ) : (
+        <button 
+          onClick={() => setOpen(true)}
+          style={{
+            background: '#1A1A1A',
+            color: 'white',
+            border: 'none',
+            borderRadius: 999,
+            padding: '10px 16px',
+            fontSize: 12,
+            cursor: 'pointer',
+            boxShadow: '0 4px 12px rgba(0,0,0,0.15)',
+          }}
+        >⚙ Tweaks</button>
+      )}
+    </div>
+  );
+}
+```
+
+### 应用Tweaks
+
+在主组件里用Tweaks：
+
+```jsx
+function App() {
+  const { tweaks } = useTweaks();
+
+  return (
+    <div style={{
+      '--primary': tweaks.primaryColor,
+      '--font-size': `${tweaks.fontSize}px`,
+      background: tweaks.dark ? '#0A0A0A' : '#FAFAFA',
+      color: tweaks.dark ? '#FAFAFA' : '#1A1A1A',
+    }}>
+      {/* 你的内容 */}
+      <TweaksPanel />
+    </div>
+  );
+}
+```
+
+CSS里用变量：
+
+```css
+button.cta {
+  background: var(--primary);
+  color: white;
+  font-size: var(--font-size);
+}
+```
+
+## 典型 Tweak 选项
+
+给不同类型的设计加什么tweaks：
+
+### 通用
+- 主色（color picker）
+- 字号（slider 12-24px）
+- 字型（select：display font vs body font）
+- 暗黑模式（toggle）
+
+### 幻灯片deck
+- 主题（light/dark/brand）
+- 背景样式（solid/gradient/image）
+- 字体对比（更装饰 vs 更克制）
+- 信息密度（minimal/standard/dense）
+
+### 产品原型
+- 布局变体（layout A / B / C）
+- 交互速度（animation speed 0.5x-2x）
+- 数据量（mock数据条数 5/20/100）
+- 状态（empty/loading/success/error）
+
+### 动画
+- 速度（0.5x-2x）
+- 循环（once/loop/ping-pong）
+- Easing（linear/easeOut/spring）
+
+### Landing page
+- Hero风格（image/gradient/pattern/solid）
+- CTA文案（几种变体）
+- 结构（single column / two column / sidebar）
+
+## Tweaks设计原则
+
+### 1. 有意义的选项，不是折腾人的
+
+每个tweak必须展示**真实的设计选项**。别加那种谁都不会真切换的tweak（比如border-radius 0-50px的slider——用户调完发现所有中间值都丑）。
+
+好的tweak暴露**离散的、有思考的variations**：
+- "圆角风格"：无圆角 / 微圆角 / 大圆角（三个选项）
+- 不是："圆角"：0-50px slider
+
+### 2. 少即是多
+
+一个设计的Tweaks面板**最多5-6个**选项。再多就变成"配置页面"，失去了快速探索variations的意义。
+
+### 3. 默认值是完成设计
+
+Tweaks是**锦上添花**。默认值必须本身就是一个完整、可发布的设计。用户关闭Tweaks面板后看到的就是产出。
+
+### 4. 合理分组
+
+选项多时分组显示：
+
+```
+---- 视觉 ----
+主色 | 字号 | 暗黑模式
+
+---- 布局 ----
+密度 | 侧栏位置
+
+---- 内容 ----
+显示数据量 | 状态
+```
+
+## 向前兼容源码级持久化 host
+
+如果你以后想把设计上传到支持源码级 tweaks（如 Claude.ai Artifacts）的环境也能跑，保留 **EDITMODE 标记块**：
+
+```jsx
+const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
+  "primaryColor": "#D97757",
+  "fontSize": 16,
+  "density": "comfortable",
+  "dark": false
+}/*EDITMODE-END*/;
+```
+
+标记块在 localStorage 方案里**无作用**（只是个普通注释），但在支持源码回写的 host 里会被读取，实现源码级持久化。加上这个对当前环境无害，同时保持向前兼容。
+
+## 常见问题
+
+**Tweaks面板挡住设计内容**
+→ 让它可关闭。默认关闭，显示一个小按钮，用户点了才展开。
+
+**用户切换tweaks后还要重复设置**
+→ 已经用localStorage。如果刷新后不持久，检查localStorage是否可用（无痕模式会失败，要catch）。
+
+**多个HTML页面想共享tweaks**
+→ 给localStorage key加project name：`design-tweaks-[projectName]`。
+
+**我想让tweak之间有联动关系**
+→ 在`update`里加逻辑：
+
+```jsx
+const update = (patch) => {
+  let next = { ...tweaks, ...patch };
+  // 联动：选dark mode时自动切换字体配色
+  if (patch.dark === true && !patch.textColor) {
+    next.textColor = '#F0EEE6';
+  }
+  setTweaks(next);
+  localStorage.setItem(...);
+};
+```

package/src/skills-lib/huashu-design/references/verification.md

@@ -0,0 +1,183 @@
+# Verification：输出验证流程
+
+一些 design-agent 原生环境（如 Claude.ai Artifacts）有内置的 `fork_verifier_agent` 起 subagent 用 iframe 截图检查。大部分 agent 环境（Claude Code / Codex / Cursor / Trae / 等）里没有这个内置能力——用 Playwright 手动做就能覆盖相同的验证场景。
+
+## 验证清单
+
+每次产出HTML后，按这个清单做一遍：
+
+### 1. 浏览器渲染检查（必做）
+
+最基础：**HTML能不能打开**？在macOS上：
+
+```bash
+open -a "Google Chrome" "/path/to/your/design.html"
+```
+
+或者用Playwright截图（下一节）。
+
+### 2. 控制台错误检查
+
+HTML文件里最常见的问题是JS报错导致白屏。用Playwright跑一遍：
+
+```bash
+python ~/.claude/skills/huashu-design/scripts/verify.py path/to/design.html
+```
+
+这个脚本会：
+1. 用headless chromium打开HTML
+2. 截图保存到项目目录
+3. 抓取控制台错误
+4. 报告status
+
+详见`scripts/verify.py`。
+
+### 3. 多视口检查
+
+如果是响应式设计，抓多个viewport：
+
+```bash
+python verify.py design.html --viewports 1920x1080,1440x900,768x1024,375x667
+```
+
+### 4. 交互检查
+
+Tweaks、动画、按钮切换——默认的静态截图看不到。**建议让用户自己开浏览器点一遍**，或者用Playwright录屏：
+
+```python
+page.video.record('interaction.mp4')
+```
+
+### 5. 幻灯片逐页检查
+
+Deck类HTML，一张张截：
+
+```bash
+python verify.py deck.html --slides 10  # 截前10张
+```
+
+生成 `deck-slide-01.png`、`deck-slide-02.png`... 方便快速浏览。
+
+## Playwright Setup
+
+首次使用需要：
+
+```bash
+# 如果还没装
+npm install -g playwright
+npx playwright install chromium
+
+# 或者Python版
+pip install playwright
+playwright install chromium
+```
+
+如果用户已经全局安装 Playwright，直接用即可。
+
+## 截图最佳实践
+
+### 截完整页面
+
+```python
+page.screenshot(path='full.png', full_page=True)
+```
+
+### 截viewport
+
+```python
+page.screenshot(path='viewport.png')  # 默认只截可见区域
+```
+
+### 截特定元素
+
+```python
+element = page.query_selector('.hero-section')
+element.screenshot(path='hero.png')
+```
+
+### 高清截图
+
+```python
+page = browser.new_page(device_scale_factor=2)  # retina
+```
+
+### 等动画结束再截
+
+```python
+page.wait_for_timeout(2000)  # 等2秒让动画settle
+page.screenshot(...)
+```
+
+## 把截图发给用户
+
+### 本地截图直接打开
+
+```bash
+open screenshot.png
+```
+
+用户会在自己的 Preview/Figma/VSCode/浏览器 里看。
+
+### 上传图床分享链接
+
+如果需要给远程协作者看（比如 Slack/飞书/微信），让用户用自己的图床工具或 MCP 上传截图，拿到一个永久链接，可以粘贴到任何地方。
+
+## 验证出错时
+
+### 页面白屏
+
+控制台一定有错。先检查：
+
+1. React+Babel script tag的integrity hash对不对（见`react-setup.md`）
+2. 是不是`const styles = {...}`命名冲突
+3. 跨文件的组件有没有export到`window`
+4. JSX语法错误（babel.min.js不报错，换babel.js非压缩版）
+
+### 动画卡
+
+- 用Chrome DevTools Performance tab录一段
+- 找layout thrashing（频繁的reflow）
+- 动效优先用`transform`和`opacity`（GPU加速）
+
+### 字体不对
+
+- 检查`@font-face`的url是否可访问
+- 检查fallback字体
+- 中文字体加载慢：先显示fallback，加载完再切换
+
+### 布局错位
+
+- 检查`box-sizing: border-box`是否全局应用
+- 检查`*  margin: 0; padding: 0`reset
+- Chrome DevTools里打开gridlines看实际布局
+
+## 验证=设计师的第二双眼
+
+**永远要自己过一遍**。AI写代码时经常出现：
+
+- 看起来对但interaction有bug
+- 静态截图好但scroll时错位
+- 宽屏好看但窄屏崩
+- Dark mode忘了测
+- Tweaks切换后某些组件没响应
+
+**最后1分钟的验证可以省1小时的返工**。
+
+## 常用验证脚本命令
+
+```bash
+# 基础：打开+截图+抓错
+python verify.py design.html
+
+# 多viewport
+python verify.py design.html --viewports 1920x1080,375x667
+
+# 多slide
+python verify.py deck.html --slides 10
+
+# 输出到指定目录
+python verify.py design.html --output ./screenshots/
+
+# headless=false，打开真实浏览器给你看
+python verify.py design.html --show
+```