html-effectiveness-design

name	html-effectiveness-design
description	子 skill — 设计系统与组件展示。当用户要从 repo 提取 design tokens 做团队 reference、或要把一个组件的所有 variant 平铺在一张 contact sheet 上 review 时使用。包含设计系统参考（design-tokens.html）和组件变体陈列两种范式。当父 skill 路由命中"设计系统/design tokens/组件变体/展示组件库"类请求时加载。

03-design — 设计系统与组件

"HTML is the medium your design system ships in, so it's the natural format for talking about it. Tokens become swatches, components become contact sheets."

何时用

用户说	用哪个范式	模板
"把我们的 design tokens 整理成一份 reference"	设计系统参考	../../templates/design-tokens.html
"review 一下我们用了哪些颜色 / 字号"	同上	同上
"show me all variants of Card / Button"	组件变体陈列	自建（见下）

---

范式 3.1 · 设计系统参考

空间形状：4 个区域 + 底部组件展示行。每个 token 必须可见：

• 颜色 → 色块 + hex + 变量名
• 字号 → 真实渲染的"Plan the week ahead"字样
• 间距 → 真实宽度的横条
• 圆角/阴影 → 真实渲染的卡片

HTML 骨架：

<section class="tokens-color">
  <h2>Color · Primary</h2>
  <div class="palette">
    <div class="swatch" style="background:#D97757">
      <span class="hex">#D97757</span><span class="var">--clay</span>
    </div>
    <div class="swatch" style="background:#141413;color:#FAF9F5">
      <span class="hex">#141413</span><span class="var">--slate</span>
    </div>
    <!-- ivory / oat -->
  </div>
</section>

<section class="tokens-type">
  <h2>Typography</h2>
  <div class="scale">
    <div>
      <p style="font-size:48px;line-height:1.1;font-weight:500">Plan the week ahead</p>
      <small>Display 48 / 1.1 / 500</small>
    </div>
    <!-- Heading 1, Heading 2, Body, Small, Caption -->
  </div>
</section>

<section class="tokens-space">
  <h2>Spacing</h2>
  <div class="space-scale">
    <div><span class="bar" style="width:4px"></span>4 <code>--sp-1</code></div>
    <div><span class="bar" style="width:8px"></span>8 <code>--sp-2</code></div>
    <!-- 12, 16, 24, 32, 48, 64 -->
  </div>
</section>

关键 CSS：

.palette { display: grid; grid-template-columns: repeat(4, 1fr); gap: 16px; }
.swatch { aspect-ratio: 1; padding: 16px; border-radius: 12px;
          color: white; display: flex; flex-direction: column;
          justify-content: flex-end; gap: 4px; font-size: 12px; }
.swatch .hex { font-family: var(--font-mono); }
.swatch .var { opacity: 0.7; }

.space-scale > div { display: flex; align-items: center; gap: 12px;
                      padding: 8px 0; }
.space-scale .bar { display: inline-block; height: 16px;
                     background: var(--clay); border-radius: 2px; }

直接可用模板：../../templates/design-tokens.html — 含 4+4+4 配色 swatches、6 级字号 scale、8 级间距、4 级圆角、3 级阴影、核心组件展示行 + light/dark 切换。修改方式：把 hex 值、变量名前缀、字号 / 间距数字换成项目自己的 tokens 即可。

---

范式 3.2 · 组件变体陈列

空间形状：3×N 网格，每格一个变体。标签 A/B/C/D 在卡片左上，"best for: ..." 在底部。可加 prop slider（padding / radius / shadow）让 reviewer 实时调。

典型变体集合（以 Card 为例）：

• A · Flat · best for dense lists on tinted backgrounds
• B · Outlined · best for default content cards on ivory
• C · Elevated · best for draggable items, popovers
• D · Accent stripe · best for pinned or priority items
• E · Inset · best for nested cards inside white panels
• F · Horizontal · best for compact row lists, sidebars

HTML 骨架：

<header class="bar">
  <span>Card variants</span>
  <div class="controls">
    <label>Padding <input type="range" id="pad" min="8" max="40" value="20">
      <output>20px</output></label>
    <label><input type="checkbox" id="shadow" checked> Shadow</label>
  </div>
</header>

<div class="grid">
  <figure class="variant">
    <span class="tag">A · Flat</span>
    <div class="card flat">[实际渲染的卡片]</div>
    <figcaption>best for: dense lists on tinted backgrounds</figcaption>
  </figure>
  <!-- B / C / D / E / F -->
</div>

关键 JS（slider 影响所有变体）：

const padSlider = document.querySelector('#pad');
const padOut = padSlider.parentElement.querySelector('output');
padSlider.oninput = () => {
  document.documentElement.style.setProperty('--card-pad', padSlider.value + 'px');
  padOut.textContent = padSlider.value + 'px';
};
document.querySelector('#shadow').onchange = (e) => {
  document.documentElement.style.setProperty(
    '--card-shadow', e.target.checked ? 'var(--shadow-md)' : 'none'
  );
};

.card { padding: var(--card-pad, 20px); box-shadow: var(--card-shadow, none); }

无独立模板。

---

共同原则

• token 永远显示具体值——不要光写 --clay，要同时显示 #D97757
• 组件变体永远 6 个左右——多了 review 不动
• 每个 variant 必须有 "best for" ——不光说什么样子，说什么时候用
• slider 不是装饰——必须真的影响渲染，而且所有变体同时变