prototyper-ui
Prototyper UI component library (Tailwind CSS v4 + Base UI) for installing components, customizing themes, and using component documentation.
Install
npx skills add https://github.com/PrototyperAI/prototyper-ui --skill prototyper-ui- metadata
- author: prototyper-ui version: "2.0.0"
Prototyper UI Development Guide
Composable, design-first React component library built on @base-ui/react primitives and Tailwind CSS v4. Copy-paste distribution (like shadcn/ui), OKLCH color system, CVA variants, compound components.
CRITICAL: This library uses @base-ui/react, NOT @radix-ui/react. Base UI is the official successor to Radix, maintained by the MUI team. Do NOT import from Radix packages. Do NOT assume shadcn/ui patterns work identically — always fetch docs first.
Dependencies
Project Structure
Required Setup
- Tailwind CSS v4 with
@tailwindcss/postcss lib/utils.tsexportingcn():prototyper-tokens.cssimported in globals.css (runnode scripts/theme.mjsto get it)next-themesfor dark mode (.darkclass strategy)
Hello World — Button
2. Component Selection Guide
What are you building?
Compound vs Simple
3. Copy-Paste Patterns
These six patterns cover ~95% of use cases. Copy them directly.
Pattern A: Simple Action (Button)
Key API difference from shadcn: render= prop replaces Radix's asChild. Pass a JSX element, and Base UI merges the props onto it. When using render= on Button, the nativeButton prop is automatically handled internally.
Pattern B: Form Field (TextField + Field)
Field is a universal wrapper. Use it around TextField, NumberField, Select, Combobox, Checkbox, Switch, RadioGroup — any form input that needs a label, description, or error message.
Pattern C: Positioned Overlay (Popover)
Positioning props (side, sideOffset, align, alignOffset) live on the Content component. Internally, they're forwarded to Base UI's Positioner layer — you don't need to think about Portal/Positioner/Popup yourself.
This same pattern applies to Tooltip, Menu, Select, and Combobox — all positioned overlays use side/align/offset. For Menu specifically:
Pattern D: Compound Visual (Slider)
Compound visual components have a strict nesting order. The sub-components must be nested correctly — they communicate via React context.
Pattern E: Selection Input (Select + Field)
Pattern F: Dialog & Sheet (Unified)
There is no separate Sheet component. Dialog handles both center modals and side sheets via the side prop. When side is set, the dialog slides in from that edge. When omitted, it's a standard centered modal.
4. Design System Reference
Token Selection: "I need a background — which token?"
Color Format (OKLCH)
Tokens store raw OKLCH channels. Tailwind utilities are pre-registered via @theme:
Never use hsl(var(--primary)), hardcoded hex, or bg-[oklch(55%_0.24_264)].
Token Categories
Derived Colors (Auto-Generated)
Hover states use color-mix() — no manual darkening:
Use as: hover-only:hover:bg-primary-hover, bg-primary-soft.
Shadow Tiers
Dark Mode
Dark mode activates via .dark class (next-themes). Token values swap automatically — you never write dark:bg-* classes. Shadows for surface and field become none in dark mode (depth comes from tonal contrast instead). Overlay shadows get a subtle white border ring.
Easing Tokens
CSS Utilities
Custom Tailwind Variants
5. Component Architecture
Sub-component Patterns
Component File Header
Every component file follows this strict pattern:
Always use deep path Base UI imports (@base-ui/react/dialog), never barrel imports. Alias primitives with Primitive suffix to avoid naming conflicts with your wrapper components.
Props Type Conventions
Components extend Base UI primitive props + CVA VariantProps:
The render= Prop (Base UI's asChild Replacement)
Base UI does not use Radix's asChild. Instead, it provides render= which takes a JSX element:
Base UI merges all primitive props (event handlers, ARIA attributes, refs) onto your element. The render= prop can also accept a function render={(props) => <Custom {...props} />} but the JSX element form is preferred.
data-slot Convention
Every rendered element gets a data-slot attribute for CSS targeting:
Pattern: root = component name (button), sub-components = {root}-{role} (dialog-header, select-item).
6. Styling & Customization
className Overrides
All components accept className. It's merged via cn() (tailwind-merge) — your classes win over defaults:
CSS Targeting via data-slot
Style components from parent CSS without prop drilling:
Reusing CVA Variants
Use variant functions on non-component elements (e.g., making a link look like a button):
Token Overrides
Override any design token in your globals.css:
Custom Tailwind Variants
Animation Conventions
Prototyper UI uses CSS-first animation — no framer-motion dependency.
- State transitions:
transition-[color,background-color,border-color,box-shadow,opacity] duration-150 ease-smooth+motion-reduce:transition-none - Press feedback:
motion-safe:active:scale-[0.97](buttons),scale-[0.98](menu items),scale-[0.95](small controls like checkbox) - Overlay enter/exit:
data-open:animate-in/data-closed:animate-outwithfade-in/zoom-in-95/directional slides - Signature easing:
--ease-out-fluid(cubic-bezier(0.32, 0.72, 0, 1)) - Split timing: colors 100-150ms, transforms 250ms, enter > exit (300ms→200ms)
- Never:
transition-all, bareactive:scale-*, animations withoutmotion-reduce:alternative
For detailed animation patterns, invoke the /animate-ui skill.
7. Accessibility Checklist
Every component should address:
- Motion reduction: Add
motion-reduce:transition-noneon elements withtransition-*classes. Addmotion-reduce:animate-noneon elements withanimate-in/animate-out. - Touch safety: Use
hover-only:hover:instead of barehover:for background/color changes. Addno-highlightutility on interactive elements. - Press feedback: Always prefix with
motion-safe:— never bareactive:scale-*. - Focus management: Use
focus-visible:focus-ringfor buttons/toggles/links. Usefocus-within:focus-field-ringfor form field groups. - Keyboard navigation: Handled by Base UI automatically — Arrow keys for RadioGroup, Tabs, Menu, Toolbar, Select. Escape to close overlays. Enter/Space to activate.
8. Common Mistakes
Import Mistakes
Styling Mistakes
Architecture Mistakes
Component-Specific Mistakes
9. Component Reference
10. Documentation Access
Scripts
Direct URLs
MCP Server
Tools: list_components, get_component_docs, get_component_source, get_theme, search_docs.
Always Fetch First
Before implementing any component, always fetch its documentation using the scripts or URLs above. Do not assume Radix/shadcn patterns work identically. Component APIs, data attributes, and animation conventions all differ from what you might expect.