Parsons/.claude/skills/normalize/SKILL.md

name, description, user-invocable, argument-hint

name	description	user-invocable	argument-hint
normalize	Cross-component consistency scan — checks token access patterns, transitions, focus styles, spacing methods, and displayName across all components in a tier or the entire system.	true	[tier (atoms/molecules/organisms) or 'all']

Scan all components in a tier (or the entire system) for consistency violations and fix them. Unlike audit/critique which evaluate individual components, normalize ensures the system behaves as one cohesive whole. This skill finds AND fixes issues.

Target tier: $ARGUMENTS

Preparation

1. Read docs/design-system.md for FA design conventions
2. Read docs/memory/decisions-log.md for design rationale (especially D031 on token access)
3. Read docs/conventions/component-conventions.md for structural rules
4. List all component files in the target tier(s):
   • Atoms: src/components/atoms/*/
   • Molecules: src/components/molecules/*/
   • Organisms: src/components/organisms/*/
   • If target is "all", scan every tier

FA context: Consistency is trust. When components behave differently for no reason — different transition speeds, different focus styles, different spacing methods — users sense it even if they cannot articulate it. For families in distress, inconsistency creates subconscious unease. Normalize ruthlessly.

Consistency Dimensions

For each dimension, scan ALL components in the target scope, compare patterns, identify outliers, and fix them to match the established convention.

1. Token Access Patterns (D031)

Convention: Two access methods, by token tier:

• Semantic tokens (colour, spacing, typography, shape): theme.palette.*, theme.spacing(), theme.typography.*, theme.shape.* inside theme callbacks. var(--fa-color-*), var(--fa-spacing-*) in static contexts.
• Component tokens (badge sizes, card shadows, input dimensions): var(--fa-badge-*), var(--fa-card-*) CSS variables only — these are NOT in the MUI theme.

Scan for violations:

• Hardcoded hex/rgb colour values (should use theme or CSS var)
• Hardcoded px spacing values (should use theme.spacing() or var(--fa-spacing-*))
• Hardcoded font sizes or weights (should use theme.typography.*)
• Semantic tokens accessed via CSS var when inside a theme callback (prefer theme accessor)
• Component tokens accessed via theme (they are CSS vars only)
• Primitive tokens used directly instead of semantic tokens

2. Transition Timing

Convention: 150ms ease-in-out for all state transitions.

Scan for violations:

• Transitions using durations other than 150ms (or theme.transitions.duration.short)
• Transitions using easing other than ease-in-out
• Transitions using bounce, elastic, or spring easing (remove — feels dated)
• Missing transitions on interactive state changes (hover, focus, active)
• Transitions on layout properties (width, height, top, left) instead of transform/opacity

3. Focus-Visible Style

Convention: :focus-visible with 2px outline, offset 2px, high contrast (3:1 minimum against adjacent colours).

Scan for violations:

• outline: none without :focus-visible replacement
• Focus styles on :focus instead of :focus-visible (shows ring on click)
• Inconsistent outline width, colour, or offset across components
• Missing focus styles entirely on interactive elements
• Focus ring colour that does not meet 3:1 contrast

4. Spacing Method

Convention: theme.spacing() in styled components and sx props. var(--fa-spacing-*) in static contexts.

Scan for violations:

• Raw pixel values for padding/margin/gap (e.g., padding: '16px')
• Mixed methods in the same component (some theme.spacing(), some raw values)
• Inconsistent spacing scale usage across similar components (e.g., one card uses spacing(2) for padding, another uses spacing(3))

5. Component Structure

Convention: Per docs/conventions/component-conventions.md.

Scan for violations:

• Missing displayName on the component
• Missing barrel export (index.ts with export { default } and export *)
• Missing JSDoc on props interface (every prop needs a /** description */)
• Missing JSDoc on the component itself
• Props defined as type instead of interface (interfaces produce better autodocs)
• Missing sx prop forwarding (every component must accept consumer overrides)
• Interactive elements not using React.forwardRef

6. Story Coverage

Convention: Per story coverage checklist in docs/conventions/component-conventions.md.

Scan for violations:

• Missing tags: ['autodocs'] in story meta
• Missing Default story
• Missing AllVariants story (if component has variants)
• Missing Disabled story (if component can be disabled)
• Missing Loading story (if component has loading state)
• Incorrect title prefix (should match tier: Atoms/, Molecules/, Organisms/)

7. Naming Consistency

Scan for violations:

• Component folder not in PascalCase
• File names not matching component name
• Inconsistent prop naming across similar components (e.g., isDisabled vs disabled, colour vs color)
• CSS custom properties not prefixed with --fa-

Normalize Process

1. Scan: Read every component file in the target tier(s)
2. Tabulate: Build a comparison table for each dimension showing what each component does
3. Identify outliers: Find components that deviate from the convention
4. Fix: Update outlier components to match the convention
5. Verify: Ensure TypeScript compiles and Storybook renders after fixes

Normalization Report

Present findings in this format:

Scan Summary

Dimension	Components scanned	Violations found	Fixed
Token access	?	?	?
Transitions	?	?	?
Focus styles	?	?	?
Spacing	?	?	?
Structure	?	?	?
Stories	?	?	?
Naming	?	?	?

Violations Fixed

For each fix, note:

• Component: Which component was changed
• Dimension: Which consistency rule was violated
• Before: What it was doing
• After: What it does now

System-Level Observations

Note any patterns that suggest a convention should be updated (e.g., if most components deviate from the convention, perhaps the convention is wrong).

NEVER:

• Change a component's behaviour or API — normalize only changes implementation details
• Fix one component and leave similar components unfixed — normalize the whole tier
• Change conventions without flagging it — if you think a convention should change, note it as an observation, do not unilaterally change the rule