How the package is put together and how products use it.
- React components on Base UI. Base UI provides behavior: focus management, keyboard support, ARIA, portals and positioning. Memos UI provides the styling, the tokens and the component API.
@base-ui/reactis a peer dependency at one exact version, so an app's own Base UI components share the package's copy. - No shadcn. Don't depend on shadcn, don't copy its code, and don't use shadcn-compatible names for components or tokens. Following a similar layering (unstyled behavior below, styled components above) is fine.
- One npm package,
@usememos/ui, used by every product. ESM only, React 18 and 19, one JS entry point, two stylesheets and a Tailwind CSS theme file. - Plain CSS on tokens. Components are styled with CSS that reads token variables. Product code uses tokens through their CSS variables (
var(--mu-well)) and never copies raw values. - Lucide icons from
lucide-react. See Icons. - No fonts. Text uses the system UI font; nothing is downloaded.
Load the tokens first, then the styles:
import "@usememos/ui/tokens.css";
import "@usememos/ui/styles.css";An app on Tailwind CSS v4 also loads @usememos/ui/tailwind.css, which maps the tokens to mu- utilities (bg-mu-surface). See Tailwind CSS.
tokens.css defines every token on :root, on a shadow root's :host, and on any element with the mu-root class. styles.css holds the foundation classes and every component's styles.
Every token is a custom property named --mu-<token>, so the surface token is var(--mu-surface). The prefix keeps the tokens apart from an app's own variables and from those of a CSS framework.
Both stylesheets sit in one cascade layer named mu. Unlayered CSS always wins over layered CSS, so app-owned layout needs no specificity fight: a className on a Button that sets width wins over the button's own rule. This is a cascade mechanism, not permission to restyle the component; follow Styling ownership.
When the app also puts its CSS in layers, declare the order once, before any import, so that mu comes after resets and before the app's components and utilities. For an app on Tailwind CSS v4:
@layer theme, base, mu, components, utilities;
@import "tailwindcss";
@import "@usememos/ui/tokens.css";
@import "@usememos/ui/styles.css";Without that line, the layer seen first is the weakest. A reset loaded after styles.css would then override the components.
Inside another page (the web clipper, an embed), mount the UI under a .mu-root element or inside a shadow root, so neither side's styles leak into the other. The package has no global selectors beyond :root, :host and .mu-root.
Set data-theme="light" | "dark" on the root element or on any .mu-root. Without the attribute the tokens are Light. The app, not the package, reads prefers-color-scheme and the user's saved choice. See Color. An app can add its own themes on top of these two; see App themes.
An app changes only the color and font tokens. Every other token and every mu-* class rule is internal. See What an app can change.
- Every class the package ships starts with
mu-. - The public classes are for apps too: size rows (
mu-s-md), surface roles (mu-key), focus, icons and the type scale. Apps apply them to their own parts and never override them. mu-positionerputs a popup's positioner onlayer-popup, andmu-popup-motionsupplies the shared opening and closing fade andspace-1offset overduration-fade. Under reduced motion it has no transition, including opacity. See Motion.- The surface classes
mu-well,mu-keyandmu-popupapply flat fills and borders. Use them for new parts. See Surfaces and boundaries. mu-iconapplies icon size and stroke rules outside a component, at the size of the nearest size row;mu-icon-xs,mu-icon-smandmu-icon-mdset a fixed size on their own. See Icons.mu-visually-hiddenhides text visually but keeps it for screen readers.- A size row class sets the
--mu-row-*variables (height, padding, text, radius, gap, icon) that every part inside reads. See Row variables. - Component part classes (
mu-menu-item) are internal. An app reaches a component's look through its class function (menuClasses()). See Class functions.
Inside the package, source order decides which rule wins: a rule later in styles.css overrides an earlier one on the same element. Selector weight must not get in the way.
- Put every
:has()inside:where(): write.mu-button:where(:has(> svg:first-child)), not.mu-button:has(> svg:first-child). A:has()takes the specificity of its argument, so the bare form scores (0,2,1) and beats a later.mu-button.mu-button-icon(0,2,0), whatever the order. - A modifier rule (a variant, an
-iconclass, a context like.mu-segmented > .mu-toggle) comes after the base rule it changes, and its selector weighs at least as much.
packages/ui/test/cascade.test.ts fails when a :has() adds specificity, and when an earlier rule outranks a later rule that adds a class to the same element and sets the same property. e2e/icons.spec.ts checks the result in the browser: icon-only buttons and toggles are squares with the icon centered, in every size.
Components follow the conventions of established React libraries (Base UI, Radix, React Aria), not the needs of one product. Each component page lists its parts and their props.
A component made of more than one element is a namespace of styled parts. Part names are Base UI's, so anyone who knows Base UI knows the anatomy:
import { Menu, Button } from "@usememos/ui";
import { Ellipsis, Pin, Trash2 } from "lucide-react";
<Menu.Root>
<Menu.Trigger render={<Button variant="ghost" icon={<Ellipsis />} aria-label="More actions" />} />
<Menu.Popup align="end">
<Menu.Item icon={<Pin />}>Pin</Menu.Item>
<Menu.Separator />
<Menu.Item icon={<Trash2 />} danger>Delete</Menu.Item>
</Menu.Popup>
</Menu.Root>- Base UI's names.
Root,Trigger,Popup,Item,Title,Description,Close,Paneland so on. No shadcn names (DropdownMenuContent,CardHeader). - One
Popupper overlay. Base UI'sPortal,PositionerandBackdropare folded into ourPopup. It takesside,align, Base UI's other placement behavior (anchor,sticky,collisionAvoidance,collisionBoundary,positionMethod,disableAnchorTracking) and its portalcontainer, and draws the backdrop where the component has one (Dialog). The gap to the trigger and the distance kept from the viewport edge are fixed by the system (4px for menus and lists, 6px for popovers and tooltips; Base UI's default edge distance), sosideOffset,alignOffsetandcollisionPaddingare not props. - Indicators are built in. The check in a menu or select item, the chevron in a select trigger and the knob in a switch render by themselves. See built-in glyphs.
- One element, one component. Button, Input, Textarea, Badge, Separator, Spinner, Skeleton, Link, Checkbox, Switch and Toggle are single components, not namespaces.
- No data props. Collections are built from parts (
Menu.Item,Select.Item,Tabs.Tab), not passed asitemsoroptionsarrays.
size: controls that offer sizes take"xs" | "sm" | "md", default"md".xsonly on the controls listed in Control sizes; other sized controls take"sm" | "md". Badge instead takes"xs" | "sm", default"sm", with its own text-density sizes. Menu has no size option onRootormenuClasses()and ignores inherited size: its fixed density is independent of its trigger. There is nolg: a bigger control is not a stronger one, and apps hardly need it. One prop sets height, padding, text, icon size and radius together. On a sized namespace, set it onRoot; every part reads it from context.- Controlled or uncontrolled, with Base UI's prop names:
value+onValueChange, ordefaultValue(Select, Combobox, Tabs, ToggleGroup, RadioGroup)checked+onCheckedChange, ordefaultChecked(Checkbox, Switch, Menu.CheckboxItem)pressed+onPressedChange, ordefaultPressed(Toggle)open+onOpenChange, ordefaultOpen(Menu, Dialog, AlertDialog, Popover, Tooltip, Collapsible, Select, Combobox)
icontakes a Lucide element (icon={<Pin />}), never a string name. Collection item slots also accept decorative emoji or identity-mark elements; see Icons.render, where the public prop type exposes it, swaps the rendered element through Base UI oruseRender: a router's link inLink, a Button as aMenu.Trigger. Fixed native-element wrappers keep their documented element. Base UI doesn't render links through Button; a link that looks like a button is an anchor withbuttonClasses()(see Button).classNameandstylepass through to the part's element, after our classes, for layout and integration within Styling ownership.- Accessible names. A control without a visible label takes
aria-label. Icon-only controls always do. tonedescribes a label or status treatment. The shared status tones are"neutral" | "success" | "warning" | "danger". Badge also keeps"outline"for a quiet label and"primary"for emphasis; these are label treatments, not statuses. Badge's user-chosencoloris allowed only with"neutral"(or an omitted tone). Toasts use the shared status tones through Base UI'stypeprop.variantselects a component's predefined appearance or structure. Values belong to that component, not a global variant set: Button has"primary" | "neutral" | "ghost" | "danger"; Toggle has"ghost" | "soft"; Select.Trigger has"neutral" | "ghost"; Popover.Popup has"panel" | "list"; Dialog.Popup and Drawer.Popup have"panel" | "bare". See each component's page for usage and defaults.- Interaction states are not variants. Hover, focus, pressed, selected, disabled, invalid and loading use the component's behavior props and state attributes, with the shared treatments in States. Do not add variants or component-specific tokens for these states.
- Native props pass through to the element a component or part renders.
- Every part has a class
mu-<component>-<part>(mu-menu-popup,mu-menu-item), plusmu-<component>on single components. Variants are classes too (mu-button-primary,mu-badge-success), so a class function can style any element. - Class functions. A component whose look apps put on their own elements exports
<component>Classes():buttonClasses,inputClasses,textareaClasses,badgeClasses,menuClassesandpopoverClasses. It returns a string for a single component and one string per part for a namespace. The component builds its own classes with it, so the two can't drift. See Class functions. - State is styled through Base UI's data attributes (
data-highlighted,data-checked,data-pressed,data-disabled,data-open,data-starting-style,data-ending-style), never through extra classes.
Wrap the app in Toast.Provider, render Toast.Viewport once, and create toasts with Base UI's manager:
const toast = Toast.useToastManager();
toast.add({ title: "Note archived", type: "success" });Rendered content and avatars belong to the product. The editor (@usememos/editor) owns its reading and editing styles; this package does not style Markdown. Build submitted forms with a native <form> or Base UI Form and this package’s Field, Fieldset and Button.
- A reason: a screen in a product needs it, and no existing component or pattern covers it.
- A generic name and API that would make sense in any of our products.
- Tokens only: no raw colors or sizes. Only Menu surfaces use the menu-depth roles; no other shadows, sheen or visible outlines.
- Every documented size (Menu has one fixed density), all states, both themes, and reduced motion.
- Keyboard and screen reader behavior from Base UI.
- A page in
docs/components/and an entry in the inventory.