@ctxr/skill-frontend-excellence 0.1.1

package/references/audit-workflow.md

@@ -0,0 +1,390 @@
+# Multi-Page Audit and Polish Workflow
+
+The procedural playbook for auditing an existing multi-page site against a reference and polishing it to that level of discipline. Use this when the work is not building a new page from scratch but bringing an existing surface to a consistent visual bar across every route.
+
+The strategic four-phase workflow in the entry SKILL.md (Frame, Plan, Build, Verify) is the right frame for greenfield work. The 19 phases below are the right frame for audit and polish work. Run them in order; each phase has a clear input and a clear output.
+
+## Core Principle
+
+Treat the rendered browser as the source of truth. Do not judge visual quality from code alone. Capture screenshots, inspect them, compare against the reference, patch the smallest set of templates, styles, or assets needed, and re-capture until the visible result is clean at every requested viewport.
+
+The goal is not to copy another brand pixel-for-pixel unless explicitly requested. The goal is to match the reference site's level of discipline: proportion, density, hierarchy, alignment, typography, spacing, interaction behavior, responsive refinement, and absence of visual defects.
+
+Equally important: repeated widgets must be standardized. If the same kind of thing appears on multiple pages, such as a hero, feature card, pricing card, integration tile, CTA band, testimonial, FAQ, footer column, media row, badge, form, or navigation dropdown, it should follow one canonical visual and content contract unless there is a deliberate, documented variant. Polishing each instance separately is not enough.
+
+## Operating Rules
+
+These rules apply to every phase below. Treat any violation as a defect.
+
+1. Identify the target URL, project root, build system, source directories, and reference URL or screenshots before making changes.
+2. Capture a baseline before editing when visual polish is the task.
+3. Capture at least one desktop viewport and one mobile viewport. Use `1440x900` and `375x812` unless the user specifies otherwise. See [responsive.md](responsive.md) for the canonical breakpoints table.
+4. Audit route-by-route. Include generated pages, legal pages, pricing pages, integration pages, 404 pages, and programmatic content routes if they are linked or published.
+5. Audit component-by-component across routes. Build a widget inventory and compare every repeated widget type across pages before finalizing. See [components.md](components.md).
+6. Extract repeated markup into reusable components, partials, includes, or framework-native primitives when the local stack supports it. If extraction is not feasible, normalize the markup and document why duplication remains.
+7. Compare real screenshots against the reference. Vague statements such as "looks better" are not evidence.
+8. Fix root component causes when the same issue appears across pages: navigation, footer, cards, buttons, typography, spacing tokens, image rules, or grid primitives.
+9. Re-render and re-screenshot after each meaningful group of fixes.
+10. Preserve the site's content, brand intent, and information architecture unless the user asks for copy or structure changes.
+11. Keep changes scoped. Do not rewrite the entire design system when a token, component, template, or layout rule fixes the defect.
+12. Run available validation commands before final delivery: build, lint, stylelint, tests, visual capture, accessibility checks, Lighthouse, and the geometry sweep in [defects.md](defects.md).
+13. Never declare the pass complete while known visible issues remain.
+
+## Phase 1: Discover Context
+
+Before capturing or editing, determine:
+
+- Project root and package manager.
+- Build system and templating mechanism (whatever the project uses; the workflow does not depend on a specific framework).
+- Source locations for templates, components, global CSS, component CSS, JavaScript, image assets, fonts, config, and generated output.
+- Local dev URL and whether a server is already running.
+- Reference source: live URL, screenshot folder, design export, previous production site, or written design standard.
+- Route scope: entire site, root only, a section, or a list of specific routes.
+
+Read the project's existing scripts before inventing commands. If a dev server is needed and none is running, start it. If the standard port is occupied, use the existing server when it matches the project; otherwise pick another port.
+
+## Phase 2: Inventory Routes
+
+Build a route list from multiple sources:
+
+- Linked anchors on the homepage and primary navigation.
+- Static-build output directories for routes the user can land on.
+- Sitemap files.
+- Route manifests, content data files, collection templates, or programmatic page data.
+- Known required pages from the user.
+
+Exclude only routes that are intentionally external, authenticated admin flows, logout or delete actions, file or mail or tel links, or fragments of pages already covered.
+
+If route generation is broken, fix missing published pages before polishing the rest of the site. A polished 404 for a page that should exist is still a failure.
+
+## Phase 3: Inventory Repeated Widgets
+
+Before editing styles, build a cross-page widget inventory. The inventory is mandatory for any multi-page polish.
+
+The 11 widget families and the inventory record format live in [components.md](components.md). For each family, record routes where it appears, the source that renders it, required and optional content fields, allowed variants, the canonical visual contract, and which deviations are intentional versus accidental.
+
+Use this inventory to decide whether to extract, extend, or normalize. The extraction rule (extract at three or more duplicates, or at two with clear future reuse, or any visible drift) is the same one in [components.md](components.md). Do not keep two visually different implementations of the same widget type unless they have distinct semantic purposes and named variants.
+
+## Phase 4: Capture Baseline
+
+Capture every route in scope at both audit viewports before editing. Store screenshots in a timestamped audit directory. Capture both viewport screenshots and full-page screenshots when useful.
+
+Use consistent file names so before-and-after comparison is mechanical:
+
+- `<route>_desktop.png`
+- `<route>_desktop_full.png`
+- `<route>_mobile.png`
+- `<route>_mobile_full.png`
+- `reference_desktop.png`
+- `reference_mobile.png`
+- `report.json`
+
+Run from a headless browser of your choice (Puppeteer, Playwright, or equivalent). The script below uses only standard browser APIs and standard Node modules; adapt the route list and the output directory for the project under audit.
+
+Before running it, install the browser-automation library the script imports (for the example below: `npm install --save-dev puppeteer`). Save the script as `capture.cjs` and invoke it with `node capture.cjs <output-dir>` (the output directory defaults to `visual-audit/`). If the project already uses Playwright or another driver, port the loop body; the screenshot file naming convention is the load-bearing part, not the driver.
+
+```js
+const fs = require("fs");
+const path = require("path");
+const puppeteer = require("puppeteer");
+
+const baseUrl = process.env.TARGET_URL || "http://localhost:3000";
+const outDir = process.argv[2] || "visual-audit";
+const routes = ["/"];
+const viewports = [
+  { name: "desktop", width: 1440, height: 900 },
+  { name: "mobile", width: 375, height: 812 },
+];
+
+const safeName = (route) =>
+  (route === "/"
+    ? "home"
+    : route.replace(/^\/|\/$/g, "").replace(/[^a-z0-9]+/gi, "_").toLowerCase()
+  ) || "home";
+
+(async () => {
+  fs.mkdirSync(outDir, { recursive: true });
+  const browser = await puppeteer.launch({ headless: "new" });
+  const failures = [];
+  for (const route of routes) {
+    for (const vp of viewports) {
+      const page = await browser.newPage();
+      await page.setViewport({ width: vp.width, height: vp.height, deviceScaleFactor: 1 });
+      try {
+        const response = await page.goto(`${baseUrl}${route}?qa=${Date.now()}`, {
+          waitUntil: "networkidle0", timeout: 30000,
+        });
+        if (response && response.status() >= 400) {
+          failures.push({ route, viewport: vp.name, status: response.status() });
+        }
+        const file = path.join(outDir, `${safeName(route)}_${vp.name}.png`);
+        await page.screenshot({ path: file });
+        await page.screenshot({ path: file.replace(".png", "_full.png"), fullPage: true });
+      } catch (error) {
+        failures.push({ route, viewport: vp.name, error: String(error.message || error) });
+      } finally {
+        await page.close();
+      }
+    }
+  }
+  await browser.close();
+  fs.writeFileSync(path.join(outDir, "report.json"), JSON.stringify({ baseUrl, routes, failures }, null, 2));
+})();
+```
+
+Adapt the script rather than rewriting it. Add route discovery, contact sheets, interactive captures, and the geometry sweep from [defects.md](defects.md) as the task requires.
+
+## Phase 5: Capture Reference
+
+Capture the reference target at the same viewport sizes used in Phase 4. If the reference is a live site, use cache-busted URLs and the same browser engine as the baseline. If the reference is a screenshot or design export, place the assets next to the local screenshots so side-by-side comparison is one open command away.
+
+When comparing to a reference:
+
+- Match polish level, not necessarily exact color or content.
+- Compare the first viewport first: navigation, hero, primary CTA, image treatment, first hint of next section.
+- Then compare section rhythm: density, vertical spacing, card grids, media-to-copy balance, and CTA placement.
+- Finally compare details: shadows, borders, radii, icon alignment, label treatment, focus states, hover states, mobile drawer behavior, footer density.
+
+## Phase 6: Audit Each Route
+
+For every route and viewport, inspect every category below. Record findings as route plus viewport plus component plus what is wrong plus why it matters plus likely source plus screenshot plus fix status.
+
+| Category | What to inspect |
+|----------|-----------------|
+| Header and navigation | Logo alignment, nav item spacing, dropdown centering, active state, hover/focus/pressed, sticky behavior, z-index, seam lines, mobile drawer, scroll lock |
+| Hero | First-viewport composition, heading scale, line length, CTA alignment, media size, image sharpness, next-section reveal, mobile fold |
+| Sections | Vertical rhythm, background bands, max-widths, gutters, content density, section transitions |
+| Cards and tiles | Equal heights in rows, equal widths, consistent padding, aligned baselines, clickable area, hover, focus ring, icon and image alignment, aspect ratio |
+| Buttons and links | Size, label clarity, icon centering, hover drift, duplicate arrows, disabled states, touch target, focus visibility |
+| Typography | Family, weight, scale, line-height, letter-spacing, wrapping, measure, hierarchy, alignment |
+| Color | Background, foreground, accent consistency, contrast, border, hover, active, muted text, light and dark bands |
+| Images and media | Crop, aspect ratio, resolution, `srcset`, lazy and eager loading, alt text, visual relevance, repeated or placeholder assets |
+| Forms | Labels, placeholders, validation states, focus, disabled, field heights, mobile keyboard fit |
+| Footer | Layout balance, link columns, legal row, social icon spacing, hit area, mobile stacking |
+| Responsive behavior | No horizontal scroll, no clipping, no desktop layout on mobile, no text overflow, no oversized buttons or cards, no tiny tap targets |
+
+Also compare each widget against other instances of the same family. Do same-type cards have the same padding, radius, border, hover, min-height, CTA position, and typography? Does the same CTA mean the same thing and use the same label style? Do integration and logo tiles use one image size, one logo treatment, and one fallback? Do section headers use the same eyebrow, H2, subhead, width, and gap rules? Do hero variants have named purposes and shared internals? Are component variants explicit in code, or are they accidental class combinations?
+
+## Phase 7: Prioritize Fixes
+
+Fix in this order. Higher tiers always block lower tiers.
+
+1. Broken routes, 404s, missing generated pages, hard layout failures.
+2. Global shell defects: header, navigation, footer, body overflow, typography tokens, color tokens.
+3. Cross-page widget drift: same widget type implemented differently across pages without a named variant.
+4. Cross-page component defects: cards, buttons, pricing, integration tiles, form controls, media blocks.
+5. Page-specific hierarchy and section density issues; interaction and accessibility issues; asset and performance polish; minor copy clarity where misleading product claims or repeated template text needs work.
+
+Prefer global fixes when a defect repeats. Prefer page-level fixes when the defect is truly contextual.
+
+## Phase 8: Patch With Component Discipline
+
+When repeated widgets drift, fix the component system before tuning page-specific CSS. The full extraction sequence and the component contract checklist live in [components.md](components.md). Walk that file before editing.
+
+The summary: choose a canonical contract, name the widget and variants clearly, move repeated markup into the project's component mechanism, pass content as explicit fields, make variants explicit, centralize CSS, re-render every route, and compare instances side-by-side at both viewports. Anti-patterns to avoid (copy-paste tweaking, near-duplicate components, one-off CSS for drift, overly generic components requiring per-call-site overrides) also live in [components.md](components.md).
+
+## Phase 9: Patch With Design Discipline
+
+Use existing design primitives before adding new ones. Patch CSS, templates, and components conservatively.
+
+- Normalize tokens first: spacing, color, border, radius, shadow, type scale. Token detail lives in [design.md](design.md).
+- Use stable dimensions for repeated UI: `min-height`, `aspect-ratio`, grid tracks, `align-items: stretch`, fixed icon boxes.
+- Avoid arbitrary one-off margins. Use local precedent or none.
+- Use `gap` for internal spacing instead of stacked margins where possible.
+- Use `max-width` and responsive constraints for readable line lengths. Layout primitive detail lives in [responsive.md](responsive.md).
+- Use full-card anchors when a card visually behaves as a link. Do not nest anchors.
+- Keep CTA hover transforms from stacking with card hover transforms.
+- Use `:focus-visible` rings that are clearly visible and consistent. Contrast detail lives in [accessibility.md](accessibility.md).
+- Avoid hiding visible text behind mismatched `aria-label`. Visible text is the accessible name.
+- Make hover and focus states visually related so a keyboard user gets the same clarity as a pointer user.
+- Use `srcset` and `sizes` for recurring large images.
+- Use `loading="eager"` and `fetchpriority="high"` only on the hero LCP image. Use `loading="lazy"` and `decoding="async"` for below-the-fold imagery. Image strategy detail lives in [performance.md](performance.md).
+
+## Phase 10: Verify After Every Fix Group
+
+After a meaningful fix group:
+
+1. Rebuild or let the dev server hot reload.
+2. Re-capture the affected routes at desktop and mobile.
+3. Compare before and after.
+4. Inspect at least the first viewport and the edited section.
+5. Confirm no regression on shared components.
+6. If a reusable widget changed, capture every route where the widget appears, not only the route where the defect was first noticed.
+
+Do not wait until the end to discover that a global CSS fix broke mobile.
+
+## Phase 11: Programmatic Geometry Checks
+
+Use browser automation to catch issues that screenshots miss: viewport bleed, hidden text overflow, sub-44 hit targets, duplicate arrows, dropdown miscentering, mobile drawer scroll-lock failures, focus invisibility.
+
+The canonical 9-check sweep, the JS snippet that runs it, and the per-check thresholds live in [defects.md](defects.md). Run it on every audited route at both capture viewports. A run is clean when every check returns zero issues.
+
+Filter false positives only when you can explain them, such as hidden off-canvas content or intentionally overflowing dropdown internals that do not affect the page viewport. Document the filter so the next run does not re-discover it.
+
+## Phase 12: Component Drift Checks
+
+Use browser automation to compare same-family widgets across pages. This does not replace visual judgment, but it catches drift early.
+
+The drift collector snippet and the property list (width, height, padding, radius, border, background, shadow, typography, CTA position, image metrics) live in [components.md](components.md). Run it on every route in scope. Compare the result for each family across pages.
+
+Flag any difference that is not explained by a named variant. A family is drift-free when every same-variant instance produces the same metrics within rounding tolerance.
+
+## Phase 13: Interaction QA
+
+Capture explicit interaction screenshots and verify behavior:
+
+- Desktop dropdown open.
+- Mobile menu open.
+- Hovered card or button.
+- Focus-visible state on major controls.
+- Pricing card hover or focus if cards animate.
+- Modal, drawer, accordion, tabs, carousel, or form validation states if present.
+
+Behavioral checks:
+
+- Dropdowns are centered or intentionally aligned.
+- Dropdowns stay within the viewport.
+- Esc closes popovers.
+- Outside click closes popovers.
+- Mobile drawer locks page scroll while open and restores scroll after close.
+- Buttons do not drift on hover.
+- Active and current nav states are visible.
+- Focus ring is not clipped.
+- Interactive element accessible names match visible labels.
+
+State coverage detail (empty, loading, success, error, partial, disabled, read-only, stale, offline, unauthorized, limit-reached, initial, done) lives in [ui-ux.md](ui-ux.md).
+
+## Phase 14: Accessibility Validation
+
+Use Lighthouse, axe, or equivalent when available. Treat these as baseline checks, not replacements for human visual inspection. The full WCAG 2.2 AA framework, ARIA rules, contrast targets, keyboard patterns, screen reader checks, and focus management live in [accessibility.md](accessibility.md).
+
+The minimum required basics specific to multi-page polish:
+
+- `<html lang>` exists and is valid on every route.
+- Exactly one primary `<main>` per route.
+- Logical heading order; one H1 per route; sequential H2 to H3.
+- Links and buttons have accessible names.
+- Form controls have labels.
+- Visible labels match accessible names.
+- Images have useful alt text or empty decorative alt.
+- Contrast passes for text, UI controls, and focus indicators in both light and dark mode.
+- Focus order follows visual order.
+- No keyboard traps.
+- Skip link works and does not create viewport overflow while hidden.
+
+If a visual fix creates an accessibility problem, the visual fix is incomplete.
+
+## Phase 15: Lighthouse and Performance Polish
+
+Run Lighthouse when the project has it set up or when the user asks for production polish. Fix failing assertions. Treat warnings as useful triage but do not over-optimize at the cost of design unless the user asks. Lighthouse setup, scoring weights, and audit-by-audit fixes live in [lighthouse.md](lighthouse.md). Performance mechanics and asset strategy live in [performance.md](performance.md).
+
+Common visual-performance fixes that surface in audit work:
+
+- Add responsive `srcset` variants for hero and recurring large images.
+- Use correct intrinsic `width` and `height` on every image to prevent layout shift.
+- Preload or prioritize only the actual LCP image.
+- Avoid loading offscreen imagery eagerly.
+- Remove giant decorative images that are visually indistinguishable from smaller assets.
+- Keep webfont usage intentional. Cap to two families and four weights.
+- Avoid expensive shadows and filters on large scrolling surfaces if they cause jank.
+
+## Phase 16: Reference-Level Design Heuristics
+
+Use these tests when comparing the audited site to the reference. Each test is a yes-or-no judgment supported by the captured screenshots. The same list lives in [design.md](design.md) "Reference Comparison Heuristics" for use outside this audit workflow; the two copies are intentionally identical so each file is self-contained for its reader's mode.
+
+1. First viewport has a clear hierarchy and does not feel accidental.
+2. The brand or product is visible immediately when relevant.
+3. The next section peeks intentionally rather than crowding the hero.
+4. Repeated cards in a row align on top edges, bottom edges, and CTA baselines.
+5. Text blocks have readable line lengths and consistent rhythm.
+6. Labels, eyebrows, and badges use one visual language.
+7. Buttons use one size system and one radius system.
+8. Icons sit optically centered, not just mathematically centered.
+9. Borders are subtle and consistent.
+10. Shadows support hierarchy but do not muddy the palette.
+11. Alternate background bands feel deliberate.
+12. Mobile layout feels designed, not merely stacked.
+13. Footer spacing is calmer than the body, with no stray gaps or cramped links.
+14. Empty states, legal pages, and 404 pages share the same polish as marketing pages.
+15. Same-family widgets look like members of one system across pages.
+16. Variants are recognizably intentional, not accidental drift.
+
+A site at reference level passes every test. A site at "fine" level fails three or more.
+
+## Phase 17: Common Defects and Fixes
+
+The 29-row symptom-to-fix lookup table lives in [defects.md](defects.md). Use it whenever a defect surfaces during Phase 6 or Phase 13. Apply the standard fix at the right layer (component, page, or design token), then re-run the geometry sweep on the affected route.
+
+## Phase 18: Deliverables
+
+Provide a concise final package:
+
+- Summary of main changes.
+- Per-page checklist with issues found, fixes applied, and screenshot references.
+- Before-and-after screenshot paths for desktop and mobile.
+- Reference screenshot paths.
+- Interactive screenshot paths if menus, drawers, or cards were tested.
+- Validation commands and pass-or-fail results.
+- Remaining risks only if real issues remain.
+- Widget inventory and standardization notes: which repeated widgets were found, which were extracted or normalized, and which named variants remain.
+
+Per-page checklist format:
+
+```markdown
+| Route | Issues found | Fixes applied | Before | After |
+| --- | --- | --- | --- | --- |
+| `/pricing/` | Pricing CTA drift, partial card click area | Full-card anchors, stable hover state | [D](before/pricing_desktop.png) [M](before/pricing_mobile.png) | [D](after/pricing_desktop.png) [M](after/pricing_mobile.png) |
+```
+
+Widget inventory format:
+
+```markdown
+| Widget family | Routes | Source | Standardization action | Variants |
+| --- | --- | --- | --- | --- |
+| Integration tile | `/integrations/`, `/whatsapp/`, `/for/.../` | duplicated markup plus partial | Extracted to `integration-card` | `link`, `static-logo` |
+```
+
+Validation summary format:
+
+```markdown
+- Build: passed
+- Lint: passed
+- Capture: 24 routes, `failures: []`
+- Geometry sweep: `[]` at `1440x900` and `375x812`
+- Drift collector: zero unexplained differences across families
+- Lighthouse: passed required assertions
+```
+
+## Phase 19: Final Acceptance Gate
+
+Before final delivery, confirm every item below. This is the authoritative gate for multi-page audit and polish work. The Self-Improvement section in the entry SKILL.md is the short version.
+
+- Every in-scope route was captured at desktop (`1440x900`) and mobile (`375x812`).
+- Every route returns the expected HTTP status.
+- Repeated widget families have been inventoried and compared across pages.
+- Same-purpose widgets have been extracted into reusable components or partials, or normalized to one contract where extraction is not feasible.
+- Remaining variants are named, intentional, and visually consistent within their variant.
+- Every edited shared component was re-captured on every route where it appears (not just the route where the defect was noticed) and the geometry sweep passed.
+- The latest screenshots reflect the latest code.
+- Build and lint pass, or failures are clearly unrelated and reported.
+- No horizontal scroll exists on mobile.
+- No known text overflow, clipped controls, duplicate arrows, tiny touch targets, or partial clickable-card defects remain.
+- The geometry sweep returns zero issues on every audited route at both capture viewports.
+- The drift collector returns no unexplained differences for any widget family.
+- Navigation, footer, pricing, cards, forms, and interactive states pass Phase 13 interaction QA and Phase 14 accessibility validation.
+- Accessibility basics from Phase 14 are clean on every route.
+- Reference-Level Design Heuristics from Phase 16 pass.
+- The final checklist is written and linked.
+
+If any item fails, continue fixing or clearly state the blocker. Do not present an incomplete visual pass as complete.
+
+## See Also
+
+- [components.md](components.md) for extraction discipline, contracts, and drift detection
+- [defects.md](defects.md) for the symptom-to-fix lookup table and the canonical geometry sweep
+- [accessibility.md](accessibility.md) for the WCAG framework, ARIA, contrast, focus, screen reader
+- [responsive.md](responsive.md) for capture viewports, breakpoints, and layout primitives
+- [design.md](design.md) for tokens, typography, color, and shadow language
+- [performance.md](performance.md) for image, font, and asset strategy
+- [lighthouse.md](lighthouse.md) for audit setup and score-driven fixes
+- [pre-launch.md](pre-launch.md) for the launch gate that runs alongside this workflow

package/references/components.md

@@ -0,0 +1,247 @@
+# Component Discipline
+
+Framework-agnostic guidance on standardizing repeated widgets across pages, defining component contracts, and detecting drift before it ships. Polishing each instance separately is not enough: same-purpose widgets must follow one canonical visual and content contract.
+
+## Terms
+
+The rest of this file (and [audit-workflow.md](audit-workflow.md) and [defects.md](defects.md)) uses these terms with the meanings below. Pin them down before reading further.
+
+- **Widget family**: a group of repeated UI elements that serve the same role across pages, e.g. all feature cards, all CTA bands, all hero variants. See the 11-family table below.
+- **Canonical contract**: the single, authoritative visual and content specification for a widget family. Names the required and optional content fields, the allowed variants, the CSS properties that are part of the family (padding, radius, shadow, etc.), and the states (hover, focus, active, disabled, loading). A component is not done until the contract is documented and every instance matches it.
+- **Named variant**: an intentional, documented variation of a component with a clear purpose, exposed through one prop, one class, or one data attribute (e.g., `card--feature`, `card--integration`, `card--pricing`). Variants are part of the contract; ad hoc class combinations are not variants, they are drift.
+- **Drift**: a repeated widget that looks or behaves differently across pages without a named variant. Drift indicates a missing component abstraction or an incomplete variant set. Detected by visual comparison and by the drift collector (below).
+- **Drift collector**: a browser-automation script that reads computed styles and bounding boxes for every member of a family across every audited route, then flags any difference not explained by a named variant.
+
+## When to Extract
+
+Extraction turns repeated markup into a single source of truth. Extract when any of these hold:
+
+- The same structure appears three or more times across routes.
+- The same structure appears twice with clear future reuse.
+- Duplicated markup is causing visible drift (different padding, radius, typography, or hover behavior on instances that should look identical).
+
+Do not extract when:
+
+- The local stack has no include or component mechanism and adding one would add build complexity out of proportion to the benefit. Normalize markup and class names instead.
+- The two instances look similar but serve genuinely different semantic purposes. Build them as named variants rather than forcing one component to flex.
+
+The principle expressed as a check: a repeated widget either has one source of truth or has a documented, named variant. There is no third option.
+
+## The 11 Widget Families
+
+Every multi-page polish pass starts by inventorying these families. For each family the inventory must record: routes where it appears, source (template or component or duplicated markup), required and optional content fields, allowed variants, and the canonical visual contract (spacing, typography, border, radius, shadow, color, icon placement, image ratio, CTA behavior, focus ring, hover behavior, responsive behavior).
+
+| Family | Members | Standardization criteria |
+|--------|---------|--------------------------|
+| Global shell | Header, primary nav, dropdowns, mobile drawer, footer, legal/social row | One header, one footer, one drawer; consistent across every route |
+| Hero systems | Centered, asymmetric, product, landing, legal/simple | Each hero variant is a named component; no ad-hoc combinations |
+| Section headers | Eyebrow/label, heading, subheading | One spacing rule, one max-width rule, one alignment rule per variant |
+| CTA systems | Primary button, secondary button, text link, final CTA band, pricing CTA, card CTA | One size scale, one radius scale, one focus ring, one hover transform |
+| Card systems | Feature, benefit, outcome, pain, directory, integration, pricing, FAQ, legal-content | Equal heights in rows, consistent padding, consistent CTA placement |
+| Media systems | Image rows, logo tiles, screenshots, illustrations, icon boxes, avatars | Fixed image box dimensions per family, one alt-text policy, one loading strategy |
+| Data/list systems | Pricing tables, comparison tables, FAQ lists, pain lists, checklists, icon lists | Tabular figures for numbers, one bullet/icon style per list type |
+| Interactive systems | Accordions, tabs, menus, dropdowns, drawers, modals, hover cards, forms | One open/close behavior, one focus management policy, one Esc/outside-click rule |
+| Empty states | Empty list, empty search, zero data | Same polish as marketing surfaces; specific message and primary action |
+| Legal pages | Terms, privacy, acceptable use, security | Shared layout shell; consistent typography and spacing |
+| 404 / error pages | 404, 5xx, offline | Branded, useful (search box, home link), not just an apology |
+
+The inventory is mandatory for any multi-page polish. Without it, drift is invisible and standardization is guesswork. See [audit-workflow.md](audit-workflow.md) Phase 3 for the procedure.
+
+## Component Contract Checklist
+
+A widget is ready for extraction when every item below is true. Before declaring a component done, walk this list.
+
+- [ ] Required content fields are documented by usage: title, body, eyebrow, image, CTA, secondary CTA, metadata, icon, badge.
+- [ ] Optional fields have graceful empty states and do not leave blank gaps.
+- [ ] Markup is semantic and stable. Headings use the right level; landmarks are correct; lists are real lists.
+- [ ] Layout is resilient to long text, very short text, and missing optional fields. Test the longest realistic title and the shortest.
+- [ ] Desktop and mobile behavior is defined explicitly, not by accident.
+- [ ] Hover, focus, active, disabled, and loading states are defined when relevant.
+- [ ] Accessible names come from visible content unless a different name is necessary; visible text and `aria-label` agree.
+- [ ] Images have consistent intrinsic dimensions, aspect ratio, loading strategy, and alt behavior.
+- [ ] No page-specific magic numbers exist inside the component unless exposed as a named variant.
+- [ ] The component owns its CSS. Page-local overrides on shared widgets are forbidden.
+- [ ] Variants are explicit (one prop, one class, one data attribute), not arbitrary class combinations.
+
+A component shipped without these answers is half-built and will drift on the next page.
+
+## Extraction Sequence
+
+Follow this sequence. Skipping a step turns extraction into yet another duplicated markup variant.
+
+1. Choose the canonical contract. Pick the best existing implementation, the reference target, and the product needs as inputs. The contract is one design, not a union of all current usages.
+2. Name the widget and its variants clearly. Names like `hero-asymmetric`, `section-heading`, `feature-card`, `integration-card`, `pricing-card`, `final-cta`, `alternating-row`, or `faq-list` make intent obvious. Avoid `card`, `section`, `block` (too generic).
+3. Move the repeated markup into the framework's native component or partial mechanism. Applies in any templating system that supports component reuse: server-side partials, single-file components, JSX components, or build-time includes. Pick the mechanism the project already uses.
+4. Pass content as explicit fields. Embedded page-specific text inside shared markup is the most common cause of "we have a component but it still drifts".
+5. Make variants explicit through one prop, one class, or one data attribute. If a variant needs three coordinated changes, encode them in one named variant, not three knobs.
+6. Centralize the CSS for the family and remove or reduce page-local overrides. The component owns its visual contract; page CSS adjusts only what the component exposes.
+7. Re-render every route that uses the widget. A single broken instance proves the component is incomplete.
+8. Compare every instance side-by-side at both audit viewports. If two instances do not look like members of the same system, the contract is wrong or the variant set is incomplete.
+
+## What To Avoid
+
+These four anti-patterns produce most cross-page drift.
+
+- Copy-pasting a polished widget and tweaking classes page by page. The first divergence is the start of the drift; every subsequent page makes the contract harder to recover.
+- Creating near-duplicate components with different names but the same semantic purpose. `feature-card`, `feature-tile`, and `benefit-card` that differ only in padding and CTA copy are one component with one variant axis.
+- Fixing drift by adding more one-off CSS selectors. Page-local overrides reduce the symptom and reproduce the disease at the next site of drift.
+- Making one component so generic that every call site needs overrides to look right. Generic components without strong defaults push the styling burden back to the page, which is where the drift lives.
+
+## Drift Detection
+
+Programmatic drift detection complements visual review. Collect computed styles and bounding boxes for every member of a family across every route, then flag any difference not explained by a named variant.
+
+For each repeated widget selector, collect:
+
+- Width, height, padding, border-radius, border color, border width, border style, background, box-shadow.
+- Heading font-size, weight, line-height.
+- Body font-size, line-height, color.
+- CTA position and size.
+- Image and logo rendered size and aspect ratio.
+- Grid row height variance across the row.
+
+Run from a headless browser of your choice (Puppeteer, Playwright, or equivalent). The snippet below uses only standard DOM and CSSOM APIs:
+
+```js
+const componentMetrics = await page.evaluate(() => {
+  const read = (el) => {
+    const cs = getComputedStyle(el);
+    const r = el.getBoundingClientRect();
+    const heading = el.querySelector("h2, h3, .card-title");
+    const body = el.querySelector("p");
+    const cta = el.querySelector("a, button, .btn, .btn-text");
+    const img = el.querySelector("img");
+    return {
+      selector: el.className,
+      width: Math.round(r.width),
+      height: Math.round(r.height),
+      padding: cs.padding,
+      radius: cs.borderRadius,
+      background: cs.backgroundColor,
+      borderColor: cs.borderColor,
+      borderWidth: cs.borderWidth,
+      borderStyle: cs.borderStyle,
+      shadow: cs.boxShadow,
+      headingSize: heading ? getComputedStyle(heading).fontSize : null,
+      headingWeight: heading ? getComputedStyle(heading).fontWeight : null,
+      bodySize: body ? getComputedStyle(body).fontSize : null,
+      bodyLine: body ? getComputedStyle(body).lineHeight : null,
+      cta: cta ? cta.getBoundingClientRect().toJSON() : null,
+      image: img ? img.getBoundingClientRect().toJSON() : null,
+    };
+  };
+  const families = {
+    cards: [".feature-card", ".card-link", ".grid-item"],
+    integrations: [".integration-card", ".integration-tile", ".integration-logo-tile"],
+    pricing: [".pricing-card", ".pricing-table"],
+  };
+  const out = {};
+  for (const [name, selectors] of Object.entries(families)) {
+    out[name] = selectors.flatMap((s) => [...document.querySelectorAll(s)].map(read));
+  }
+  return out;
+});
+```
+
+Run the collector on every route in scope. Compare the result for each family across pages. Any difference in padding, radius, shadow, heading size, or CTA position that is not explained by a named variant is drift; fix the component (not the page) until the next run is clean.
+
+A family is drift-free when every same-variant instance produces the same metrics within rounding tolerance.
+
+## CSS Patterns That Prevent Drift
+
+These patterns reduce the surface area for drift before it starts. Use them on every shared widget. Detailed treatment of layout primitives lives in [responsive.md](responsive.md); detailed treatment of color, typography, and shadow tokens lives in [design.md](design.md). The patterns below are the multi-instance subset.
+
+### Tokens before primitives
+
+Normalize spacing, color, border, radius, shadow, and type scale tokens before building components. A component that references tokens stays in step with the system; a component that hardcodes values drifts from it.
+
+### Stable dimensions for repeated UI
+
+Card rows, logo tiles, and grid items must hold a consistent shape regardless of content length.
+
+- `min-height` on cards prevents short-content rows from collapsing.
+- `aspect-ratio` on media boxes prevents image jitter.
+- `align-items: stretch` on grid and flex rows keeps siblings the same height.
+- Fixed icon boxes (square wrapper around the SVG) prevent optical mis-centering.
+
+### Card grid pattern
+
+```css
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 24px;
+  align-items: stretch;
+}
+
+.card-grid > * {
+  min-width: 0;
+  height: 100%;
+}
+
+.card-link {
+  display: flex;
+  flex-direction: column;
+  min-height: 100%;
+  text-decoration: none;
+}
+
+.card-link:focus-visible,
+.button:focus-visible {
+  outline: 3px solid var(--focus-ring-fallback, #4f8cff);
+  outline: 3px solid color-mix(in srgb, var(--accent) 45%, white);
+  outline-offset: 3px;
+}
+
+@media (max-width: 767px) {
+  .card-grid {
+    grid-template-columns: 1fr;
+    gap: 16px;
+  }
+}
+```
+
+The `min-width: 0` on grid children is the most-skipped guard against text overflow. Without it, long words break out of the cell and drag the page wide on mobile.
+
+`color-mix(in srgb, ...)` is Baseline 2024. Older browsers fall back to the preceding `outline` declaration, so always provide the static-color line first. If the project supports browsers older than the 2024 baseline, drop the `color-mix` line entirely and use a precomputed token (`var(--color-focus-ring)`) instead.
+
+### Spacing via gap, not margin stacks
+
+Use `gap` for internal spacing on flex and grid containers. Margin stacks accumulate across instances and produce per-page drift; `gap` is owned by the container and stays constant.
+
+### Line length via max-width
+
+Constrain prose with `max-inline-size: 65ch` (or similar). Cards without measure constraints produce 90-character lines on desktop and 30-character lines on mobile, neither of which reads cleanly.
+
+### Full-card anchor, not nested anchors
+
+When a card visually behaves as a link, the entire card is the anchor. Nested anchors are invalid HTML and produce inconsistent click areas. If a card needs an inner CTA distinct from the outer link, switch to the button-card pattern: a stretched `::before` pseudo-element on the title link makes the whole card clickable while keeping nested controls separate.
+
+### Hover transforms do not stack
+
+If the card animates on hover and an inner CTA also animates, the two transforms compose and produce a buggy shift. Pick one layer for the hover transform; suppress the other inside the animated container.
+
+### Focus-visible, not focus
+
+Use `:focus-visible` so mouse users do not see a ring when clicking but keyboard users always do. The ring must be 2 to 4 px, with 3:1 contrast against both the surface and the resting state. Detailed contrast targets live in [accessibility.md](accessibility.md).
+
+### Image loading strategy per role
+
+- Hero LCP image: `loading="eager"`, `fetchpriority="high"`, declared `width` and `height`, `srcset` plus `sizes` for responsive widths.
+- Below-the-fold imagery: `loading="lazy"`, `decoding="async"`.
+- Logo tiles and avatars: fixed intrinsic dimensions, consistent ratio across the family.
+
+Performance treatment of images and fonts lives in [performance.md](performance.md); the rule above is the multi-instance one.
+
+### Visible text is the accessible name
+
+Do not hide visible text behind a mismatched `aria-label`. If the visible text names the control well, let it be the accessible name. When a control is icon-only, the `aria-label` matches the visible meaning the icon conveys.
+
+## See Also
+
+- [audit-workflow.md](audit-workflow.md) for the multi-page audit procedure that builds the widget inventory
+- [defects.md](defects.md) for symptom-to-fix lookup and the canonical geometry sweep
+- [ui-ux.md](ui-ux.md) for state coverage and interaction patterns
+- [accessibility.md](accessibility.md) for focus-visible, accessible names, and contrast rules referenced in the CSS patterns above
+- [responsive.md](responsive.md) for layout primitives
+- [design.md](design.md) for tokens, typography, and shadow language