---
name: normalize
description: Normalize design to match your design system and ensure consistency
user-invokable: true
args:
  - name: feature
    description: The page, route, or feature to normalize (optional)
    required: false
author: "@firdausmntp"
---

## Intent Primacy

Read the user's request before applying this command's defaults.

1. **Exact target**: Identify the specific feature, file, or area named. If none is named, ask before acting broadly.
2. **Stated scope wins**: "/normalize just the header" means only the header. Do not expand scope.
3. **User's choices bind you**: If the user specifies a framework, style, or approach, follow it even if this skill would suggest otherwise. Warn once, then comply.
4. **Proportional output**: A narrow request gets a targeted answer with only the relevant sections from this skill. A broad request gets the full protocol.
5. **No unrequested work**: Do not refactor, rename, add tests, or generate documentation the user did not ask for.
6. **Hard gates only for safety**: Accessibility AA floor and security checks override user intent. Aesthetic or stylistic preferences do not.
7. **Ask only when it matters**: Ambiguity on scope or destructive action (data loss, breaking change, deleting files) — ask once with specific options. Ambiguity on cosmetic defaults — state assumption and proceed. Never stack questions. Never ask what you can read yourself. STOP and call the `question` tool to clarify.

---

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

## MANDATORY PREPARATION

Use the frontend-design skill — 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 teach-impeccable first.

---

## Plan

Before making changes, deeply understand the context:

1. **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.

2. **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?

3. **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.

## Before / After

Concrete examples of normalization. The "before" snippets are real-world drift — the kind that accumulates when features ship without reference to the system.

### 1. Token replacement — inline colors to semantic tokens

Hard-coded hex values break the palette the moment someone rebrands or adjusts contrast for dark mode. Replace them with the token the design system already ships.

```css
/* before — off-palette hex values, no relationship to the system */
.cta {
  background: #7c3aed;
  color: #ffffff;
  border: 1px solid #6d28d9;
}
.cta:hover {
  background: #6d28d9;
}
.cta[disabled] {
  background: #c4b5fd;
}
```

```css
/* after — semantic tokens that track the palette */
.cta {
  background: var(--color-primary);
  color: var(--color-on-primary);
  border: 1px solid var(--color-primary-strong);
}
.cta:hover {
  background: var(--color-primary-strong);
}
.cta[disabled] {
  background: var(--color-primary-muted);
}

/* tokens.css — single source of truth */
:root {
  --color-primary:        oklch(58% 0.22 285);
  --color-primary-strong: oklch(50% 0.24 285);
  --color-primary-muted:  oklch(78% 0.08 285);
  --color-on-primary:     oklch(98% 0.01 285);
}
```

### 2. Component consolidation — merge near-duplicates

Two buttons that are 90% identical are a maintenance tax and a consistency risk. Merge them behind one API with variants.

```tsx
// before — two components, same job, subtly different
export function PrimaryButton({ children, onClick }) {
  return (
    <button onClick={onClick} className="px-4 py-2 bg-violet-600 text-white rounded-lg font-semibold">
      {children}
    </button>
  );
}

export function DangerButton({ label, handler }) {
  return (
    <button onClick={handler} className="px-4 py-2 bg-red-600 text-white rounded-md font-bold">
      {label}
    </button>
  );
}
```

```tsx
// after — one component, design-system tokens, explicit variants
type ButtonProps = {
  variant?: "primary" | "danger" | "ghost";
  size?: "sm" | "md" | "lg";
  children: React.ReactNode;
  onClick?: () => void;
};

export function Button({ variant = "primary", size = "md", children, onClick }: ButtonProps) {
  return (
    <button
      onClick={onClick}
      className={cn(buttonBase, buttonVariant[variant], buttonSize[size])}
    >
      {children}
    </button>
  );
}
```

### 3. Spacing realignment — random px to the scale

Arbitrary values read as sloppy up close and chaotic at a distance. Snap everything to the spacing scale the rest of the app uses.

```tsx
{/* before — values pulled from thin air */}
<section style={{ padding: "17px 23px", marginTop: 42, gap: 11 }}>
  <header style={{ marginBottom: 13 }}>…</header>
  <ul style={{ paddingLeft: 19 }}>…</ul>
</section>
```

```tsx
{/* after — tokens from the 4pt scale (space-1=4, space-2=8, space-4=16, space-6=24, space-8=32) */}
<section className="px-6 py-4 mt-10 gap-3">
  <header className="mb-3">…</header>
  <ul className="pl-5">…</ul>
</section>
```

### 4. Typography realignment — mixed scale to system scale

Mixed line-heights and non-scale sizes leave text rivers and awkward vertical rhythm. Map every text style to a named role.

```css
/* before — one-off sizes, inconsistent line-heights */
.hero-title    { font-size: 37px; line-height: 1.15; font-weight: 700; }
.section-title { font-size: 22.5px; line-height: 1.3;  font-weight: 600; }
.card-title    { font-size: 19px; line-height: 28px; font-weight: 700; }
.body          { font-size: 15px; line-height: 1.45; }
```

```css
/* after — roles from the type scale, consistent leading per role */
.text-display    { font: 600 var(--text-4xl)/1.1  var(--font-display); }
.text-heading-lg { font: 600 var(--text-2xl)/1.25 var(--font-display); }
.text-heading-sm { font: 600 var(--text-lg)/1.35  var(--font-display); }
.text-body       { font: 400 var(--text-base)/1.5 var(--font-body); }
```

---

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.