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. Generated utilities before arbitrary values
Skill / UI / Tailwind

Generated utilities before arbitrary values

Prefer Tailwind v4's generated utility scales and shorthand forms before arbitrary bracket values.

Goal

Keep class strings readable, mergeable, and statically detectable while still allowing precise one-off values when they are genuinely needed.

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

Checks

1Use generated spacing and sizing utilities such as `min-w-100`, `w-150`, `size-6`, `mt-17`, `grid-cols-15`, `h-dvh`, `w-dvw`, `h-lh`, and container max-width utilities when they fit.
2Use boolean data variants such as `data-current:opacity-100`; keep bracketed values for real values like `data-[state=open]:opacity-100`.
3Keep class strings complete and statically detectable by mapping props to full class names, for example `{ success: "bg-positive1" }[tone]`.
4Use square brackets for true one-offs such as `max-h-[calc(100dvh-3rem)]`, `grid-cols-[200px_minmax(0,1fr)]`, and arbitrary properties like `[mask-type:luminance]`.

Avoid

1Reaching for bracket values when a generated v4 utility exists.
2Building Tailwind class fragments dynamically, such as concatenating `bg-`, a tone, and `-500`, because the compiler cannot reliably detect them.

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