codebyplan 1.5.1 → 1.9.0

package/templates/skills/cbp-frontend-a11y/reference/contrast-visual.md

@@ -0,0 +1,122 @@
+# Contrast and Visual Accessibility Reference
+
+## WCAG 2.1 AA Contrast Requirements
+
+All text and UI components must meet these minimum contrast ratios:
+
+| Content type | Minimum ratio | Standard |
+|-------------|--------------|---------|
+| Normal text (< 18pt / < 14pt bold) | **4.5:1** | WCAG 2.1 AA SC 1.4.3 |
+| Large text (≥ 18pt / ≥ 14pt bold) | **3:1** | WCAG 2.1 AA SC 1.4.3 |
+| UI components (borders, icons, form controls) | **3:1** | WCAG 2.1 AA SC 1.4.11 |
+| Graphical objects (data chart elements, icons conveying meaning) | **3:1** | WCAG 2.1 AA SC 1.4.11 |
+
+**Decorative** elements (purely ornamental, no meaning) are EXEMPT.
+
+### Verification
+
+Use design tokens from `packages/design-tokens/` to derive hex values, then verify with a contrast checker:
+
+- Browser DevTools Accessibility panel
+- `npx @accessibility-checker/cli` against the rendered component
+- Design-tool plugins (Figma Contrast, Stark)
+
+If a token pair is new, record the ratio in a comment in the SCSS: `/* contrast: 5.2:1 vs --color-surface */`.
+
+## Focus Visible
+
+Focus indicators must NEVER be suppressed via `outline: none` or `outline: 0` without providing a replacement that meets **3:1 contrast** against adjacent colour:
+
+```scss
+// Anti-pattern — removes all visible focus indicator
+&:focus {
+  outline: none; // WCAG failure
+}
+
+// Correct — custom focus ring that meets 3:1 contrast
+&:focus-visible {
+  outline: 2px solid var(--color-focus-ring);   // 3:1 minimum
+  outline-offset: 2px;
+}
+```
+
+Use `:focus-visible` (not `:focus`) for the custom ring — `:focus-visible` suppresses the ring for mouse clicks while preserving it for keyboard navigation.
+
+The WCAG 2.2 enhanced criterion (SC 2.4.11, AAA) requires 3:1 contrast + 2px outline area. Target this for new components.
+
+## Colour-Only State Communication
+
+State conveyed through colour alone is a WCAG 2.1 AA failure (SC 1.4.1). Always pair colour with at least one of: icon, text label, pattern, or shape.
+
+| Anti-pattern | Fix |
+|-------------|-----|
+| Red border = error (colour only) | Red border + error icon + "Invalid email" text |
+| Green = online (colour only) | Green dot + "Online" text label |
+| Yellow = warning (colour only) | Yellow background + warning icon + descriptive text |
+| Active nav item is blue (colour only) | Blue + `aria-current="page"` + underline or bold weight |
+
+## prefers-reduced-motion
+
+Users with vestibular disorders may configure `prefers-reduced-motion: reduce` in their OS. Honour it:
+
+```scss
+@keyframes slideIn {
+  from { transform: translateX(-100%); }
+  to   { transform: translateX(0); }
+}
+
+.panel {
+  animation: slideIn 300ms ease-out;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+    // Provide instant appearance or a fade (no translate/scale/spin)
+  }
+}
+```
+
+For JavaScript-driven animations:
+
+```ts
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+if (!prefersReduced) {
+  // run animation
+}
+```
+
+Transitions that solely affect `opacity` (fade) are generally safe — opacity changes do not trigger vestibular responses. Transforms (`translate`, `scale`, `rotate`) and large motion sweeps are the primary triggers.
+
+## Touch Target Size
+
+Interactive elements must have a minimum tap target of **44 × 44 CSS px** (Apple HIG / WCAG 2.5.5 AAA, de-facto standard):
+
+```scss
+.icon-button {
+  min-width: 44px;
+  min-height: 44px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+```
+
+When the visible icon is smaller (e.g. 24px), expand the tap target with padding:
+
+```scss
+.icon-button {
+  padding: 10px; // 24px icon + 2×10px padding = 44px touch target
+}
+```
+
+On mobile breakpoints specifically, verify that adjacent interactive elements have at least 8px spacing between tap target edges to prevent accidental activation.
+
+## Text Resizing
+
+Users who increase browser text size up to 200% must be able to read and use all content without horizontal scroll (WCAG 1.4.4). Use relative units:
+
+- `font-size`: `rem` (relative to browser root, respects user preference)
+- `line-height`: unitless (e.g. `1.5`) or `em`
+- Container widths: `max-width` in `ch` or `%`, never fixed `px` for reading columns
+- Spacing: `em` for component-internal spacing; `rem` for layout spacing
+
+Avoid `px` for font sizes on text elements that users may need to scale.

package/templates/skills/cbp-frontend-a11y/reference/keyboard-patterns.md

@@ -0,0 +1,154 @@
+# Keyboard Interaction Patterns Reference
+
+Every interactive component must be fully operable with a keyboard alone. Mouse-only patterns are WCAG 2.1 AA failures (Success Criterion 2.1.1).
+
+## Focus Management
+
+### On Mount (Dialog / Modal / Drawer)
+
+When a dialog, modal, or drawer opens:
+
+1. Move focus to the FIRST interactive element inside (or to the dialog container if no interactive element exists — ensure `tabindex="0"` on the container in that case)
+2. For modals with a clear primary action: move focus to the primary action button
+3. For forms: move focus to the first form field
+
+```jsx
+// Using useEffect + ref
+const modalRef = useRef<HTMLDivElement>(null);
+
+useEffect(() => {
+  if (isOpen) {
+    // Focus the first focusable element inside
+    const firstFocusable = modalRef.current?.querySelector<HTMLElement>(
+      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+    );
+    firstFocusable?.focus();
+  }
+}, [isOpen]);
+```
+
+### On Close (Dialog / Modal / Drawer)
+
+When a dialog, modal, or drawer closes:
+
+1. Return focus to the element that TRIGGERED the opening (save a ref to it before opening)
+2. If the trigger no longer exists (deleted row), focus the nearest logical element
+
+```jsx
+const triggerRef = useRef<HTMLButtonElement>(null);
+
+const handleClose = () => {
+  setIsOpen(false);
+  // Return focus to trigger
+  triggerRef.current?.focus();
+};
+```
+
+## Tab Order
+
+- Tab order must follow the logical reading/interaction order — typically top-left to bottom-right
+- Never use `tabindex > 0` — it creates a separate tab order before natural DOM order, confusing all keyboard users
+- `tabindex="0"` adds a non-interactive element to natural tab order (use sparingly — prefer interactive elements)
+- `tabindex="-1"` removes from natural tab order but allows programmatic `.focus()` (correct for modal containers)
+
+## Esc Key
+
+Any overlay, popover, dropdown, or modal MUST close on `Escape`:
+
+```jsx
+useEffect(() => {
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'Escape') {
+      onClose();
+    }
+  };
+  if (isOpen) {
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }
+}, [isOpen, onClose]);
+```
+
+## Arrow Key Navigation
+
+For composite widgets (menu, listbox, radio group, tabs, grid), arrow keys navigate BETWEEN items — Tab moves focus OUT of the widget entirely.
+
+| Widget | Keys |
+|--------|------|
+| Menu / dropdown | `↑`/`↓` between items, `Home`/`End` to first/last |
+| Tabs | `←`/`→` between tabs (horizontal) or `↑`/`↓` (vertical) |
+| Listbox | `↑`/`↓` between options, `Home`/`End` |
+| Grid | `↑`/`↓`/`←`/`→` between cells |
+| Radio group | `↑`/`↓` or `←`/`→` between radios; selection follows focus |
+
+## Focus Traps (Modal)
+
+While a modal is open, Tab and Shift+Tab must cycle WITHIN the modal — not escape to the page behind:
+
+```jsx
+const FOCUSABLE_SELECTORS =
+  'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+const handleTabKey = (e: KeyboardEvent) => {
+  const focusableEls = Array.from(
+    modalRef.current?.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTORS) ?? []
+  );
+  const first = focusableEls[0];
+  const last = focusableEls[focusableEls.length - 1];
+
+  if (e.shiftKey && document.activeElement === first) {
+    e.preventDefault();
+    last.focus();
+  } else if (!e.shiftKey && document.activeElement === last) {
+    e.preventDefault();
+    first.focus();
+  }
+};
+```
+
+Library alternative: `focus-trap-react` handles this pattern with accessibility compliance. If it is already in `package.json`, use it.
+
+## Type-Ahead (Listbox / Menu)
+
+When a user types a character while focus is inside a listbox or menu, focus jumps to the first item whose label starts with that character. Implement only when `role="listbox"` or `role="menu"` is used with custom keyboard handling — native `<select>` has this built in.
+
+## Enter and Space Activation
+
+| Element | Enter | Space |
+|---------|-------|-------|
+| `<button>` | Activates | Activates |
+| `<a href>` | Follows link | Scrolls page (native browser) |
+| `<input type="checkbox">` | n/a | Toggles |
+| `role="button"` | Must activate | Must activate |
+| `role="menuitem"` | Activates | Activates |
+
+For custom `role="button"` on a non-button element:
+```jsx
+<div
+  role="button"
+  tabIndex={0}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      handleActivate();
+    }
+  }}
+  onClick={handleActivate}
+>
+  Custom button
+</div>
+```
+
+Prefer `<button>` — it handles Enter/Space natively and avoids this boilerplate.
+
+## Skip Links
+
+For pages with repeated navigation (header nav present on every page), provide a skip-to-main-content link as the first focusable element:
+
+```jsx
+<a href="#main-content" className={styles.skipLink}>
+  Skip to main content
+</a>
+```
+
+Visible on focus (via CSS), hidden otherwise. The `<main id="main-content">` is the target.

package/templates/skills/cbp-frontend-a11y/reference/semantic-html.md

@@ -0,0 +1,111 @@
+# Semantic HTML Reference
+
+Use native HTML semantics first. ARIA is a gap-filler for when no native element meets the need — not a replacement.
+
+## Landmark Roles
+
+| Element | Role | Notes |
+|---------|------|-------|
+| `<main>` | `main` | Exactly ONE per page |
+| `<nav>` | `navigation` | Multiple allowed; each needs an `aria-label` |
+| `<header>` | `banner` (at page scope) | In a sectioning element it becomes generic |
+| `<footer>` | `contentinfo` (at page scope) | |
+| `<aside>` | `complementary` | |
+| `<section>` | `region` (only when it has an `aria-labelledby`) | Without label, it's generic |
+
+Anti-pattern: `<div role="main">` — use `<main>` instead.
+
+## Heading Hierarchy
+
+- One `<h1>` per page — the page title or primary content heading
+- Never skip levels: `h1 → h2 → h3`, not `h1 → h3`
+- Headings convey structure, not visual size — use CSS for size; use the correct level for hierarchy
+- Empty headings (`<h2></h2>`) violate WCAG 2.4.6
+
+## `<button>` vs `<a>`
+
+| Use | Element |
+|-----|---------|
+| Triggers an action (submit, open modal, toggle) | `<button>` |
+| Navigates to a URL | `<a href="...">` |
+| Downloads a file | `<a href="..." download>` |
+
+Anti-patterns:
+- `<div onClick={doAction}>` — not keyboard accessible; use `<button>`
+- `<button onClick={() => router.push('/path')}>` — use `<a href="/path">`; or `<Link href="/path">` in Next.js
+- `<a href="#">` with an onClick — use `<button>` if no real URL
+
+## Form Elements
+
+```html
+<!-- Correct: explicit association -->
+<label htmlFor="email-input">Email</label>
+<input id="email-input" type="email" name="email" />
+
+<!-- Correct: implicit wrapping -->
+<label>
+  Email
+  <input type="email" name="email" />
+</label>
+
+<!-- Anti-pattern: no association -->
+<span>Email</span>
+<input type="email" name="email" />
+```
+
+For fieldsets with radio/checkbox groups:
+```html
+<fieldset>
+  <legend>Preferred contact method</legend>
+  <label><input type="radio" name="contact" value="email" /> Email</label>
+  <label><input type="radio" name="contact" value="phone" /> Phone</label>
+</fieldset>
+```
+
+## Lists
+
+Use `<ul>/<ol>/<li>` for lists of items — screen readers announce item count and position.
+
+Anti-pattern: `<div class="list"><div class="item">...</div></div>` — no count/position announced.
+
+Exception: `list-style: none` on `<ul>` removes list semantics in Safari/VoiceOver. Add `role="list"` when list-style is suppressed:
+```jsx
+<ul role="list" style={{ listStyle: 'none' }}>
+```
+
+## Tables
+
+For data tables (not layout):
+```html
+<table>
+  <caption>Monthly sales by region</caption>
+  <thead>
+    <tr>
+      <th scope="col">Region</th>
+      <th scope="col">Sales</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th scope="row">North</th>
+      <td>$12,000</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+`<caption>` is the table's accessible name. `scope="col"/"row"` associates headers with cells.
+
+Never use `<table>` for visual layout — use CSS Grid or Flexbox.
+
+## Anti-Pattern Quick-Reference
+
+| Anti-pattern | Fix |
+|-------------|-----|
+| `<div onClick>` | `<button>` or `<a>` |
+| `<span onClick>` | `<button>` |
+| `<img>` missing `alt` | Add `alt="description"` or `alt=""` for decorative |
+| `<input>` missing label | Add `<label htmlFor>` or `aria-label` |
+| `<h1>` used for styling | Use CSS; pick correct heading level |
+| `<table>` for layout | Use CSS Grid/Flexbox |
+| Empty `<button>` (icon only) | Add `aria-label="Close"` |

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

@@ -0,0 +1,145 @@
+---
+scope: org-shared
+name: cbp-frontend-design
+description: Up-front design playbook loaded BEFORE writing UI / styling code. Detects the stack, loads the matching reference file, commits to an aesthetic direction, and prevents generic AI-slop output. Modelled on Anthropic's frontend-design skill, adapted for CBP repos with existing design systems.
+effort: xhigh
+---
+
+# Frontend Design (Pre-Implementation Playbook)
+
+Loaded by `round-executor` Step 2.7 BEFORE any UI or styling file is written. Not a review skill — review happens later via the `frontend-ui` and `frontend-ux` skills, invoked inline by `round-executor` Step 3.8 after code is written. This is the up-front "think before you code" pass that produces good design at the first attempt instead of catching bad design after.
+
+## When this skill fires
+
+Round-executor invokes when the round's `files_to_modify` contains ANY of:
+
+- `*.tsx`, `*.jsx` (React, RN, RN-Web components)
+- `*.scss`, `*.css`, `*.module.{scss,css}`
+- Files under `packages/design-tokens/`, `apps/*/styles/`, design-system folders
+- A new page, screen, route, or component file
+- Plan deliverables mentioning UI, layout, visual, screen, page, modal, button, form
+
+If none match, skip — proceed to Step 3.
+
+## Phase 1: Read the brand BEFORE choosing an aesthetic
+
+In an existing app, the brand already exists. Discovery is mandatory before any creative choice:
+
+1. Find the design tokens — `packages/design-tokens/`, `apps/*/styles/tokens.*`, `apps/*/src/theme/*`, or equivalent. Read what colours, type scale, spacing scale, radii, shadows, motion, breakpoints are defined.
+2. Find sibling components — open 2 components in the same folder as the file you're about to write. Note their layout, density, type usage, motion presence.
+3. Find the established aesthetic in 30 seconds: refined-minimal? Dense-data? Editorial? Brutalist? Soft-pastel? Industrial? Read 1 page-level component to feel the answer.
+
+### Design source images (when provided)
+
+If the requirements reference design sources OR the round is page-level:
+
+- **Location**: `/docs/development/product/sources/design/*.png` — Glob by page or component name from requirements
+- **Read** matching PNGs before writing `plan.ui_ux_considerations.visual_notes` (planner) or before any code (executor)
+- **Extract**:
+  - Control shapes (flat buttons, pill buttons, toggles, steppers, dropdowns)
+  - Background colours within cards and sections
+  - Column layout and which column holds action controls
+  - Dividers, separators, row structure
+  - Spacing patterns between rows and groups
+  - Placeholder style, border, input shape — for embedded form controls
+
+If no PNGs exist, skip silently and rely on sibling-component discovery (steps 1–3 above).
+
+### Embedded controls also count
+
+When a round adds a NEW interactive control (input, button, tag, toggle block) inside an EXISTING row or card component, the same design-source reading applies — even when:
+
+- The parent component already exists
+- The new control is "small" (e.g., an address input inside a row)
+- The design change seems incremental
+
+Iterative discovery of visual constraints causes 3–5 styling rework rounds. A single design-source read up-front prevents them.
+
+The output of Phase 1 is a one-line **brand commitment**: "this app is X, so the new component must read as X." Skip Phase 1 only if the round is greenfield (no sibling components, no PNGs).
+
+## Phase 2: Detect stack and load the reference file
+
+Detect the host app's stack from the file paths in `files_to_modify`:
+
+| Signal | Stack | Reference to load |
+|--------|-------|-------------------|
+| `next.config.ts` near target + `*.module.scss` | Next.js + SCSS Modules | `references/nextjs-scss.md` |
+| `expo` in deps + `*.tsx` under `apps/mobile/` | React Native + Expo | `references/rn-expo.md` |
+| `tauri.conf.json` + React frontend | Tauri + React | `references/tauri-react.md` |
+
+Read the matching reference file with the Read tool — never paraphrase from memory. The reference encodes stack-idiomatic conventions (token usage, layout primitives, animation libraries, accessibility patterns).
+
+If the stack does NOT match any reference, surface to the user via `AskUserQuestion` before guessing — don't ship generic CSS that ignores the host app's idioms.
+
+## Phase 3: Commit to a direction
+
+Greenfield: pick a BOLD aesthetic direction (one extreme — brutally minimal, maximalist, editorial, brutalist, soft-pastel, industrial, etc.) and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality.
+
+Existing app: the direction is already chosen. Match it exactly. Match the established density, type contrast, motion vocabulary, colour weighting. New components that look "AI-default" because they ignored the existing aesthetic are the most common round-rework cause.
+
+Either way, write down the commitment in one sentence in the round notes: "Direction: {phrase}." This forces the choice to be conscious.
+
+## Phase 4: Universal aesthetics guidelines
+
+These apply regardless of stack. From Anthropic's frontend-design skill, adapted:
+
+- **Typography**: distinctive, not generic. Pair a display font with a refined body font. Avoid Arial / Roboto / Inter unless the existing design system mandates them.
+- **Colour & theme**: dominant colour with sharp accents beats a timid evenly-distributed palette. Use the design tokens.
+- **Motion**: high-impact moments over scattered micro-interactions. One well-orchestrated entrance with staggered reveals beats a hover-effect on every button.
+- **Spatial composition**: asymmetry, overlap, diagonal flow, grid-breaking. Generous negative space OR controlled density — pick.
+- **Backgrounds & visual details**: atmosphere and depth, not solid colours. Gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, grain overlays — when the aesthetic calls for it.
+
+Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code. Minimalist designs need restraint, precision, and careful spacing/typography.
+
+## Phase 5: What NEVER to ship
+
+- Generic AI defaults: Inter / Roboto / Arial / system-fonts when the design system has its own
+- Cliché schemes (purple gradients on white, neon teal accent on dark navy)
+- Predictable card-grid layouts when the design language is editorial
+- Cookie-cutter component patterns that ignore the surrounding aesthetic
+- "Safe" middle-ground choices that read as undecided
+- The same aesthetic across two unrelated components in the same round
+
+## Phase 6: Pre-write checklist
+
+Before writing the first character of UI / styling code, confirm:
+
+| Check | Pass condition |
+|-------|----------------|
+| Tokens located | Read tokens file path on disk |
+| Sibling components read | At least 2 reference components opened |
+| Stack reference loaded | One of `reference/*.md` read |
+| Design sources reviewed | PNG location checked, visual constraints extracted (or "no PNGs found" recorded) |
+| Direction committed | One-sentence aesthetic commitment written down |
+| Repo-specific rule constraints | Auto-loaded rules for the file paths checked |
+| Stack-specific rule constraints | See `reference/*.md` "Mandatory rules" sections |
+
+### Floating panel close-on-deselect (cross-stack)
+
+Any time a component declares `useState(false)` for a variable named `show*`, `open*`, `visible*`, or `expanded*` AND the component receives an `isSelected` / `isActive` prop:
+
+```tsx
+const [showPanel, setShowPanel] = useState(false);
+
+useEffect(() => {
+  if (!isSelected) setShowPanel(false);
+}, [isSelected]);
+```
+
+Adding the close-on-deselect effect at the moment the state is introduced is mandatory. Style toolbars, dropdowns, popovers, context menus, action sheets all share this lifecycle.
+
+Unit tests for floating panels MUST cover: panel shows when toggled with isSelected=true; panel hides when isSelected transitions true→false; panel state does NOT persist across select/deselect cycles.
+
+If any check fails, fix before proceeding to Step 3.
+
+## Output back to the round-executor
+
+After Phase 6, the executor proceeds to Step 3 with the brand commitment + stack reference + direction in working memory. Round-executor records `frontend_design_loaded: { stack, direction, tokens_path }` in `round.context` so `frontend-ui` (Step 3.8) and `cbp-improve-round` can verify the commitment was honoured.
+
+## Integration
+
+- **Loaded by**: `round-executor` Step 2.7 (mandatory when has_ui_work / UI-class files present)
+- **Reads**: tokens files, sibling components, `references/{stack}.md`, auto-loaded UI rules
+- **Writes**: nothing directly — output is in-memory direction + stack context for Step 3
+- **Pattern references** (consulted during Phase 1 sibling discovery and Phase 6 pre-write checks): `frontend-ui/reference/ui-layout-patterns.md`, `frontend-ui/reference/variant-defaults.md`, `frontend-ui/reference/ui-label-maps.md`
+- **Paired with (post-implementation)**: `frontend-ui` (visual self-review), `frontend-ux` (interaction self-review) — both invoked inline by `round-executor` Step 3.8. This skill prevents bad design; those skills catch what slipped through.

package/templates/skills/cbp-frontend-design/reference/nextjs-scss.md

@@ -0,0 +1,118 @@
+# Next.js + SCSS Modules — Stack Reference
+
+Loaded by `frontend-design` Phase 2 when the host app uses Next.js (App Router) with SCSS Modules. Applies to `codebyplan` (`apps/web`), `tarkur` (`apps/*/web`).
+
+## Tokens
+
+Single source of truth for design tokens — never hardcode colour, spacing, type, radius, shadow values in component SCSS:
+
+| Path pattern | Purpose |
+|--------------|---------|
+| `packages/design-tokens/src/tokens.scss` | Canonical SCSS tokens — colours, spacing scale, radii, shadows, motion |
+| `packages/design-tokens/src/tokens.ts` | TypeScript mirror for runtime token access |
+| `apps/*/src/styles/_layout.scss` | App-specific layout variables (navbar, sidebar widths) |
+| `apps/*/src/styles/_typography.scss` | Type scale + font-family vars |
+
+Read the tokens file on disk before writing any component's SCSS. If a colour or spacing isn't already a token, surface the gap — don't introduce a hex literal.
+
+## Layout primitives
+
+| Tool | Use for |
+|------|---------|
+| `fluid(min, max)` mixin | Responsive sizes that interpolate between viewport widths — fonts, padding, gap, navbar height, etc. |
+| `clamp(min, preferred, max)` | When `fluid` doesn't fit and you need browser-native interpolation |
+| CSS Grid | Page-level layout, dashboard regions |
+| Flexbox | Component-internal alignment |
+
+`fluid` is the strong default for any size that should respond to viewport. Hardcoded `rem` / `px` is a yellow flag — ask "should this scale?"
+
+## SCSS Modules conventions
+
+- **BEM modifiers** for variants: `.button--primary`, `.card--compact`. The variant resolver pattern (see `frontend-ui/reference/variant-defaults.md`) produces these class names.
+- **No global selectors** — always scoped via the module. Global resets live in `apps/*/src/app/globals.scss`.
+- **Composition over override** — prefer multiple small modules and `composes:` over `!important` or specificity wars.
+- **Co-locate styles** — `MyComponent.tsx` + `MyComponent.module.scss` in the same folder.
+
+## Mandatory rules to load alongside this reference
+
+When editing files matched here, these rules also apply:
+
+- `rules/api-route-auth-enforcement.md` — for any new route handler with auth surface
+- `rules/eslint-fix-scope.md` — never repo-wide `--fix`
+- `rules/lint-warnings-greenfield.md` — new ESLint configs ship with zero warnings
+
+Pattern references the executor consults when applicable (folded into the `frontend-ui` skill — see Step 3.8):
+
+- `frontend-ui/reference/ui-layout-patterns.md` — navbar height, focus-visible, z-index layering, fluid heights, logo overflow
+- `frontend-ui/reference/variant-defaults.md` — `createResolver`, `SIZE_VARIANTS`, `COLOR_VARIANTS`, `CUSTOM_VARIANTS`
+- `frontend-ui/reference/ui-label-maps.md` — humanising DB column names + enum values for user-facing UI
+
+## Fonts and typography
+
+The host app declares fonts via `next/font/google` or `next/font/local` in `app/layout.tsx`. Read it before adding new font imports — duplicate imports cost network round-trips and the font loader's optimisation goes through the existing declaration.
+
+For new pages, use the type scale defined in `_typography.scss`. New `font-size` literals are a yellow flag — match them to the scale or add a token.
+
+## Motion
+
+Prefer CSS-only motion for hover, focus, simple transitions. Reserve JS motion (Motion library / Framer Motion) for orchestrated multi-element entrances. Page-load entrance: stagger via CSS `animation-delay` on consecutive children.
+
+## Split-layer CSS components
+
+When a component renders an outer container `<div>` and an inner content `<div>`, properties MUST be assigned to the correct layer before coding starts.
+
+| Property class | Outer container | Inner content div |
+|----------------|-----------------|-------------------|
+| Background colour / image | YES | NO |
+| Borders + border-radius | YES | NO |
+| Grid placement (`gridColumn`) | YES | NO |
+| Drag transform (`CSS.Transform`) | YES | NO |
+| Flex layout (`display:flex`, `flexDirection`) | NO | YES |
+| Content alignment (`alignItems`, `justifyContent`) | NO | YES |
+| Text alignment (`textAlign`) | NO | YES |
+
+**Full-width children require `textAlign`**: when inner children span 100% width (block default), `alignItems` alone has no visible effect. Always pair horizontal alignment with `textAlign` for text content.
+
+**Function naming**: split-CSS utility functions name their target layer:
+- `blockContainerCSS()` — outer (background, borders, grid)
+- `blockContentAlignmentCSS()` — inner (flex, alignment, textAlign)
+
+A function named `blockStyleToCSS()` (singular) is a **red flag** — it implies both layers merged, which is wrong for split-layer components.
+
+**Planning hand-off**: when a task involves styling a component with outer + inner layers, the plan's `ui_ux_considerations` MUST include a "CSS layer contract" naming the outer + inner elements and their property assignments.
+
+## Pre-handoff checklist (Next.js-specific)
+
+Before marking a round complete on a Next.js app, verify these eight points:
+
+1. **External links**: every `<a>` with `href` starting with `http://` or `https://` has `target="_blank"` AND `rel="noopener noreferrer"`
+2. **Navigation landmarks**: every `<nav>` has `aria-label` identifying its purpose
+3. **Next.js metadata**: `app/layout.tsx` exports BOTH `export const metadata: Metadata = { ... }` (title + description minimum) AND `export const viewport: Viewport = { themeColor: [...] }` (required for PWA / mobile)
+4. **ESLint greenfield severity**: when `eslint.config.mjs` is new, ALL rules are `"error"`, not `"warn"` (per `lint-warnings-greenfield.md`)
+5. **Test assertions**: every unit test file contains at least one `expect(` call beyond `toBeInTheDocument()` smoke. A `render()` without `screen.getBy*` + `expect()` is a compile check, not a test
+6. **API route SDK imports**: any API route that imports an SDK requiring a runtime env var (`@vercel/blob`, `@supabase/ssr`, `stripe`) MUST export `export const dynamic = 'force-dynamic'` at the top of the file. Without it, Next.js static analysis runs at build time when the env var is absent and the build fails
+7. **Async client component test patterns**: when a component uses `useEffect` with `fetch`, every test assertion on state that depends on the fetch result MUST use `waitFor`. For accessible name resolution, `aria-label` overrides inner text — tests use `getByRole('link', { name: /aria-label-text/i })`, NOT `getByText` targeting `aria-hidden` inner text
+8. **Config file ESLint coverage**: when adding Vitest with `@typescript-eslint/parser` `projectService: true`, verify `vitest.config.ts` is in tsconfig `include` OR added to ESLint `ignores`. Without this, a parse error appears at lint time
+
+## Floating panel close-on-deselect
+
+See parent SKILL.md Phase 6 — applies to React floating panels (style toolbars, dropdowns, popovers, context menus). The `useEffect` close-on-deselect is mandatory at the moment the panel state is introduced.
+
+## Common defects this stack produces
+
+- Hardcoded hex colours instead of token variables
+- Margin / padding values that aren't on the spacing scale (e.g. `padding: 13px` when scale is 4 / 8 / 12 / 16)
+- `font-family: Inter` literal because the design tokens already declare a different display font
+- `z-index: 9999` without checking the layering rule in `frontend-ui/reference/ui-layout-patterns.md`
+- Missing `aria-label` on `<nav>` and missing `target="_blank" rel="noopener noreferrer"` on external `<a>`
+
+The pre-write checklist in the parent SKILL.md catches these. Run it.
+
+## Greenfield page or screen
+
+When a brand-new top-level page is added (no sibling page exists in this app yet):
+
+1. Pick the BOLD aesthetic direction per Phase 3 of the parent skill
+2. Set up the page-level layout primitives: hero zone, content rhythm, scroll-driven reveals
+3. Use the design tokens for everything; if a token is missing, add it to `packages/design-tokens` in the same round (don't fork it inline)
+4. One delight moment per page — use it where the user dwells longest, not where they bounce