Siteplane UI

Upgrading to 2.0

Move an application from Siteplane UI 1.x to 2.0, with the new size steps, the removed names, the changed defaults and the reinstall.

Markdown

Siteplane UI 2.0 puts every control on one size scale in steps of 4 px and gives the basic controls new spacing and structure in the kit's own look. Its icons are Phosphor, the text Button variant is gone, and sixteen components join the kit. The kit's own texts come from one set of messages, so you translate them in one place. A control without a size keeps its height, so most screens change little. Code that names sizes, the names on this page, a style on a field and tests of the loading, copy and menu states need changes. Installed source changes only when you install again, so you choose when 2.0 reaches your application. The changelog lists every change.

Reinstall every item

Commit your work, then look at what an item will change:

pnpm dlx shadcn@4.18.0 add @siteplane/button --diff

The items of a release work together, so reinstall every Siteplane UI item your application uses in one command, and your Siteplane UI Pro patterns the same way under @siteplane-pro:

pnpm dlx shadcn@4.18.0 add @siteplane/button @siteplane/input @siteplane/select @siteplane/dialog --overwrite

The registry installs @phosphor-icons/react with the components that use it and no longer lucide-react. Remove lucide-react from package.json once your own code no longer imports it, and set "iconLibrary": "phosphor" in components.json, as Installation shows. Phosphor does not hide an icon from assistive technology on its own, so a decorative icon of yours takes aria-hidden="true":

1.x
import { BellIcon } from "lucide-react";

<BellIcon />;
2.0
import { BellIcon } from "@phosphor-icons/react/dist/ssr";

<BellIcon aria-hidden="true" />;

Update the agent skill as described in Skills, so your agent writes 2.0 code. To stay on 1.x for now, install the fixed source of 1.8.1 as described in Pin a release.

Sizes

Size1.x2.0
xs24 px32 px
sm28 px36 px, the default
md32 px40 px
lg36 px, the default44 px
xl48 px48 px

The default moved from lg to sm and kept its 36 px, so a control without a size keeps its height. A size you set, and the controlSize of a provider, now name a taller step. To keep a Button's 1.x height, use the size of the same height:

1.xHeight2.0
xs24 pxxs, 32 px; no text Button is smaller
sm28 pxxs, 32 px
md32 pxxs
lg, the default36 pxsm, the default, or no size
xl48 pxxl
icon-2xs20 pxicon-2xs, 24 px
icon-xs24 pxicon-2xs
icon-sm28 pxicon-xs, 32 px
icon-md32 pxicon-xs
icon-lg, the default36 pxicon-sm, the default, or no size
icon-xl48 pxicon-xl
1.x
<SiteplaneUIProvider controlSize="lg">
  <Button size="sm">Edit</Button>
  <Button aria-label="Remove" size="icon-md">
    <TrashIcon aria-hidden="true" />
  </Button>
</SiteplaneUIProvider>
2.0
<SiteplaneUIProvider>
  <Button size="xs">Edit</Button>
  <Button aria-label="Remove" size="icon-xs">
    <TrashIcon aria-hidden="true" />
  </Button>
</SiteplaneUIProvider>
  • Provider: controlSize="lg" on SiteplaneUIProvider becomes controlSize="sm", or leave it out. With controlSize="sm" or "md", controls are now 36 or 40 px high, and no field is smaller than 36 px.
  • Controls from 36 px: fields, Toggle, Toggle Group, Select Button and Color Swatch Picker start at sm, 36 px. Check narrow layouts, since a row of compact controls grows: a Toggle Group item at sm has 14 px at either side of its label, where it had 6 px. Items with grow share the row and come down to 6 px before the row overflows.
  • Relative sizes: useRelativeControlSize counts from the default sm. Pass the size the part has at sm: a compact part that was useRelativeControlSize("sm"), 28 px beside 36 px controls, is useRelativeControlSize("xs"), 32 px. See Control size.
  • CSS: the control tokens follow the new scale, so --sp-rw-control-lg is 44 px. Read --sp-rw-control-sm for the 36 px default, for example h-(--sp-rw-control-sm). See Shared dimensions.
  • Selectors: Buttons and fields write their size to data-size, and a control without a size writes sm, where it wrote lg. CSS of yours that selects [data-size="lg"] for the default control now matches only 44 px controls, so select [data-size="sm"] for it.

Components with steps of their own

  • Badge: sm to xl are 22, 24, 28 and 32 px, where they were 16, 20, 24 and 28 px, and a Badge without a size is 22 px instead of 24. Use md for 24 px and lg for 28 px; no Badge is smaller than 22 px.
  • Calendar: the days are 32 px at xs, 40 px at sm, the default, 48 px at md, 52 px at lg and 56 px at xl, where they were 28 px at xs, 32 px at sm, 40 px at md and at the default lg, and 48 px at xl. A Calendar at md or without a size keeps its 40 px without a size, one at sm keeps its 32 px at xs, and one at xl keeps its 48 px at md. There is no 28 px step, so a Calendar at xs grows from 28 to 32 px. A Calendar takes xs only from its own size, never from the provider. See Calendar sizes.
  • Avatar Group: the sizes moved one name down. xs is 24 px, sm 32 px and the default, then md 40, lg 48, xl 56 and 2xl 64 px. In 1.x, sm was 24 px and the default md 32 px.
  • Checkbox, Radio and Switch: the boxes are 16, 20, 24 and 28 px, 16 px by default where it was 18. The Switch is 36 by 20 px by default, where it was 36 by 22.
  • Slider: the thumb is as large as the Switch thumb of the same size, 16, 20, 24 and 28 px from sm to xl, on rails of 6, 8, 8 and 10 px, where the thumbs were 14, 16, 18 and 20 px on rails of 4, 6, 8 and 10 px. A Slider without a size has a 16 px thumb on a 6 px rail, where it had 18 px on 8 px.
  • Table and Native Table: the default sm has a 36 px heading row, rows of at least 56 px and 12 px above and 20 px beside each cell. The dense table of 1.x is size="xs": a 32 px heading row, 4 and 8 px of cell padding and rows as tall as their content. See Table sizes.
1.x
<Badge size="lg">Beta</Badge>
<AvatarGroup size="sm">{/* … */}</AvatarGroup>
<Table aria-label="Payments" size="sm">{/* … */}</Table>
<Calendar aria-label="Booking date" size="sm" />
2.0
<Badge size="md">Beta</Badge>
<AvatarGroup size="xs">{/* … */}</AvatarGroup>
<Table aria-label="Payments" size="xs">{/* … */}</Table>
<Calendar aria-label="Booking date" size="xs" />

Removed, renamed and changed

The text variant

text was a second name for the link and is removed. Use link on Button; on ExpandingArrowButton, link is the default.

1.x
<Button variant="text">Show all</Button>
<ExpandingArrowButton label="Read the guide" variant="text" />
2.0
<Button variant="link">Show all</Button>
<ExpandingArrowButton label="Read the guide" />

MenuCheckboxItem, DropdownMenuCheckboxItem and ContextMenuCheckboxItem no longer take size, which sized the switch. A switch row draws the standard Switch at the size of the row.

1.x
<DropdownMenuCheckboxItem size="sm" variant="switch">
  Daily digest
</DropdownMenuCheckboxItem>
2.0
<DropdownMenuCheckboxItem variant="switch">
  Daily digest
</DropdownMenuCheckboxItem>

switchVariants and switchMenuTrackClassName are removed with it. switchTrackClassName is the composition string of a menu row's track, beside switchThumbClassName:

1.x
const track = switchVariants({ size: "lg" });
const menuTrack = switchMenuTrackClassName;
2.0
const track = switchTrackClassName;

The check of a chosen row

The check of a chosen row ends the row in Select, Combobox, List Box and every menu, and it follows the label in the markup. indicatorPosition="end" is the default now, so remove it; indicatorPosition="start" puts the check first, as in 1.x. The box of a multiple Select, a multiple Combobox and a checkbox row still leads its row.

1.x
<DropdownMenuRadioItem indicatorPosition="end" value="owner">
  Owner
</DropdownMenuRadioItem>
2.0
<DropdownMenuRadioItem value="owner">Owner</DropdownMenuRadioItem>

Radio rows close their menu

A radio row closes its menu when it is picked, in Menu, Dropdown Menu and Context Menu, and a radio row of a Drawer Menu closes its drawer. In 1.x they kept it open, so a radio row that closed its menu with closeOnClick no longer needs it, and a menu that should stay open after a pick takes closeOnClick={false} on its radio rows. Check rows stay open, and a switch row never closes its menu.

1.x
<MenuRadioGroup onValueChange={setModel} value={model}>
  <MenuRadioItem closeOnClick value="fast">
    Fast
  </MenuRadioItem>
  <MenuRadioItem closeOnClick value="thorough">
    Thorough
  </MenuRadioItem>
</MenuRadioGroup>
2.0
<MenuRadioGroup onValueChange={setModel} value={model}>
  <MenuRadioItem value="fast">Fast</MenuRadioItem>
  <MenuRadioItem value="thorough">Thorough</MenuRadioItem>
</MenuRadioGroup>

Featured Icon is a component of its own, and Notification no longer exports it. Reinstalling Notification installs it, or add @siteplane/featured-icon. Import FeaturedIcon and FeaturedIconTone from it, and pass the glyph as children instead of icon. Without a size it keeps the 36 px box, the 18 px glyph and the pulsing rings of 1.x.

1.x
import { FeaturedIcon } from "@/siteplane/components/notification";

<FeaturedIcon icon={BellIcon} tone="accent" />;
2.0
import { FeaturedIcon } from "@/siteplane/components/featured-icon";

<FeaturedIcon tone="accent">
  <BellIcon aria-hidden="true" />
</FeaturedIcon>;

Native date and time inputs

Input no longer styles the browser's date and time inputs, and its hidePickerIndicator prop is removed. For a date, use Date Field, which types it in segments and opens the kit's calendar, or Date Picker, which chooses it from that calendar behind a button. For a time, use Time Field. Each takes the Field's label, description and error, as Input does.

1.x
<Input hidePickerIndicator type="date" />
<Input type="time" />
2.0
<DateField />
<DatePicker />
<TimeField />

The time of a Date Time Picker

The field of a Date Time Picker types its time into its segments, as a Date Field with a time does, and ends with its calendar button. The time button, its list of hours and minutes and the comma the picker drew between the date and the time are gone; the separator of the locale stands there, a comma and a space in en-US. So openTimePickerLabel is removed, and minuteStep no longer sets a step for the field, whose segments take any minute: it sets the times of the panel that trigger="button" opens, every 30 minutes by default. Check a step on the server if it matters. Time Field keeps its button and its list.

1.x
<DateTimePicker
  aria-label="Meeting start"
  minuteStep={15}
  openTimePickerLabel="Choose a time"
/>
2.0
<DateTimePicker aria-label="Meeting start" />
<DateTimePicker aria-label="Meeting start" minuteStep={15} trigger="button" />

See Minute step.

Fields that fill their row

Number Field and Date Field fill their container, as Input does. width="fit" keeps the compact Number Field of 1.x. Time Field, Date Range Picker and Date Time Picker keep the width of their content, and width="full" fills the row in place of a width class. A Select trigger fills its container as before, and width="fit" on SelectTrigger or SelectButton makes it as wide as its value in place of a class such as w-fit min-w-0. Date Picker keeps the width of its date and Native Select fills its container, and each takes the other width with width="full" or width="fit".

1.x
<NumberField defaultValue={3} />
<TimeField className="w-full" />
<SelectTrigger className="w-fit min-w-0">
  <SelectValue />
</SelectTrigger>
2.0
<NumberField defaultValue={3} width="fit" />
<TimeField width="full" />
<SelectTrigger width="fit">
  <SelectValue />
</SelectTrigger>

Field variants

The fields keep two surfaces, the default and soft. elevated and inset are removed from Input, Input Group, Textarea, Number Field, OTP Field, the date and time fields, the inputs of Combobox and Autocomplete, ComboboxChips, Prompt Input and Password Strength, and from SelectTrigger and SelectButton. inset drew the default field, and elevated added only the contour of an elevated Card around it; a Select trigger drew its default surface for both. Remove the prop or pass variant="default". soft stays on Input, Input Group, the date and time fields, File Input, Prompt Input and Password Strength, and every other field you type into takes it too, such as Textarea, Number Field, OTP Field, Tags Input and the inputs and chips of Combobox and Autocomplete. For a trigger in a filter bar or a toolbar, beside a search field, the new variant="outline" rests transparent inside the rim of an outline Button. SelectTrigger, SelectButton, Native Select, Date Picker, the Button trigger of Date Range Picker and Date Time Picker, and Color Picker take it. formControlSurfaceClassNames and the shadow-form-control class are gone with them, so CSS of yours keyed on that class, on a field's data-variant="elevated" or "inset" or on a trigger's data-profile-mode of those names matches nothing. Remove it.

1.x
<Input aria-label="Search" variant="elevated" />
<SelectTrigger variant="inset">
  <SelectValue />
</SelectTrigger>
2.0
<Input aria-label="Search" />
<SelectTrigger>
  <SelectValue />
</SelectTrigger>

See Input and Select.

The className and style of a field

className and style style the field you lay out, its outer element, on every field. Input and Textarea sent style to the native control in 1.x and now send it to their outer span with className, so a margin or a width in style moves the whole field. Input's style takes an object, no longer a function of the input's state. ComboboxInput and AutocompleteInput send both to the group that holds the input with its trigger, its clear button and its start addon, where className reached the input's box and style the input, and CommandInput's className follows. A style meant for the text inside moves to className with a child selector. The style of InputGroupInput, InputGroupSegment and InputGroupTextarea still reaches their native control.

1.x
<Input aria-label="Amount" style={{ textAlign: "end" }} />
2.0
<Input aria-label="Amount" className="[&_input]:text-end" />

See Input.

Sticky table headers

The heading row of Table and Native Table sticks to the top of its scrolling container only with stickyHeader; in 1.x it always did. Add stickyHeader where a table keeps its heading row in view. With it, a table in a parent of a fixed height, such as a card or a panel, takes at most that height, so it needs no height class there.

1.x
<Table aria-label="Payments" containerClassName="max-h-80">
2.0
<Table aria-label="Payments" containerClassName="max-h-80" stickyHeader>

On a phone the Dashboard Shell's header is 56 px high, where it was 48 px, and it stays in view over the page. A sticky bar of your own in DashboardShellMain takes --sp-dashboard-shell-header-offset as its top in place of an offset of its own: the shell sets it to 56 px below the breakpoint, where the header sticks over the page, and to 0 where the main area scrolls on its own. See Sticky header.

1.x
<div className="sticky top-12 md:top-0">{/* toolbar */}</div>
2.0
<div className="sticky top-(--sp-dashboard-shell-header-offset)">
  {/* toolbar */}
</div>

Round skeletons

shape="circle" on Skeleton rounds it fully, for the placeholder of an avatar or a status dot, in place of a rounded-full class.

1.x
<Skeleton className="size-10 rounded-full" />
2.0
<Skeleton className="size-10" shape="circle" />

Popover headers

PopoverDescription no longer keeps 4 px above itself after a PopoverTitle. Put the two in PopoverHeader, which keeps them 4 px apart, as the header of a Dialog does, and remove a wrapper of your own that spaced them with a gap or a margin. Both stand on a 20 px line, where they stood on 21 px.

1.x
<PopoverPopup>
  <div className="grid gap-1">
    <PopoverTitle>Snooze until</PopoverTitle>
    <PopoverDescription>The thread returns to your inbox.</PopoverDescription>
  </div>
</PopoverPopup>
2.0
<PopoverPopup>
  <PopoverHeader>
    <PopoverTitle>Snooze until</PopoverTitle>
    <PopoverDescription>The thread returns to your inbox.</PopoverDescription>
  </PopoverHeader>
</PopoverPopup>

See Popover.

The Page Header photo

The page-header-avatar-badge slot is removed. The badge of Page Header's avatar is the avatar's corner mark, an AvatarBadge that the avatar sizes and places, 24 px on the 96 px photo over a banner, 32 px on the 160 px one and 18 px on the 56 px avatar beside the title. A size on the verified Badge no longer changes it, so remove it. Over a banner the photo is the Avatar's profile photo, with a hairline ring and a gap in the header's color that cuts it out of the cover.

1.x
<PageHeader
  avatar={{
    alt: "Mara Ellis",
    badge: (
      <Badge profile="verified" size="lg">
        <CheckIcon aria-hidden="true" />
        <span className="sr-only">Verified</span>
      </Badge>
    ),
    initials: "ME",
    src: "/avatars/mara.webp",
  }}
  banner
  title="Mara Ellis"
/>
2.0
<PageHeader
  avatar={{
    alt: "Mara Ellis",
    badge: (
      <Badge profile="verified">
        <CheckIcon aria-hidden="true" />
        <span className="sr-only">Verified</span>
      </Badge>
    ),
    initials: "ME",
    src: "/avatars/mara.webp",
  }}
  banner
  title="Mara Ellis"
/>

See Banner.

Remove names of tags

A Tag's remove button has one name of its own, "Remove" and the tag, such as "Remove Design", where 1.x read "Remove tag" and the tag. A removeLabel is now that whole name, where 1.x put the tag after it, so a label of your own names the tag too:

1.x
<Tag key={tag} onRemove={() => remove(tag)} removeLabel="Delete">
  {tag}
</Tag>
2.0
<Tag key={tag} onRemove={() => remove(tag)} removeLabel={`Delete ${tag}`}>
  {tag}
</Tag>

Header Navigation on a phone

backLabel is removed from HeaderNavigation: the links of a dropdown, and of a link with items, open in place under their row in the phone menu, so it has no Back button. Remove the prop. mobileVariant picks the menu of a narrow header: fullscreen, the default, as in 1.x, or default for the Sidebar's side sheet, which suits an application. See Mobile navigation.

1.x
<HeaderNavigation backLabel="Back" brand={brand} items={items} />
2.0
<HeaderNavigation brand={brand} items={items} />
<HeaderNavigation brand={brand} items={items} mobileVariant="default" />

Empty State spacing

Empty adds no space around itself; the surface it sits on gives that. Its title and description step with its new size: lg by default for a page, md for a card or a table and sm for a compact surface such as a popover. To keep the room of 1.x, give the Empty its padding:

1.x
<Empty>{/* EmptyHeader, EmptyContent */}</Empty>
2.0
<Empty className="px-6 py-24">{/* EmptyHeader, EmptyContent */}</Empty>

See Empty State sizes.

Text on accent fills

Text and checks on an accent fill take --sp-rw-fg-on-accent, which came with 1.2: the label of the accent Button and Badge, the checks of Checkbox, Radio, Table selection and the checkbox rows, a selected Calendar day and, new in 2.0, text-primary-foreground. It defaults to --sp-rw-fg-emphasis, the white of destructive fills. Give a light brand its dark text in --sp-rw-fg-on-accent, in both theme scopes. An override of --sp-rw-fg-emphasis, as applications set it before 1.2, no longer reaches the accent fills inside an element of your own, and on :root it turns the text of destructive fills dark too.

1.x
:root {
  --sp-rw-bg-accent: #facc15;
  --sp-rw-fg-emphasis: #1c1917;
}
2.0
:root,
:is(.light, [data-theme="light"]) {
  --sp-rw-bg-accent: #facc15;
  --sp-rw-fg-on-accent: #1c1917;
}
:is(.dark, [data-theme="dark"]) {
  --sp-rw-bg-accent: #facc15;
  --sp-rw-fg-on-accent: #1c1917;
}

See Override component colors.

Removed deprecated names

2.0 removes the names that 1.x deprecated, as Stability and deprecations promised. TypeScript reports each one that your code still writes; a value that comes from data, such as a tone read from an API, needs the same change. Use the replacements:

RemovedUse
isActive on PaginationLink, PaginationPrevious, PaginationNext, SidebarMenuButton and SidebarMenuSubButtonactive
current on StepperButtonItemactive
checked, defaultChecked and onCheckedChange on the theme togglespressed, defaultPressed and onPressedChange
DetailDrawerContentDetailDrawerPopup
Badge variant="brand"variant="accent"
TimelineItem variant, and its defaulttone, and neutral
Meter tone default and destructiveaccent and error
TooltipPopup tone default and destructiveneutral and error
ResourceListIndicator tone="muted"tone="neutral"
FeaturedIcon tone gray and brandneutral and accent
Notification tone gray, brand and defaultneutral, accent and no tone
ActivityFeedItem presencestatus and statusLabel
ModalBlock tone default and destructiveneutral and error
onChange on the Modal date range parts, ModalImageCrop and ModalTextEditoronValueChange
ModalDateRangePresetspresets on ModalDateRangeFields
1.x
<PaginationLink href="?page=2" isActive>
  2
</PaginationLink>
<Badge variant="brand">New</Badge>
<TooltipPopup tone="destructive">Payment failed</TooltipPopup>
2.0
<PaginationLink active href="?page=2">
  2
</PaginationLink>
<Badge variant="accent">New</Badge>
<TooltipPopup tone="error">Payment failed</TooltipPopup>

The icon prop of FeaturedIcon and the FeaturedIcon of Notification go with them, as Featured Icon shows.

Behavior that tests notice

  • Loading: loading no longer sets disabled. The Button stays focusable, sets aria-busy and aria-disabled, and hides its spinner from assistive technology, so its accessible name is its label without "Loading". A test that expects a disabled button checks aria-disabled or aria-busy instead. LoadingButton renders the Button without a wrapper element and shows loadingText while its action runs. See Disabled and loading states.
  • Copy Button: a Copy Button with a label keeps the label and swaps only its icon. "Copied" and a failure are announced instead of shown. See With text.
  • Icons: kit icons are Phosphor SVGs with aria-hidden="true" and no lucide-* classes, so a selector for a Lucide class no longer finds them.
  • Menus: a radio row closes its menu, or its Drawer Menu's drawer, when it is picked, and so does an account row of HeaderAccountMenu; see Radio rows close their menu. A switch row keeps its menu open when it is pressed, whatever closeOnClick says, and check rows stay open, as in 1.x.
  • Choice rows: the rows of a multiple Select or Combobox show a checkbox box. A Combobox with chips takes a chosen option out of the list and closes once every option is chosen; hideSelected={false} keeps them in the list.
  • Fields: an invalid Input, Input Group or date field shows an alert icon at its end; showInvalidIcon={false} leaves it out. A Textarea inside a Field takes the Field's name and disabled state, as Input does. The popover of a date picker or of Color Picker keeps to the room beside its trigger and scrolls inside it, and it brings the day in focus into view. The calendar of a Date Field opens with the focus on its day, the value or today, where it started on the button for the previous month. A date or time segment is as wide as its text, so the first digit typed over a placeholder moves the segments after it. A Date Time Picker's field has one button, the calendar's, and takes its time typed into the segments, as The time of a Date Time Picker shows.
  • Names: a Tag's remove button reads "Remove" and the tag, such as "Remove Design", where 1.x read "Remove tag" and the tag, and a removeLabel is its whole name, as Remove names of tags shows. The Breadcrumb ellipsis reads "More", and a date picker's trigger ends its name with the chosen value. The search field inside a Combobox popup, such as the one of a searchable select, is named by its own aria-label or "Search", where it took the label of its Field, also over an aria-label of its own.
  • Keyboard and focus: Home and End move the focus to the first and last item of a Toolbar, and a field inside it keeps both keys. Closing a Notification moves the focus to the next element after it, as closing an Alert does.
  • Tooltips: TooltipProvider opens the first tooltip after 300 ms, where it waited 700 ms, and keeps 550 ms for the next one. A tooltip stays a visual label; describeTrigger on a Tooltip that adds information gives its popup role="tooltip" and names it in its trigger's aria-describedby while it is open. describeTrigger="always" names it while the tooltip is closed as well. The help icon of a field works this way, so its button names the hidden popup in aria-describedby at all times and no longer holds a hidden copy of the text; reinstall tooltip and input-group together. See Supporting text.
  • Payment fields: the card number of ModalPaymentFields keeps the blocks of its network, 4, 6 and 5 digits for American Express and 4, 6 and 4 for a Diners Club number that starts with 36, where every number stood in fours, and the expiry month stays between 01 and 12: a 4 becomes 04, and a digit that would make the month 00 or 13 is left out.
  • Navigation: on a phone, Header Navigation's fullscreen menu opens under its bar and is not modal: the menu button stays in the tab order as its toggle and its close, Tab moves from it into the menu and Shift+Tab back, and Escape closes the menu and returns the focus to the button. A dropdown's links open in place under their row. The Sidebar's sheet starts with its close button, the first Tab stop, named "Close sidebar" or by closeLabel, and a SidebarTrigger inside the sidebar renders nothing there.
  • Texts and locale: the kit's own texts read their English from the messages of SiteplaneLocaleProvider, so the words stay the same until you translate them, once, as Localization shows; the kit ships German as @siteplane/messages-de. The date parts of Modal Block write their dates in the provider's locale, or the browser's language without one, where 1.x always wrote en-US. Task Calendar writes its dates and weekdays in the provider's locale and starts its week on the locale's first day, Sunday in en-US, where it always wrote en-US and started on Monday. Inside a provider, the charts, Bar List, Progress, Meter, Avatar Group, Motion Number, Number Field and Slider write their numbers in its locale, where 1.x wrote en-US, or the browser's language in Number Field and Slider, unless each got a locale; without a provider they stay as they were. A Spinner without a name of yours is named "Loading" by a hidden label inside it, where 1.x set an aria-label, so a test finds it by its role and name.
  • Charts: tooltip values and axis labels change at once instead of rolling. Pass rollingNumbers to roll them. See Rolling numbers.
  • Motion: MotionSwap renders one pane and replaces its content at once, where the old content stayed and faded out over the new one, and only the height of its container follows; Stepper, Metric Card, Notification, File Upload, Prompt Input and the tabs of a Filter Bar switch this way. A test that waited for the old content to leave finds it gone at once. Every floating panel, such as a Popover, a Menu, a Select's list or the calendar of a Date Picker, opens in 150 ms and closes in 100 ms, where a Popover, a Menu or a Select's list took 240 ms each way and the popover of a date or color picker 160 ms to open and 150 ms to close. A Dialog or Alert Dialog opens and closes in 200 ms, where it took 210 ms. An Accordion's or a Collapsible's panel opens and closes in 200 ms on one curve and fades its content with it, where the Accordion took the state curve and the Collapsible a curve of its own, neither with a fade. The Tabs indicator glides in 250 ms, where it took 150 ms. A toast slides in over 350 ms and out over 250 ms, where it took 380 ms each way, and a Sheet or Drawer opens in 250 ms and closes in 200 ms, where a Sheet took 450 ms each way and a Drawer 450 ms to open and 400 ms to close. A test that waits for one of them waits less. The text of a Tooltip or Popover that moves to another trigger switches at once too, where the old text faded out over the new one, and a Navigation Menu cross-fades its panels where they stand, where they slid 12 px; --motion-navigation-distance is gone with the slide. A List Box row shows its focus ring only for keyboard focus. See Replace content.
  • Tables: pressing a control inside a column heading no longer sorts the column, and the heading row scrolls with the rows unless the table has stickyHeader.
  • Slots and classes: the close button of an Alert carries data-slot="alert-close", where it carried the Button's button. The parts of FilterBar carry slots of their own, filter-bar, filter-bar-controls, filter-bar-search, filter-bar-filters, filter-bar-active-filters and filter-bar-actions, beside their data-pattern, and DashboardShellPrimary carries dashboard-shell-primary. CommandShortcut carries data-slot="command-shortcut" on a <kbd> of its own, where it was a Kbd with data-slot="kbd" and data-command-shortcut. The Date Time Picker's date-time-picker-time-trigger, date-time-picker-time-popover, date-time-picker-time-selector and date-time-picker-separator and Page Header's page-header-avatar-badge are gone with their parts. The triggers of Date Picker and Color Picker carry data-variant="default", where they carried outline, and a number or text in SidebarMenuBadge renders a Badge inside it. The sp-swap-fade class and its rules are gone, and the installed motion-presence.ts no longer exports swapPresence, SwapTiming, toMotionElement or swapFadeClassName; content that switches carries sp-panel-switch, as a Tabs panel does. The caret of HeaderAccountMenu's card trigger, as of Account Card, is MenuTriggerIcon variant="switcher", with data-slot="menu-trigger-icon", data-variant="switcher" and the class sp-menu-trigger-icon, where it was an icon of its own.

What looks different

  • Weights: Button labels are 450, where they took the text weight of 400, and links are 500, 50 above the Buttons. A chosen row of Select, Combobox and List Box keeps the weight of the other rows, where a chosen Select row took 450, so the check alone marks it. In a Calendar, the headings, today and the chosen day take the label weight, 500, where the month and year picker's heading, today and the chosen day took 560. See Typeface.
  • Links: a link never rests underlined; the underline appears on hover and press. A link of the inline profile takes the accent color, in a sentence and on its own beside text, such as View report at the foot of a card. profileTone="neutral" keeps the text color, as a Back link does.
  • Fields: a focused field draws a 1 px accent edge, also while the calendar or the list of one of its buttons is open, and an invalid field a 1 px error edge with the alert icon. A trigger that opens a list or a picker rests raised, as a Select trigger does, and a field you type into rests inset. Every trigger takes the hover and pressed tints of a Button, 4 % and 7 % in Light and 6 % and 10 % in Dark, where a Select trigger drew 4 % and 8 %. An icon laid over the input of a Toolbar is the field's icon, 16 px at sm and 20 px from md, 8 px from the text, where it took the Toolbar's 20 px. The triggers of Date Picker and Color Picker, outline Buttons in 1.x, take the surface and the edges of a Select trigger and place their icon or swatch and their value as a field does, in the field's text at the regular weight. The glyphs in a field rest in the tertiary text color at 80 %, the caret of a Select, an icon that SelectValue renders, an icon in GroupText and the steppers of a Number Field included, where the steppers took the secondary color. Every disabled field fades to 50 % and lays a light gray fill under its text, as a disabled Input, Input Group and Textarea did in 1.x, and shows the not-allowed cursor over it; a Select trigger faded to 64 % without the fill. The line inside a field, such as the divider of an Input Group addon, takes the color of the field's edge. The selector of a Time Field follows the field's size: its rows are 36, 40, 44 and 48 px from sm to xl, where they were 32 px at every size, with 16 px text from md, and Hours and Minutes are small group labels in the tertiary color. The list of times of a Date Time Picker follows its size too. See Field edges.
  • Rows and popups: menu rows are 36 px with the check at the end, options are as tall as their field, a one-line tooltip is 34 px, field labels stand 6 px above their control, and badges are 22 px by default. The check of a chosen row takes the accent color in every menu and list. A chosen List Box row takes the fill of the current Sidebar row, where it took the secondary fill, and its focus ring sits inside the row, for keyboard focus only. A highlighted Command row takes the lighter fill of a highlighted option, its shortcut is plain text, as in a Menu row, where it was a keycap, and the footer of a Command is the band of a Menu footer, with 14 px text in the quaternary color, where it held 12 px text. Toggles and the items of a Toggle Group rest in the text color of a Button and show that they are on by their fill, where they rested in the secondary text color.
  • Chips and tags: the tags of a Tag Group and the chips of a Combobox stand on the surface of a default Badge with its hairline, white in Light, where a tag took the gray fill of a secondary Badge. A Tag's count keeps its gray box. In a field, the chips of a Combobox stand 6 px apart, where they stood 4 px apart, and the text starts 8 px after the last one.
  • Chevrons: the down chevron of a trigger turns half a turn while its list, menu or panel is open, all with one motion, and is 16 px at every size: the caret of a Select, the chevron of a Navigation Menu trigger, which moved 1 px down in 1.x, an Accordion's and a Collapsible's, and MenuTriggerIcon, the new chevron of a menu button, which replaces a chevron icon of your own. A chevron icon of your own stays still. Each draws Phosphor's CaretDown, the Select's caret too, where 1.x drew a narrower caret there. An up-down caret stays still: a switcher row of a Sidebar, such as a workspace switcher, ends with SidebarMenuChevron variant="switcher", and a menu button that switches accounts, workspaces or plans with MenuTriggerIcon variant="switcher", each in place of an up-down icon of your own. That caret, like the caret of an Account Card and of HeaderAccountMenu's card trigger, rests in the tertiary text color and takes the primary one on hover, press and while the menu is open, where the card trigger drew it in its text color.
  • Dots: the dots of a trigger that opens more actions are OverflowGlyph, the dots in the Bold weight at 20 px, which replaces a dots icon of your own. The Breadcrumb ellipsis and the menu of a Metric Card draw it, where the Breadcrumb drew 16 px dots.
  • Groups and segments: a segment of an Input Group, such as a Select, Copy or Button segment, draws its divider unless you pass divider={false}, where 1.x drew a divider only with divider. Text before or after the value stands in the field without a cell or a line, as an Input Group's text of any length did in 1.x, such as https://, .com, EUR or $, and now also GroupText beside an Input in a Group, where it stood on a gray cell. The value starts 8 px after the text; pass divider to an addon to keep a line. GroupText among other controls, such as the Buttons of a pager, keeps its gray cell, with its text centered, and among default Buttons the cell takes their edge where it forms the outside of the group, where it drew none. The prefix of ModalTextField and the username prefix of ModalProfileFields draw no divider, where they drew one. A Group joins its parts with one hairline: a GroupSeparator between Buttons with a rim lies on their rims, and a Group of outline Buttons draws the edge of a single outline Button, where it drew a ring in the color of a separator around the group. An outline Toggle Group keeps its pressed-in look.
  • Surface edges: the neutral edges are softer. Every surface draws one edge color, --sp-rw-surface-edge, never weaker than a separator: in Light 17 % on 1x screens and 28 % on 2x and denser screens, where it was 24 % on both, and 40 % in Dark, where it was 52 %. Separators, --sp-rw-border-translucent, are 11 % and 28 %, where they were 16 % and 40 %. The rim of a default Button, a field and a Select trigger is 12 %, where it was 16 %, and the rim of an outline Button, Toggle or trigger 18 %, where it was 25 %; the edge of a Checkbox and a Radio keeps its strength. The surface edge reaches Cards, CardFrames, Frame panels, a raised Notification and the sidebars, and the default Alert draws it without a shadow, where it drew the separator color. An inset Card in Dark draws 40 %, where it drew 24 %; if you set --sp-rw-surface-inset-shadow on :root and nest a Dark scope, set it in the Dark scope too. To draw every line 1 px wide on every screen, in the colors of a 1x screen, pass hairline={false} to SiteplaneUIProvider, as Hairline shows. A message Card, an outline Bubble, a Code Block, an Attachment, a choice card at rest, an icon well and the frame of a Task Calendar draw it as their border, where they drew the separator color. Inline Code, Kbd and dividers keep the separator color. See Surface edges.
  • Date and time fields: a segment is as wide as its text, so the separators stand at the same distance from the digits in every locale, such as tt.mm.jjjj in German, where segments of a fixed minimum width left uneven gaps. A separator keeps its spaces, so a Czech date reads 01. 10. 2026 and a Hungarian one 2026. 10. 01., where 1.x dropped them.
  • Alerts: an inline Alert places its action by its own width, as a banner and a band do: beside the text from 32rem of the Alert's width and under it in a narrower Alert, such as one in a drawer, where 1.x followed the width of the window. The title and description of every Alert stand on a 20 px line, where they stood on 21 px. See With actions.
  • Slider: the thumb is as large as the Switch thumb of its size, 16 px on a 6 px rail without a size. See Components with steps of their own.
  • Navigation: underline tabs are 32 px at the default size. The default Pagination puts Previous and Next at the ends as links with arrows, centers the pages and fills the current one. A count in a Sidebar row is a small secondary Badge, where it was a bare figure in the row's text color: pass a number or a text to SidebarMenuBadge, and put an element of your own, such as an animated number, in a Badge size="sm" variant="secondary". Sidebar group labels take the tertiary text color. HeaderAccountMenu opens with its header band only from the avatar trigger, and its account rows show 20 px avatars, where they showed 24 px. Its avatar trigger shows a 32 px avatar in its 36 px button, where the avatar filled it, and its card trigger shows the account as an Avatar Label Group with a 40 px avatar, as Account Card does.
  • On a phone: Header Navigation and the Dashboard Shell show a bar 56 px high, where Header Navigation's was 64 px and the Dashboard Shell's 48 px, and Header Navigation keeps 16 px at either side, where it kept 20 px. Header Navigation's menu button is MenuIconMorph, whose bars turn into the close, and its links are Sidebar rows. On a phone SidebarTrigger is a 40 px icon button with a menu glyph, and the Sidebar's sheet starts with a 56 px row with its close button at the end; a SidebarTrigger inside the sidebar stays out of the sheet, so remove a close button of your own from it. The bars of a MenuIconMorph are those of the menu glyph, 15 px long, 5 px apart and 1 px thick at every size, where they were 18 to 27.5 px long and 1.5 or 2 px thick, and it shows the hover fill of a ghost icon button. The text rows of a fullscreen Sheet menu rest in the secondary text with the rows' hover fill.
  • Overlays: Sheet, the side Drawers and Detail Drawer are 400 px wide, where they were 448; pass className="max-w-md" to the popup for 448 px. Dialogs have a 24 px header and 16 px before their actions, actions stand 12 px apart, and the corner close is 40 px in a Dialog and 36 px in a Sheet. The Detail Drawer has the look of a Sheet: it floats on the Sheet's shadow without an edge line, its header has no hairline under it, and its body keeps 24 px from every side, where it kept 16 px above and below. An Alert Dialog takes the corners of a Dialog, 16 px at the default radius, where it took 24 px, and so does an inset Sheet, where it took 18 px. A Preview Card draws the surface of a Popover, and the title and description of a Popover stand on a 20 px line.
  • Cards: the footer of a Frame and of a Card Frame is a row, as a Card's is, so its parts stand side by side, centered, and the actions in the footer of a Card, a Frame or a Card Frame stand 12 px apart without a gap class, as in a Dialog, where they touched; a gap class of yours still sets the gap. Drop flex and items-center from the className of FrameFooter and CardFrameFooter, give a single child that fills the width flex-1, and wrap parts that should stack in an element of their own. The title of a Card header stands 4 px above its description, where it stood 6 px above it. See Footer actions.
  • Calendar: Previous, Next and the month heading are as tall as a day, 32, 40, 48, 52 and 56 px from xs to xl, as in the month and year picker, where they were Buttons of the default height at every size of the Calendar. So a Calendar, and the popover of a date picker, is 4 px taller at the default size and 12 to 20 px taller from md. The heading keeps 8 px inside its edges and writes the Calendar's 14 px text, and a Calendar marks today with a dot.
  • Data: tables are roomier by default, and the tables in rendered Markdown are compact. Empty States have a larger title and md actions at their default size. A Resource List's dot is 8 px, where it was 6 px, its neutral dot takes the full muted gray, and a ring and the disc of an icon indicator take the solid colors of a dark Featured Icon. The unread dot of an Activity Feed takes the green of a status dot, and the count of an Avatar Group grows with the group's size.
  • Colors: success takes the green and warning the amber of their status dots, so warning no longer reads as orange. Info takes the accent color: text-info, bg-info and text-info-foreground follow it, and so do the info icons of Alert and Toast, the info dot of a Resource List and the info marker of a Timeline, which now looks like its accent marker. Every status glyph takes the tone of its status dot in both themes, while status text keeps the text colors. The icons of Alert and Toast read text-success, text-warning, text-destructive and text-info as in 1.x. A Timeline marker, a Featured Icon's outline, which was a Notification's icon, the check and the cross of CopyButton, the lock of a blocked Stepper step and the status icons of the Patterns took the color of status text and now take the dot tones too, lighter in Light and a step deeper in Dark. --sp-semantic-color-primary (bg-primary, --primary, ring-primary) aliases the accent fill and --sp-semantic-color-primary-foreground the text on it, where they were a navy and white, so your own primary utilities draw the accent, and so does today in a Task Calendar. --sp-semantic-color-destructive and -control (bg-destructive, bg-control) alias the fills of the destructive and default Button, where they were Tailwind's red and white or a near-black, and -primary-hover, -destructive-hover and -control-hover (bg-primary-hover and its siblings) the fills of the accent, destructive and default Button on hover, where they were fixed Tailwind colors; the theme files no longer set them. The error icon of Alert and Toast, the dot of an error Badge and the busy dot of an Avatar take the destructive Button's red, a little darker than Tailwind's, and so does every other color of yours that reads --destructive. --sp-semantic-color-destructive-foreground (text-destructive-foreground), -invalid (border-invalid) and -invalid-muted (bg-invalid-muted) alias the error family's text, fill and tint, and -warning-foreground the warning text, where they named Tailwind colors: invalid is the error fill in both themes, about 5 L darker in Light and 7 L in Dark, invalid-muted is its tint, a red tint in Dark where it was a gray, and the error text keeps its color in Light and is 5.75 L lighter and a little paler in Dark. --sp-semantic-color-focus (ring-focus, outline-focus) aliases --sp-rw-border-focus, the color of every focus ring, so the focus of a Calendar day and of the Color Picker's thumbs no longer draws a fixed blue. --state-selected (bg-state-selected) is the selected fill of the rows, black at 5 % in Light and white at 6 % in Dark, where it was a tint of the navy, so a selected Resource List row looks the same with or without interactive. To keep a color of 1.x, set the token after the base import in both theme scopes, as Override component colors shows. The page and the default Button are darker in Dark. See Status colors.
  • Colors inside controls: Button, Input, Input Group, Textarea and Switch read the theme's colors and keep no copies of their own, so text inside them that takes the foreground colors matches the text around them. In Light it is #030303 where 1.x drew #262626, and muted text, such as an Input Group's addon text, is #636363 where it was #686868; in Dark the two are #efefef and #878787, where they were #f5f5f5 and #818181.
  • Details: Buttons other than links, Toggles, pressable Badges and selectable Tags flash their edge when a press ends; data-flash={false} leaves a Button out. Icons are Phosphor in the Regular weight. Badges take the corner radius of their size, avatar initials are larger, and the Spinner turns with its solid head in front. A bordered profile photo, from 3xl, paints the gap of its ring in the color of its surface, as the photos of Page Header and ModalUserSettings do. The remove button of a File Upload row is a 24 px icon action in the tertiary color, where it was a 36 px ghost Button, and a disabled Editable fades, its pencil included. Content that replaces content switches at once, the axis labels and grid lines of a chart and the pencil of an Editable included, and floating panels, dialogs and the items of a flow list move on the gentler ease curve, where they took a curve that covered three quarters of the way in the first fifth of its time. A Popover, a Menu, a Select's list, a Tooltip or the popover of a date or color picker opens in 150 ms, growing from 95 % as it travels 4 px, and closes in 100 ms, so its text no longer lingers after its surface; it took 240 ms each way from 95.5 % and 7 px, and a picker's popover grew from 98 %. A Dialog or Alert Dialog on a wide screen grows from 95 % over 200 ms, where it grew from 98 % over 210 ms, and a tag or a chip that is added grows from 80 % around its center, where it grew from 96 %.

A worked example

An application with a customer list, an inbox, settings pages and an assistant moved to 2.0 with these changes:

  1. It reinstalled every item and replaced its Lucide imports with Phosphor ones, adding aria-hidden="true" to decorative icons. Its dots icons became OverflowGlyph, and the chevrons of its menu buttons MenuTriggerIcon.
  2. Where its views were dense, it kept the 1.x heights: Buttons sm and md became xs and lg became sm, icon Buttons icon-md became icon-xs and icon-xs became icon-2xs, Badges xl became lg and md became sm, and its --sp-rw-control-lg height classes read --sp-rw-control-sm.
  3. Its data tables took size="xs".
  4. variant="text" became variant="link", every indicatorPosition="end" went, and icon-only Toolbar buttons took shape="square".
  5. Its shells took contained in place of the frame classes. The window its sheets and dialogs portal into kept its transform, and SidebarMenu lost its gap-px.
  6. Its Empty States took their padding on the host, and the ones inside its views size="sm"; a compact Number Field took width="fit".
  7. Its loading skeletons took the 2.0 sizes, so a view no longer moved when it loaded, and its round placeholders took shape="circle" in place of rounded-full.
  8. Its customer drawer took DetailDrawerPopup, and the marks of its workspaces and companies became Avatar shape="square".
  9. Its workspace switcher ended with SidebarMenuChevron variant="switcher", its account menu opened with a DropdownMenuHeader that holds an Avatar Label Group, and its inbox count, an animated number, went into a Badge size="sm" variant="secondary" inside SidebarMenuBadge.
  10. Its snooze picker put its title and description in a PopoverHeader, and its card footers dropped their gap classes.

Its 16 px count badges are 22 px now and its sm toggles 36 px. A row of seven day toggles with grow still fits a phone's column, because its items come down to 6 px of inset.