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. Use existing components first
Skill / UI / Tailwind

Use existing components first

Start from the local design system or registry primitive before creating a new styled element.

Goal

Preserve visual consistency and accessibility by reusing the closest existing component contract.

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

Checks

1Search existing Refined UI primitives, hooks, and examples before adding a new surface.
2Use variants or composition slots when the existing component already owns the behavior.
3Create a new primitive only when the required behavior or anatomy is genuinely missing.

Avoid

1Duplicating a button, menu, select, dialog, sidebar, or scroll behavior with raw divs.
2Adding a component to a shared design-system folder without an explicit shared ownership reason.

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