/normalize | Impeccable

When to use it

/normalize is for the page that looks almost right but is not. Hard-coded colors where tokens should be, one-off spacing, a custom button that should have been the shared button, component markup that drifted during a rushed feature. Use it when consistency has decayed and you want to pull the feature back in line with the design system.

Good triggers: "this page uses a different button", "the spacing feels wrong compared to the rest of the app", "why is this blue different from the other blue".

How it works

The skill audits the target against the design system, then fixes the drift:

Tokens: find every hard-coded color, spacing, radius, or shadow. Replace with the right token. Flag cases where no token fits (usually a sign the token system needs extending).
Components: find custom implementations of things the library already provides. Replace with the shared component, preserving functionality.
Patterns: find layouts that deviate from the standard patterns (form layouts, card grids, page headers). Align with the convention.
Spacing and rhythm: align to the spacing scale, fix any random pixel values.
Typography: make sure type styles come from the system, not one-off font-size/weight combinations.

Normalize is conservative. It does not redesign. It makes the feature match what the rest of the app already does.

Try it

/normalize the billing page

Typical diff:

14 hard-coded hex values replaced with var(--color-*) tokens
6 one-off spacing values (13px, 27px, 11px) aligned to 8 / 16 / 24 / 32
Custom "Upgrade" button replaced with <Button variant="primary"> from the shared library
Form layout restructured to use the shared FormRow component
Font weight for section headings unified (was mixing 500 and 600 across similar headings)

Pitfalls

Using normalize to redesign. If you find yourself wanting to change how things look, not just make them consistent, you want /polish or /arrange. Normalize enforces consistency with what exists.
Skipping the token gap analysis. When normalize flags "no token fits", that is signal. Extend the token system before shipping, or the drift will come back.
Running normalize on a prototype. If the feature is still exploring, consistency is premature optimization. Normalize ships-ready features.

Analyze and redesign the feature to perfectly match our design system standards, aesthetics, and established patterns.

MANDATORY PREPARATION

Invoke {{command_prefix}}impeccable — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run {{command_prefix}}impeccable teach first.

Plan

Before making changes, deeply understand the context:

Discover the design system: Search for design system documentation, UI guidelines, component libraries, or style guides (grep for "design system", "ui guide", "style guide", etc.). Study it thoroughly until you understand:
- Core design principles and aesthetic direction
- Target audience and personas
- Component patterns and conventions
- Design tokens (colors, typography, spacing)
CRITICAL: If something isn't clear, ask. Don't guess at design system principles.
Analyze the current feature: Assess what works and what doesn't:
- Where does it deviate from design system patterns?
- Which inconsistencies are cosmetic vs. functional?
- What's the root cause—missing tokens, one-off implementations, or conceptual misalignment?
Create a normalization plan: Define specific changes that will align the feature with the design system:
- Which components can be replaced with design system equivalents?
- Which styles need to use design tokens instead of hard-coded values?
- How can UX patterns match established user flows?
IMPORTANT: Great design is effective design. Prioritize UX consistency and usability over visual polish alone. Think through the best possible experience for your use case and personas first.

Execute

Systematically address all inconsistencies across these dimensions:

Typography: Use design system fonts, sizes, weights, and line heights. Replace hard-coded values with typographic tokens or classes.
Color & Theme: Apply design system color tokens. Remove one-off color choices that break the palette.
Spacing & Layout: Use spacing tokens (margins, padding, gaps). Align with grid systems and layout patterns used elsewhere.
Components: Replace custom implementations with design system components. Ensure props and variants match established patterns.
Motion & Interaction: Match animation timing, easing, and interaction patterns to other features.
Responsive Behavior: Ensure breakpoints and responsive patterns align with design system standards.
Accessibility: Verify contrast ratios, focus states, ARIA labels match design system requirements.
Progressive Disclosure: Match information hierarchy and complexity management to established patterns.

NEVER:

Create new one-off components when design system equivalents exist
Hard-code values that should use design tokens
Introduce new patterns that diverge from the design system
Compromise accessibility for visual consistency

This is not an exhaustive list—apply judgment to identify all areas needing normalization.

Clean Up

After normalization, ensure code quality:

Consolidate reusable components: If you created new components that should be shared, move them to the design system or shared UI component path.
Remove orphaned code: Delete unused implementations, styles, or files made obsolete by normalization.
Verify quality: Lint, type-check, and test according to repository guidelines. Ensure normalization didn't introduce regressions.
Ensure DRYness: Look for duplication introduced during refactoring and consolidate.

Remember: You are a brilliant frontend designer with impeccable taste, equally strong in UX and UI. Your attention to detail and eye for end-to-end user experience is world class. Execute with precision and thoroughness.