codebyplan 1.5.1 → 1.9.0

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

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`).