aphrody-m3-primitives/README.md

@aphrody/m3-primitives

Material Design 3 React primitives. This is the SpaceUI component set (@spacedrive/primitives, MIT, © Spacedrive, vendored in packages/aphrody-spaceui) rebuilt on the aphrody M3 system: M3 color roles and state layers, the 10-step shape scale, the M3 typescale, the M3 focus ring, elevation, Material Symbols and the M3 easings of @aphrody/m3-motion. Base UI (@base-ui/react) is the headless layer: it owns behavior, keyboard interaction, focus management and accessibility, and drives the M3 enter / exit motion through its data-starting-style / data-ending-style attributes. Every upstream export and prop still works; the Radix-era props (asChild, checked="indeterminate", delayDuration, forceMount, onSelect, array slider values) are mapped onto Base UI, and Base UI props are accepted as well.

Fusion rules, token mapping and the Material Web equivalents of each component: docs/design/SPACEUI-M3-FUSION.md.

Install

bun add @aphrody/m3-primitives @aphrody/m3-theme @aphrody/m3-tokens

Peers: react and react-dom 18 or 19, tailwindcss 4.1+.

Styles

The components are styled with M3 Tailwind utilities (bg-surface-container, text-on-surface-variant, rounded-full, text-label-large, hover:bg-on-surface/8), so the app compiles them with Tailwind v4:

@import "tailwindcss";
@import "@aphrody/m3-tokens/m3-tokens.css"; /* shape, typescale, elevation, motion, state */
@import "@aphrody/m3-theme/spaceui.css"; /* SpaceUI themes as M3 schemes — or tokens.css */
@import "@aphrody/m3-theme/tailwind.css"; /* M3 utilities */
@source "../node_modules/@aphrody/m3-primitives/dist";

Icons use the Material Symbols font; register it once:

import { ensureMaterialSymbols } from "@aphrody/material-web/icon/material-symbols.js";
ensureMaterialSymbols();

Usage

import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
  Icon,
  Input,
} from "@aphrody/m3-primitives";

export function Welcome() {
  return (
    <Card variant="elevated">
      <CardHeader>
        <CardTitle>Welcome</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <Input placeholder="Your name" icon="person" />
        <Button variant="filled">
          <Icon name="arrow_forward" size={18} /> Get started
        </Button>
      </CardContent>
    </Card>
  );
}

Components

Group	Components	M3 anatomy
Actions	Button (filled, tonal, outlined, text, elevated + the SpaceUI variants), CircleButton, CircleButtonGroup, ShinyButton, ShinyToggle, FilterButton, SelectPill, SelectTriggerButton	Common buttons, icon buttons, connected group, filter chip
Selection	CheckBox, RadixCheckbox, Switch, Slider, RadioGroupRoot/Item, ToggleGroup, OptionList	Checkbox, switch, slider, radio, segmented button
Text input	Input, SearchInput, PasswordInput, TextArea, Label, SearchBar, NumberStepper, Select	Outlined / filled text fields, search bar, exposed dropdown menu
Navigation	TabsRoot/List/Trigger/Content, TabBar, SpaceItem	Primary tabs, navigation-drawer item
Menus and overlays	Dialog (+ dialogManager, useDialog), Popover, Tooltip, Kbd, DropdownMenu, ContextMenu, Dropdown	Basic dialog, menus, plain tooltip
Feedback	toast, Toaster, Loader, ProgressBar, CircularProgress, Banner, InfoBanner, Badge	Snackbar, progress indicators, banners, badges and assist chips
Containment	Card (elevated, filled, outlined), Divider, Collapsible, Resizable, LayoutCard, GridLayout	Cards, divider, expansion panel
Type	CategoryHeading, ScreenHeading, Shortcut	Title small, headline small, key chips
Forms	Form, ErrorMessage, errorStyles, z	Error supporting text
Helpers	Icon, renderIcon, IconSource, PHOSPHOR_TO_SYMBOL, m3StateLayer, m3FocusRing, tw, surface class names, key symbols

Sizes: the default (md/unset) is the M3 baseline height; smaller sizes are M3 density steps.

Coming from @spacedrive/primitives

Rename the import. Phosphor icon props still compile (they accept an IconSource: a Material Symbols name, an element or a component). Visible differences: M3 heights (inputs default to 56, icon buttons to 40), pill-shaped buttons, secondary-container selection, Material Symbols glyphs, Select opens below its field, Collapsible draws an expand_more indicator (indicator={false} to opt out).

Development

bun run typecheck
bun test          # happy-dom preloaded by bunfig.toml
bun run build     # tsup + declarations

Licence

Apache-2.0 AND MIT: aphrody changes under Apache-2.0, SpaceUI-derived code under MIT (LICENSE.spaceui).