codebyplan 1.13.49 → 1.13.51

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

@@ -1,122 +0,0 @@
-# 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

@@ -1,154 +0,0 @@
-# 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

@@ -1,111 +0,0 @@
-# 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-git-worktree-create/SKILL.md

@@ -1,199 +0,0 @@
----
-name: cbp-git-worktree-create
-description: Create git worktree with clean command setup and register in CodeByPlan
-argument-hint: <branch-name> e.g. codebyplan-app
-effort: low
----
-
-# Git Worktree Create
-
-Create a git worktree as a sibling folder and register it in CodeByPlan. The worktree gets its own full copy of `.claude/` files on disk (rules, skills, hooks, agents, context) — git deduplicates at the object level so there's no real cost.
-
-## Arguments
-
-`$ARGUMENTS`: branch name — becomes both the branch name and the folder name.
-
-Examples:
-- `codebyplan-app` → folder `../codebyplan-app/`, branch `codebyplan-app`
-- `codebyplan-package` → folder `../codebyplan-package/`, branch `codebyplan-package`
-
-## Prerequisites
-
-- Must run from the **main repo** (the non-worktree checkout)
-- Working tree should be clean
-- Branch should not already exist as a worktree
-- New branches are always rooted at `origin/{production}` (read from `.codebyplan/git.json`), independent of the main repo's currently checked-out branch
-
-## Instructions
-
-### Step 1: Verify Main Repo
-
-```bash
-MAIN_REPO="$(git rev-parse --show-toplevel)"
-```
-
-Verify this is the main repo (not itself a worktree):
-
-```bash
-git rev-parse --git-dir
-```
-
-If the result is a file (not `.git` directory), this is already a worktree. Stop:
-
-```
-## Error
-
-Run this command from the main repo, not from a worktree.
-Main repo: [path from git-common-dir parent]
-```
-
-### Step 2: Validate Arguments
-
-If `$ARGUMENTS` is empty, ask the user:
-
-```
-What should the worktree be called? (e.g. codebyplan-app)
-```
-
-Set:
-- `BRANCH_NAME` = `$ARGUMENTS`
-- `WORKTREE_PATH` = `$MAIN_REPO/../$BRANCH_NAME`
-
-### Step 3: Check for Conflicts
-
-Check if the worktree already exists:
-
-```bash
-git worktree list | grep "$BRANCH_NAME"
-```
-
-If it exists:
-```
-## Worktree Already Exists
-
-Branch `[name]` is already checked out at [path].
-
-Use `/cbp-git-worktree-remove [name]` to remove it first.
-```
-Stop here.
-
-Check if the folder already exists:
-
-```bash
-ls -d "$WORKTREE_PATH" 2>/dev/null
-```
-
-If it exists, stop and inform the user.
-
-### Step 4: Create Branch If Needed
-
-Resolve the production branch: read `.codebyplan/git.json` and take `branch_config.production` (fall back to `main` if the file or field is absent). Call this `$PRODUCTION`.
-
-Check if branch exists:
-
-```bash
-git branch --list "$BRANCH_NAME"
-```
-
-If branch does NOT exist, create it from the freshest production tip — **not** from the main repo's ambient HEAD (which is often a stale home branch such as `codebyplan-main`):
-
-```bash
-git fetch origin "$PRODUCTION" 2>/dev/null || true
-git branch "$BRANCH_NAME" "origin/$PRODUCTION"
-```
-
-This guarantees every worktree starts at `origin/{production}` regardless of which branch the main repo currently has checked out.
-
-### Step 5: Create Worktree
-
-```bash
-git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"
-```
-
-### Step 6: Set Up MCP Connection
-
-Copy `.mcp.json` from the main repo to the worktree. The file is committed and contains only the public MCP URL (no secret), so this is a plain `cp` — no path rewriting or key substitution needed:
-
-```bash
-cp "$MAIN_REPO/.mcp.json" "$WORKTREE_PATH/.mcp.json"
-```
-
-Expected shape (do NOT rewrite paths — this is remote HTTP):
-
-```json
-{
-  "mcpServers": {
-    "codebyplan": {
-      "type": "http",
-      "url": "https://mcp.codebyplan.com/mcp"
-    }
-  }
-}
-```
-
-### Step 7: Set Up Environment
-
-Copy `.env.local` from the main repo to the worktree (contains the app's environment variables such as Supabase keys and feature flags — MCP auth is OAuth Bearer handled by Claude Code, not a key in this file):
-
-```bash
-cp "$MAIN_REPO/.env.local" "$WORKTREE_PATH/.env.local"
-```
-
-Verify `.env.local` is already in `.gitignore` (it should be via `.env.local` pattern). If not, add it.
-
-Also copy the gitignored E2E credentials source (`.codebyplan/e2e.env`, referenced by `.codebyplan/e2e.json`) so the new worktree can run Playwright auth flows immediately:
-
-```bash
-mkdir -p "$WORKTREE_PATH/.codebyplan"
-if [ -f "$MAIN_REPO/.codebyplan/e2e.env" ]; then
-  cp "$MAIN_REPO/.codebyplan/e2e.env" "$WORKTREE_PATH/.codebyplan/e2e.env"
-fi
-```
-
-If the main repo has no `.codebyplan/e2e.env` yet, provision it after setup by running `codebyplan ports --path "$WORKTREE_PATH" --provision-e2e` (copies the canonical E2E vars from `apps/web/.env.local`). Pass `--path` BEFORE the boolean flag. `.codebyplan/e2e.env` is gitignored — never commit it.
-
-### Step 8: Push Branch
-
-```bash
-cd "$WORKTREE_PATH" && git push -u origin "$BRANCH_NAME"
-```
-
-### Step 9: Register Worktree and Write `.codebyplan/` Config
-
-Run `codebyplan worktree create "$BRANCH_NAME" --path "$WORKTREE_PATH"` and parse the JSON output (`{ worktree_files_written: boolean, mcp_registered: boolean, worktree_id?, warn? }`):
-
-- If `warn` is present: surface it as a non-blocking warning.
-- Save the returned `worktree_id` for reference (if present).
-
-The CLI atomically writes the `.codebyplan/` directory with per-concern config stubs and registers the worktree in the CodeByPlan database. The `.codebyplan/device.local.json` file is created by `npx codebyplan setup` on the device (gitignored). The `worktree_id` is never COMMITTED; it may be cached per-device in the gitignored `.codebyplan/worktree.local.json` (branch-keyed, re-derivable via `codebyplan resolve-worktree --cache`), otherwise resolved at runtime from the `(device_id, repo path, branch)` tuple via `npx codebyplan resolve-worktree`.
-
-No need to mark as `skip-worktree` — the committed files are merge-safe per CHK-108 and CHK-120.
-
-### Step 10: Show Result
-
-```
-## Worktree Created
-
-**Branch**: [branch-name]
-**Path**: [worktree-path]
-**Main repo**: [main-repo-path]
-**Base**: origin/[production] ([sha])
-**CodeByPlan**: Registered (worktree ID: [id])
-
-### Setup
-- MCP: connected (remote endpoint, OAuth Bearer)
-- `.claude/` files: full copy on disk (rules, skills, hooks, agents, context)
-
-### Next Steps
-- Open `[worktree-path]` in your editor
-- Run `/cbp-session-start` to begin working
-- Checkpoints can be assigned to this worktree via `worktree_id`
-
-### Existing Worktrees
-[output of git worktree list]
-```
-
-## Integration
-
-- **Related**: `/cbp-git-worktree-remove` (cleanup and deregister)
-- **CLI**: `codebyplan worktree create <name> --path <abs>` (Step 9 — writes `.codebyplan/` config and registers worktree)