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. Real stack tests
Skill / React code quality

Real stack tests

Prefer tests that drive production hooks, clients, routing, and cache behavior with only the network mocked.

Goal

Make a green test prove the real UI path, not a mocked copy of the implementation.

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

Checks

1Render through the real provider stack when the component depends on cache, router, or client behavior.
2Mock network responses at the boundary and use production response types where available.
3Assert behavior visible to the user rather than duplicating implementation class strings or hook internals.

Avoid

1vi.mock for local hooks, services, auth gates, or SDK calls that the component is meant to exercise.
2Bespoke test-only data shapes that drift from production response types.

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