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. ClassName boundaries
Skill / UI / Tailwind

ClassName boundaries

Use component APIs for intended variation instead of overriding design-system internals with className.

Goal

Keep component contracts meaningful and avoid style drift from consumer overrides.

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

Checks

1Prefer props, variants, slots, and composition over broad className overrides.
2Allow size-only className overrides where layout ownership clearly belongs to the caller.
3Use Tailwind v4 trailing important syntax when needed: `fixed!`, `bottom-0!`, `translate-x-0!`.
4If many consumers need the same override, promote it into the component API.

Avoid

1Passing long className strings into shared components to bypass their variants.
2Using older leading important utilities such as `!fixed` in Tailwind v4 code.
3Consumer overrides that change color, border, focus, radius, or typography semantics.

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