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. Remount state boundaries
Skill / React code quality

Remount state boundaries

Reset state by changing component identity or loading boundaries, not by syncing with effects.

Goal

When an upstream identity changes, remount the stateful branch so initializers naturally receive fresh data.

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

Checks

1Lift the discriminant, such as selected id or route param, above the stateful form or editor.
2Render a skeleton or keyed branch while new data loads so stale state cannot flash.
3Use a key as the narrow fallback when there is no async boundary to restructure around.

Avoid

1useEffect blocks that call several setters to reset a form after props change.
2Rendering an editor once with the previous entity and correcting it after an effect runs.

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