normalize

Overview of normalize skill

What normalize does

The normalize skill audits a UI feature and realigns it to an existing design system. It is built for cases where a page, route, or component has drifted from approved patterns, spacing, tokens, hierarchy, or interaction conventions.

Who should use normalize

Use normalize if you already have some design direction and want an agent to bring implementation back into line. It fits frontend teams, design system owners, and product engineers working in mature apps where inconsistency is more expensive than inventing new UI.

The real job-to-be-done

Most users are not asking for “nicer visuals.” They need a feature to look and behave like the rest of the product without introducing fresh one-off styling. The normalize skill is best when the goal is consistency, not ideation.

What makes this skill different

Unlike a generic “improve this UI” prompt, normalize is explicitly anchored to existing standards. The repository makes one thing clear: the skill should not guess. It requires design-context gathering first, asks you to identify deviations, and expects a plan before edits.

Best-fit scenarios

• A feature uses inconsistent spacing, typography, or color tokens
• A component visually works but does not match the system
• Legacy UI needs cleanup before broader refactoring
• A new page was shipped quickly and now needs design-system alignment
• Teams want normalization without redesigning product intent

When normalize is a weak fit

normalize for Design Systems is not the right first step if your team has no documented patterns, no reusable components, or unresolved product/UX direction. In that case, the skill may help surface gaps, but it cannot invent authoritative standards safely.

How to Use normalize skill

Install normalize in your skills environment

The repo does not publish an install command inside SKILL.md, so directory users typically add it from the source repository path used by the skill system they already run. If your environment supports direct GitHub skill installs, use the pbakaus/impeccable repository and select the normalize skill.

If you use a command pattern similar to:
npx skills add pbakaus/impeccable --skill normalize

verify it against your own runner first. The important part is that the skill lives at .agents/skills/normalize.

Read this file before first use

Start with:

• SKILL.md

This skill has no extra helper files, scripts, or references in the folder, so nearly all usable guidance is in that single file. That is good for speed, but it also means you must supply the missing project context yourself.

Understand the required dependency on frontend-design

The biggest adoption blocker is easy to miss: normalize says you must invoke /frontend-design first. That upstream skill contains the design principles, anti-patterns, and context-gathering protocol this workflow depends on.

It also says that if no design context exists yet, you must run /teach-impeccable before proceeding. In practice, normalize usage is a chained workflow, not a standalone one-shot prompt.

Know what input normalize expects

The declared argument hint is:
[feature (page, route, component...)]

Good inputs are concrete units of UI work, such as:

• checkout page
• settings/billing route
• pricing card component
• mobile nav menu

Weak inputs are broad targets like:

• the whole app
• make the UI better
• fix styling everywhere

Turn a rough goal into a strong normalize prompt

A weak request:
Normalize the dashboard

A stronger request:
Use normalize on the analytics dashboard route. Align it to our design system by checking token usage, spacing scale, typography hierarchy, component variants, and empty-state patterns. Preserve current functionality. Flag any places where the design system is unclear instead of guessing.

Why this works:

• names the feature boundary
• sets the normalization criteria
• protects functionality
• tells the agent what to do when standards are missing

Gather the minimum context before running normalize

For high-quality output, provide:

• the target feature path or route
• your component library or design system location
• token sources such as theme files or CSS variables
• relevant UI guidelines or screenshots
• any “do not change” business constraints
• whether you want plan-only or plan-plus-edits

Without this context, the skill can identify drift, but it cannot reliably choose the right replacement pattern.

Follow the workflow the skill implies

The repository text supports this sequence:

1. Run /frontend-design
2. If design context is missing, run /teach-impeccable
3. Discover design system docs, component patterns, and tokens
4. Analyze the current feature for deviations
5. Create a normalization plan
6. Execute changes conservatively
7. Clean up one-off styling and inconsistencies

That order matters because the skill is opinionated about not guessing at standards.

What normalize should inspect in your codebase

The source excerpt emphasizes:

• design principles and aesthetic direction
• target audience and personas
• component patterns and conventions
• design tokens for color, type, and spacing
• whether inconsistencies are cosmetic or functional
• root causes such as one-off implementation or missing tokens

This means normalize install is only half the decision. The more important question is whether your repo exposes enough of these signals for an agent to follow.

Prompt patterns that improve normalize output

Ask for both diagnosis and action:
Normalize the account settings page. First identify where it deviates from our system and categorize issues as token misuse, layout inconsistency, component misuse, or interaction mismatch. Then propose the minimal set of edits to align it.

Ask for uncertainty handling:
If a pattern is not documented, stop and ask rather than inventing a new one.

Ask for output format:
Return a brief audit, a change plan, then the implementation.

Practical guardrails for using normalize on real products

To keep normalize guide usage safe:

• preserve product requirements and copy intent
• avoid changing flows unless they clearly violate established patterns
• prefer replacing custom styling with existing primitives
• ask for diffs that reduce one-off code, not just visual tweaks
• require the agent to note where the system itself is inconsistent

A useful normalization run often improves both UI consistency and maintainability.

normalize skill FAQ

Is normalize better than a normal UI cleanup prompt?

Usually yes, if you already have a design system. The value of normalize is not fancy prompting; it is the enforced workflow of gathering standards first, checking drift against those standards, and avoiding invented design decisions.

Is normalize beginner-friendly?

Moderately. The skill itself is simple, but beginners often lack the prerequisites it expects: design docs, token sources, and confidence about what counts as canonical. If you are new, use smaller targets like one route or component.

Can normalize work without a formal design system?

Only partially. It can still surface inconsistency, but output quality drops when there is no clear source of truth. The skill explicitly warns against guessing, so missing standards become blockers instead of hidden assumptions.

What does normalize not do well?

It is not primarily for:

• greenfield visual exploration
• major UX strategy changes
• brand invention
• app-wide refactors in one pass

Use it for alignment, not broad product redesign.

How does normalize fit frontend stacks?

The normalize skill is conceptually stack-agnostic because it focuses on tokens, patterns, and conventions. It is most effective where the codebase has reusable components, theme primitives, and enough structure for an agent to trace canonical UI decisions.

When should I avoid normalize for Design Systems?

Avoid it when your real problem is unresolved product scope, not visual inconsistency. Also avoid it when teams disagree on the design system itself; otherwise the skill may spend effort normalizing toward a moving target.

How to Improve normalize skill

Give normalize a narrower target

The fastest quality win is scoping. Ask normalize to handle one route, feature, or component cluster at a time. Smaller scopes produce clearer audits, fewer accidental regressions, and better alignment decisions.

Provide the actual source of truth

Do not just say “follow our design system.” Point to:

• component folders
• Storybook or docs URLs
• token files
• screenshots of canonical screens
• examples of approved patterns

This reduces the biggest failure mode: plausible but incorrect alignment.

Distinguish cosmetic drift from pattern drift

Strong requests tell the skill whether you want:

• token cleanup only
• visual hierarchy alignment
• component replacement with approved variants
• interaction normalization too

That distinction changes the plan significantly and helps avoid over-editing.

Tell the skill what must not change

A better normalize usage prompt includes constraints such as:

• keep current data flow
• do not alter validation logic
• preserve accessibility behavior
• keep analytics selectors stable
• avoid introducing new components

This keeps normalization focused on system fit instead of accidental refactoring.

Ask for a plan before code changes

Because the repository emphasizes planning, use that. Ask for:

1. design-system findings
2. deviation audit
3. proposed normalization steps
4. only then implementation

This is the easiest way to catch wrong assumptions early.

Handle missing standards explicitly

If the agent cannot find a rule for spacing, typography, or component choice, instruct it to:

• stop and ask
• propose options with tradeoffs
• mark the gap as a design-system issue

That behavior matches the intent of the skill better than forcing a guess.

Review for maintainability, not just screenshots

The best normalize guide outcome is not merely visual sameness. Review whether the result:

• replaces hard-coded values with tokens
• removes custom one-off wrappers
• reuses approved primitives
• simplifies future updates across the system

This is where the skill can create lasting value for design systems.

Iterate after the first normalize pass

After the first run, ask a focused follow-up:
Re-check the implementation and list any remaining deviations from the design system, especially token usage, component variants, and spacing rhythm.

A second pass is often where subtle inconsistencies get caught.

Improve output quality with comparison examples

If you have a gold-standard screen, say so:
Normalize the billing page to match the visual and structural patterns used in the account overview page.

Reference examples are one of the highest-leverage inputs for normalize for Design Systems.

Know the main failure modes

Watch for:

• invented patterns when docs are thin
• overcorrection that changes UX intent
• visual alignment without token cleanup
• local fixes that ignore shared components
• broad “polish” edits with no design-system justification

If you see these, tighten scope, add references, and require explicit reasoning tied to your system.