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 migration syntax
Skill / UI / Tailwind

Tailwind v4 migration syntax

Use v4 names and modifiers when replacing or reviewing v3-era Tailwind classes.

Goal

Avoid silent visual regressions from v3 names that still compile but mean something different in Tailwind v4.

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

Checks

1Use v4 scale names such as `shadow-xs`, `drop-shadow-xs`, `blur-xs`, `rounded-xs`, `outline-hidden`, and explicit `ring-3` where the old default mattered.
2Use slash opacity and v4 gradient names: `bg-black/50`, `text-white/50`, and `bg-linear-to-r`.
3Use trailing important syntax such as `bg-red-500!`, plus `shrink-*` and `grow-*` instead of `flex-shrink-*` and `flex-grow-*`.
4Use v4 CSS-variable shorthand and type hints: `bg-(--row-bg)`, `text-(color:--fg)`, and `text-(length:--size)`.
5Use underscores inside arbitrary list values, such as `grid-cols-[max-content_auto]`.

Avoid

1Keeping old classes such as `bg-opacity-*`, `text-opacity-*`, `bg-gradient-to-*`, prefix important utilities, `bg-[--var]`, or comma-separated arbitrary grid values.
2Assuming a bare v3 size still has the same rendered weight, radius, shadow, blur, ring, or outline behavior in v4.

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