Skip to content

Latest commit

 

History

History
79 lines (64 loc) · 5.09 KB

README.md

File metadata and controls

79 lines (64 loc) · 5.09 KB

Components

Components in five groups, chosen from what Base UI and other popular libraries provide and what our products need today. Every component is generic: it works the same in memos, the website, the web clipper and any future product.

Group Components
Actions Button, Toggle, ToggleGroup, Menu, Link
Forms Field and Fieldset, Input, Textarea, Select, Combobox, Checkbox, Switch, RadioGroup
Navigation Tabs, Collapsible
Overlays Dialog (and its sheet form), Drawer, Popover, Tooltip, Toast
Display Badge, Separator, Spinner, Skeleton, Table, List, plus Lucide icons

Page template

Map parts to the shared rules in Keeping the system consistent. This page template does not authorize component-specific versions of typography, geometry or combined states. Put an exception beside its owning rule, then link it from the component page and cover it in the shared reference or an existing fixture.

Pages are reference for agents: short, imperative, no narrative. Every page has these sections, in this order:

  1. Title and purpose. # Name, then one line: what it is for.
  2. Example. One complete, copyable example of the common case.
  3. Parts. One row per part: name, the Base UI part it wraps, what it renders. Skip for single-element components.
  4. Props. A TypeScript block per part, only for props we add or change, then one line on which Base UI props pass through.
  5. Rules. Imperative bullets: when to use it, what to use instead, required labels, keyboard behavior.
  6. Style. Bullets for building the component: tokens, sizes, states and motion.

Components follow the API conventions: parts with Base UI's names, no data props.

Left out on purpose

  • Card. Content is grouped by spacing, headings and separators. The only boxes are a List of settings or records and a bordered Table.
  • Avatar, Form, Kbd, Prose. Products own avatar presentation and rendered content. Compose submitted forms from a native <form> or Base UI Form with Field, Fieldset and Button. Shortcut hints use Menu or Tooltip shortcut; standalone key labels use native <kbd>.
  • Slider, Stepper. No setting in our products needs a continuous range. Use an Input with type="number" or a Select.
  • Chip, SegmentedControl, Accordion. A Toggle covers filter chips, a single-choice ToggleGroup covers segmented choices, and stacked Collapsibles cover an accordion.
  • Later, when a screen needs them: multi-select Combobox, ContextMenu, ScrollArea, Progress, Calendar.

Choosing between similar components

The short version. Using the components has the full decision guides, recipes and common mistakes.

Need Use
Start an action Button
Go somewhere Link, or an anchor with buttonClasses() when it should look like an action
A setting that saves at once Switch
An option saved with a form Checkbox
One of 2 or 3 options, with room to show them RadioGroup
One of a short list Select
One of a long list, or typing to find Combobox
On/off in a toolbar, or stacking filters Toggle, or ToggleGroup with multiple
A layout preference or filter of the same content ToggleGroup without multiple
Content sections of a page, with one panel per choice Tabs
A list of actions for one thing Menu
A few controls that belong to one thing Popover
A decision that blocks the page Dialog
Navigation or details that slide in from an edge Drawer
Name an icon-only control Tooltip
Confirm something happened Toast
Settings rows, or a short list of records with actions List
Data with columns Table
A submitted form A native <form> or Base UI Form with Field, Fieldset and Button
A status or tag label Badge
A clickable tag filter Toggle
Compact reactions and their picker Soft pill Toggles, a ghost pill Button and Popover; see the composition
Content still loading Skeleton
A control waiting on a server the control's loading prop

Shared types

type Size = "xs" | "sm" | "md"; // control sizes; xs only where a page says so
// Badge has its own "xs" | "sm" sizes and defaults to sm.
// Menu has one fixed density and no size option.
type ControlShape = "default" | "pill"; // Button and Toggle; defaults keep size-row corners
type Tone = "neutral" | "success" | "warning" | "danger";
/** An icon element. Controls use Lucide; collection rows also accept decorative emoji or identity marks. */
type IconElement = React.ReactElement;

See Building on it for the conventions every component follows.