Html Plan
- 1.8k installs
- 1.6k repo stars
- Updated August 3, 2026
- plannotator/effective-html
html-plan provides documented workflows for Create a self-contained HTML plan that is pragmatic, simple, and visually organized. Use when the user wants a plan page in the effective HTML style, wants the
About
The html-plan skill create a self-contained HTML plan that is pragmatic, simple, and visually organized. Use when the user wants a plan page in the effective HTML style, wants the writing kept close to what they gave you, or wants the grammar cleaned up without turning it into a whole bigger thing. # HTML Plan Review the files throughout `references/html-effectiveness/`. After reviewing them, create an HTML file for the plan in a similar style. Keep it pragmatic and simple. Always include dark mode: hand-rolled CSS variables on `:root` / `html.dark`, a small theme toggle button, `localStorage` persistence, and an apply-before-paint script in `<head>` (default to `prefers-color-scheme`). # HTML Plan Review the files throughout `references/html-effectiveness/`. After reviewing them, create an HTML file for the plan in a similar style. Keep it pragmatic and simple. Always include dark mode: hand-rolled CSS variables on `:root` / `html.dark`, a small theme toggle button, `localStorage` persistence, and an apply-before-paint script in `<head>` (default to `prefers-color-scheme`).
- # HTML Plan Review the files throughout `references/html-effectiveness/`.
- After reviewing them, create an HTML file for the plan in a similar style.
- Keep it pragmatic and simple.
- Create a self-contained HTML plan that is pragmatic, simple, and visually organized. Use when the user wants a plan page
- Create a self-contained HTML plan that is pragmatic, simple, and visually organized. Use when the user wants a plan page
Html Plan by the numbers
- 1,841 all-time installs (skills.sh)
- +220 installs in the week ending Aug 4, 2026 (Skillselion tracking)
- Ranked #196 of 2,715 Automation & Workflows skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
html-plan capabilities & compatibility
- Capabilities
- # html plan review the files throughout `referen · after reviewing them, create an html file for th · keep it pragmatic and simple. · create a self contained html plan that is pragma
- Use cases
- documentation
What html-plan says it does
# HTML Plan Review the files throughout `references/html-effectiveness/`.
After reviewing them, create an HTML file for the plan in a similar style.
npx skills add https://github.com/plannotator/effective-html --skill html-planAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 1.8k |
|---|---|
| repo stars | ★ 1.6k |
| Last updated | August 3, 2026 |
| Repository | plannotator/effective-html ↗ |
How do I use html-plan for the task described in its SKILL.md triggers?
Create a self-contained HTML plan that is pragmatic, simple, and visually organized. Use when the user wants a plan page in the effective HTML style, wants the writing kept close to what they gave yo.
Who is it for?
Teams invoking html-plan when the user request matches documented triggers and prerequisites.
Skip if: Skip when cached docs are missing, the request is a negative trigger, or another sibling skill owns the workflow.
When should I use this skill?
Create a self-contained HTML plan that is pragmatic, simple, and visually organized. Use when the user wants a plan page in the effective HTML style, wants the writing kept close to what they gave you, or wants the gramm
What you get
Step-by-step guidance grounded in html-plan documentation and reference files.
- Self-contained HTML plan file with dark mode
Files
HTML Plan
Review the files throughout references/html-effectiveness/.
After reviewing them, create an HTML file for the plan in a similar style.
Keep it pragmatic and simple.
Always include dark mode: hand-rolled CSS variables on :root / html.dark, a small theme toggle button, localStorage persistence, and an apply-before-paint script in <head> (default to prefers-color-scheme).
interface:
display_name: "HTML Plan"
short_description: "Create pragmatic visual HTML plans"
default_prompt: "Use $html-plan to create a pragmatic HTML plan."
policy:
allow_implicit_invocation: false
<!-- Copyright 2026 Anthropic PBC · SPDX-License-Identifier: Apache-2.0 -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Debounced search — three approaches</title>
<style>
:root {
--ivory: #FAF9F5;
--slate: #141413;
--clay: #D97757;
--oat: #E3DACC;
--olive: #788C5D;
--gray-150: #F0EEE6;
--gray-300: #D1CFC5;
--gray-500: #87867F;
--gray-700: #3D3D3A;
--white: #FFFFFF;
--serif: ui-serif, Georgia, 'Times New Roman', serif;
--sans: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
--mono: ui-monospace, 'SF Mono', Menlo, Monaco, monospace;
}
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: var(--sans);
background: var(--ivory);
color: var(--gray-700);
line-height: 1.55;
padding: 56px 32px 96px;
-webkit-font-smoothing: antialiased;
}
.page {
max-width: 1360px;
margin: 0 auto;
}
/* ---------- header ---------- */
header.page-head {
margin-bottom: 48px;
max-width: 760px;
}
.eyebrow {
font-size: 12px;
letter-spacing: 0.08em;
text-transform: uppercase;
color: var(--gray-500);
margin-bottom: 12px;
}
h1 {
font-family: var(--serif);
font-weight: 500;
font-size: 38px;
line-height: 1.15;
color: var(--slate);
margin-bottom: 18px;
letter-spacing: -0.01em;
}
.prompt-box {
background: var(--gray-150);
border: 1.5px solid var(--gray-300);
border-radius: 12px;
padding: 16px 20px;
font-size: 14.5px;
color: var(--gray-700);
}
.prompt-box .label {
font-family: var(--mono);
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.06em;
color: var(--gray-500);
display: block;
margin-bottom: 6px;
}
/* ---------- approach grid ---------- */
.approaches {
display: grid;
grid-template-columns: repeat(3, minmax(0, 1fr));
gap: 28px;
margin-bottom: 56px;
}
@media (max-width: 1100px) {
.approaches { grid-template-columns: 1fr; }
}
.approach {
background: var(--white);
border: 1.5px solid var(--gray-300);
border-radius: 12px;
padding: 24px;
display: flex;
flex-direction: column;
gap: 20px;
}
.approach-head h2 {
font-family: var(--serif);
font-weight: 500;
font-size: 21px;
color: var(--slate);
margin-bottom: 6px;
}
.approach-head .num {
display: inline-block;
font-family: var(--mono);
font-size: 12px;
background: var(--oat);
color: var(--slate);
padding: 2px 8px;
border-radius: 8px;
margin-right: 8px;
vertical-align: 3px;
}
.approach-head p {
font-size: 14px;
color: var(--gray-500);
}
/* ---------- code panel ---------- */
.code {
background: var(--slate);
border-radius: 12px;
padding: 18px 20px;
overflow-x: auto;
}
.code pre {
font-family: var(--mono);
font-size: 12.5px;
line-height: 1.65;
color: #E8E6DE;
white-space: pre;
}
.code .kw { color: var(--clay); } /* keywords */
.code .str { color: var(--olive); } /* strings */
.code .cm { color: var(--gray-500); } /* comments */
.code .fn { color: #C9B98A; } /* identifiers, subtle warm */
/* ---------- tradeoffs table ---------- */
.tradeoffs {
border: 1.5px solid var(--gray-300);
border-radius: 8px;
overflow: hidden;
font-size: 13px;
}
.tradeoffs .row {
display: grid;
grid-template-columns: 1fr 1fr;
}
.tradeoffs .row + .row {
border-top: 1.5px solid var(--gray-300);
}
.tradeoffs .cell {
padding: 10px 14px;
}
.tradeoffs .cell:first-child {
border-right: 1.5px solid var(--gray-300);
}
.tradeoffs .head {
background: var(--gray-150);
font-weight: 600;
color: var(--slate);
font-size: 12px;
text-transform: uppercase;
letter-spacing: 0.04em;
}
.tradeoffs .pro::before,
.tradeoffs .con::before {
content: '';
display: inline-block;
width: 6px;
height: 6px;
border-radius: 50%;
margin-right: 8px;
vertical-align: 2px;
}
.tradeoffs .pro::before { background: var(--olive); }
.tradeoffs .con::before { background: var(--clay); }
/* ---------- chip footer ---------- */
.chips {
display: flex;
flex-wrap: wrap;
gap: 8px;
}
.chip {
font-family: var(--mono);
font-size: 11.5px;
background: var(--gray-150);
border: 1.5px solid var(--gray-300);
color: var(--gray-700);
padding: 5px 10px;
border-radius: 8px;
white-space: nowrap;
}
.chip strong { color: var(--slate); font-weight: 600; }
/* ---------- recommendation ---------- */
.reco {
border-left: 4px solid var(--clay);
background: var(--white);
border-radius: 0 12px 12px 0;
padding: 24px 28px;
max-width: 860px;
}
.reco h2 {
font-family: var(--serif);
font-weight: 500;
font-size: 22px;
color: var(--slate);
margin-bottom: 10px;
}
.reco p {
font-size: 15px;
margin-bottom: 8px;
}
.reco code {
font-family: var(--mono);
font-size: 0.92em;
background: var(--gray-150);
padding: 1px 6px;
border-radius: 4px;
}
</style>
</head>
<body>
<div class="page">
<header class="page-head">
<div class="eyebrow">Exploration · Acme web client</div>
<h1>Three ways to implement debounced search</h1>
<div class="prompt-box">
<span class="label">Prompt</span>
Show me three different ways to implement debounced search for the task
filter input in our React codebase, with tradeoffs for each.
</div>
</header>
<!-- ============================================================= -->
<section class="approaches">
<!-- ---------- Approach 1 ---------- -->
<article class="approach">
<header class="approach-head">
<h2><span class="num">01</span>Inline useEffect + setTimeout</h2>
<p>Debounce logic lives directly inside the component that owns the input.</p>
</header>
<div class="code"><pre><span class="kw">export function</span> <span class="fn">TaskSearch</span>() {
<span class="kw">const</span> [draft, setDraft] = <span class="fn">useState</span>(<span class="str">''</span>);
<span class="kw">const</span> [query, setQuery] = <span class="fn">useState</span>(<span class="str">''</span>);
<span class="fn">useEffect</span>(() <span class="kw">=></span> {
<span class="kw">const</span> id = <span class="fn">setTimeout</span>(() <span class="kw">=></span> setQuery(draft), <span class="str">300</span>);
<span class="kw">return</span> () <span class="kw">=></span> <span class="fn">clearTimeout</span>(id);
}, [draft]);
<span class="kw">const</span> { data } = <span class="fn">useTasks</span>({ search: query });
<span class="kw">return</span> (
<<span class="fn">input</span>
value={draft}
onChange={(e) <span class="kw">=></span> setDraft(e.target.value)}
placeholder=<span class="str">"Filter tasks…"</span>
/>
);
}</pre></div>
<div class="tradeoffs">
<div class="row head">
<div class="cell">Pro</div>
<div class="cell">Con</div>
</div>
<div class="row">
<div class="cell pro">Zero new abstractions to learn</div>
<div class="cell con">Logic duplicated everywhere search exists</div>
</div>
<div class="row">
<div class="cell pro">Easy to step through in devtools</div>
<div class="cell con">Two pieces of state for one conceptual value</div>
</div>
<div class="row">
<div class="cell pro">No dependency or bundle change</div>
<div class="cell con">Delay constant is buried in component body</div>
</div>
</div>
<div class="chips">
<span class="chip">Bundle impact: <strong>+0 kb</strong></span>
<span class="chip">Testability: <strong>medium</strong></span>
<span class="chip">Reuse: <strong>low</strong></span>
<span class="chip">SSR safe: <strong>yes</strong></span>
</div>
</article>
<!-- ---------- Approach 2 ---------- -->
<article class="approach">
<header class="approach-head">
<h2><span class="num">02</span>Custom useDebounce hook</h2>
<p>Extract the timer into a shared hook under <code style="font-family:var(--mono)">src/hooks/</code>.</p>
</header>
<div class="code"><pre><span class="cm">// src/hooks/useDebounce.ts</span>
<span class="kw">export function</span> <span class="fn">useDebounce</span><T>(value: T, ms = <span class="str">300</span>): T {
<span class="kw">const</span> [debounced, setDebounced] = <span class="fn">useState</span>(value);
<span class="fn">useEffect</span>(() <span class="kw">=></span> {
<span class="kw">const</span> id = <span class="fn">setTimeout</span>(() <span class="kw">=></span> setDebounced(value), ms);
<span class="kw">return</span> () <span class="kw">=></span> <span class="fn">clearTimeout</span>(id);
}, [value, ms]);
<span class="kw">return</span> debounced;
}
<span class="cm">// TaskSearch.tsx</span>
<span class="kw">const</span> [draft, setDraft] = <span class="fn">useState</span>(<span class="str">''</span>);
<span class="kw">const</span> query = <span class="fn">useDebounce</span>(draft, <span class="str">300</span>);
<span class="kw">const</span> { data } = <span class="fn">useTasks</span>({ search: query });</pre></div>
<div class="tradeoffs">
<div class="row head">
<div class="cell">Pro</div>
<div class="cell">Con</div>
</div>
<div class="row">
<div class="cell pro">Single import reused across filter, command bar, board search</div>
<div class="cell con">One more file to maintain and document</div>
</div>
<div class="row">
<div class="cell pro">Trivial to unit test with fake timers</div>
<div class="cell con">Generic <code style="font-family:var(--mono)">T</code> hides intent slightly</div>
</div>
<div class="row">
<div class="cell pro">Delay is a visible, tunable argument</div>
<div class="cell con">Still re-renders on every keystroke</div>
</div>
</div>
<div class="chips">
<span class="chip">Bundle impact: <strong>+0.2 kb</strong></span>
<span class="chip">Testability: <strong>high</strong></span>
<span class="chip">Reuse: <strong>high</strong></span>
<span class="chip">SSR safe: <strong>yes</strong></span>
</div>
</article>
<!-- ---------- Approach 3 ---------- -->
<article class="approach">
<header class="approach-head">
<h2><span class="num">03</span>Tiny external library</h2>
<p>Adopt <code style="font-family:var(--mono)">use-debounce</code> for both values and callbacks.</p>
</header>
<div class="code"><pre><span class="kw">import</span> { useDebouncedCallback }
<span class="kw">from</span> <span class="str">'use-debounce'</span>;
<span class="kw">export function</span> <span class="fn">TaskSearch</span>() {
<span class="kw">const</span> [query, setQuery] = <span class="fn">useState</span>(<span class="str">''</span>);
<span class="kw">const</span> onChange = <span class="fn">useDebouncedCallback</span>(
(next: <span class="kw">string</span>) <span class="kw">=></span> setQuery(next),
<span class="str">300</span>,
{ leading: <span class="kw">false</span>, maxWait: <span class="str">1000</span> },
);
<span class="kw">const</span> { data } = <span class="fn">useTasks</span>({ search: query });
<span class="kw">return</span> (
<<span class="fn">input</span>
defaultValue=<span class="str">""</span>
onChange={(e) <span class="kw">=></span> onChange(e.target.value)}
/>
);
}</pre></div>
<div class="tradeoffs">
<div class="row head">
<div class="cell">Pro</div>
<div class="cell">Con</div>
</div>
<div class="row">
<div class="cell pro">leading / trailing / maxWait handled for us</div>
<div class="cell con">New runtime dependency to audit and update</div>
</div>
<div class="row">
<div class="cell pro">Callback form skips intermediate re-renders</div>
<div class="cell con">Uncontrolled input diverges from Acme form patterns</div>
</div>
<div class="row">
<div class="cell pro">Well-tested edge cases (unmount, flush, cancel)</div>
<div class="cell con">~1.4 kb gzipped for something we could own</div>
</div>
</div>
<div class="chips">
<span class="chip">Bundle impact: <strong>+1.4 kb</strong></span>
<span class="chip">Testability: <strong>high</strong></span>
<span class="chip">Reuse: <strong>high</strong></span>
<span class="chip">SSR safe: <strong>yes</strong></span>
</div>
</article>
</section>
<!-- ============================================================= -->
<aside class="reco">
<h2>Recommendation</h2>
<p>
Go with <strong>approach 02, the custom <code>useDebounce</code> hook</strong>.
Acme already has three places that hand-roll the inline pattern
(task filter, command palette, member picker), so extracting one
shared hook removes duplication without taking on a new dependency.
</p>
<p>
Revisit approach 03 only if we later need <code>maxWait</code> or
<code>flush()</code> semantics — the library earns its bundle cost
once the requirements outgrow a ten-line hook.
</p>
</aside>
</div>
</body>
</html>
<!-- Copyright 2026 Anthropic PBC · SPDX-License-Identifier: Apache-2.0 -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Empty state — four visual directions</title>
<style>
:root {
--ivory: #FAF9F5;
--slate: #141413;
--clay: #D97757;
--oat: #E3DACC;
--olive: #788C5D;
--gray-150: #F0EEE6;
--gray-300: #D1CFC5;
--gray-500: #87867F;
--gray-700: #3D3D3A;
--white: #FFFFFF;
--serif: ui-serif, Georgia, 'Times New Roman', serif;
--sans: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
--mono: ui-monospace, 'SF Mono', Menlo, Monaco, monospace;
}
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: var(--sans);
background: var(--ivory);
color: var(--gray-700);
line-height: 1.55;
-webkit-font-smoothing: antialiased;
padding-bottom: 96px;
}
/* ---------- sticky toolbar ---------- */
.toolbar {
position: sticky;
top: 0;
z-index: 10;
background: var(--ivory);
border-bottom: 1.5px solid var(--gray-300);
padding: 14px 32px;
display: flex;
align-items: center;
gap: 18px;
font-size: 13px;
}
.toolbar .title {
font-family: var(--mono);
font-size: 12px;
letter-spacing: 0.04em;
color: var(--gray-500);
margin-right: auto;
}
.toolbar .field {
display: flex;
align-items: center;
gap: 10px;
}
.toolbar .field > span {
color: var(--gray-700);
font-weight: 500;
}
.seg {
display: inline-flex;
border: 1.5px solid var(--gray-300);
border-radius: 8px;
overflow: hidden;
background: var(--white);
}
.seg label {
padding: 6px 14px;
cursor: pointer;
font-size: 13px;
color: var(--gray-700);
user-select: none;
}
.seg label + label {
border-left: 1.5px solid var(--gray-300);
}
.seg input { display: none; }
.seg input:checked + span {
color: var(--slate);
font-weight: 600;
}
.seg label:has(input:checked) {
background: var(--oat);
}
/* ---------- page header ---------- */
.page {
max-width: 1240px;
margin: 0 auto;
padding: 48px 32px 0;
}
header.page-head {
max-width: 720px;
margin-bottom: 40px;
}
.eyebrow {
font-size: 12px;
letter-spacing: 0.08em;
text-transform: uppercase;
color: var(--gray-500);
margin-bottom: 12px;
}
h1 {
font-family: var(--serif);
font-weight: 500;
font-size: 38px;
line-height: 1.15;
color: var(--slate);
margin-bottom: 18px;
letter-spacing: -0.01em;
}
.prompt-box {
background: var(--gray-150);
border: 1.5px solid var(--gray-300);
border-radius: 12px;
padding: 16px 20px;
font-size: 14.5px;
}
.prompt-box .label {
font-family: var(--mono);
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.06em;
color: var(--gray-500);
display: block;
margin-bottom: 6px;
}
/* ---------- artboard grid ---------- */
.board {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 32px;
}
@media (max-width: 960px) {
.board { grid-template-columns: 1fr; }
}
.artboard {
background: var(--white);
border: 1.5px solid var(--gray-300);
border-radius: 12px;
padding: 20px;
position: relative;
}
.tag {
position: absolute;
top: 14px;
left: 14px;
font-family: var(--mono);
font-size: 11px;
letter-spacing: 0.02em;
background: var(--oat);
color: var(--slate);
padding: 4px 10px;
border-radius: 8px;
z-index: 2;
}
.stage {
height: 280px;
border-radius: 8px;
border: 1.5px solid var(--gray-300);
background: var(--ivory);
display: flex;
align-items: center;
justify-content: center;
padding: 24px;
transition: background 0.15s, border-color 0.15s;
overflow: hidden;
}
.stage.dark {
background: var(--slate);
border-color: var(--slate);
}
.rationale {
margin-top: 16px;
font-size: 13px;
color: var(--gray-500);
line-height: 1.5;
}
/* =========================================================
Empty-state variants — each scoped under .es-*
Theme tokens flip when .stage.dark is present.
========================================================= */
.stage { --fg: var(--slate); --muted: var(--gray-500); --line: var(--gray-300); --panel: var(--white); }
.stage.dark { --fg: #F0EEE6; --muted: #9C9A93; --line: #3D3D3A; --panel: #1F1E1B; }
/* ---- A · Minimal ---- */
.es-a {
text-align: center;
max-width: 300px;
}
.es-a h3 {
font-family: var(--serif);
font-weight: 500;
font-size: 19px;
color: var(--fg);
margin-bottom: 6px;
}
.es-a p {
font-size: 13px;
color: var(--muted);
margin-bottom: 18px;
}
.es-a .btn {
display: inline-block;
font-size: 13px;
color: var(--fg);
border: 1.5px solid var(--line);
border-radius: 8px;
padding: 8px 16px;
background: transparent;
}
/* ---- B · Illustrated ---- */
.es-b {
text-align: center;
max-width: 320px;
}
.es-b svg {
display: block;
margin: 0 auto 18px;
}
.es-b h3 {
font-family: var(--serif);
font-weight: 500;
font-size: 19px;
color: var(--fg);
margin-bottom: 6px;
}
.es-b p {
font-size: 13px;
color: var(--muted);
margin-bottom: 16px;
}
.es-b .btn {
display: inline-block;
font-size: 13px;
font-weight: 500;
color: var(--white);
background: var(--clay);
border-radius: 8px;
padding: 8px 16px;
}
.stage.dark .es-b .btn { color: var(--slate); background: var(--oat); }
/* ---- C · Playful ---- */
.es-c {
text-align: center;
max-width: 300px;
}
.es-c .float {
width: 56px;
height: 56px;
margin: 0 auto 20px;
position: relative;
animation: bob 3.2s ease-in-out infinite;
}
.es-c .float .card {
position: absolute;
inset: 0;
border-radius: 10px;
background: var(--panel);
border: 1.5px solid var(--line);
}
.es-c .float .card:nth-child(1) { transform: rotate(-8deg) translate(-6px, 4px); opacity: 0.5; }
.es-c .float .card:nth-child(2) { transform: rotate( 6deg) translate( 6px, 2px); opacity: 0.75; }
.es-c .float .card:nth-child(3) { background: var(--oat); border-color: var(--oat); }
.stage.dark .es-c .float .card:nth-child(3) { background: var(--clay); border-color: var(--clay); }
.es-c .shadow {
width: 44px;
height: 8px;
margin: -8px auto 22px;
border-radius: 50%;
background: rgba(0,0,0,0.12);
filter: blur(2px);
animation: shadow 3.2s ease-in-out infinite;
}
.stage.dark .es-c .shadow { background: rgba(0,0,0,0.5); }
.es-c h3 {
font-family: var(--serif);
font-weight: 500;
font-size: 19px;
color: var(--fg);
margin-bottom: 6px;
}
.es-c p {
font-size: 13px;
color: var(--muted);
}
@keyframes bob {
0%, 100% { transform: translateY(0); }
50% { transform: translateY(-10px); }
}
@keyframes shadow {
0%, 100% { transform: scaleX(1); opacity: 0.9; }
50% { transform: scaleX(0.8); opacity: 0.5; }
}
/* ---- D · Instructional ---- */
.es-d {
width: 100%;
max-width: 360px;
}
.es-d h3 {
font-family: var(--serif);
font-weight: 500;
font-size: 18px;
color: var(--fg);
margin-bottom: 14px;
}
.es-d ol {
list-style: none;
counter-reset: step;
display: flex;
flex-direction: column;
gap: 10px;
}
.es-d li {
counter-increment: step;
display: flex;
align-items: flex-start;
gap: 12px;
background: var(--panel);
border: 1.5px solid var(--line);
border-radius: 8px;
padding: 10px 14px;
font-size: 13px;
color: var(--fg);
}
.es-d li::before {
content: counter(step);
font-family: var(--mono);
font-size: 11px;
flex: 0 0 20px;
height: 20px;
border-radius: 50%;
background: var(--oat);
color: var(--slate);
display: inline-flex;
align-items: center;
justify-content: center;
margin-top: 1px;
}
.es-d li span { color: var(--muted); display: block; font-size: 12px; margin-top: 2px; }
</style>
</head>
<body>
<div class="toolbar">
<div class="title">Acme · design exploration</div>
<div class="field">
<span>Background:</span>
<div class="seg" id="bg-seg">
<label><input type="radio" name="bg" value="light" checked><span>Light</span></label>
<label><input type="radio" name="bg" value="dark"><span>Dark</span></label>
</div>
</div>
</div>
<div class="page">
<header class="page-head">
<div class="eyebrow">Exploration · Empty states</div>
<h1>Four visual directions for the “no tasks yet” state</h1>
<div class="prompt-box">
<span class="label">Prompt</span>
Explore four visual directions for our empty-state component. Render each
live so we can compare tone, density, and how well they hold up on light
and dark surfaces.
</div>
</header>
<section class="board">
<!-- ================= A — Minimal ================= -->
<article class="artboard">
<span class="tag">A — Minimal</span>
<div class="stage">
<div class="es-a">
<h3>No tasks yet</h3>
<p>When you create a task it will show up here.</p>
<span class="btn">New task</span>
</div>
</div>
<p class="rationale">
Pure typography, single quiet action. Reads as calm and confident;
assumes the surrounding UI already carries enough personality.
</p>
</article>
<!-- ================= B — Illustrated ================= -->
<article class="artboard">
<span class="tag">B — Illustrated</span>
<div class="stage">
<div class="es-b">
<svg width="120" height="90" viewBox="0 0 120 90" aria-hidden="true">
<rect x="14" y="20" width="72" height="54" rx="8"
fill="var(--panel)" stroke="var(--line)" stroke-width="1.5"/>
<rect x="34" y="10" width="72" height="54" rx="8"
fill="var(--oat)"/>
<line x1="46" y1="26" x2="92" y2="26"
stroke="var(--slate)" stroke-width="2" stroke-linecap="round"/>
<line x1="46" y1="38" x2="80" y2="38"
stroke="var(--slate)" stroke-width="2" stroke-linecap="round" opacity="0.5"/>
<circle cx="98" cy="60" r="12" fill="var(--clay)"/>
<path d="M98 55 v10 M93 60 h10"
stroke="white" stroke-width="2" stroke-linecap="round"/>
</svg>
<h3>Start your first list</h3>
<p>Group related work and watch progress roll up automatically.</p>
<span class="btn">Create a task</span>
</div>
</div>
<p class="rationale">
A small geometric spot illustration anchors the eye and explains the
object model (lists contain tasks) without a wall of copy.
</p>
</article>
<!-- ================= C — Playful ================= -->
<article class="artboard">
<span class="tag">C — Playful</span>
<div class="stage">
<div class="es-c">
<div class="float">
<div class="card"></div>
<div class="card"></div>
<div class="card"></div>
</div>
<div class="shadow"></div>
<h3>Nothing on your plate</h3>
<p>Enjoy the quiet, or add something to get moving.</p>
</div>
</div>
<p class="rationale">
A gently bobbing stack adds life to an otherwise static screen. Motion
is subtle enough to loop indefinitely without drawing complaints.
</p>
</article>
<!-- ================= D — Instructional ================= -->
<article class="artboard">
<span class="tag">D — Instructional</span>
<div class="stage">
<div class="es-d">
<h3>Set up this project</h3>
<ol>
<li>
Create your first task
<span>Give it a name and an owner.</span>
</li>
<li>
Add a due date
<span>Acme will surface it on the timeline.</span>
</li>
<li>
Invite a teammate
<span>Shared projects stay in sync automatically.</span>
</li>
</ol>
</div>
</div>
<p class="rationale">
Treats the empty state as onboarding. Higher density, but every line is
actionable — best when the user is new to the product, not just the view.
</p>
</article>
</section>
</div>
<script>
const stages = document.querySelectorAll('.stage');
document.getElementById('bg-seg').addEventListener('change', (e) => {
const dark = e.target.value === 'dark';
stages.forEach((s) => s.classList.toggle('dark', dark));
});
</script>
</body>
</html>
<!-- Copyright 2026 Anthropic PBC · SPDX-License-Identifier: Apache-2.0 -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>PR #247 — Review Summary</title>
<style>
:root {
--ivory: #FAF9F5;
--slate: #141413;
--clay: #D97757;
--oat: #E3DACC;
--olive: #788C5D;
--rust: #B04A3F;
--gray-150: #F0EEE6;
--gray-300: #D1CFC5;
--gray-500: #87867F;
--gray-700: #3D3D3A;
--serif: ui-serif, Georgia, 'Times New Roman', serif;
--sans: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
--mono: ui-monospace, 'SF Mono', Menlo, Monaco, monospace;
}
* { box-sizing: border-box; margin: 0; padding: 0; }
html { scroll-behavior: smooth; }
body {
background: var(--ivory);
color: var(--gray-700);
font-family: var(--sans);
font-size: 15px;
line-height: 1.6;
padding: 48px 24px 80px;
}
.page {
max-width: 920px;
margin: 0 auto;
}
/* ---------- Header ---------- */
header.pr-head {
border: 1.5px solid var(--gray-300);
border-radius: 12px;
padding: 28px 32px;
background: #fff;
margin-bottom: 36px;
}
.repo-line {
font-family: var(--mono);
font-size: 12.5px;
color: var(--gray-500);
letter-spacing: 0.01em;
margin-bottom: 10px;
}
h1 {
font-family: var(--serif);
font-weight: 500;
font-size: 30px;
line-height: 1.25;
color: var(--slate);
margin-bottom: 18px;
}
.meta-row {
display: flex;
align-items: center;
flex-wrap: wrap;
gap: 20px;
}
.author {
display: flex;
align-items: center;
gap: 10px;
}
.avatar {
width: 36px;
height: 36px;
border-radius: 50%;
background: var(--oat);
color: var(--slate);
display: flex;
align-items: center;
justify-content: center;
font-weight: 600;
font-size: 13px;
letter-spacing: 0.02em;
border: 1.5px solid var(--gray-300);
}
.author-name { font-weight: 500; color: var(--slate); }
.author-sub { font-size: 12px; color: var(--gray-500); }
.branch {
font-family: var(--mono);
font-size: 12.5px;
color: var(--gray-700);
background: var(--gray-150);
border: 1.5px solid var(--gray-300);
border-radius: 8px;
padding: 6px 10px;
}
.branch .arrow { color: var(--gray-500); margin: 0 6px; }
.stat {
font-family: var(--mono);
font-size: 13px;
}
.stat .add { color: var(--olive); font-weight: 600; }
.stat .del { color: var(--rust); font-weight: 600; }
.stat .files { color: var(--gray-500); margin-left: 10px; }
/* ---------- Section blocks ---------- */
section { margin-bottom: 40px; }
h2 {
font-family: var(--serif);
font-weight: 500;
font-size: 21px;
color: var(--slate);
margin-bottom: 14px;
}
.prose ul {
list-style: none;
padding: 0;
}
.prose li {
position: relative;
padding-left: 22px;
margin-bottom: 10px;
}
.prose li::before {
content: "";
position: absolute;
left: 4px;
top: 9px;
width: 6px;
height: 6px;
background: var(--gray-500);
border-radius: 2px;
}
/* ---------- Risk map ---------- */
.risk-map {
display: flex;
flex-wrap: wrap;
gap: 10px;
}
.chip {
display: inline-flex;
align-items: center;
gap: 8px;
padding: 8px 12px;
border-radius: 8px;
border: 1.5px solid var(--gray-300);
font-family: var(--mono);
font-size: 12.5px;
color: var(--slate);
text-decoration: none;
background: #fff;
transition: transform 0.12s ease;
}
.chip:hover { transform: translateY(-1px); }
.chip .dot {
width: 9px;
height: 9px;
border-radius: 50%;
flex-shrink: 0;
}
.chip.safe { background: rgba(120,140,93,0.10); border-color: rgba(120,140,93,0.45); }
.chip.safe .dot { background: var(--olive); }
.chip.medium { background: var(--oat); }
.chip.medium .dot { background: #B89B6E; }
.chip.attention { background: rgba(217,119,87,0.12); border-color: rgba(217,119,87,0.55); }
.chip.attention .dot { background: var(--clay); }
.legend {
margin-top: 12px;
font-size: 12px;
color: var(--gray-500);
display: flex;
gap: 18px;
}
.legend span { display: inline-flex; align-items: center; gap: 6px; }
.legend .dot { width: 8px; height: 8px; border-radius: 50%; }
/* ---------- File sections ---------- */
.file-card {
border: 1.5px solid var(--gray-300);
border-radius: 12px;
background: #fff;
margin-bottom: 24px;
overflow: hidden;
scroll-margin-top: 20px;
}
.file-head {
padding: 16px 20px;
border-bottom: 1.5px solid var(--gray-150);
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
}
.file-path {
font-family: var(--mono);
font-size: 13.5px;
color: var(--slate);
}
.file-delta {
font-family: var(--mono);
font-size: 12px;
color: var(--gray-500);
}
.file-delta .add { color: var(--olive); }
.file-delta .del { color: var(--rust); }
.risk-tag {
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.06em;
padding: 3px 8px;
border-radius: 6px;
font-weight: 600;
}
.risk-tag.safe { background: rgba(120,140,93,0.15); color: var(--olive); }
.risk-tag.medium { background: var(--oat); color: #7A6A4F; }
.risk-tag.attention { background: rgba(217,119,87,0.15); color: var(--clay); }
/* ---------- Diff block ---------- */
.diff {
background: var(--slate);
font-family: var(--mono);
font-size: 12.5px;
line-height: 1.7;
overflow-x: auto;
}
.diff-row {
display: grid;
grid-template-columns: 48px 18px 1fr;
align-items: baseline;
padding: 0 14px 0 0;
white-space: pre;
}
.diff-row .ln {
text-align: right;
padding-right: 14px;
color: var(--gray-500);
user-select: none;
}
.diff-row .mark {
text-align: center;
color: var(--gray-500);
}
.diff-row .code { color: #E8E6DC; }
.diff-row.ctx .code { color: #B8B6AC; }
.diff-row.add { background: rgba(120,140,93,0.15); }
.diff-row.add .mark { color: var(--olive); }
.diff-row.del { background: rgba(176,74,63,0.15); }
.diff-row.del .mark { color: var(--rust); }
.diff-row.hunk {
background: rgba(255,255,255,0.04);
color: var(--gray-500);
}
.diff-row.hunk .code { color: var(--gray-500); }
/* ---------- Review comments ---------- */
.comments {
padding: 18px 20px 20px;
display: flex;
flex-direction: column;
gap: 14px;
background: var(--gray-150);
}
.bubble {
position: relative;
background: #fff;
border: 1.5px solid var(--gray-300);
border-left-width: 4px;
border-radius: 8px;
padding: 12px 14px 12px 16px;
max-width: 680px;
}
.bubble.blocking { border-left-color: var(--clay); }
.bubble.nit { border-left-color: var(--gray-300); }
.bubble::before {
content: "";
position: absolute;
left: -9px;
top: 16px;
width: 12px;
height: 12px;
background: #fff;
border-left: 1.5px solid var(--gray-300);
border-bottom: 1.5px solid var(--gray-300);
transform: rotate(45deg);
}
.bubble.blocking::before { border-left-color: var(--clay); border-bottom-color: var(--clay); }
.bubble .anchor {
font-family: var(--mono);
font-size: 11.5px;
color: var(--gray-500);
margin-bottom: 4px;
}
.bubble .label {
display: inline-block;
font-size: 10.5px;
text-transform: uppercase;
letter-spacing: 0.08em;
font-weight: 700;
margin-right: 8px;
}
.bubble.blocking .label { color: var(--clay); }
.bubble.nit .label { color: var(--gray-500); }
.bubble p { font-size: 13.5px; color: var(--gray-700); }
.bubble code {
font-family: var(--mono);
font-size: 12.5px;
background: var(--gray-150);
padding: 1px 5px;
border-radius: 4px;
}
/* ---------- Collapsed files ---------- */
details.file-collapsed {
border: 1.5px solid var(--gray-300);
border-radius: 12px;
background: #fff;
margin-bottom: 14px;
scroll-margin-top: 20px;
}
details.file-collapsed summary {
list-style: none;
cursor: pointer;
padding: 14px 20px;
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
}
details.file-collapsed summary::-webkit-details-marker { display: none; }
details.file-collapsed summary::after {
content: "+";
font-family: var(--mono);
color: var(--gray-500);
font-size: 16px;
}
details.file-collapsed[open] summary::after { content: "−"; }
details.file-collapsed .body {
padding: 0 20px 16px;
font-size: 13.5px;
color: var(--gray-700);
}
/* ---------- Footer ---------- */
footer.next-steps {
border: 1.5px solid var(--gray-300);
border-radius: 12px;
background: #fff;
padding: 24px 28px;
}
.checklist { list-style: none; padding: 0; }
.checklist li {
display: flex;
align-items: flex-start;
gap: 12px;
padding: 8px 0;
}
.checklist input[type="checkbox"] {
width: 17px;
height: 17px;
margin-top: 2px;
accent-color: var(--olive);
cursor: pointer;
}
.checklist label { cursor: pointer; flex: 1; }
.checklist code {
font-family: var(--mono);
font-size: 12.5px;
background: var(--gray-150);
padding: 1px 5px;
border-radius: 4px;
}
</style>
</head>
<body>
<div class="page">
<header class="pr-head">
<div class="repo-line">acme/web · Pull Request #247</div>
<h1>Add optimistic updates to task list mutations</h1>
<div class="meta-row">
<div class="author">
<div class="avatar">MO</div>
<div>
<div class="author-name">Mira Okafor</div>
<div class="author-sub">opened 2 days ago</div>
</div>
</div>
<div class="branch">
mo/optimistic-tasks <span class="arrow">→</span> main
</div>
<div class="stat">
<span class="add">+142</span> / <span class="del">−38</span>
<span class="files">6 files changed</span>
</div>
</div>
</header>
<section class="prose">
<h2>What this PR does</h2>
<ul>
<li>Replaces the await-then-refetch pattern in <code style="font-family:var(--mono);font-size:12.5px;background:var(--gray-150);padding:1px 5px;border-radius:4px">TaskList</code> with optimistic cache writes, so toggling or reordering a task feels instant instead of waiting ~300ms for the round-trip.</li>
<li>Introduces a small <code style="font-family:var(--mono);font-size:12.5px;background:var(--gray-150);padding:1px 5px;border-radius:4px">useOptimisticTasks</code> hook that wraps the mutation, snapshots the previous list, and rolls back on error.</li>
<li>Extends the API client to accept an idempotency key per mutation and adds a toast when a rollback fires.</li>
</ul>
</section>
<section>
<h2>Risk map</h2>
<div class="risk-map">
<a class="chip attention" href="#file-hook"><span class="dot"></span>useOptimisticTasks.ts</a>
<a class="chip medium" href="#file-tasklist"><span class="dot"></span>TaskList.tsx</a>
<a class="chip medium" href="#file-api"><span class="dot"></span>api/tasks.ts</a>
<a class="chip safe" href="#file-toast"><span class="dot"></span>Toast.tsx</a>
<a class="chip safe" href="#file-types"><span class="dot"></span>types/task.ts</a>
<a class="chip safe" href="#file-test"><span class="dot"></span>TaskList.test.tsx</a>
</div>
<div class="legend">
<span><span class="dot" style="background:var(--olive)"></span> safe</span>
<span><span class="dot" style="background:#B89B6E"></span> worth a look</span>
<span><span class="dot" style="background:var(--clay)"></span> needs attention</span>
</div>
</section>
<section>
<h2>Files</h2>
<!-- File 1: hook (attention) -->
<article class="file-card" id="file-hook">
<div class="file-head">
<div>
<div class="file-path">src/hooks/useOptimisticTasks.ts</div>
</div>
<div style="display:flex;align-items:center;gap:12px">
<span class="risk-tag attention">needs attention</span>
<span class="file-delta"><span class="add">+58</span> <span class="del">−0</span></span>
</div>
</div>
<div class="diff">
<div class="diff-row hunk"><span class="ln"></span><span class="mark"></span><span class="code">@@ -0,0 +1,58 @@</span></div>
<div class="diff-row add"><span class="ln">1</span><span class="mark">+</span><span class="code">import { useMutation, useQueryClient } from '@tanstack/react-query';</span></div>
<div class="diff-row add"><span class="ln">2</span><span class="mark">+</span><span class="code">import { updateTask, TaskPatch } from '../api/tasks';</span></div>
<div class="diff-row add"><span class="ln">3</span><span class="mark">+</span><span class="code">import type { Task } from '../types/task';</span></div>
<div class="diff-row add"><span class="ln">4</span><span class="mark">+</span><span class="code"> </span></div>
<div class="diff-row add"><span class="ln">5</span><span class="mark">+</span><span class="code">export function useOptimisticTasks(boardId: string) {</span></div>
<div class="diff-row add"><span class="ln">6</span><span class="mark">+</span><span class="code"> const qc = useQueryClient();</span></div>
<div class="diff-row add"><span class="ln">7</span><span class="mark">+</span><span class="code"> const key = ['tasks', boardId];</span></div>
<div class="diff-row add"><span class="ln">8</span><span class="mark">+</span><span class="code"> </span></div>
<div class="diff-row add"><span class="ln">9</span><span class="mark">+</span><span class="code"> return useMutation({</span></div>
<div class="diff-row add"><span class="ln">10</span><span class="mark">+</span><span class="code"> mutationFn: (patch: TaskPatch) => updateTask(patch),</span></div>
<div class="diff-row add"><span class="ln">11</span><span class="mark">+</span><span class="code"> onMutate: async (patch) => {</span></div>
<div class="diff-row add"><span class="ln">12</span><span class="mark">+</span><span class="code"> const prev = qc.getQueryData<Task[]>(key);</span></div>
<div class="diff-row add"><span class="ln">13</span><span class="mark">+</span><span class="code"> qc.setQueryData<Task[]>(key, (old = []) =></span></div>
<div class="diff-row add"><span class="ln">14</span><span class="mark">+</span><span class="code"> old.map(t => t.id === patch.id ? { ...t, ...patch } : t)</span></div>
<div class="diff-row add"><span class="ln">15</span><span class="mark">+</span><span class="code"> );</span></div>
<div class="diff-row add"><span class="ln">16</span><span class="mark">+</span><span class="code"> return { prev };</span></div>
<div class="diff-row add"><span class="ln">17</span><span class="mark">+</span><span class="code"> },</span></div>
<div class="diff-row add"><span class="ln">18</span><span class="mark">+</span><span class="code"> onError: (_e, _p, ctx) => qc.setQueryData(key, ctx?.prev),</span></div>
<div class="diff-row add"><span class="ln">19</span><span class="mark">+</span><span class="code"> });</span></div>
<div class="diff-row add"><span class="ln">20</span><span class="mark">+</span><span class="code">}</span></div>
</div>
<div class="comments">
<div class="bubble blocking">
<div class="anchor">line 11</div>
<p><span class="label">Blocking</span><code>onMutate</code> doesn't call <code>qc.cancelQueries(key)</code> first. If a background refetch lands between the optimistic write and the server response, it will clobber the optimistic state and the UI will flicker back to the old value.</p>
</div>
<div class="bubble nit">
<div class="anchor">line 18</div>
<p><span class="label">Nit</span>Rollback restores the list but never surfaces the error. Consider wiring the existing <code>pushToast</code> here so users know the toggle didn't stick.</p>
</div>
</div>
</article>
<!-- File 2: TaskList (medium) -->
<article class="file-card" id="file-tasklist">
<div class="file-head">
<div>
<div class="file-path">src/components/TaskList.tsx</div>
</div>
<div style="display:flex;align-items:center;gap:12px">
<span class="risk-tag medium">worth a look</span>
<span class="file-delta"><span class="add">+31</span> <span class="del">−24</span></span>
</div>
</div>
<div class="diff">
<div class="diff-row hunk"><span class="ln"></span><span class="mark"></span><span class="code">@@ -42,14 +42,17 @@ export function TaskList({ boardId }: Props) {</span></div>
<div class="diff-row ctx"><span class="ln">42</span><span class="mark"> </span><span class="code"> const { data: tasks } = useTasks(boardId);</span></div>
<div class="diff-row del"><span class="ln">43</span><span class="mark">-</span><span class="code"> const [pending, setPending] = useState<string | null>(null);</span></div>
<div class="diff-row del"><span class="ln">44</span><span class="mark">-</span><span class="code"> </span></div>
<div class="diff-row del"><span class="ln">45</span><span class="mark">-</span><span class="code"> async function toggle(task: Task) {</span></div>
<div class="diff-row del"><span class="ln">46</span><span class="mark">-</span><span class="code"> setPending(task.id);</span></div>
<div class="diff-row del"><span class="ln">47</span><span class="mark">-</span><span class="code"> await updateTask({ id: task.id, done: !task.done });</span></div>
<div class="diff-row del"><span class="ln">48</span><span class="mark">-</span><span class="code"> await refetch();</span></div>
<div class="diff-row del"><span class="ln">49</span><span class="mark">-</span><span class="code"> setPending(null);</span></div>
<div class="diff-row del"><span class="ln">50</span><span class="mark">-</span><span class="code"> }</span></div>
<div class="diff-row add"><span class="ln">43</span><span class="mark">+</span><span class="code"> const { mutate, isPending } = useOptimisticTasks(boardId);</span></div>
<div class="diff-row add"><span class="ln">44</span><span class="mark">+</span><span class="code"> </span></div>
<div class="diff-row add"><span class="ln">45</span><span class="mark">+</span><span class="code"> const toggle = (task: Task) =></span></div>
<div class="diff-row add"><span class="ln">46</span><span class="mark">+</span><span class="code"> mutate({ id: task.id, done: !task.done });</span></div>
<div class="diff-row ctx"><span class="ln">47</span><span class="mark"> </span><span class="code"> </span></div>
<div class="diff-row ctx"><span class="ln">48</span><span class="mark"> </span><span class="code"> return (</span></div>
<div class="diff-row ctx"><span class="ln">49</span><span class="mark"> </span><span class="code"> <ul className="tasks"></span></div>
<div class="diff-row del"><span class="ln">50</span><span class="mark">-</span><span class="code"> {tasks?.map(t => <TaskRow key={t.id} task={t} busy={pending === t.id} />)}</span></div>
<div class="diff-row add"><span class="ln">50</span><span class="mark">+</span><span class="code"> {tasks?.map(t => <TaskRow key={t.id} task={t} onToggle={toggle} />)}</span></div>
<div class="diff-row ctx"><span class="ln">51</span><span class="mark"> </span><span class="code"> </ul></span></div>
</div>
<div class="comments">
<div class="bubble nit">
<div class="anchor">line 43</div>
<p><span class="label">Nit</span><code>isPending</code> is destructured but never read. Either drop it or pass it to <code>TaskRow</code> so the checkbox can dim while the request is in flight.</p>
</div>
</div>
</article>
<!-- File 3: api/tasks (medium) -->
<article class="file-card" id="file-api">
<div class="file-head">
<div>
<div class="file-path">src/api/tasks.ts</div>
</div>
<div style="display:flex;align-items:center;gap:12px">
<span class="risk-tag medium">worth a look</span>
<span class="file-delta"><span class="add">+19</span> <span class="del">−6</span></span>
</div>
</div>
<div class="diff">
<div class="diff-row hunk"><span class="ln"></span><span class="mark"></span><span class="code">@@ -12,10 +12,15 @@ export type TaskPatch = Partial<Task> & { id: string };</span></div>
<div class="diff-row ctx"><span class="ln">12</span><span class="mark"> </span><span class="code"> </span></div>
<div class="diff-row del"><span class="ln">13</span><span class="mark">-</span><span class="code">export async function updateTask(patch: TaskPatch) {</span></div>
<div class="diff-row del"><span class="ln">14</span><span class="mark">-</span><span class="code"> return http.patch(`/tasks/${patch.id}`, patch);</span></div>
<div class="diff-row add"><span class="ln">13</span><span class="mark">+</span><span class="code">export async function updateTask(</span></div>
<div class="diff-row add"><span class="ln">14</span><span class="mark">+</span><span class="code"> patch: TaskPatch,</span></div>
<div class="diff-row add"><span class="ln">15</span><span class="mark">+</span><span class="code"> key = crypto.randomUUID(),</span></div>
<div class="diff-row add"><span class="ln">16</span><span class="mark">+</span><span class="code">) {</span></div>
<div class="diff-row add"><span class="ln">17</span><span class="mark">+</span><span class="code"> return http.patch(`/tasks/${patch.id}`, patch, {</span></div>
<div class="diff-row add"><span class="ln">18</span><span class="mark">+</span><span class="code"> headers: { 'Idempotency-Key': key },</span></div>
<div class="diff-row add"><span class="ln">19</span><span class="mark">+</span><span class="code"> });</span></div>
<div class="diff-row ctx"><span class="ln">20</span><span class="mark"> </span><span class="code">}</span></div>
</div>
<div class="comments">
<div class="bubble blocking">
<div class="anchor">line 15</div>
<p><span class="label">Blocking</span>Generating the idempotency key as a default parameter means retries from the mutation layer get a <em>new</em> key each time, which defeats the purpose. The key should be minted once in <code>onMutate</code> and threaded through.</p>
</div>
</div>
</article>
<!-- Collapsed files -->
<details class="file-collapsed" id="file-toast">
<summary>
<span class="file-path">src/components/Toast.tsx</span>
<span style="display:flex;align-items:center;gap:12px">
<span class="risk-tag safe">safe</span>
<span class="file-delta"><span class="add">+14</span> <span class="del">−2</span></span>
</span>
</summary>
<div class="body">Adds a <code style="font-family:var(--mono)">variant="warning"</code> style and exports <code style="font-family:var(--mono)">pushToast</code>. Purely additive, no behaviour change for existing call sites.</div>
</details>
<details class="file-collapsed" id="file-types">
<summary>
<span class="file-path">src/types/task.ts</span>
<span style="display:flex;align-items:center;gap:12px">
<span class="risk-tag safe">safe</span>
<span class="file-delta"><span class="add">+6</span> <span class="del">−2</span></span>
</span>
</summary>
<div class="body">Widens <code style="font-family:var(--mono)">Task.status</code> to include <code style="font-family:var(--mono)">"archived"</code> and adds an optional <code style="font-family:var(--mono)">updatedAt</code> timestamp. Type-only change.</div>
</details>
<details class="file-collapsed" id="file-test">
<summary>
<span class="file-path">src/components/__tests__/TaskList.test.tsx</span>
<span style="display:flex;align-items:center;gap:12px">
<span class="risk-tag safe">safe</span>
<span class="file-delta"><span class="add">+14</span> <span class="del">−4</span></span>
</span>
</summary>
<div class="body">Adds a test asserting the row updates synchronously after click, and one asserting rollback when the mocked request rejects. Both pass locally.</div>
</details>
</section>
<footer class="next-steps">
<h2>Suggested next steps</h2>
<ul class="checklist">
<li>
<input type="checkbox" id="step1">
<label for="step1">Add <code>await qc.cancelQueries(key)</code> at the top of <code>onMutate</code> in <code>useOptimisticTasks.ts</code>.</label>
</li>
<li>
<input type="checkbox" id="step2">
<label for="step2">Move idempotency-key generation into the mutation context so retries reuse the same key.</label>
</li>
<li>
<input type="checkbox" id="step3">
<label for="step3">Either consume <code>isPending</code> in <code>TaskRow</code> or remove it from the destructure to keep lint clean.</label>
</li>
</ul>
</footer>
</div>
<script>
// Briefly highlight a file card when reached via the risk-map anchors.
document.querySelectorAll('.risk-map a').forEach(function (a) {
a.addEventListener('click', function () {
var target = document.querySelector(a.getAttribute('href'));
if (!target) return;
target.style.transition = 'box-shadow 180ms ease';
target.style.boxShadow = '0 0 0 3px rgba(217,119,87,0.35)';
setTimeout(function () { target.style.boxShadow = 'none'; }, 1400);
});
});
</script>
</body>
</html>
<!-- Copyright 2026 Anthropic PBC · SPDX-License-Identifier: Apache-2.0 -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>How authentication flows through acme/web</title>
<style>
:root {
--ivory: #FAF9F5;
--slate: #141413;
--clay: #D97757;
--oat: #E3DACC;
--olive: #788C5D;
--rust: #B04A3F;
--gray-150: #F0EEE6;
--gray-300: #D1CFC5;
--gray-500: #87867F;
--gray-700: #3D3D3A;
--serif: ui-serif, Georgia, 'Times New Roman', serif;
--sans: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
--mono: ui-monospace, 'SF Mono', Menlo, Monaco, monospace;
}
* { box-sizing: border-box; margin: 0; padding: 0; }
body {
background: var(--ivory);
color: var(--gray-700);
font-family: var(--sans);
font-size: 15px;
line-height: 1.65;
padding: 48px 24px 80px;
}
.page {
max-width: 1080px;
margin: 0 auto;
display: grid;
grid-template-columns: minmax(0, 1fr) 280px;
gap: 40px;
}
@media (max-width: 960px) {
.page { grid-template-columns: 1fr; }
}
/* ---------- Header ---------- */
header {
grid-column: 1 / -1;
margin-bottom: 8px;
}
.repo-line {
font-family: var(--mono);
font-size: 12.5px;
color: var(--gray-500);
margin-bottom: 10px;
}
h1 {
font-family: var(--serif);
font-weight: 500;
font-size: 32px;
line-height: 1.25;
color: var(--slate);
margin-bottom: 16px;
}
.summary {
max-width: 760px;
font-size: 15.5px;
}
.summary code { font-family: var(--mono); font-size: 13px; }
h2 {
font-family: var(--serif);
font-weight: 500;
font-size: 22px;
color: var(--slate);
margin: 36px 0 16px;
}
/* ---------- Diagram ---------- */
.diagram-panel {
border: 1.5px solid var(--gray-300);
border-radius: 12px;
background: #fff;
padding: 20px;
overflow-x: auto;
}
svg.flow { display: block; max-width: 100%; }
.flow text {
font-family: var(--mono);
font-size: 12px;
fill: var(--slate);
}
.flow .sub { font-size: 10px; fill: var(--gray-500); }
.flow .box { fill: #fff; stroke: var(--gray-300); stroke-width: 1.5; }
.flow .box.hot { fill: rgba(217,119,87,0.10); stroke: var(--clay); }
.flow .arrow { stroke: var(--gray-500); stroke-width: 1.5; fill: none; }
/* ---------- Walkthrough ---------- */
.step {
display: grid;
grid-template-columns: 44px 1fr;
gap: 18px;
padding: 20px 0;
border-bottom: 1.5px solid var(--gray-150);
}
.step:last-of-type { border-bottom: none; }
.badge {
width: 34px;
height: 34px;
border-radius: 50%;
background: var(--oat);
border: 1.5px solid var(--gray-300);
display: flex;
align-items: center;
justify-content: center;
font-family: var(--mono);
font-weight: 600;
color: var(--slate);
font-size: 14px;
}
.step.hot .badge {
background: rgba(217,119,87,0.14);
border-color: var(--clay);
color: var(--clay);
}
.step-loc {
font-family: var(--mono);
font-size: 13px;
color: var(--slate);
margin-bottom: 6px;
}
.step-loc .range { color: var(--gray-500); }
.step-body p { margin-bottom: 10px; }
details.snippet { margin-top: 6px; }
details.snippet summary {
list-style: none;
cursor: pointer;
font-size: 12.5px;
color: var(--gray-500);
font-family: var(--mono);
display: inline-flex;
align-items: center;
gap: 6px;
padding: 4px 0;
user-select: none;
}
details.snippet summary::-webkit-details-marker { display: none; }
details.snippet summary::before {
content: "▸";
font-size: 10px;
transition: transform 0.15s ease;
}
details.snippet[open] summary::before { transform: rotate(90deg); }
pre.code {
background: var(--slate);
color: #E8E6DC;
font-family: var(--mono);
font-size: 12.5px;
line-height: 1.7;
border-radius: 8px;
padding: 14px 16px;
overflow-x: auto;
margin-top: 10px;
}
pre.code .dim { color: var(--gray-500); }
pre.code .kw { color: #C9B98A; }
pre.code .str { color: #A8BC8C; }
/* ---------- Sidebar ---------- */
aside {
position: sticky;
top: 24px;
align-self: start;
}
.panel {
border: 1.5px solid var(--gray-300);
border-radius: 12px;
background: #fff;
padding: 18px 20px;
margin-bottom: 20px;
}
.panel h3 {
font-family: var(--sans);
font-size: 11px;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 0.08em;
color: var(--gray-500);
margin-bottom: 12px;
}
.key-files { list-style: none; padding: 0; }
.key-files li { margin-bottom: 12px; }
.key-files li:last-child { margin-bottom: 0; }
.key-files .path {
font-family: var(--mono);
font-size: 12px;
color: var(--slate);
display: block;
margin-bottom: 2px;
word-break: break-all;
}
.key-files .desc {
font-size: 12.5px;
color: var(--gray-500);
line-height: 1.45;
}
.gotchas {
border: 1.5px solid var(--clay);
border-radius: 12px;
background: rgba(217,119,87,0.06);
padding: 18px 20px;
}
.gotchas h3 {
font-family: var(--sans);
font-size: 11px;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 0.08em;
color: var(--clay);
margin-bottom: 10px;
}
.gotchas ul { list-style: none; padding: 0; }
.gotchas li {
position: relative;
padding-left: 16px;
font-size: 13px;
margin-bottom: 8px;
}
.gotchas li::before {
content: "";
position: absolute;
left: 0; top: 8px;
width: 5px; height: 5px;
background: var(--clay);
border-radius: 2px;
}
.gotchas code { font-family: var(--mono); font-size: 11.5px; }
</style>
</head>
<body>
<div class="page">
<header>
<div class="repo-line">acme/web · architecture note</div>
<h1>How authentication flows through the codebase</h1>
<p class="summary">
Acme uses cookie-based sessions: the browser never holds a bearer token directly. Every authenticated request hits <code>/api/*</code>, passes through a single <code>verifyToken()</code> middleware, and resolves to a <code>Session</code> row that downstream handlers read off <code>req.ctx</code>. The middleware is the only place that talks to the session store, which is the only place that talks to the <code>sessions</code> table — so there's exactly one trust boundary to reason about.
</p>
</header>
<main>
<h2 style="margin-top:0">Request path</h2>
<div class="diagram-panel">
<svg class="flow" viewBox="0 0 720 280" width="720" height="280" role="img" aria-label="Authentication flow diagram">
<defs>
<marker id="arrowHead" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
<path d="M 0 0 L 10 5 L 0 10 z" fill="#87867F"></path>
</marker>
</defs>
<!-- Row 1 -->
<g>
<rect class="box" x="30" y="40" width="150" height="64" rx="10"></rect>
<text x="105" y="68" text-anchor="middle">Browser</text>
<text class="sub" x="105" y="84" text-anchor="middle">acme.app</text>
</g>
<g>
<rect class="box" x="245" y="40" width="150" height="64" rx="10"></rect>
<text x="320" y="68" text-anchor="middle">/api/session</text>
<text class="sub" x="320" y="84" text-anchor="middle">route handler</text>
</g>
<g>
<rect class="box hot" x="460" y="40" width="180" height="64" rx="10"></rect>
<text x="550" y="68" text-anchor="middle">verifyToken()</text>
<text class="sub" x="550" y="84" text-anchor="middle">middleware/auth.ts</text>
</g>
<!-- Row 2 -->
<g>
<rect class="box" x="460" y="170" width="180" height="64" rx="10"></rect>
<text x="550" y="198" text-anchor="middle">SessionStore</text>
<text class="sub" x="550" y="214" text-anchor="middle">lib/sessionStore.ts</text>
</g>
<g>
<rect class="box" x="245" y="170" width="150" height="64" rx="10"></rect>
<text x="320" y="198" text-anchor="middle">Postgres</text>
<text class="sub" x="320" y="214" text-anchor="middle">sessions table</text>
</g>
<!-- Arrows -->
<line class="arrow" x1="180" y1="72" x2="245" y2="72" marker-end="url(#arrowHead)"></line>
<line class="arrow" x1="395" y1="72" x2="460" y2="72" marker-end="url(#arrowHead)"></line>
<line class="arrow" x1="550" y1="104" x2="550" y2="170" marker-end="url(#arrowHead)"></line>
<line class="arrow" x1="460" y1="202" x2="395" y2="202" marker-end="url(#arrowHead)"></line>
<text class="sub" x="212" y="62" text-anchor="middle">cookie</text>
<text class="sub" x="560" y="140" text-anchor="start">lookup</text>
</svg>
</div>
<h2>Callstack walkthrough</h2>
<!-- Step 1 -->
<div class="step">
<div class="badge">1</div>
<div class="step-body">
<div class="step-loc">src/app/providers/AuthProvider.tsx<span class="range"> :22-48</span></div>
<p>On mount, the React provider issues a <code style="font-family:var(--mono);font-size:12.5px">GET /api/session</code> with <code style="font-family:var(--mono);font-size:12.5px">credentials: 'include'</code> so the <code style="font-family:var(--mono);font-size:12.5px">fw_sid</code> cookie rides along. The response either hydrates <code style="font-family:var(--mono);font-size:12.5px">currentUser</code> into context or leaves it <code style="font-family:var(--mono);font-size:12.5px">null</code>, which the router treats as "show the sign-in screen".</p>
<details class="snippet">
<summary>show source</summary>
<pre class="code"><span class="dim">// src/app/providers/AuthProvider.tsx</span>
<span class="kw">export function</span> AuthProvider({ children }: Props) {
<span class="kw">const</span> [user, setUser] = useState<User | <span class="kw">null</span>>(<span class="kw">null</span>);
useEffect(() => {
fetch(<span class="str">'/api/session'</span>, { credentials: <span class="str">'include'</span> })
.then(r => r.ok ? r.json() : <span class="kw">null</span>)
.then(setUser);
}, []);
<span class="kw">return</span> <AuthCtx.Provider value={{ user }}>{children}</AuthCtx.Provider>;
}</pre>
</details>
</div>
</div>
<!-- Step 2 -->
<div class="step">
<div class="badge">2</div>
<div class="step-body">
<div class="step-loc">src/server/routes/session.ts<span class="range"> :9-27</span></div>
<p>The route itself is thin: it just returns whatever <code style="font-family:var(--mono);font-size:12.5px">req.ctx.session</code> the middleware attached. If the middleware short-circuited with a 401, this handler never runs — so there's no auth logic duplicated here.</p>
<details class="snippet">
<summary>show source</summary>
<pre class="code"><span class="dim">// src/server/routes/session.ts</span>
router.get(<span class="str">'/session'</span>, verifyToken, (req, res) => {
<span class="kw">const</span> { session } = req.ctx;
res.json({
id: session.userId,
email: session.email,
role: session.role,
exp: session.expiresAt,
});
});</pre>
</details>
</div>
</div>
<!-- Step 3 -->
<div class="step hot">
<div class="badge">3</div>
<div class="step-body">
<div class="step-loc">src/middleware/auth.ts<span class="range"> :14-31</span></div>
<p>This is the trust boundary. <code style="font-family:var(--mono);font-size:12.5px">verifyToken</code> reads the signed <code style="font-family:var(--mono);font-size:12.5px">fw_sid</code> cookie, asks <code style="font-family:var(--mono);font-size:12.5px">SessionStore</code> to resolve it, and either populates <code style="font-family:var(--mono);font-size:12.5px">req.ctx.session</code> or responds 401. Every protected route in the app is mounted behind this function, so changing its behaviour changes auth globally.</p>
<details class="snippet" open>
<summary>show source</summary>
<pre class="code"><span class="dim">// src/middleware/auth.ts</span>
<span class="kw">export async function</span> verifyToken(req, res, next) {
<span class="kw">const</span> raw = req.signedCookies[<span class="str">'fw_sid'</span>];
<span class="kw">if</span> (!raw) <span class="kw">return</span> res.status(401).end();
<span class="kw">const</span> session = <span class="kw">await</span> SessionStore.get(raw);
<span class="kw">if</span> (!session || session.expiresAt < Date.now()) {
<span class="kw">return</span> res.status(401).end();
}
req.ctx = { session };
next();
}</pre>
</details>
</div>
</div>
<!-- Step 4 -->
<div class="step">
<div class="badge">4</div>
<div class="step-body">
<div class="step-loc">src/lib/sessionStore.ts<span class="range"> :8-52</span></div>
<p><code style="font-family:var(--mono);font-size:12.5px">SessionStore</code> is a small read-through cache: it checks an in-process LRU first, then falls back to Postgres. Writes (<code style="font-family:var(--mono);font-size:12.5px">create</code>, <code style="font-family:var(--mono);font-size:12.5px">revoke</code>) always go straight to the DB and invalidate the cache entry so other workers don't serve a stale session.</p>
<details class="snippet">
<summary>show source</summary>
<pre class="code"><span class="dim">// src/lib/sessionStore.ts</span>
<span class="kw">const</span> cache = <span class="kw">new</span> LRU<string, Session>({ max: 5000, ttl: 60_000 });
<span class="kw">export const</span> SessionStore = {
<span class="kw">async</span> get(id: string) {
<span class="kw">const</span> hit = cache.get(id);
<span class="kw">if</span> (hit) <span class="kw">return</span> hit;
<span class="kw">const</span> row = <span class="kw">await</span> db.one(SELECT_SESSION, [id]);
<span class="kw">if</span> (row) cache.set(id, row);
<span class="kw">return</span> row ?? <span class="kw">null</span>;
},
<span class="dim">/* create, revoke, touch ... */</span>
};</pre>
</details>
</div>
</div>
<!-- Step 5 -->
<div class="step">
<div class="badge">5</div>
<div class="step-body">
<div class="step-loc">db/migrations/004_sessions.sql<span class="range"> :1-18</span></div>
<p>The <code style="font-family:var(--mono);font-size:12.5px">sessions</code> table is keyed on a random 32-byte id (the cookie value) with a covering index on <code style="font-family:var(--mono);font-size:12.5px">user_id</code> for "sign out everywhere". Expiry is enforced both here (<code style="font-family:var(--mono);font-size:12.5px">expires_at</code>) and again in the middleware as defence in depth.</p>
<details class="snippet">
<summary>show source</summary>
<pre class="code"><span class="dim">-- db/migrations/004_sessions.sql</span>
<span class="kw">create table</span> sessions (
id <span class="kw">text primary key</span>,
user_id <span class="kw">uuid not null references</span> users(id),
created_at <span class="kw">timestamptz default</span> now(),
expires_at <span class="kw">timestamptz not null</span>,
ip <span class="kw">inet</span>,
user_agent <span class="kw">text</span>
);
<span class="kw">create index</span> sessions_user_id_idx <span class="kw">on</span> sessions(user_id);</pre>
</details>
</div>
</div>
</main>
<aside>
<div class="panel">
<h3>Key files</h3>
<ul class="key-files">
<li>
<span class="path">src/middleware/auth.ts</span>
<span class="desc">Single entry point for request authentication.</span>
</li>
<li>
<span class="path">src/lib/sessionStore.ts</span>
<span class="desc">LRU + Postgres session lookup; only DB caller.</span>
</li>
<li>
<span class="path">src/server/routes/session.ts</span>
<span class="desc">Returns the current session to the client.</span>
</li>
<li>
<span class="path">src/server/routes/login.ts</span>
<span class="desc">Exchanges credentials for a cookie via SessionStore.create.</span>
</li>
<li>
<span class="path">src/app/providers/AuthProvider.tsx</span>
<span class="desc">Client-side context that mirrors the server session.</span>
</li>
<li>
<span class="path">db/migrations/004_sessions.sql</span>
<span class="desc">Schema for the sessions table and indexes.</span>
</li>
</ul>
</div>
<div class="gotchas">
<h3>Gotchas</h3>
<ul>
<li>The LRU in <code>SessionStore</code> is per-process. Revoking a session only clears the local cache — other workers may serve it for up to 60s until their TTL lapses.</li>
<li><code>verifyToken</code> compares <code>expiresAt</code> against <code>Date.now()</code>, but the column is <code>timestamptz</code>. The driver returns a <code>Date</code>, so the comparison works, but don't refactor it to a raw string without adjusting the check.</li>
</ul>
</div>
</aside>
</div>
<script>
// Keep at most one snippet open at a time so the walkthrough stays scannable.
var snippets = document.querySelectorAll('details.snippet');
snippets.forEach(function (d) {
d.addEventListener('toggle', function () {
if (!d.open) return;
snippets.forEach(function (other) {
if (other !== d) other.open = false;
});
});
});
</script>
</body>
</html>
<!-- Copyright 2026 Anthropic PBC · SPDX-License-Identifier: Apache-2.0 -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Acme — Design System Reference</title>
<style>
:root {
--ivory: #FAF9F5;
--slate: #141413;
--clay: #D97757;
--oat: #E3DACC;
--olive: #788C5D;
--gray-100: #F0EEE6;
--gray-300: #D1CFC5;
--gray-500: #87867F;
--gray-700: #3D3D3A;
--white: #FFFFFF;
--serif: ui-serif, Georgia, serif;
--sans: system-ui, -apple-system, sans-serif;
--mono: ui-monospace, 'SF Mono', Menlo, monospace;
--radius-panel: 12px;
--radius-row: 8px;
--border: 1.5px solid var(--gray-300);
}
* { box-sizing: border-box; }
body {
margin: 0;
padding: 56px 24px 96px;
background: var(--ivory);
color: var(--slate);
font-family: var(--sans);
font-size: 15px;
line-height: 1.55;
-webkit-font-smoothing: antialiased;
}
.page {
max-width: 980px;
margin: 0 auto;
}
header h1 {
font-family: var(--serif);
font-weight: 500;
font-size: 40px;
letter-spacing: -0.01em;
margin: 0 0 6px;
}
header .sub {
color: var(--gray-500);
font-size: 14px;
margin: 0 0 48px;
}
header .sub code {
font-family: var(--mono);
font-size: 13px;
background: var(--gray-100);
padding: 1px 5px;
border-radius: 4px;
}
section { margin-bottom: 64px; }
h2 {
font-family: var(--serif);
font-weight: 500;
font-size: 26px;
margin: 0 0 8px;
letter-spacing: -0.01em;
}
hr.rule {
border: none;
border-top: 1px solid var(--gray-300);
margin: 0 0 28px;
}
/* ---------- Color ---------- */
.swatch-group {
margin-bottom: 28px;
}
.swatch-group-label {
font-family: var(--mono);
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.08em;
color: var(--gray-500);
margin-bottom: 12px;
}
.swatch-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(96px, 1fr));
gap: 20px 16px;
}
.swatch {}
.swatch .chip {
width: 64px;
height: 64px;
border-radius: var(--radius-row);
border: var(--border);
margin-bottom: 8px;
}
.swatch .chip.no-border { border-color: transparent; }
.swatch .hex {
font-family: var(--mono);
font-size: 12px;
color: var(--gray-700);
display: block;
}
.swatch .token {
font-family: var(--mono);
font-size: 11px;
color: var(--gray-500);
display: block;
}
/* ---------- Typography ---------- */
.type-scale {
border: var(--border);
border-radius: var(--radius-panel);
background: var(--white);
overflow: hidden;
}
.type-row {
display: flex;
align-items: baseline;
justify-content: space-between;
gap: 24px;
padding: 20px 24px;
border-bottom: 1px solid var(--gray-100);
}
.type-row:last-child { border-bottom: none; }
.type-specimen {
flex: 1;
min-width: 0;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
color: var(--slate);
}
.type-meta {
font-family: var(--mono);
font-size: 12px;
color: var(--gray-500);
text-align: right;
flex-shrink: 0;
}
.type-meta .name {
color: var(--gray-700);
display: block;
margin-bottom: 2px;
}
.t-display { font-family: var(--serif); font-size: 48px; line-height: 1.1; font-weight: 500; letter-spacing: -0.02em; }
.t-h1 { font-family: var(--serif); font-size: 32px; line-height: 1.2; font-weight: 500; letter-spacing: -0.01em; }
.t-h2 { font-family: var(--serif); font-size: 24px; line-height: 1.3; font-weight: 500; }
.t-body { font-family: var(--sans); font-size: 16px; line-height: 1.55; font-weight: 430; }
.t-small { font-family: var(--sans); font-size: 14px; line-height: 1.5; font-weight: 430; }
.t-caption { font-family: var(--sans); font-size: 12px; line-height: 1.4; font-weight: 500; color: var(--gray-500); }
/* ---------- Spacing ---------- */
.spacing-ruler {
display: flex;
align-items: flex-end;
gap: 28px;
padding: 28px 24px;
background: var(--white);
border: var(--border);
border-radius: var(--radius-panel);
overflow-x: auto;
}
.space-token {
display: flex;
flex-direction: column;
align-items: center;
gap: 10px;
flex-shrink: 0;
}
.space-bar {
background: var(--clay);
border-radius: 3px;
height: 14px;
}
.space-label {
font-family: var(--mono);
font-size: 11px;
color: var(--gray-700);
text-align: center;
}
.space-label span {
display: block;
color: var(--gray-500);
}
/* ---------- Radius & Elevation ---------- */
.token-row {
display: flex;
flex-wrap: wrap;
gap: 20px;
margin-bottom: 28px;
}
.radius-card {
width: 120px;
height: 88px;
background: var(--oat);
border: var(--border);
display: flex;
align-items: flex-end;
padding: 10px 12px;
}
.radius-card .lbl {
font-family: var(--mono);
font-size: 11px;
color: var(--gray-700);
}
.radius-card .lbl span { color: var(--gray-500); display: block; }
.shadow-card {
width: 160px;
height: 96px;
background: var(--white);
border-radius: var(--radius-panel);
display: flex;
align-items: flex-end;
padding: 12px 14px;
}
.shadow-card .lbl {
font-family: var(--mono);
font-size: 11px;
color: var(--gray-700);
}
.shadow-card .lbl span { color: var(--gray-500); display: block; }
/* ---------- Core components ---------- */
.component {
margin-bottom: 32px;
}
.component-name {
font-family: var(--mono);
font-size: 12px;
color: var(--gray-500);
margin-bottom: 12px;
}
.component-stage {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 16px;
padding: 24px;
background: var(--white);
border: var(--border);
border-radius: var(--radius-panel);
}
/* Button */
.btn {
display: inline-flex;
align-items: center;
justify-content: center;
height: 36px;
padding: 0 16px;
font-family: var(--sans);
font-size: 14px;
font-weight: 500;
border-radius: var(--radius-row);
border: 1.5px solid transparent;
cursor: pointer;
transition: background 0.12s ease, border-color 0.12s ease;
}
.btn-primary { background: var(--clay); color: var(--white); }
.btn-primary:hover { background: #C7684C; }
.btn-secondary { background: var(--white); color: var(--slate); border-color: var(--gray-300); }
.btn-secondary:hover { background: var(--gray-100); }
.btn-ghost { background: transparent; color: var(--gray-700); }
.btn-ghost:hover { background: var(--gray-100); }
.btn-danger { background: #B04A4A; color: var(--white); }
.btn-danger:hover { background: #9A3F3F; }
/* Input */
.input {
height: 38px;
padding: 0 12px;
font-family: var(--sans);
font-size: 14px;
color: var(--slate);
background: var(--white);
border: var(--border);
border-radius: var(--radius-row);
width: 260px;
outline: none;
transition: border-color 0.12s ease, box-shadow 0.12s ease;
}
.input::placeholder { color: var(--gray-500); }
.input:focus {
border-color: var(--clay);
box-shadow: 0 0 0 3px rgba(217, 119, 87, 0.15);
}
/* Checkbox */
.checkbox {
display: inline-flex;
align-items: center;
gap: 10px;
font-size: 14px;
cursor: pointer;
user-select: none;
}
.checkbox input {
appearance: none;
width: 18px;
height: 18px;
border: var(--border);
border-radius: 5px;
background: var(--white);
margin: 0;
cursor: pointer;
position: relative;
transition: background 0.12s ease, border-color 0.12s ease;
}
.checkbox input:checked {
background: var(--clay);
border-color: var(--clay);
}
.checkbox input:checked::after {
content: "";
position: absolute;
left: 5px; top: 1px;
width: 5px; height: 10px;
border: solid var(--white);
border-width: 0 2px 2px 0;
transform: rotate(45deg);
}
/* Badge */
.badge {
display: inline-flex;
align-items: center;
height: 22px;
padding: 0 9px;
font-size: 12px;
font-weight: 500;
border-radius: 999px;
}
.badge-neutral { background: var(--gray-100); color: var(--gray-700); }
.badge-accent { background: rgba(217, 119, 87, 0.14); color: var(--clay); }
.badge-success { background: rgba(120, 140, 93, 0.16); color: var(--olive); }
.badge-warning { background: rgba(199, 142, 63, 0.16); color: #A06A2A; }
</style>
</head>
<body>
<div class="page">
<header>
<h1>Acme design system</h1>
<p class="sub">
Generated from <code>src/styles/tokens.ts</code> and <code>src/components/</code> — use as a portable reference when prompting.
</p>
</header>
<!-- ===================== COLOR ===================== -->
<section id="color">
<h2>Color</h2>
<hr class="rule">
<div class="swatch-group">
<div class="swatch-group-label">Primary</div>
<div class="swatch-grid">
<div class="swatch">
<div class="chip no-border" style="background:#D97757"></div>
<span class="hex">#D97757</span>
<span class="token">--clay</span>
</div>
<div class="swatch">
<div class="chip no-border" style="background:#141413"></div>
<span class="hex">#141413</span>
<span class="token">--slate</span>
</div>
<div class="swatch">
<div class="chip" style="background:#FAF9F5"></div>
<span class="hex">#FAF9F5</span>
<span class="token">--ivory</span>
</div>
<div class="swatch">
<div class="chip no-border" style="background:#E3DACC"></div>
<span class="hex">#E3DACC</span>
<span class="token">--oat</span>
</div>
</div>
</div>
<div class="swatch-group">
<div class="swatch-group-label">Neutral</div>
<div class="swatch-grid">
<div class="swatch">
<div class="chip" style="background:#FFFFFF"></div>
<span class="hex">#FFFFFF</span>
<span class="token">--white</span>
</div>
<div class="swatch">
<div class="chip" style="background:#F0EEE6"></div>
<span class="hex">#F0EEE6</span>
<span class="token">--gray-100</span>
</div>
<div class="swatch">
<div class="chip no-border" style="background:#D1CFC5"></div>
<span class="hex">#D1CFC5</span>
<span class="token">--gray-300</span>
</div>
<div class="swatch">
<div class="chip no-border" style="background:#87867F"></div>
<span class="hex">#87867F</span>
<span class="token">--gray-500</span>
</div>
<div class="swatch">
<div class="chip no-border" style="background:#3D3D3A"></div>
<span class="hex">#3D3D3A</span>
<span class="token">--gray-700</span>
</div>
</div>
</div>
<div class="swatch-group">
<div class="swatch-group-label">Semantic</div>
<div class="swatch-grid">
<div class="swatch">
<div class="chip no-border" style="background:#788C5D"></div>
<span class="hex">#788C5D</span>
<span class="token">--success</span>
</div>
<div class="swatch">
<div class="chip no-border" style="background:#C78E3F"></div>
<span class="hex">#C78E3F</span>
<span class="token">--warning</span>
</div>
<div class="swatch">
<div class="chip no-border" style="background:#B04A4A"></div>
<span class="hex">#B04A4A</span>
<span class="token">--danger</span>
</div>
<div class="swatch">
<div class="chip no-border" style="background:#5C7CA3"></div>
<span class="hex">#5C7CA3</span>
<span class="token">--info</span>
</div>
</div>
</div>
</section>
<!-- ===================== TYPOGRAPHY ===================== -->
<section id="typography">
<h2>Typography</h2>
<hr class="rule">
<div class="type-scale">
<div class="type-row">
<div class="type-specimen t-display">Plan the week ahead</div>
<div class="type-meta">
<span class="name">Display</span>
48 / 1.1 / 500
</div>
</div>
<div class="type-row">
<div class="type-specimen t-h1">Plan the week ahead</div>
<div class="type-meta">
<span class="name">Heading 1</span>
32 / 1.2 / 500
</div>
</div>
<div class="type-row">
<div class="type-specimen t-h2">Plan the week ahead</div>
<div class="type-meta">
<span class="name">Heading 2</span>
24 / 1.3 / 500
</div>
</div>
<div class="type-row">
<div class="type-specimen t-body">Review milestones, assign owners, and surface blockers before they cascade.</div>
<div class="type-meta">
<span class="name">Body</span>
16 / 1.55 / 430
</div>
</div>
<div class="type-row">
<div class="type-specimen t-small">Review milestones, assign owners, and surface blockers before they cascade.</div>
<div class="type-meta">
<span class="name">Small</span>
14 / 1.5 / 430
</div>
</div>
<div class="type-row">
<div class="type-specimen t-caption">UPDATED 2 HOURS AGO</div>
<div class="type-meta">
<span class="name">Caption</span>
12 / 1.4 / 500
</div>
</div>
</div>
</section>
<!-- ===================== SPACING ===================== -->
<section id="spacing">
<h2>Spacing</h2>
<hr class="rule">
<div class="spacing-ruler">
<div class="space-token">
<div class="space-bar" style="width:4px"></div>
<div class="space-label">4<span>--sp-1</span></div>
</div>
<div class="space-token">
<div class="space-bar" style="width:8px"></div>
<div class="space-label">8<span>--sp-2</span></div>
</div>
<div class="space-token">
<div class="space-bar" style="width:12px"></div>
<div class="space-label">12<span>--sp-3</span></div>
</div>
<div class="space-token">
<div class="space-bar" style="width:16px"></div>
<div class="space-label">16<span>--sp-4</span></div>
</div>
<div class="space-token">
<div class="space-bar" style="width:24px"></div>
<div class="space-label">24<span>--sp-5</span></div>
</div>
<div class="space-token">
<div class="space-bar" style="width:32px"></div>
<div class="space-label">32<span>--sp-6</span></div>
</div>
<div class="space-token">
<div class="space-bar" style="width:48px"></div>
<div class="space-label">48<span>--sp-7</span></div>
</div>
<div class="space-token">
<div class="space-bar" style="width:64px"></div>
<div class="space-label">64<span>--sp-8</span></div>
</div>
</div>
</section>
<!-- ===================== RADIUS & ELEVATION ===================== -->
<section id="shape">
<h2>Radius & Elevation</h2>
<hr class="rule">
<div class="token-row">
<div class="radius-card" style="border-radius:4px">
<div class="lbl">4px<span>--r-xs</span></div>
</div>
<div class="radius-card" style="border-radius:8px">
<div class="lbl">8px<span>--r-sm</span></div>
</div>
<div class="radius-card" style="border-radius:12px">
<div class="lbl">12px<span>--r-md</span></div>
</div>
<div class="radius-card" style="border-radius:20px">
<div class="lbl">20px<span>--r-lg</span></div>
</div>
</div>
<div class="token-row">
<div class="shadow-card" style="box-shadow:0 1px 2px rgba(20,20,19,0.06)">
<div class="lbl">--shadow-sm<span>0 1px 2px / 6%</span></div>
</div>
<div class="shadow-card" style="box-shadow:0 4px 10px rgba(20,20,19,0.08)">
<div class="lbl">--shadow-md<span>0 4px 10px / 8%</span></div>
</div>
<div class="shadow-card" style="box-shadow:0 12px 28px rgba(20,20,19,0.12)">
<div class="lbl">--shadow-lg<span>0 12px 28px / 12%</span></div>
</div>
</div>
</section>
<!-- ===================== CORE COMPONENTS ===================== -->
<section id="components">
<h2>Core components</h2>
<hr class="rule">
<div class="component">
<div class="component-name"><Button /></div>
<div class="component-stage">
<button class="btn btn-primary">Create task</button>
<button class="btn btn-secondary">Cancel</button>
<button class="btn btn-ghost">Skip</button>
<button class="btn btn-danger">Delete</button>
</div>
</div>
<div class="component">
<div class="component-name"><Input /></div>
<div class="component-stage">
<input class="input" type="text" placeholder="Search tasks…">
<input class="input" type="text" value="Weekly planning">
</div>
</div>
<div class="component">
<div class="component-name"><Checkbox /></div>
<div class="component-stage">
<label class="checkbox">
<input type="checkbox">
Notify assignees
</label>
<label class="checkbox">
<input type="checkbox" checked>
Archive on complete
</label>
</div>
</div>
<div class="component">
<div class="component-name"><Badge /></div>
<div class="component-stage">
<span class="badge badge-neutral">Draft</span>
<span class="badge badge-accent">In review</span>
<span class="badge badge-success">Done</span>
<span class="badge badge-warning">Overdue</span>
</div>
</div>
</section>
</div>
</body>
</html>
<!-- Copyright 2026 Anthropic PBC · SPDX-License-Identifier: Apache-2.0 -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Acme — Card Variant Matrix</title>
<style>
:root {
--ivory: #FAF9F5;
--slate: #141413;
--clay: #D97757;
--oat: #E3DACC;
--olive: #788C5D;
--gray-100: #F0EEE6;
--gray-300: #D1CFC5;
--gray-500: #87867F;
--gray-700: #3D3D3A;
--white: #FFFFFF;
--serif: ui-serif, Georgia, serif;
--sans: system-ui, -apple-system, sans-serif;
--mono: ui-monospace, 'SF Mono', Menlo, monospace;
/* live-controlled tokens */
--card-pad: 20px;
--card-border: 1.5px solid var(--gray-300);
--card-shadow: 0 4px 14px rgba(20, 20, 19, 0.08);
}
* { box-sizing: border-box; }
body {
margin: 0;
background: var(--ivory);
color: var(--slate);
font-family: var(--sans);
font-size: 15px;
line-height: 1.5;
-webkit-font-smoothing: antialiased;
}
.page {
max-width: 1100px;
margin: 0 auto;
padding: 0 28px 80px;
}
header {
padding: 48px 0 20px;
}
header h1 {
font-family: var(--serif);
font-weight: 500;
font-size: 36px;
letter-spacing: -0.01em;
margin: 0 0 6px;
}
header p {
color: var(--gray-500);
font-size: 14px;
margin: 0;
max-width: 640px;
}
/* ---------- Toolbar ---------- */
.toolbar {
position: sticky;
top: 0;
z-index: 10;
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 28px;
padding: 16px 20px;
margin: 24px 0 36px;
background: var(--white);
border: 1.5px solid var(--gray-300);
border-radius: 12px;
}
.control {
display: flex;
align-items: center;
gap: 10px;
}
.control-label {
font-family: var(--mono);
font-size: 12px;
color: var(--gray-700);
}
.control-value {
font-family: var(--mono);
font-size: 12px;
color: var(--gray-500);
min-width: 36px;
}
input[type="range"] {
appearance: none;
width: 140px;
height: 4px;
background: var(--gray-300);
border-radius: 2px;
outline: none;
}
input[type="range"]::-webkit-slider-thumb {
appearance: none;
width: 16px; height: 16px;
background: var(--clay);
border-radius: 50%;
cursor: pointer;
}
input[type="range"]::-moz-range-thumb {
width: 16px; height: 16px;
background: var(--clay);
border: none;
border-radius: 50%;
cursor: pointer;
}
.radio-group {
display: inline-flex;
border: 1.5px solid var(--gray-300);
border-radius: 8px;
overflow: hidden;
}
.radio-group label {
padding: 6px 12px;
font-size: 13px;
cursor: pointer;
user-select: none;
color: var(--gray-700);
border-right: 1px solid var(--gray-300);
}
.radio-group label:last-child { border-right: none; }
.radio-group input { display: none; }
.radio-group input:checked + span {
color: var(--slate);
}
.radio-group label:has(input:checked) {
background: var(--gray-100);
}
.check {
display: inline-flex;
align-items: center;
gap: 8px;
font-size: 13px;
cursor: pointer;
user-select: none;
}
.check input {
appearance: none;
width: 16px; height: 16px;
border: 1.5px solid var(--gray-300);
border-radius: 4px;
margin: 0;
cursor: pointer;
position: relative;
}
.check input:checked {
background: var(--clay);
border-color: var(--clay);
}
.check input:checked::after {
content: "";
position: absolute;
left: 4px; top: 0;
width: 4px; height: 9px;
border: solid var(--white);
border-width: 0 2px 2px 0;
transform: rotate(45deg);
}
/* ---------- Grid ---------- */
.grid {
display: grid;
grid-template-columns: repeat(3, 1fr);
gap: 28px;
}
@media (max-width: 960px) {
.grid { grid-template-columns: repeat(2, 1fr); }
}
@media (max-width: 640px) {
.grid { grid-template-columns: 1fr; }
}
.cell {}
.variant-label {
display: inline-flex;
align-items: center;
height: 22px;
padding: 0 9px;
font-family: var(--mono);
font-size: 11px;
font-weight: 500;
color: var(--gray-700);
background: var(--gray-100);
border-radius: 999px;
margin-bottom: 10px;
}
.variant-note {
font-size: 12px;
color: var(--gray-500);
margin-top: 10px;
}
/* ---------- Card base ---------- */
.card {
border-radius: 12px;
padding: var(--card-pad);
transition: padding 0.15s ease, box-shadow 0.15s ease, border 0.15s ease;
cursor: pointer;
}
.card:hover { outline: 2px solid var(--clay); outline-offset: 2px; }
.card-head {
display: flex;
align-items: center;
gap: 12px;
margin-bottom: 12px;
}
.avatar {
width: 36px; height: 36px;
border-radius: 50%;
background: var(--oat);
flex-shrink: 0;
display: flex;
align-items: center;
justify-content: center;
font-size: 13px;
font-weight: 600;
color: var(--gray-700);
}
.card-titles { min-width: 0; }
.card-title {
font-family: var(--serif);
font-size: 17px;
font-weight: 500;
margin: 0 0 2px;
line-height: 1.3;
}
.card-sub {
font-size: 13px;
color: var(--gray-500);
margin: 0;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
.chips {
display: flex;
gap: 6px;
margin-bottom: 14px;
}
.chip {
display: inline-flex;
align-items: center;
height: 20px;
padding: 0 8px;
font-size: 11px;
font-weight: 500;
border-radius: 999px;
background: var(--gray-100);
color: var(--gray-700);
}
.chip.olive { background: rgba(120,140,93,0.16); color: var(--olive); }
.ghost-btn {
display: inline-flex;
align-items: center;
height: 30px;
padding: 0 12px;
font-size: 13px;
font-weight: 500;
color: var(--gray-700);
background: transparent;
border: 1.5px solid var(--gray-300);
border-radius: 8px;
cursor: pointer;
}
.ghost-btn:hover { background: var(--gray-100); }
/* ---------- Variant treatments ---------- */
.v-flat {
background: var(--white);
border: none;
box-shadow: none;
}
.v-outlined {
background: var(--white);
border: var(--card-border);
box-shadow: none;
}
.v-elevated {
background: var(--white);
border: none;
box-shadow: var(--card-shadow);
}
.v-stripe {
background: var(--white);
border: var(--card-border);
box-shadow: none;
position: relative;
overflow: hidden;
}
.v-stripe::before {
content: "";
position: absolute;
left: 0; right: 0; top: 0;
height: 4px;
background: var(--clay);
}
.v-inset {
background: var(--oat);
border: none;
box-shadow: none;
}
.v-inset .chip { background: rgba(255,255,255,0.6); }
.v-inset .ghost-btn { border-color: rgba(20,20,19,0.15); }
.v-inset .avatar { background: var(--white); }
.v-horizontal {
background: var(--white);
border: var(--card-border);
box-shadow: none;
display: flex;
align-items: center;
gap: 14px;
}
.v-horizontal .card-head { margin: 0; flex: 1; min-width: 0; }
.v-horizontal .chips { margin: 0; }
.v-horizontal .card-sub { display: none; }
.v-horizontal .ghost-btn { flex-shrink: 0; }
/* ---------- Snippet panel ---------- */
.snippet-panel {
margin-top: 40px;
border: 1.5px solid var(--gray-300);
border-radius: 12px;
overflow: hidden;
}
.snippet-head {
padding: 10px 16px;
font-family: var(--mono);
font-size: 12px;
color: var(--gray-500);
background: var(--gray-100);
border-bottom: 1px solid var(--gray-300);
}
pre#snippet {
margin: 0;
padding: 20px;
background: var(--slate);
color: var(--ivory);
font-family: var(--mono);
font-size: 13px;
line-height: 1.6;
overflow-x: auto;
min-height: 120px;
}
</style>
</head>
<body>
<div class="page">
<header>
<h1>Card variant matrix</h1>
<p>Six structural treatments of the Acme <code style="font-family:var(--mono);font-size:13px"><Card /></code> component. Adjust density and emphasis with the controls, hover a variant to see its prop combo.</p>
</header>
<!-- ---------- Toolbar ---------- -->
<div class="toolbar">
<div class="control">
<span class="control-label">Padding</span>
<input id="ctl-pad" type="range" min="12" max="32" value="20" step="2">
<span class="control-value" id="pad-out">20px</span>
</div>
<div class="control">
<span class="control-label">Border</span>
<div class="radio-group">
<label><input type="radio" name="border" value="none"><span>none</span></label>
<label><input type="radio" name="border" value="hairline" checked><span>hairline</span></label>
<label><input type="radio" name="border" value="solid"><span>solid</span></label>
</div>
</div>
<div class="control">
<label class="check">
<input id="ctl-shadow" type="checkbox" checked>
Show shadow
</label>
</div>
</div>
<!-- ---------- Grid ---------- -->
<div class="grid" id="grid">
<!-- A: Flat -->
<div class="cell">
<span class="variant-label">A · Flat</span>
<div class="card v-flat"
data-snippet='<Card variant="flat" padding={PAD}>
<Card.Header avatar title="Weekly planning" subtitle="12 tasks · due Friday" />
<Card.Meta tags={["Q2", "Roadmap"]} />
<Button variant="ghost">Open</Button>
</Card>'>
<div class="card-head">
<div class="avatar">WP</div>
<div class="card-titles">
<p class="card-title">Weekly planning</p>
<p class="card-sub">12 tasks · due Friday</p>
</div>
</div>
<div class="chips">
<span class="chip">Q2</span>
<span class="chip olive">Roadmap</span>
</div>
<button class="ghost-btn">Open</button>
</div>
<p class="variant-note">best for: dense lists on tinted backgrounds</p>
</div>
<!-- B: Outlined -->
<div class="cell">
<span class="variant-label">B · Outlined</span>
<div class="card v-outlined"
data-snippet='<Card variant="outlined" padding={PAD} border="BORDER">
<Card.Header avatar title="Weekly planning" subtitle="12 tasks · due Friday" />
<Card.Meta tags={["Q2", "Roadmap"]} />
<Button variant="ghost">Open</Button>
</Card>'>
<div class="card-head">
<div class="avatar">WP</div>
<div class="card-titles">
<p class="card-title">Weekly planning</p>
<p class="card-sub">12 tasks · due Friday</p>
</div>
</div>
<div class="chips">
<span class="chip">Q2</span>
<span class="chip olive">Roadmap</span>
</div>
<button class="ghost-btn">Open</button>
</div>
<p class="variant-note">best for: default content cards on ivory</p>
</div>
<!-- C: Elevated -->
<div class="cell">
<span class="variant-label">C · Elevated</span>
<div class="card v-elevated"
data-snippet='<Card variant="elevated" padding={PAD} shadow="md">
<Card.Header avatar title="Weekly planning" subtitle="12 tasks · due Friday" />
<Card.Meta tags={["Q2", "Roadmap"]} />
<Button variant="ghost">Open</Button>
</Card>'>
<div class="card-head">
<div class="avatar">WP</div>
<div class="card-titles">
<p class="card-title">Weekly planning</p>
<p class="card-sub">12 tasks · due Friday</p>
</div>
</div>
<div class="chips">
<span class="chip">Q2</span>
<span class="chip olive">Roadmap</span>
</div>
<button class="ghost-btn">Open</button>
</div>
<p class="variant-note">best for: draggable items, popovers</p>
</div>
<!-- D: Accent stripe -->
<div class="cell">
<span class="variant-label">D · Accent stripe</span>
<div class="card v-stripe"
data-snippet='<Card variant="outlined" accent="clay" padding={PAD} border="BORDER">
<Card.Header avatar title="Weekly planning" subtitle="12 tasks · due Friday" />
<Card.Meta tags={["Q2", "Roadmap"]} />
<Button variant="ghost">Open</Button>
</Card>'>
<div class="card-head">
<div class="avatar">WP</div>
<div class="card-titles">
<p class="card-title">Weekly planning</p>
<p class="card-sub">12 tasks · due Friday</p>
</div>
</div>
<div class="chips">
<span class="chip">Q2</span>
<span class="chip olive">Roadmap</span>
</div>
<button class="ghost-btn">Open</button>
</div>
<p class="variant-note">best for: pinned or priority items</p>
</div>
<!-- E: Inset / filled -->
<div class="cell">
<span class="variant-label">E · Inset</span>
<div class="card v-inset"
data-snippet='<Card variant="filled" tone="oat" padding={PAD}>
<Card.Header avatar title="Weekly planning" subtitle="12 tasks · due Friday" />
<Card.Meta tags={["Q2", "Roadmap"]} />
<Button variant="ghost">Open</Button>
</Card>'>
<div class="card-head">
<div class="avatar">WP</div>
<div class="card-titles">
<p class="card-title">Weekly planning</p>
<p class="card-sub">12 tasks · due Friday</p>
</div>
</div>
<div class="chips">
<span class="chip">Q2</span>
<span class="chip olive">Roadmap</span>
</div>
<button class="ghost-btn">Open</button>
</div>
<p class="variant-note">best for: nested cards inside white panels</p>
</div>
<!-- F: Horizontal / compact -->
<div class="cell">
<span class="variant-label">F · Horizontal</span>
<div class="card v-horizontal"
data-snippet='<Card variant="outlined" layout="row" padding={PAD} border="BORDER">
<Card.Header avatar title="Weekly planning" />
<Card.Meta tags={["Q2", "Roadmap"]} />
<Button variant="ghost">Open</Button>
</Card>'>
<div class="card-head">
<div class="avatar">WP</div>
<div class="card-titles">
<p class="card-title">Weekly planning</p>
<p class="card-sub">12 tasks · due Friday</p>
</div>
</div>
<div class="chips">
<span class="chip">Q2</span>
<span class="chip olive">Roadmap</span>
</div>
<button class="ghost-btn">Open</button>
</div>
<p class="variant-note">best for: compact row lists, sidebars</p>
</div>
</div>
<!-- ---------- Snippet ---------- -->
<div class="snippet-panel">
<div class="snippet-head">JSX — hover a variant above</div>
<pre id="snippet">// hover a card to preview its props</pre>
</div>
</div>
<script>
(function () {
var root = document.documentElement;
var pad = document.getElementById('ctl-pad');
var padOut = document.getElementById('pad-out');
var shadow = document.getElementById('ctl-shadow');
var snippet = document.getElementById('snippet');
var currentBorder = 'hairline';
var borderMap = {
none: 'none',
hairline: '1px solid var(--gray-300)',
solid: '1.5px solid var(--gray-300)'
};
function applyPad() {
root.style.setProperty('--card-pad', pad.value + 'px');
padOut.textContent = pad.value + 'px';
}
function applyBorder(v) {
currentBorder = v;
root.style.setProperty('--card-border', borderMap[v]);
}
function applyShadow() {
root.style.setProperty('--card-shadow',
shadow.checked ? '0 4px 14px rgba(20,20,19,0.08)' : 'none');
}
pad.addEventListener('input', applyPad);
shadow.addEventListener('change', applyShadow);
document.querySelectorAll('input[name="border"]').forEach(function (r) {
r.addEventListener('change', function () { applyBorder(r.value); });
});
document.querySelectorAll('.card').forEach(function (card) {
card.addEventListener('mouseenter', function () {
var raw = card.getAttribute('data-snippet') || '';
snippet.textContent = raw
.replace(/PAD/g, pad.value)
.replace(/BORDER/g, currentBorder);
});
});
applyPad(); applyBorder('hairline'); applyShadow();
})();
</script>
</body>
</html>
<!-- Copyright 2026 Anthropic PBC · SPDX-License-Identifier: Apache-2.0 -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Acme — Task completed micro-interaction</title>
<style>
:root {
--ivory: #FAF9F5;
--slate: #141413;
--clay: #D97757;
--oat: #E3DACC;
--olive: #788C5D;
--gray-50: #F0EEE6;
--gray-200: #D1CFC5;
--gray-500: #87867F;
--gray-800: #3D3D3A;
--white: #ffffff;
--serif: ui-serif, Georgia, "Times New Roman", serif;
--sans: system-ui, -apple-system, "Segoe UI", sans-serif;
--mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
/* swapped at runtime by the easing panel */
--ease: cubic-bezier(0.34, 1.56, 0.64, 1);
}
* { box-sizing: border-box; }
html, body {
margin: 0;
background: var(--ivory);
color: var(--slate);
font-family: var(--sans);
font-size: 14px;
line-height: 1.5;
}
.wrap {
max-width: 1080px;
margin: 0 auto;
padding: 48px 32px 64px;
}
header { margin-bottom: 28px; }
.eyebrow {
font-family: var(--mono);
font-size: 11px;
letter-spacing: 0.08em;
text-transform: uppercase;
color: var(--gray-500);
}
h1 {
font-family: var(--serif);
font-weight: 500;
font-size: 30px;
letter-spacing: -0.01em;
margin: 6px 0 4px;
}
.sub {
color: var(--gray-500);
max-width: 560px;
}
/* ---------- layout ---------- */
.bench {
display: grid;
grid-template-columns: 1fr 240px;
gap: 24px;
align-items: start;
}
.stage {
background: var(--white);
border: 1.5px solid var(--gray-200);
border-radius: 12px;
height: 360px;
display: flex;
align-items: center;
justify-content: center;
position: relative;
overflow: hidden;
}
.hint {
position: absolute;
bottom: 14px;
left: 50%;
transform: translateX(-50%);
font-family: var(--mono);
font-size: 11px;
color: var(--gray-500);
}
/* ---------- the task row ---------- */
.task {
display: flex;
align-items: center;
gap: 14px;
padding: 14px 18px;
border: 1.5px solid var(--gray-200);
border-radius: 8px;
background: var(--white);
width: 360px;
max-height: 64px;
position: relative;
transition: max-height 280ms var(--ease) 600ms,
opacity 280ms var(--ease) 600ms,
padding 280ms var(--ease) 600ms,
border-color 200ms var(--ease);
cursor: pointer;
user-select: none;
}
.task:hover { border-color: var(--gray-500); }
.check {
flex: none;
width: 24px;
height: 24px;
border-radius: 50%;
border: 1.5px solid var(--gray-500);
background: var(--white);
position: relative;
transition: background 180ms var(--ease),
border-color 180ms var(--ease),
transform 260ms var(--ease);
}
.check svg {
position: absolute;
inset: 0;
margin: auto;
width: 14px;
height: 14px;
}
.check path {
stroke: var(--white);
stroke-width: 2.5;
stroke-linecap: round;
stroke-linejoin: round;
fill: none;
stroke-dasharray: 20;
stroke-dashoffset: 20;
transition: stroke-dashoffset 220ms var(--ease) 80ms;
}
.label {
position: relative;
font-size: 15px;
color: var(--slate);
transition: color 200ms var(--ease) 120ms;
}
.label::after {
content: "";
position: absolute;
left: 0;
top: 52%;
height: 1.5px;
width: 0;
background: var(--gray-500);
transition: width 240ms var(--ease) 120ms;
}
.due {
margin-left: auto;
font-family: var(--mono);
font-size: 11px;
color: var(--gray-500);
background: var(--gray-50);
border: 1.5px solid var(--gray-200);
padding: 3px 8px;
border-radius: 8px;
transition: opacity 200ms var(--ease) 120ms;
}
/* confetti — six particles, css-only, driven by .done on the row */
.confetti {
position: absolute;
left: 22px;
top: 50%;
width: 6px;
height: 6px;
border-radius: 2px;
opacity: 0;
pointer-events: none;
}
.confetti.c1 { background: var(--clay); }
.confetti.c2 { background: var(--olive); }
.confetti.c3 { background: var(--oat); }
.confetti.c4 { background: var(--clay); }
.confetti.c5 { background: var(--olive); }
.confetti.c6 { background: var(--gray-800); }
/* ---------- done state ---------- */
.task.done .check {
background: var(--olive);
border-color: var(--olive);
transform: scale(1.12);
animation: settle 380ms var(--ease) forwards;
}
@keyframes settle {
0% { transform: scale(0.8); background: var(--clay); border-color: var(--clay); }
55% { transform: scale(1.18); }
100% { transform: scale(1); background: var(--olive); border-color: var(--olive); }
}
.task.done .check path { stroke-dashoffset: 0; }
.task.done .label { color: var(--gray-500); }
.task.done .label::after { width: 100%; }
.task.done .due { opacity: 0.35; }
.task.done {
max-height: 44px;
padding-top: 8px;
padding-bottom: 8px;
opacity: 0.6;
}
.task.done .confetti { animation: pop 520ms var(--ease) 200ms forwards; }
.task.done .confetti.c1 { --dx: -28px; --dy: -22px; --rot: 40deg; }
.task.done .confetti.c2 { --dx: -6px; --dy: -34px; --rot: -60deg; }
.task.done .confetti.c3 { --dx: 18px; --dy: -26px; --rot: 90deg; }
.task.done .confetti.c4 { --dx: 30px; --dy: -4px; --rot: -30deg; }
.task.done .confetti.c5 { --dx: -24px; --dy: 14px; --rot: 20deg; }
.task.done .confetti.c6 { --dx: 12px; --dy: 22px; --rot: -80deg; }
@keyframes pop {
0% { opacity: 0; transform: translate(0, 0) rotate(0) scale(0.6); }
15% { opacity: 1; }
100% { opacity: 0; transform: translate(var(--dx), var(--dy)) rotate(var(--rot)) scale(1); }
}
/* ---------- easing panel ---------- */
.panel {
background: var(--white);
border: 1.5px solid var(--gray-200);
border-radius: 12px;
padding: 18px;
}
.panel h2 {
font-family: var(--serif);
font-weight: 500;
font-size: 16px;
margin: 0 0 4px;
}
.panel p {
margin: 0 0 14px;
font-size: 12px;
color: var(--gray-500);
}
.ease-btn {
display: block;
width: 100%;
text-align: left;
background: var(--gray-50);
border: 1.5px solid var(--gray-200);
border-radius: 8px;
padding: 10px 12px;
margin-bottom: 8px;
font-family: var(--sans);
font-size: 13px;
color: var(--slate);
cursor: pointer;
}
.ease-btn:hover { border-color: var(--gray-500); }
.ease-btn.active {
border-color: var(--clay);
background: #FBF1EC;
}
.ease-btn code {
display: block;
font-family: var(--mono);
font-size: 10px;
color: var(--gray-500);
margin-top: 2px;
}
/* ---------- timeline ---------- */
.timeline {
margin-top: 28px;
background: var(--white);
border: 1.5px solid var(--gray-200);
border-radius: 12px;
padding: 22px 22px 30px;
}
.timeline h2 {
font-family: var(--serif);
font-weight: 500;
font-size: 16px;
margin: 0 0 18px;
}
.track {
position: relative;
height: 2px;
background: var(--gray-200);
margin: 20px 8px 0;
}
.key {
position: absolute;
top: -5px;
width: 12px;
height: 12px;
border-radius: 50%;
background: var(--clay);
border: 1.5px solid var(--white);
box-shadow: 0 0 0 1.5px var(--clay);
transform: translateX(-50%);
}
.key span {
position: absolute;
top: 16px;
left: 50%;
transform: translateX(-50%);
white-space: nowrap;
font-family: var(--mono);
font-size: 10px;
color: var(--gray-800);
}
.key em {
position: absolute;
bottom: 16px;
left: 50%;
transform: translateX(-50%);
white-space: nowrap;
font-style: normal;
font-size: 11px;
color: var(--gray-500);
}
.k1 { left: 0%; }
.k2 { left: 13%; }
.k3 { left: 20%; }
.k4 { left: 33%; }
.k5 { left: 100%; background: var(--olive); box-shadow: 0 0 0 1.5px var(--olive); }
/* ---------- snippet ---------- */
.snippet {
margin-top: 28px;
}
.snippet h2 {
font-family: var(--serif);
font-weight: 500;
font-size: 16px;
margin: 0 0 10px;
}
pre {
background: var(--gray-800);
color: var(--gray-50);
border-radius: 12px;
padding: 18px 20px;
font-family: var(--mono);
font-size: 12px;
line-height: 1.7;
overflow-x: auto;
margin: 0;
}
pre .c { color: var(--gray-500); }
pre .k { color: var(--clay); }
pre .v { color: #B8C99D; }
</style>
</head>
<body>
<div class="wrap">
<header>
<div class="eyebrow">Acme / prototype / micro-interaction</div>
<h1>Task completed</h1>
<p class="sub">
A single click should feel like a tiny win. Circle fills, check draws,
label strikes, a small burst, then the row quietly steps back. Click
the row to play; click again to reset.
</p>
</header>
<div class="bench">
<div class="stage">
<div class="task" id="task">
<div class="check">
<svg viewBox="0 0 16 16"><path d="M3 8.5 L6.5 12 L13 4.5"/></svg>
</div>
<span class="label">Send weekly digest</span>
<span class="due">Fri</span>
<div class="confetti c1"></div>
<div class="confetti c2"></div>
<div class="confetti c3"></div>
<div class="confetti c4"></div>
<div class="confetti c5"></div>
<div class="confetti c6"></div>
</div>
<div class="hint">click to toggle</div>
</div>
<aside class="panel">
<h2>Easing</h2>
<p>Swaps <code>--ease</code> across every transition so you can feel the difference.</p>
<button class="ease-btn" data-ease="linear">
Linear
<code>linear</code>
</button>
<button class="ease-btn" data-ease="cubic-bezier(0.16, 1, 0.3, 1)">
Ease-out
<code>cubic-bezier(.16, 1, .3, 1)</code>
</button>
<button class="ease-btn active" data-ease="cubic-bezier(0.34, 1.56, 0.64, 1)">
Spring
<code>cubic-bezier(.34, 1.56, .64, 1)</code>
</button>
</aside>
</div>
<section class="timeline">
<h2>Keyframes</h2>
<div class="track">
<div class="key k1"><em>fill</em><span>0ms</span></div>
<div class="key k2"><em>check</em><span>80ms</span></div>
<div class="key k3"><em>strike</em><span>120ms</span></div>
<div class="key k4"><em>confetti</em><span>200ms</span></div>
<div class="key k5"><em>collapse</em><span>600ms</span></div>
</div>
</section>
<section class="snippet">
<h2>Copy-paste CSS</h2>
<pre><span class="c">/* circle: clay flash, settle to olive with spring overshoot */</span>
<span class="k">.task.done .check</span> {
animation: settle 380ms <span class="v">cubic-bezier(.34,1.56,.64,1)</span> forwards;
}
<span class="k">@keyframes settle</span> {
0% { transform: scale(.8); background: <span class="v">#D97757</span>; }
55% { transform: scale(1.18); }
100% { transform: scale(1); background: <span class="v">#788C5D</span>; }
}
<span class="c">/* checkmark draws via stroke-dashoffset, 80ms delay */</span>
<span class="k">.check path</span> { stroke-dasharray: 20; stroke-dashoffset: 20;
transition: stroke-dashoffset 220ms var(--ease) 80ms; }
<span class="k">.task.done path</span> { stroke-dashoffset: 0; }
<span class="c">/* strikethrough grows left → right */</span>
<span class="k">.label::after</span> { width: 0; transition: width 240ms var(--ease) 120ms; }
<span class="k">.task.done .label::after</span> { width: 100%; }
<span class="c">/* row steps back after the celebration */</span>
<span class="k">.task.done</span> { max-height: 44px; opacity: .6;
transition-delay: 600ms; }</pre>
</section>
</div>
<script>
var task = document.getElementById('task');
task.addEventListener('click', function () {
task.classList.toggle('done');
});
var root = document.documentElement;
var buttons = document.querySelectorAll('.ease-btn');
buttons.forEach(function (btn) {
btn.addEventListener('click', function () {
buttons.forEach(function (b) { b.classList.remove('active'); });
btn.classList.add('active');
root.style.setProperty('--ease', btn.dataset.ease);
});
});
</script>
</body>
</html>
Code of Conduct
Our Pledge
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
Our Standards
Examples of behavior that contributes to a positive environment include:
- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
- Focusing on what is best for the overall community
Examples of unacceptable behavior include:
- The use of sexualized language or imagery, and sexual attention or advances of
any kind
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or email address,
without their explicit permission
- Other conduct which could reasonably be considered inappropriate in a
professional setting
Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers at opensource@anthropic.com. All complaints will be reviewed and investigated promptly and fairly.
Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
[homepage]: https://www.contributor-covenant.org
The unreasonable effectiveness of HTML — examples
Sample code. Not maintained and not accepting contributions.
A gallery of standalone HTML examples that accompany the blog post on using HTML as a flexible output format. Each file is a self-contained .html page (no build step, no dependencies) demonstrating a different use case — from code review and design systems to slide decks, status reports, and small interactive editors.
Open `index.html` for the full, categorized index, or open any numbered file directly in a browser.
Contents
| Category | Examples |
|---|---|
| Exploration | code approaches, visual designs |
| Code | review, understanding, design systems, component variants |
| Prototyping | animation, interaction |
| Communication | slide deck, status report, incident report, PR write-up |
| Diagrams & research | flowchart, feature/concept explainers |
| Custom editing UIs | triage board, feature flags, prompt tuner |
Running
There is nothing to install or build. Clone the repo and open index.html (or any individual file) in a web browser.
A note on sample data
All product names, data, and scenarios in these examples are fictional and used only for illustration. The placeholder brand "Acme" and any figures shown are not real.
Security
See SECURITY.md for how to report a vulnerability.
License
Released under the Apache License 2.0.
Security Policy
Reporting a vulnerability
If you believe you have found a security vulnerability in this repository, please report it responsibly.
- Do not open a public issue for security problems.
- Email security@anthropic.com with a description of the issue and steps to
reproduce it.
We will acknowledge your report, investigate, and keep you informed of the resolution.
Scope
This repository contains static, self-contained HTML example files with no server-side components, no build pipeline, and no third-party runtime dependencies. The most likely relevant reports are issues such as unsafe inline script behavior or content that could mislead a reader. General questions about the accompanying blog post are not security issues — please use normal issues for those.
Related skills
Agent BrowserGive their coding agent reliable, high-fidelity control over any website or Electron desktop app.591k39.6k
Lark ApprovalLet their AI coding agent create, read, update, and approve items in Lark (Feishu) approval workflows without leaving the coding environment.494kLark EventHandle Feishu/Lark bot events, webhooks, and subscription callbacks in agent-driven backend code.493kLark Workflow Meeting SummaryAutomatically generate structured meeting summaries and action items from Lark/Feishu calls without manual note-taking.492kLark Workflow Standup ReportAutomatically generate and post daily standup reports in Lark/Feishu from their workflow and activity data.492k
Twitter AutomationAutomate X/Twitter posts, scheduling, and engagement via X API integration441k669How it compares
Pick html-plan for single-file dark-mode planning HTML; pick markdown or Notion export skills when collaborators need editable wiki workflows.
FAQ
What does html-plan do?
Create a self-contained HTML plan that is pragmatic, simple, and visually organized. Use when the user wants a plan page in the effective HTML style, wants the writing kept close to what they gave you, or wants the gramm
When should I use html-plan?
Create a self-contained HTML plan that is pragmatic, simple, and visually organized. Use when the user wants a plan page in the effective HTML style, wants the writing kept close to what they gave you, or wants the gramm
What are common prerequisites?
--- name: html-plan description: Create a self-contained HTML plan that is pragmatic, simple, and visually organized.
Automation & Workflowsintegrations