T3-26.29 Prod Release

.claude/skills/build-block-from-figma/agents/accessibility-check.md

@@ -0,0 +1,95 @@
+# Accessibility Check Subagent
+
+This script is delegated from Phase 6 of the main SKILL.md.
+Run **only after** the visual comparison loop (Phase 5) is complete.
+
+---
+
+## Target
+
+**WCAG 2.2 AA** — full compliance.  No violations, no incomplete
+checks left unresolved.
+
+---
+
+## Tool
+
+Uses `@axe-core/playwright` (installed as a project dev dependency).
+Axe-core is injected into the page via Playwright MCP.
+
+---
+
+## Procedure
+
+1. **Navigate** to the preview URL using Playwright MCP.
+2. **Set viewport** to 1360 px wide (desktop) for the initial scan.
+3. **Inject and run axe-core** scoped to the block's root element:
+   ```js
+   const { AxeBuilder } = require('@axe-core/playwright');
+
+   const results = await new AxeBuilder({ page })
+     .include('.<block-name>')
+     .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
+     .analyze();
+   ```
+4. **Repeat** the scan at mobile viewport (375 px) to catch
+   responsive-specific issues (touch target sizes, focus visibility).
+
+---
+
+## Processing results
+
+### Violations (must fix)
+
+For each violation in `results.violations`:
+
+1. **Log** the rule ID, impact level, description, and affected nodes.
+2. **Fix** the violation:
+   - CSS issue (contrast, focus indicator, sizing) → update the block's
+     CSS file.
+   - HTML/DOM issue (missing alt text, incorrect ARIA, missing labels) →
+     update the block's JS file (JS is responsible for DOM manipulation at
+     init time).
+   - Authoring issue (e.g. missing alt text from authored content) → note
+     as an authoring concern but do not modify authored content.
+3. **Re-run** axe-core to confirm the fix.
+4. **Repeat** until zero violations.
+
+### Incomplete checks (review)
+
+For each item in `results.incomplete`:
+- Assess whether the block can resolve it or whether it requires manual
+  review (e.g. colour contrast on complex backgrounds).
+- If resolvable, fix it.  If not, document it in Obstacles Encountered.
+
+### Common block-level a11y issues to watch for
+
+- **Missing focus indicators** on interactive elements.
+- **Insufficient colour contrast** between text and background, especially
+  on dark/gradient backgrounds.
+- **Touch target size** — interactive elements must be at least 24×24 px
+  (WCAG 2.2 AA).
+- **Missing or decorative alt text** — `<img>` elements need appropriate
+  `alt` attributes; decorative images should have `alt=""` and
+  `aria-hidden="true"`.
+- **Heading hierarchy** — no skipped levels within the block's content.
+- **Keyboard navigation** — interactive elements must be reachable and
+  operable via keyboard.
+
+---
+
+## Iteration limits
+
+- Maximum **3 fix-and-rerun cycles**.
+- If violations persist after 3 cycles, document them and move on.
+
+---
+
+## Obstacles Encountered
+
+Compile and surface back to the main skill:
+
+- List of violations found and fixed (rule ID + description).
+- List of violations that could not be fixed, with explanation.
+- List of incomplete checks that require manual review.
+- Any authoring-level concerns (content the block cannot control).

.claude/skills/build-block-from-figma/agents/performance-check.md

@@ -0,0 +1,115 @@
+# Performance Check Subagent
+
+This script is delegated from Phase 7 of the main SKILL.md.
+Run **only after** the visual comparison loop (Phase 5) and the
+accessibility audit (Phase 6) are complete.
+
+---
+
+## Target thresholds
+
+| Metric | Target | Why it matters |
+|--------|--------|----------------|
+| **Overall score** | ≥ 90 | Composite performance health |
+| **LCP** | ≤ 2.5 s | Perceived load speed |
+| **CLS** | ≤ 0.1 | Layout stability |
+| **INP** | ≤ 200 ms | Responsiveness |
+| **TBT** | ≤ 200 ms | Main-thread availability |
+
+---
+
+## Tool
+
+Uses the `lighthouse` CLI executed via shell commands.
+
+---
+
+## Procedure
+
+1. **Run Lighthouse** against the preview URL:
+   ```bash
+   npx lighthouse <preview-url> \
+     --output=json \
+     --output-path=/tmp/lighthouse-report.json \
+     --chrome-flags="--headless --no-sandbox" \
+     --only-categories=performance
+   ```
+2. **Parse** the JSON output and extract:
+   - `categories.performance.score` × 100
+   - `audits['largest-contentful-paint'].numericValue` (ms)
+   - `audits['cumulative-layout-shift'].numericValue`
+   - `audits['total-blocking-time'].numericValue` (ms)
+   - `audits['interaction-to-next-paint'].numericValue` (ms, if available)
+3. **Assess** each metric against the target thresholds.
+
+---
+
+## LCP-specific assessment
+
+1. **Identify the LCP element** from the Lighthouse report:
+   `audits['largest-contentful-paint'].details`.
+2. **Check if the LCP element is inside the new block.**
+   - If yes, the block directly impacts LCP — assess whether block CSS or
+     JS is delaying the paint.
+   - If no, verify the block doesn't add blocking resources.
+3. **Common LCP pitfalls**:
+   - Synchronous JS running before block content is visible.
+   - CSS hiding content on initial load then revealing it with a transition.
+   - Large un-optimised images loaded eagerly above the fold (use
+     `createOptimizedPicture` from Milo instead of bare `<img>` tags).
+   - Web fonts blocking text rendering.
+
+---
+
+## What to check beyond Lighthouse
+
+Using Playwright MCP, also verify:
+
+1. **No render-blocking resources** — the block's CSS is loaded
+   asynchronously by the EDS framework (verify, don't assume).
+   The block's JS must not introduce synchronous `<script>` tags.
+2. **No excessive DOM size** — the block should not generate more DOM
+   nodes than necessary.
+3. **No unnecessary reflows** — if the block's JS modifies layout
+   properties, it must batch reads and writes.
+
+---
+
+## Regression detection
+
+If any metric is worse than the target threshold:
+
+1. Determine if the block is the cause — temporarily hide the block
+   (`display: none`) and re-run Lighthouse to get a baseline.
+2. If the block is the cause, identify the specific resource or code path.
+3. **Suggest fixes** but do not apply them automatically — performance
+   fixes may require architectural decisions.  Surface them to the user.
+
+---
+
+## Output format
+
+```
+Performance Report
+──────────────────
+Overall score:  XX / 100   [PASS/FAIL]
+LCP:            X.Xs       [PASS/FAIL]
+CLS:            X.XX       [PASS/FAIL]
+INP:            XXX ms     [PASS/FAIL] (or N/A)
+TBT:            XXX ms     [PASS/FAIL]
+
+LCP element:    <element description>
+LCP in block:   Yes / No
+```
+
+---
+
+## Obstacles Encountered
+
+Compile and surface back to the main skill:
+
+- Metrics that failed thresholds, with root cause analysis.
+- Whether the new block is the cause of any regression.
+- Suggested fixes for any performance issues.
+- Any measurement limitations (e.g. INP requires interaction, localhost
+  vs production differences).

.claude/skills/build-block-from-figma/agents/visual-comparison.md

@@ -0,0 +1,119 @@
+# Visual Comparison Subagent
+
+This script is delegated from Phase 5 of the main SKILL.md.
+Use **Playwright MCP** for all browser interactions.
+
+---
+
+## Viewport → width mapping
+
+| Viewport | Playwright width | Figma input |
+|----------|-----------------|-------------|
+| Mobile | 375 px | Figma Mobile URL |
+| Tablet | 1024 px | Figma Tablet URL |
+| Desktop | 1360 px | Figma Desktop URL |
+
+Only test viewports for which a Figma frame was provided.
+
+---
+
+## Comparison procedure (per breakpoint)
+
+For each breakpoint:
+
+1. **Navigate** to the preview URL.
+2. **Set viewport width** to the value from the table above.
+   Set height to a generous value (e.g. 900 px) to avoid scroll clipping.
+3. **Wait** for the block to finish rendering — wait for the block's root
+   element to be visible and for any images inside it to load.
+4. **Screenshot** the block's bounding box (not the full page).
+   Use Playwright's element screenshot to capture just the component.
+5. **Load the cached Figma frame** for this breakpoint from
+   `/tmp/build-block-figma/<viewport>.png` (saved during Phase 3).
+   Do **not** re-fetch from the Figma MCP — the cached file is the source of
+   truth.  If the cache file is missing for a breakpoint, skip that breakpoint
+   and document it in Obstacles Encountered.
+6. **Compare** the screenshot against the Figma frame.
+
+---
+
+## What to assess
+
+For each breakpoint, evaluate:
+
+### Layout & stacking
+- Are elements stacked vertically vs placed side-by-side correctly?
+  This is the most common error — if Figma shows mobile stacking with
+  heading above image, the implementation must match, not place them in a row.
+- Flex/grid direction, wrapping, and alignment.
+- Element ordering matches Figma layer order.
+
+### Spacing
+- Padding, margins, and gaps between elements.
+- Spacing between the block and its container edges.
+- Spacing between text elements (heading → body → CTA).
+
+### Typography
+- Font size, weight, and line height are visually consistent.
+- Heading vs body font family is correct.
+- Text colour matches the design.
+
+### Colours & backgrounds
+- Background colours, gradients, or images match Figma.
+- Foreground element colours (text, icons, borders) match.
+- Verify colours against `--color-*` CSS tokens.
+
+### Media
+- **Element presence check (critical)**: cross-reference the per-breakpoint
+  element inventory from Phase 3.  If an image or media element exists in
+  the Figma frame for this breakpoint, it **must** be visible in the
+  implementation screenshot.  A missing image at tablet/desktop when it
+  exists at mobile is the most common failure — flag this immediately.
+- Images are positioned correctly relative to text content.
+- Image aspect ratios are preserved.
+- Image sizing fills or fits the container as shown in Figma.
+
+### Overall fidelity
+- The implementation looks like the Figma design at a glance.
+- No missing elements, no extra elements.
+- No overflow or clipping issues.
+
+---
+
+## Iteration loop
+
+If a breakpoint differs meaningfully from the Figma design:
+
+1. **Identify** the specific CSS properties causing the discrepancy.
+   Be precise — e.g. "the flex-direction should be column on mobile but is
+   currently row" or "the gap between heading and body is 8px but Figma
+   shows 24px (--spacing-m)".
+2. **Update** the local CSS file (and JS if DOM restructuring is needed).
+3. **Make changes visible**:
+   - **Localhost mode:** reload the page in Playwright.
+   - **Remote-branch-mode:** the main skill (Phase 5d) handles pushing
+     updated files to the feature branch and force-refreshing the CDN via
+     `?eventlibs=<branch-name>`.  Follow those instructions rather than
+     simply reloading.
+4. **Re-screenshot** and **re-assess** the breakpoint.
+5. **Repeat** until fidelity is high.
+
+### Iteration limits
+
+- Maximum **5 passes** per breakpoint.
+- If after 5 passes there are still discrepancies, **stop iterating** and
+  document the remaining issues in the **Obstacles Encountered** section.
+
+---
+
+## Obstacles Encountered
+
+At the end of the visual comparison phase, compile a list of:
+
+- Breakpoints that reached high fidelity (pass).
+- Breakpoints that still have discrepancies after 5 passes, with specific
+  details of what differs and which CSS properties were attempted.
+- Any Figma ambiguities (e.g. unclear auto-layout settings, unusual spacing
+  that doesn't match any token).
+
+Surface this list back to the main skill for inclusion in the final summary.