# UI Skills

> Opinionated constraints for building better interfaces with agents.

- Skill: `diegosouzapw/ui-skills` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/ui-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/ui-skills/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, Productivity
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/ui-skills

---


# UI Skills

Opinionated constraints for building better interfaces with agents.

## Stack

-   MUST use Tailwind CSS defaults (spacing, radius, shadows) before custom values
-   MUST use `motion-sv` (works like motion.dev for vue but its svelte) when JavaScript animation is required
-   SHOULD use `tw-animate-css` for entrance and micro-animations in Tailwind CSS
-   MUST use `cn` utility (`clsx` + `tailwind-merge`) for class logic

## Components

-   MUST use accessible component primitives for anything with keyboard or focus behavior (`bits-ui`)
-   MUST use the project’s existing component primitives first
-   NEVER mix primitive systems within the same interaction surface
-   SHOULD prefer [`bits-ui`](https://bits-ui.com/docs/introduction) for new primitives if compatible with the stack
-   MUST add an `aria-label` to icon-only buttons
-   NEVER rebuild keyboard or focus behavior by hand unless explicitly requested

## Interaction

-   MUST use an `AlertDialog` for destructive or irreversible actions
-   SHOULD use structural skeletons for loading states
-   NEVER use `h-screen`, use `h-svh`
-   MUST respect `safe-area-inset` for fixed elements
-   MUST show errors next to where the action happens
-   NEVER block paste in `input` or `textarea` elements

## Animation

-   NEVER add animation unless it is explicitly requested
-   MUST animate only compositor props (`transform`, `opacity`)
-   NEVER animate layout properties (`width`, `height`, `top`, `left`, `margin`, `padding`)
-   SHOULD avoid animating paint properties (`background`, `color`) except for small, local UI (text, icons)
-   SHOULD use `ease-out` on entrance
-   NEVER exceed `200ms` for interaction feedback
-   MUST pause looping animations when off-screen
-   MUST respect `prefers-reduced-motion`
-   NEVER introduce custom easing curves unless explicitly requested
-   SHOULD avoid animating large images or full-screen surfaces

## Typography

-   MUST use `text-balance` for headings and `text-pretty` for body/paragraphs
-   MUST use `tabular-nums` for data
-   SHOULD use `truncate` or `line-clamp` for dense UI
-   NEVER modify `letter-spacing` (`tracking-`) unless explicitly requested

## Layout

-   MUST use a fixed `z-index` scale (no arbitrary `z-x`)
-   SHOULD use `size-x` for square elements instead of `w-x` + `h-x`

## Performance

-   NEVER animate large `blur()` or `backdrop-filter` surfaces
-   NEVER apply `will-change` outside an active animation
-   NEVER use `useEffect` for anything that can be expressed as render logic

## Design

-   NEVER use gradients unless explicitly requested
-   NEVER use purple or multicolor gradients
-   NEVER use glow effects as primary affordances
-   SHOULD use Tailwind CSS default shadow scale unless explicitly requested
-   MUST give empty states one clear next action
-   SHOULD limit accent color usage to one per view
-   SHOULD use existing theme or Tailwind CSS color tokens before introducing new ones