|
| 1 | +--- |
| 2 | +description: Opinionated constraints for building better interfaces with agents |
| 3 | +mode: subagent |
| 4 | +tools: |
| 5 | + read: true |
| 6 | + write: true |
| 7 | + edit: true |
| 8 | + bash: true |
| 9 | + glob: true |
| 10 | + grep: true |
| 11 | + webfetch: true |
| 12 | + task: true |
| 13 | +--- |
| 14 | + |
| 15 | +# UI Skills |
| 16 | + |
| 17 | +<!-- AI-CONTEXT-START --> |
| 18 | + |
| 19 | +## Quick Reference |
| 20 | + |
| 21 | +- **Purpose**: Opinionated constraints for building better interfaces with agents |
| 22 | +- **Source**: https://www.ui-skills.com/llms.txt |
| 23 | +- **Stack**: Tailwind CSS, motion/react, tw-animate-css, clsx + tailwind-merge |
| 24 | + |
| 25 | +**When to apply these constraints**: |
| 26 | +- Building React/Next.js interfaces |
| 27 | +- Working with Tailwind CSS |
| 28 | +- Adding animations or transitions |
| 29 | +- Creating accessible components |
| 30 | +- Optimizing UI performance |
| 31 | + |
| 32 | +**Key Principles**: |
| 33 | +- Use Tailwind defaults before custom values |
| 34 | +- Use accessible component primitives (Base UI, React Aria, Radix) |
| 35 | +- Never add animation unless explicitly requested |
| 36 | +- Respect `prefers-reduced-motion` |
| 37 | +- Never block paste in inputs |
| 38 | + |
| 39 | +<!-- AI-CONTEXT-END --> |
| 40 | + |
| 41 | +## Stack |
| 42 | + |
| 43 | +- MUST use Tailwind CSS defaults (spacing, radius, shadows) before custom values |
| 44 | +- MUST use `motion/react` (formerly `framer-motion`) when JavaScript animation is required |
| 45 | +- SHOULD use `tw-animate-css` for entrance and micro-animations in Tailwind CSS |
| 46 | +- MUST use `cn` utility (`clsx` + `tailwind-merge`) for class logic |
| 47 | + |
| 48 | +## Components |
| 49 | + |
| 50 | +- MUST use accessible component primitives for anything with keyboard or focus behavior (`Base UI`, `React Aria`, `Radix`) |
| 51 | +- MUST use the project's existing component primitives first |
| 52 | +- NEVER mix primitive systems within the same interaction surface |
| 53 | +- SHOULD prefer [`Base UI`](https://base-ui.com/react/components) for new primitives if compatible with the stack |
| 54 | +- MUST add an `aria-label` to icon-only buttons |
| 55 | +- NEVER rebuild keyboard or focus behavior by hand unless explicitly requested |
| 56 | + |
| 57 | +## Interaction |
| 58 | + |
| 59 | +- MUST use an `AlertDialog` for destructive or irreversible actions |
| 60 | +- SHOULD use structural skeletons for loading states |
| 61 | +- NEVER use `h-screen`, use `h-dvh` |
| 62 | +- MUST respect `safe-area-inset` for fixed elements |
| 63 | +- MUST show errors next to where the action happens |
| 64 | +- NEVER block paste in `input` or `textarea` elements |
| 65 | + |
| 66 | +## Animation |
| 67 | + |
| 68 | +- NEVER add animation unless it is explicitly requested |
| 69 | +- MUST animate only compositor props (`transform`, `opacity`) |
| 70 | +- NEVER animate layout properties (`width`, `height`, `top`, `left`, `margin`, `padding`) |
| 71 | +- SHOULD avoid animating paint properties (`background`, `color`) except for small, local UI (text, icons) |
| 72 | +- SHOULD use `ease-out` on entrance |
| 73 | +- NEVER exceed `200ms` for interaction feedback |
| 74 | +- MUST pause looping animations when off-screen |
| 75 | +- MUST respect `prefers-reduced-motion` |
| 76 | +- NEVER introduce custom easing curves unless explicitly requested |
| 77 | +- SHOULD avoid animating large images or full-screen surfaces |
| 78 | + |
| 79 | +## Typography |
| 80 | + |
| 81 | +- MUST use `text-balance` for headings and `text-pretty` for body/paragraphs |
| 82 | +- MUST use `tabular-nums` for data |
| 83 | +- SHOULD use `truncate` or `line-clamp` for dense UI |
| 84 | +- NEVER modify `letter-spacing` (`tracking-`) unless explicitly requested |
| 85 | + |
| 86 | +## Layout |
| 87 | + |
| 88 | +- MUST use a fixed `z-index` scale (no arbitrary `z-x`) |
| 89 | +- SHOULD use `size-x` for square elements instead of `w-x` + `h-x` |
| 90 | + |
| 91 | +## Performance |
| 92 | + |
| 93 | +- NEVER animate large `blur()` or `backdrop-filter` surfaces |
| 94 | +- NEVER apply `will-change` outside an active animation |
| 95 | +- NEVER use `useEffect` for anything that can be expressed as render logic |
| 96 | + |
| 97 | +## Design |
| 98 | + |
| 99 | +- NEVER use gradients unless explicitly requested |
| 100 | +- NEVER use purple or multicolor gradients |
| 101 | +- NEVER use glow effects as primary affordances |
| 102 | +- SHOULD use Tailwind CSS default shadow scale unless explicitly requested |
| 103 | +- MUST give empty states one clear next action |
| 104 | +- SHOULD limit accent color usage to one per view |
| 105 | +- SHOULD use existing theme or Tailwind CSS color tokens before introducing new ones |
| 106 | + |
| 107 | +## Related Resources |
| 108 | + |
| 109 | +- [UI Skills](https://www.ui-skills.com/) |
| 110 | +- [Base UI](https://base-ui.com/react/components) |
| 111 | +- [React Aria](https://react-spectrum.adobe.com/react-aria/) |
| 112 | +- [Radix Primitives](https://www.radix-ui.com/primitives) |
| 113 | +- [motion/react](https://motion.dev/) |
| 114 | +- [tw-animate-css](https://github.com/Wombosvideo/tw-animate-css) |
| 115 | +- [shadcn/ui](https://ui.shadcn.com/) - See `tools/ui/shadcn.md` |
0 commit comments