# Interface

> Design engineering principles for making interfaces feel polished. Use when building UI components, reviewing frontend code, implementing animations, hover states, shadows, borders, typography, micro-interactions, enter/exit animations, or any visual detail work. Triggers on UI polish, design details, "make it feel better", "feels off", stagger animations, border radius, optical alignment, font s…

- **Type:** Skill
- **Install:** `agentstack add skill-wellwelwel-blue-spec-interface`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [wellwelwel](https://agentstack.voostack.com/s/wellwelwel)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [wellwelwel](https://github.com/wellwelwel)
- **Source:** https://github.com/wellwelwel/blue-spec/tree/main/.claude/skills/interface
- **Website:** https://bluespec.weslley.io

## Install

```sh
agentstack add skill-wellwelwel-blue-spec-interface
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Details that make interfaces feel better

Great interfaces rarely come from a single thing. It's usually a collection of small details that compound into a great experience. Apply these principles when building or reviewing UI code.

## Quick Reference

| Category                      | When to Use                                                       |
| ----------------------------- | ----------------------------------------------------------------- |
| [Typography](typography.md)   | Text wrapping, font smoothing, tabular numbers                    |
| [Surfaces](surfaces.md)       | Border radius, optical alignment, shadows, hit areas              |
| [Animations](animations.md)   | Interruptible animations, enter/exit transitions, icon animations |
| [Performance](performance.md) | Transition specificity, `will-change` usage                       |

## Core Principles

### 1. Concentric Border Radius

Outer radius = inner radius + padding. Mismatched radii on nested elements is the most common thing that makes interfaces feel off.

### 2. Optical Over Geometric Alignment

When geometric centering looks off, align optically. Buttons with icons, play triangles, and asymmetric icons all need manual adjustment.

### 3. Shadows Over Borders

Layer multiple transparent `box-shadow` values for natural depth. Shadows adapt to any background; solid borders don't.

### 4. Interruptible Animations

Use CSS transitions for interactive state changes — they can be interrupted mid-animation. Reserve keyframes for staged sequences that run once.

### 5. Split and Stagger Enter Animations

Don't animate a single container. Break content into semantic chunks and stagger each with ~100ms delay.

### 6. Subtle Exit Animations

Use a small fixed `translateY` instead of full height. Exits should be softer than enters.

### 7. Contextual Icon Animations

Animate icons with `opacity`, `scale`, and `blur` instead of toggling visibility. Use exactly these values: scale from `0.25` to `1`, opacity from `0` to `1`, blur from `4px` to `0px`. If the project has `motion` or `framer-motion` in `package.json`, use `transition: { type: "spring", duration: 0.3, bounce: 0 }` — bounce must always be `0`. If no motion library is installed, keep both icons in the DOM (one absolute-positioned) and cross-fade with CSS transitions using `cubic-bezier(0.2, 0, 0, 1)` — this gives both enter and exit animations without any dependency.

### 8. Font Smoothing

Apply `-webkit-font-smoothing: antialiased` to the root layout on macOS for crisper text.

### 9. Tabular Numbers

Use `font-variant-numeric: tabular-nums` for any dynamically updating numbers to prevent layout shift.

### 10. Text Wrapping

Use `text-wrap: balance` on headings. Use `text-wrap: pretty` for body text to avoid orphans.

### 11. Skip Animation on Page Load

Use `initial={false}` on `AnimatePresence` to prevent enter animations on first render. Verify it doesn't break intentional entrance animations.

### 12. Never Use `transition: all`

Always specify exact properties: `transition-property: scale, opacity`. Tailwind's `transition-transform` covers `transform, translate, scale, rotate`.

### 13. Use `will-change` Sparingly

Only for `transform`, `opacity`, `filter` — properties the GPU can composite. Never use `will-change: all`. Only add when you notice first-frame stutter.

### 14. Minimum Hit Area

Interactive elements need at least 40×40px hit area. Extend with a pseudo-element if the visible element is smaller. Never let hit areas of two elements overlap.

## Common Mistakes

| Mistake                                | Fix                                               |
| -------------------------------------- | ------------------------------------------------- |
| Same border radius on parent and child | Calculate `outerRadius = innerRadius + padding`   |
| Icons look off-center                  | Adjust optically with padding or fix SVG directly |
| Hard borders between sections          | Use layered `box-shadow` with transparency        |
| Jarring enter/exit animations          | Split, stagger, and keep exits subtle             |
| Numbers cause layout shift             | Apply `tabular-nums`                              |
| Heavy text on macOS                    | Apply `antialiased` to root                       |
| Animation plays on page load           | Add `initial={false}` to `AnimatePresence`        |
| `transition: all` on elements          | Specify exact properties                          |
| First-frame animation stutter          | Add `will-change: transform` (sparingly)          |
| Tiny hit areas on small controls       | Extend with pseudo-element to 40×40px             |

## Review Output Format

Always present changes as a markdown table with **Before** and **After** columns. Include every change you made — not just a subset. Never list findings as separate "Before:" / "After:" lines outside of a table. Group changes by principle using a heading above each table, and keep each row focused on a single diff so the reader can scan the whole list quickly.

### Example

#### Concentric border radius

| Before                                                      | After                                                          |
| ----------------------------------------------------------- | -------------------------------------------------------------- |
| `rounded-xl` on card + `rounded-xl` on inner button (`p-2`) | `rounded-2xl` on card (`12 + 8`), `rounded-lg` on inner button |
| `border-radius: 16px` on both nested surfaces               | Outer `24px`, inner `16px` with `8px` padding                  |

#### Tabular numbers

| Before                                     | After                                              |
| ------------------------------------------ | -------------------------------------------------- |
| `{count}` on animated counter | `{count}`    |
| Default numerals on timer                  | Added `font-variant-numeric: tabular-nums` to root |

Rows should cite the specific file and the specific property that changed when it isn't obvious from the snippet. If a principle was reviewed but nothing needed to change, omit that table entirely — empty tables add noise.

## Review Checklist

- [ ] Nested rounded elements use concentric border radius
- [ ] Icons are optically centered, not just geometrically
- [ ] Shadows used instead of borders where appropriate
- [ ] Enter animations are split and staggered
- [ ] Exit animations are subtle
- [ ] Dynamic numbers use tabular-nums
- [ ] Font smoothing is applied
- [ ] Headings use text-wrap: balance
- [ ] AnimatePresence uses `initial={false}` for default-state elements
- [ ] No `transition: all` — only specific properties
- [ ] `will-change` only on transform/opacity/filter, never `all`
- [ ] Interactive elements have at least 40×40px hit area

## Reference Files

- [typography.md](typography.md) — Text wrapping, font smoothing, tabular numbers
- [surfaces.md](surfaces.md) — Border radius, optical alignment, shadows
- [animations.md](animations.md) — Interruptible animations, enter/exit transitions, icon animations
- [performance.md](performance.md) — Transition specificity, `will-change` usage

## Credits

Adapted from [make-interfaces-feel-better](https://github.com/jakubkrehel/make-interfaces-feel-better/tree/384562064fcdd99778fcbafd8729626fe6aab02f) by [Jakub Krehel](https://github.com/jakubkrehel).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [wellwelwel](https://github.com/wellwelwel)
- **Source:** [wellwelwel/blue-spec](https://github.com/wellwelwel/blue-spec)
- **License:** MIT
- **Homepage:** https://bluespec.weslley.io

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-wellwelwel-blue-spec-interface
- Seller: https://agentstack.voostack.com/s/wellwelwel
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.