ui-final-polish

What this skill does

# UI Final Polish

Apply a restrained final polish pass to an existing UI component or screen.

Use this skill when the job is to make something feel cleaner, sharper, and more production-ready while preserving the current design. This skill is not a redesign skill.

If the user is asking how to structure, name, organize, package, or hand off a design for code, use `pencil-ui-structure` first and only use this skill afterward for visual polish.

Short usage name:

- `ui-final-polish`

## Goals

- Preserve the existing composition, visual direction, component role, and design intent
- Strengthen text hierarchy
- Improve spacing rhythm and readability
- Fix weak or awkward composition
- Make actions feel properly anchored
- Preserve the existing style unless the user explicitly asks for redesign

## Non-Goals

- Do not create a new visual direction
- Do not reinterpret the component's aesthetic
- Do not change the component category, product role, or hierarchy
- Do not broadly retheme colors, materials, effects, typography, or spacing
- Do not apply a style guide as a full redesign unless the user explicitly asks for a redesign
- Do not make changes because they are "more beautiful" if they do not solve a concrete polish issue
- Do not replace a user's preferred design with your preferred design
- Do not silently change multiple unrelated areas when the user named one issue or node

## Default Stance

- Polish is a scalpel, not a redesign pass
- Do not redesign when polish is requested
- Keep the current visual language, density, and dark/light mood
- Prefer surgical fixes over broad stylistic changes
- Prefer hierarchy and spacing fixes before introducing new visual elements
- Avoid unnecessary gradients, glows, heavy shadows, or decorative effects unless they improve hierarchy or usability
- Remove friction, not personality
- Polish should improve clarity and confidence without changing the product identity
- If a change would be visible as a new style direction, pause and either avoid it or ask first
- If the user says "do not redesign", treat that as a hard constraint

## Review Order

Check in this order:

1. User-stated problem or requested node
2. Current component role and intended visual category
3. Existing visual language that must be preserved
4. Text hierarchy and readability
5. Spacing and alignment
6. Action placement
7. Content width, scroll, and resizing behavior
8. Effects/material cleanup only if needed
9. Final production-clean pass

## Core Heuristics

- A polished UI should feel obvious, calm, and intentional
- If everything feels important, nothing is important
- Consistent spacing usually matters more than additional styling
- Visual emphasis should follow product importance, not decoration
- A component should feel visually stable before it feels visually impressive
- Misalignment is usually more damaging than weak styling
- Hierarchy should be created with spacing and contrast before color and effects
- Every polish edit should have a job: improve hierarchy, readability, alignment, affordance, or material separation
- If a change only makes the component more decorative, treat it as suspect until the hierarchy is stable
- The smallest effective change is usually the best change
- When preserving a finished design, "less changed" is a quality metric
- If two fixes both work, choose the one that changes fewer properties

## Polish Decision Rules

Before editing, identify:

- User intent: what specific thing did they ask to improve?
- Preservation target: what must remain recognizably the same after the pass?
- Foreground: the element the user should act on or read first
- Support layer: secondary context that should stay visible but quieter
- Background: decorative or environmental content that must not compete
- Interaction target: the thing that should feel clickable, draggable, editable, or selected

Then make the smallest change that clarifies the relationship between those layers.

If the user gave a specific node, do not touch sibling nodes unless the named node cannot be judged or fixed without its immediate context.

If the user gave a specific issue, fix that issue only. Examples:

- "contrast" means adjust contrast, not layout, mood, or component structure.
- "spacing" means adjust spacing/alignment, not palette or effects.
- "make it match DESIGN.md" means map the existing component to the closest category in the design doc, not redesign it into another category.
- "this part is good" means preserve that part exactly unless a tiny mechanical fix is required.

Use this priority order:

1. Preserve the current design intent
2. Fix the named issue
3. Fix obvious readability/accessibility problems inside the named scope
4. Fix spacing and alignment inside the named scope
5. Tune shadows, highlights, fills, and glows only if they are the problem
6. Remove anything that competes with the primary action or primary content

## What Good Looks Like

### Structure and Composition

- The component should have one clear parent layout
- Major areas should read in a stable order: header, content, metadata, actions
- Resize behavior should be intentional: fixed viewport, fill container, or fit content
- Avoid making layouts overly dense. Preserve breathable negative space
- Do not rearrange major regions unless the user asks for layout work
- Do not add or remove product content during polish unless it is clearly decorative noise

### Typography and Hierarchy

- Title should clearly dominate
- Subtitle should support, not compete
- Labels should be quieter than values
- Helper copy and lists should sit below values in emphasis
- Long text blocks should maintain comfortable reading width
- Avoid large blocks of equally emphasized text

### Actions and Dark UI

- Primary actions should feel anchored to the component, not visually detached
- Bottom actions should align with the same width and padding system as the card
- In dark interfaces, hierarchy should come primarily from contrast and spacing, not saturation

## Typical Fixes

- Fix spacing, hierarchy, and alignment before adding decoration
- Tighten or loosen section gaps
- Lower secondary text contrast
- Reduce bullet or helper text size
- Improve line-height on paragraphs and lists
- Convert a floating button into a proper child of the card
- Reduce overly long line width in text-heavy areas
- Change inner viewport from fixed height to fill container when the shell should stretch
- Change shell height to fit content when clipping is artificial
- Reduce visual noise before introducing new styling
- Replace an overly strong stroke with a quieter stroke
- Reduce an effect that competes with content
- Make a primary action clearer without changing its component type
- Preserve successful local details while fixing surrounding issues

## Change Budget

Default to a small change budget.

- `Tiny polish`: 1-3 property changes on the named node or direct children.
- `Normal polish`: a small set of related changes in one component area.
- `System polish`: only when the user explicitly asks to update a kit, system, or multiple components.

When in doubt, start with `Tiny polish`. Do not jump to `System polish` because a style guide exists.

Do not make broad replacements across a file unless the user explicitly asks for KIT/system-level cleanup.

## Effects Best Practices

Use effects to support hierarchy and material feel, not to compensate for weak structure.

Effects are especially likely to become redesign. Add new effects only when:

- the component already uses that material language
- the requested problem is about depth, contrast, or material separation
- the effect remains weaker than the primary content/action
- the user did not ask to keep the current material exactly

### Shadows

- Assume a single light source per screen. Default to light coming from above, so shadows fall downward.
- Use the blur-to-offset rule as a starting point: `blur = y * 2`.
- Avoid pure black shad