@aphrody/m3-baseui

Material 3 for Base UI (@base-ui/react; the aphrody-labs fork lives in forks/base-ui). Base UI keeps behaviour, accessibility and the data-* state attributes; this package adds the M3 classes and the stylesheets that paint them from the --md-sys-* tokens. Every Base UI primitive is wrapped: 38 components, 0 CSS-in-JS, no MUI.

import "@aphrody/m3-tokens/m3-tokens.css";
import "@aphrody/m3-tokens/expressive.css";
import "@aphrody/m3-baseui/m3-baseui.css"; // or core.css + the sheets you use, below
import { M3Button, M3Dialog, M3Select, M3Switch } from "@aphrody/m3-baseui";

<M3Button variant="tonal" size="md">
  Save
</M3Button>;

<M3Dialog.Root>
  <M3Dialog.Trigger render={<M3Button variant="text" />}>Delete</M3Dialog.Trigger>
  <M3Dialog.Portal>
    <M3Dialog.Backdrop />
    <M3Dialog.Popup>
      <M3Dialog.Title>Delete the file?</M3Dialog.Title>
      <M3Dialog.Description>It cannot be undone.</M3Dialog.Description>
      <M3Dialog.Close render={<M3Button variant="text" />}>Cancel</M3Dialog.Close>
    </M3Dialog.Popup>
  </M3Dialog.Portal>
</M3Dialog.Root>;

Shape of the API

• Single-element primitives are components: M3Button (variant filled, tonal, outlined, text, elevated; size xs, sm, md, lg, xl), M3Input (variant outlined, filled), M3Toggle, M3ToggleGroup (segmented button), M3Separator, M3Form, M3RadioGroup, M3CheckboxGroup, M3Menubar.
• Closed forms of the three controls with fixed internals: M3Switch, M3Checkbox, M3Radio. Their parts are flat exports for custom content: M3SwitchRoot and M3SwitchThumb, M3CheckboxRoot and M3CheckboxIndicator, M3RadioRoot and M3RadioIndicator.
• Multi-part primitives are namespaces that mirror Base UI: M3Accordion, M3AlertDialog, M3Autocomplete, M3Avatar, M3Collapsible, M3Combobox, M3ContextMenu, M3Dialog, M3Drawer, M3Field, M3Fieldset, M3Menu, M3Meter, M3NavigationMenu, M3NumberField, M3OtpField, M3Popover, M3PreviewCard, M3Progress, M3ScrollArea, M3Select, M3Slider, M3Tabs, M3Toast, M3Toolbar, M3Tooltip. Parts without a visual role (Root, Portal, Trigger, createHandle, useToastManager, ...) are Base UI's own, so a namespace has exactly the parts Base UI has (a test compares them against the installed Base UI).
• Non-visual helpers are re-exported: CSPProvider, DirectionProvider, useDirection, mergeProps, useRender.
• className stays a string or a state function ((state) => string), the M3 classes come first; ref is an ordinary prop (React 19, no forwardRef); render composes as in Base UI.
• Every wrapper module is 'use client', so Server Components render the wrappers with plain props.

Per-component modules and sheets

@aphrody/m3-baseui/<name> is the module of one primitive (@aphrody/m3-baseui/dialog exports Root, Popup, ...) and @aphrody/m3-baseui/css/<name>.css its sheet. css/core.css is required with any of them: type shorthands, the state layer, the focus ring, the popup surface and the menu item.

| Components | Sheet | | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Button | button.css | | Toggle, ToggleGroup | toggle.css | | Checkbox, CheckboxGroup | checkbox.css (group layout is in core.css) | | Radio, RadioGroup | radio.css | | Switch | switch.css | | Input, Field, Fieldset, Form | field.css | | NumberField, OtpField | number-field.css, otp-field.css | | Select | select.css | | Menu, ContextMenu, Menubar | menu.css | | Combobox, Autocomplete | combobox.css | | Dialog, AlertDialog | dialog.css | | Drawer | drawer.css | | Popover, PreviewCard | popover.css | | Tooltip | tooltip.css | | Tabs, Slider, Progress and Meter, Accordion, Collapsible, Avatar, Separator, ScrollArea, Toolbar, NavigationMenu, Toast | tabs.css, slider.css, progress.css, accordion.css, collapsible.css, avatar.css, separator.css, scroll-area.css, toolbar.css, navigation-menu.css, toast.css |

Styling rules

• Every rule is inside @layer components: Tailwind utilities (utilities layer) and your unlayered CSS always win, with no specificity fights. Without Tailwind the layer is harmless.
• Colours come only from tokens (--md-sys-color-*; disabled and scrims use color-mix of a token). A test fails on a literal colour, on a token that is not defined in @aphrody/m3-tokens, on a wrapper class without a rule and on a rule without a wrapper.
• State layers use --md-sys-state-*-state-layer-opacity through .m3-bui-state (hover, focus, pressed; data-highlighted for menu items). Motion uses --md-sys-motion-*; prefers-reduced-motion shortens every transition and animation.
• Expressive touches: buttons tighten their corners while pressed, a selected toggle becomes square, the drawer uses the directional extra-large-top and large-start|end corners, the switch thumb grows 16, 24 and 28dp.
• Tailwind v4 users get the matching variants from @aphrody/m3-tailwind (m3-open:, m3-on:, m3-highlighted:, ...).

To build against the fork, point the catalog @base-ui/react entry at it (bun link from forks/base-ui/packages/react).

bun test, bun run typecheck, bun run lint.