Refined UI

An opinionated, customizable superset of shadcn/ui

AgentsPrimitivesSkillsSkins
Guides
  • Overview
  • Get started
  • Shadcn compatibility
  • Architecture
  • Agent surface
CSS-first
  • CSS-first interactivity
  • CSS-first motion & sizing
React code quality
  • Derive, do not duplicate
  • Remount state boundaries
  • One responsibility per file
  • Real stack tests
UI / Tailwind
  • Use existing components first
  • Token discipline
  • Class Name boundaries
  • Tailwind v4 CSS configuration
  • Tailwind v4 migration syntax
  • Generated utilities before arbitrary values
  • Variant-first styling
  • Tailwind v4 capabilities
  • Tailwind v4 behavior & motion
UX
  • State continuity
  • Provenance without noise
  • Dense but scannable
  • Say it once
Refined UI registry
  • Skin authoring
  • Extension authoring
  • Registry-first DX
  • Skin completeness
  • Refined UI composition
  • Runtime-agnostic UI
  • Compound components DX
  • Context vs props
  1. Skills
  3. Tailwind v4 behavior & motion
Skill / UI / Tailwind

Tailwind v4 behavior & motion

Account for v4 behavior changes around transforms, hover, default colors, variant order, spacing, and motion.

Goal

Prevent subtle interaction and visual bugs that come from assuming Tailwind v3 runtime behavior still applies.

Styling rules for Tailwind v4, token discipline, component reuse, and className boundaries.

Checks

1Transition individual transform properties with utilities such as `transition-[opacity,scale]`; reset transforms with `scale-none`, `rotate-none`, and `translate-none`.
2Treat `hover:` as hover-capable only and keep required functionality available on touch devices.
3Set explicit border, divide, ring, and outline colors when the color matters because v4 defaults these to `currentColor`.
4Stack variants left to right, for example `*:first:pt-0`, and prefer flex or grid `gap-*` over `space-x-*` or `space-y-*`.
5Gate decorative animation with `motion-safe:` and `motion-reduce:`, and put reusable animations in `--animate-*` tokens with matching `@keyframes`.

Avoid

1`transition-[opacity,transform]` when the animated property is now `scale`, `rotate`, or `translate`.
2Required actions that are only discoverable or usable through hover.
3Hardcoded local animation durations that bypass motion tokens and reduced-motion behavior.

Source

Imported as local Refined UI skill guidance, with this repo owning the final wording.

Mastra tailwind-v4
../mastra/.claude/skills/tailwind-v4

On this page

  • Checks
  • Avoid
  • Source