opencode-skills-collection 3.1.12 → 3.1.14

package/bundled-skills/design-spatial/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: design-spatial
+description: Design — spatial composition
+risk: unknown
+source: https://github.com/connerkward/ckw-design-skill/tree/main/deterministic-design/design-spatial
+source_repo: connerkward/ckw-design-skill
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/connerkward/ckw-design-skill/blob/main/LICENSE
+---
+
+# Design — spatial composition
+## When to Use
+
+Use this skill when you need design — spatial composition.
+
+
+A model cannot trust its own UI output. Everything else follows from two failures.
+
+## 1. It can't see what it made
+
+UI is generated as a token stream, never as pixels — so the model cannot perceive collisions, overlap, imbalance, or broken spacing. It will write a headline that runs into the hero image and have no idea.
+
+**Render it and judge the image, not the code.** Serve with any static server (e.g. `python3 -m http.server` or `npx serve`) and screenshot headless via Playwright. Screenshot at a few widths.
+
+**Critique with fresh eyes — not your own.** Grading your own output rationalizes it; the builder looks at its overlapping headline and calls it fine (this is exactly how a real collision shipped in testing). Use a separate judge — a subagent that did *not* write the page — and tell it to hunt for what's *wrong*: collisions, edge tangents, ragged alignment, lopsided weight, no clear focal point, breaks at some width. Fix, re-render, re-judge.
+
+## 2. Its first idea is the average
+
+Whatever it produces first is the mean of its training data — and there is more than one mean:
+
+- the **generic-AI mean**: Inter, purple-on-white gradients, centered single column, three equal cards;
+- the **designer-trend mean**: oversized condensed caps, dark-mode + grain, monospace "vibes" microtext, sticker badges.
+
+Landing on the second isn't taste — it's a more flattering average, which is why it slips past. **Treat your first instinct as the mean and deviate deliberately — toward *this product's specific world*** (use design-thinking's domain / color-world / signature as the direction), **not toward another trend.** If the result could be any startup, you shipped the mean.
+
+## 3. So don't prescribe a style
+
+Any fixed rule — a 12-col grid, an 8-point scale, "mono = data" — *becomes* next cycle's mean, and a blind model executes it into collisions anyway. Prescribe the **process, not the look**: see it with fresh eyes, and push off the average toward the domain. Taste supplies the direction (design-thinking / design-philosophy); this skill only insists you **look** and **don't ship the mean**.
+
+For iterative spatial tuning, a local page with live controls (sliders, pickers, drag handles) beats one-shot critique.
+
+## 4. NEVER ship horizontal overflow — THE mandatory gate, no exceptions
+
+> **BLOCKING GATE. You may not call any web UI "done", "working", "fixed", or
+> "looks good" until you have run the `scrollWidth` check below at a narrow width
+> THIS turn and seen `0`. Not "I added overflow-x:clip so it's fine." Not "it
+> looked fine at my width." MEASURE. Narrow. Every time. If you didn't measure,
+> it isn't done — say "haven't checked overflow yet" instead of claiming done.**
+
+A side-to-side scrollbar that doesn't match the content is the **single most common
+and most embarrassing** layout failure, and it ships *over and over* because the dev
+viewport is wide enough to hide it — the overflow only appears once the window is
+narrower than some element. It is **invisible at desktop width**, so the §1
+render-critique loop will NOT catch it unless you screenshot narrow. Separate,
+explicit, non-negotiable gate.
+
+**It recurs because layouts GROW after they were last checked.** Every time you add a
+nav tab, a toolbar button, a header control, a chip, a wider equation/`<pre>`, or any
+new item to a `flex`/`inline` row, you have invalidated the last overflow check — the
+row that fit yesterday now pushes past the edge between ~720–1200px while your 1440px
+dev window shows nothing wrong. (Real ship, 2026-06, TWICE: a progress-bar edge label
+overflowed 23px; then a `flex-wrap:nowrap` header that grew 4 tabs scrolled the whole
+page 309px across 720–1200px — both invisible at dev width, both caught only by
+measuring narrow.) **So: any change that adds an element to a horizontal row re-arms
+this gate. Re-measure.**
+
+**Default defenses to apply up front (so the gate passes by construction):**
+- **Header / nav / toolbar rows: `flex-wrap: wrap`, never `nowrap`.** A growing
+  single-row flex is the #1 source of this bug. Wrapping is a no-op when it fits and
+  saves you when it doesn't.
+- **`body { overflow-x: clip }`** as a backstop on every app (clip, not hidden — keeps
+  sticky/anchored layouts working). A backstop, NOT a substitute for measuring.
+
+**The check — run before calling ANY page done:** `document.documentElement.scrollWidth - document.documentElement.clientWidth` must equal `0`, tested at your dev width AND resized narrow (≤1024px, and a phone width ~390px). If > 0, find the offender:
+```js
+document.querySelectorAll('*').forEach(el=>{const r=el.getBoundingClientRect();
+  if(r.right>innerWidth+1||r.left<-1) console.log(Math.round(r.right), el);});
+```
+
+**Safety net:** `overflow-x: clip` on `body` (prefer `clip` over `hidden` — it clips without creating a scroll container, so it won't break `position:sticky`/anchored layouts). But a net is not a fix — **find and kill the root cause:**
+
+- **`position:absolute` + `white-space:nowrap` anchored at an edge** (`left:100%`, `right:0`): a *centered* nowrap label on the right edge juts past the viewport. (Real ship, 2026-06: a progress bar's "300 · learned model" milestone label at `left:100%` with `translateX(-50%)` overflowed 23px → phantom horizontal scroll at sub-1180px widths.) **Anchor edge labels inward** — right end `right:0; transform:none`, left end `left:0; transform:none`.
+- **`100vw`** — includes the scrollbar width (~15px), so on any vertically-scrolling page it guarantees ~15px of horizontal overflow. Use `100%`.
+- **flex / grid children without `min-width:0`** — they refuse to shrink below their content and blow out the track (a long title in a flex card, a `<pre>` in a grid cell). Add `min-width:0`.
+- **long unbreakable strings** (URLs, hashes, tokens): `overflow-wrap:anywhere` or `word-break:break-word`.
+- fixed pixel widths wider than the viewport; large negative margins; oversized `position:absolute` elements.
+
+The generalization: **anything pinned to an edge or sized in viewport units is a horizontal-overflow suspect — test narrow, measure `scrollWidth`, clip the body as backstop, and anchor edge-pinned content inward.**
+
+## 5. Lay out in TASK order — minimize transition cost
+
+Before placing elements, **walk the user's actual step sequence for completing the
+page's action**, then arrange elements in that same perceptual/view order. The
+layout should read like the task: orient → work → confirm. Any mouse travel or
+scrolling that serves no practical purpose is a defect.
+
+- **Orient at top:** controls/options up top are good — they tell the user what
+  the page is for and what it can do before they commit to reading it.
+- **Confirm where the work ENDS:** if the task is "review a long list, then act"
+  (approve, flag, submit, save), the action buttons must ALSO exist at the
+  bottom — where the user's eyes and cursor are when they finish. The original
+  failure: a delete-review page with confirm buttons only in the top toolbar —
+  after scrolling through 120 images, the user had to scroll all the way back up
+  to click "flag the rest." Duplicate the action bar at the bottom (or make the
+  toolbar sticky); both are one line of code, the scroll-back is paid per page.
+- **The heuristic: save the user transit time.** Every interaction has a path:
+  where the eyes/cursor are when a step ends vs where the next step's control
+  is. Sum those distances; shrink the big ones. Fitts's law for the page as a
+  whole, not just one button.
+- **Check it in the render-and-critique loop (§1):** ask the judge "trace the
+  task: where is the user when they finish each step, and how far is the next
+  control?" — a layout can be aligned, balanced, and still force a round trip.
+
+## 6. Balance is measurable — don't eyeball it (or trust a VLM's eye)
+
+§1 says render and have fresh eyes critique it. That qualitative pass catches
+collisions and ragged alignment, but **a model has no reliable sense of visual
+balance** — ask a VLM "is this centered / balanced?" and it confabulates a verdict.
+The fix is to stop asking opinions and **measure a number**, then keep that number
+honest with an *independent* check. Use both: §1's fresh-eyes critique AND the hard
+number below. (This pairs a live in-browser box model + auto-balancer with an
+offline pixel-oracle that re-measures the rendered screenshot — see the
+`layout-audit.js` companion script in this skill.)
+
+**The principle.** Visual balance is the *center of mass of visual weight*. It's
+arithmetic, not taste — so compute it.
+
+**Optical center, not geometric.** Target `x = 0.50`, `y ≈ 0.46` — slightly high,
+because a centroid at literal 50% reads as sagging.
+
+**Visual weight = area × ink-density, not area alone.** Same-size ≠ same-weight: a
+solid-black heading is heavy; a grey/ASCII/light image reads far lighter than its
+area; body text is sparse. Calibrated starting multipliers (from `asym.html`, re-tune
+per project — these were hand-guesses until corrected against the pixel oracle):
+```js
+const DENS = {portrait:0.34, h1:0.82, kicker:0.42, lead:0.22, body:0.16, meta:0.5};
+```
+
+**Centroid.** Per axis, `centroid = Σ(wᵢ·posᵢ) / Σwᵢ`; balanced ⇔ the centroid sits
+on the optical center. To FIX imbalance, think see-saw: what counts is the **moment**
+= weight × distance-from-axis, so a heavy element near the edge is counterweighted by
+(a) an opposing weight, (b) a bigger element on the other side, (c) pulling the heavy
+element inward (shorter lever arm), or (d) shrinking it. That's exactly the
+auto-balancer's escalation order in `asym.html` — grow the opposing heading first
+(cheapest), then add weight, then pull the heavy element in, then shrink it (last
+resort).
+
+**Two models — and why you need the independent one:**
+- **Cheap box model** (live tuning): put each element's weight at its bounding-box
+  *center*. Instant, fine for dragging sliders. BUT it has a systematic bug —
+  left-aligned text's ink sits *left* of its box, so the box model misplaces the
+  weight. A metric that shares the layout's own assumptions is **circular**; it once
+  reported "balanced" at a pixel-measured 0.93 lopsided.
+- **Ground-truth pixel oracle** (`analyze.py`): rasterize the *rendered* page
+  (Playwright screenshot or html2canvas) and take the centroid of actual non-paper
+  pixels, weighting each pixel by its distance from the background color. It knows
+  nothing about the layout's intent — it just counts ink. **When the box model and
+  the pixels disagree, the pixels win.** (`asym.html` closes the loop: it regresses
+  the box-vs-pixel discrepancy and offers a trust dial α to blend toward the oracle.)
+- **Acceptance criterion (measurable):** `|centroid_x − 0.50| < 0.03` and
+  `|centroid_y − 0.46| < 0.04`, plus low left/right and top/bottom imbalance
+  (`|w_left − w_right| / total`).
+
+**The verification gate (lighter than §4's, same spirit).** Before calling a
+balance-critical layout "balanced", do NOT assert it from the code or a VLM opinion —
+screenshot the *rendered* page, compute the ink-centroid offset from optical center,
+and report the actual number. This is the design-skill application of
+`verify-outputs-rule`: look at the real artifact, and make the validating check
+(pixels) independent of the thing you tuned (the layout). It's the quantitative
+complement to §1's qualitative critique.
+
+## 7. The layout audit — metrics that MEDIATE the eye, never replace it
+
+§6 covers balance; this generalizes it to a full deterministic sweep, and fixes the
+failure mode that matters most: **the model reads a metric/JSON and never looks at the
+screenshot, so it can't apply the common sense that catches the metric being wrong.**
+
+`scripts/layout-audit.js` is a dependency-free pass you run via Playwright MCP
+`browser_evaluate` on a rendered page. It measures six things deterministically — all
+geometry, color, and pixels, no "does this look right?":
+
+| check | how (deterministic) | tier |
+|---|---|---|
+| **collision** | content-rect intersection ≥12% | gate |
+| **contrast** | WCAG luminance ratio of text vs effective bg (<4.5, large <3) | gate |
+| **tap** | interactive targets <44×44 (Apple HIG) | gate |
+| **overflow** | `scrollWidth − clientWidth` (the §4 gate) | gate |
+| **alignment** | left-edge clusters → near-misses 1–7px off the shared line | signal |
+| **spacing** | gap CoV among a container's children | signal |
+| **balance** | ink-density-weighted centroid vs optical center (§6) | signal |
+
+**What makes it mediate rather than replace:** it doesn't just return JSON — it **draws
+every finding as an SVG overlay onto the page**, so the *next* `browser_take_screenshot`
+is an **annotated screenshot**. The number tells you WHERE to look; you then look and
+decide. This is mandatory, not optional:
+
+```
+browser_evaluate({ function: "() => { <paste scripts/layout-audit.js> ; return __audit({}); }" })
+browser_take_screenshot()      // ← the overlay is now on the page. VIEW IT. Reason over it.
+```
+
+Pass `{align:'.card .title,.card .price', space:'.feature-list'}` to scope the two
+selector-dependent checks; pass `{contentSelector:'…'}` for non-semantic layouts where
+collision needs help finding the blocks.
+
+**These are HEURISTICS, not laws — and they split into two kinds you must not conflate:**
+
+- **GATES = correctness** (overflow, contrast, tap). These measure accessibility/
+  usability *facts*, not taste. Failing one is a real defect. Safe to **block** on.
+  (Collision is a near-gate: usually a real bug, but can be intentional — so eye-confirm,
+  don't auto-fail.)
+- **SIGNALS = convention** (balance, alignment, spacing rhythm). These measure how
+  closely the layout matches a *symmetric, regular, gridded* aesthetic — which is exactly
+  the **generic mean** §2 tells you to push *away* from. **Optimizing a layout to maximize
+  these scores makes it blander.** An off-center balance, a deliberate misalignment, an
+  uneven rhythm are core creative tools and frequently the best thing on the page. Treat
+  signals as "worth a look," **never** as defects to fix.
+
+**The discipline (the whole point — bias hard toward this):**
+- **Never accept a metric you have not looked at.** A flag is a *pointer to look*, not a
+  verdict. Reading `collisions: 1` and acting without viewing the annotated shot is the
+  exact failure this section exists to kill.
+- **Use signals to catch ACCIDENTS, never to enforce convention.** A 7px alignment drift
+  you didn't mean, a phantom scrollbar, a 1.9:1 caption — catch those. But the *same*
+  balance/alignment/spacing signal fires on deliberate asymmetry, intentional overlap,
+  and expressive rhythm. **When the metric and the interesting choice conflict, the
+  interesting choice usually wins.** Do not "fix" a signal toward symmetry/evenness unless
+  the eye judges the deviation actually worse. A model that maximizes these scores designs
+  the mean.
+- **Overrule flags the eye judges intentional.** Brutalist headline overlap, avatar on a
+  banner, asymmetric hero — the metric flags them; common sense overrules. Proven live in
+  the worked example: obeying the collision check on the brutalist mock removes the overlap
+  and the design goes *flat*.
+- **Gates are necessary, not sufficient.** `gates_pass:true` (overflow/contrast/tap all 0)
+  clears the deterministic floor — it does **not** mean the layout is good. A bland centered
+  template passes every gate and is still the mean. After gates pass, the real judgment (§1
+  fresh-eyes critique, taste, brand fit) still has to happen.
+
+**The proof, made concrete:** build a page that runs all six algorithms live on a few
+realistic mock sites in different styles, each with a toggle between the layout **as
+designed** and the version **obeying the metric**, plus on-render overlays. It shows both
+halves: obeying a *gate* fixes a real bug (low-contrast CTA, sub-44 tap target, overlapping
+cards), while obeying a *signal* makes it worse (an asymmetric editorial hero is the more
+interesting layout; "correcting" a deliberate brutalist overlap flattens it). That explorable
+is where `layout-audit.js` was distilled from.
+
+## 8. Optical craft — perception beats geometry
+
+The audit's alignment check (§7) measures *geometric* edges. The eye doesn't read geometry,
+it reads perception — so a few cases need a manual nudge the metric can't make. These are
+eye-judgments, not gates. (From the Web Interface Guidelines, `vercel-labs/web-interface-guidelines` @ `4e799d4`.)
+
+- **Optical alignment — nudge ±1–2px when it *looks* off though it measures centered.** A
+  play-triangle in a round button must shift right of geometric center to look centered (its
+  visual mass is left-biased). Glyphs, arrows, and asymmetric icons often need the same. Text
+  vertically centered by box metrics frequently sits a hair low — lift it. Geometry is the
+  starting point; the eye is the judge.
+- **Balance icon/text lockups.** When an icon sits beside text, match their *visual weight* —
+  adjust the icon's stroke, size, spacing, or color so neither overpowers. A thin-stroke icon
+  next to medium-weight text looks weak; thicken its stroke (or size it up slightly) so they
+  read as one lockup. Optical size, not equal pixel size, is the target.
+- This is the same principle as the §6/§7 debias: the number gets you close; the eye makes the
+  final 1px call. Don't let a geometric alignment metric *prevent* an optical correction.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/design-spatial/scripts/layout-audit.js

@@ -0,0 +1,138 @@
+/* ============================================================================
+   layout-audit.js — deterministic layout metrics that MEDIATE the eye.
+
+   Run via Playwright MCP `browser_evaluate` on a rendered page. It does TWO things:
+     1. returns a compact JSON of measured findings (geometry, contrast, tap, balance)
+     2. DRAWS those findings as an SVG overlay onto the page, so the very next
+        `browser_take_screenshot` is an ANNOTATED screenshot.
+
+   The annotated screenshot is the whole point. You MUST view it and reason over the
+   picture + the numbers together — the metric tells you WHERE to look; your eyes
+   decide whether each flag is a real defect or an intentional choice (an avatar on a
+   banner "collides"; a brutalist overlap is the design). NEVER auto-fail on a count,
+   and never accept a metric you haven't looked at. The number points; the eye decides.
+
+   Usage (Playwright MCP):
+     browser_evaluate({ function: "() => { <paste this whole file> ; return __audit({}); }" })
+     browser_take_screenshot()          // <-- now shows the overlay; LOOK at it
+   Options (pass to __audit):
+     { align: '.card .title, .card .price',  // selector whose left edges SHOULD align
+       space: '.feature-list',               // container whose children's vertical rhythm to check
+       draw: true }                          // set false to measure without drawing
+   Re-run __clearAudit() to remove the overlay.
+   ============================================================================ */
+function __audit(opts){
+  opts = opts || {};
+  const DRAW = opts.draw !== false;
+  const COL = {collision:'#e0245e',align:'#d98a00',spacing:'#2f7fd6',contrast:'#8a2be2',tap:'#159a4d',balance:'#111'};
+  const vis = el => { const s=getComputedStyle(el); return s.display!=='none'&&s.visibility!=='hidden'&&el.getClientRects().length>0; };
+  const R = el => { const r=el.getBoundingClientRect();
+    return {el,x:r.left,y:r.top,w:r.width,h:r.height,r:r.right,b:r.bottom,cx:r.left+r.width/2,cy:r.top+r.height/2}; };
+
+  // ---- content set: visible, sized, leaf-ish "ink" elements (skip layout wrappers) ----
+  const CONTENT = (opts.contentSelector
+      ? [...document.querySelectorAll(opts.contentSelector)]
+      : [...document.querySelectorAll('h1,h2,h3,h4,p,li,img,svg,button,a,input,label,figure,blockquote,[class*="card"],[class*="tile"],[class*="btn"],[class*="hero"],[class*="banner"],[class*="panel"],[class*="badge"],[class*="chip"],[class*="thumb"],[class*="avatar"]')])
+    .filter(vis).map(R).filter(it=>it.w>=8&&it.h>=8&&it.w<innerWidth*1.5);
+
+  // 1. COLLISION — content rects overlapping ≥12% of the smaller (skip ancestor/descendant)
+  const collisions=[];
+  for(let i=0;i<CONTENT.length;i++)for(let j=i+1;j<CONTENT.length;j++){
+    const a=CONTENT[i],b=CONTENT[j];
+    if(a.el.contains(b.el)||b.el.contains(a.el))continue;
+    const ix=Math.max(0,Math.min(a.r,b.r)-Math.max(a.x,b.x)), iy=Math.max(0,Math.min(a.b,b.b)-Math.max(a.y,b.y));
+    if(ix*iy<=0)continue;
+    if(ix*iy/Math.min(a.w*a.h,b.w*b.h)>0.12) collisions.push([a,b]);
+  }
+
+  // 2. ALIGNMENT near-miss — only meaningful when scoped to elements that SHOULD share a line
+  let nearmiss=[], guides=[];
+  if(opts.align){
+    const els=[...document.querySelectorAll(opts.align)].filter(vis).map(R).sort((a,b)=>a.x-b.x);
+    let cur=[]; const cl=[];
+    els.forEach(e=>{ if(cur.length&&e.x-cur[cur.length-1].x>11){cl.push(cur);cur=[];} cur.push(e); });
+    if(cur.length)cl.push(cur);
+    cl.forEach(c=>{ if(c.length<2)return;
+      const xs=c.map(e=>e.x).sort((a,b)=>a-b), med=xs[(xs.length/2)|0], spread=xs[xs.length-1]-xs[0];
+      guides.push(med); if(spread<=0.8||spread>10)return;
+      c.forEach(e=>{ if(Math.abs(e.x-med)>0.8) nearmiss.push({x:e.x,med,y:e.y,b:e.b,cy:e.cy,off:Math.round(e.x-med)}); });
+    });
+  }
+
+  // 3. SPACING rhythm — vertical gaps among a container's direct children
+  let spacing={gaps:[],cov:0,outliers:[]};
+  if(opts.space){ const cont=document.querySelector(opts.space);
+    if(cont){ const kids=[...cont.children].filter(vis).map(R).sort((a,b)=>a.y-b.y), gaps=[];
+      for(let i=0;i<kids.length-1;i++){const g=kids[i+1].y-kids[i].b; if(g>-6&&g<400)gaps.push({g:Math.round(g),a:kids[i],b:kids[i+1]});}
+      if(gaps.length>=2){ const v=gaps.map(o=>o.g),mn=v.reduce((s,x)=>s+x,0)/v.length,
+        sd=Math.sqrt(v.reduce((s,x)=>s+(x-mn)**2,0)/v.length);
+        spacing={gaps,cov:mn?Math.abs(sd/mn):0,mean:mn,outliers:gaps.filter(o=>Math.abs(o.g-mn)>Math.max(6,Math.abs(mn)*0.5))}; }
+    }
+  }
+
+  // 4. CONTRAST — WCAG ratio of text vs effective background
+  const rgb=s=>{const m=(s||'').match(/rgba?\(([^)]+)\)/);if(!m)return null;const p=m[1].split(',').map(parseFloat);return{r:p[0],g:p[1],b:p[2],a:p[3]??1};};
+  const ebg=el=>{let n=el;while(n&&n.nodeType===1){const c=rgb(getComputedStyle(n).backgroundColor);if(c&&c.a>0.5)return c;n=n.parentElement;}return{r:255,g:255,b:255,a:1};};
+  const lum=({r,g,b})=>{const f=v=>{v/=255;return v<=0.03928?v/12.92:((v+0.055)/1.055)**2.4;};return .2126*f(r)+.7152*f(g)+.0722*f(b);};
+  const ratio=(a,b)=>{const L1=lum(a),L2=lum(b),hi=Math.max(L1,L2),lo=Math.min(L1,L2);return (hi+.05)/(lo+.05);};
+  const contrast=[];
+  [...document.querySelectorAll('h1,h2,h3,h4,h5,h6,p,a,span,li,button,label,td,th,figcaption,small,strong,em')].filter(vis).forEach(el=>{
+    const t=(el.childNodes.length&&[...el.childNodes].some(n=>n.nodeType===3&&n.textContent.trim()));if(!t)return;
+    const cs=getComputedStyle(el),fg=rgb(cs.color);if(!fg)return;
+    const ra=ratio(fg,ebg(el)),px=parseFloat(cs.fontSize),wt=parseInt(cs.fontWeight)||400,large=px>=24||(px>=18.66&&wt>=700);
+    if(ra < (large?3:4.5)){const r=R(el);contrast.push({x:r.x,y:r.y,w:r.w,h:r.h,ratio:Math.round(ra*10)/10,large});}
+  });
+
+  // 5. TAP — interactive targets under 44×44 (Apple HIG)
+  const tap=[...document.querySelectorAll('a,button,[role="button"],input:not([type="hidden"]),select,textarea,[onclick]')]
+    .filter(vis).map(R).filter(it=>it.w<44||it.h<44);
+
+  // 6. BALANCE — ink-density-weighted centroid (box-model ESTIMATE) vs optical center (0.50,0.46)
+  // NOTE: this is the cheap model. For ground truth, screenshot and run a pixel-centroid (see SKILL §6).
+  const DENS={H1:.82,H2:.62,H3:.5,H4:.45,P:.16,LI:.16,IMG:.5,SVG:.5,BUTTON:.7,A:.4};
+  const dens=el=>el.tagName in DENS?DENS[el.tagName]:0.3;
+  let W=0,Mx=0,My=0; const pw=document.documentElement.scrollWidth, ph=document.documentElement.scrollHeight;
+  CONTENT.forEach(it=>{const w=it.w*it.h*dens(it.el);W+=w;Mx+=w*(it.cx+scrollX);My+=w*(it.cy+scrollY);});
+  const balance = W?{cx:Mx/W/pw,cy:My/W/ph}:{cx:.5,cy:.46};
+  balance.off=Math.hypot(balance.cx-0.5,balance.cy-0.46);
+
+  // 7. OVERFLOW — horizontal scroll (the §4 gate)
+  const overflow=Math.max(0, document.documentElement.scrollWidth - document.documentElement.clientWidth);
+
+  // ---- draw overlay (this is what makes the next screenshot annotated) ----
+  __clearAudit();
+  if(DRAW){
+    const NS='http://www.w3.org/2000/svg', svg=document.createElementNS(NS,'svg');
+    svg.id='__auditOverlay';
+    Object.assign(svg.style,{position:'fixed',inset:'0',width:'100vw',height:'100vh',zIndex:2147483647,pointerEvents:'none'});
+    const add=(t,a)=>{const e=document.createElementNS(NS,t);for(const k in a)e.setAttribute(k,a[k]);if(a._t)e.textContent=a._t;svg.appendChild(e);};
+    collisions.forEach(([a,b])=>[a,b].forEach(it=>add('rect',{x:it.x,y:it.y,width:it.w,height:it.h,fill:COL.collision+'22',stroke:COL.collision,'stroke-width':2.5})));
+    guides.forEach(x=>add('line',{x1:x,y1:0,x2:x,y2:innerHeight,stroke:COL.align,'stroke-width':1,'stroke-dasharray':'6 5','opacity':.6}));
+    nearmiss.forEach(n=>{add('line',{x1:n.x,y1:n.y,x2:n.x,y2:n.b,stroke:COL.align,'stroke-width':3});add('text',{x:n.x+8,y:n.cy+4,fill:COL.align,'font-family':'monospace','font-size':13,_t:(n.off>=0?'+':'')+n.off+'px'});});
+    spacing.gaps.forEach(o=>{const bad=spacing.outliers.includes(o),x=Math.min(o.a.x,o.b.x)-16;add('line',{x1:x,y1:o.a.b,x2:x,y2:o.b.y,stroke:bad?COL.collision:COL.spacing,'stroke-width':bad?3.5:2});add('text',{x:x-7,y:(o.a.b+o.b.y)/2+4,fill:bad?COL.collision:COL.spacing,'font-family':'monospace','font-size':13,'text-anchor':'end',_t:o.g});});
+    contrast.forEach(c=>{add('rect',{x:c.x-2,y:c.y-2,width:c.w+4,height:c.h+4,fill:'none',stroke:COL.contrast,'stroke-width':2,'stroke-dasharray':'3 3'});add('rect',{x:c.x,y:c.y-19,width:64,height:17,fill:COL.contrast});add('text',{x:c.x+4,y:c.y-6,fill:'#fff','font-family':'monospace','font-size':12,_t:c.ratio+':1 ✗'});});
+    tap.forEach(it=>{add('rect',{x:it.x,y:it.y,width:it.w,height:it.h,fill:'none',stroke:COL.tap,'stroke-width':2.5});add('text',{x:it.x,y:it.b+13,fill:COL.tap,'font-family':'monospace','font-size':12,_t:Math.round(it.w)+'×'+Math.round(it.h)});});
+    document.body.appendChild(svg);
+  }
+
+  // ---- JSON summary, split by KIND. The metric is never a verdict on its own. ----
+  return {
+    // GATES — correctness (accessibility/usability facts). Safe to block on; gates_pass must hold.
+    gates: { overflow_px: overflow, contrast_fails: contrast.length, tap_too_small: tap.length },
+    gates_pass: overflow===0 && contrast.length===0 && tap.length===0,
+    // REVIEW — usually a real defect, but can be intentional (deliberate overlap). Eye-confirm; do NOT auto-fail.
+    collisions: collisions.length,
+    // SIGNALS — convention, NOT correctness. High score = closer to the symmetric/regular MEAN (§2).
+    // Deviation is often the better design. Use to catch accidents; never auto-correct toward symmetry.
+    signals: { balance_offset:+balance.off.toFixed(3), balance_centroid:[+balance.cx.toFixed(3),+balance.cy.toFixed(3)],
+               align_nearmiss: nearmiss.length, spacing_cov:+spacing.cov.toFixed(2) },
+    contrast_detail: contrast.map(c=>({ratio:c.ratio, large:c.large})),
+    note: 'These are HEURISTICS. (1) LOOK at the annotated screenshot — a flag marks WHERE to look, never a verdict. '
+        + '(2) GATES (overflow/contrast/tap) are correctness — fix them. (3) SIGNALS (balance/alignment/spacing) measure '
+        + 'CONVENTION = the generic mean; off-center balance, deliberate misalignment, uneven rhythm are creative tools — '
+        + 'do NOT "fix" a signal toward symmetry unless the eye judges the deviation worse. Maximizing signals designs the mean. '
+        + '(4) collisions: usually a bug, sometimes intentional (overlap aesthetics) — eye-confirm. '
+        + 'gates_pass is necessary, not sufficient; a passing layout can still be generic.'
+  };
+}
+function __clearAudit(){ const o=document.getElementById('__auditOverlay'); if(o)o.remove(); }

package/bundled-skills/design-system/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: design-system
+description: "Mechanical implementation invariants for frontend design: token architecture, typography hierarchy, loading order, FOUT prevention, chrome stability, motion timing, color semantics. Use with design when building components, pages, or design systems. (Aesthetic direction lives in..."
+risk: unknown
+source: https://github.com/connerkward/ckw-design-skill/tree/main/design-system
+source_repo: connerkward/ckw-design-skill
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/connerkward/ckw-design-skill/blob/main/LICENSE
+author: Conner K Ward
+---
+
+# Design system
+## When to Use
+
+Use this skill when you need mechanical implementation invariants for frontend design: token architecture, typography hierarchy, loading order, FOUT prevention, chrome stability, motion timing, color semantics. Use with design when building components, pages, or design systems. (Aesthetic direction lives in...
+
+
+Apply with **design** when implementing UI: components, pages, or design systems. Every color, type, and motion choice should trace back to these rules.
+
+## Token architecture
+
+All colors map to a small set of primitives. No random hex values.
+
+- **Foreground**: Text hierarchy (primary, secondary, muted).
+- **Background**: Surface elevation (base, raised, overlay).
+- **Border**: Separation hierarchy (subtle, default, emphasis).
+- **Brand**: Identity and primary accent.
+- **Semantic**: Destructive, warning, success (and optional info).
+
+Use tokens in code (CSS variables, theme objects); never hardcode hex for UI.
+
+## Typography
+
+- **Hierarchy**: Headlines — heavier weight, tighter letter-spacing for presence. Body — comfortable weight for readability. Labels/UI — medium weight, works at smaller sizes. Data — monospace, `tabular-nums` for alignment.
+- Combine size, weight, and letter-spacing so hierarchy is clear at a glance. If you squint and can't tell headline from body, hierarchy is too weak.
+- **Fonts**: pair a display font with a body font; keep hierarchy legible at a glance. *Which* fonts is direction, not mechanics — pick from the domain and push off your first/default instinct (the mean); see design-spatial §2.
+- **Data (functional only)**: real aligned numbers, IDs, timestamps in monospace with `tabular-nums` — mono earns its place when values line up in a column. Do NOT sprinkle mono on decorative eyebrow/metadata microtext ("35MM · DEVELOP · SCAN", fake spec captions) for a "technical" look — that's the current trend-slop, not data. See design-spatial §2.
+
+## Loading order — first seen, first loaded
+
+The first viewport must paint complete and correct, fast. Order every resource by whether the user sees it first; the rest waits.
+
+- **Prioritize only the above-the-fold set** (hero text, hero image/video, brand mark). Preloading everything is the same as preloading nothing — the true criticals lose the bandwidth race. Pick the few things in the first screenful and prioritize *those*.
+- **Fonts: self-host WOFF2.** Convert OTF/TTF → WOFF2 (Brotli; ~half the bytes, identical glyphs) and `<link rel="preload" as="font" type="font/woff2" crossorigin>` the weights used in the first viewport. Never a render-blocking third-party font stylesheet — a Google Fonts `<link>` adds a CSS round-trip plus extra DNS/TLS before the font even starts downloading; self-host instead.
+- **LCP image/video:** `fetchpriority="high"` on the hero image (or the video poster); `<link rel="preload" as="image">` it when it's CSS-referenced (the parser can't see CSS `url()`s early). The hero box must never be empty — ship a poster/low-res placeholder so there's no blank frame.
+- **Below the fold:** `loading="lazy" decoding="async"` on images; `preload="none"` (or `"metadata"`) on video; `defer` non-critical JS. Always reserve space (`aspect-ratio`, or `width`+`height`) so deferred media can't shift layout (CLS).
+- Keep the render-blocking head minimal: inline critical CSS, defer the rest.
+
+## Never let fonts pop in (no FOUT) — ever
+
+`font-display: swap` **is** the pop — it paints a fallback face, then swaps to the webfont and reflows. Do not use it for any text the user watches load (titles, wordmarks, hero copy). The rule is absolute: title/display text must never flash a fallback or reflow.
+
+- **Gate visibility on the real font.** Synchronously in `<head>`, add a `fonts-pending` class to `<html>` that holds the display-font text at `opacity: 0`. On `document.fonts.ready` — kick it with `document.fonts.load('<weight> 1em "Family"')` for each critical face — swap to `fonts-ready` and fade the text in (~0.5s). Always include a safety timeout (~2.5s) that reveals regardless, so a font failure can never leave text permanently hidden.
+- Pair this with preload + WOFF2 (above) so the hidden window is a few hundred ms, not seconds — the fade reads as intentional, not as a stall.
+- For body text where a sub-perceptual swap is tolerable, at minimum kill the reflow: define a fallback `@font-face` (or `font-family` fallback) tuned with `size-adjust` / `ascent-override` / `descent-override` so the fallback occupies the same metrics as the webfont and the swap shifts nothing.
+
+Worked example — an AR product-research page: a head script toggles `fonts-pending → fonts-ready` (titles fade in on `fonts.ready`, 2.5s fallback), preloads the four above-the-fold WOFF2 weights, and self-hosts the brand face so there's no Google round-trip.
+
+## Slow-loading content — never show the ugly intermediate state
+
+Anything that *could* take a noticeable moment to be ready — fonts (above), large images, video, `<canvas>` scenes, Three.js / WebGL, lazy-loaded React islands, anything that fetches over the network or runs heavy main-thread setup — must either **arrive fast** or **load gracefully**. The default browser behavior (blank box → partial paint → reflow → final state) is the ugly intermediate state. Catch it.
+
+Two levers; use both:
+
+- **Arrive faster.** Compress (WOFF2 for fonts, Draco for glTF, WebP/AVIF for images, h264/h265 for video with `preload="metadata"`). Preload the *few* assets the first viewport actually needs (`<link rel="preload">`). Lazy-load below-the-fold so the LCP set isn't competing. Reserve the box (`aspect-ratio`, `width`+`height`) so deferred content can't trigger CLS.
+- **Load gracefully.** Hide the in-flight state behind a styled placeholder, then fade the real thing in. Skeleton boxes, low-res blurred posters, a single ASCII glyph, even just the container's bg color — anything coherent with the design beats the default partial-paint.
+
+What "ugly" looks like, concretely, and the fix:
+
+| Symptom | Fix |
+|---|---|
+| Annotation labels stack at `translate(0,0)` (top-left of container) until JS positions them | Start labels at `opacity: 0` with a `transition: opacity ~0.35s`; first projection sets inline opacity → CSS fades them up. |
+| Canvas/WebGL paints empty/black for a frame on first render | Show a placeholder (CSS art, low-res poster image, or paper/skeleton fill) in the same box; remove it once the first real frame has rendered. |
+| Lazy image fetches and snaps in with a layout-jump | `aspect-ratio` + `<link rel="preload">` (above-the-fold) or `loading="lazy" decoding="async"` (below); fade from `opacity:0` on the `load` event for the first paint. |
+| Video poster pops to first frame on play | `poster` matches a still you control; once `playing` event fires, you've already had a clean handoff. |
+| 3D model "appears" mid-screen with no transition | Keep the canvas visible but at `opacity: 0`; toggle a `.viewer-ready` class (or set inline opacity) inside the GLTFLoader success callback, after the first `tick()`. |
+| Lazy React island flashes a fallback that looks worse than no UI | Replace `Suspense` fallback with a skeleton that traces the final layout, not a spinner. |
+
+Rule of thumb: if a user could screenshot the page mid-load and you'd be embarrassed, you owe it a graceful state. The placeholder doesn't have to be fancy — it has to be *intentional*, sized correctly, and in the design language of what's coming.
+
+## Chrome stays still — status text never resizes layout
+
+Persistent chrome (headers, nav, toolbars, search bars, status regions) must hold a **constant height** no matter what text lands in it. Transient status / loading / explanatory copy — "loading model…", "N matching · M indexed", empty-state hints — must not wrap to a second line and shove adjacent controls down. A status region that grows and shrinks as its message changes is a layout-jank bug, not dynamic content.
+
+- **Constrain to one line:** `white-space: nowrap; overflow: hidden; text-overflow: ellipsis` so the longest message truncates instead of wrapping.
+- **Reserve the space up front:** give the container a fixed `height` (or `min-height`) sized for the message, so the shortest and longest states — and the empty state — occupy the same footprint.
+
+Only the content area should move while chrome stays fixed; layout shift from transient text reads as broken polish. (Concrete failure this prevents: in a search app, a model-loading message wrapping to two lines and pushing the search bar downward.)
+
+## Motion
+
+- Keep timing consistent and purposeful; one well-orchestrated moment (staggered page load with `animation-delay`) beats scattered micro-interactions. Prefer CSS-only for HTML; Motion library for React. (Honor `prefers-reduced-motion` for public/multi-user projects.)
+- **Defaults for restrained/professional UIs** (a starting point, not law): micro-interactions ~150ms, larger transitions 200–250ms, ease-out. A playful/toy-like tone (design-thinking) may want spring/bounce and longer beats — match motion feel to the chosen direction rather than defaulting to these numbers.
+- **Choreography** — for anything beyond a single micro-interaction (route/page transitions, list reorder, reveals, shared elements), load [references/motion-choreography.md](references/motion-choreography.md): when a transition earns its keep (it must *communicate* something or get cut), which kinds to implement and in what order, **style by navigation type** (directional slide only for hierarchical/ordered — a slide between peers lies about depth; laterals fade), a duration table, and craft (compositor-only props, motion-blur on morphs, never raster-scale text, persistent-chrome isolation). Framework-agnostic.
+
+### Scroll-driven narrative (scrollytelling)
+
+For **explanatory / editorial / data-walkthrough** content, prefer **scroll-driven graphics over click-interactive widgets**. A reader scrolls by default; making them hunt for and click a toggle to advance an explanation adds friction and gets skipped. Use the NYT/Pudding pattern: pin one graphic (`position: sticky`) while short text "steps" scroll past it, and let each step drive the graphic's state.
+
+- **Mechanics:** one `IntersectionObserver` with `rootMargin: '-48% 0px -48% 0px'` (threshold 0) so a step goes "active" exactly as it crosses the viewport mid-line; the active index re-renders the pinned graphic. ~30 lines — this *is* scrollama minus the dependency; don't add a scroll library.
+- **Layout:** two columns — steps scroll in one, the graphic `sticky top-0 h-screen` in the other; stack on mobile with the graphic sticky on top. Give each step ~85vh so exactly one is centered at a time; dim the inactive step cards (`opacity:.3`) so the live one reads.
+- **Graphic is a pure function of the active step** (`graphic(active)`), holding no click state of its own — so it also screenshots/exports deterministically and degrades to a static figure. Animate *between* states (color / width / opacity, 300–700ms) so scrolling feels continuous, not steppy.
+- **When NOT to:** dashboards, tools, forms — anything the user *operates* rather than *reads* — stay interactive. Scrollytelling is for **narration**, where you own the order. (Public/multi-user builds: honor `prefers-reduced-motion` per the Motion note above; keep the state changes but drop the tweens.)
+
+## Spatial composition & layout
+
+Grid systems, the 8-point spacing scale, visual-weight balance, alignment, and the render-then-critique loop live in **design-spatial** ([../design-spatial/SKILL.md](../design-spatial/SKILL.md)) — the mechanical counterpart to this file's tokens/type/color. Load it whenever composing pages, dashboards, or components. (Direction nugget that belongs here: match composition ambition to the vision — maximalist earns elaborate/layered code; minimal/refined demands restraint and precise spacing.)
+
+## Nested radii (only when one rounded element sits inside another)
+
+Not a push to round things — this governs the case where a rounded element is nested in
+another (a button in a card, an inset panel in a container). When nested:
+
+- **Child radius ≤ parent radius**, never larger (a child corner rounder than its parent looks
+  like it's bulging out).
+- **Concentric** is the ideal: `child_radius = parent_radius − gap` (the padding between them),
+  so the two curves run parallel and the inner corner echoes the outer. Flat/unrounded children
+  in a rounded parent are fine; what reads as broken is mismatched, non-concentric curves.
+
+## Color
+
+- **Palette from domain**: colors should feel like they came *from* the product's world, not applied on top.
+- **Beyond temperature**: quiet vs loud, dense vs spacious, serious vs playful, geometric vs organic — not just warm/cool.
+- **Color carries meaning**: gray builds structure; color communicates status, action, emphasis, identity. Unmotivated color is noise. (Restraint — one accent, not five — is a direction principle; see design-thinking → *reserve impact for punctuation*.)
+- **Contrast — APCA for decisions, WCAG for the gate.** For *perceptual* contrast judgments (is this text comfortably readable on this surface?) prefer **APCA** ([apcacontrast.com](https://apcacontrast.com/)) — it models lightness perception far better than the WCAG 2 ratio, which mis-rates light-on-dark and mid-tones. Keep **WCAG 2 (4.5 / 3:1) as the compliance floor** — it's what `design-spatial`'s `layout-audit.js` gates on and what accessibility standards require. Use APCA to design, WCAG to certify.
+- **Interactive states gain contrast.** `:hover`, `:active`, `:focus` must read as *more* prominent than rest — more contrast, not less. A hover that lowers contrast (e.g. lightens text toward the bg) reads as disabled.
+
+Avoiding the generic/trend look (Inter, purple-on-white, the same dark-glass card) and varying across generations is **design-spatial §2** — not restated here.
+
+## Backgrounds & detail
+
+Atmosphere over flat fills — but matched to the chosen aesthetic, not a default. The reflexive gradient-mesh / noise / grain "premium" treatment is itself the designer-trend mean (design-spatial §2); reach for it only when the direction genuinely calls for it, never as decoration for its own sake.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.