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. Derive, do not duplicate
Skill / React code quality

Derive, do not duplicate

Avoid second sources of truth in component props, hook parameters, and local state.

Goal

Compute values from the source already in scope instead of asking callers to pass both source and derivative.

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

Checks

1Derive itemCount, isEmpty, selected item, filtered count, and booleans from the data already passed in.
2Keep a single owner for each value; callers should not synchronize pairs such as items plus itemCount.
3When state mirrors props, check whether the value should be derived during render instead.

Avoid

1Props such as itemCount next to items, isEmpty next to a list, or selectedName next to selectedId and entities.
2Effects whose only job is to keep duplicated state synchronized.

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