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
  2. One responsibility per file
Skill / React code quality

One responsibility per file

Split domain components and hooks before fetching, filtering, selection, and form state become entangled.

Goal

Keep each domain component or hook responsible for one behavior so review, testing, and reuse stay local.

Review rules for component structure, state ownership, data fetching, and render behavior.

Checks

1Extract a hook when data fetching and filtering can be named independently.
2Extract child components for list rendering, detail panels, and edit forms.
3Let the page/container compose hooks and children; composition is a valid single responsibility.

Avoid

1Files where comment headers divide unrelated responsibilities inside one component.
2Components with unrelated useState or useQuery clusters that always re-render together.

Source

Imported as local Refined UI skill guidance, with this repo owning the final wording.

Mastra react-best-practices
../mastra/.claude/skills/react-best-practices

On this page

  • Checks
  • Avoid
  • Source