better-ui

Applies design engineering principles to polish UI components, animations, icons, and surfaces.

Updated Aug 2, 2026
One-click install
npx skills add https://github.com/leonardoacosta/agents --skill better-ui-leonardoacosta
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: better-ui
Source: https://github.com/leonardoacosta/agents/tree/main/skills/better-ui
Command: npx skills add https://github.com/leonardoacosta/agents --skill better-ui-leonardoacosta

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Interfaces often feel subtly off due to small compounding details like mismatched border radii, jarring animations, or misaligned icons. This Skill provides concrete, opinionated rules and code recipes for reviewing and fixing those visual and motion details in frontend code. ## Core Features & Use Cases - Surface Polish: Enforces concentric border radius, optical alignment, layered box-shadows instead of decorative borders, and pure black/white image outlines for light and dark modes. - Motion Recipes: Provides exact patterns for interruptible CSS transitions, scale-on-press feedback, staggered enter animations, subtle exits, theme-switch transition suppression, and contextual icon cross-fades with or without Motion/Framer Motion. - Icon Consistency: Matches icon stroke weight to text weight, uses one currentColor SVG recolored per state, outline-by-default with fill for active states, and RTL flipping rules. - Structured Review Output: Defines a severity-scaled findings table, verification steps, and a Block/Needs changes/Approve verdict for standalone UI-polish reviews. - Use Case: When a user says a settings page "feels off", apply the principles to find nested cards sharing the same radius, a theme toggle smearing transitions across the page, and icons with hairline strokes beside semibold labels, then report fixes with before/after code. ## Quick Start Review this component for UI polish issues and report findings using the better-ui principles.

Frequently Asked Questions about better-ui

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make nested border radius look right in CSS?

Use concentric border radius: outer radius equals inner radius plus padding. For example, a card with 8px padding and a 12px inner radius needs a 20px outer radius. If padding exceeds 24px, treat the layers as separate surfaces instead.

How do I animate an icon state change without Framer Motion?

Keep both icons in the DOM with one absolutely positioned over the other, then cross-fade with CSS transitions using cubic-bezier(0.2, 0, 0, 1). Animate scale from 0.25 to 1, opacity from 0 to 1, and blur from 4px to 0 so both enter and exit animate smoothly.

Should I use CSS transitions or keyframe animations for interactive elements?

Use CSS transitions for interactive state changes like hover, toggles, and open/close because they can be interrupted and retargeted mid-animation. Reserve keyframe animations for one-shot staged sequences such as enter animations or loading states.

Why does my theme toggle animate the whole page slowly?

A theme flip changes color, background, border, and shadow on many elements at once, so every transition fires together and smears. Inject a stylesheet disabling all transitions, force a reflow, then remove it on the next frame; next-themes ships this as disableTransitionOnChange.

When should I use will-change in CSS animations?

Use will-change only for GPU-compositable properties like transform, opacity, and filter, and only when you notice first-frame stutter. Never use will-change: all, and avoid it for properties like background-color or padding that cannot be composited.

What icon stroke width should I use next to text?

Match the icon stroke to the adjacent text weight: 1.5px beside regular 400 text, 2px beside semibold 600, and 2.5px beside bold 700. Keep one stroke weight per icon set and never mix icon libraries on a single surface.