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. Say it once
Skill / UX

Say it once

Cut redundant AI-slop copy so labels, controls, and state carry the obvious meaning.

Goal

Make every visible sentence earn its space by adding a decision, constraint, consequence, or recovery path.

Interaction and information-design checks for agent-facing product surfaces.

Checks

1Trust clear labels, icons, toggles, and placement to explain standard interactions.
2Before adding helper text, name the new information it adds beyond the label and control.
3Reserve descriptions for unusual behavior, irreversible actions, hidden constraints, permissions, delays, or failure recovery.
4Use progressive disclosure for secondary context so frequent users do not scan past repeated explanations.

Avoid

1Label-description pairs that restate the same action, such as "Change theme" plus "This changes the theme."
2Always-visible paragraphs under every input, toggle, tab, or card because generated UI looks more complete with copy.
3Explaining standard control mechanics instead of naming the user outcome.
4Empty states that describe the product when they should give the next useful action or reason.

Source

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

Mastra Playground UI compact controls
../mastra/packages/playground-ui/src/ds/components/Button/Button.tsx

On this page

  • Checks
  • Avoid
  • Source