normalize

Overview of normalize skill

What normalize does

The normalize skill audits a UI feature and brings it back into alignment with an existing design system. It is meant for cases where a page, route, or component has drifted from established patterns in spacing, typography, tokens, states, or interaction design.

Who should install normalize

This normalize skill is best for teams that already have some design language in place: a component library, style guide, token set, or repeated product patterns. It is especially useful for frontend engineers, design engineers, and AI-assisted maintainers cleaning up inconsistent surfaces without redesigning the whole product.

Real job-to-be-done

Users do not usually want “make this prettier.” They want to:

• identify where a feature breaks system conventions
• separate cosmetic inconsistency from structural UI problems
• produce changes that feel native to the product
• avoid inventing new patterns when existing ones should be reused

Why normalize is different from a generic prompt

The main differentiator is that normalize is explicitly a design-system alignment workflow, not an open-ended UI redesign prompt. The skill pushes the agent to gather system context first, analyze deviations, and avoid guessing when design principles are unclear. It also depends on another skill, /frontend-design, and may require /teach-impeccable first if no design context exists.

Best-fit and misfit scenarios

Best fit:

• a feature looks “off” compared with the rest of the app
• tokens, spacing, typography, or component usage are inconsistent
• a team wants consistency without broad product redesign
• a Design Systems workflow already exists but is unevenly applied

Poor fit:

• greenfield product design with no system to normalize against
• brand exploration or visual direction work
• flows that need UX strategy before UI cleanup
• teams expecting automatic fixes without giving repository context

How to Use normalize skill

normalize install context

The upstream SKILL.md does not publish a package-style install command, so use the skill through the host skill system that supports GitHub-based skills. If your environment uses the common CLI pattern, the baseline install is:

npx skills add https://github.com/pbakaus/impeccable --skill normalize

What matters more than install is dependency setup: normalize requires /frontend-design context gathering, and if that context has not been established yet, the skill instructs you to run /teach-impeccable first.

Required prerequisites before first use

Before calling normalize, confirm you have:

• access to the target repository or relevant UI files
• some evidence of a design system: tokens, docs, shared components, style guides, screenshots, or conventions
• permission to inspect neighboring features for pattern matching
• /frontend-design available in the same skill environment

Without that context, normalize will have to guess, and the source guidance explicitly says not to guess when principles are unclear.

What input normalize expects

The argument hint is:

[feature (page, route, component...)]

In practice, the strongest inputs name a specific surface plus where to look. Examples:

• normalize settings billing page
• normalize /dashboard/reports route
• normalize AccountMenu component and related dropdown states

This skill works better on a bounded feature than on “the whole app.”

How to frame a strong normalize request

A weak request:

• “Normalize the UI.”

A stronger request:

• “Normalize the /checkout flow to match our existing design system. Focus on spacing, form field hierarchy, button treatments, error states, and component reuse. Compare against our account settings pages and shared form components before changing anything.”

Why this helps:

• it names the scope
• it points to comparison surfaces
• it gives quality criteria
• it reduces the chance of an unnecessary redesign

Suggested workflow for normalize usage

A practical flow is:

1. Run /frontend-design and follow its context-gathering protocol.
2. If there is no usable design context yet, run /teach-impeccable.
3. Ask normalize to analyze one feature.
4. Review the plan before code changes.
5. Have the agent implement only the agreed normalization work.
6. Re-check adjacent states and variants so the fix does not stop at the happy path.

This sequence matters because normalize is built around understanding the system first, then editing.

What normalize should inspect first

Since the repository support for this skill is minimal, your own repo context matters most. Ask the agent to inspect:

• shared UI components
• token definitions
• design system or style guide docs
• similar mature pages in the product
• form, table, modal, card, and navigation patterns
• current feature states: empty, loading, error, disabled, success

If you only provide the target component, output quality will usually plateau at cosmetic cleanup.

Repository file to read first

For the upstream skill itself, start with:

• SKILL.md

That file contains nearly all available guidance, including the mandatory preparation step and the normalize workflow emphasis on discovering the design system before making changes.

Practical prompt pattern for normalize for Design Systems

If you are using normalize for Design Systems work, give the agent a comparison set. Example:

“Use normalize on the TeamMembers page. First study our design system tokens, the shared table component, and the settings pages. Identify where this page diverges in spacing, typography, action placement, row density, empty states, and status badges. Propose a concise plan, then update the implementation to reuse existing patterns instead of introducing new ones.”

This is better than asking for “consistency” because it names observable dimensions.

Constraints and tradeoffs to expect

normalize is not a magic “make it perfect” button. Tradeoffs include:

• if your system is inconsistent, the skill may surface ambiguity rather than cleanly resolve it
• strong visual normalization can expose deeper UX issues it should not invent solutions for
• some drift comes from product requirements, not poor implementation
• strict consistency can conflict with local feature needs

The skill is most trustworthy when the system is mature enough to be referenced, not inferred.

Common mistakes during normalize usage

Avoid these adoption blockers:

• skipping /frontend-design
• asking for a broad app-wide cleanup in one pass
• giving no reference components or mature pages
• letting the agent invent tokens or patterns
• treating visual normalization as a substitute for product or accessibility review

What success looks like

A good normalize result should:

• reuse existing components and tokens
• reduce one-off styling
• make the feature feel native to the product
• preserve feature intent while improving consistency
• explain why each change aligns with established patterns

If the output mostly changes colors and spacing without pattern reasoning, you likely underprovided context.

normalize skill FAQ

Is normalize beginner-friendly?

Yes, with guardrails. A beginner can use normalize if they can point to the target feature and a few good reference surfaces. It is less beginner-friendly when the codebase has no obvious design system or when product patterns are undocumented.

Do I need an existing design system for normalize?

Not necessarily a formal design system site, but you do need evidence of recurring standards. Shared components, tokens, stable pages, and visual conventions are usually enough. If none of that exists, normalize becomes a weak fit.

How is normalize different from asking an AI to clean up UI?

A normal prompt often jumps straight to edits. normalize is explicitly about finding and applying existing standards first. That makes it better for consistency work, especially in larger products where local improvements can accidentally fragment the system further.

When should I not use normalize?

Do not use normalize when you need:

• brand-new visual direction
• early-stage product design exploration
• major UX flow invention
• broad accessibility validation as the primary task
• a full component library strategy from scratch

In those cases, normalize is too narrow.

Can normalize work on a single component?

Yes. In fact, that is often the best starting point. A single page section, route, or component gives the skill enough scope to reason well while keeping changes reviewable.

Is normalize only for visual polish?

No. The source description mentions standards, tokens, and patterns, which usually include component usage, hierarchy, and state handling—not just surface styling. Still, it is not a substitute for deep UX research.

How to Improve normalize skill

Give normalize comparison targets

The fastest way to improve normalize output is to specify what “good” looks like in your app. Name two or three reference pages or components. This gives the skill an anchor and reduces invented design decisions.

Provide system evidence, not just the broken feature

High-quality inputs include:

• token files
• shared component paths
• design documentation
• screenshots of mature interfaces
• notes on audience or brand tone

This directly supports the skill’s requirement to discover design principles before changing code.

Ask for a plan before implementation

Because normalize is alignment-oriented, planning first improves trust. Ask for:

• detected deviations
• root causes
• proposed reuse of existing components
• open questions where the system is unclear

This catches “polish-only” output before it lands in code.

Break broad cleanup into feature-sized passes

If you want normalize across a large product, run it incrementally:

1. normalize one route
2. normalize one shared component family
3. normalize a neighboring flow
4. consolidate patterns revealed by the previous passes

This produces better consistency than a single broad request.

Watch for these failure modes

Common failure modes include:

• the agent guessing the design language
• overfitting to one reference page
• introducing new variants instead of reusing existing ones
• fixing happy-path visuals while ignoring states
• making style changes without explaining pattern alignment

If you see these, the issue is usually missing context, not just weak execution.

Strengthen your follow-up prompts

After the first output, improve normalize results with prompts like:

• “Revise this to use only existing button and form patterns.”
• “Re-check empty, loading, and validation states against our settings pages.”
• “List any new patterns you introduced and replace them with existing system equivalents.”
• “Separate must-fix inconsistencies from optional polish.”

These follow-ups keep the work grounded in system consistency.

Use normalize as a design debt reducer

The normalize skill is most valuable when used repeatedly on drift-prone areas: old routes, recently shipped features, or surfaces touched by many contributors. Treat it as a targeted design debt tool, not a one-time beautifier.

Improve outputs by clarifying non-negotiables

Tell the skill what must stay stable:

• layout constraints
• business logic
• component APIs
• accessibility requirements
• release-risk limits

This helps normalize focus on system alignment without overreaching into unrelated rewrites.