aiox-core 5.0.3 → 5.0.4

package/pro/squads/design/checklists/ds-component-quality-checklist.md

@@ -1,150 +1,150 @@
-# Component Quality Checklist
-
-**Purpose:** Validate component before marking complete
-**Agent:** Merovingian (Design System Builder)
-**Standard:** Production-ready React/TypeScript components
-
----
-
-## CODE QUALITY
-
-- [ ] TypeScript compiles with zero errors
-  → Fix: Run `tsc --noEmit` and resolve each error by type. Most common: missing prop types, incorrect event handler signatures
-- [ ] No `any` types used
-  → Fix: Replace `any` with specific types. Use `unknown` + type guard for truly dynamic data. Search: `grep -rn ': any' src/`
-- [ ] Props fully typed with interface
-  → Fix: Create `interface {Component}Props` with each prop explicitly typed. Avoid `Record<string, unknown>` for known shapes
-- [ ] All props documented with TSDoc comments
-  → Fix: Add `/** description */` TSDoc comment above each prop in the interface. Include `@default` for optional props
-- [ ] Component exported correctly
-  → Fix: Ensure `export const {Component}` or named export in index.ts. Verify barrel file re-exports: `export { Component } from './Component'`
-
----
-
-## STYLING
-
-- [ ] All styling uses tokens (zero hardcoded values)
-  → Fix: `grep -rn '#[0-9a-f]' *.module.css` to find hardcoded values, replace with `var(--token-name)`
-- [ ] CSS Modules or chosen approach used consistently
-  → Fix: Rename .css to .module.css, update imports to `import styles from './X.module.css'`
-- [ ] No inline styles
-  → Fix: `grep -rn 'style={{' *.tsx` — move all inline styles to CSS Module classes
-- [ ] Responsive design implemented (if needed)
-  → Fix: Add `@media` queries for sm/md/lg breakpoints using token breakpoint values
-- [ ] All variants styled correctly
-  → Fix: Create CSS class per variant (`.primary`, `.secondary`), verify each renders differently in Storybook
-
----
-
-## ACCESSIBILITY (WCAG AA MINIMUM)
-
-- [ ] Semantic HTML elements used
-  → Fix: Replace `<div onClick>` with `<button>`, `<div>` navigation with `<nav>`, generic containers with `<section>`/`<article>`
-- [ ] ARIA attributes present where needed
-  → Fix: Add `aria-label` for icon-only buttons, `aria-expanded` for toggles, `role` only when no native semantic equivalent
-- [ ] Color contrast ≥4.5:1 for text
-  → Fix: Use `*contrast-matrix` to find failing pairs, adjust to nearest compliant token color
-- [ ] Keyboard navigation works (Tab, Enter, Space)
-  → Fix: Ensure `onKeyDown` handles Enter/Space for custom interactive elements. Native `<button>` gets this for free
-- [ ] Focus indicators visible
-  → Fix: Add `:focus-visible` style with `outline: 2px solid var(--color-focus)` and `outline-offset: 2px`
-- [ ] Disabled state handled correctly
-  → Fix: Add `aria-disabled="true"` + visual dimming + prevent onClick via `pointer-events: none` or early return
-- [ ] Screen reader tested (or documented)
-  → Fix: Test with VoiceOver (Mac: Cmd+F5) or NVDA (Windows). Document results in component README
-
----
-
-## TESTING
-
-- [ ] Unit tests written
-  → Fix: Create `{Component}.test.tsx` using React Testing Library. Start with render test, then add interaction tests
-- [ ] All variants tested
-  → Fix: Use `test.each` to iterate over variant values. Verify each variant applies the correct CSS class
-- [ ] All sizes tested
-  → Fix: Render each size, assert expected class or computed style. Use snapshot tests for visual regression
-- [ ] Disabled state tested
-  → Fix: Render with `disabled` prop, assert `aria-disabled`, verify click handler is NOT called
-- [ ] Event handlers tested
-  → Fix: Use `fireEvent.click()` or `userEvent.click()`, assert callback was called with expected args
-- [ ] Test coverage >80%
-  → Fix: Run `--coverage` flag, check uncovered lines. Add tests for branches (if/else, ternary, early returns)
-- [ ] All tests pass
-  → Fix: Run `npm test -- --watchAll=false`. Fix failures starting with type errors, then logic errors
-
----
-
-## DOCUMENTATION
-
-- [ ] Component.md created
-  → Fix: Copy template from `docs/templates/component.md`. Fill in purpose, API, and examples sections
-- [ ] Props documented with examples
-  → Fix: Add a props table with Name, Type, Default, Description columns. Include code snippet for each prop
-- [ ] Variants explained
-  → Fix: Show visual example or code snippet for each variant. Explain when to use which variant
-- [ ] Usage examples provided
-  → Fix: Add at least 3 examples: basic usage, with all props, and composition with other components
-- [ ] Accessibility notes included
-  → Fix: Document keyboard shortcuts, ARIA attributes used, and screen reader behavior
-
----
-
-## STORYBOOK (if enabled)
-
-- [ ] Stories file created
-  → Fix: Create `{Component}.stories.tsx` with `Meta` and `StoryObj` types from `@storybook/react`
-- [ ] Story for each variant
-  → Fix: Export a named story per variant (e.g., `export const Primary: Story = { args: { variant: 'primary' } }`)
-- [ ] Interactive controls work
-  → Fix: Ensure `argTypes` are defined in Meta. Use `control: 'select'` for enums, `control: 'boolean'` for flags
-- [ ] Stories display correctly
-  → Fix: Check Storybook console for warnings. Verify all stories render without errors in multiple viewports
-
----
-
-## Edge Cases
-
-- [ ] **Empty/null state:** Component handles `undefined` props gracefully (default values or explicit empty state UI)
-  → Fix: Add default values for all optional props, test with `<Component />` (no props)
-- [ ] **Loading state:** If async, component shows loading indicator with `aria-busy="true"`
-- [ ] **Error state:** Component displays error feedback (not just console.error) with `role="alert"`
-- [ ] **Long content:** Text overflow handled (truncation with `title` attribute or expand/collapse)
-  → Fix: Add `overflow: hidden; text-overflow: ellipsis` or `word-break: break-word` as appropriate
-- [ ] **RTL support:** Layout mirrors correctly for right-to-left languages (if i18n required)
-  → Fix: Use logical properties (`margin-inline-start` instead of `margin-left`)
-- [ ] **Recursive nesting:** Component renders correctly when nested inside itself
-  → Fix: Test recursive rendering, ensure no infinite loops in useEffect
-
----
-
-**Reviewer:** ________ **Date:** ________
-**Quality Gate:** [ ] PASS [ ] FAIL
-
----
-
-## Scoring
-
-### Point System
-Each checkbox item = 1 point.
-
-| Category | Items | Weight |
-|----------|-------|--------|
-| Code Quality (API Design) | 5 | 5pts |
-| Styling (Token Integration) | 5 | 5pts |
-| Accessibility | 7 | 7pts |
-| Testing | 7 | 7pts |
-| Documentation | 5 | 5pts |
-| Storybook | 4 | 4pts |
-| Edge Cases | 6 | 6pts |
-| **Total** | **39** | **39pts** |
-
-### Pass/Fail Thresholds
-| Grade | Score | Action |
-|-------|-------|--------|
-| PASS | >= 80% (32+) | Proceed to next phase |
-| CONDITIONAL | 60-79% (24-31) | Fix critical items, re-check |
-| FAIL | < 60% (23-) | Major rework required |
-
-### Auto-Correction
-If items fail:
-- Run `*ds-build-component --validate` to check token coverage. Use `*execute-checklist` for automated validation.
+# Component Quality Checklist
+
+**Purpose:** Validate component before marking complete
+**Agent:** Merovingian (Design System Builder)
+**Standard:** Production-ready React/TypeScript components
+
+---
+
+## CODE QUALITY
+
+- [ ] TypeScript compiles with zero errors
+  → Fix: Run `tsc --noEmit` and resolve each error by type. Most common: missing prop types, incorrect event handler signatures
+- [ ] No `any` types used
+  → Fix: Replace `any` with specific types. Use `unknown` + type guard for truly dynamic data. Search: `grep -rn ': any' src/`
+- [ ] Props fully typed with interface
+  → Fix: Create `interface {Component}Props` with each prop explicitly typed. Avoid `Record<string, unknown>` for known shapes
+- [ ] All props documented with TSDoc comments
+  → Fix: Add `/** description */` TSDoc comment above each prop in the interface. Include `@default` for optional props
+- [ ] Component exported correctly
+  → Fix: Ensure `export const {Component}` or named export in index.ts. Verify barrel file re-exports: `export { Component } from './Component'`
+
+---
+
+## STYLING
+
+- [ ] All styling uses tokens (zero hardcoded values)
+  → Fix: `grep -rn '#[0-9a-f]' *.module.css` to find hardcoded values, replace with `var(--token-name)`
+- [ ] CSS Modules or chosen approach used consistently
+  → Fix: Rename .css to .module.css, update imports to `import styles from './X.module.css'`
+- [ ] No inline styles
+  → Fix: `grep -rn 'style={{' *.tsx` — move all inline styles to CSS Module classes
+- [ ] Responsive design implemented (if needed)
+  → Fix: Add `@media` queries for sm/md/lg breakpoints using token breakpoint values
+- [ ] All variants styled correctly
+  → Fix: Create CSS class per variant (`.primary`, `.secondary`), verify each renders differently in Storybook
+
+---
+
+## ACCESSIBILITY (WCAG AA MINIMUM)
+
+- [ ] Semantic HTML elements used
+  → Fix: Replace `<div onClick>` with `<button>`, `<div>` navigation with `<nav>`, generic containers with `<section>`/`<article>`
+- [ ] ARIA attributes present where needed
+  → Fix: Add `aria-label` for icon-only buttons, `aria-expanded` for toggles, `role` only when no native semantic equivalent
+- [ ] Color contrast ≥4.5:1 for text
+  → Fix: Use `*contrast-matrix` to find failing pairs, adjust to nearest compliant token color
+- [ ] Keyboard navigation works (Tab, Enter, Space)
+  → Fix: Ensure `onKeyDown` handles Enter/Space for custom interactive elements. Native `<button>` gets this for free
+- [ ] Focus indicators visible
+  → Fix: Add `:focus-visible` style with `outline: 2px solid var(--color-focus)` and `outline-offset: 2px`
+- [ ] Disabled state handled correctly
+  → Fix: Add `aria-disabled="true"` + visual dimming + prevent onClick via `pointer-events: none` or early return
+- [ ] Screen reader tested (or documented)
+  → Fix: Test with VoiceOver (Mac: Cmd+F5) or NVDA (Windows). Document results in component README
+
+---
+
+## TESTING
+
+- [ ] Unit tests written
+  → Fix: Create `{Component}.test.tsx` using React Testing Library. Start with render test, then add interaction tests
+- [ ] All variants tested
+  → Fix: Use `test.each` to iterate over variant values. Verify each variant applies the correct CSS class
+- [ ] All sizes tested
+  → Fix: Render each size, assert expected class or computed style. Use snapshot tests for visual regression
+- [ ] Disabled state tested
+  → Fix: Render with `disabled` prop, assert `aria-disabled`, verify click handler is NOT called
+- [ ] Event handlers tested
+  → Fix: Use `fireEvent.click()` or `userEvent.click()`, assert callback was called with expected args
+- [ ] Test coverage >80%
+  → Fix: Run `--coverage` flag, check uncovered lines. Add tests for branches (if/else, ternary, early returns)
+- [ ] All tests pass
+  → Fix: Run `npm test -- --watchAll=false`. Fix failures starting with type errors, then logic errors
+
+---
+
+## DOCUMENTATION
+
+- [ ] Component.md created
+  → Fix: Copy template from `docs/templates/component.md`. Fill in purpose, API, and examples sections
+- [ ] Props documented with examples
+  → Fix: Add a props table with Name, Type, Default, Description columns. Include code snippet for each prop
+- [ ] Variants explained
+  → Fix: Show visual example or code snippet for each variant. Explain when to use which variant
+- [ ] Usage examples provided
+  → Fix: Add at least 3 examples: basic usage, with all props, and composition with other components
+- [ ] Accessibility notes included
+  → Fix: Document keyboard shortcuts, ARIA attributes used, and screen reader behavior
+
+---
+
+## STORYBOOK (if enabled)
+
+- [ ] Stories file created
+  → Fix: Create `{Component}.stories.tsx` with `Meta` and `StoryObj` types from `@storybook/react`
+- [ ] Story for each variant
+  → Fix: Export a named story per variant (e.g., `export const Primary: Story = { args: { variant: 'primary' } }`)
+- [ ] Interactive controls work
+  → Fix: Ensure `argTypes` are defined in Meta. Use `control: 'select'` for enums, `control: 'boolean'` for flags
+- [ ] Stories display correctly
+  → Fix: Check Storybook console for warnings. Verify all stories render without errors in multiple viewports
+
+---
+
+## Edge Cases
+
+- [ ] **Empty/null state:** Component handles `undefined` props gracefully (default values or explicit empty state UI)
+  → Fix: Add default values for all optional props, test with `<Component />` (no props)
+- [ ] **Loading state:** If async, component shows loading indicator with `aria-busy="true"`
+- [ ] **Error state:** Component displays error feedback (not just console.error) with `role="alert"`
+- [ ] **Long content:** Text overflow handled (truncation with `title` attribute or expand/collapse)
+  → Fix: Add `overflow: hidden; text-overflow: ellipsis` or `word-break: break-word` as appropriate
+- [ ] **RTL support:** Layout mirrors correctly for right-to-left languages (if i18n required)
+  → Fix: Use logical properties (`margin-inline-start` instead of `margin-left`)
+- [ ] **Recursive nesting:** Component renders correctly when nested inside itself
+  → Fix: Test recursive rendering, ensure no infinite loops in useEffect
+
+---
+
+**Reviewer:** ________ **Date:** ________
+**Quality Gate:** [ ] PASS [ ] FAIL
+
+---
+
+## Scoring
+
+### Point System
+Each checkbox item = 1 point.
+
+| Category | Items | Weight |
+|----------|-------|--------|
+| Code Quality (API Design) | 5 | 5pts |
+| Styling (Token Integration) | 5 | 5pts |
+| Accessibility | 7 | 7pts |
+| Testing | 7 | 7pts |
+| Documentation | 5 | 5pts |
+| Storybook | 4 | 4pts |
+| Edge Cases | 6 | 6pts |
+| **Total** | **39** | **39pts** |
+
+### Pass/Fail Thresholds
+| Grade | Score | Action |
+|-------|-------|--------|
+| PASS | >= 80% (32+) | Proceed to next phase |
+| CONDITIONAL | 60-79% (24-31) | Fix critical items, re-check |
+| FAIL | < 60% (23-) | Major rework required |
+
+### Auto-Correction
+If items fail:
+- Run `*ds-build-component --validate` to check token coverage. Use `*execute-checklist` for automated validation.

package/pro/squads/design/checklists/ds-critical-eye-review-checklist.md

@@ -1,147 +1,147 @@
-# Critical Eye — Canonical Review Checklist
-
-**Purpose:** Human checkpoint for STABLE → CANONICAL and CANONICAL → DEPRECATED transitions
-**Agent:** Design Chief (Design Principal)
-**Standard:** Enterprise DS governance — only the best pattern per category becomes canonical
-**Authority:** Nathan Curtis/EightShapes, GOV.UK Contribution Criteria, USWDS Lifecycle, Salesforce 4-Point Screening
-
----
-
-## CONTEXT
-
-- **Proposal ID:** ________
-- **Cycle:** ________
-- **Variant:** ________
-- **Category:** ________
-- **Proposed Transition:** [ ] STABLE → CANONICAL  [ ] CANONICAL → DEPRECATED
-- **Current Score:** ________/100
-- **Replacing (if deprecation):** ________
-
----
-
-## SCORE VERIFICATION
-
-- [ ] Total score >= 80 (canonical threshold)
-  → Fix: If score < 80, REJECT proposal. Variant needs improvement before canonical consideration.
-- [ ] Highest score in its category
-  → Fix: If not the leader, check comparison matrix. Only the best becomes canonical.
-- [ ] All 5 dimensions have non-null scores
-  → Fix: Re-run scoring if any dimension is null. Incomplete evaluation cannot be promoted.
-- [ ] No accessibility blocker (a11y > 0)
-  → Fix: Accessibility score = 0 is absolute REJECT. Cannot be overridden.
-
----
-
-## BREADTH (Nathan Curtis — Usage Breadth Scale)
-
-- [ ] Pattern appears in 2+ sources/brands
-  → Fix: Single-source patterns are snowflakes. Need adoption across brands before canonical status.
-- [ ] Source attributions are accurate (verified against brand.json files)
-  → Fix: Cross-reference variant.sources with actual brand files. Remove phantom sources.
-- [ ] Breadth score reflects actual usage, not just registration
-  → Fix: Verify the pattern is ACTUALLY USED in source brands, not just registered.
-
----
-
-## QUALITY (EightShapes Component QA 8+1)
-
-- [ ] Token compliance: zero hardcoded values
-  → Fix: Search component source for `#hex` and `Npx` values. Replace all with CSS custom properties.
-- [ ] States coverage: all required states implemented [default, hover, focus, disabled, error, loading]
-  → Fix: Check component for missing states. Focus and disabled are non-negotiable.
-- [ ] Accessibility: WCAG AA contrast + ARIA + keyboard + focus-visible
-  → Fix: Run contrast checker. Add missing ARIA attributes. Test keyboard navigation.
-- [ ] Responsiveness: works across mobile, tablet, desktop
-  → Fix: Test at 320px, 768px, 1024px widths minimum.
-- [ ] Composability: integrates with other canonical components
-  → Fix: Test composition with 3+ other components. No CSS hacks or overrides needed.
-- [ ] Resilience: handles edge cases (empty, long text, overflow, missing image)
-  → Fix: Test with empty props, 500-character strings, missing optional data.
-
----
-
-## CONSISTENCY (GOV.UK Contribution Criteria — Consistent)
-
-- [ ] Follows DS naming conventions (kebab-case, semantic prefixes)
-  → Fix: Rename files, props, and CSS classes to match established conventions.
-- [ ] API follows established patterns (CVA + variants + slots)
-  → Fix: Align prop signatures with other canonical components. Use same variant/size pattern.
-- [ ] Visually harmonious with rest of DS (indistinguishable quality)
-  → Fix: Compare side-by-side with existing canonicals. Spacing, typography, and color should match.
-
----
-
-## MATURITY (USWDS Component Lifecycle)
-
-- [ ] Stable for 3+ cycles (no breaking changes)
-  → Fix: Check lifecycleHistory. Recent major changes disqualify from canonical. Wait for stabilization.
-- [ ] Documentation complete (guidelines + API + examples + do/dont)
-  → Fix: Create missing documentation sections. Canonical components MUST have full docs.
-- [ ] Test coverage adequate (unit + a11y minimum)
-  → Fix: Add missing tests. Canonical components must demonstrate reliability.
-
----
-
-## SIMPLICITY (Brad Frost — Death to Complexity)
-
-- [ ] Reasonable LOC count (< 150 LOC preferred)
-  → Fix: Refactor complex components. Extract utilities. Simplify branching logic.
-- [ ] Minimal dependencies (0-2 external deps preferred)
-  → Fix: Evaluate if dependencies can be removed or replaced with lighter alternatives.
-
----
-
-## DEPRECATION-SPECIFIC (only for CANONICAL → DEPRECATED)
-
-- [ ] Replacement candidate scores > current + 10 points
-  → Fix: Margin must be significant (>10%) to justify disruption of deprecating a canonical.
-- [ ] Migration path documented for consumers
-  → Fix: Document exactly how existing usage should be updated. Provide codemod if possible.
-- [ ] Deprecation timeline defined (minimum 2 cycles grace period)
-  → Fix: Deprecated components remain available for at least 2 more cycles.
-
----
-
-## FINAL DECISION
-
-**Reviewer:** ________ **Date:** ________
-
-| Decision | Criteria |
-|----------|----------|
-| [ ] **APPROVE** | All checks pass. Transition is justified and beneficial. |
-| [ ] **APPROVE WITH CONDITIONS** | Minor issues to address, but transition is warranted. |
-| [ ] **DEFER** | Not ready yet. Specific improvements needed first. |
-| [ ] **REJECT** | Does not meet canonical/deprecation criteria. |
-
-**Conditions (if applicable):**
-________________________________________________________________________
-
-**Notes:**
-________________________________________________________________________
-
----
-
-## Scoring
-
-### Point System
-Each checkbox item = 1 point.
-
-| Category | Items | Weight |
-|----------|-------|--------|
-| Score Verification | 4 | 4pts |
-| Breadth | 3 | 3pts |
-| Quality | 6 | 6pts |
-| Consistency | 3 | 3pts |
-| Maturity | 3 | 3pts |
-| Simplicity | 2 | 2pts |
-| Deprecation (if applicable) | 3 | 3pts |
-| **Total (promotion)** | **21** | **21pts** |
-| **Total (deprecation)** | **24** | **24pts** |
-
-### Pass/Fail Thresholds
-| Grade | Score | Action |
-|-------|-------|--------|
-| APPROVE | >= 90% (19+/21 or 22+/24) | Execute transition |
-| APPROVE WITH CONDITIONS | 75-89% (16-18/21 or 18-21/24) | Execute with noted conditions |
-| DEFER | 60-74% (13-15/21 or 15-17/24) | Return for improvements |
-| REJECT | < 60% (12-/21 or 14-/24) | Do not transition |
+# Critical Eye — Canonical Review Checklist
+
+**Purpose:** Human checkpoint for STABLE → CANONICAL and CANONICAL → DEPRECATED transitions
+**Agent:** Design Chief (Design Principal)
+**Standard:** Enterprise DS governance — only the best pattern per category becomes canonical
+**Authority:** Nathan Curtis/EightShapes, GOV.UK Contribution Criteria, USWDS Lifecycle, Salesforce 4-Point Screening
+
+---
+
+## CONTEXT
+
+- **Proposal ID:** ________
+- **Cycle:** ________
+- **Variant:** ________
+- **Category:** ________
+- **Proposed Transition:** [ ] STABLE → CANONICAL  [ ] CANONICAL → DEPRECATED
+- **Current Score:** ________/100
+- **Replacing (if deprecation):** ________
+
+---
+
+## SCORE VERIFICATION
+
+- [ ] Total score >= 80 (canonical threshold)
+  → Fix: If score < 80, REJECT proposal. Variant needs improvement before canonical consideration.
+- [ ] Highest score in its category
+  → Fix: If not the leader, check comparison matrix. Only the best becomes canonical.
+- [ ] All 5 dimensions have non-null scores
+  → Fix: Re-run scoring if any dimension is null. Incomplete evaluation cannot be promoted.
+- [ ] No accessibility blocker (a11y > 0)
+  → Fix: Accessibility score = 0 is absolute REJECT. Cannot be overridden.
+
+---
+
+## BREADTH (Nathan Curtis — Usage Breadth Scale)
+
+- [ ] Pattern appears in 2+ sources/brands
+  → Fix: Single-source patterns are snowflakes. Need adoption across brands before canonical status.
+- [ ] Source attributions are accurate (verified against brand.json files)
+  → Fix: Cross-reference variant.sources with actual brand files. Remove phantom sources.
+- [ ] Breadth score reflects actual usage, not just registration
+  → Fix: Verify the pattern is ACTUALLY USED in source brands, not just registered.
+
+---
+
+## QUALITY (EightShapes Component QA 8+1)
+
+- [ ] Token compliance: zero hardcoded values
+  → Fix: Search component source for `#hex` and `Npx` values. Replace all with CSS custom properties.
+- [ ] States coverage: all required states implemented [default, hover, focus, disabled, error, loading]
+  → Fix: Check component for missing states. Focus and disabled are non-negotiable.
+- [ ] Accessibility: WCAG AA contrast + ARIA + keyboard + focus-visible
+  → Fix: Run contrast checker. Add missing ARIA attributes. Test keyboard navigation.
+- [ ] Responsiveness: works across mobile, tablet, desktop
+  → Fix: Test at 320px, 768px, 1024px widths minimum.
+- [ ] Composability: integrates with other canonical components
+  → Fix: Test composition with 3+ other components. No CSS hacks or overrides needed.
+- [ ] Resilience: handles edge cases (empty, long text, overflow, missing image)
+  → Fix: Test with empty props, 500-character strings, missing optional data.
+
+---
+
+## CONSISTENCY (GOV.UK Contribution Criteria — Consistent)
+
+- [ ] Follows DS naming conventions (kebab-case, semantic prefixes)
+  → Fix: Rename files, props, and CSS classes to match established conventions.
+- [ ] API follows established patterns (CVA + variants + slots)
+  → Fix: Align prop signatures with other canonical components. Use same variant/size pattern.
+- [ ] Visually harmonious with rest of DS (indistinguishable quality)
+  → Fix: Compare side-by-side with existing canonicals. Spacing, typography, and color should match.
+
+---
+
+## MATURITY (USWDS Component Lifecycle)
+
+- [ ] Stable for 3+ cycles (no breaking changes)
+  → Fix: Check lifecycleHistory. Recent major changes disqualify from canonical. Wait for stabilization.
+- [ ] Documentation complete (guidelines + API + examples + do/dont)
+  → Fix: Create missing documentation sections. Canonical components MUST have full docs.
+- [ ] Test coverage adequate (unit + a11y minimum)
+  → Fix: Add missing tests. Canonical components must demonstrate reliability.
+
+---
+
+## SIMPLICITY (Brad Frost — Death to Complexity)
+
+- [ ] Reasonable LOC count (< 150 LOC preferred)
+  → Fix: Refactor complex components. Extract utilities. Simplify branching logic.
+- [ ] Minimal dependencies (0-2 external deps preferred)
+  → Fix: Evaluate if dependencies can be removed or replaced with lighter alternatives.
+
+---
+
+## DEPRECATION-SPECIFIC (only for CANONICAL → DEPRECATED)
+
+- [ ] Replacement candidate scores > current + 10 points
+  → Fix: Margin must be significant (>10%) to justify disruption of deprecating a canonical.
+- [ ] Migration path documented for consumers
+  → Fix: Document exactly how existing usage should be updated. Provide codemod if possible.
+- [ ] Deprecation timeline defined (minimum 2 cycles grace period)
+  → Fix: Deprecated components remain available for at least 2 more cycles.
+
+---
+
+## FINAL DECISION
+
+**Reviewer:** ________ **Date:** ________
+
+| Decision | Criteria |
+|----------|----------|
+| [ ] **APPROVE** | All checks pass. Transition is justified and beneficial. |
+| [ ] **APPROVE WITH CONDITIONS** | Minor issues to address, but transition is warranted. |
+| [ ] **DEFER** | Not ready yet. Specific improvements needed first. |
+| [ ] **REJECT** | Does not meet canonical/deprecation criteria. |
+
+**Conditions (if applicable):**
+________________________________________________________________________
+
+**Notes:**
+________________________________________________________________________
+
+---
+
+## Scoring
+
+### Point System
+Each checkbox item = 1 point.
+
+| Category | Items | Weight |
+|----------|-------|--------|
+| Score Verification | 4 | 4pts |
+| Breadth | 3 | 3pts |
+| Quality | 6 | 6pts |
+| Consistency | 3 | 3pts |
+| Maturity | 3 | 3pts |
+| Simplicity | 2 | 2pts |
+| Deprecation (if applicable) | 3 | 3pts |
+| **Total (promotion)** | **21** | **21pts** |
+| **Total (deprecation)** | **24** | **24pts** |
+
+### Pass/Fail Thresholds
+| Grade | Score | Action |
+|-------|-------|--------|
+| APPROVE | >= 90% (19+/21 or 22+/24) | Execute transition |
+| APPROVE WITH CONDITIONS | 75-89% (16-18/21 or 18-21/24) | Execute with noted conditions |
+| DEFER | 60-74% (13-15/21 or 15-17/24) | Return for improvements |
+| REJECT | < 60% (12-/21 or 14-/24) | Do not transition |