@arbor-education/design-system.components 0.10.0 → 0.11.1

package/.claude/skills/map-legacy/README.md

@@ -0,0 +1,87 @@
+# Map Legacy Skill
+
+AROOOOO HUNNI!! 🐺💪 This BOMBASS skill takes a screenshot of an existing page built with legacy components and maps every element to its Arbor design system equivalent! xxx
+
+## What It Does
+
+Produces a **migration map** for an existing legacy page — showing which Arbor components replace which legacy ones, how complex each swap is, and what gaps remain.
+
+**The key insight:** This skill focuses on **functional equivalence**, not visual similarity. A legacy data grid and our `Table` component may look completely different, but they serve the same purpose — and that makes it a valid migration target.
+
+## Usage
+
+```bash
+/map-legacy /path/to/screenshot.png
+```
+
+Or with a description if no screenshot is available:
+
+```bash
+/map-legacy "student dashboard with a data table, breadcrumb nav, and form"
+```
+
+## What You Get
+
+A migration report at `.claude/migration-report-{page-name}-{date}.md` containing:
+
+- **Migration map table** — every legacy element → Arbor equivalent at a glance
+- **Element-by-element breakdown** — detailed analysis with prop mappings and gotchas
+- **Complexity ratings** — 🟢 Low / 🟡 Medium / 🔴 High / ❌ No equivalent
+- **Recommended migration order** — start with easy wins, tackle heavy lifting last
+- **Gaps** — legacy elements with no Arbor equivalent (flagged for new component work)
+
+## Complexity Ratings
+
+| Rating | Meaning |
+|---|---|
+| 🟢 **Low** | Direct swap — prop names may differ but same data shape, trivial to migrate |
+| 🟡 **Medium** | Same purpose but different API — some refactoring, adapter code, or config needed |
+| 🔴 **High** | Significant behavioral differences — complex config, data transformation, or model changes |
+| ❌ **No equivalent** | Nothing in Arbor covers this — needs placeholder SVG or new component |
+
+## How It Differs From `/analyze-design`
+
+| | `/analyze-design` | `/map-legacy` |
+|---|---|---|
+| **Input** | Figma URL or screenshot | Screenshot of existing page |
+| **Question asked** | "Can we build this?" | "What replaces what we have?" |
+| **Focus** | Does a component EXIST? | Is this component EQUIVALENT? |
+| **Output** | Feasibility report | Migration map |
+| **Use case** | Building from Figma | Modernising existing pages |
+
+## The Golden Girls
+
+This skill uses BOTH mandatory agents:
+
+- 👜 **Sophia Componentspert** — identifies Arbor equivalents for each legacy element
+- 🔍 **Dorothy Fact-Checker** — verifies Sophia's claims against actual source code
+
+Sophia without Dorothy = unverified claims. Both are required. AROOOOO!! 🐺
+
+## After the Migration Map
+
+Once you have the map, use `/create-page` with the Figma design (or the migration map as a guide) to actually build the modernised page using Arbor components.
+
+Elements with **No equivalent** get **placeholder SVGs** (see create-page skill for the pattern) and generate tickets for new component work.
+
+## Example Output
+
+```
+📊 Migration score: 14 out of 18 elements have direct Arbor equivalents!
+
+🟢 Easy wins: buttons, inputs, dividers, panel headers
+🟡 Some work: data grid, modal, tag colour system
+🔴 Heavy lifting: custom drag-sort table
+❌ Gaps: breadcrumb nav, timetable widget
+
+📄 Full report: .claude/migration-report-student-dashboard-2026-02-19.md
+🏁 Start here: the buttons and inputs — quick wins before tackling the grid
+```
+
+## Notes
+
+- This is a **MAP**, not a build — use `/create-page` when ready to actually implement
+- **Functional equivalence** is the measure, not visual similarity
+- Gaps are **useful data** for the component roadmap, not failures
+- Dorothy's fact-checking prevents starting migration on false assumptions
+- AROOO like you mean it! 🐺💪

package/.claude/skills/map-legacy/SKILL.md

@@ -0,0 +1,465 @@
+---
+name: map-legacy
+description: Analyze a screenshot of an existing legacy page and map its old components to their Arbor design system equivalents. Produces a migration report showing old→new component mappings, prop translations, complexity ratings, and gaps.
+---
+
+# Map Legacy Page to Arbor Components
+
+AROOOOO HUNNI!! 🐺 Time to drag those HEINOUS legacy components into the light and find their BODACIOUS Arbor replacements!! xxx
+
+## Goal
+
+Analyze a screenshot of an **existing page built with legacy components** and produce a **migration map** — a report showing exactly which Arbor components can replace each legacy element, how complex the migration is, and what gaps remain.
+
+**This is NOT a fresh build assessment.** The question is not "can we build this?" — it's "what replaces what we already have?"
+
+**CRITICAL PRINCIPLE — Functional Equivalence Over Visual Similarity:**
+- A legacy data grid and our `Table` component may look different but ARE equivalent
+- A legacy modal and our `Modal` component serve the same purpose even if the API differs
+- Focus on WHAT THE COMPONENT DOES, not just what it looks like
+- Even if the new component looks different, if it covers the use case → it's a valid replacement
+
+## The Golden Girls Team — MANDATORY COLLABORATORS
+
+- 👜 **Sophia Componentspert** (`sophia-componentspert`) — MANDATORY at Step 4. She maps legacy patterns to Arbor equivalents.
+- 🔍 **Dorothy Fact-Checker** (`dorothy-fact-checker`) — MANDATORY at Step 5. She verifies Sophia's Arbor claims against actual source code.
+
+**RULE**: You MUST call BOTH agents. Sophia without Dorothy = unverified claims. Skipping either = MOST HEINOUS failure. AROOOOO!! 🐺💪
+
+## Input
+
+Screenshot path or description provided: `$ARGUMENTS`
+
+## Process
+
+### 1. Determine Input Type
+
+- **File path** (e.g. `/path/to/screenshot.png`) — use `Read` tool to load the image
+- **No path yet** — ask the user to provide a screenshot path or paste a description of the page
+
+### 2. Read the Screenshot
+
+Use the `Read` tool on the screenshot path. Claude Code is multimodal — you will SEE the page visually.
+
+```
+Read tool: file_path="<path-to-screenshot>"
+```
+
+Study the image carefully. You're looking at a REAL page that was built with legacy components. Every UI element you can see is something that needs a migration decision.
+
+### 3. Catalog Legacy UI Elements
+
+Go section by section through the page. For each distinct UI element, note:
+
+- **What it looks like** (visual description)
+- **What it does** (functional purpose — this is the key!)
+- **Where it appears** (which section of the page)
+- **Approximate count** (e.g. "3 instances of this pattern")
+
+Be THOROUGH. Common legacy patterns to look for:
+
+**Data display:**
+- Data tables / grids (sortable columns, pagination, row actions)
+- Key-value / label-value rows (read-only property lists)
+- Cards and panels
+- Stats / KPI displays
+- Tags, badges, status indicators
+
+**Navigation:**
+- Breadcrumbs
+- Tab bars
+- Side navigation (icon and/or text variants)
+- Top navigation bar
+- Pagination controls
+
+**Forms & inputs:**
+- Text inputs, textareas, number inputs
+- Select / dropdown inputs
+- Radio buttons, checkboxes
+- Date pickers
+- Search bars
+
+**Actions:**
+- Primary / secondary / tertiary buttons
+- Icon buttons
+- Dropdown action menus (e.g. "Actions ▼")
+- Split buttons
+
+**Overlays:**
+- Modals / dialogs
+- Slide-out panels / drawers
+- Tooltips
+- Popovers
+
+**Layout:**
+- Section/panel headers with optional actions
+- Collapsible sections
+- Dividers / separators
+- Page header with title and CTA
+
+**Feedback:**
+- Alert / notification banners
+- Empty states
+- Loading states / spinners
+
+Also note anything that looks **completely custom** or **one-of-a-kind** — these are your gap candidates.
+
+### 4. Read Available Arbor Components
+
+Before calling Sophia, read the public API so you both know exactly what's available:
+
+```
+Read tool: file_path="src/index.ts"
+```
+
+### ⚡ MANDATORY STEP 4 — CALL SOPHIA COMPONENTSPERT NOW ⚡
+
+**YOU MUST USE THE `Task` tool RIGHT NOW.** Do NOT attempt the mapping yourself. Sophia knows this library inside out. Let her do the expert work.
+
+```
+Task tool: subagent_type="sophia-componentspert"
+prompt: "I'm migrating a legacy page to Arbor components. I need you to map each legacy UI element to its best Arbor equivalent.
+
+IMPORTANT PRINCIPLE: Focus on FUNCTIONAL EQUIVALENCE, not visual similarity. Even if the new component looks different, if it covers the same use case it's a valid replacement.
+
+LEGACY UI ELEMENTS IDENTIFIED:
+[List every element you catalogued in step 3, with its functional description]
+
+AVAILABLE ARBOR COMPONENTS (from src/index.ts):
+[List all components from src/index.ts]
+
+For each legacy element, please provide:
+
+1. **Arbor equivalent** — which component(s) to use (or NONE if nothing fits)
+2. **Migration complexity** — Low / Medium / High with reasoning:
+   - LOW: Direct swap, same API shape, minimal code changes
+   - MEDIUM: Similar purpose but different API, some refactoring needed
+   - HIGH: Significant behavioral differences, data transformation, or multiple components needed
+3. **Key prop mappings** — what old props map to what new props (best guess)
+4. **Feature gaps** — anything the legacy component did that Arbor component can't do yet
+5. **Migration notes** — any gotchas, behavioral differences, or things to watch out for
+
+Also identify any elements with NO Arbor equivalent (will need placeholder SVGs or new component builds).
+
+Be specific about component APIs. Don't guess — if you're unsure about a prop, say so."
+```
+
+**WAIT for Sophia's response.** Her mapping is the core of this skill.
+
+After Sophia responds, **relay her key findings to the user:**
+
+> 👜 **Sophia says:** _[Sophia's overall take — how mappable is this page? Any surprises? Relay in her warm, knowledgeable, Sicilian-grandmother voice]_
+
+### ⚡ MANDATORY STEP 5 — CALL DOROTHY FACT-CHECKER NOW ⚡
+
+**YOU MUST USE THE `Task` tool RIGHT NOW.** Sophia can hallucinate props. Dorothy reads the actual source files to verify EVERY claim.
+
+```
+Task tool: subagent_type="dorothy-fact-checker"
+prompt: "Sophia just mapped legacy UI elements to Arbor components for a migration project. I need you to FACT-CHECK her component capability claims.
+
+SOPHIA'S CLAIMS TO VERIFY:
+[List each legacy element → Arbor component mapping Sophia recommended, with the specific props/features she claimed the Arbor component supports]
+
+YOUR TASK:
+1. Read src/index.ts to confirm what's exported
+2. Read the actual component files for each component Sophia mentioned
+3. For each mapping, verify:
+   - Does the Arbor component exist?
+   - Does it actually support the features/props needed for this migration?
+   - Are there capability gaps Sophia missed or overstated?
+   - Is the migration complexity rating accurate given the actual API?
+4. Flag any hallucinated props or overstated capabilities
+5. Provide CORRECTED complexity ratings where needed
+6. List every source file you read
+
+BE BRUTALLY HONEST. If an Arbor component can't cover what the legacy component did, the migration team needs to know BEFORE they start rewriting code."
+```
+
+**WAIT for Dorothy's response.** Use her CORRECTED information — not Sophia's original if Dorothy found errors.
+
+### 6. Generate Migration Report
+
+Using Sophia's mapping AND Dorothy's corrections, write a comprehensive migration report.
+
+**CRITICAL — PRESERVE SOPHIA'S VOICE IN THE REPORT:**
+
+Sophia's responses contain Sicily anecdotes, "listen pussycat" warnings, and conversational asides that carry REAL information — gotchas, nuances, and migration pitfalls wrapped in personality. Do NOT strip these out into dry bullet points. The migration report should read like Sophia wrote it. Her warmth is not decoration; it's context.
+
+**Rules for preserving Sophia's voice:**
+- Include her Sicily/family anecdotes verbatim (or near-verbatim) — they exist to make concepts memorable
+- Include her specific warnings in her own words (e.g. "do NOT use Section as a nav sidebar — I have seen people try. It ends badly.")
+- Use conversational section intros in her voice, not just bare headings and tables
+- Dorothy's corrections can be integrated as annotations: "_(Dorothy verified: confirmed)_" or "_(Dorothy corrected: actual prop is X)_"
+- The report should be something a developer enjoys reading, not just a reference doc
+
+**Report file naming:**
+`.claude/migration-report-{page-name}-{date}.md`
+e.g. `.claude/migration-report-student-profile-2026-02-19.md`
+
+**Report structure:**
+
+```markdown
+# Legacy Migration Report
+## Page: [Page name / description]
+**Mapped by:** Sophia Petrillo, Componentspert
+**Verified by:** Dorothy Zbornak, QA Expert
+**Date:** [date]
+**Screenshot:** [path if provided]
+
+---
+
+## TL;DR
+
+[2-3 sentence summary in Sophia's voice: how many elements mapped cleanly, how many need work, any major gaps. Include her overall take.]
+
+**Migration readiness: X/Y elements have direct Arbor equivalents**
+
+---
+
+## Migration Map
+
+| Legacy Element | Where | Arbor Component | Complexity | Status |
+|---|---|---|---|---|
+| Old data grid | Main content | `Table` | Medium | ✅ Mappable |
+| Legacy breadcrumb | Page header | `Breadcrumbs` | Low | ❌ Not in library yet |
+| Custom modal | Various | `Modal` | Low | ✅ Mappable |
+| ... | ... | ... | ... | ... |
+
+---
+
+## Element-by-Element Breakdown
+
+[Write this section in Sophia's voice — introduce each group of elements conversationally before the technical detail]
+
+### [Legacy Element Name]
+
+[Optional Sophia intro — e.g. "Picture it: Sicily, 1948. We had three buckets..." — if she included an anecdote for this element, KEEP IT]
+
+**What it does:** [Functional description]
+**Where it appears:** [Location on page]
+**Arbor replacement:** `ComponentName` (`path/to/Component.tsx`)
+**Migration complexity:** Low / Medium / High
+
+**Why this replacement works:**
+[In Sophia's voice where she explained equivalence]
+
+**Prop mapping:**
+| Legacy prop | Arbor prop | Notes |
+|---|---|---|
+| `data` | `rowData` | Same shape |
+| `onRowClick` | `onRowClicked` | Same signature |
+
+**Key differences to handle:**
+- [Include Sophia's specific warnings verbatim where she flagged gotchas]
+- [Behavioral difference]
+
+**Feature gaps (if any):**
+- [Feature legacy component had that Arbor doesn't]
+
+_(Dorothy verified: [brief Dorothy confirmation or correction])_
+
+---
+
+[Repeat for each element]
+
+---
+
+## Elements With No Arbor Equivalent
+
+These need either:
+a) A **placeholder SVG** (for page builds using `/create-page`)
+b) A **new component** to be built in the design system
+
+| Legacy Element | Why Nothing Fits | Suggested New Component | Priority |
+|---|---|---|---|
+| Custom timeline | No timeline component | `Timeline` | Medium |
+| ... | ... | ... | ... |
+
+---
+
+## Migration Complexity Summary
+
+| Complexity | Count | Elements |
+|---|---|---|
+| 🟢 Low | X | List them |
+| 🟡 Medium | Y | List them |
+| 🔴 High | Z | List them |
+| ❌ No equivalent | W | List them |
+
+---
+
+## Recommended Migration Order
+
+[Sophia's recommended sequence in her voice — she usually has an opinion about where to start]
+
+1. **Start with Low complexity** — direct swaps, quick wins, build confidence
+2. **Then Medium complexity** — similar purpose, some refactoring
+3. **High complexity last** — tackle when the rest is stable
+4. **Gaps** — flag for component team, use placeholders in the meantime
+
+### Suggested sequence:
+1. [Element] → `[Component]` — [why first]
+2. [Element] → `[Component]` — [why second]
+...
+
+---
+
+## What This Migration Will NOT Change
+
+Things that stay the same regardless of component swap:
+- Business logic and data fetching
+- Routing
+- State management patterns
+- [Any other app-level concerns]
+
+---
+
+## Appendix: Files Dorothy Verified
+
+[List every source file Dorothy read — proves the assessment is grounded in real code]
+
+- `src/index.ts`
+- `src/components/button/Button.tsx`
+- ...
+```
+
+### 7. Write the Report
+
+```
+Write tool:
+  file_path: ".claude/migration-report-{page-name}-{date}.md"
+  content: [generated report]
+```
+
+### 8. Present Summary to User
+
+Share Sophia AND Dorothy's combined wisdom:
+
+> 👜 **Sophia says:** _[Overall migration outlook in her warm voice]_
+
+Then provide:
+1. 📊 **Migration score**: "X out of Y elements have direct Arbor equivalents"
+2. 🟢 **Easy wins** (Low complexity): List them
+3. 🟡 **Some work needed** (Medium): List them
+4. 🔴 **Heavy lifting** (High): List them
+5. ❌ **Gaps** (No equivalent): List them
+6. 📄 **Report location**: Path to the generated markdown file
+7. 🏁 **Recommended first step**: The single best place to start the migration
+
+---
+
+## Key Principles to Keep in Mind
+
+### Functional Equivalence is Everything
+
+A legacy `<OldTable data={rows} cols={cols} />` and our `<Table rowData={rows} columnDefs={cols} />` are functionally equivalent even though:
+- The prop names are different
+- The visual styling differs
+- The internal implementation is completely different
+
+The migration question is: **does the new component cover the use case?** Not "does it look the same?"
+
+### Complexity Ratings Guide
+
+**🟢 LOW** — Direct swap:
+- Same purpose, similar API shape
+- Prop names may differ but same data
+- Styling differences handled by design tokens
+- Example: `<OldButton type="primary">` → `<Button variant="primary">`
+
+**🟡 MEDIUM** — Refactoring needed:
+- Same purpose but meaningfully different API
+- May need data transformation or adapter code
+- Some behavioral differences to handle
+- Example: Legacy self-managed form → `FormField` (self-contained with label + input)
+
+**🔴 HIGH** — Significant work:
+- Similar purpose but very different model (e.g. uncontrolled → controlled)
+- Multiple legacy components collapse into one Arbor component (or vice versa)
+- Complex behavioral differences (e.g. legacy virtual scroll vs AG Grid)
+- Example: Custom drag-and-drop table → `Table` with AG Grid row dragging config
+
+**❌ NO EQUIVALENT** — Gap:
+- Nothing in Arbor covers this use case
+- Use placeholder SVG in page builds
+- Needs a ticket for new component development
+
+### What to Do With Gaps in Page Builds
+
+For elements with no Arbor equivalent, the `/create-page` skill's **placeholder SVG pattern** applies:
+
+```tsx
+{/*
+  ⚠️ MISSING COMPONENT PLACEHOLDER
+  Component: [LegacyComponentName replacement]
+  Reason: No Arbor equivalent for this legacy element.
+  TODO: Replace once [NewComponentName] is built.
+*/}
+<svg
+  role="img"
+  aria-label="[ComponentName] placeholder - component not yet available in design system"
+  width="100%"
+  height={approximateHeight}
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <rect width="100%" height="100%" fill="#f5f5f5" rx="4" />
+  <rect x="2" y="2" width="calc(100% - 4px)" height={approximateHeight - 4}
+    fill="none" stroke="#cccccc" strokeWidth="2" strokeDasharray="8 4" rx="3" />
+  <text x="50%" y="42%" textAnchor="middle" dominantBaseline="middle"
+    fill="#888888" fontSize="13" fontWeight="600" fontFamily="sans-serif">
+    [ComponentName]
+  </text>
+  <text x="50%" y="65%" textAnchor="middle" dominantBaseline="middle"
+    fill="#aaaaaa" fontSize="11" fontFamily="sans-serif">
+    Component not yet available in design system
+  </text>
+</svg>
+```
+
+---
+
+## Example Output
+
+```
+AROOOOO HUNNI! 🐺 Sophia and Dorothy have mapped that legacy page! xxx
+
+📊 Migration score: 14 out of 18 elements have direct Arbor equivalents!
+
+🟢 Easy wins (Low complexity — just swap them):
+- Legacy buttons → Button (variant prop differs, trivial)
+- Old text inputs → FormField + TextInput
+- Custom dividers → Separator
+- Panel headers → Section
+
+🟡 Some work needed (Medium):
+- Legacy data grid → Table (prop renaming + AG Grid config)
+- Old modal → Modal (API shape differs, need adapter)
+- Legacy tags → Tag (color system differs, needs mapping)
+
+🔴 Heavy lifting (High):
+- Custom drag-sort table → Table with AG Grid row drag (complex config)
+
+❌ Gaps (no Arbor equivalent — placeholder SVGs):
+- Legacy breadcrumb nav → no Breadcrumbs component yet
+- Custom timetable widget → no WeeklySchedule component yet
+
+📄 Full report: .claude/migration-report-student-dashboard-2026-02-19.md
+
+🏁 Start here: The buttons and text inputs — pure Low complexity, gets your
+   team familiar with the Arbor API before tackling the data grid migration.
+```
+
+---
+
+## Important Notes
+
+- **Functional equivalence is the goal** — don't let visual differences fool you
+- **Dorothy is essential** — Sophia can overstate Arbor component capabilities
+- **Complexity ratings are honest** — don't downplay High just to seem optimistic
+- **Gaps are useful data** — knowing what's missing guides the component roadmap
+- **This is a MAP, not a build** — use `/create-page` when you're ready to actually build
+- This codebase serves millions of users — accurate migration assessments matter!
+- Use yarn (NOT npm)
+
+AROOOOO LET'S DRAG THOSE HEINOUS LEGACY COMPONENTS INTO THE LIGHT, HUNNI!! xxx 💪🏍️✨🐺

package/.claude/skills/migrate-page/README.md

@@ -0,0 +1,125 @@
+# Migrate Page Skill
+
+AROOOOO HUNNI!! 🐺💪 This BOMBASS skill takes a migration report from `/map-legacy` and builds a production-ready React page that replaces the legacy implementation with Arbor components! xxx
+
+## What It Does
+
+Takes the verified migration map that Sophia and Dorothy already produced, and turns it into **actual code** — TSX, SCSS, tests, and Storybook stories.
+
+**The key insight:** The migration report already has the hard thinking done. This skill trusts that work and focuses purely on building — no re-researching components, no second-guessing the map.
+
+## Usage
+
+```bash
+# Best case — provide both
+/migrate-page /path/to/screenshot.png .claude/migration-report-custom-report-writer-2026-02-19.md
+
+# Screenshot only — auto-runs /map-legacy first
+/migrate-page /path/to/screenshot.png
+
+# Report only — no visual reference
+/migrate-page .claude/migration-report-custom-report-writer-2026-02-19.md
+```
+
+## What You Get
+
+A production-ready page at `src/pages/{pageName}/` containing:
+
+- **`{PageName}.tsx`** — React page composed from Arbor components, following the migration map exactly
+- **`{pageName}.scss`** — Styles using design tokens (Blanche-reviewed)
+- **`{PageName}.test.tsx`** — Full test coverage (Dorothy-verified)
+- **`{PageName}.stories.tsx`** — Storybook stories (Rose-crafted)
+- **Export added** to `src/index.ts`
+
+## The Pipeline
+
+```
+/map-legacy screenshot.png
+    → .claude/migration-report-{page}-{date}.md
+         (Sophia maps, Dorothy verifies)
+
+/migrate-page screenshot.png report.md
+    → reads the report
+    → builds the page
+    → Blanche reviews SCSS
+    → Rose writes stories
+    → Dorothy does final QA
+    → production-ready page
+```
+
+## How It Differs from `/create-page`
+
+| | `/create-page` | `/migrate-page` |
+|---|---|---|
+| **Input** | Figma URL | Screenshot + migration report |
+| **Pre-flight** | Runs `analyze-design` | Reads migration report |
+| **Visual ref** | Figma design | Legacy page screenshot |
+| **Sophia/Dorothy** | Called live | NOT called (trust the report) |
+| **Intent** | Build something new | Replace something existing |
+
+## The Golden Girls
+
+This skill uses THREE mandatory agents (not all four — Sophia and Dorothy already ran in `/map-legacy`):
+
+- 💄 **Blanche Designspert** — Reviews SCSS for correct token usage and naming conventions
+- 🌹 **Rose Storybookspert** — Writes comprehensive Storybook stories
+- 🔍 **Dorothy Fact-Checker** — Final QA on generated files (not component capabilities)
+
+Skipping any of them = MOST HEINOUS. AROOOOO!! 🐺
+
+## Placeholder SVGs
+
+Every element from the migration report marked ❌ (no Arbor equivalent) gets a placeholder SVG:
+
+```tsx
+{/* ⚠️ MISSING COMPONENT PLACEHOLDER — TODO: Replace once Breadcrumbs is built */}
+<svg role="img" aria-label="Breadcrumbs placeholder - component not yet available in design system" ...>
+```
+
+Placeholders are:
+- Accessible (`role="img"` + `aria-label`)
+- Testable (`getByRole('img', { name: /Breadcrumbs placeholder/i })`)
+- Visually obvious in Storybook (dashed border)
+- Clearly documented with TODO comments
+
+## Example Output
+
+```
+AROOOOO HUNNI! 🐺 That legacy page has been BODACIOUSLY MIGRATED! xxx
+
+✅ Files created:
+  - src/pages/customReportWriterPage/CustomReportWriterPage.tsx
+  - src/pages/customReportWriterPage/customReportWriterPage.scss
+  - src/pages/customReportWriterPage/CustomReportWriterPage.test.tsx
+  - src/pages/customReportWriterPage/CustomReportWriterPage.stories.tsx
+
+✅ Migration map followed:
+  - Heading → Heading level={1}
+  - Create New Report → Button variant="primary"
+  - Tabs → Tabs + Tabs.Item
+  - Data table → Table (AG Grid) with full columnDefs
+  - Bulk action → Table.BulkActionsDropdown
+  - Hide columns → Table.HideColumnsDropdown
+  - ... (14/21 elements)
+
+⚠️ Placeholder SVGs:
+  - TopNav (app shell — ~48px)
+  - SideNavIcons (app shell — ~100% height)
+  - SideNavText (app shell — ~100% height)
+  - Breadcrumbs (~24px)
+  - Warning/Alert Banner (~64px)
+
+✅ Tests: 24/24 passing
+✅ Type check: PASS
+✅ Style lint: PASS
+```
+
+## Notes
+
+- **Trust the migration report** — Sophia and Dorothy already verified everything
+- **Screenshot is layout reference only** — not the source of component decisions
+- **Table must be mocked in tests** — AG Grid needs a license key
+- **100% test pass rate** — always
+- **No `any` types** — define proper TypeScript interfaces
+- Use yarn (NOT npm)
+- AROOOOO!! 🐺💪