@ctxr/skill-frontend-excellence 0.1.1

package/references/data-viz.md

@@ -0,0 +1,457 @@
+# Data Visualization
+
+Framework-agnostic guidance on charts, tables, and data-dense interfaces. Library-agnostic; the same principles apply to D3, Chart.js, Recharts, ECharts, Highcharts, Vega-Lite, and others.
+
+## The Hierarchy of Data Display
+
+When showing data, walk this list. The first that fits is the right choice.
+
+1. **One number with context.** "$48,231 monthly recurring revenue" beats a chart with one data point.
+2. **Comparison or ranking** (top 5, top 10). A list with bars beats a pie chart.
+3. **Trend over time.** A line chart.
+4. **Distribution.** Histogram, box plot.
+5. **Composition.** Stacked bar, treemap.
+6. **Relationship between two variables.** Scatter plot.
+7. **Geographic.** Map.
+8. **Detailed records.** Table.
+
+If you reach for a chart and a table or summary number works, use the simpler thing.
+
+## Choosing the Right Chart
+
+| Data | Best chart | Avoid |
+|------|-----------|-------|
+| Single value | Stat card with sparkline | Chart |
+| Trend over time | Line chart | Pie chart |
+| Compare 2-10 categories | Bar chart (horizontal if labels long) | Pie chart |
+| Compare 10-30 categories | Horizontal bar | Vertical bar (cramped on mobile) |
+| Compare > 30 categories | Top N + "Other" or table | Bar chart with all |
+| Composition (parts of whole, 2-5 categories) | Pie or donut | Pie with > 5 |
+| Composition over time | Stacked area | Pie carousel |
+| Distribution | Histogram or box plot | Bar chart of raw values |
+| Two-variable relationship | Scatter plot | Two side-by-side bar charts |
+| Multiple metrics over time | Multi-line, small multiples | Stacked line (hides individual values) |
+| Geographic | Choropleth map | Pie chart |
+| Hierarchical composition | Treemap or sunburst | Stacked bar |
+| Funnel (sequential drop-off) | Funnel chart | Bar chart |
+| Network / relationships | Graph / network diagram | Table |
+
+### Pie/donut rules
+
+- Maximum 5 categories. Beyond that, switch to bar.
+- Sum to 100%.
+- Order by size (largest first, clockwise from 12 o'clock).
+- Direct-label slices when space allows; legend if not.
+- Don't 3D pie. Ever.
+- Don't compare two pies side by side; use a stacked bar.
+
+### Bar chart rules
+
+- Bar baseline at zero. Always.
+- Vertical bars for short labels, horizontal for long.
+- Order by value (descending) unless there's a natural order (months, ranks).
+- Spacing between bars: about 30-40% of bar width.
+- Categorical x-axis on horizontal; numerical on vertical.
+
+### Line chart rules
+
+- Time on the x-axis.
+- Multiple lines: maximum 5 before they tangle.
+- Distinct color or dash pattern per line.
+- Direct-label lines at the right end where space allows.
+- Connect data points; don't put markers on every point unless you want emphasis.
+
+## Axes
+
+### Labels
+
+- Always label both axes.
+- Include units in the axis label or as a suffix on tick labels ("$", "%", "ms").
+- Don't rotate labels 90 degrees on horizontal bars; just go horizontal-bar layout.
+- Auto-skip labels when they overlap (every other, or larger interval).
+
+### Ticks
+
+- Use round numbers (10, 20, 50, 100), not 7, 23, 47.
+- 4-7 ticks per axis is usually right.
+- Y-axis baseline at zero for bar charts. Truncating the y-axis exaggerates differences.
+- For dramatic small variations, add a "broken axis" indicator (zigzag) to be honest about it.
+
+### Time axis
+
+- Match granularity to the time range:
+  - < 1 day: hours
+  - 1-30 days: days
+  - 1-12 months: weeks or months
+  - 1-5 years: months or quarters
+  - > 5 years: years
+- Allow user to change granularity (day/week/month).
+- Show the date format consistent with the user's locale.
+
+### Number formatting
+
+- Locale-aware via `Intl.NumberFormat`.
+- Compact notation for large numbers: `1.2M`, `4.7K`.
+- Currency: respect locale and currency code.
+- Percentages: 1 decimal (`23.4%`) for finance, no decimals (`23%`) for categorical.
+
+## Color in Charts
+
+### Single series
+
+- Use the brand primary or a single neutral.
+- Add a slight gradient (top to bottom) only on filled area charts; never on bar charts (looks gimmicky).
+
+### Multiple series
+
+- Sequential (ordered, e.g., low to high values): single hue, light to dark. Use a perceptually uniform scale (viridis, magma).
+- Diverging (centered, e.g., positive vs negative): two-hue diverging palette (blue-white-red).
+- Categorical (no order, e.g., Series A vs Series B vs Series C): qualitative palette, distinct hues. Use a colorblind-safe palette.
+
+### Colorblind-safe palettes
+
+Avoid red/green pairs alone. Use:
+
+- Tol's "bright" palette: blue, red, green, yellow, cyan, purple, gray (distinguishable in most colorblind types).
+- ColorBrewer's "Set2" or "Dark2".
+- Always supplement color with shape/pattern/label so meaning isn't lost.
+
+### Pattern alongside color
+
+For stacked bars or pies, use a subtle hatching/dot pattern in addition to color. Color carries the primary signal, pattern carries redundancy:
+
+```css
+.series-a { fill: var(--color-1); }
+.series-b { fill: var(--color-2); background-image: repeating-linear-gradient(45deg, transparent, transparent 4px, rgba(0,0,0,0.1) 4px, rgba(0,0,0,0.1) 8px); }
+```
+
+### Contrast against background
+
+Data marks (bars, lines) need at least 3:1 contrast against the chart background. Text labels need 4.5:1.
+
+In dark mode, lighten the data marks. Don't just keep light-mode colors.
+
+## Legends
+
+- Always show a legend for multi-series charts.
+- Place near the chart, not detached below a scroll fold.
+- Order matches data (largest to smallest, or alphabetical).
+- For interactive charts, legends are clickable to toggle series visibility.
+- Direct labeling (label at the line/bar) often beats a separate legend.
+
+## Tooltips
+
+- Show on hover (desktop) or tap (mobile).
+- Show the exact value (numeric labels are too small for crowded charts; tooltips fill in).
+- Label which series, the x value, and the y value.
+- Anchor near the cursor; don't make the user scan.
+- Persist long enough to read (don't dismiss on tiny mouse movement).
+
+```
+[X-axis label, e.g., March 12]
+Series A: 12,400 (+18%)
+Series B:  8,200 (-3%)
+```
+
+For accessibility, tooltip content must be reachable via keyboard (focus on data point reveals tooltip).
+
+## Direct Labeling
+
+For small datasets, label values directly on the chart instead of forcing the eye to travel to an axis:
+
+- Bar chart with 3-5 bars: put the value on or above each bar.
+- Line chart: put the value at the rightmost point of each line.
+- Pie chart: put values inside slices (or outside with a leader line if too small).
+
+## Animation
+
+### Entrance animation
+
+- Bars rise from the baseline, 400-600ms staggered by 30-50ms per bar.
+- Lines draw from left to right, 600-800ms total.
+- Pies sweep from 12 o'clock clockwise, 800-1000ms.
+
+### Update animation
+
+When data changes:
+
+- Animate from old to new values, 300-500ms.
+- Use ease-out.
+- Animate the path's `d` attribute or use a library helper for smooth transitions.
+
+### When to disable
+
+- `prefers-reduced-motion: reduce`: skip entrance animation; show data immediately.
+- Live-updating data views: no animation on every refresh; just update.
+- Print: no animation.
+
+```js
+const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+chart.options.animation = reduced ? false : { duration: 600, easing: 'easeOutQuart' };
+```
+
+## Accessibility
+
+### Screen readers
+
+Charts are inherently visual. Provide a text alternative:
+
+- Concise summary near the chart describing the key insight (one sentence stating the trend or comparison the chart shows).
+- A data table either inline or in a `<details>` toggle, with the same data the chart shows.
+- For complex charts, use `aria-describedby` to link the chart to a longer description.
+
+```html
+<figure>
+  <figcaption>Chart caption describing what is plotted</figcaption>
+  <div class="chart" role="img" aria-labelledby="chart-summary">
+    <svg>...</svg>
+  </div>
+  <p id="chart-summary">
+    One sentence stating the key insight the chart conveys, in plain language, with the headline numbers.
+  </p>
+  <details>
+    <summary>View data table</summary>
+    <table>
+      ...
+    </table>
+  </details>
+</figure>
+```
+
+### Keyboard
+
+- Interactive elements (data points, legend items) must be focusable.
+- Arrow keys navigate between data points (left/right for adjacent, up/down for series).
+- Enter/Space activates (toggles legend, drills down).
+- Esc closes any popover or expanded view.
+
+### Touch targets
+
+Interactive chart elements (data points, legend toggles) need at least 44x44 touch area. For dense charts, expand the hit area beyond the visual element:
+
+```html
+<circle cx="100" cy="50" r="4" />
+<circle cx="100" cy="50" r="22" fill="transparent" pointer-events="all" />
+```
+
+The visible dot is 4px; the touch target is 22px (44px diameter).
+
+## Responsive Charts
+
+### Reflow at small widths
+
+Charts must adapt or simplify on small screens:
+
+- Vertical bars become horizontal bars (long labels easier).
+- Multi-line charts collapse to top-N or to small multiples.
+- Pie charts stack labels below.
+- Axis ticks reduce to 3-5 from 7-10.
+
+### Container query
+
+Charts that appear in different layout slots benefit from container queries:
+
+```css
+.chart-container { container-type: inline-size; }
+
+@container (max-width: 480px) {
+  .chart .legend { display: none; }
+  .chart .axis-label { font-size: 0.75rem; }
+}
+```
+
+### Re-render on resize
+
+For SVG-based charts, listen to resize and re-render with new dimensions. Throttle to 100-200ms.
+
+## Loading and Error States
+
+### Loading
+
+- Show a skeleton or shimmer matching the chart's eventual shape.
+- Don't show a blank axis frame; that looks broken.
+
+### Empty data
+
+- Show a message: "No data for this period yet."
+- Optionally a placeholder chart (greyed out) with the message overlaid.
+- Action: "Try a different range" or "Connect data source".
+
+### Error
+
+- Show an error message with retry: "Couldn't load chart. Retry?"
+- Don't show a broken/clipped chart.
+
+## Large Datasets
+
+For 1000+ data points:
+
+- **Aggregate.** Group by hour/day/week to reduce point count.
+- **Sample.** Show every Nth point.
+- **Summarize.** Show the trend; provide drill-down for detail.
+- **Virtualize.** For long tables, only render visible rows.
+- **Server-side processing.** Aggregate on the server; ship summarized data.
+- **Web Workers.** For client-side heavy aggregation, move work off the main thread.
+
+Anti-pattern: shipping 50,000 points to a `<canvas>` chart and expecting smooth interaction.
+
+## Tables
+
+### Anatomy
+
+```html
+<table>
+  <caption>Table caption describing the data</caption>
+  <thead>
+    <tr>
+      <th scope="col">Row category</th>
+      <th scope="col">Metric A</th>
+      <th scope="col">Metric B</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th scope="row">Row label</th>
+      <td>4,200,000</td>
+      <td>+12%</td>
+    </tr>
+    ...
+  </tbody>
+</table>
+```
+
+- `<caption>` describes the table.
+- `<th scope="col">` for column headers, `<th scope="row">` for row headers.
+- For complex tables (multi-level headers), use `headers="..."` to associate cells with their headers.
+
+### Visual rules
+
+- Tabular figures (`font-variant-numeric: tabular-nums`) for numeric columns.
+- Right-align numbers, left-align text, center-align symbols/icons.
+- Subtle row dividers (low-contrast borders) rather than alternating row colors. Alternating colors look dated and reduce readability.
+- Sticky header for long tables (`position: sticky` on `<thead>`).
+- Hover state on rows for navigability.
+
+### Sorting
+
+- Click column header to sort ascending; click again for descending.
+- Show current sort direction with an arrow icon.
+- Use `aria-sort="ascending|descending|none"` on the column header.
+- Multi-column sort: hold Shift to add additional sorts.
+
+### Filtering
+
+- Per-column filters: dropdown, search, range slider depending on data type.
+- Active filters visible as chips above the table.
+- "Clear all" link.
+
+### Selection
+
+- Checkbox per row.
+- Select-all checkbox in the header (with indeterminate state for partial selection).
+- Show count of selected rows.
+- Bulk actions appear when rows selected.
+
+### Pagination vs infinite scroll
+
+- **Pagination** for tables: predictable, accessible, supports deep linking.
+- **Infinite scroll** for activity feeds: low-stakes, sequential reading.
+- Don't mix.
+
+### Mobile tables
+
+For wide tables on small screens:
+
+- **Horizontal scroll** with sticky first column (the row identifier).
+- **Card view**: each row becomes a card, fields as label/value pairs.
+- **Collapse**: show a few key columns, expand row to see all.
+
+```css
+.table-scroll {
+  overflow-x: auto;
+  scrollbar-width: thin;
+}
+
+.table-scroll table {
+  min-inline-size: 720px;
+}
+```
+
+## Stat Cards / KPI Tiles
+
+For data summaries, the most important number gets a stat card:
+
+```
+[ Stat Card ]
+[ Label: short description of the metric ]
+[ Value: the formatted number, largest type ]
+[ Change: direction icon + delta vs comparison period ]
+[ Sparkline: subtle line chart of recent history ]
+```
+
+Rules:
+
+- Label first (small, muted).
+- Value largest (display type).
+- Change indicator with direction icon and color (green up, red down). Pair with text so color isn't the only signal.
+- Optional sparkline. Subtle (single neutral color), no axis.
+- Optional click affordance to drill down.
+
+## Real-Time Updates
+
+For live-updating data:
+
+- Update without animation (or very subtle pulse on changed values).
+- Don't shift other content. New rows arrive at the top with a brief highlight.
+- Allow pause/resume so users can read without flicker.
+- Show last-updated timestamp.
+
+## Common Data Viz Mistakes
+
+- Pie chart with > 5 categories.
+- Bar chart with truncated y-axis (exaggerates differences).
+- Line chart with too many series tangling.
+- 3D charts.
+- Tooltip showing only a value with no series/x-axis context.
+- Color-only encoding (red good / red bad without text or icon).
+- Chart that's a bar chart on desktop and a different chart entirely on mobile (jarring).
+- Chart with no axis labels.
+- Chart with no units.
+- Chart that loads with a flicker (no skeleton, then sudden content).
+- Animation that runs on every data refresh (every 5s in a live data view).
+- Chart in dark mode with light-mode colors.
+- Inaccessible chart with no text alternative.
+- Tables without sorting or filtering on data-heavy views.
+- Tables with row colors so loud they distract from data.
+- Numbers without locale formatting (US format in a German UI).
+- Tooltip that doesn't work on touch.
+
+## Self-Healing for Data Viz
+
+Before declaring work complete:
+
+- [ ] Right chart for the data
+- [ ] Bar charts have zero baseline
+- [ ] Pies have <= 5 categories
+- [ ] Axes labeled with units
+- [ ] Colorblind-safe palette
+- [ ] Color is never the only signal (paired with shape/pattern/label)
+- [ ] Legend shown and accessible
+- [ ] Tooltip works on hover AND tap
+- [ ] Chart has text alternative (summary or table)
+- [ ] Interactive elements keyboard-accessible
+- [ ] Touch targets >= 44x44
+- [ ] Responsive: simplifies/reflows on small screens
+- [ ] Loading skeleton matches eventual layout
+- [ ] Empty state has a message and action
+- [ ] Error state has retry
+- [ ] Numbers locale-formatted
+- [ ] Animation respects `prefers-reduced-motion`
+- [ ] Tested in light AND dark mode
+- [ ] Tables: sorting, sticky header, mobile-adaptive
+
+## See Also
+
+- [accessibility.md](accessibility.md) for chart and table accessibility
+- [responsive.md](responsive.md) for chart reflow patterns
+- [motion.md](motion.md) for chart animation

package/references/defects.md

@@ -0,0 +1,152 @@
+# Common Visual Defects and Geometry Checks
+
+A symptom-to-fix lookup for visible defects, plus a canonical programmatic geometry sweep that runs against every audited route at both capture viewports. Use this file when something looks wrong and you want the standard fix, or when you want a deterministic check that catches issues screenshots can miss.
+
+## How to Use
+
+1. Identify the symptom on the rendered page or in a screenshot.
+2. Look it up in the defect table below.
+3. Apply the standard fix at the right layer (component, page, or design token).
+4. Re-run the geometry sweep on the affected route at both audit viewports.
+5. Re-capture before-and-after screenshots and confirm the fix did not regress neighbors.
+
+The defect table is one big table by design: one search lands you on the symptom regardless of which topic it might also live under. Topical references point readers here rather than restating the table.
+
+## Defect Lookup Table
+
+| Defect | Likely cause | Fix |
+|--------|--------------|-----|
+| Button shifts oddly on hover | Parent and child both transform | Disable child transform inside the animated card or move the transform to one layer |
+| Dark line after sticky header | Border/shadow/background mismatch between header and section top | Normalize header border, shadow, and section top background so the seam is invisible |
+| Dropdown not centered | Absolute position tied to item edge | Use `left: 50%`, `transform: translateX(-50%)`, clamp width on small screens |
+| Mobile dropdown off-canvas | Desktop hover rule overrides mobile rule | Add a media-specific override and constrain the dropdown to the viewport |
+| Card row uneven heights | Content-dependent heights with no stretch | Use grid stretch, flex column, `height: 100%`, and stable `min-height` |
+| Only nested CTA clickable | Card visually behaves as a link but the anchor wraps only the CTA | Make the full card an anchor, or use a button-card pattern with a stretched pseudo-element on the title link; never nest anchors, which is invalid HTML per the `<a>` content model |
+| Duplicate arrows | CSS pseudo-element arrow plus a text or icon arrow | Choose one arrow source and suppress the other by component class |
+| Pricing implies wrong plan | Ambiguous trial or setup wording on shared cards | State paid plan terms and fees plainly; remove repeated misleading phrases |
+| Social icons too far apart or too small | Independent margins and small hit boxes | Use fixed 44px boxes and `gap` |
+| Cross or check icon off-center | Pseudo-element dimensions mismatch the icon box | Use a square icon box with absolutely centered pseudo-elements, or inline SVG |
+| Mobile horizontal scroll | Hidden off-canvas element, wide image, long unbreakable word, or `100vw` misuse | Inspect `scrollWidth`; constrain media; use `min-width: 0` on grid children; avoid `width: 100vw` inside padded containers |
+| Low-quality page versus reference | Thin sections, repeated template copy, generic stock images | Add useful sections, vary copy, use relevant images, tighten hierarchy |
+| Same widget looks different across pages | Duplicated markup, page-local CSS, no component contract | Extract a shared component or normalize markup and classes to one contract; see [components.md](components.md) |
+| Many card variants without purpose | Ad hoc class combinations applied page by page | Define named variants in the component and map old usages into them |
+| Integration or logo tiles inconsistent in size | Each page hand-codes image and card rules | Create one logo tile component with a fixed image box, label treatment, and grid behavior |
+| CTA bands vary randomly | Page-specific final sections | Create one final-CTA component with explicit variants for centered, split, compact, or gradient |
+| Focus ring clipped | Parent uses `overflow: hidden` with insufficient padding | Move the ring to an `outline` (which paints outside the box) or add internal padding so the ring fits |
+| Focus ring invisible on dark surfaces | Single-color ring chosen for light mode only | Use a ring color with 3:1 contrast against both surface and resting element state, in both light and dark mode |
+| Hero image causes CLS | Missing intrinsic `width` and `height` | Declare width and height as attributes; reserve space with `aspect-ratio` |
+| Late-loading hero image hurts LCP | Hero image is `loading="lazy"` or behind hydration | Use `loading="eager"` and `fetchpriority="high"` on the hero LCP image only |
+| Webfont flash on first paint | `font-display: block` or no `font-display` set | Use `font-display: swap` for body and `optional` for display; preload at most one critical weight |
+| Unstyled flash on hydration | Critical CSS not inlined | Inline above-the-fold CSS under 14 KB so it fits in the first round trip |
+| Button label truncates on mobile | Fixed width or `white-space: nowrap` with insufficient room | Constrain by `max-width`, allow wrap, or shorten the label |
+| Form validation appears late | Validation runs on every keystroke, then debounces | Validate on blur for new errors; clear errors live as the user types |
+| Modal scrolls with the page | Body scroll not locked when modal is open | Lock body scroll on open, restore on close; restore the scroll position |
+| Modal traps keyboard but not screen reader | Background is interactive in the accessibility tree | Mark background `inert` (or `aria-hidden="true"` plus `pointer-events: none`) while modal is open |
+| Skip link overflows the viewport while hidden | `position: absolute; left: -9999px` can still extend the document layout box, or the focus state inherits the off-screen position | Use the modern `clip-path: inset(100%)` plus `position: absolute; width: 1px; height: 1px; overflow: hidden` pattern when hidden; switch to `clip-path: inset(0); position: fixed; top: 1rem; left: 1rem` on `:focus` |
+| Tables overflow on mobile | Fixed-width table without scroll wrapper | Wrap in a scroll container with `overflow-x: auto`, or transform to cards below the breakpoint |
+| Empty state is blank | No specific message and no primary action | Add a specific message, the condition that fills it, and a primary action that resolves it |
+
+## Programmatic Geometry Sweep
+
+The geometry sweep catches defects that are easy to miss in a screenshot pass: sub-44 hit targets buried in long pages, hidden text overflow on edge cases, viewport bleed from a single rogue element, duplicate arrows that read fine in isolation but stack across siblings.
+
+Run from a headless browser of your choice (Puppeteer, Playwright, or equivalent). The snippet below uses only standard DOM and CSSOM APIs:
+
+```js
+const issues = await page.evaluate(() => {
+  const out = [];
+  const visible = (el) => {
+    const r = el.getBoundingClientRect();
+    const cs = getComputedStyle(el);
+    return r.width > 0 && r.height > 0 && cs.display !== "none"
+      && cs.visibility !== "hidden" && parseFloat(cs.opacity) > 0;
+  };
+  const nameFor = (el) =>
+    el.tagName.toLowerCase()
+    + (el.className
+        ? "." + String(el.className).trim().split(/\s+/).slice(0, 3).join(".")
+        : "");
+
+  if (document.scrollingElement.scrollWidth > window.innerWidth + 1) {
+    out.push({ type: "viewport-bleed", value: document.scrollingElement.scrollWidth, viewport: window.innerWidth });
+  }
+
+  for (const el of document.querySelectorAll("body *")) {
+    if (!visible(el)) continue;
+    const cs = getComputedStyle(el);
+    if (el.clientWidth > 0 && el.scrollWidth > el.clientWidth + 2 && cs.overflowX === "visible") {
+      const text = (el.textContent || "").trim().replace(/\s+/g, " ").slice(0, 80);
+      if (text && !["HTML", "BODY", "MAIN", "SECTION"].includes(el.tagName)) {
+        out.push({ type: "text-overflow", selector: nameFor(el), text });
+      }
+    }
+  }
+
+  for (const el of document.querySelectorAll("a, button, input, select, textarea, [role='button'], .btn")) {
+    if (!visible(el)) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width < 44 || r.height < 44) {
+      out.push({ type: "small-target", selector: nameFor(el), width: Math.round(r.width), height: Math.round(r.height) });
+    }
+  }
+
+  for (const el of document.querySelectorAll("a, .btn-text")) {
+    const text = (el.textContent || "").replace(/\s+/g, " ").trim();
+    if (/→\s*→|›\s*›|»\s*»/.test(text)) out.push({ type: "duplicate-arrow", text });
+  }
+
+  return out;
+});
+```
+
+The sweep returns nine check categories. Run it on every audited route at both capture viewports.
+
+| # | Check | Triggers when |
+|---|-------|---------------|
+| 1 | Viewport bleed | `document.scrollingElement.scrollWidth` exceeds `window.innerWidth` by more than 1 px |
+| 2 | Visible text overflow | An element's `scrollWidth` exceeds its `clientWidth` by more than 2 px while `overflow-x` is `visible` |
+| 3 | Small interactive target | A visible interactive element measures less than 44 by 44 CSS pixels |
+| 4 | Duplicate arrow | A link or text-button label contains stacked arrow glyphs (`→ →`, `› ›`, `» »`) |
+| 5 | Pricing or card clickable mismatch | A card visually behaves as a link but only an inner CTA is the anchor (extend the sweep with a per-project selector list) |
+| 6 | Header or dropdown centering | The dropdown's horizontal center is more than 4 px from its trigger center (extend with the per-project selector) |
+| 7 | Mobile drawer scroll lock | Body scroll is not locked while the drawer is open (extend with a per-project trigger sequence) |
+| 8 | Focus state presence | A keyboard-focusable element produces no visible outline change on focus (extend with a per-project focus drive) |
+| 9 | Project-specific extension | Open slot for negative letter-spacing, banned colors, or any rule the project standardizes on |
+
+The base snippet covers checks 1 through 4 directly. Checks 5 through 8 require selectors and triggers specific to the project under audit; add them to the same `evaluate` call. Check 9 is the slot for any rule the project enforces on top of the standard nine.
+
+Filter false positives only when you can explain them: hidden off-canvas content, intentionally overflowing dropdown internals that do not affect the page viewport, or a tap target that is intentionally part of a larger ancestor hit area. Document the filter so the next run does not re-discover it.
+
+## Per-Check Thresholds
+
+The thresholds below align with the North Star Targets in the entry SKILL.md and the touch-target rule in [ui-ux.md](ui-ux.md). They do not introduce new bars; they make the bars measurable.
+
+| Check | Threshold | Source |
+|-------|-----------|--------|
+| Capture viewports | `1440x900` desktop, `375x812` mobile | [responsive.md](responsive.md) breakpoints table |
+| Touch target minimum | 44 by 44 CSS pixels | Rule 25 in SKILL.md, [ui-ux.md](ui-ux.md) hit targets table |
+| Horizontal overflow tolerance | 0 px on mobile, 0 px on desktop | [responsive.md](responsive.md) |
+| Duplicate arrow count | 0 across all visible labels | This file, defect table |
+| Dropdown centering tolerance | 4 px from trigger center | This file, geometry sweep |
+| Focus ring contrast | 3:1 against surface and resting state | [accessibility.md](accessibility.md) contrast targets |
+| LCP image declared dimensions | Both `width` and `height` present | Rule 1 in SKILL.md, [performance.md](performance.md) |
+
+A run is "clean" when every check returns zero issues at both capture viewports.
+
+## Acceptance
+
+A polish pass is not complete until:
+
+- The geometry sweep returns zero issues on every audited route at `1440x900` and `375x812`.
+- Every defect found in the lookup table has been fixed at the right layer (component, page, or design token).
+- Re-captured screenshots show the fix and no regression on neighbors.
+
+Until then, the work is not done. Do not present an incomplete visual pass as complete.
+
+## See Also
+
+- [audit-workflow.md](audit-workflow.md) for the full multi-page audit procedure
+- [components.md](components.md) for component contracts and drift detection
+- [accessibility.md](accessibility.md) for focus, contrast, and skip-link patterns
+- [responsive.md](responsive.md) for capture viewports and breakpoints
+- [performance.md](performance.md) for LCP, font, and image strategy