control/uialpha
Guides
  • Overview
  • Get started
  • Shadcn compatibility
  • Architecture
  • Agent surface
  • Theme accessibility
  • Theme AI builder
Skins
  • Skinning Control UI
CSS-first
  • CSS-first interactivity
  • CSS-first motion & sizing
React code quality
  • Derive, do not duplicate
  • Remount state boundaries
  • Explicit names instead of comments
  • One responsibility per file
  • Keep input and output AP Is narrow
  • Keep context necessary, narrow, and stable
  • Do not query the DOM in React
  • Real stack tests
  • Test rendered output, not class names
Architecture
  • Cohesive folders
  • Single source of truth
UI / Tailwind
  • Use existing components first
  • Token discipline
  • Class Name boundaries
  • Tailwind v4 CSS configuration
  • Tailwind v4 migration syntax
  • First-class utilities before custom CSS
  • Variant-first styling
  • Tailwind v4 capabilities
  • Tailwind v4 behavior & motion
UX
  • State continuity
  • Provenance without noise
  • Dense but scannable
  • Say it once
Control UI registry
  • Skin authoring
  • Extension authoring
  • Registry-first DX
  • Skin completeness
  • Control UI composition
  • Runtime-agnostic UI
  • Compound components DX
  • Context vs props
Create app

An opinionated, customizable superset of shadcn/ui

  • GitHub9
No results found.
Guides
Overview
An owned-source registry of primitives, agent surfaces, complete blocks, and swappable skins.
Guide
Get started
Choose a skin, install a component or complete block, wire its CSS, and compose your application runtime.
Guide
shadcn compatibility
shadcn registry, token, and ownership conventions without writing to components/ui.
Guide
Architecture
Runtime ownership, skin layering, customization paths, and registry derivation.
Guide
Agent surface
Inspect and install registry items through HTTP, shadcn manifests, static metadata, and machine-readable docs.
Guide
Theme accessibility
Audit canonical theme colors plus rendered popup, badge, and active-tab states, then run the same checks from the CLI.
Guide
Theme AI builder
Create a Control UI theme with Claude Code, Codex, or Mastra Code, then import and test it live.
Guide
Skins
Skinning Control UI
Author complete token-driven Control UI skins with slots, adornments, motion controls, and one shared component source.
Skin
Refined
Compact, calm starting skin with a complete Control UI token contract.
Skin
Windows XP
Windows XP-inspired Luna tokens, bevels, and titlebar details.
Skin
Liquid metal
Polished metal skin with a WebGL shader control surface.
Skin
Rig
Brutalist skin with coral accents, squared corners, and dense typography.
Skin
Flat
Neutral reset skin with square corners, no shadows, and instant motion.
Skin
Modern Apple
Apple-inspired Liquid Glass skin: WebGL-refraction on floating surfaces, precise directional rims, transparent inputs, and continuous corners.
Skin
Cuicui
Cuicui-inspired shell skin with fixed grain, a docked w-80 sidebar, a neutral main container, and the send-aurora anchored extension on ChatComposer (skin.config fills the chat-composer:send-layer anchor).
Skin
Linear
Linear-inspired skin: indigo brand on a cool neutral ramp, a flat 13px chrome band, 4px radius, hairline borders instead of elevation, and pill-shaped filled actions.
Skin
Skills
CSS-first interactivity
Model UI reactions with relational selectors, container/style queries, and native platform elements before adding React state, effects, or event handlers.
Skill
CSS-first motion & sizing
Drive sizing, enter/exit motion, and scroll effects from CSS and native attributes — token-driven and progressively enhanced — instead of measuring and animating values in JavaScript.
Skill
Derive, do not duplicate
Avoid second sources of truth in component props, hook parameters, and local state.
Skill
Remount state boundaries
Reset state by changing component identity or loading boundaries, not by syncing with effects.
Skill
Explicit names instead of comments
Encode intent in identifiers and extracted units so the code needs no explanatory comments, and keep the rare justified one telegraphic.
Skill
One responsibility per file
Split domain components and hooks before fetching, filtering, selection, and form state become entangled.
Skill
Keep input and output APIs narrow
Split oversized prop, argument, and return-value APIs into cohesive responsibilities.
Skill
Keep context necessary, narrow, and stable
Use context only across real composition boundaries, with the smallest stable semantic value consumers need.
Skill
Do not query the DOM in React
Keep element identity and collections in React instead of searching rendered markup.
Skill
Real stack tests
Prefer tests that drive production hooks, clients, routing, and cache behavior with only the network mocked.
Skill
Test rendered output, not class names
Prove visual behavior through computed styles, geometry, or browser output instead of Tailwind class strings.
Skill
Cohesive folders
Keep every folder a short, readable table of contents by grouping loose files into named responsibilities.
Skill
Single source of truth
Prevent shared facts from drifting by assigning each one a canonical owner.
Skill
Use existing components first
Start from the local design system or registry primitive before creating a new styled element.
Skill
Token discipline
Use established design tokens and local CSS variables before reaching for one-off values.
Skill
ClassName boundaries
Use component APIs for intended variation instead of overriding design-system internals with className.
Skill
Tailwind v4 CSS configuration
Configure Tailwind through CSS directives and tokens instead of adding new JavaScript config.
Skill
Tailwind v4 migration syntax
Use v4 names and modifiers when replacing or reviewing v3-era Tailwind classes.
Skill
First-class utilities before custom CSS
Prefer Tailwind v4's first-class utility families before arbitrary properties or handwritten CSS.
Skill
Variant-first styling
Check Tailwind variants before adding handwritten selectors, style props, or React state for styling.
Skill
Tailwind v4 capabilities
Reach for new v4 utilities before layout hacks, user-agent checks, or JavaScript measurement.
Skill
Tailwind v4 behavior & motion
Account for v4 behavior changes around transforms, hover, default colors, variant order, spacing, and motion.
Skill
State continuity
Show loading, empty, partial, success, and failure states in the same product language.
Skill
Provenance without noise
Surface source, runtime, and ownership cues only where they help the user trust or act.
Skill
Dense but scannable
Favor compact surfaces that support repeated work without flattening hierarchy.
Skill
Say it once
Cut redundant AI-slop copy so labels, controls, and state carry the obvious meaning.
Skill
Skin authoring
Author a skin as three files with strict roles — theme.css owns the complete token contract, skin.config restyles slots and declares DS choices, skin.css says only what classes cannot.
Skill
Extension authoring
Author an extension as an optional installable layered on the library — root-mounted for cross-cutting anatomy-attached behavior, anchored for component-scoped fx activated from skin.config.
Skill
Registry-first DX
Keep the registry manifest and installed source as the contract users can inspect.
Skill
Skin completeness
Treat a skin as a complete source recipe, not a partial class override layer.
Skill
Control UI composition
Keep blocks readable by composing public agent components, hooks, and slots explicitly.
Skill
Runtime-agnostic UI
Keep core visual surfaces independent from model runners, stores, and transport lifecycles.
Skill
Compound components DX
Expose named anatomy parts when users need to customize layout or actions.
Skill
Context vs props
Reach for a compound-component context only when props cannot reach the part, and store intent in it, not styling.
Skill
AI
AI components
Explore composable surfaces for messages, input, activity, media, and agent workflows.
Agent
ChatMessage
Composable chat message with typed role, density, and tone state.
Agent
ChatComposer
Prompt composer with controlled text, submit state, and trigger-menu support.
Agent
ChatComposerAttachment
Composer attachment rail with file previews, upload progress, and removal.
Agent
UserAsk
Keyboard-first agent question panel that temporarily replaces the chat composer inside its container.
Agent
TaskList
Floating agent task progress pill above the composer that expands into the full task list.
Agent
AudioRecorder
Voice recorder with realtime waveform, duration, cancel, and submit controls.
Agent
AudioVisualizer
Levels-driven realtime audio visualizer offered in two usage versions - bars and line - sharing one export and one props contract.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Agent
DynamicNotification
Dynamic Island-style AI notification pill with a thinking state that morphs into a reply bubble — token-driven surface, WebGL-enhanced backdrop blur, or real refractive liquid glass.
ExpExperimental — the contract and the rendering can change without notice. Own the installed copy before shipping it.Agent
EnvironmentVariables
Composable environment variable editor with .env upload, bulk paste, reveal controls, and submit helpers.
ExpExperimental — the contract and the rendering can change without notice. Own the installed copy before shipping it.Agent
Activity
Shared static and collapsible activity anatomy with bounded, scrollable detail content.
Agent
Context
Compact context-window usage with an automatically derived token graph and anchored detail inspector.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Agent
InlineCitation
Inline multi-source citation with a keyboard-accessible preview and source navigation.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Agent
SourceBadge
Linked source badge with an automatic same-origin favicon, derived hostname, and resilient fallback.
Agent
ActionBar
Reusable hover actions for message and response controls.
Agent
InlineAttachment
Inline file and media previews for chat turns.
Agent
MarkdownBlock
Assistant markdown output rendered to prose, with a header and copy-source action.
Agent
CodeBlockEditor
Editable code surface with Shiki highlighting and token-based light/dark themes.
Agent
ChatLayout
Layout primitives for full chat threads, turns, and thoughts.
Agent
ThreadRail
Conversation minimap for scanning and jumping between chat turns.
Agent
Primitives
Primitives
Browse every Control UI primitive through the same live examples used in its documentation.
Primitive
Button
Accessible action button with size, variant, and semantic tone support.
Primitive
Collapsible
Accessible disclosure primitive with measured open and close motion.
Primitive
Tabs
Segmented and browser-style navigation with a stable active indicator.
Primitive
Sidebar
Responsive app sidebar with collapse, mobile sheet, and keyboard toggle support.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Scroll area
Scroll container with overlay scrollbars and edge fades.
Primitive
Table of contents
Sticky in-page navigation with scroll-spy range highlighting.
Primitive
Timeline
Static chronological events with independent status, connectors, descriptions, and metadata.
Primitive
Stepper
Static and interactive workflow steps with horizontal and vertical layouts.
Primitive
Skeleton
Loading placeholder with a token-driven shimmer.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Slider
Single-value range control with branded and plain treatments.
Primitive
Select
Single-choice picker with a token-matched trigger and floating list.
Primitive
DropdownMenu
Dropdown menu for actions, resources, labels, separators, and submenus.
Primitive
Context Menu
Pointer-positioned right-click and long-press menu with nested actions and selection controls.
Primitive
Toggle
Pressed-state button and toggle group built on the Button surface.
Primitive
Switch
On/off control with token-driven track, thumb, and press motion.
Primitive
Dialog
Modal dialog for focused tasks, confirmations, and custom panels.
Primitive
Popover
Anchored floating panel for inline settings and contextual content.
Primitive
Tooltip
Hover or focus hint popup with Base UI positioning and Control UI tokens.
Primitive
Drawer
Swipeable edge panel for mobile sheets and off-canvas surfaces.
Primitive
Responsive dialog
Modal dialog on desktop that becomes a swipeable bottom drawer on mobile.
Primitive
Toast
Transient notifications with a callable toast API and single Toaster mount.
Primitive
Input
Text field primitive sized and styled to match other controls.
Primitive
Input group
Joined input wrapper for addons, icons, and focus-within rings.
Primitive
Dropzone
Composable file intake with validation, managed selection, and drag-activated overlays.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Phone input
International phone field with country search, E.164 values, and Zod validation helpers.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Command
Command palette with token-matched dialog, input, and result rows.
Primitive
Kbd
Keyboard shortcut chip and chord group.
Primitive
Checkbox
Single checkbox control with checked and indeterminate states.
Primitive
Radio group
Single-choice radio set for plans, filters, and option lists.
Primitive
Accordion
Stacked disclosure rows with measured panel animation.
Primitive
Avatar
Profile image with initials fallback and composable overlapping groups.
Primitive
Progress
Determinate task progress with optional label and value rows.
Primitive
Hover card
Hover or focus preview panel for profiles, links, and contextual details.
Primitive
Alert dialog
Modal confirmation dialog for destructive or blocking decisions.
Primitive
Menubar
Desktop command bar with nested menus, shortcuts, and separators.
Primitive
Navigation menu
Site navigation menu with a shared animated viewport.
Primitive
Field
Form field wrapper for labels, descriptions, errors, and validity state.
Primitive
Form
Form wrapper that coordinates field validation and returned errors.
Primitive
Native select
Native select control styled to match the Control UI control family.
Primitive
Textarea
Multiline text field with CSS-first auto-growth.
Primitive
Input OTP
One-time-code field with grouped, focus-aware slots.
Primitive
Combobox
Searchable single-select with input and floating option list.
Primitive
Alert
Inline status panel for callouts, errors, and notices.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Badge
Compact status, label, or count chip.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Card
Content surface for panels, tiles, and settings groups.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Table
Responsive data table for lists, comparisons, and structured records.
Primitive
Aspect ratio
CSS aspect-ratio wrapper for media and previews.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Button group
Joined button group for toolbars, split actions, and segmented controls.
Primitive
Empty
Empty-state layout for blank lists, zero results, and new workspaces.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Item
List row with media, content, and trailing actions.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Pagination
Page navigation for long lists and result sets.
Primitive
Spinner
Accessible loading indicator for pending buttons, panels, and inline waits.
Primitive
Meter
Static range meter for quota, storage, score, or usage values.
Primitive
Tree
Accessible tree view with roving keyboard navigation, single/multi selection, and animated disclosure.
Primitive
Checkbox Group
Multi-select checkbox set with shared state and select-all support.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Autocomplete
Free-text input with search-as-you-type suggestions.
Primitive
Number Field
Numeric input with stepper buttons and optional drag-to-change behavior.
Primitive
Trigger Menu
Caret-anchored command or mention menu for text editors.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Toolbar
Roving-focus toolbar for editor controls and compact actions.
Primitive
Dockable Panel
Non-modal workspace panel that moves between two explicit edge slots with a mobile Drawer fallback.
ExpExperimental — the contract and the rendering can change without notice. Own the installed copy before shipping it.Primitive
Infinite Canvas
Pan-and-zoom spatial workspace for arranging content without fixed bounds.
ExpExperimental — the contract and the rendering can change without notice. Own the installed copy before shipping it.Primitive
Morphing Panel
Accessible disclosure surface that morphs between explicit collapsed and expanded dimensions.
ExpExperimental — the contract and the rendering can change without notice. Own the installed copy before shipping it.Primitive
Color Picker
Color input with picker UI, formats, presets, and contrast helpers.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Gradient Editor
CSS gradient editor with draggable stops and live preview.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Resizable
Accessible resizable panel groups and split layouts with keyboard support.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Calendar
Date selection grid built on react-day-picker and themed through tokens.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Primitive
Typography
The token-driven type scale — one --text-* rung per size, named by role. Publish the utilities, not a component.
Primitive
Code
Shared code surface: Shiki-highlighted lines, gutter, clean copy, and virtualization for large files.
Primitive
Code Diff
Unified or split diff from a git patch or a before/after pair, with word-level intra-line highlighting.
Primitive
Markdown
Rendered agent markdown (GFM) whose code fences compose Code, and diff fences compose CodeDiff.
Primitive
Support files
useChatMessage
Typed role, density, and tone state for ChatMessage.
Hook
useChatComposer
Controlled composer text and submit state.
Hook
useUserAsk
Question/option registration, selection, freeform text, and keyboard flow for UserAsk.
Hook
useAudioRecorder
Browser microphone recording state, waveform levels, and Blob completion.
Hook
useEnvironmentVariables
Editable environment variable rows with .env parsing, upload, duplicate detection, and submit helpers.
Hook
useCopyToClipboard
Copy-to-clipboard behavior with success state and fallback support.
Hook
cn
Tailwind class-name merge helper.
Util
skin
Skin slot and adornment resolvers for the Control UI library.
Util
contracts
Shared prop and slot contracts for swappable skins.
Util
serialize
Bridge a rich editor doc to plain text (and structured mentions) and back — independent of any one component.
Util
Use cases
Use cases
Start from complete workspace templates or focused interaction patterns, then own and adapt the installed source.
Use case
Chat
Controlled chat shell that composes rendered turns and a provider-owned composer.
Use case
Theme toggle
Controlled theme controls with a three-value switch, binary switch, cycle button, and dropdown.
Use case
Coding agent
Desktop coding workspace with project tasks, a focused conversation, and a persistent controlled composer.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Use case
Settings
Searchable multi-page settings shell with responsive navigation and accessible control groups.
Use case
File explorer
Finder-inspired file browser with locations, search, resizable columns, breadcrumbs, and an item preview.
BetaBeta — the props contract is close to final, but small breaking changes can still land.Use case
PrimitivesAIUse casesSkills
Skill / React code quality

Test rendered output, not class names

Prove visual behavior through computed styles, geometry, or browser output instead of Tailwind class strings.

Goal

Make style tests fail on a user-visible regression, not on an implementation-detail refactor.

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

Checks

1Assert computed styles when CSS behavior is available in the DOM test runtime.
2Assert real geometry for layout and overflow, including dimensions, scrollWidth, and clientWidth.
3Use browser validation for pseudo-elements, media and container queries, hover or focus rendering, and layout-engine behavior.
4Assert class strings only when a class builder, class forwarding, or a public slot/classNames API is the contract under test.

Avoid

1Assertions that grep rendered HTML, source files, snapshots, className, or classList for Tailwind utilities to prove appearance.
2Calling a value computed when the test merely maps a class token to an expected CSS value.
3Keeping a class-name-only test when the current test runtime cannot observe the claimed behavior.

Source

Imported as local Control 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