Reference

Upgrading

What each release changes in your code, and the command that makes most of those changes for you.

The upgrade command

Bump the package, then run upgrade from your app's root. It rewrites source written for an older version and lists what it could not move safely.

npx foundations upgrade --dry-run   # list what it would move
npx foundations upgrade             # move it
npx foundations upgrade src/app     # only these paths

Each migration ships in the release that removed what it replaces, and changes nothing on code already migrated, so upgrade runs all of them and never needs to know the version you came from. It reads your .tsx and .jsx with your app's own TypeScript and edits exact ranges, so it leaves your formatting alone and a file it moves nothing in is not written at all. An import it needs joins your existing one from the package, or follows your last import, in your file's own quotes and semicolons.

A clean tree first

upgrade writes only when git has no uncommitted changes to tracked files, so git diff shows exactly what it did and is the undo. --force writes anyway. After it runs, your lint names anything left, and npx foundations doctor stops counting files written for an older version.

0.4: marks

One way to put an icon, checkbox or dot beside words, in place of five. The slot seats every mark on the middle of the capitals, within half a pixel at any size, leading or zoom.

// 0.3
<TypographyCaption className="flex items-center gap-1">
  <Icons.Clock className="size-3" /> 44d ago
</TypographyCaption>

// 0.4
<TypographyCaption mark={<Icons.Clock />}>44d ago</TypographyCaption>

Removed, and what replaces each:

ON_FIRST_LINE: the words' mark prop, or <Marked mark title> for a title with lines under it.
ON_BASELINE: items-baseline for words at two sizes, and the icon in the words' mark.
icon-inline, and the caption sizing a loose svg: a glyph in a mark is one em of the words.
CAP_TRIM on a label beside an icon: the label's mark. CAP_TRIM stays for text centred in a box of its own, or beside an object taller than the line.
inline with align-middle or a top margin on an icon: <Mark> around it.

What upgrade moves for you:

a glyph first or last inside a text role into mark or markEnd;
a glyph beside a text role in a flex row into that role's mark, unwrapping the row when nothing else is left in it;
an inline glyph held with align-middle or a top margin into <Mark>, which it imports.

What to check by hand afterwards: a glyph that took its colour from the row it left, words that a flex gap used to separate and now need a space, centred or right-aligned words, where an inline <Mark> keeps the glyph beside them, and an avatar or anything else taller than the line, which is not a mark: the words centre on it with CAP_TRIM.

What looks different on purpose: every glyph beside words is one em of them, so caption icons grow from 0.8em and oversized ones shrink. Controls size a glyph that is their direct child, so one you wrap in an element of your own keeps the size you give it. Badge no longer forces a 12px icon into its 10px size, and the design lint now flags a loose icon in a text role, a size class on a glyph in a mark or a control, and a glyph nudged into line. The Marks section shows every placement live.

0.4: one way to do each thing

Every name this release removes was a second way to do something the package already did. Each has one spelling now.

TypographySmall: TypographyCaption, as="small" for small print or as="p" for a note. upgrade writes as="p", which keeps the block the old one rendered.
TypographyProseList: <TypographyList variant="prose">. upgrade renames it.
Accordion and its three parts: DisclosureGroup and Disclosure, which now animate open and closed where the browser supports it. upgrade moves them, a literal defaultValue included. Open state the app keeps is open and onToggle on each Disclosure, which <details> supports natively.
Tabs, TabsList, TabsTrigger and TabsContent: TabGroup, built with .map when the tabs are data. From 0.4.1 a strip with no panels is a TabGroup picker and a compact one is size="sm". upgrade moves them.
DISCLOSURE: Disclosure, whose surfaces are its own.
INK_ON_CARD, INK_ON_POPOVER and INK_ON_SIDEBAR: style={inkOnSurfaceStyle("--card-foreground")}, and the same for any surface. upgrade moves one in a className.

upgrade marks each thing it could not move with a ✖ and the reason, and each move worth a second look with a !: a panel's spacing under TabGroup, a glyph's colour. Take 0.4.1 or later, whose upgrade moves the accordions, tabs and inks that 0.4.0's left to you.

What looks different on purpose: a TypographyLink with no tone takes the ink around it, which on a page is what muted gave and on a filled surface is legible where muted was not. Its addArrow glyph is a mark, one em of the link.