Base UI Primitives - Skill
Name: base-ui
Purpose: Build accessible, composable UI with @base-ui/react primitives and project styling tokens.
Use this when creating or refining unstyled primitive components and behavior-heavy UI.
Applies when: Building overlays, menus, form controls, or custom component APIs with Base UI.
Do not use when: You are using copied-in shadcn components as the primary implementation path (use moai-library-shadcn first).
Rules
- Docs first: Start from reference-links.md, then read the exact component page before writing code.
- Behavior before styling: Preserve Base UI interaction and accessibility behavior before adding project styles.
- Styling agnostic: Keep logic and visuals decoupled; prefer wrappers and class composition over forking behavior code.
- Tailwind compatibility: Base UI examples target Tailwind v4. If a target package uses v3, convert unsupported utilities to v3-safe equivalents.
- Composable APIs: Favor controlled/uncontrolled patterns, small props, and clear slots over monolithic components.
- A11y is non-negotiable: Keep labels, descriptions, focus handling, keyboard support, and ARIA relationships intact.
- Styled wrapper contracts: Preserve state-based
className/style, render, refs, and cancelable events. Use packages/ui/lib/base-ui.ts to merge a Base UI class callback after receiving state; ordinary cn/CVA calls do not evaluate it.
- Forms: Keep TanStack Form as the validation/submission owner. Base UI Field can supply accessible relationships without adding a second Form state system. Group labels name a group; they are not labels for Select/Combobox controls.
Workflow
- Confirm
@base-ui/react is present in the target workspace package.json.
- Open the exact docs page from reference-links.md for the primitive you need.
- Implement behavior with Base UI primitives first, then layer project styles (
cn, tokens, Tailwind).
- Convert any Tailwind v4-only example classes if the target workspace is still on Tailwind v3.
- Validate keyboard navigation, focus states, and screen-reader output.
- Run local quality gates (typecheck/lint/tests relevant to changed scope).
Checklists
Implementation checklist
Review checklist
Minimal examples
Wrapper-first composition
import { Field } from "@base-ui/react/field";
type FieldShellProps = {
label: string;
error?: string;
children: React.ReactNode;
};
export function FieldShell({ label, error, children }: FieldShellProps) {
return (
<Field.Root invalid={Boolean(error)} className="grid gap-1.5">
<Field.Label className="text-sm font-medium">{label}</Field.Label>
{children}
{error ? (
<Field.Error match className="text-sm text-destructive">
{error}
</Field.Error>
) : null}
</Field.Root>
);
}
Use a Base UI-aware control such as the shared Input inside this shell. Core's
existing TanStack adapter already handles the product form case; reuse it instead
of adding another field wrapper. The static shadcn Field layout parts also support
display-only content and should not be globally replaced with behavioral Field.
Tailwind v4 to v3 guardrail
When docs examples rely on Tailwind v4-only utilities,
replace them with equivalent v3-safe utilities before commit.
Common mistakes / pitfalls
- Styling first, then patching broken interactions later
- Copying examples without checking Tailwind version compatibility
- Mixing multiple primitive systems in one component without intent
- Building large wrapper components with too many boolean props
1---2name: base-ui3description: "Build accessible, composable UI with @base-ui/react primitives and project styling tokens. Use when creating or refining unstyled primitive components and behavior-heavy UI such as overlays, menus, popovers, dialogs, and form controls, or defining custom component APIs. Prefer the moai-library-shadcn skill when copied-in shadcn components are the primary implementation path."4metadata:5 source: https://skillmd.com/skills/asymmetric-al/base-ui6---78# Base UI Primitives - Skill910**Name:** `base-ui`11**Purpose:** Build accessible, composable UI with `@base-ui/react` primitives and project styling tokens.12Use this when creating or refining unstyled primitive components and behavior-heavy UI.1314**Applies when:** Building overlays, menus, form controls, or custom component APIs with Base UI.15**Do not use when:** You are using copied-in shadcn components as the primary implementation path (use `moai-library-shadcn` first).1617## Rules1819- **Docs first:** Start from [reference-links.md](reference-links.md), then read the exact component page before writing code.20- **Behavior before styling:** Preserve Base UI interaction and accessibility behavior before adding project styles.21- **Styling agnostic:** Keep logic and visuals decoupled; prefer wrappers and class composition over forking behavior code.22- **Tailwind compatibility:** Base UI examples target Tailwind v4. If a target package uses v3, convert unsupported utilities to v3-safe equivalents.23- **Composable APIs:** Favor controlled/uncontrolled patterns, small props, and clear slots over monolithic components.24- **A11y is non-negotiable:** Keep labels, descriptions, focus handling, keyboard support, and ARIA relationships intact.25- **Styled wrapper contracts:** Preserve state-based `className`/`style`, `render`, refs, and cancelable events. Use `packages/ui/lib/base-ui.ts` to merge a Base UI class callback after receiving state; ordinary `cn`/CVA calls do not evaluate it.26- **Forms:** Keep TanStack Form as the validation/submission owner. Base UI Field can supply accessible relationships without adding a second Form state system. Group labels name a group; they are not labels for Select/Combobox controls.2728## Workflow29301. Confirm `@base-ui/react` is present in the target workspace `package.json`.312. Open the exact docs page from [reference-links.md](reference-links.md) for the primitive you need.323. Implement behavior with Base UI primitives first, then layer project styles (`cn`, tokens, Tailwind).334. Convert any Tailwind v4-only example classes if the target workspace is still on Tailwind v3.345. Validate keyboard navigation, focus states, and screen-reader output.356. Run local quality gates (typecheck/lint/tests relevant to changed scope).3637## Checklists3839### Implementation checklist4041- [ ] Primitive choice matches the interaction model (dialog/menu/select/etc.)42- [ ] Controlled/uncontrolled behavior is explicit and testable43- [ ] Styling is layered without breaking interaction semantics44- [ ] Tailwind classes are compatible with the target package version45- [ ] Labels, descriptions, and focus behavior are preserved4647### Review checklist4849- [ ] No unnecessary re-implementation of behavior primitives50- [ ] No prop explosion; component API stays composable51- [ ] Keyboard-only interaction works end-to-end52- [ ] Error/help text is correctly announced for form fields5354## Minimal examples5556### Wrapper-first composition5758```tsx59import { Field } from "@base-ui/react/field";6061type FieldShellProps = {62 label: string;63 error?: string;64 children: React.ReactNode;65};6667export function FieldShell({ label, error, children }: FieldShellProps) {68 return (69 <Field.Root invalid={Boolean(error)} className="grid gap-1.5">70 <Field.Label className="text-sm font-medium">{label}</Field.Label>71 {children}72 {error ? (73 <Field.Error match className="text-sm text-destructive">74 {error}75 </Field.Error>76 ) : null}77 </Field.Root>78 );79}80```8182Use a Base UI-aware control such as the shared `Input` inside this shell. Core's83existing TanStack adapter already handles the product form case; reuse it instead84of adding another field wrapper. The static shadcn Field layout parts also support85display-only content and should not be globally replaced with behavioral Field.8687### Tailwind v4 to v3 guardrail8889```txt90When docs examples rely on Tailwind v4-only utilities,91replace them with equivalent v3-safe utilities before commit.92```9394## Common mistakes / pitfalls9596- Styling first, then patching broken interactions later97- Copying examples without checking Tailwind version compatibility98- Mixing multiple primitive systems in one component without intent99- Building large wrapper components with too many boolean props