@arbor-education/design-system.components 0.9.0 → 0.11.0

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

@@ -0,0 +1,374 @@
+---
+name: migrate-page
+description: Build a React page that replaces an existing legacy page. Uses a migration report from /map-legacy (or auto-generates one) to compose Arbor components into a production-ready page with tests and Storybook stories.
+---
+
+# Migrate Legacy Page to Arbor Components
+
+AROOOOO HUNNI!! 🐺 Time to rip out those HEINOUS legacy components and replace them with BODACIOUS Arbor ones! We have the migration map — now let's BUILD!! xxx
+
+## Goal
+
+Take a migration report (from `/map-legacy`) and a screenshot of the legacy page, and generate a **production-ready React page** that replaces the legacy implementation using Arbor design system components.
+
+**This is NOT a fresh build from Figma.** The migration map already tells us what replaces what. We trust Sophia and Dorothy's verified analysis — no need to re-run that work.
+
+**CRITICAL:**
+- ❌ DO NOT create new reusable components
+- ✅ DO USE existing components from `src/components/`
+- ✅ DO follow the migration map — it's already been Sophia-mapped and Dorothy-verified
+- ✅ DO use the legacy screenshot as the layout reference (not Figma)
+- ✅ DO use placeholder SVGs for elements with no Arbor equivalent
+
+## The Golden Girls Team — MANDATORY COLLABORATORS
+
+Some agents were already used in `map-legacy`. We don't re-do their work. We pick up from where they left off:
+
+- ~~👜 **Sophia Componentspert**~~ — Already ran in `map-legacy`. Her mapping is in the report. **Do NOT call her again** unless you hit an edge case not covered in the report.
+- ~~🔍 **Dorothy Fact-Checker**~~ — Already verified Sophia's claims in `map-legacy`. Trust the report. **Do NOT call her again** for component capability checks.
+- 💄 **Blanche Designspert** (`blanche-designspert`) — MANDATORY at Step 6. Design token and CSS class naming review.
+- 🌹 **Rose Storybookspert** (`rose-storybookspert`) — MANDATORY at Step 8. Storybook stories.
+- 🔍 **Dorothy Fact-Checker** (`dorothy-fact-checker`) — MANDATORY at Step 9. Final QA on the generated files.
+
+**RULE**: Blanche, Rose, and Dorothy (final QA) are NOT optional. Skip any of them = MOST HEINOUS failure. AROOOOO!! 🐺💪
+
+## Input
+
+Screenshot path and/or migration report path provided: `$ARGUMENTS`
+
+## Process
+
+### 1. Determine Input
+
+Check what the user provided:
+
+- **Both screenshot + report path**: Best case — use both
+- **Screenshot only, no report**: Auto-run `/map-legacy` first:
+  ```
+  Use Skill tool: skill="map-legacy", args="[screenshot path]"
+  ```
+  Wait for it to complete and find the generated `.claude/migration-report-*.md` file.
+- **Report path only, no screenshot**: Read the report, use it without a visual reference (note this in the output)
+- **Neither**: Ask the user for at least a screenshot path or a migration report path
+
+### 2. Read the Migration Report
+
+Use the `Read` tool on the migration report file. This is your **primary guide** — it contains:
+- The complete legacy element → Arbor component mapping (already verified by Dorothy)
+- Complexity ratings (Low / Medium / High / No equivalent)
+- Prop mappings and gotchas in Sophia's voice
+- A recommended migration order
+- Elements with no Arbor equivalent (→ placeholder SVGs)
+
+```
+Read tool: file_path=".claude/migration-report-{page-name}-{date}.md"
+```
+
+**CRITICAL:** Trust the report. Sophia and Dorothy already did the hard work. Do NOT second-guess the component choices or re-research them from scratch. If the report says use `Table.BulkActionsDropdown`, use it.
+
+### 3. Read the Screenshot (if provided)
+
+Use the `Read` tool on the screenshot path. This gives you the **visual layout reference** — use it to understand:
+- The overall page layout (two-column? header + content? sidebar?)
+- Relative sizing and spacing of sections
+- The order elements appear on the page
+- What content is in the page (text, labels, data examples)
+
+```
+Read tool: file_path="[screenshot path]"
+```
+
+### 4. Determine Page Name and Directory
+
+Derive the page name from the migration report title (e.g. "Custom Report Writer — All Reports" → `CustomReportWriterPage`).
+
+**Directory:**
+```
+src/pages/{pageName}/
+├── {PageName}.tsx
+├── {PageName}.test.tsx
+├── {PageName}.stories.tsx
+└── {pageName}.scss
+```
+
+Read `src/index.ts` to check whether a page with this name already exists. If it does, confirm with the user before overwriting.
+
+### 5. Build the Page
+
+#### 5a. Plan the structure
+
+Go through the migration report's **Recommended Migration Order**. Group elements into:
+- **Page layout** (header, main, sidebar, footer)
+- **Sections** (using `Section` component)
+- **Toolbar elements** (buttons, dropdowns, search)
+- **Table** (if present — use the full `columnDefs` from the report)
+- **Gaps** (no equivalent → placeholder SVGs)
+
+#### 5b. Generate the TSX
+
+Create the page component. Import ONLY from the design system using path aliases:
+
+```tsx
+import { Button } from 'Components/button/Button';
+import { Heading } from 'Components/heading/Heading';
+// etc.
+```
+
+**Component mapping rules from the report:**
+- Follow the migration report's element-by-element breakdown for every component choice
+- Use the exact prop names Sophia specified (Dorothy verified them)
+- Include Sophia's specific gotchas from the report (e.g. `headerContent={<></>}` to trigger SearchBar)
+- Use `Heading.InnerContainer` pattern for heading + right-side CTA if the report recommends it
+
+**For Table pages specifically:**
+- Inline `cellRenderer` functions for link cells, icon+text cells, overflow menus
+- `Table.BulkActionsDropdown` and `Table.HideColumnsDropdown` in `headerContent`
+- `hasSearch` defaults to `true` when `headerContent` is set — no extra work needed
+- Do NOT call `setAgGridLicenseKey()` — Table handles it
+- Do NOT spread `DSDefaultColDef` — Table merges it automatically
+
+**For elements with no Arbor equivalent (❌ in report):**
+
+Use the placeholder SVG pattern:
+
+```tsx
+{/*
+  ⚠️ MISSING COMPONENT PLACEHOLDER
+  Component: [ComponentName e.g. "Breadcrumbs"]
+  Reason: No Arbor equivalent — flagged in migration report as a gap.
+  TODO: Replace once [ComponentName] is built in the design system.
+*/}
+<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>
+```
+
+**Page props pattern** — expose callbacks and initial data:
+
+```tsx
+export interface {PageName}Props {
+  className?: string;
+  // Callbacks for primary actions
+  onCreateNew?: () => void;
+  onSchedule?: () => void;
+  // Data props
+  initialData?: RowType[];
+  // etc.
+}
+```
+
+**Typing:**
+- No `any` types — ever
+- Define row types for table data
+- Export type definitions with the component
+
+#### 5c. Generate SCSS
+
+Use design tokens for EVERYTHING. No hardcoded values.
+
+```scss
+// NO @use import — CSS custom properties are global
+.ds-{page-name-kebab} {
+  // page root styles using var(--token-name)
+}
+```
+
+**Token hierarchy** (most specific wins):
+1. Component tokens: `var(--{component}-{state}-color-{usage})`
+2. Semantic tokens: `var(--color-semantic-{name}-{scale})`
+3. Base tokens: `var(--color-{name}-{scale})`
+
+Spacing: `var(--spacing-{size})` or `$space-{n}`
+Border radius: `var(--border-radius-{size})`
+CSS class prefix: always `ds-` — no exceptions.
+
+### ⚡ MANDATORY STEP 6 — CALL BLANCHE DESIGNSPERT NOW ⚡
+
+**YOU MUST USE THE `Task` tool RIGHT NOW.** Do NOT move to step 7 without this.
+
+```
+Task tool: subagent_type="blanche-designspert"
+prompt: "I've created a SCSS file for a migrated legacy page. Please review for correct design token usage and CSS naming conventions. Here is the SCSS: [paste SCSS]"
+```
+
+After Blanche responds, relay her verdict:
+
+> 💄 **Blanche says:** _[relay in her glamorous, exacting voice — she will not tolerate a hardcoded hex value]_
+
+Apply ALL of Blanche's corrections before continuing.
+
+### 7. Generate Tests
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import '@testing-library/jest-dom/vitest';
+import { describe, it, expect, vi } from 'vitest';
+import { {PageName} } from './{PageName}';
+
+// Mock Table to avoid AG Grid license errors
+vi.mock('Components/table/Table', () => ({
+  Table: ({ rowData }: { rowData: unknown[] }) => (
+    <div role="grid" aria-label="...">
+      {/* map rowData */}
+    </div>
+  ),
+}));
+```
+
+**Test priorities (from the migration report):**
+- Render all section headings
+- Render all placeholder SVGs (verifiable via `getByRole('img', { name: /ComponentName placeholder/i })`)
+- Render the table (mocked)
+- Verify all primary action callbacks are called on click
+- Verify accessible landmarks (main, complementary/aside)
+- Verify accessible element (link hrefs, aria labels)
+- `className` prop applies to root element
+
+**Rules:**
+- No `any` types in test helpers
+- No `testId` — use `getByRole`, `getByLabelText`, `getByText`
+- Mock `Table` if it's in the page (AG Grid license)
+- 100% pass rate required — no placeholder tests
+
+### ⚡ MANDATORY STEP 8 — CALL ROSE STORYBOOKSPERT NOW ⚡
+
+**YOU MUST USE THE `Task` tool RIGHT NOW.**
+
+```
+Task tool: subagent_type="rose-storybookspert"
+prompt: "I've created a new page component called [{PageName}] that migrates a legacy page to Arbor components. Please create comprehensive Storybook stories for it. Here is the component: [paste TSX]. The file should go at src/pages/{pageName}/{PageName}.stories.tsx."
+```
+
+After Rose responds, relay her work and use her output as the story file.
+
+> 🌹 **Rose says:** _[relay in her warm storytelling voice]_
+
+### 9. Quality Checks
+
+Run in this order — lint and type-check FIRST:
+
+```bash
+yarn check-types
+yarn style-lint
+yarn test
+```
+
+Fix lint with `--fix` flag, not manually:
+```bash
+yarn eslint src/pages/{pageName}/ --fix
+```
+
+All checks must pass. 100% test pass rate. No exceptions.
+
+### ⚡ MANDATORY STEP 9 — CALL DOROTHY FACT-CHECKER NOW ⚡
+
+**YOU MUST USE THE `Task` tool RIGHT NOW.** Final quality gate — Dorothy checks the GENERATED FILES, not the component capabilities (those were already verified in `map-legacy`).
+
+```
+Task tool: subagent_type="dorothy-fact-checker"
+prompt: "I've just finished building a migrated legacy page. Please verify:
+1. All files actually exist on disk: [list file paths]
+2. Tests pass with 100% pass rate
+3. Tests are meaningful (not placeholders)
+4. Components are used with correct props (matching the migration report)
+5. No 'any' types used
+6. SCSS follows token conventions (Blanche already reviewed but double-check)
+7. Placeholder SVGs are present for every ❌ element from the migration report
+8. All callback props are tested"
+```
+
+After Dorothy responds, relay her verdict IN FULL:
+
+> 🔍 **Dorothy says:** _[relay her no-nonsense verdict — she doesn't sugarcoat]_
+
+Fix ALL issues before presenting the final summary.
+
+### 10. Export from src/index.ts
+
+Add the new page to the public API — matching the pattern of existing pages:
+
+```typescript
+export { {PageName}, type {PageName}Props, type {RowType} } from './pages/{pageName}/{PageName}';
+```
+
+### 11. Present Summary to User
+
+```
+AROOOOO HUNNI! 🐺 That legacy page has been BODACIOUSLY MIGRATED! xxx
+
+✅ Files created:
+  - src/pages/{pageName}/{PageName}.tsx
+  - src/pages/{pageName}/{pageName}.scss
+  - src/pages/{pageName}/{PageName}.test.tsx
+  - src/pages/{pageName}/{PageName}.stories.tsx
+
+✅ Components used from migration map:
+  [List each legacy element → Arbor component, matching report]
+
+⚠️ Placeholder SVGs (elements with no Arbor equivalent):
+  [List each gap with the component name and TODO]
+  These need real implementations before the page is production-ready.
+
+✅ Quality checks:
+  - Type check: PASS
+  - Style lint: PASS
+  - Tests: X/X passing
+
+🎯 Migration fidelity:
+  [Note anything that differs from the migration map, and why]
+
+🏁 Next steps:
+  - Replace placeholder SVGs when library components are built
+  - Wire up data fetching / routing in the consumer app
+  - [Any other integration notes]
+```
+
+---
+
+## Key Differences from `/create-page`
+
+| | `/create-page` | `/migrate-page` |
+|---|---|---|
+| **Input** | Figma URL | Screenshot + migration report |
+| **Pre-flight** | Runs `analyze-design` (Sophia + Dorothy) | Reads migration report (already done) |
+| **Visual ref** | Figma design | Legacy page screenshot |
+| **Component map** | Sophia generates it live | Already in the migration report |
+| **Sophia/Dorothy** | Called for component assessment | NOT called again (trust the report) |
+| **Blanche/Rose/Dorothy QA** | Mandatory | Mandatory |
+| **Intent** | Build something new | Replace something existing |
+
+---
+
+## Important Notes
+
+- **Trust the migration report** — Sophia and Dorothy already did the hard work. Don't re-research.
+- **Screenshot is layout reference** — use it for sizing, spacing, and content examples, not component choices
+- **Gaps get placeholder SVGs** — every ❌ element from the report needs one, testable via `getByRole('img')`
+- **Table mock is essential** — AG Grid needs a license key; always mock `Table` in tests
+- **100% test pass rate** — no shortcuts, no placeholder tests
+- **Dorothy does final QA on FILES** — she's checking your code output, not component capabilities
+- **No `any` types** — ever. Define proper TypeScript interfaces for all data shapes
+- **Use yarn (NOT npm)**
+- This codebase serves millions of users — accurate migrations matter!
+
+AROOOOO LET'S DRAG THAT LEGACY PAGE INTO THE BODACIOUS MODERN ERA, HUNNI!! xxx 💪🏍️✨🐺

package/.github/CODEOWNERS

@@ -3,5 +3,6 @@
 # Order is important. The last matching pattern has the most precedence.
 # The team needs to exist and have write access to the repository
 
+* @arbor-education/Frontend_Reviewers
 .github/** @arbor-education/DevOps_Reviewers
 terraform/** @arbor-education/DevOps_Reviewers

package/.github/pull_request_template.md

@@ -0,0 +1,39 @@
+## Summary of changes
+
+<!-- Link to the Jira ticket. Then summarise in your own words — don't assume everyone has Jira context. -->
+
+[MIS-XXXXX](https://arbor-education.atlassian.net/browse/MIS-XXXXX)
+
+### Areas to focus on
+
+<!-- Point reviewers to the most important or complex parts of the diff. -->
+
+### Notes for code owners
+
+<!-- Anything reviewers should know about scope, dependencies, or follow-up tickets. -->
+
+### Breaking changes
+
+<!-- Does this change the public API? Does it require consumers to update their code? If none, write "None." -->
+
+## How can a reviewer test this?
+
+<!-- Step-by-step testing instructions. Include any browser-specific or environment-specific notes.
+     Chromatic will post a Storybook link automatically — no need to include one here. -->
+
+1. 
+2. 
+3. 
+
+## Checklist
+
+- [ ] This PR does **one thing** — the title does not contain "and" or "also"
+- [ ] The meaningful code diff is under 400 lines (or a justification is written in "Notes for code owners")
+- [ ] `yarn check-types` passes with no errors
+- [ ] `yarn test:coverage` passes — all tests green, 100% pass rate
+- [ ] `yarn style-lint` passes with no errors
+- [ ] I have self-reviewed the diff line by line
+- [ ] Dead code, debug statements, and commented-out code are removed
+- [ ] A changeset has been created (`yarn changeset`) if this affects the public API
+
+<!-- AI AGENTS: You must complete every item in this checklist before opening this PR. Do not open the PR if any item is unchecked without a written explanation. -->

package/.github/workflows/release.yml

@@ -99,7 +99,7 @@ jobs:
           gh release create "${version}" \
             --repo "arbor-education/design-system.components" \
             --title "${version}" \
-            --notes "${{ env.changelog }}" \
+            --notes "$changelog" \
             "./release/design-system.components.tgz"
 
       - name: Send Slack Success Message

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.11.0
+
+### Minor Changes
+
+- [#159](https://github.com/arbor-education/design-system.components/pull/159) [`555e538`](https://github.com/arbor-education/design-system.components/commit/555e538d157d2f18c2aebf380ec57fcc19dfd467) Thanks [@angusmglfraser](https://github.com/angusmglfraser)! - MIS-69127 ✨ checkbox cell renderer
+
+## 0.10.0
+
+### Minor Changes
+
+- [#157](https://github.com/arbor-education/design-system.components/pull/157) [`f8a5137`](https://github.com/arbor-education/design-system.components/commit/f8a5137f17b758a6a062fa8c96511fc1e93e6618) Thanks [@danielpeplow](https://github.com/danielpeplow)! - **DatePicker / DateTimePicker** — The date side of `DatePicker` is a normal `date` field now, so you don’t get that odd native “time” bit when you only care about the day. If you set a custom placeholder while the field is still empty, we treat it like a hint: we open the calendar and skip free typing so the fake placeholder and the browser UI don’t fight. Same idea for `DateTimePicker` when you’re in native mode.
+
+  **Combobox** — If you’re on the button-style dropdown with search inside the panel, filtering down to nothing no longer nukes the whole popover—you can keep typing or clear and try again. Choosing one value (e.g. a time from the list) closes the dropdown even when that combobox lives inside another popover.
+
+- [#150](https://github.com/arbor-education/design-system.components/pull/150) [`7f49140`](https://github.com/arbor-education/design-system.components/commit/7f491402c72a29fc29f2ae1907f5487a71d5db70) Thanks [@angusmglfraser](https://github.com/angusmglfraser)! - MIS-69124 ✨ boolean cell renderer for tables
+
 ## 0.9.0
 
 ### Minor Changes

package/CLAUDE.md

@@ -139,6 +139,37 @@ The Table component is a wrapper around AG Grid:
 ## Commit rules
 - Each commit message should start with the same Jira ticket number as the branch name followed by a description of whats being committed. i.e. `MIS-68964 changed x prop to be a string`
 
+## PR rules (MANDATORY — applies to all agents)
+
+These rules are non-negotiable. Read CONTRIBUTING.md for the full rationale.
+
+### Scope control
+- **One PR = one Jira ticket.** Never combine multiple tickets or concerns into a single PR.
+- **Before writing any code**, identify the minimal set of files needed to complete the task. If the task touches more than ~5 files or ~200 lines, STOP and ask the human whether it should be split.
+- **Never bundle refactoring with feature work.** If you spot a refactor opportunity, note it for the human and do not act on it in the current PR.
+- **Never touch files outside the task scope.** Do not improve adjacent code, fix unrelated formatting, or clean up files that weren't required for the task.
+
+### Size limits
+| Lines changed (meaningful code) | Action |
+|----------------------------------|--------|
+| < 200 | Proceed |
+| 200–400 | Proceed, ensure description is thorough |
+| 400–800 | STOP — write a justification in the PR description, confirm with human |
+| > 800 | STOP — split the PR before continuing |
+
+Generated files, `yarn.lock`, and auto-generated types do NOT count toward these limits.
+
+### Quality gates — all must pass before opening a PR
+- `yarn check-types` — zero type errors
+- `yarn test:coverage` — 100% of tests passing
+- `yarn style-lint` — zero SCSS linting errors
+
+### PR description
+Always use the PR template at `.github/pull_request_template.md`. Fill in every section. Do not leave placeholders or blank sections.
+
+### When in doubt
+Ask the human. A question is always better than a PR that is too large to review.
+
 ## Notes for Claude
 - This is an active production codebase serving educational institutions
 - Changes can affect millions of users - be thoughtful and careful

package/CONTRIBUTING.md

@@ -0,0 +1,191 @@
+# Contributing to Arbor Design System Components
+
+Welcome, and thank you for contributing! This guide applies to **everyone** — human developers, non-developers, and AI agents using agentic tools. The rules here exist to protect the team's ability to review changes safely and keep this codebase — which serves millions of students in educational institutions — reliable and maintainable.
+
+---
+
+## The Golden Rule: One PR, One Thing
+
+> If your PR title needs the word "and" or "also", it should be two PRs.
+
+A pull request should represent a single, coherent unit of change. A reviewer should be able to understand what it does, why it exists, and whether it is correct — without losing context or needing to context-switch between unrelated concerns.
+
+**Good:**
+
+- `MIS-12345 ✨ Add disabled state to Button component`
+- `MIS-12346 🐛 Fix dropdown closing on outside click in Firefox`
+- `MIS-12347 ♻️ Refactor FormField to use new token API`
+
+**Not good:**
+
+- `MIS-12345 Add disabled Button state, fix dropdown bug, and refactor FormField`
+- `MIS-12345 Various fixes and improvements`
+- `MIS-12345 WIP`
+
+---
+
+## PR Size
+
+Small PRs get reviewed faster, get merged sooner, and carry far lower bug risk. Research consistently shows that large PRs take **4–5× longer to merge** and produce lower-quality reviews because humans (and tools) struggle to hold large diffs in working memory.
+
+| Size           | Lines changed | Files changed | What to do                                        |
+| -------------- | ------------- | ------------- | ------------------------------------------------- |
+| **Ideal**      | < 200         | < 5           | Ship it                                           |
+| **Acceptable** | 200–400       | < 10          | Fine, make sure description is thorough           |
+| **Large**      | 400–800       | any           | Add a written justification in the PR description |
+| **Too large**  | > 800         | any           | **Stop. Split it.**                               |
+
+### What counts as "lines changed"?
+
+Generated files, lockfiles (`yarn.lock`), and auto-generated type definitions do not count. Focus on the meaningful code diff.
+
+### How to split a large PR
+
+1. **Refactor first, feature second.** If you need to restructure existing code before adding new behaviour, that's two PRs: the refactor PR (no new behaviour) and the feature PR (uses the refactored foundation).
+2. **One component per PR.** Adding a new component? Each component gets its own PR.
+3. **Separate concerns.** Infrastructure changes (build config, CI) go in their own PR, separate from product changes.
+4. **Stack PRs.** Create PR B off the branch of PR A, and set PR B's base to A's branch. When A merges, update B's base to main.
+
+---
+
+## Anatomy of a Good PR
+
+### Title
+
+Format: `{JIRA-TICKET} {gitmoji} {Short, imperative description}`
+
+- Start with the Jira ticket number (required — CI will check this)
+- Optionally follow with a [gitmoji](https://gitmoji.dev/) that signals the type of change at a glance
+- Use the imperative mood: "Add", "Fix", "Remove", "Update" — not "Added", "Fixes", "Removing"
+- Keep it under 72 characters
+
+**Common gitmoji:**
+| Emoji | Use for |
+|-------|---------|
+| ✨ | New feature |
+| 🐛 | Bug fix |
+| ♻️ | Refactor (no behaviour change) |
+| 💄 | Styling / visual change |
+| 🧪 | Tests only |
+| 📝 | Documentation |
+| ⬆️ | Dependency upgrade |
+| 🔧 | Config / tooling change |
+| 💥 | Breaking change |
+| ♿️ | Accessibility improvement |
+
+### Description
+
+A PR description is documentation. Write it as if a future developer — who has no context on your task — needs to understand why this change exists. Answer these four questions:
+
+**1. What problem does this solve?**
+Link to the Jira ticket, but also summarise in your own words. Don't assume everyone has Jira access or context.
+
+**2. How does it solve it?**
+Explain the key implementation decisions. If you chose approach A over approach B, say why.
+
+**3. What are the risks?**
+What could go wrong? What areas of the codebase might be affected that aren't immediately obvious?
+
+**4. How can a reviewer test this?**
+List steps. Include any relevant Storybook story paths, component names, or browser/environment-specific notes.
+
+**Optional but excellent:**
+
+- Screenshots or videos for visual changes
+- A note if this PR depends on another PR being merged first
+- A note if there are follow-up tickets already created for known limitations
+
+### Commits
+
+Each commit should tell part of the story. A reviewer should be able to follow your commits in order and understand the journey.
+
+- Write commit messages that explain **why**, not just what
+- Format: `{JIRA-TICKET} {description of why}`
+- Rebase and clean up your history before opening a PR — squash "fix typo" and "oops" commits
+- Do not mix formatting-only changes with logic changes in the same commit
+
+---
+
+## Before You Open a PR
+
+Run through this checklist yourself before requesting review:
+
+- [ ] My branch name includes the Jira ticket number (e.g. `feature/MIS-12345-add-button-variant`)
+- [ ] My PR does **one thing**. The title does not contain "and" or "also"
+- [ ] The diff is under 400 lines of meaningful code (or I have written a justification)
+- [ ] I have run `yarn check-types` and there are no type errors
+- [ ] I have run `yarn test:coverage` and all tests pass (100% pass rate required)
+- [ ] I have run `yarn style-lint` and there are no SCSS linting errors
+- [ ] I have self-reviewed my own diff — line by line — before requesting review
+- [ ] I have removed dead code, debugging statements, and commented-out code
+- [ ] I have created a changeset with `yarn changeset` if this change affects the public API
+- [ ] My PR description answers: What? Why? How? Risks? How to test?
+
+---
+
+## For AI Agents and Agentic Tools
+
+**This section is specifically for you.** If you are an AI agent (Claude Code, Copilot, Cursor, or any other tool) generating or submitting code to this repository, you MUST follow these rules. They are not suggestions.
+
+### Hard rules for agents
+
+1. **One PR per Jira ticket.** Never combine work from multiple tickets into a single PR, even if the work seems related.
+
+2. **Stop and check scope before starting.** Before writing any code, identify the minimal set of files required to complete the task. If you find yourself touching more than ~5 files or ~200 lines, pause and ask the human whether the task should be split.
+
+3. **Never bundle refactoring with feature work.** If you notice an opportunity to refactor while implementing a feature, stop. Create a note for the human. Do not refactor in the same PR unless explicitly instructed.
+
+4. **Never touch files outside the task scope.** Do not "improve" adjacent code, fix unrelated formatting, or clean up files you didn't need to open to complete the task.
+
+5. **Never open a PR with failing tests.** All tests must pass. `yarn test:coverage` must complete with 100% of tests passing.
+
+6. **Never open a PR with type errors.** `yarn check-types` must pass cleanly.
+
+7. **Write a complete PR description.** Use the template. Answer all four questions. Do not leave sections blank.
+
+8. **Warn before generating large changes.** If completing a task would require changes to more than 400 lines of meaningful code or more than 10 files, stop and tell the human before proceeding. Ask whether the task should be broken into smaller pieces.
+
+9. **Commit atomically.** Each commit should be a coherent, working unit. Do not commit broken intermediate states.
+
+10. **Ask, don't assume.** When the scope or approach is unclear, ask the human rather than making assumptions that lead to larger-than-expected changes.
+
+---
+
+## Code Review Culture
+
+Reviews are collaborative, not adversarial. The goal is to ship high-quality software together.
+
+### For authors
+
+- If you disagree with feedback, explain why — but be open to being wrong
+- If significant changes happen after approval, flag this to reviewers
+- Do not merge without all required reviewers approving
+
+### For reviewers
+
+- Review the code, not the person. Feedback is never personal
+- When suggesting a change, explain why and offer an alternative
+- Distinguish between blocking issues ("this will cause a bug") and preferences ("I'd personally style this differently")
+- Do not use diminishing language ("just", "simply", "obviously") — what's obvious to you may not be obvious to others
+- Rely on automated linters for style enforcement — don't debate formatting in review comments
+- If a PR is too large to review effectively, say so and ask for it to be split before you start reviewing
+
+---
+
+## Branch and Commit Conventions
+
+See [CLAUDE.md](./CLAUDE.md) for the definitive reference. In summary:
+
+- Branches: `feature/MIS-12345-short-description`, `bugfix/MIS-12345-short-description`, or `issue/MIS-12345-short-description`
+- Commits: `MIS-12345 description of the why`
+- All branches must include a Jira ticket number
+- Never push directly to `main`
+
+---
+
+## Resources
+
+- [gitmoji reference](https://gitmoji.dev/)
+- [Arbor Jira](https://orchard.atlassian.net/) — for ticket context
+- [Production Storybook](https://main--68c3f2a09d95b22aa55a11e8.chromatic.com/) – Builds every time something is pushed to main
+- [Local Storybook](http://localhost:6006) — run locally with `yarn storybook`