codebyplan 1.5.1 → 1.8.0

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

package/templates/skills/cbp-frontend-design/reference/rn-expo.md

@@ -0,0 +1,101 @@
+# React Native + Expo — Stack Reference
+
+Loaded by `frontend-design` Phase 2 when the host app uses React Native + Expo.
+
+## Tokens
+
+Single source of truth — read before writing any component. Paths below assume an RN/Expo app under `<app>/` (typical convention is `apps/mobile/`); adjust for your repo structure:
+
+| Path pattern | Purpose |
+|--------------|---------|
+| `<app>/src/design-system/tokens.ts` | Colours, spacing scale, type scale, radii — TypeScript module |
+| `<app>/src/design-system/index.ts` | Re-exports of typed components (`<Text>`, `<Button>`, `<Card>`, etc.) |
+
+If your project maintains a generated tokens catalogue (a markdown listing of every token with its references), keep it under your repo's docs tree and read it before editing tokens.
+
+Always import tokens from the design-system module. Hardcoded colours / spacing in `StyleSheet.create` are a hard fail.
+
+## StyleSheet.create vs inline
+
+- **`StyleSheet.create`** for static styles known at module load. The platform memoizes — cheaper than inline.
+- **Inline `style={...}`** only for values that genuinely depend on props or runtime state. Three or more dynamic styles → extract a `useMemo` or computed style.
+- **Never object-spread inside `style`** in render hot paths — creates a new object every render and busts memoization downstream.
+
+## Layout primitives
+
+| Primitive | Use for |
+|-----------|---------|
+| `Flex` (custom wrapper if present) or `View` with `flex-direction` | All layout |
+| `useSafeAreaInsets()` from `react-native-safe-area-context` | Top / bottom padding to clear notches and gesture areas |
+| `ScrollView` / `FlatList` / `SectionList` | Lists — pick `FlatList` for >20 items, virtualisation matters |
+| `useWindowDimensions()` | Responsive logic — never `Dimensions.get` (doesn't update on rotate) |
+
+## Mandatory rules to load alongside this reference
+
+- `rules/react-native-render-purity.md` — render functions must be pure; no side effects
+- `rules/expo-router-navigation-methods.md` — `router.push` vs `router.replace` vs `router.back` semantics
+- `rules/tab-screen-form-state.md` — tab-screen state lifecycle
+- `rules/maestro-merged-a11y-labels.md` — Maestro flattens nested Text — accessibility labels must work on the merged surface
+- `rules/hermes-bundle-grep-false-negative.md` — verifying symbols in Hermes bytecode
+- `rules/auth-listener-lifecycle-cases.md` — auth-listener edge cases when changing UI that touches session state
+
+## Floating panel close-on-deselect
+
+Modals, action sheets, dropdowns, popovers, and bottom-sheets that respond to a parent's selection state MUST close when the parent is deselected:
+
+```tsx
+const [showSheet, setShowSheet] = useState(false);
+
+useEffect(() => {
+  if (!isSelected) setShowSheet(false);
+}, [isSelected]);
+```
+
+Add this `useEffect` at the moment the panel state is introduced — never as a follow-up. Unit tests MUST cover open-on-toggle, close-on-deselect, no-state-persist-across-cycles. Same pattern as the cross-stack rule in parent SKILL.md Phase 6.
+
+## Typography
+
+The design-system exports typed `<Text>` variants (`<Heading>`, `<BodyText>`, `<Caption>`, etc.). Never use bare `<Text>` in app code — always the variant. Variant choices are part of the type scale; introducing a new variant means updating the design-system module, not adding a one-off `fontSize` prop.
+
+## Motion
+
+- `react-native-reanimated` for any non-trivial motion (gestures, scroll-driven, layout animations)
+- `LayoutAnimation` for cheap layout transitions (list insert/remove)
+- Avoid `Animated` (legacy API) for new work
+- Respect `useReducedMotion()` — system-level accessibility setting
+
+## Accessibility
+
+- Every interactive element needs `accessibilityRole` and `accessibilityLabel`
+- For Text-on-Text composition, the merged label rule applies (see `maestro-merged-a11y-labels.md`)
+- Test labels in Maestro before assuming they work — the rendered tree differs from the JSX tree
+
+## Theming and dark mode
+
+If the design-system supports light/dark, use `useColorScheme()` + the typed token accessor. Never branch on a string at the component level — branch in the token resolver.
+
+## Platform-specific code
+
+`Platform.OS === 'ios'` branches are last resort. Prefer:
+- `*.ios.tsx` / `*.android.tsx` file split for substantial divergence
+- Style merging via design-system tokens for visual differences
+- The platform-specific ergonomic adjustments (haptics, gesture, haptic feedback) wrapped in design-system hooks
+
+## Common defects this stack produces
+
+- Hardcoded `#fff` / `#000` instead of `tokens.color.background` / `tokens.color.foreground`
+- Padding values not on the spacing scale (e.g. `padding: 13` when scale is 4 / 8 / 12 / 16 / 24)
+- Inline-style object that creates a new reference every render
+- Missing `accessibilityRole` on a `<Pressable>`
+- Forgetting `useSafeAreaInsets()` — content under the notch / gesture bar
+- Bare `<Text>` instead of the typed variant
+- `setState` inside render (impure render — see render-purity rule)
+
+## Greenfield screen
+
+When adding a brand-new top-level screen:
+
+1. Pick the aesthetic direction per Phase 3 of the parent skill — match the rest of the mobile app's vibe
+2. Use the typed component imports from `apps/mobile/src/design-system/`
+3. Wrap in the standard screen scaffold (header / safe-area / scroll behaviour) — find the nearest sibling screen and match its scaffold exactly
+4. Add a Maestro flow if the screen is part of a critical path (per `rules/maestro-coverage-required.md`)

package/templates/skills/cbp-frontend-design/reference/tauri-react.md

@@ -0,0 +1,82 @@
+# Tauri + React — Stack Reference
+
+Loaded by `frontend-design` Phase 2 when the host app is Tauri (Rust shell + React WebView frontend). Applies to `workbyplan` (`apps/desktop`), `codebyplan` (`apps/desktop`), and any future Tauri app.
+
+## Tokens
+
+| Path pattern | Purpose |
+|--------------|---------|
+| `apps/desktop/src/styles/tokens.scss` (or equivalent) | Colours, spacing, type — desktop-specific where the web tokens don't fit |
+| `packages/design-tokens/` | Shared with web if the repo has a sibling Next.js app |
+
+Tauri apps often need their own token layer because desktop chrome (window controls, drag regions, native-feel sizing) doesn't map cleanly onto web tokens. Read the desktop token file first; fall back to shared tokens for non-chrome elements.
+
+## Layout primitives
+
+Tauri renders React inside a native WebView, so the layout vocabulary is web (CSS Grid, Flexbox, SCSS Modules) — but the constraints are desktop:
+
+| Constraint | Implication |
+|------------|-------------|
+| Window resize | Layout must respond to small (~600×400) and large (~2560×1440) windows |
+| No mobile breakpoints | Skip RN-style breakpoint logic; design for desktop sizes |
+| Pointer + keyboard primary | Touch is rare; hover states matter; keyboard navigation is required |
+| Native menus + window controls | Don't reinvent in HTML — use the Tauri menu API |
+| Drag regions | Use `data-tauri-drag-region` attribute on the title-bar surface, not synthetic mouse events |
+
+## Mandatory rules to load alongside this reference
+
+- `rules/eslint-fix-scope.md` — same as web stack
+- `rules/lint-warnings-greenfield.md` — same as web stack
+- `rules/over-engineering-avoidance.md` — desktop apps tempt premature abstraction (custom theming engines, plugin systems) before there's product justification
+
+## Split-layer CSS components
+
+Tauri uses web CSS, so the split-layer contract from `reference/nextjs-scss.md` applies — outer container holds background / borders / grid placement; inner content holds flex / alignment / textAlign. Function naming `*ContainerCSS()` and `*ContentAlignmentCSS()` conveys layer intent. A merged `*StyleToCSS()` is a red flag.
+
+## Floating panel close-on-deselect
+
+Same pattern as parent SKILL.md Phase 6 — applies to context menus, dropdowns, sidebars that respond to selection state.
+
+## Typography
+
+Desktop apps have more vertical space than mobile but less than a desktop browser tab — type scales need to be denser than a marketing site, less dense than a CLI / IDE. Pair a UI-grade body font (system stack `-apple-system, "Segoe UI", system-ui` is acceptable here, even encouraged for native feel) with a distinctive display font for hero / headline surfaces only.
+
+## Motion
+
+CSS transitions for state changes (hover, focus, active). Avoid heavy JS motion libraries — Tauri WebView is performant but desktop users notice jank more than web users. Reserve animations for:
+- Window state transitions (minimize, restore)
+- Modal / panel reveal
+- List item enter/exit
+
+## Native shell integration
+
+Things that should NOT be done in CSS / React:
+
+- Window chrome drawing — use `tauri.conf.json` window decorations
+- Dock / system tray icons — Tauri APIs
+- Notification toasts — system notification API, not a React component
+- File-system pickers — Tauri dialog plugin
+
+## Accessibility
+
+WebView accessibility tree maps to platform AT (VoiceOver, NVDA, etc.) — same `aria-*` rules as web. Plus:
+- Keyboard navigation MUST work without mouse (every action needs a shortcut or tab path)
+- Focus rings must be visible — `outline: 2px solid` is fine; never `outline: none` without a `:focus-visible` replacement
+- Window controls must be reachable via keyboard
+
+## Common defects this stack produces
+
+- Reinventing window chrome in HTML when the Tauri config supports it
+- Designing only for the "default" window size and breaking when the user resizes
+- Using mobile breakpoints (e.g. `@media (max-width: 768px)`) — irrelevant for desktop apps
+- Skipping keyboard navigation because "users have a mouse"
+- Heavy bundle size from web-first libraries that don't pull their weight in a desktop context
+
+## Greenfield desktop screen
+
+When adding a new top-level screen:
+
+1. Read the design from Figma if provided — extract tokens (colour, spacing, type scale) NOT pixel measurements; see parent SKILL.md Phase 1 "Design source images" for the procedure
+2. Decide the resize behaviour up-front: fluid, breakpointed, or fixed-with-scroll
+3. Wire keyboard shortcuts in the same round (don't defer)
+4. Test the screen at three window sizes: minimum, default, maximum