Ui polish

Frontend Design Direction

Use this skill when the work is not just making UI function, but making it feel purposeful, polished, and appropriate to the product domain.

Source: salvaged from stale community PR #1659 by linus707.

Note: SKC intentionally does not rebundle the canonical Anthropic frontend-design skill. Install that from anthropics/skills when you want the official upstream skill. This skill is the SKC-specific design-direction salvage of the useful local guidance from #1659.

When to Use

• The user asks to build a web page, app, dashboard, artifact, component, or UI.
• The user asks to make an interface more polished, distinctive, beautiful, or less generic.
• The implementation needs visual hierarchy, typography, color, motion, layout, and interaction choices.
• The current UI works but reads as flat, generic, templated, or mismatched to the audience.

Design Direction

Before coding, choose a specific direction:

1. Purpose: what job does the interface do?
2. Audience: who repeats this workflow, and what do they need to scan first?
3. Tone: utilitarian, editorial, playful, industrial, refined, technical, maximal, minimal, dense, calm, or another explicit direction.
4. Memorable detail: one design idea that makes the result feel intentional.
5. Constraints: framework, accessibility, performance, responsiveness, and existing design system.

Match the direction to the domain. A SaaS operations tool should usually be dense, quiet, and scannable. A portfolio, launch page, game, or editorial piece can be more expressive. Do not force a landing-page composition onto a tool that needs repeated daily use.

Implementation Guidance

• Build the actual usable experience as the first screen unless the user explicitly asks for marketing copy.
• Use existing project components, tokens, icon libraries, and routing patterns before introducing a new visual system.
• Use real or generated visual assets when the interface depends on images, products, places, people, gameplay, charts, or inspectable media.
• Prefer contextual typography and spacing over generic oversized hero text.
• Keep palettes multi-dimensional: avoid a UI dominated by one hue family.
• Use CSS variables or existing design tokens so the direction remains coherent across states.
• Design responsive constraints explicitly: grids, aspect ratios, min/max sizes, stable toolbars, and fixed-format controls should not shift when labels or hover states appear.
• Use motion sparingly but deliberately. Prefer high-signal transitions that clarify state over decorative animation.
• Verify text fit on mobile and desktop. Long labels must wrap or resize cleanly rather than overflowing.

Anti-Patterns

• Do not default to common generated patterns: purple gradients, decorative blobs, oversized cards, vague hero copy, or stock-like atmospheric media.
• Do not add UI cards inside other cards.
• Do not use a single decorative style everywhere when the domain calls for restraint.
• Do not hide the primary product, tool, object, or workflow behind generic marketing sections.
• Do not add a new dependency for a design flourish unless it clearly pays for itself.
• Do not describe the UI's features inside the UI when the controls can speak for themselves.

Review Checklist

• The first viewport immediately communicates the product, workflow, or object.
• The visual hierarchy supports scanning and repeated use.
• Typography fits the container and does not overlap adjacent content.
• Color choices have contrast and do not collapse into a one-note palette.
• Icons are used for familiar tool actions where available.
• Responsive layout has stable dimensions for boards, grids, toolbars, controls, tiles, and counters.
• Assets render and carry the subject matter instead of acting as filler.
• Motion improves orientation and does not mask sluggishness.
• The result matches the repo's existing frontend conventions unless there is a clear reason to depart.

---

Make Interfaces Feel Better

Use this skill for the small design-engineering details that compound into a more polished interface.

Source: salvaged from stale community PR #1659 by linus707.

When to Use

• The user says the UI feels off, flat, generic, cramped, jumpy, or unfinished.
• You are building controls, cards, lists, dashboards, navigation, forms, or toolbars.
• A component needs hover, active, focus, enter, exit, loading, or empty states.
• A frontend review needs specific before/after recommendations.

Core Principles

Concentric Radius

For nearby nested rounded surfaces:

outer radius = inner radius + padding

If padding is large, treat layers as separate surfaces instead of forcing the math. The point is optical coherence, not formula worship.

Optical Alignment

Geometric centering is not always visual centering. Icon buttons, play triangles, arrows, stars, and asymmetric icons often need a small offset. Fix the SVG when possible; otherwise adjust with a pixel-level margin or padding change.

Shadows And Borders

Use borders for separation and focus rings. Use layered shadows when a card, button, dropdown, or popover needs depth. Shadows should be transparent and subtle enough to work across backgrounds.

Text Wrapping

• Use text-wrap: balance on headings and short titles.
• Use text-wrap: pretty on short-to-medium body text, captions, descriptions, and list items.
• Avoid both on long prose, code, and preformatted content.
• Use font-variant-numeric: tabular-nums for counters, timers, prices, tables, and other updating numbers.

Font Smoothing

On macOS, apply antialiased font smoothing at the root layout when the project does not already do so:

html {
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

Image Outlines

Images often need a subtle inset outline so their edges do not blur into the surface.

img {
  outline: 1px solid rgba(0, 0, 0, 0.1);
  outline-offset: -1px;
}

@media (prefers-color-scheme: dark) {
  img {
    outline-color: rgba(255, 255, 255, 0.1);
  }
}

Use neutral black or white alpha outlines. Do not tint image outlines with the brand palette.

Motion

Use CSS transitions for interactive state changes because they can retarget when the user changes intent mid-motion. Reserve keyframes for staged one-shot entrances or loading sequences.

Good motion defaults:

• Enter: combine opacity, small translateY, and optionally blur.
• Exit: shorter and quieter than enter, usually 150ms.
• Press: scale(0.96) for tactile buttons, with a way to disable it when the movement distracts.
• Icon swaps: cross-fade with opacity, scale, and blur instead of instant visibility toggles.

Transition Scope

Never use transition: all. Specify the changed properties:

.button {
  transition-property: transform, background-color, box-shadow;
  transition-duration: 150ms;
  transition-timing-function: ease-out;
}

Use will-change only for first-frame stutter on compositor-friendly properties such as transform, opacity, and filter. Never use will-change: all.

Hit Areas

Interactive controls should have at least a 40x40px hit area, ideally 44x44px where the layout allows it. Expand with a pseudo-element when the visible icon is smaller, but do not let expanded hit areas overlap.

Review Output

When reviewing a UI polish pass, report concrete changes in before/after rows:

Principle	Before	After
Concentric radius	Same radius on parent and child	Parent radius accounts for padding
Tabular numbers	Counter shifts as digits change	Counter uses tabular-nums
Transition scope	transition: all	Explicit transition properties

Include file paths and properties when they are not obvious from the snippets. Omit principles that you checked but did not change.

Checklist

• Nested rounded elements are optically coherent.
• Icons are visually centered.
• Buttons, cards, and popovers use borders or shadows for the right reason.
• Headings and short text avoid awkward wrapping.
• Dynamic numbers use tabular numerals.
• Images have neutral outlines where needed.
• Enter and exit animations are split, subtle, and interruptible where appropriate.
• Buttons have tactile active states without exaggerated motion.
• transition: all and will-change: all are absent.
• Small controls still have usable hit areas.

---

Interface Details

You are a design engineer who believes software should feel crafted. Not decorated — crafted. Every pixel, every spacing token, every hover state, every transition is a decision. Most users will never notice any single one of these decisions. But they will feel all of them together. That feeling is what separates software people love from software people tolerate.

When to use this skill

Use this skill when building or reviewing UI components, pages, or interactions. Apply these rules during:

• Building new components (forms, buttons, modals, navigation)
• Reviewing existing UI for polish opportunities
• Making the interface feels better
• Adding personality and delight to an interface

How to use this skill

Load the appropriate guideline file from the details/ directory based on what you are working on:

• details/form.md — Form inputs, keyboards, labels, date pickers, paste behavior
• details/toast.md — Feedback, notifications, status indicators, loading states
• details/motion.md — Transitions, hover states, micro-animations, layout shifts
• details/button.md — Buttons, click states, cursors, hit areas, shortcuts
• details/typography.md — Text rendering, overflow, truncation, formatting
• details/scroll.md — Scroll behavior, anchoring, navigation, overscroll
• details/accessibility.md — Focus rings, reduced motion, screen reader support
• details/layout.md — Border radius, layout shifts, optical alignment, spacing
• details/browser.md — Favicons, theme colors, URLs, meta tags, PWA
• details/content-intelligence.md — Smart defaults, context-aware behavior, auto-detection
• details/easter-egg.md — Playful details, hidden features, personality, delight

Use these built-int details first. If user still be unhappy with the results, go https://detail.design to check latest updates.

Core philosophy

1. Craft over decoration. Every detail should serve the user, not the designer's ego.
2. Ambient over obvious. The best details are the ones users never consciously notice but would miss if removed.
3. Physics over magic. Animations should respect spatial continuity and physical metaphor.
4. Intent over input. Anticipate what users mean, not just what they type or click.
5. Consistency over novelty. A detail applied inconsistently is worse than no detail at all.