codebyplan 1.5.1 → 1.8.0

package/templates/skills/cbp-frontend-ui/SKILL.md

@@ -0,0 +1,262 @@
+---
+scope: org-shared
+name: cbp-frontend-ui
+description: Visual quality self-review pass invoked twice per round — once by round-executor Step 3.8 (phase 'style_only', no screenshots) for token/spacing/typography/color/cohesion, once by /cbp-round-execute Step 5b (phase 'screenshot_review', with e2e screenshots) for rendered-output review and baseline regressions. Default phase 'full' runs everything for back-compat.
+effort: xhigh
+---
+
+# Frontend UI (Post-Implementation Visual Self-Review)
+
+Invoked twice per round in non-`claude_only` profiles:
+
+1. `round-executor` Step 3.8 — `phase: 'style_only'`, no e2e screenshots. Reviews token/spacing/typography/color/cohesion against the just-written code.
+2. `/cbp-round-execute` Step 5b — `phase: 'screenshot_review'`, with screenshots from `test-e2e-agent`. Reviews rendered output and detects baseline regressions.
+
+Default `phase: 'full'` runs everything (back-compat for any caller not yet migrated). Inline counterpart of the up-front `frontend-design` skill — `frontend-design` decides direction before code; `frontend-ui` reviews and polishes after code.
+
+## When this skill fires
+
+Round-executor invokes when the round's `files_changed` contains ANY of:
+
+- `*.tsx`, `*.jsx` (React, RN, RN-Web components)
+- `*.scss`, `*.css`, `*.module.{scss,css}`
+- Files under design-system / token folders, app-level styles
+- New page / screen / route / component files
+
+Same trigger condition as Step 2.7's `frontend-design` pre-implementation pass. If none match, skip — proceed to Step 4 (Quality Checks).
+
+## Input Contract
+
+```yaml
+input:
+  task_number: number
+  round_number: number
+  phase: 'full' | 'style_only' | 'screenshot_review'   # Default 'full'. Phase Gate at Workflow start routes execution.
+  files_changed: [{path, action}]
+  context:
+    checkpoint_goal: string
+    round_requirements: string
+  e2e_screenshots:                          # Required for phase 'screenshot_review' or 'full' (when present); empty / omitted for 'style_only'. Sourced from round.context.e2e_output.screenshots (populated by test-e2e-agent at /cbp-round-execute Step 5).
+    - test_name: string
+      path: string                          # Repo-relative or absolute path to PNG
+      page_or_screen: string
+      viewport: 'desktop' | 'mobile' | 'tablet' | 'device'
+      is_new: bool                          # No baseline existed (new screen)
+      baseline_diff_pct: number | null      # Pixel-diff % vs Playwright baseline
+```
+
+## Output Contract
+
+```yaml
+output:
+  status: 'completed'
+  findings:
+    - category: 'tokens' | 'spacing' | 'typography' | 'color' | 'layout' | 'cohesion' | 'rendered_visual' | 'baseline_regression'
+      severity: 'critical' | 'warning' | 'suggestion'
+      file: string                       # Source file OR screenshot path (for rendered_visual / baseline_regression)
+      line: number | null                # null when finding originates from a screenshot
+      issue: string
+      suggestion: string
+      screenshot: string | null          # Path to screenshot this finding was derived from (if any)
+  files_changed:
+    - path: string
+      action: 'modified'
+      fix_for: string                    # Which finding this fix addresses
+  screenshot_review:
+    reviewed: number                     # Count of e2e_screenshots reviewed
+    baseline_regressions: number         # Count with baseline_diff_pct > threshold
+    new_screens_reviewed: number         # Count with is_new == true
+  summary:
+    total_issues: number
+    critical: number
+    warnings: number
+    suggestions: number
+    auto_fixed: number
+```
+
+The executor writes the output to `round.context.frontend_ui_review` and merges `files_changed` into the round's `files_changed` list.
+
+## Reference Material
+
+Pattern references this skill consults during review (folded from former standalone skills):
+
+- `reference/ui-layout-patterns.md` — navbar height, focus-visible, z-index layering, fluid heights, logo overflow
+- `reference/variant-defaults.md` — `createResolver`, `SIZE_VARIANTS`, `COLOR_VARIANTS`, `CUSTOM_VARIANTS`, lightweight variant maps
+- `reference/ui-label-maps.md` — humanising DB column names + enum values for user-facing UI
+
+## Workflow
+
+### Phase Gate (preamble)
+
+Read `input.phase` (default `'full'` when absent). The gate routes which phases run:
+
+| Phase value | Phases that run |
+|-------------|----------------|
+| `'full'` (default) | All phases — 1, 2, 2.5, 3, 4, 5, 6, **6.5** (when `e2e_screenshots[]` non-empty), 7, 8 |
+| `'style_only'` | Phases 1, 2, 2.5, 3, 4, 5, 6, 7, 8 (Phase 6.5 is SKIPPED regardless of `e2e_screenshots[]`) |
+| `'screenshot_review'` | Phases 1 (read changed files only — needed for design-source comparison), **6.5**, 7, 8 (Phase 8 is a no-op for `rendered_visual` / `baseline_regression` — those categories are never auto-fixed) |
+
+When `phase === 'screenshot_review'` and `e2e_screenshots[]` is empty, return immediately with `status: 'completed'` and an empty `findings[]` — caller asked for screenshot review but provided no screenshots.
+
+When `phase === 'style_only'` and `files_changed[]` contains no UI files (no `*.tsx`, `*.scss`, `*.css`, design-token folders), return immediately with `status: 'completed'` and an empty `findings[]`.
+
+### Phase 1: Read Changed Files
+
+Read all `.tsx`, `.scss`, and `variants.ts` files from `files_changed`.
+
+### Phase 2: Design Token Compliance
+
+For each SCSS file:
+- Check that colors use semantic tokens (`$color-brand-*`, `$color-highlight-*`), never raw hex/rgb
+- Check spacing uses fluid tokens (`fluid()`, `$spacing-*`), never hardcoded px for layout
+- Check typography uses type scale tokens (`$font-size-*`, `$font-weight-*`)
+- Check z-index uses layering tokens, never arbitrary numbers — see `reference/ui-layout-patterns.md` "Z-Index Layers"
+
+For each TSX file:
+- Check inline styles are not used (should be SCSS modules)
+- Check className uses styles from module imports
+
+### Phase 2.5: Design Source Comparison
+
+When changed files belong to a page that has design source PNGs at a project-known design-sources path (e.g. `docs/design/`, `docs/development/product/sources/design/`):
+
+1. **Read** the design source PNG for the relevant page/component
+2. **Compare** the implemented component structure against the design source
+3. **Flag as critical** any of these mismatches:
+   - Wrong control shape (e.g. pill vs flat button, toggle vs stepper)
+   - Wrong background color (e.g. grey when design shows white)
+   - Missing dividers or separators shown in design
+   - Wrong column placement (e.g. controls in label column instead of action column)
+   - Wrong row/grid structure (e.g. stacked when design shows inline)
+4. Add findings to output with `category: 'cohesion'` and `severity: 'critical'`
+
+If no design source PNGs exist for the changed pages, skip this phase.
+
+### Phase 3: Spacing Consistency
+
+- Verify consistent spacing patterns within components (same spacing system)
+- Check padding/margin consistency across sibling elements
+- Verify fluid spacing is used for layout, em-based for typography-adjacent
+
+### Phase 4: Typography Review
+
+- Check font-family assignments use design tokens
+- Verify heading hierarchy (h1 > h2 > h3 in size)
+- Check line-height and letter-spacing use tokens
+- Verify responsive typography uses fluid values
+
+### Phase 5: Color Usage
+
+- Check color semantics (brand vs highlight vs accent vs interactive)
+- Verify hover/focus states use correct color variants — see `reference/ui-layout-patterns.md` "Focus-Visible" and `reference/variant-defaults.md` "COLOR_VARIANTS"
+- Check dark mode compatibility if applicable
+- Verify sufficient contrast ratios (reference WCAG)
+
+### Phase 6: Visual Cohesion
+
+- Check that new components match visual patterns of existing components
+- Verify consistent border-radius, shadow, and transition usage
+- Check animation patterns follow existing conventions
+- For variant components: verify `variants.ts` follows the resolver patterns in `reference/variant-defaults.md` (no duplicate defaults, correct layer ordering)
+- For DB-sourced strings rendered in JSX (snake_case enums, trigger types, status codes): verify `LABELS` const maps are used per `reference/ui-label-maps.md`
+
+### Phase 6.5: Rendered-Output Visual Review (from E2E screenshots)
+
+**Runs only if `e2e_screenshots[]` is non-empty.** This is the critical step that closes the loop — e2e tests proved behavior works; this step checks what the screen actually looks like.
+
+For each screenshot in `e2e_screenshots[]`:
+
+1. **Read the PNG via the Read tool** (Claude multimodal — the PNG is shown to the model directly). Do not use Bash to inspect bytes.
+2. **Check baseline regression** (`baseline_diff_pct != null`):
+   - If `baseline_diff_pct > 0.1%`: emit finding `{category: 'baseline_regression', severity: 'critical', file: {path}, screenshot: {path}, issue: 'Pixel diff vs committed baseline: {diff_pct}%', suggestion: 'Inspect the diff PNG (same folder, -diff suffix). Either fix the regression or, if intentional, run `playwright test --update-snapshots` and commit the new baseline.'}`
+   - Do NOT auto-update baselines. The user must explicitly approve via QA.
+3. **Semantic review of rendered output** (both new screens and existing):
+   - **Text overflow / truncation** — text clipped, ellipsis in unintended places, buttons cut off
+   - **Unstyled elements** — unbranded default fonts, missing styles (flash of unstyled content captured), default blue links
+   - **Missing imagery / broken images** — placeholder icons, broken-image glyphs, avatar fallback unstyled
+   - **Contrast failures** — text barely visible against background (WCAG fail)
+   - **Layout breaks** — overlapping elements, pushed-off-canvas content, unintended scrollbars, empty whitespace where content should be
+   - **Loading-state artifacts** — spinner visible in final-state screenshot (data didn't load in time or empty-state is wrong)
+   - **Error-boundary leaks** — "Something went wrong" / red error banners that shouldn't be there
+   - **Design-source mismatch** (if a design-source PNG exists for the page) — compare rendered to designed
+4. **Emit findings** with `category: 'rendered_visual'`, the screenshot path in `screenshot`, and `line: null`. Severity: `critical` for broken state (overflow, missing images, error banners, contrast fails), `warning` for cosmetic misalignment, `suggestion` for minor polish.
+5. **Cross-viewport consistency**: if the same `page_or_screen` appears at multiple viewports (desktop + mobile), verify responsive behavior is correct (nothing cropped at mobile, desktop isn't mobile-sized). Emit `{category: 'layout', severity: 'warning', …}` on mismatch.
+
+Populate `screenshot_review` totals.
+
+**Do not attempt to auto-fix `rendered_visual` or `baseline_regression` findings** — they feed into user QA and the fix loop, because the root cause is typically in app code/data, not in the SCSS.
+
+### Phase 7: Aggregate Findings
+
+Categorize all issues by severity:
+- **Critical**: Hardcoded colors/spacing, missing tokens, broken layout
+- **Warning**: Inconsistent spacing, non-standard patterns
+- **Suggestion**: Minor visual improvements, optional enhancements
+
+### Phase 8: Auto-Fix In-Scope Findings
+
+For every finding in `category` ∈ {`tokens`, `spacing`, `typography`, `color`, `layout`, `cohesion`} — critical, warning, and suggestion — apply the fix directly when the target file is in `files_changed`:
+
+#### Pre-Edit Scope Gate (MANDATORY)
+
+Before any Write/Edit:
+
+1. Build `allowed = new Set(input.files_changed.map(f => f.path))`.
+2. If the target path is in `allowed`, proceed to apply the fix.
+3. If the target path is NOT in `allowed`, do NOT edit. Instead:
+   - Emit the proposed fix as a `findings[]` entry with the appropriate severity and a `suggestion` describing the change verbatim.
+   - Set `auto_fixed = false` for that finding.
+   - Increment `summary.out_of_scope_fixes`.
+
+The skill's auto-fix capability is for in-scope polish, not opportunistic sweeps of unrelated files. The scope gate prevents the round's diff from absorbing visual changes outside the round's contract.
+
+**Specifically forbidden** (always out of scope, never edited regardless of `files_changed`):
+
+- `.claude/**` — managed infrastructure under user-level governance
+- Project test infrastructure (e.g., `playwright.config.*`, `e2e/**`) — governed by `test-e2e-agent`
+- DB migrations (e.g., `supabase/migrations/**`) — governed by `database-agent`
+- Vendor mirrors and read-only reference trees
+
+#### In-Scope Auto-Fix Procedure
+
+For findings whose target file IS in `allowed`:
+
+1. Read the file at the reported line
+2. Apply the fix (replace hardcoded hex with token, swap px for fluid spacing, improve visual consistency, refine typography, enhance cohesion)
+3. Track in `files_changed` with `fix_for` referencing the finding
+
+Go beyond fixing violations — actively improve visual quality. If spacing could be better, improve it. If a component looks inconsistent with siblings, align it. Deliver polished UI, not just compliant UI.
+
+**Do not auto-fix** findings with `category` ∈ {`rendered_visual`, `baseline_regression`} — these surface through QA and the fix loop because the root cause is typically in app state/data, not styling.
+
+**Do not modify** component logic or behavior — only visual/design work.
+
+## Completion Criteria
+
+- All changed SCSS/TSX files reviewed
+- Token compliance checked
+- Spacing consistency verified
+- **All `e2e_screenshots` reviewed** (when provided) — rendered output checked for overflow, unstyled elements, missing imagery, contrast, layout breaks, loading/error artifacts, design-source fidelity
+- Baseline regressions surfaced (never auto-accepted)
+- Critical/warning issues auto-fixed where possible (styling only, in-scope only)
+- Findings categorized by severity
+
+## Failure Modes
+
+| Condition | Status | What to populate |
+|---|---|---|
+| No UI files changed AND `e2e_screenshots[]` is empty | `completed` | Empty `findings[]`, `summary.total_issues: 0`, `screenshot_review: {reviewed: 0, ...}` — caller decided to invoke; return clean |
+| Screenshot path in `e2e_screenshots[]` cannot be read (missing file, corrupt PNG) | `completed` | Add `{category: 'rendered_visual', severity: 'warning', file: {path}, issue: 'Screenshot unreadable — visual review skipped for this state'}` and continue with the remaining screenshots |
+| Design source PNG referenced but missing | `completed` | Skip Phase 2.5 for that page; note in finding with `category: 'cohesion', severity: 'suggestion'` that design source should be added |
+| Auto-fix attempt introduces a syntax error in an SCSS/TSX file | `completed` | Revert the auto-fix, keep the finding as a non-fixed entry, do NOT silently leave the file broken |
+
+## Integration
+
+- **Loaded twice per round** (non-`claude_only` profiles):
+  1. `round-executor` Step 3.8 with `phase: 'style_only'` and empty `e2e_screenshots[]` — reviews the just-written code's tokens/spacing/typography/color/cohesion (mandatory when files_changed contains UI / styling files)
+  2. `/cbp-round-execute` Step 5b with `phase: 'screenshot_review'` and screenshots from `round.context.e2e_output.screenshots` — runs Phase 6.5 only (rendered-output review + baseline regressions). Skipped when no e2e ran (`claude_only` / `backend` / `has_ui_work === false`).
+- **Also invoked by**: `/cbp-checkpoint-check` (TASK-2 deliverable, future) with screenshots from a whole-checkpoint e2e run
+- **Consumes**: `e2e_screenshots[]` from `round.context.e2e_output.screenshots` (populated by `test-e2e-agent` at `/cbp-round-execute` Step 5)
+- **Output written to**: `round.context.frontend_ui_review` — when invoked twice per round, the second invocation merges with the first
+- **User-QA construction (downstream)**: this skill emits `findings[]` only — it does NOT construct user_qa items. `/cbp-round-end` Step 3b reads `round.context.frontend_ui_review.findings[]` and aggregates baseline-regression + rendered-visual-critical entries into the round's `user_qa[]`. Single source of truth for the user_qa schema lives at round-end.
+- **Paired with**: `frontend-design` (pre-implementation aesthetic decision), `frontend-ux` (interaction-quality self-review, also Step 3.8)

package/templates/skills/cbp-frontend-ui/reference/ui-label-maps.md

@@ -0,0 +1,42 @@
+# UI Label Maps
+
+Pattern for humanizing DB column names, enum values, and trigger types when displayed in user-facing JSX.
+
+When displaying database column names, enum values, trigger types, or status codes in user-facing JSX, define a `LABELS` const map in the same component file (or a shared labels module).
+
+## Pattern
+
+```ts
+const TRIGGER_LABELS: Record<string, string> = {
+  port_changed: "Port Changed",
+  repo_created: "Repo Created",
+  tech_stack_changed: "Tech Stack Changed",
+  port_conflict_detected: "Port Conflict",
+  created: "Created",
+};
+
+function formatTriggerLabel(trigger: string | null | undefined): string {
+  if (!trigger) return "Event";
+  return TRIGGER_LABELS[trigger] ?? trigger;
+}
+```
+
+## When to Apply
+
+- Rendering DB enum columns in JSX (status, type, action, trigger)
+- Displaying changed_field arrays in audit log UIs
+- Showing column names from JSONB context fields
+- ANY snake_case string sourced from DB that a user will see
+
+## Anti-Pattern
+
+NEVER render `{event.trigger}` directly when trigger is a snake_case enum. Users see "PORT_CHANGED" with no context.
+
+## Shared vs Local Maps
+
+- **Local** (in component file): map is used in 1 component, fewer than ~10 entries
+- **Shared** (`apps/web/src/lib/labels/`): map is used in 2+ components OR has 10+ entries
+
+## Source
+
+CHK-077 TASK-3 Round 2 required adding `TRIGGER_LABELS` + `FIELD_LABELS` maps to `TaskDetail.tsx` after testing-qa flagged raw snake_case in the event timeline.

package/templates/skills/cbp-frontend-ui/reference/ui-layout-patterns.md

@@ -0,0 +1,105 @@
+# UI Layout Patterns
+
+Navbar layout patterns, focus-visible accessibility conventions, and z-index layering. Ensures consistent navbar implementation and proper focus-visible accessibility across all client projects.
+
+Apply when working with Navbar components, focus-visible styles, or z-index layering in `.scss` files.
+
+## 1. Navbar Height is Fluid
+
+```scss
+// layout/_variables.scss
+$navbar-height: fluid(3.5rem, 4.5rem);  // 56px -> 72px responsive
+```
+
+All navbar molecules use the layout variable:
+
+```scss
+@use '../../../../styles/layout' as layout;
+.desktop { height: layout.$navbar-height; }
+```
+
+## 2. Logo Sizing Based on Navbar
+
+Logo size derives from navbar height:
+
+```scss
+$_logo-nav-size: calc(#{layout.$navbar-height} * 0.6);
+
+.logo {
+  &--nav { font-size: $_logo-nav-size; }
+  &--nav-mobile { height: layout.$navbar-height; font-size: $_logo-nav-size; }
+}
+```
+
+## 3. Logo Overflow
+
+Logo can overflow navbar with absolute positioning:
+
+```scss
+.logo {
+  &--nav {
+    position: absolute;
+    top: 50%;
+    transform: translateY(-50%);
+    z-index: calc(layout.z-index('navbar') + 1);
+  }
+}
+
+.desktop {
+  position: relative;  // Positioning context
+  overflow: visible;   // Allow overflow
+}
+```
+
+## 4. Navbar Variants
+
+| Variant | Component | Height | Notes |
+|---------|-----------|--------|-------|
+| Desktop | Desktop molecule | $navbar-height | Logo overflows |
+| Mobile (collapsed) | MobileOpen | $navbar-height | Logo inside |
+| Mobile (expanded) | MobileClose | 100vh | Full-screen overlay |
+
+## 5. Z-Index Layers
+
+```scss
+layout.z-index('navbar')     // Base navbar layer
+layout.z-index('navbar') + 1 // Logo (above navbar)
+layout.z-index('overlay')    // Mobile menu overlay
+```
+
+## 6. Focus-Visible: Always Use the Mixin
+
+NEVER write inline `:focus-visible` styles. Always use accessibility module mixins:
+
+```scss
+@use '../../styles/accessibility' as a11y;
+
+// CORRECT
+.button { @include a11y.focus-visible; }
+
+// WRONG
+.button { &:focus-visible { outline: 2px solid #00a7b3; } }
+```
+
+## 7. Available Focus Mixins
+
+| Mixin | Use Case |
+|-------|----------|
+| `focus-visible` | Standard (2px solid, 2px offset) |
+| `focus-visible-offset($offset)` | Custom offset |
+| `focus-visible-inset` | Inset outline (-2px offset) |
+
+## 8. Border-Radius Affects Focus Outline
+
+Add `border-radius` for rounded focus outline:
+
+```scss
+.logo {
+  border-radius: 4px;
+  @include a11y.focus-visible;
+}
+```
+
+## 9. Focus vs Hover Colors
+
+Use `:focus-visible` (not `:focus`) — shows only on keyboard navigation. Different colors for hover (`$hover-active`) vs focus (`$focus-outline`).

package/templates/skills/cbp-frontend-ui/reference/variant-defaults.md

@@ -0,0 +1,149 @@
+# Variant Defaults & Button Patterns
+
+3-layer variant architecture using `createResolver` with SIZE, COLOR, and CUSTOM variants, lightweight variant maps for simpler components, plus button-specific patterns.
+
+Apply when working with `variants.ts` files, components in `src/components/buttons/`, or components using size/color variant props with BEM modifier classes. Ensures correct variant resolution order and prevents duplicate defaults.
+
+## 1. 3-Layer Architecture
+
+```
+Props -> createResolver -> CSS Classes
+         Resolution Order:
+         1. Custom variant (presets)
+         2. Size variant (typography/spacing)
+         3. Color variant (colors/interactions)
+         4. Direct prop overrides (highest priority)
+```
+
+## 2. Never Duplicate Defaults
+
+Values in SIZE/COLOR/CUSTOM_VARIANTS MUST NOT repeat defaults:
+
+```typescript
+// WRONG
+const defaults = { fontWeight: 'medium', typoPx: 's1' };
+const SIZE_VARIANTS = {
+  md: { fontSize: 'body-md', fontWeight: 'medium' }, // duplicates default
+};
+
+// CORRECT
+const SIZE_VARIANTS = {
+  md: { fontSize: 'body-md' },  // only what differs
+};
+```
+
+## 3. Layer Definitions
+
+**SIZE_VARIANTS** (typography/spacing):
+```typescript
+const SIZE_VARIANTS = {
+  sm: { fontSize: 'body-sm' },
+  md: { fontSize: 'body-md' },
+  lg: { fontSize: 'body-lg', typoPx: 's15', typoPy: 's1' },
+} as const satisfies Record<string, SizeConfig>;
+```
+
+**COLOR_VARIANTS** (colors/interactions):
+```typescript
+const COLOR_VARIANTS = {
+  primary: { bg: 'primary', text: 'inverse' },
+  highlight: { bg: 'highlight', text: 'primary' },
+  transparent: { bg: 'transparent', text: 'primary' },
+} as const satisfies Record<string, ColorConfig>;
+```
+
+**CUSTOM_VARIANTS** (presets combining size + color + overrides):
+```typescript
+const CUSTOM_VARIANTS = {
+  cta: {
+    colorVariant: 'highlight',
+    fontFamily: 'accent',
+    glow: 'sm',
+  },
+} as const satisfies Record<string, CustomConfig>;
+```
+
+## 4. Type Annotations Required
+
+All variant maps MUST use `as const satisfies Record<string, *Config>`.
+
+## 5. createResolver Setup
+
+```typescript
+import { createResolver, SizeConfig, ColorConfig, CustomConfig } from '@/utils/variants';
+
+export const getVariant = createResolver({
+  sizes: SIZE_VARIANTS,
+  colors: COLOR_VARIANTS,
+  custom: CUSTOM_VARIANTS,
+  defaults,
+});
+```
+
+## 6. Button Types
+
+```
+src/components/buttons/
+├── Button/       # Form submit, modal triggers, state changes
+├── LinkButton/   # Navigation (links)
+└── IconButton/   # Icon-only actions
+```
+
+All buttons use `createResolver`. Each has 5 files: `index.ts`, `Component.tsx`, `Component.module.scss`, `types.ts`, `variants.ts`.
+
+## 7. Button Defaults
+
+| Button | Default Size | Default Color |
+|--------|--------------|---------------|
+| Button | md | primary |
+| LinkButton | md | transparent |
+| IconButton | md | transparent |
+
+## 8. SCSS Modifier Includes
+
+All buttons include the standard modifier mixins:
+
+```scss
+.button {
+  @include typography.font-family;
+  @include typography.font-weight;
+  @include typography.font-size;
+  @include typography.tracking;
+  @include typography.leading;
+  @include typography.transform;
+  @include typography.typo-px;
+  @include typography.typo-py;
+  @include typography.typo-gap;
+  @include borders.border-radius;
+  @include borders.border-width;
+  @include borders.border-color;
+  @include interactive.color-interactive;
+  @include shadows.glow;
+  @include a11y.focus-visible;
+}
+```
+
+## 9. Lightweight Variant Maps (Alternative to createResolver)
+
+For components that only need prop-to-BEM-suffix resolution without the full variant pipeline, use simple `Record<TypeUnion, string>` maps or direct prop interpolation.
+
+**When to use**: Component has 1-2 variant dimensions (size, color) with no defaults merging, no custom presets, and no resolution priority logic. Common in icon components and simple wrappers.
+
+**Pattern A — Direct prop interpolation** (no variants.ts needed):
+```typescript
+// Prop value IS the BEM suffix — no map needed
+styles[`spinner--${size}`]
+styles[`checkmark--text-${color}`]
+```
+
+**Pattern B — Explicit variant map** (in variants.ts):
+```typescript
+export const SIZE_VARIANTS: Record<ContainerSize, string> = {
+  sm: 'sm',
+  md: 'md',
+  lg: 'lg',
+}
+// Usage: styles[`container--${SIZE_VARIANTS[size]}`]
+```
+
+**Decision rule**: If prop values map 1:1 to BEM suffixes, use Pattern A. If mapping differs from prop names or you want a centralized variants.ts, use Pattern B. If you need defaults merging, resolution priority, or custom presets, use `createResolver` (sections 1-5).