visual-hierarchy-refactoring

Visual Hierarchy Refactoring

Take a real screen or component and refactor it so the eye lands on the right things in the right order. The deliverable is refactored code plus a before/after hierarchy audit — not design commentary. Governing principles: hierarchy is a function of size, weight, and lightness contrast — color is the last resort, and the fastest fix is de-emphasis: quiet the noise before amplifying the signal.

When to use / handoffs

• Use when a specific screen is cluttered, flat, unscannable, or "looks off" despite sane tokens.
• No consistent tokens exist at all (every fix would be a new magic number) → skills/frontend-design/design-foundation first.
• The problem is structural (columns misaligned, breaks on mobile) → skills/frontend-design/layout-system.
• Font sizes themselves are chaotic across the app → skills/frontend-design/typography-system.
• Palette is the problem (clashing hues, contrast failures everywhere) → skills/frontend-design/color-system.

Step 1 — Inspect the target

1. Get the actual component. Read the file(s) for the screen the user named; if none named, ask for the one screen that matters most (this is the only intake question that blocks). Render or screenshot it if the environment allows.
2. Read the available tokens (spacing scale, text sizes, grey ramp) — every fix must use them.
3. Detect hierarchy smells in the code, with counts:
   • Emphasis inflation: how many elements per screen are bold, colored, large, or bordered? (>3 competing emphases = nothing is emphasized)
   • Cramped spacing: padding/margins ≤8px between unrelated groups
   • True greys / pure black: #808080-family, #000, text-gray-500 on colored surfaces
   • Uniform sizing: title, body, and metadata within a step of each other
   • Even spacing everywhere: identical gap inside and between groups (kills Gestalt grouping)
   • Border overuse: boxes-in-boxes where spacing would separate

Step 2 — Build the hierarchy audit