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. Variant-first styling
Skill / UI / Tailwind

Variant-first styling

Check Tailwind variants before adding handwritten selectors, style props, or React state for styling.

Goal

Express styling reactions with variants the compiler understands instead of duplicating browser state in CSS or JavaScript.

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

Checks

1Use pseudo, ARIA, and data variants such as `active:`, `focus-visible:`, `aria-expanded:`, `data-[state=open]:`, and boolean `data-current:`.
2Use relationship variants such as `group-*`, `peer-*`, `has-*`, `in-*`, `*:`, and `**:` before adding parent-state selectors or event handlers.
3Use capability and structural variants such as `pointer-coarse:`, `pointer-fine:`, `first:`, `last:`, `odd:`, `nth-*`, and `not-*`.
4Use built-in mask and container-query utilities such as `mask-b-from-80%`, `mask-t-from-*`, `@container`, `@sm:`, and `@max-md:`.

Avoid

1Handwritten pseudo-state CSS or `style` props when a Tailwind variant directly models the state.
2React hover, focus, or child-presence state whose only purpose is toggling a style a selector variant can express.

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