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. Runtime-agnostic UI
Skill / Refined UI registry

Runtime-agnostic UI

Keep core visual surfaces independent from model runners, stores, and transport lifecycles.

Goal

Keep Refined UI core components independent from model runners, message stores, and transport lifecycles.

Registry-first guidance for installable Refined UI components, skins, hooks, and blocks.

Checks

1Core components render from plain props and children without requiring a runtime provider.
2Context is only used for local UI anatomy or behavior, such as role, density, open state, copy value, or submit state.
3Provider-specific code lives in usage examples or host-app mapping functions, not installed core files.
4Blocks compose UI components and callbacks without owning model calls, streaming transport, persistence, branching, or tool execution.

Avoid

1AssistantRuntimeProvider-style APIs that make UI components depend on one runtime shape.
2Importing Mastra, AI SDK, LangChain, or custom runner packages from skins or core components.
3Hiding message/thread/run lifecycle inside visual components.
4Installing runner adapters as the default path for rendering the UI.

On this page

  • Checks
  • Avoid