/arc:distill

UI simplification

—What it does

Distill analyzes a component or page for unnecessary complexity and strips it to its essentials. It finds redundant wrapper divs, excessive nesting, unused CSS classes, over-engineered abstractions, and visual noise that doesn't serve the user. The output is simpler code with fewer elements, cleaner Tailwind classes, and a more focused user experience.

—Why it exists

AI-generated UI tends toward over-engineering — extra wrapper divs "just in case," defensive styling, redundant containers. Human developers accumulate complexity through iterations. Distill provides the opposite force: ruthless simplification while preserving what matters.

—Design decisions

  • —User-interactive, not agent-delegated. Every removal is discussed and approved.
  • —Never sacrifices accessibility, functionality, or necessary information for minimalism.
  • —Complexity should match actual task complexity — simple tasks deserve simple UI.

Source document

Distill Workflow

Strip UI to its essence. "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."

Announce at start: "I'm using the distill skill to simplify this UI."

This skill is user-interactive. Do NOT spawn agents. Simplification requires judgment about what matters — it's collaborative, not automated.

Never sacrifice:

  • Accessibility
  • Core functionality
  • Necessary information
  • User understanding

Simplicity means removing obstacles between users and their goals — not eliminating features or clarity.

Phase 0: Context

Ask the user using AskUserQuestion:

AskUserQuestion:
  question: "What is the ONE thing this component/page should accomplish?"
  header: "Core purpose"
  options:
    - label: "Let me explain"
      description: "I'll describe the core purpose"
    - label: "Infer from code"
      description: "You analyze and propose the core purpose"

Phase 1: Assess Current State

Read the code

Read all files for the target component/page. Look for:

Structural Complexity

  • Redundant wrappers: Div soup — containers that add no styling, no semantics, no layout purpose
  • Excessive nesting: More than 3-4 levels deep for simple content
  • Unnecessary cards: Content grouped in cards that could use spacing/typography alone
  • Cards within cards: Almost never justified — use spacing and dividers instead
  • Defensive containers: Wrappers added "just in case" that serve no current purpose

Visual Complexity

  • Too many font sizes: More than 5 distinct sizes creates muddy hierarchy
  • Too many colors: More than 3 distinct colors (plus neutrals) creates noise
  • Decorative clutter: Borders, shadows, backgrounds that don't aid comprehension
  • Inconsistent spacing: Different gaps that should be the same
  • Gradient/effect overuse: Visual effects without communicative purpose

Tailwind Complexity

  • Class sprawl: Elements with 15+ classes that could be simplified
  • Redundant classes: flex flex-col items-start when items-start is the default
  • Responsive overrides that undo: hidden md:block chains that suggest wrong base state
  • Arbitrary values: p-[17px] instead of scale values
  • Dark mode duplication: text-gray-900 dark:text-gray-100 instead of CSS variable flipping

Interaction Complexity

  • Too many actions: Every section doesn't need a CTA
  • Over-configured components: Props that could be fewer with better defaults
  • Modal/dialog overuse: Inline expansion or navigation might be simpler
  • Form over-engineering: Validation for scenarios that can't happen

Phase 2: Plan Removal

Present findings as a distillation plan:

## Distillation Plan

### Remove (no value lost)
1. [Wrapper div at line X — adds no styling or semantics]
2. [Card container — spacing alone creates grouping]

### Simplify (same value, less code)
1. [15 Tailwind classes → 8 by removing redundancies]
2. [3-level nesting → flat with gap]

### Consolidate (multiple things → one)
1. [3 similar buttons → 1 with variant prop]
2. [Repeated icon+text pattern → shared component]

### Preserve (looks removable but isn't)
1. [Wrapper needed for overflow handling]
2. [Extra div required for animation transform-origin]

Ask using AskUserQuestion:

AskUserQuestion:
  question: "Does this distillation plan look right? Anything I should preserve?"
  header: "Distillation plan"
  options:
    - label: "Looks good"
      description: "Proceed with simplification"
    - label: "Adjust"
      description: "I have changes or things to preserve"
    - label: "Too aggressive"
      description: "Keep more of the current structure"

Phase 3: Simplify Systematically

Apply changes in this order (safest first):

3.1 Remove Redundant Wrappers

<!-- Before: unnecessary wrapper -->
<div>
  <div class="flex gap-4">
    <div class="p-4">Content</div>
  </div>
</div>

<!-- After: flat -->
<div class="flex gap-4">
  <div class="p-4">Content</div>
</div>

3.2 Replace Cards with Spacing

<!-- Before: card for grouping -->
<div class="rounded-lg border p-4 shadow-sm">
  <h3>Title</h3>
  <p>Description</p>
</div>

<!-- After: spacing creates grouping -->
<div class="space-y-2">
  <h3 class="font-semibold">Title</h3>
  <p class="text-gray-600">Description</p>
</div>

3.3 Clean Tailwind Classes

Remove classes that are defaults or redundant:

  • flex-row (default for flex)
  • items-stretch (default for flex)
  • static (default position)
  • visible (default)
  • text-left (default for LTR)

3.4 Flatten Nesting

Use gap-* instead of nested containers with margins.

3.5 Reduce Visual Noise

Ask for each decorative element: "Would the user notice if this was removed?" If no, remove it.

Phase 4: Verify

After each batch of changes:

  1. Visual check: Screenshot if Chrome MCP available, or run dev server
  2. Functionality check: Ensure nothing broke
  3. Accessibility check: Semantic HTML preserved, ARIA attributes intact

Ask: "The simplified version is ready. Does it still feel complete?"