"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."
When to use
| User says | Which paradigm to use | Template |
|---|---|---|
| "Organize our design tokens into a reference" | Design system reference | ../../templates/design-tokens.html |
| "Review which colors / font sizes we used" | Same as above | Same as above |
| "show me all variants of Card / Button" | Component variant showcase | Build your own (see below) |
Paradigm 3.1 · Design system reference
Spatial shape: 4 sections + a bottom component showcase row. Every token must bevisible：
- Color → swatch + hex + variable name
- Font size → actually rendered "Plan the week ahead" text
- Spacing → bars of actual width
- Radius/shadow → actually rendered cards
HTML skeleton：
<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>
Key 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; }
Ready-to-use template：../../templates/design-tokens.html — includes 4+4+4 color swatches, a 6-level font-size scale, 8 spacing levels, 4 radius levels, 3 shadow levels, a core component showcase row + light/dark toggle.How to modify: just replace the hex values, variable name prefixes, and font-size / spacing numbers with your project's own tokens.
Paradigm 3.2 · Component variant showcase
Spatial shape: 3×N grid, one variant per cell. Labels A/B/C/D in the top-left of the card, "best for: ..." at the bottom. You can add prop sliders (padding / radius / shadow) to let the reviewer adjust in real time.
Typical variant set(using Card as an example):
- 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 skeleton：
<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>
Key JS(slider affects all variants):
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); }
No standalone template.
Shared principles
- Tokens always show concrete values— don't just write
--clay, also show#D97757 - Component variants always around 6— more than that and review won't happen
- Every variant must have a "best for" — don't just say what it looks like, say when to use it
- Sliders are not decoration— they must actually affect rendering, andall variants change simultaneously