Changelog

• The selected option's highlight in SegmentedControl and Tabs shifts or resizes by up to half a pixel to match its option exactly.

• Select menus whose options are longer than the trigger come out wider, with each option on one line. Menus whose options fit the trigger do not move.

• None. select-item-hand-rolled-trailing lands as a warning.

In SiteFooterColumn: every link under a title moves up 6px.

In Prose: a figure under a paragraph, and everything after it, moves down 8px.

In Prose: a figure under a paragraph moves down 8px, everything after a figure moves up 16px, and a figure right under a heading moves up (32px under h2 to h6, 8px under an h1).

In Prose, every code block or table that follows a paragraph moves up 40px.

None. trim-rung-mismatch also reads --spacing-rhythm-trim-pair-display now, and flags it in a file that trims nothing, as a warning like the rest of that rule.

• Every carousel arrow is now a 28px round button with a 16px chevron, a card fill and a ring edge, at full opacity. Arrows that were already chips shrink from 32px with a 20px chevron. Each chevron sits 1px toward its point, which centres it by eye.
• CarouselControls no longer pulls itself 12px past the end of its row. That pull lined up a plain chevron's ink with the edge; a chip's edge is its shape, so it sits flush.

• carousel-arrow-variant-removed (warning): names a variant="bare" or variant="chip" left on CarouselPrevious, CarouselNext or CarouselControls. Delete it.

• A SearchTrigger with a shortcut moves its keycap 7px toward the end, so it sits as far from the end as from the top and bottom.
• A card holding only a CardHeader gains 20px under the header, the same as above it. Its text used to sit on the card's bottom edge. If you added pb-5 to work around it, nothing moves and you can delete it.
• CodeBlock showLineNumbers now numbers its lines. Every line read 0 before, because the counter classes compiled to nothing.
• A Lockup no longer grows past its container when one line in it cannot wrap (an install command). The page stops scrolling sideways on a phone and that line scrolls inside its own box.

• A Lockup size="lg" inside a Section loses 64px above and below and 16px at each side. If you had px-0 py-0! on it, nothing moves; you can delete that now.

• The page scrolls when the wheel reaches the end of a vertical ScrollFade.
• In Safari, a vertical region may bounce a little at its ends.

A horizontal Nav that overflows opens scrolled to its current item instead of to its first.

The cursor over Tabs, Nav items, radios, switches, menu items and options is the hand. Nothing moves.

• An AuthDialog that showed an error and was closed now opens clean the next time, instead of still showing the old message.

• A stack table in a server page now shows each value's column name on a phone.
• A layout="fixed" table in a server page now honours each column's width, and its firstColumnWidth / lastColumnWidth defaults.

The default SiteFooter strip's links lose their 8px inset, so they line up with the fine print when the row wraps on a phone. On a wide screen the gap between the fine print and the first link closes from 32px to the row's 24px.

• The page takes the kit's background and text colour. The token file now sets background-color and color on body, so a project that never added bg-background text-foreground to its own body stops rendering on plain white. A project that already sets them sees nothing change.
• Lockup at size="section" and size="page" loses its 16px side inset, so a section heading lines up with the cards, list or FAQ under it instead of sitting 16px in from them. A className="px-0" you added to fix that is no longer needed. The empty-state sizes (sm, md, lg) keep the inset.

raw-section-frozen-padding lands as a warning: a plain <section> padded with a numbered vertical class of 32px or more (pb-16, pt-12). Swap it for <Section>, whose pad and padTop read the rhythm rungs, or read one rung on one side (pb-(--spacing-rhythm-section)). --strict fails on it now.

The total time on a soundless player moves 8px in from the pill's right edge.

With reduced motion turned on, the fan now opens and closes without moving between poses. Before, the open rule outranked the reduced-motion one, so the cards still slid.

• The footer's year is filled in by the browser just after the page loads, so the server HTML ends at "©". It sits at the end of the line, so nothing beside it moves.

• DialogFooter showCancelButton and SheetFooter showCancelButton: Cancel moves from beside the actions to the left edge from sm up.
• AlertDialogCancel: the same, when it is the first child of AlertDialogFooter. Placed after the action, it now pushes the action left instead, so put Cancel first.

• In CommandDialog, the search field and the footer are inset 16px on both sides, the same as the rows' content. They were 12px. The search icon is 20px (was 16px), so it lines up with row icons and CommandItemMedia. The footer's last hint now ends where CommandItemMeta ends.

• In Command, a highlighted row's CommandShortcut turns foreground along with its label. It was muted.
• Kbd inside a Button: the keycap's edge now follows the button's label colour instead of a neutral grey ring, and its text is 80% of the label (was 70%). Outside a Button nothing changes.

• The highlighted row in DropdownMenu, Select, Command and Combobox is a soft neutral grey (bg-secondary) under foreground text, in both modes. It was the accent tint with accent text. Destructive menu rows are unchanged.
• Every overlay backdrop (Dialog, AlertDialog, Sheet, Drawer) now fades on the motion roles: 200ms in and 150ms out, as before, but a retune of the large and small roles now reaches it too.

• Every PageHeader with an action and children: the content moves up to the same distance below the title as a header without an action.
• The action itself moves from the title's cap top to centred on the title's first line.

• Every card fan: no bounce on hover, the hovered card straightens and lifts, the others darken.
• A fan using the default size or default cards is now 180px, with 96 by 128px cards fanned sideways, where it was 120px with 78px squares fanned upward. Pass your own slots and size settings to keep the old shape.

• Hovering or focusing a card in a card fan brings it in front of the others.

• A card clips its content to its own corners, so an image inside one is rounded. A card with no content looks the same as before.
• A focused card shows a focus ring and comes to the front.

• A square-cornered target catches flakes on a flat top. It used to be read as a pill whatever its corners, so a tall image caught flakes inside itself. A fully rounded button lands them exactly as before.
• A heading or text target catches flakes on its letters, not on the empty top of its box.

• Switching tabs on a strip wider than its space: the strip and the pill now move as one and stop at the same moment. A wheel or touch on the strip during the glide stops it. A strip that fits is unchanged.

• The first tabs of an overflowing strip are no longer cut off past the left edge where no scroll could reach them.
• An overflowing strip fades at each edge that has more tabs past it: the right edge at rest, both once you scroll, the left alone at the end. A strip that fits shows no fade.
• When the active tab changes, the strip scrolls it toward the middle.
• TabsList now renders a wrapper (data-slot="tabs-list-track") that holds the border, fill and corners, with the scrolling list inside it. Your className on TabsList goes on the wrapper. If you styled [data-slot="tabs-list"] directly for its border or fill, move that to the new slot.

• A search field and a button in action no longer run past the row's edge when space is short. Under 42rem of row width the actions take the room the title leaves, and a search field grows to fill it beside the button. When they do not fit beside the title, they drop to the next line together.
• With center (a tab set between title and actions), the row switches to three columns at 32rem of row width rather than at the sm screen width. Below that, the title and actions share the first line and the tabs take the next. Above it, the outer columns split what the tabs leave, so the tabs stay centered and no longer overlap a long title.

• Row lines under a pinned first column now show on every table.

• The page now scrolls when the wheel is over a table or a horizontal ScrollFade.

• WeekSchedule's Today, previous week and next week buttons change from outline to subtle: a neutral tinted fill instead of an accent border.
• The Button docs page, the examples and the pricing rule in the rules file now show soft and subtle where they showed outline.

• variant="outline" on Button no longer exists, so TypeScript fails on it, and the same goes for buttonVariant="outline" on a Calendar or any component of yours that forwards the variant to Button. Replace it with soft. Run node scripts/verify-ui.mjs to list every call site.
• New warning button-outline-removed: names each outline Button, buttonVariants({ variant: "outline" }) and Calendar buttonVariant, including the ones TypeScript cannot see. Badge's outline is not flagged.

• None. New warning brand-on-control: a brand colour in the className of a kit control (Button, Input, Textarea, Select and Combobox triggers, Checkbox, Switch, Radio, Slider, Tabs, Nav items, Segmented control). A shadow-brand-* glow is not flagged. Escape hatch: ui-md-allow-brand-control.

• Items in SiteHeader's right-hand slot no longer wrap. A crowded bar used to squeeze a two-word link like "Log in" onto two lines at phone width; it now stays on one line, and a bar that still does not fit overflows instead. If yours does, hide the text actions below md (hidden md:inline-flex) and move them into SiteNav, which Page composition in the rules now says. In the default navPlacement="start" layout the slot's children now sit inside one wrapper div, with the same 16px gaps as before.

• Your own text-display and text-jumbo text is set slightly tighter: -0.025em instead of the body's -0.01em. Kit parts look the same (Lockup's large title already used that value). If you added tracking-tight next to text-display or text-jumbo, you can delete it.

• Only in Windows high contrast mode: cards, popovers, menus, dialogs, sheets, drawers, badges with an edge, and code blocks in Prose now show a 1px outline. Before, their edge was a box-shadow, which high contrast mode removes, so they had no edge at all. Normal rendering is unchanged.

• A read-only Input or Textarea now sits flat on the muted fill with no shadow. It used to look exactly like an editable field.
• Combobox takes disabled (dims to 70% and will not open) and aria-invalid (destructive border and ring, as on Input and Select). Nothing changes until you pass them.

• The focus ring is darker in light mode and lighter in dark mode. --ring-focus moved from neutral-300 (light) and neutral-700 (dark) to neutral-500 in both. The old ring was under 2:1 against the page and failed the 3:1 a keyboard user needs to find focus.
• An off Switch has a darker track in light mode and a lighter one in dark mode, for the same reason: neutral-500 in both, up from neutral-300 / neutral-700.
• If you set --ring-focus in your own CSS, keep it at 3:1 against --background and --card in both modes.

• A vertical ScrollFade no longer cuts off a ring drawn outside a child's box. A Badge (its 1px edge), a focused Button (its 3px ring) or a focused field sitting flush against the region's left or top edge used to lose that side. The region now reaches 4px past its box and pads it back, so the content does not move and the ring shows whole. Seen first on a Badge at the top of a Sheet body.
• The vertical scroll thumb sits where it did. A horizontal ScrollFade (a Table, a CodeBlock) is unchanged.
• If you added padding inside a ScrollFade to clear a ring yourself, delete it.

• PageHeader: with an action, the action drops under the description when the title would get narrower than 240px beside it. It used to stay on the right and squeeze the title to a word or two per line.
• Pagination: when the numbered row does not fit, it turns into a compact row: previous, "Page 3 of 10", next. The switch point depends on siblings and reads the pager's own width, so a pager in a narrow card switches too. The pager now always fills its row (w-full), which is what it measures: in a flex row it no longer hugs its content, and with no count or page size it centres in the space it takes.
• Carousel: below sm, the default (bare) arrows sit inside the slide, so they now take the chip look there: a round filled button. Half-opacity chevrons on top of artwork could not be seen.
• Table: a narrow table fits before it scrolls. Below the xl container width (42rem) the column minimums drop from 160 / 128px to 112 / 80px, so a short three-column table on a phone no longer scrolls. A table that still does not fit scrolls inside a horizontal ScrollFade with its first column pinned: the cut edge fades, and a hairline appears on the pinned column only while content slides under it. table-container no longer scrolls itself. A stickyHeader table, and a surface="bare" one for the pinning, are unchanged. Installing table now also installs scroll-fade.
• TableToolbar: below the xl container width (42rem), the controls wrap with the rest of the row, and a search field grows from a 224px floor instead of keeping its fixed width. It used to squeeze to a cut-off placeholder beside a select.

• CopyLabelButton: the shorter face is now centred in the button instead of sitting against the left edge. Its gap and icon-side padding are unchanged: SwapButton reads both from the same tables Button uses (buttonGap and buttonIconSidePadding, now exported from button-variants).

• A Table text column no longer narrows to one word per line on a small screen. Text columns keep at least 128px, and the first column at least 160px, so the table scrolls sideways instead. On a wide screen nothing changes, since columns are already wider than that.
• Numbers, centred columns, checkbox columns, an empty actions header, and any column with its own width keep their old sizing.
• Default-density cells have 16px of side padding, down from 24px, when the table itself is under 576px wide. A table in a narrow sheet gets this too, not just a phone.

• A CodeBlock line that runs past the edge now scrolls under the kit's overlay thumb (fades in on scroll, out after a second, draggable) instead of the browser's scrollbar, with no reserved gutter.
• The text fades out toward the right edge so it no longer shows behind the copy button, and a left fade appears once scrolled. At the end of the scroll the right fade is gone.
• Every CodeBlock has 48px of right padding, up from 16px (on touch it was already 48px). The last characters scroll clear of the button.

• Every timed event in WeekSchedule sits 2px clear of the hour line above AND below it. It used to touch the line under it, and a neutral event touched both, because its edge ring painted outside the box. The ring is now drawn inside.
• All-day bars are 20px, the height of a one-line timed event.
• The hour grid scrolls with the kit's ScrollFade thumb instead of the browser's scrollbar.

• A text link painted with buttonVariants({ variant: "link" }) loses 16px of side padding. <Link className={buttonVariants({ variant: "link" })}>, the idiom for a link in a Server Component, kept the default size's px-4 because the class list was joined, not merged, and Tailwind emits px-4 after p-0. A "Forgot password?" link beside a label therefore sat 16px short of the field's right edge. It now lines up with the edge. Button was never affected. If you added px-0 or -mr-4 to compensate, delete it.
• buttonVariants now returns the same merged class list Button builds, so a link painted this way matches a Button of the same variant and size. Where two classes used to fight (the link rule's height, padding and corner against the size's, or a stray text-xs under the size's own text size), only the winner is left. If a link painted this way changes size, that is the cause. A className you pass still wins over the variant.

None.

The component index in docs/ui-md-rules.md now says when to reach for seven parts it described too loosely: SiteHeader (a marketing or docs top bar, not an app shell) and Nav (the sidebar of an app shell), SiteNav (the phone menu, not a bare Drawer), Brand (mattdowney.com projects only), Toaster (mount once, for showToast), Toast, Hr and Separator (each names the other), and Badge. No component code changed.

• A form in a card sits 8px lower. CardContent directly under a borderless CardHeader used to start 8px below the description, whatever it held. That is right for prose, and it put a form's first label on the description as if it were one more line. When CardContent holds a field (an input, textarea, select, switch, checkbox, radio group, Label, or a Select/Combobox trigger), the gap is now 16px, the cluster rung. Prose still gets 8px, and a bordered header still gets the full 20px. If you reopened this gap yourself with [[data-slot=card-header]:not(.border-b)+&]:pt-*, the kit's rule now outranks it for a form: delete yours.
• Input icons follow Button's size ramp. iconStart and iconEnd were a flat 12px at every size. They are now 12 / 14 / 14 / 16px across xs / sm / default / lg, the same as a Button of that size. A glyph inside actionEnd (a reveal-password or copy button) is resized to match. Text next to an icon moves over to keep the 8px gap: 32px (unchanged) at xs, 34px (was
  32. at sm and default, 36px (was 32) at lg. Text beside actionEnd does not move.

None.

Three additions to the rules an agent reads. No component or token changed.

• docs/ui-md-writing.md is new. It holds the portable rules for interface copy: verb-first button labels, sentence case, how to word an error, an empty state with one next action, and a confirmation that repeats the consequence instead of asking Yes or No. If your project has a docs/voice.md, it wins for wording. The AGENTS.md block gains two lines pointing at both, and it is replaced on this pull like any other.
• docs/ui-md-rules.md gains a "Where to start, by job" table under "Start here", and a "When the rules do not cover it" section. The uimd-build skill now sends an agent to the table instead of a fixed list, and asks it to name any call no rule covered.
• The component index now lists whole-screen recipes (settings, dashboard, landing), each linking to a working page on ui.mattdowney.com and naming the kit parts it is built from.

None.

CardFooter gains size="compact": a bordered footer with 12px above and below its actions instead of 20px, so the band is 52px with a sm button rather than 68px. It is for a dense grid of cards such as a dashboard, where that band repeats under every card. Reach for it instead of overriding the footer's padding through className.

• A bar Sparkline (including a MetricCard trend) with fewer than 12 points no longer stretches its bars across the card. Each bar keeps the width it would have at 12 points, and the bars sit against the right edge, newest last. Before, a short series drew wide bars whose rounded ends turned into ovals. Series of 12 or more points look the same.

• A MetricCard (or MetricCardValue) goal line too long for its card now ends in an ellipsis instead of wrapping to a second line. Short goal lines look the same.
• If you shortened a long goal line yourself with truncate, remove it: its overflow-hidden cut the bottoms off letters like p and g, because the line is cap-trimmed. The kit now does the shortening without that clip.

• An autofilled input, textarea, or select no longer shows Chrome's pale blue fill on a non-white surface. The token file clips the browser's forced background to the text (-webkit-background-clip: text) and fills the glyphs and caret with --foreground, so the field keeps its own bg-input-bg, shadow-xs, and focus ring. This is not the classic box-shadow: inset autofill hack: that hack paints over an element's own box-shadow, and Input carries one (shadow-xs) plus a focus ring (also a box-shadow in Tailwind v4), so it would have silently deleted both on autofill.

A code block or table nested in a list item now sits 12px clear of the text above and below it. It had no gap at all: the block's spacing only reached figures that are direct children of the Prose root, so a fenced block under a bullet drew its ringed edge flush against the bullet's line. Top-level code blocks and tables, and the 8px between list items, are unchanged.

Every SegmentedControl is shorter, squarer, and its selected option is accent-tinted instead of a raised white thumb. The widget now measures the same as a Button of the same size name, 28 / 32 / 40, where it measured 38 / 42 / 50 before. It used to size its options to the rung and let the track add padding on top, the way Tabs does, so a sm control stood 10px taller than the sm Button in the same title row. Corners come off the action ramp (rounded-action-sm / rounded-action / rounded-action-lg, options one step in) rather than rounded-full, so it reads as the same shape family as the button beside it. The thumb is now Tabs' indicator, accent-100 in light and accent-800 in dark under an accent label, with no shadow; the track is the same neutral well a TabsList sits in. iconOnly options are no longer forced square, since that rule only existed to keep a circle from reading as an oval. The onMedia tone keeps its black and white but takes the same radius and loses the thumb shadow. If a control was placed with a hand-tuned offset to line up with its neighbours, that offset is now wrong: delete it.

Inline code inside Prose now renders as the same chip the docs site uses for prop names and class names: accent tint (accent-100, accent-900 in dark), accent label, medium weight, 0.85em of the surrounding text. It was a neutral grey chip that inherited the sentence's size, so a code word in rendered markdown and the same word in an API table on the same page read as two systems. A monospace face also sets wider and taller than the sans at the same nominal size, so the inherited chip read a step large. Code blocks are untouched; they set their own size.

A vertical Stepper's connector below a step now fills whenever that step is below value, matching the horizontal rail. It used to fill only when the item's own state resolved to completed, so the documented state override (re-reading a finished step as active) greyed the segment under that step while later segments stayed green, which read as the flow having skipped one. A stepper that never passes state renders exactly as before.

ThemeToggle no longer animates, and it no longer draws its own glyphs. It imports IconSunHighFilled, IconMoonFilled and IconKeyboardFilled and swaps between them instantly. Same box, same sizes, same cycle.

It used to paint one circle that scaled up while a masking circle slid across it to carve a crescent, with eight rays retracting into it. That drawing was a hand-traced copy of Tabler's path data, and a copy has to be re-traced every time the set moves. Nothing gates one against the real glyph: it had already drifted into a visibly different sun with typecheck, verify-ui and the build all green. Importing the icons removes the whole class of problem.

Two of the three glyphs also changed. The sun was IconSunFilled, whose rays are short stubs running r=7 to r=9; it is now IconSunHighFilled, whose rays run r=7 to r=11, so the sun reads larger at the 12-16px sizes a menu row and a segmented pill actually use. system was IconDeviceDesktopFilled and is now IconKeyboardFilled: the row means "whatever this machine is set to", and half the machines reading it have no monitor to draw.

The system dot is gone. When the preference is system the button now shows the keyboard, the same glyph the segmented and menu forms put on that row. The dot only existed because a two-ended animation had nowhere to put a third state, and the docs already called it weak signage.

resolvedTheme is now optional. The glyph is a function of the stored preference alone, so nothing breaks if you drop it. Keep passing it and the accessible name still reports "system (dark)" instead of just "system". Existing call sites need no change.

theme-toggle now declares @tabler/icons-react, which is already in the kit's universal set, so it stays in kit and pulls in nothing new.

If you built the settings or menu form from the docs, swap those two imports too, or a stale IconSunFilled sits beside the updated button.

ThemeToggle's sun and moon are redrawn to Tabler's exact geometry, and this is the one thing in the entry you will see without touching your code.

Its rays were eight stroked lines that, with round caps, reached from the disc's edge out to r=9, so they touched the disc and the sun read as one solid spiky star. IconSunFilled draws detached stubs from r=7 to r=9, with a clear gap. The two were visibly different suns the moment anyone put the segmented form next to the button, which is how this was caught. The moon grew to match too: its disc now scales to IconMoonFilled's r=10 outer circle rather than to 7.5, cut by the same 6.5 circle Tabler uses.

The sun therefore reads slightly lighter and the moon noticeably larger. Nothing about the box, the sizes, the animation or the API changed.

Nothing, in practice. ThemeToggle is a new component and no existing markup renders it, and the SegmentedControl additions below are opt in: an option with no icon renders exactly the classes it did before.

One edge worth naming rather than burying. A segmented option now sizes any svg inside it (size-3 / size-3.5 / size-4 by rung, skipped where the icon sets its own size-*). label is typed string, so this reaches you only if you were passing an element through it from untyped code. If you were, give that icon an explicit size-* or move it to the new icon field.

A horizontal Stepper label now wraps inside a fixed measure, 128px at the default size and 112px at size="sm", instead of sitting in a zero-width box that could hold only one short line. The box still gives back exactly as much margin as it takes in width, so it contributes nothing to the row and the dots stay evenly spaced with the first flush left and the last flush right. Nothing about your markup changes.

Take this one if you have ever put more than one word in a horizontal StepperTitle, because until now it did not render the way it looked in the code. whitespace-nowrap on the label box and text-pretty on StepperTitle are both shorthands over the same longhand, text-wrap-mode. The box set it to nowrap, the title set it back to wrap, and a declaration on an element beats the value it inherits: the title was free to wrap, and in a zero-width box it wrapped once per space. A three-word title came out as three stacked lines. Under the measure it wraps where a reader would put the break.

The measure is fixed and does not grow with the container, so a label longer than a phrase still belongs in orientation="vertical". That was always true; it just used to fail by overflowing into the next step rather than by wrapping.

The completed step's ring, its check, and the connector behind it are now one colour, success-500, in both themes. The ring used to be a success-300 around a success-500 check, which is two greens in one 32px circle for no reason a reader could name, and the 300 was also the weakest mark on the light page at 1.66:1. If you had themed --color-success-300 to tune that ring, it no longer reaches the stepper; theme the 500 instead. Completed steps still recede, because they are still an outline on the page background with no fill: the quiet comes from how little ink they use, not from how little contrast.

Worth knowing if you are auditing: the 500 measures 2.85:1 against the light background, just under the 3:1 that WCAG 1.4.11 asks of a graphic carrying meaning. That is a chosen trade, and the state does not rest on colour alone. A completed step swaps its numeral for a check, which is a shape change, and the indicator's screen-reader text says "Completed:" outright. If you need the light rail to clear 3:1 on its own, override all three parts to success-600 together.

The connector running into the active step no longer blends from green to the accent. Every filled connector is the one success colour end to end. A filled connector means the segment is behind you, and everything behind you is done; the blend said the segment itself was in progress, which it never was, the step was. The junction it was smoothing does not need smoothing, since the active indicator carries a 4px accent halo outside its border and the line ends underneath it.

docs/ui-md-rules.md now opens with a component index, under "Reach for the component first": one row per component, keyed by the SITUATION you are building rather than by the component's name.

It exists because the rule it enforces was already in the file and was being broken by agents that had read it. The recorded case is a consumer's sign-in page built out of a Stack and four rhythm rungs, by an agent that had just read every section the uimd-build skill names. Lockup ships that page whole, and appeared in the rules file's other 85,000 characters exactly twice, both times incidentally, inside rules about other things.

The failure is retrieval, not comprehension, and that is why more prose was not the fix. An agent reaches for what it can name, so it reaches for Button and Stack and hand-builds the rest. The file was organised by rule (spacing, type, radius), which is the wrong axis for the question actually being asked, and at 85,000 characters adding another rule section makes retrieval worse rather than better.

The index is GENERATED from a @use-when marker in each component's own source, so the description lives beside the thing it describes and a second place to describe every component never exists. All 60 are seeded, and the generator FAILS on a component that carries no marker: an index with holes is worse than no index, because a miss reads as "the kit has nothing for this".

Nothing to do on your side. The index arrives with the rules file on your next pull.

One new rule, hand-rolled-composite, and like every new rule it lands as a warning first. --strict promotes it now.

It fires on a heading, then a paragraph, then an action, as adjacent siblings in one container. That shape is Lockup rebuilt by hand: the kit's stack for a prompt standing in for content, an empty result, an error, a success screen, a sign-in gate. Lockup owns that whole rhythm and ramps all four gaps by size.

The rule is deliberately narrow and will not catch every hand-built composite. Only whitespace and JSX comments may sit between the three parts, and each of the first two must hold plain text, because the same heading-then-paragraph shape is what ordinary prose looks like and a style rule that over-fires gets switched off in every repo that pulls it. A draft without those limits matched across sibling boundaries, walking from one component's heading to the next component's button and reporting a composite nobody wrote. A heading, paragraph and link inside real prose carries a ui-md-allow-hand-rolled comment.

stepper completed indicators drop from solid success-500 with a white check to an outline: the circle keeps the theme background, with a 2px success-300 edge matching the connector's color and width and a success-500 check (in dark mode edge and connector both hold the check's 500; muted rungs read as murk on a near-black canvas). The connector fill lightens with them (success-300 in light), including the gradient end that blends into the active step. A long run of finished steps now recedes so the active step carries the weight; before, ten solid green discs were the loudest thing on screen. The active step's halo doubles its alpha in dark (ring-accent-500/30); 15% was invisible there.

The check's stroke is heavier, and the reason is worth knowing if you set icon stroke anywhere. A Tabler glyph paints strokeWidth * box / 24 pixels of ink, so the nominal 2 it shipped with painted only 1.33px inside the 32px indicator and 1.0px at size="sm", against a ring and connector that both paint a true 2px. The check read thin and small next to its own rail. It now sets a stroke that inverts the formula (3 at the 16px box, 4 at 12px) to land exactly 2px at both sizes, on whole device pixels at 2x. The box is unchanged.

That stroke is pinned to the ring rather than reading --stroke-icon, and deliberately so: that token is matched to a font weight, so retuning it for labels would drift this check off the 2px ring beside it.

Nothing, unless you retune the accent. --accent-foreground (the label on a solid accent fill, e.g. the primary Button) is no longer hardcoded white. On browsers that support OKLCH relative color (Chrome 119+, Safari 16.4+, Firefox 128+) it reads the accent's own lightness and snaps to black or white at a threshold, so a light accent gets a dark label instead of an unreadable white one. The shipped accent is dark, so its label stays white and nothing moves. Retune --accent to a light color and the label flips to black on its own, with no per-color hand-tuning. Older browsers keep the white fallback.

This pairs the label to the fill wherever the fill is --accent (the primary Button's light-theme rest, and any consumer surface using bg-accent text-accent-foreground). The primary Button's DARK rest still uses the tuned accent-600 plate, which is dark, so its white label is correct and unchanged; if you retune the dark fill to a light color, point that plate at --accent so the paired label follows.

An agent that runs the install now wires one managed block into your AGENTS.md. It is fenced with <!-- ui-md:begin --> / <!-- ui-md:end --> markers and holds a two-line pointer: read docs/ui-md-rules.md before building UI, and follow docs/ui-md-upgrade.md to upgrade. This is the one hook Codex, Cursor, and other agents read, and it is what stops a fresh project from hand-rolling components while the kit's rules sit unread on disk.

It is safe by construction. The kit only ever touches what is between its two markers: on a first install it appends the block (or creates AGENTS.md if you have none), and on every later pull it replaces just that block to keep the pointer current. Everything you wrote above or below it is never touched, and the file is never overwritten. If you would rather it stay out, delete the block; keep the markers empty and a pull leaves them empty.

The rules file opens with a short "Start here" gate. The top of docs/ui-md-rules.md now leads with the six rules an agent breaks by reaching for another project's defaults (use the kit's components, space with the rhythm rungs, size type from the scale, elevation is shadow-ring-*, no alpha on semantic tokens, run the checker), so an agent that opens the file reads the mandate before the detail.

--icon-optical-scale is now in the rules doc, under the icon stroke ladder, where it should have been when it shipped. That ladder derives stroke 2 from Geist's stem (24 x 0.084 = 2.02) and tells you to retune the token rather than a call site, and it was silent about a third token that multiplies both rungs by 1.1.

The entry now carries the painted-pixel table, because the token values alone lead you to the wrong conclusion. The ladder is stated at icon box == font size, and no real control is built that way: Button runs 12/14/14/16px of icon against 11/12/13/14px of type. Compared in painted ink against a semibold label, the action rung reaches 79-85% of the label's stem on its own and 87-94% with the scale, so the scale closes part of an existing shortfall rather than overshooting, and turning it off makes icons lighter than the words beside them rather than better matched.

What it does cost is the pixel grid, and that is the real reason to turn it off. A tenth is the worst multiplier available: at 2x, scale: 1 paints Button's icon boxes at exactly 24 / 28 / 28 / 32 device pixels with lg's stroke at exactly 3, while 1.1 paints 26.4 / 30.8 / 30.8 / 35.2 with every stroke fractional, so both edges of every line land mid-pixel and the glyph renders soft. Largest is worst, because the fringe is the same width on a bigger drawing. --icon-optical-scale: 1 takes that trade.

Two things the scale does NOT touch, so nobody compensates for it twice: the counter ceiling is a ratio and a uniform scale moves gap and stroke together, and the property is the individual scale rather than transform, so it still composes with a chevron's rotate.

Every icon in the kit is about a tenth smaller and renders crisply. --icon-optical-scale ships at 1 where it shipped at 1.1 the day before. No per-component opt out; set the token to 1.1 in your own CSS to put it back.

The 1.1 was there to fill the box the way lucide did, and it does. What it also does is multiply every icon size by a tenth, and a tenth is the worst multiplier available on a pixel grid. At 2x, scale 1 paints Button's four icon boxes at exactly 24 / 28 / 28 / 32 device pixels with lg's stroke at exactly 3; at 1.1 they are 26.4 / 30.8 / 30.8 / 35.2 with every stroke fractional, so both edges of every line land mid-pixel and the glyph renders soft. The biggest button looked worst, because the same fringe covers a bigger drawing.

This is a trade and the entry says so, because the case for 1.1 is real. Measured in painted ink against a font-semibold label's stem, the action stroke reaches 79-85% of it at scale 1 and 87-94% at 1.1: the icons really are lighter than the words beside them now. The reasoning for shipping crisp anyway is that a weight 8 points light is something you notice if you go looking, where a soft icon is something you notice immediately. Raising --stroke-icon-action instead does not work: holding lg's stroke on the grid allows only 2.25 (what ships) and 3.0, and 3.0 closes the trash lid's counter to 0.63px, under the ceiling in the rules file.

auth-dialog is the other component edited, and its output is identical: the error copy it keeps on screen while the panel collapses moved from a ref written and read during render to state adjusted during render, React's own documented pattern for exactly this. The ref version drew two react-hooks/refs errors in any project linting with the React hooks plugin, which this repo does not, so it shipped clean from here and failed in a consumer. It was also a real correctness risk rather than a lint technicality: a ref write is invisible to React, so a render that gets thrown away could leave the retained message set to one the user never saw.

One new rule, icon-name-in-copy, and like every new rule it lands as a warning first. --strict promotes it now.

It exists because of what the previous entry costs you when you follow it. Moving your OWN icon imports from lucide to Tabler means renaming Inbox to IconInbox across your app, and the obvious way to do that is a find and replace on the word. A word replace cannot tell an identifier from the same letters inside a label, a placeholder, an aria-label, or a comment. The consumer this came from shipped 47 of them across 22 files: a nav reading IconInbox and IconCalendar, search fields placeheld with IconSearch…, a Save button labelled IconDeviceFloppy, and an aria-label reading IconSearch archived captures. Every check they had passed, because the code is correct: it type-checks, it lints, and it renders. Only the words are wrong.

The rule reads strings and JSX text, and deliberately not comments, because a comment is not copy and legitimately names types like IconProp. A string that holds a code sample is skipped, so a docs site showing <IconStar /> is quiet. A picker or a table that lists icon names on purpose carries a ui-md-allow-icon-name comment.

If you are about to do this migration, rename by identifier rather than by word: your editor's rename symbol, or a replace anchored on the import statement. Then run the checker and fix whatever copy the rename reached anyway.

Every icon in every kit component is now a Tabler glyph (@tabler/icons-react) where it was a lucide one. This is a whole-kit rendering change with no per-component opt out: buttons, inputs, menus, the dialog close, table sorters, every place the kit draws an icon now draws Tabler's version of it.

The measurable parts are unchanged on purpose, which is why Tabler was the choice. Both sets are stroked inside a 24-unit viewBox at a default stroke of 2, so the two icon-stroke tokens (--stroke-icon 2, --stroke-icon-action 2.25) carry over untouched and the button label still pulls its glyph weight up to Semibold the same way. Alignment does not move either: it rests on Geist's cap band, a fact about the font, not the icon set. What changes is the drawing: Tabler's joins are rounder and several glyphs are simply shaped differently, so expect a friendlier line and, in a handful of spots, a different picture for the same idea.

A few icons have no same-name twin and were mapped to the closest Tabler glyph: a trash can, a "more" affordance (Tabler draws it as three dots), a lightning bolt, a globe (Tabler's is world), an info circle, a hamburger, and the sort/select chevron pair. If you passed your own icon elements into a kit component nothing here touches them; only the kit's built-in icons changed.

Icons render a touch larger than the raw Tabler glyph. Tabler draws inside a wider margin than lucide did, so at the same box every icon read about a tenth small, worst in menus. The tokens file now ships one rule, .tabler-icon { scale: var(--icon-optical-scale) }, with --icon-optical-scale: 1.1, so every Tabler icon fills its box the way lucide's did. It also lifts the stroke by the same tenth (a 2 reads as ~2.2). Set --icon-optical-scale: 1 in your own CSS to turn it off; it is a normal token, so it survives the next pull.

None. No new verify-ui rule ships with this entry.

One dependency note that is not a rule but can still break a build: the kit now declares @tabler/icons-react instead of lucide-react. A fresh add installs Tabler for you. If your OWN code imported lucide-react and was relying on the kit to pull it in transitively, add it to your project directly; it is no longer a kit dependency.

A selected TableRow is neutral now, in both modes. It was bg-accent-50 / dark:bg-accent-950, the quietest rung at each end of the accent ramp. Quiet in lightness, not in chroma: the dark step is C 0.0753 at the accent hue, and a select-all across a 39 row table painted a wall of navy. That is emphasis, and a selection is a state. The fill is now a neutral alpha tint, bg-neutral-900/5 in light and bg-neutral-100/[3.5%] in dark, at C 0.0017 and C 0.0024, which cannot accumulate into brand colour at any row count.

It is a tint rather than a scale step because no solid rung is free. bg-card and bg-muted are adjacent neutral steps in both modes (L 0.9886 / 0.9725 light, 0.1651 / 0.2242 dark), and bg-muted is the header and the footer, so a selected row landing on it reads as chrome. The new values clear all three grounds by roughly the same 0.02 the old pair claimed: light lands at L 0.9531, 0.0355 under card and 0.0194 under muted; dark lands at L 0.2019, 0.0368 over card and 0.0223 under muted. Both also clear the striped fill (L 0.9776 light, 0.1824 dark) by about 0.02, which the accent pair did not: accent-950 sat 0.0026 off the dark stripe and was told apart by hue alone, as was accent-50 from muted in light at 0.0025.

Nothing else moves. The menu-row recipe (accent-100 / accent-800 + text-accent) is untouched everywhere it belongs: Dropdown, Select, Command, Combobox, Calendar, Tabs, the Nav pill, badges, ghost hovers. A popup row is one transient highlight in a narrow column; a table row is full-width, persistent, and multi-select, and that is the whole reason these two differ.

Nothing moves on its own. One addition to page-title-row:

New optional titleBadge prop. The slot for a count or a status pill beside the page title, a Badge reading "39 items" or "Live". Until now the only inline slot was subtitle, and a Badge passed there renders broken: that wrapper is an inline <span> carrying truncate, and overflow does not apply to a non-replaced inline box, so the pill comes out unclipped and hanging low against the letterforms. A consumer hit exactly that with a row count, which is what the prop exists to stop. titleBadge is a direct child of the title cluster, centred on the title's cap band rather than seated on its baseline, in a zero-height wrapper so it contributes nothing to the row's height: a page carrying a count and a page without one put their titles on the same line. Controls are untouched by this and still belong in actions.

Nothing moves on its own. One addition to carousel (a kit extra — pull it by name):

New export carouselTweenRestStyle from carousel-tween.ts. A server-rendered coverflow paints its raw HTML — every slide full size — before the tween's first frame, so the neighbours visibly snap down after hydration. This returns the pose the tween will compute for a slide at a given distance from centre, as an inline style for the markup, so the pre-hydration HTML already matches and the handoff is invisible. Pass it the same scaleMin/opacityMin given to the hook; hand-copying the numbers instead is the drift this export exists to prevent. It fixes the pose, not the track: when the start slide is dynamic or mid-list, Embla still paints the strip left-aligned until init, and the right remedy there is fading the whole carousel in on the api's arrival (the "Coverflow scale" docs example does this). The hook's header comment now documents both remedies.

Nothing moves on its own. The carousel arrows (CarouselPrevious / CarouselNext, a kit extra) gain two opt-in props:

variant: "bare" (the default, today's naked chevron at half opacity) or "chip", a filled circular button (bg-card, ring edge) at full opacity, for arrows sitting over artwork, where a half-opacity chevron goes illegible.

tone: "default" (the theme's neutrals) or "accent", which reuses Button's accent recipe. A bare accent arrow is an accent-coloured chevron; a chip accent arrow is a solid accent fill with Button's exact rest and hover pair, so it matches an accent button beside it.

Nothing moves on its own. One addition to carousel (a kit extra):

New opt-in edgeFade prop on CarouselContent dissolves the slides at the viewport's edges instead of clipping them on a hard line. It is for peeking layouts (a fractional basis-*, a basis-auto strip, the coverflow tween), where the neighbour slide is otherwise cut dead at the clip edge. The gradient's stops trace a smoothstep, zero slope at both ends, so the fade neither snaps off at the clip edge nor leaves a findable line where it lands on full opacity. The width is a fixed pixel band, not a viewport percentage (a percentage read as a kiss on one layout and swallowed the whole neighbour on another): pass a number to tune it, true means 64px, and it should stay comfortably inside the neighbour's visible peek. Dimming the neighbour is the coverflow tween's job, and its opacityMin should stay near its default when both run. It is position-driven, like the coverflow tween: each edge fades only while content actually extends past it, ramping in over one slide of travel, so at rest on the first slide the leading edge stays a hard line (a loop carousel keeps both edges faded). A mask rather than an overlay, so it works over any page background, and it follows orientation. If you hand rolled this as a static mask utility on viewportClassName, the prop replaces it and fixes that resting edge.

Nothing moves on its own. Two additions to carousel (a kit extra — pull it by name):

New opt-in hook useCarouselTween (its own shipped file, components/ui/carousel-tween.ts — a hook cannot leave the "use client" module and still reach a Server Component as a value) gives a peek carousel the coverflow treatment: slides scale and fade with their live distance from centre, on a smoothstep curve. The curve is the point — a piecewise-linear ramp puts a velocity corner at each end and the arriving card visibly pops; smoothstep's zero slope at the centre also absorbs Embla's settle jitter, so no dead band is needed. Position-driven, so it tracks a drag 1:1 and inherits the carousel's reduced-motion handling.

The duration default now documents its range. 14 is tuned for short hops; over a ~500px slide it overshoots the snap and creeps back — a double bounce. Measured: 18 lands with 0.7px overshoot and is still by ~430ms. Long-slide carousels should pass 18-25.

Dialog, AlertDialog and Sheet space their heading from the body on the heading-md rung (24px), up from 16px. The title carries cap-trim, which removes the font's top space, so a 16px gap measured from the cap edge read tight against the body, most visibly when there was no description to soften it. 24px is the same rung PageHeader already gives a text-lg heading, so a modal heading and a page heading now clear their content by the same amount. Drawer is unchanged: its content spaces a short form, not a modal header.

The BreadcrumbBack chevron now recolors and nudges left on hover. It was meant to from the start; the hover state was wired to a group that was not there, so nothing fired. If you relied on the chevron staying still on hover, this is the change that starts it moving.

A <Card animateHeight> mounted on a non-card host no longer clips a focus ring at rest. The shell used to lean on the Card base class to hide content mid-animation, which also clipped a non-card host permanently. It now clips only while a height animation is running. A plain Card is unaffected.

Nothing, unless you reach for the new token. This is an addition.

New: --container-content and its max-w-content utility. It caps a block that is READ, where max-w-measure caps a line of copy. Capping only the paragraphs leaves the code blocks between them running to whatever width the layout gives them, so the two edges keep no relationship at all: on this kit's own docs a paragraph sat at 60ch while the code block under it ran to 976px, half again the width of the sentence introducing it.

It resolves to var(--container-measure), so a code block and the copy above it share one edge and retuning the measure moves both.

Put it on the blocks, not on the column that holds them. Some blocks in a document are read and some are examined, and only the first kind answers to a measure. A data table, a chart or a component specimen takes the width its content needs; capping those makes a table unreadable in service of a rule that was never about it. Capping the column was tried first and caught everything, and no column width is right for both a sentence and a twelve-column table.

A block a little wider than its copy was also tried and is the worst of the three: it reads as a near-miss rather than as hierarchy. 60ch is not a squeeze for code either, which is the usual objection to going flush: it renders 636px in Geist, about 81 monospace characters at 13px.

It is the one cap that carries no text-wrap pairing: text-wrap inherits, and the copy inside a block already brings its own.

A selected TableRow is much quieter, and its cells stop turning blue. The row used to stack two effects: an accent-100 fill (accent-700 in dark) plus text-accent forced onto every td. Across a full-width table with several rows selected that reads as a slab of brand colour rather than as a selection, and the text recolor carried most of it, since accent-500 is C 0.2489 against the fill's 0.0342. It also applied unevenly: a cell that set its own text-foreground kept it while its neighbours turned blue, so the row rendered half-applied.

Selection is now a fill and nothing else, at the quietest rung on each end of the ramp: bg-accent-50 in light, bg-accent-950 in dark. Both are the same ~0.02 lightness step off bg-card, which is the ground a Table paints for itself. The dark step is not the accent-900 the menu-row recipe mirrors to: its L 0.2407 sits 0.016 from bg-muted (0.2242), and bg-muted is the header and footer, so a selected row would have read as chrome.

If you were relying on the blue text to find the selected row, pair the fill with the cue that should have been carrying it: a checked checkbox, or a count in the toolbar above the table.

A selected row in a striped table is now actually painted. The stripe and the selection are both backgrounds on the same tr, and the stripe's selector descends from the table element, so it scored (0,2,2) against the row's own (0,2,0) and won the cascade on every even row. Selection was invisible on half the table, and had been since striping shipped. The stripe now excludes a selected row outright, so the two no longer compete. Only striped tables are affected, and only their even rows.

Nothing else changed. The menu-row recipe (accent-100 / accent-900 + text-accent) is untouched everywhere it belongs: Dropdown, Select, Command, Combobox, Calendar. A popup row is one transient highlight in a narrow column; a table row is full-width, persistent, and multi-select, and that is the whole reason these two now differ.

Nothing. No rule was added and no severity was promoted.

What arrives is a second skill and two procedure changes, aimed at one gap: the rules shipped, and nothing read them.

uimd-build installs alongside uimd-pull at .claude/skills/uimd-build/SKILL.md. uimd-pull fires on "update the kit", which happens a few times a year. uimd-build fires on building a page or a component, changing spacing, or touching typography, which is every day, and it routes to the Page rhythm, Spacing and layout, Type scale and Hard rules sections of docs/ui-md-rules.md BEFORE class strings get written rather than after. Reading them afterwards makes them a cleanup pass, and a cleanup pass preserves pixel counts and loses relationships.

The upgrade procedure now wires the checker into package.json during the pull, as "verify:ui", and calls it from the build or CI script. It used to say "wire it into the build/CI if it is not there", which was a suggestion at the end of a long checklist and was skipped. A checker that ships as a file and is never run enforces nothing.

The AGENTS.md snippet now covers building, not just upgrading. For Codex, Cursor, or anything else outside Claude Code, that is the only pointer at the rules that exists, and it used to mention the kit only when installing it. The kit still does not write to your instructions files.

Nothing here is required. If a project already runs the checker in CI and its agents already read the rules, this changes nothing for it.

• AuthDialog is 32px shorter when there is no error, which is nearly every open. It used to hold an empty line under the description so an error could appear without moving the panel. That reserved line is gone: the description now sits 16px above the first provider button instead of 48px. On a short panel (two providers, no passkey) the hole between the description and the buttons is what this closes.
• An error now grows the panel instead of filling a slot. The message region animates open over 200ms, the same timing as a disclosure, and the panel grows from its centre because it is centred vertically. Under prefers-reduced-motion: reduce it appears with no transition.
• The gap above the error message is 4px, not 12px. Neither the description nor the message is cap-trimmed, so both still supply their own half-leading; the 12px was the header's trim-compensated rung spilling down from the title and painted the pair about 8px loose. With an error showing, the panel is now 24px taller than its resting height rather than 32px.

Nothing about the public API changed, and the message is still announced. The announcement moved to a permanently mounted screen-reader-only region whose text tracks the error exactly, so clearing and re-setting the same message is still announced as a repeat. data-slot="auth-dialog-error" still names the visible message.

• A completed step in Stepper is now green, not accent. The circle, its border and its check mark read --success, and the connector behind it fills green to match. The active step is unchanged: it stays accent with its ring, so the flow now separates three states by hue rather than two, and "you are here" is still the only thing wearing your brand colour.
• The connector that lands on the active step blends from success to accent. Only that one. A line between two completed steps stays solid green, because a connector's two ends match the two circles it touches; gradienting every line that leaves a completed step would fade it to accent and land it on a green circle.

This is why --success reads "confirmation and completion" in the token table rather than "confirmation" alone. If you had leaned on the accent-coloured completed state to carry your brand through a checkout or onboarding flow, the active step still does that, and StepperItem's state prop still overrides any step's treatment by hand.

A new token ships with this: --success-foreground, the text and icon colour that pairs with a --success fill. It mirrors --destructive-foreground and defaults to the same near-white in both themes. Success was the only intent colour shipping a fill with no partner, so anything of your own painting on green had to borrow another token's foreground; it no longer does.

• Nothing. segmented-control is a new component and changes nothing you already have. It arrives with kit, since its only npm dependency is motion, which is already in the universal set.

SegmentedControl is a compact in-place switch for one of a small set of options, drawn as a pill group with a sliding thumb: a unit toggle, a view mode, a billing period. It is a radiogroup, not a tablist, so reach for it when the choice changes a value and for Tabs when it swaps a panel of content. Arrow keys move the selection with wrap-around, an aria-label is required, and the thumb is a single persistent element rather than a per-option shared layout, so it cannot stretch across the track mid-slide. size reads the same control ramp as Button and Tabs (28 / 32 / 40px of option, plus 4px of track each side); tone="onMedia" swaps the palette for fixed black and white with a backdrop blur, for sitting over a photo.

• A toast behind the newest one is now a clean blank card edge instead of cut-off text. Fire two toasts and the older one used to stay fully painted while being squashed to the new one's height, so its words and buttons showed through, clipped. It now fades its contents the way sonner's own deck does, and hovering the stack still expands it to a readable list.
• A toast whose panel had been opened no longer stands out below the deck. Opening a panel releases the card's height so it can grow; once that card was pushed to the back it kept the taller height and hung past the stack.

Both fixes have the same cause, worth knowing if you have restyled toasts: toast.custom() bodies are always marked data-styled="false" by sonner, and sonner's collapsed-deck CSS is split across that attribute. The rule that hides a back toast's contents is gated on it; the rule that clamps a back toast's height is not. The toast item now ships the missing half.

• Every left-aligned title in the kit now wraps with text-pretty instead of text-balance, so a title that runs to two or more lines gets wider. CardTitle, DialogTitle, AlertDialogTitle, SheetTitle, DrawerTitle, ToastTitle, StepperTitle, PageHeader's heading and prose's h1-h6 are affected. text-wrap: balance resolves to the narrowest width that still fits the text in the same number of lines, so a balanced two-line title stopped short of its container's right edge while the description under it ran all the way, and the two left-aligned blocks finished in different places. A single-line title does not move at all: neither property does anything until the text wraps. A wrapped one keeps the same line count in almost every case and simply fills the measure, which can move the break point by a word.
• Titles longer than about six lines change behaviour more than that. Chrome stops applying balance past that many lines, so those titles were already wrapping normally and now gain orphan protection they did not have.
• TooltipContent keeps text-balance, and so do the max-w-measure-heading and max-w-measure-heading-relaxed caps that Lockup reads. Nothing about tooltips, lockups, or centred hero headings moves. The rule is the box, not the element: balance stays where the box hugs the text (w-fit) or the text is centred, because that is where there is no sibling edge to mismatch and the equalised lines read as a deliberate shape.

• DashboardCardHeader takes actionInset ("icon" | "flush", default flush). The old blanket outdent conflated two things the slot carries: an icon button, whose box extends past its glyph and wants the glyph seated on the inset, and a badge/count/caption, whose visible edge is its box edge and must not be pulled off the inset. Splitting them makes the common drop-in case correct with no flag and asks the button case, the one that knows it has chrome to compensate, to declare it.

• A DashboardCardHeader action that is not an icon button moves 6px away from the right edge, onto the content inset. The header used to outdent every action by 6px, a correction meant only for an icon button's transparent chrome. A Badge, a count, or a caption passed as action was pulled 6px too close to the edge and read lopsided against the title. Those now sit flush. An icon Button or Kebab action needs actionInset="icon" added, or its glyph moves 6px inboard and reads adrift. The kit's own two examples that use an icon action (Compact Header, Tabbed Filter) carry the flag now.

• Icon alignment rests on a property of the font, and Geist happens to satisfy it exactly. Icons sit in items-center rows, so flexbox centres them on the text's line box, whose centre is (ascent - descent)/2 above the baseline and cannot be moved by line-height. The eye reads them against the cap band, centred capHeight/2 above the baseline. For Geist both are 355 per 1000 em, so icons land dead centre and no component needs a nudge. Point --font-sans-custom at a face that misses this and every icon in the kit shifts at once with no class change, no CSS change and nothing failing. docs/ui-md-rules.md has the check and the one-token correction.

• Two new tokens, --stroke-icon (2) and --stroke-icon-action (2.25). They ship from base into :root, so your own unlayered :root overrides them. They exist because icon stroke is a property of the typeface, not of a component: if you swap Geist for a face with a different stem, measure its stem in em, multiply by 24, and set these two rather than touching call sites. The full derivation, including the counter ceiling that caps the stroke, is in docs/ui-md-rules.md.

• Every button icon gets heavier and most get bigger. Button glyphs were rendering at Lucide's stock stroke of 2, which measures out to Geist Regular, while button labels are font-semibold: two weight steps apart. Icons now read --stroke-icon-action (2.25), and the icon box steps 12 / 14 / 14 / 16px across xs / sm / default / lg, up from a near-flat 12 / 12 / 12 / 14. The stroke could not move on its own, because at a 12px box the tightest counter in the icon set (Trash2's lid) already had only 0.97px of clearance, so a heavier stroke with no extra size fills counters in rather than adding weight.
• A button with an icon gets ~2px wider wherever its glyph grew, so a tight row of iconned buttons can rewrap. Icon-only buttons keep their box and only the glyph inside changes.
• variant="link" is deliberately excluded. It is the one variant that sets font-normal, so its glyph stays at stroke 2 and would otherwise have gone heavier than the word it sits in.
• Input, Badge and prose icons are unchanged. They sit beside regular-weight text, where the stock stroke was already the right answer.
• An iconned button's icon-side padding now scales with its size. It was a flat 12px on the icon side at every size, which balanced only at sm: at lg the icon was crammed to the edge and the button read right-heavy, at xs the asymmetry was reversed. The icon side is now 2px tighter than the label side at each size (6/10/14/18px across xs/sm/default/lg). Any button with a leading or trailing icon shifts its contents slightly, and a tight row can rewrap.

• cn() is extended, because tailwind-merge cannot read a theme. It ships a fixed map of Tailwind's stock scales, so a utility built from a token the kit adds falls outside every class group it knows. Two such classes both survive the merge and land at equal specificity, so stylesheet order decides which one paints. That is not the call site, and it is not stable.

  Measured: 13 of 18 custom utilities failed to override. Two failed worse than failing. text-display and text-jumbo look like colour names, so they were sorted into text-color, and cn("text-muted-foreground", "text-display") dropped the colour and put nothing in its place.

  registry/lib/utils.ts now teaches it the kit's container sizes, font sizes and control radii. Spacing is deliberately not taught: the named form (h-site-header) is banned because Tailwind inlines a spacing value at compile time, and the rung form h-(--spacing-site-header) is an arbitrary property that merged correctly all along. Teaching the frozen spelling would make a banned one behave.

• DashboardCardHeader takes inset. A card header and the body under it share one left edge, so their side padding is one decision, and until now the header was pinned at 16px with no way to say otherwise except a className override that moves one edge and leaves the other. default (16px) is the row tier and stays the default, so nothing moves. loose (24px) is the prose tier, for a card whose body is paragraphs rather than rows, where 16px reads thin once the card is wide. Set the body to match in the same edit. No third value, since a third inset is a third left edge to keep in step.

• Anywhere a caller was already overriding one of 13 custom utilities, the override now takes. Those call sites were shipping both classes and getting whichever Tailwind emitted later, so some of them were painting the component's default and will change. Check any use of max-w-measure, max-w-chrome, text-display, text-jumbo, or the rounded-action* ramp passed through a className.
• <Prose className="max-w-none"> now actually removes the cap. That is the opt-out Prose has always documented, and it never worked, so a consumer relying on it has been rendering capped prose and will see it go full width.

• verify:registry gains one check, and it fails the build rather than warning, because it cannot fire on existing code: it only triggers when a token is added to --container-*, --text-* or --radius-* without being added to the list in registry/lib/utils.ts. Nothing already in the kit trips it.

• A band scale has no floor, so smooth the series, never the component. The chart rule already said how a baseline is chosen and stopped there. What it never said is that the band making a line honest will stretch any range to the full height, so it cannot tell a five-point drift from five points of sampling noise. A consumer hit both halves at once on newsletter tiles: an open rate spanning 5.7 points across twenty sends, and a click rate where one click moved the number by a point, drawn as a sawtooth that read as violent movement in a series that was flat.

  The fix is a rolling mean in the consumer, over a window measured against its own data. That consumer counted direction changes to pick one: raw ran 12 on open rate and 10 on click rate, a 3-send window gave 8 and 6, a 4-send window 5 and 4, and a 5-send window went back up to 7 on click rate, because over-smoothing starts beating real turns against their neighbours.

  Sparkline takes no smooth prop, and that is the rule's point. A drawing component that quietly averages what it was handed is the same lie as a band-scaled bar. The prop would also let one card print a number while the line beside it ends on another, which is exactly what smoothing costs: name it in the accessible label, and prefer area over line, because a filled band reads as a level where a line invites you to take a point off it.

• A rule for when a text button gets a leading icon. The kit documented the mechanics thoroughly (element vs bare component and the server/client boundary, iconSize, the reduced padding on the icon side, the heavier in-button stroke) and never said when to reach for one. So consumers drifted, and the tell is a control row where the create button has a +, the destructive one has a trash can, and the two beside them have nothing, with no reason available for any of it.

  Two halves. A glyph is allowed only where it is the conventional symbol for that exact action, tested by hiding the label and asking whether the action can still be named: + is add, a trash can is delete, and a check mark is approve and save and confirm and done, so it is decoration. And inside one button group it is all-or-nothing, because a single iconned button beside plain ones reads as the important one, which is an emphasis signal the variants already own.

  One override: a destructive action keeps its icon even in an otherwise plain group, since the button is red and the glyph is what keeps the meaning off colour alone (WCAG 1.4.1).

  Icon-only buttons are untouched. There the glyph is the label and carries an aria-label; this rule is about a glyph sitting next to a word.

  Deliberately prose, not a checker rule. Whether a glyph is conventional for an action is a judgment about meaning, so a checker would fail honest call sites and pass dishonest ones. The group half looks checkable and is not: a group is a visual cluster, not a DOM shape.

• rung-as-interior-padding (warning). A rhythm rung read into padding on opposing sides: p-, px-, py-, or pt- and pb- together in one class string. A rung measures the space between two blocks, and painting one as padding is correct where something sits between them that makes gap impossible: a border-t above a footer row, or reopening the gap under a borderless CardHeader. The kit ships both, and a single side is never flagged. Opposing sides are not a gap between anything, they are the block's own inset, and the ladder does not measure interiors. peer is 40px because that is what two peer blocks need between them, which says nothing about what a page shell should hold inside it.

  This rule exists because a consumer read "every vertical gap between blocks comes from a rung" as "every vertical space comes from a rung" and padded every page shell with peer and section. Each page opened about 120px taller than the rest of their site and nothing in the kit said it was wrong. Use the numbered spacing scale for an inset. Where the padding really is a gap a boundary stops you writing as a gap, carry a ui-md-allow-rung-padding comment and name the boundary.

• offsystem-color-on-kit-component (warning). A raw Tailwind hue (bg-pink-500, text-violet-400) in the className of a kit component. It repaints the component from outside the kit's colour system, and cn() is tailwind-merge, so your class wins the base colour while every state the component paints for itself - hover, disabled, open, checked, the focus ring - keeps the colour it was built with. That is a control which looks right at rest and wrong the moment it is used, and it is also the one colour on the page that does not flip with the theme.

  This is not a ban on Tailwind hues. They are yours to use in your own markup, exactly as the colours page says, and are only flagged inside a kit component. Kit tokens are not flagged there either: <TableCell className="text-foreground"> and <CardHeader className="border-b border-border"> are ordinary composition. Names the kit ships its own scale for (neutral, accent, destructive, success, warning, chart) are read out of the token file and resolve to the kit ramp, so they are never off-system. Where the component has a variant, that is the fix and it moves every state together. Where it does not, re-point the token for the scope (--accent, --muted, --card on a wrapper), or colour a wrapper instead of the component. Deliberate exception: ui-md-allow-kit-recolor.

  The part names come from the installed kit's own data-slot attributes rather than a list in the checker, so a component added or renamed upstream is covered without an edit here.

• carousel no longer reads autoHeight in CarouselItem. It was destructured and never used, which trips @typescript-eslint/no-unused-vars in a project that lints its components/ui. Nothing about the rendered slide changes, and it was not fixable on your side: the next add -o overwrites the file.

• carousel now installs embla-carousel-autoplay and embla-carousel-fade alongside embla-carousel-react. Both are first-party plugins from the same monorepo and maintainer as the engine you already had, pinned to the same 8.6.0, MIT, with zero runtime dependencies of their own and a peer on embla-carousel that your install already satisfies. So the new surface is two packages and nothing transitive.

  They are declared rather than left to you because the alternative is a docs page whose examples do not run until you notice a missing import. carousel already lives in kit-extras precisely because it brings a runtime package; this does not change which bundle it is in.

• A vertical Carousel's arrows start inside the viewport and move outside at sm, which is what the horizontal arrows already did. Vertical had only the outside position, at 48px above and below its own box, so any container that did not happen to leave 48px of room clipped them. Under an overflow-hidden ancestor that produces a control you can see part of and cannot click, with nothing in the console. A vertical carousel with room to spare is unchanged at sm and up; below that its arrows now sit over the slide the same way the horizontal ones do on a phone.

• Carousel takes an autoHeight prop. Off by default, so nothing moves unless you ask for it. On, the viewport sizes itself to whichever slide is in view, so slides of different heights each get their own instead of every one being stretched to the tallest.

  Horizontal only, and ignored when vertical. That is structural, not a missing feature. Embla measures its scroll bounds once at init. On the x-axis the viewport's height is not the scroll axis, so changing it afterwards costs nothing. On the y-axis it is the scroll axis: a viewport sized after init leaves Embla believing there is nothing to scroll, which disables both arrows and renders every slide stacked for a frame first. A vertical carousel needs a bounded height from CSS, before Embla measures. CarouselContent takes a new viewportClassName for exactly that, and the distinction matters: className lands on the flex track, so a height there does not bound the element that clips and every slide renders stacked. viewportClassName="aspect-square" bounds the viewport and derives the number from the carousel's own width. Same split, and the same reason, as ScrollFade's viewportClassName.

  Two things it gets right that a hand-rolled version usually does not. It measures the slide, never the viewport it resizes, because reading the element you are sizing feeds your own value back in. And it keeps a ResizeObserver on the slides, because slides change size after mount constantly: an image with no intrinsic size finishing its load, a font swap, text reflowing. Without that the viewport keeps whatever it measured before the image landed. It runs in a layout effect, so the first height lands before paint rather than as a visible jump.

  That observer is the reason this is opt-in rather than the default: a gallery of one aspect ratio does not need it. Under prefers-reduced-motion the height is still set and only the 200ms transition drops, because here the height is structural, not decoration.

• A CardHeader followed straight by a CardFooter no longer collides with it. The header carries no bottom padding on purpose: whatever follows owns that gap, which is why CardContent supplies its own top padding. A footer cannot do the same. Its padding sits below its own border-t, and the missing space is above that line, so a card with a header and a bordered footer and nothing between them drew the rule across the description's descenders. Borderless footers had the same hole with no line to make it obvious: they were told to borrow 20px from the content above, and there was no content above.

  CardHeader now supplies its own 20px when a CardFooter is its next sibling. Any card built that way grows 20px taller. A card with a CardContent between the two is unchanged.

• Every cap-trimmed title sits 4px further from its description. --spacing-rhythm-heading-pair goes 8px to 12px, which moves PageHeader and the Header part of Dialog, AlertDialog, Sheet and Drawer. Nothing else reads that rung.

  8px was derived to paint what the plain 4px pair rung paints on an untrimmed box, and that arithmetic was right as far as it went. What it missed: cap-trim puts the title's bottom edge at the baseline, and a descender still paints below the baseline. So a title with a p or a j in it spends 0.254em of the gap on ink, and a title without one does not. "Delete this project?" read cramped while "Terms of service" read fine, at the same token.

  It gets worse as the title gets bigger, because that 0.254em is a fraction of the font size: about 3px under a 12px heading and about 7px under a 28px one. 12px covers the descender case at every size the kit ships and leaves the clean case a pair rather than a separation.

  If you override this token, you are unaffected. If you set a heading group by hand on the plain pair rung, you are also unaffected, and trim-rung-mismatch already warns about that.

• A DialogTitle, AlertDialogTitle, SheetTitle or DrawerTitle that wraps to two lines is now readable. All four carried leading-none and text-balance, which contradict each other: text-balance only does anything when the text wraps, so a title carrying it expects two lines, and at a line-height of 1.0 the second line's ascenders collide with the first line's descenders. CardTitle had already reached the other answer and says so in a comment. All four now read leading-snug, the same as CardTitle.

  A single-line title does not move. cap-trim collapses the box to cap-to-baseline whatever the line-height is, so the change reaches only a title long enough to wrap. If yours wrap, those overlays get taller by the added leading.

• A MetricCard badge no longer pushes the line under it down. The value row is baseline-aligned, so its height is max(above-baseline) + max(below-baseline). Cap-trimming the value took its below-baseline extent to zero, which is the point, but it also handed that edge to whatever else sat in the row: a sm Badge hangs about 5.7px below the baseline, so a card with a badge grew that much taller than one without and its goal line sat lower. In a row of cards that meant second lines at different heights.

  The badge now renders in a zero-height wrapper, so it cannot set the row's height. It overflows the row instead, centred on the number's cap box, which is where a pill beside a number wants to sit. Nothing clips: the overflow is about 3px each way inside 20px of padding.

  The slot this uses (MetricCardValue's children) is therefore for a short inline annotation, not a control. Something 32px tall would now overflow 16px each way and reach the line below. If you were passing a control there, move it under the value block.

• MetricCard pins its trend chart to the bottom of the card. Metric cards live in a grid, a grid row stretches every card to the tallest, and the text block is the part that varies: a card with a delta line is one line taller than one without. Packed from the top, that difference fell as dead space under the chart, so three cards in a row showed three charts at three different heights and the one with the least text got the biggest hole beneath it. The slack now sits above the chart instead, where it reads as breathing room, and a row of cards shares one chart baseline to scan across.

  A card that is not stretched has no free space to absorb, so a standalone MetricCard keeps its natural height and looks the same.

• New rung --spacing-rhythm-lines (12px), and MetricCardValue reads it. The ladder jumped from 8px (bind, heading-pair, label, help) straight to 16px (cluster), and a stat block sits between them. lines is for three or more short lines that read as one unit: a value and the lines that qualify it, a label over two facts. pair is the two-line case; cluster is where they stop being one unit.

  It assumes the lines are cap-trimmed. An untrimmed stack already gets this much air from its own dead space, which is exactly the trap it came out of: MetricCardValue asked for 4px and painted 15.4px between its value and its goal and 14.1px between goal and delta. Not just far more than the number it set, but uneven, because a 20px value sheds more dead space than the 13px lines under it. Its three lines are now trimmed and the gaps paint an even 12px. If you use MetricCardValue, expect the block to tighten by about 3px and stop drifting between its own rows.

• Your own headings are no longer cap-trimmed, and go back to how they looked before today's earlier pull. The trim shipped this morning as a blanket h1, h2, h3, h4, h5, h6 rule in @layer base, which reached every heading in your app. It is now an opt-in cap-trim utility that the kit applies inside the components that also own the gap beside the heading: PageHeader, the Title part of Dialog, AlertDialog, Sheet and Drawer, and headings inside prose-flow. Lockup is deliberately not among them: its title-to-description step is four frozen per-size classes rather than a rung, so it renders exactly as it did before this morning. Those render exactly as they did after this morning's pull. Everything else, including every heading you wrote yourself, reverts.

  Why it was pulled back. A blanket trim changes every heading at once, while the gap that compensates for it can only change one container at a time. The two sets never line up. Trimmed headings sat on gaps nobody had adjusted, and adjusted gaps landed next to text that was never trimmed. Neither failure is visible in code review, and finding them one at a time is unbounded work. Tying the trim to the component that owns the gap makes it one decision in one file, and leaves your own markup alone.

  You can still opt any heading in: add cap-trim, and set its container's gap to a rung chosen for a trimmed box (see the next item).

• --spacing-rhythm-pair goes back to 4px, and the compensated gap gets its own rung. This morning's pull raised pair from 4px to 8px. That was wrong, because pair was doing two jobs: binding a trimmed heading to its description in PageHeader, and binding an untrimmed label to its value everywhere else. No single number is right for both. The result was 4px of unwanted air under every metric value, swatch caption, form help line and card title in the system, none of which had a heading anywhere near them.

  Token	This morning	Now
  --spacing-rhythm-pair	8px	4px (back to yesterday)
  --spacing-rhythm-heading-pair	did not exist	8px

  Use pair for an untrimmed tight pair and heading-pair where the title carries cap-trim. The two numbers differ so the two gaps paint the same. The other three rungs re-tuned this morning (heading-sm 20px, heading-md 24px, heading-lg 32px) are unchanged and still correct: every one of their uses sits under a trimmed heading.

  If you overrode --spacing-rhythm-pair in your own CSS to undo this morning's change, delete the override.

• DialogHeader, AlertDialogHeader, SheetHeader and DrawerHeader read a rung instead of a frozen gap-2. Same 8px on screen. It is now overridable, which it was not before: a gap-2 class is inlined at compile time and no token could reach it.

• --spacing-rhythm-heading-pair is now --spacing-rhythm-trim-pair, and the Stack gap value "heading-pair" is now "trim-pair". The old names are gone. There is no alias and no deprecation window: a var() on the old token resolves to nothing, and <Stack gap="heading-pair"> stops type-checking. Nothing moves on screen. The value is the same 12px it was, so a project that only renames its references renders exactly what it rendered before.

  The name was wrong, and it was wrong in a way that cost a real call site. The rung means "the tight pair relationship rendered on a cap-trimmed box", and nothing about it needs a heading. MetricCardValue wanted precisely that relationship and could not reach for it, because a token with heading in the name reads as off limits next to a number. A name that turns people away from the right rung is worse than a long one.

  Renaming a shipped token is normally not worth the churn. This one is cheap today and will not be tomorrow: it landed earlier in this same day's entries, so the only projects it can reach are ones that pulled within hours of it going up. That window is why the rename is happening now rather than living with the wrong name forever.

  Two rungs deliberately keep their names: --spacing-rhythm-heading-sm, -md and -lg are the gap below a heading group, ramped by heading size, so heading is accurate there and they are untouched.

  Fix it with a find and replace across your project, both spellings, then run node scripts/verify-ui.mjs. If you overrode --spacing-rhythm-heading-pair in your own CSS, rename your override too: an override under the old name is silently dead, since nothing reads it any more.

• New rule trim-rung-mismatch, severity warn. Flags a gap rung that disagrees with whether its heading is trimmed: the plain --spacing-rhythm-pair sitting beside a cap-trim heading, or --spacing-rhythm-heading-pair in a file that trims nothing at all. Both are invisible in review, because the class is real, the token exists, and only the pixels are wrong.

  The fix is usually not to swap the token but to use the component that encodes the pairing: PageHeader, DialogHeader, SheetHeader, DrawerHeader, AlertDialogHeader. A component cannot pick the wrong rung.

  Where the rungs themselves are the subject (a spacing specimen, a demo showing both side by side), opt the line out with a ui-md-allow-trim-rung comment.

  It will not fail your build yet. If your build script runs verify-ui.mjs --strict, it will: --strict promotes every warning to an error, so check your own script before assuming a new warning is safe.

• Four rungs got bigger, because cap-trim exposed what they were really worth. Take this pull together with the trim entry below it: that change tightened every gap next to a heading, and this one re-tunes the gaps that were tuned by eye before the trim.

  Token	Was	Now
  --spacing-rhythm-pair	4px	8px
  --spacing-rhythm-heading-sm	16px	20px
  --spacing-rhythm-heading-md	16px	24px
  --spacing-rhythm-heading-lg	24px	32px

  Why they were wrong: an untrimmed heading box carried dead space proportional to its own font-size, roughly 0.31em below the baseline at --leading-snug. That is about 9px under a 28px title, 6px under an 18px one, 4px under a 12px label. So one flat number rendered as three different gaps, wider under the bigger title, which is exactly what made it look right. None of that was in a token. Trimming the box deleted the subsidy and left the flat number exposed, so these four now state outright what they used to get for free.

  heading-sm and heading-md were both 16px and could not stay that way: their titles are 14px and 18px, so they lost different amounts.

  The page-scale rungs (peer, region, section) were left alone even though the trim does reach them: a Stack around a PageHeader puts one directly above a trimmed heading. A 40px peer above a lg PageHeader used to paint about 47.5px and now paints 40. They were not re-tuned because the same rung also sits between two ordinary blocks where nothing is trimmed and the value is already right, and the difference is 10-19% on gaps big enough to absorb it. If one reads tight on your page, raise it there.

  No other rung moved. cluster, field, label, help, peer, region and section never sit next to a heading, so the trim never reached them.

  Where you will see it: any title over its description gains 4px (PageHeader, CardTitle over CardDescription, and anywhere you used pair yourself), and a heading group clears its content by 4-8px more. If you had already re-tuned these tokens in your own CSS to recover from the trim, your values still win, and this is the moment to delete them and check the defaults instead.

  One rough edge, stated rather than hidden: p is not trimmed, only headings are. So a rung sitting under a description still paints about 6px looser than the same rung under a bare heading. Both are consistent per shape; they are not consistent with each other. Trimming paragraphs too would fix it and would move text inside every padded overlay, so it is not in this release. Padding is not a gap: no token re-tune reaches it, because those numbers are shared with icons, inputs and rows that have no text box to trim.

• prose-flow's four heading gaps gained 8px each. Its other two did not move. Same correction as the rungs above, applied to the long-form utility. It owns top-margin on the following element, so these four each sit next to a heading and each lost that heading's dead space: roughly 6px next to an h3, 9px next to an h1.

  Token	Was	Now
  --rhythm-above-h3	28px	36px
  --rhythm-above-h2	48px	56px
  --rhythm-above-h1	64px	72px
  --rhythm-below-h1	32px	40px

  --rhythm-base (block to block, nothing trimmed on either side) and --rhythm-figure (a table or pre, which has no text box to trim) render exactly as they always did and were left alone. If you re-tune any of this yourself, that is the rule to copy: compensate only where a trimmed box is actually adjacent. Raising a gap that never lost anything just makes it loose.

  Two things this changes that you may have relied on. --rhythm-below-h1 is no longer literally half of --rhythm-above-h1; that was only ever true of the token values, never of the painted gaps, because each carried a different amount of dead space. And an h1 followed directly by an h2 lost dead space on both sides, so it stays about 8px tighter than before. That pairing has no content between the two headings and is rare enough that it did not earn a token of its own.

• Watch your gaps against the line-height now, not just against each other. Untrimmed boxes supplied half-leading on both sides of every block, which quietly kept the gap between two paragraphs larger than the gap between two lines inside one. Trim removes that guarantee. A 16px gap between blocks of 24px-leading text now reads as no break at all, so if you have hand-set a gap between text blocks anywhere, compare it to the leading before deciding it is still right.

• heading-hand-tuned-margin (warning, not yet an error). Fails on a numbered mt-*, mb-*, my-* or space-y-* in the className of an h1-h6 or a kit *Title part.

  This exists because of the trap in the change above. Gaps under headings got tighter, and the tempting fix is a margin on the heading. That margin is frozen at compile time and sits outside the ladder, where no token, theme, or override can reach it. The fix is the rung: put the heading and its description in a group on --spacing-rhythm-pair and let the group clear its content on --spacing-rhythm-heading-sm|md|lg, or use PageHeader, which encodes both.

  A negative margin is the one to look for hardest. -mt-1 on a heading is almost always a nudge that was compensating for the untrimmed box, so it now double-counts: delete it rather than re-tune it.

  Two things it deliberately leaves alone. mt-0 is a reset of an inherited prose margin and is correct. So is the rung-reading form mb-(--spacing-rhythm-heading-md), which follows an override the way a frozen number cannot. A line that needs the margin anyway can carry a ui-md-allow-heading-margin comment.

• Superseded, see above. The kit no longer asserts this globally; the trim travels with the components that own the gap beside the heading.

• The kit now asserts that headings are cap-trimmed without owning how they look. Size, face, weight, tracking and any .h*-display recipes stay yours; the trim is the one thing hoisted here, because it is the only part that decides whether a spacing token renders honestly. A project that had been applying the trim in its own CSS can delete that rule after this pull.

• Superseded the same day by the entry above: this blanket trim was pulled back to an opt-in cap-trim utility. If you are reading both entries in one pull, follow the newer one and skip the opt-out recipe below, which no longer applies because there is nothing global to opt out of. Kept for the record.

• Every heading is cap-trimmed, so every gap touching a heading tightens. h1-h6 now carry text-box-trim: trim-both; text-box-edge: cap alphabetic in @layer base. A heading's line box used to be taller than its letters, so every gap above or below one rendered looser than the token that set it, and the token was never the number you saw.

  How much depends on your heading face and size. Measured on the face that found this (ascender 0.975em, cap 0.721em) at 28px with --leading-snug: 8.8px of dead space above the cap and the same below the baseline. So --spacing-rhythm-heading-lg (24px) painted 32.8px. The offset is fixed, so the smaller the gap the more it lied: that 24px was off by 37%, a 64px section pad by 14%. Expect small gaps to tighten most.

  Two knock-ons worth looking for. Headings sitting in a flex row with items-center next to an icon, badge, or arrow will re-center, because the box they are centered against just changed height; items-baseline is the fix and may already be there. And any nudge someone added to compensate for the untrimmed box is now double-counting: delete it rather than re-tune it.

  Descenders hang into the gap below a heading now. That is what alphabetic means and it is intended, not a clipping bug.

  Firefox does not support this yet (Chrome/Edge 133+, Safari 18.2+; Firefox has it behind layout.css.text-box.enabled in Nightly as of 2026-08). An unsupporting browser ignores both properties and renders the untrimmed boxes it rendered before, so this degrades to the old look rather than to a broken one. Shipped with that known, because the alternative is gap tokens that never mean what they say in any browser.

  To opt out, re-declare it in your own CSS below the kit import:

  h1, h2, h3, h4, h5, h6 { text-box-trim: none; }
  

  No longer needed. The blanket rule is gone; see the newer entry.

• SiteHeader is finally responsive, and it needed no new prop. The bar height, the sticky offset and the scroll margin are now read as h-(--spacing-site-header), top-(--spacing-site-header) and scroll-mt-(--spacing-site-header) instead of the h-site-header family.

  This was a real bug, not a tidy-up. Tailwind v4 inlines a named spacing token when it compiles, so h-site-header shipped as height: 4rem with no var() in it and your override of --spacing-site-header could never reach it. The only way out was restating the compiled utility in an unlayered block, which is what at least one site was doing. The paren form compiles to height: var(--spacing-site-header) and stays live.

  A compact mobile bar and a taller desktop one is now two lines of your own CSS, and the sticky offsets, scroll margins and hero scrim all follow from that one number:

  :root { --spacing-site-header: 3.5rem }
  @media (width >= 48rem) { :root { --spacing-site-header: 5rem } }
  

  If you were patching .h-site-header or .top-site-header directly, delete that block and set the token instead.

• Drawer has a second layout for application panels. <DrawerContent layout="panel"> turns the drawer into a cart, an inspector or a filter rail: DrawerHeader becomes a fixed 64px bar with the title and its metadata left, an inline close right, and a hairline running wall to wall; the new DrawerBody scrolls under it; DrawerFooter pins to the bottom with its own hairline. The popup owns no padding in this layout, so each region pads its own contents and the rules reach both edges.

  The default prose layout is untouched, so nothing changes unless you ask for panel. If you were building this shape by hand with p-0 gap-0 showCloseButton={false} plus your own <header> and an absolutely positioned hairline, that all comes out; the layout is one prop on DrawerContent and the parts read it.

• DrawerHeader takes a close slot under layout="panel". Pass your own control (<DrawerClose render={<MyButton />} />) when the bar's close needs a different accessible name, icon, or an analytics attribute. Omit it and you get the stock X.

• DrawerBody is new. Use it for the scrolling middle of any drawer. It carries the min-h-0 that flex-1 overflow-y-auto needs to actually scroll instead of growing the popup past the bottom of the screen.

• The site header is 80px, up from 64px. --spacing-site-header moved from 4rem to 5rem. Every SiteHeader on your site gets 16px taller, and anything you pinned to it (a sticky sub-nav, an anchor's scroll margin) moves with it.

  If 80px is wrong for you, it is now genuinely one line to change, which is the other half of this release. See below.

• The hero scrim tracks the bar instead of being its own length. --spacing-site-header-scrim is now calc(var(--spacing-site-header) * 2). It was 8rem, which was exactly twice the old bar and stopped being twice anything the moment the bar moved. Only affects surface="hero".

• Pull the extras you already have. kit does not list the eight kit-extras components, so add -o kit.json has never updated them. If you installed one of these, it has been frozen at the release you installed it on, through every pull since:

  calendar  carousel  code-block  combobox  command  rich-text-editor  sonner  toast
  

  It type checks and it renders. It is just an older release of the same component sitting beside newer ones, which shows up as a fix that looks half-applied rather than as a missed pull.

  node scripts/verify-ui.mjs --drift is what catches it: the file differs from what is published, so it gets listed. Read that listing carefully, because it uses one label, kit-file-differs, for two opposite problems. On a kit component it usually means you edited the file and the pull is about to revert it. On one of the eight above it usually means the file is just behind, and the remedy is to pull it by name.

  Add the ones you have to a single call, by name. This installs nothing new, and their packages are already in your package.json:

  npx shadcn@latest add -o https://ui.mattdowney.com/r/command.json \
                          https://ui.mattdowney.com/r/combobox.json
  

  docs/ui-md-upgrade.md step 2 now carries this, so it happens on every pull from here. Do not install one you do not already have: each forces a third-party runtime package.

• verify-ui now says when it could not reach the registry. It fetches kit.json and kit-extras.json on every run, which is the only way it can tell an installed kit file apart from your own code. That fetch failing has always been safe: everything under a ui/ directory is treated as kit and skipped, so a network blip can never fail your build. It was also silent, and the counts read identically either way.

  That matters most if you have wired this into npm run build, because a clean offline run checked strictly less than a clean online one at exactly the moment it decides whether a deploy ships. It now prints a line saying so. Nothing about the exit code changed.

• Badge grew a display size, for a featured stat in a chip on a marketing surface: a subscriber count in a hero, a founding year beside a wordmark.

  <Badge size="display" icon={<Star />}>12,480 subscribers</Badge>
  

  It is a different job, not the next step of the annotation ramp: 16px type, deliberately skipping body size, with padding and icon scaled to match. The annotation ceiling still holds everywhere a badge annotates something (lg, 13px, remains the largest of those). If you were faking this size through className, the size-faked-with-classname listing goes away when you move to the prop.

• ProgressRing takes a weight. The stroke has always been an eighth of the diameter, which is tuned to the 16-48px rings the kit ships; perceived weight grows with area, so a ring sized well past that reads the same ratio as a donut. weight="thin" halves the stroke to a sixteenth:

  <ProgressRing value={72} weight="thin" className="size-20">72%</ProgressRing>
  

  Use it when you size the ring past the shipped three with a className, instead of forking the component to redraw the arc. Rings without the prop are unchanged.

• NavItem takes a count, the same counter chip a TabsTrigger carries, and the same recipe: solid accent fill on the active item, neutral tint on the rest, tabular-nums so a live number does not jitter.

  <NavItem href="/inbox" icon={<Inbox />} count={12} active>Inbox</NavItem>
  

  Horizontal, the chip sits inline after the label. Vertical, it is pushed to the trailing edge so a column of numbers reads as a column, which needs the nav to have a width; an item without a count leaves the slot empty rather than reflowing its label. Cap large counts at "99+" yourself, and add an aria-label where a bare number needs context. Items without the prop render exactly as before.

• ProgressRing, the same progress as a ring, shipped from the progress item beside the bar.

  <ProgressRing value={72} size="lg" aria-label="Storage used">72%</ProgressRing>
  

  For the places a full-width bar does not fit: a row, a card corner, beside a label. Three sizes (16 / 24 / 48px), and the stroke is an eighth of the diameter at each, so all three read as one ring rather than three weights, and that holds if you size it past those three yourself. Children sit in the middle, out of the flow, so the box stays the size it was asked for, and lg is sized to hold a two-digit percentage without it touching the arc.

  It never spins. A ring is a quantity; a spinning ring is a wait, and the two are only a shape apart. With no value it draws an empty track and holds still. The bar keeps its indeterminate state.

• Pagination, a pager for a table, a card grid, or any list.

  <Pagination
    page={page}
    pageCount={12}
    onPageChange={setPage}
    total={240}
    pageSize={20}
    pageSizeOptions={[20, 50, 100]}
    onPageSizeChange={setPageSize}
  />
  

  Give it total and pageSize and it renders the "1-20 of 240" count; give it pageSizeOptions and it renders the rows-per-page select. With neither, it is only the pager, and it centers under whatever it belongs to rather than sitting against one edge.

  It works from a Server Component. Pass renderPage={(page) => <Link href={?page=${page}} />} and the pages draw as links instead of buttons, which is the one shape a server page can do: it can build a link, but it cannot hand a click handler to a button. The component carries no "use client" so that stays true.

  The window of page numbers is always the same length. The usual pager drops its ellipsis near either end and renders fewer controls there, so the row changes width as you page through it and everything beside it shifts.

• MetricCard, the dashboard card for one number: title, value, goal, a delta badge, and the metric's recent trend, in one component.

  <MetricCard
    title="Subscribers"
    value="183"
    goal="Goal: 262"
    delta={{ value: 79 }}
    trend={{ data: subscribers, type: "bar" }}
  />
  

  It is a composition, not a new surface. Card, DashboardCardHeader, MetricCardValue, and Stack all still ship on their own, and what this adds is the rhythm, which is the part that was being retyped and quietly getting different at every call site: the goal line and anything you pass as children bind to the value at 8px, and the chart sits under that whole block at 16px as a peer. When your layout differs, reach past it to those parts. That is what they are for, and it is not a fork.

  Sparkline ships from the same file, and draws the chart. Three shapes on one type prop: bar for a count per period, line for a trend, area for volume under a trend. Three heights on size (24 / 40 / 64), and the width always fills its container. MetricCard draws it for you through trend, but it is reachable on its own for a table row or a list item, where a card would be the wrong box entirely.

  A bar chart is drawn, not laid out. The bars were a row of CSS boxes, and a row of boxes cannot be evenly spaced at an arbitrary width: thirty columns in a 203px card is a 6.77px pitch, and a browser snaps a box to whole device pixels, so the gaps land 3px and 4px apart in whatever pattern the fraction falls in. The bars measure identical and the row still reads uneven, because the eye takes the whitespace as part of the rhythm. They are <rect>s in an SVG now, where geometry is antialiased instead of snapped, so every bar and every gap carries the same ink at any container width.

  The chart fills its container. The bar row used to stop at a maximum width per point and center itself, so a wide card drew a short chart adrift in the middle of it. A bar is 60% of its column at every size instead, which means a wide card gets wider bars rather than the same thin ones in bigger gutters.

  It renders on the server with no JavaScript and no third-party package, so a wall of metric cards costs nothing at runtime. Every mark paints currentColor off a text-accent root, so it follows your accent automatically and one class retargets the whole chart: <Sparkline data={churn} className="text-destructive-500" />.

  The scale is not the same for every shape, on purpose. bar measures from zero, because a bar's length is the value and a band-scaled bar claims a 98 is a fraction of a 100. line and area measure the min-to-max band, because a zero-based line flattens any series whose values sit far from zero. A series that crosses zero belongs in line; bars clamp negatives to the baseline.

  A bar is always half its column, so bar and gap hold the same ratio at any card width and any number of points. An empty data array still renders at full height with a hairline on the baseline, so a card does not jump when its numbers arrive.

• Dark mode: every accent-tinted selected state got one step lighter, and its label one step brighter. The pair went from accent-900 under text-accent to accent-800 under text-accent-400. Light mode is unchanged.

  It was backwards. On the old pair the selected label sat at 3.22:1 while the unselected labels beside it sat at 7.32:1, so the item you had chosen was the hardest one in the row to read, and it failed AA while its neighbours passed. Tabs is where it shows worst, because the active tab sets its colour on the button and lets the label inherit.

  You get this on: Tabs, Nav (and the mobile site nav), Badge, the tinted Buttons (outline, soft, ghost) and their count chip, Select, Command, Combobox, DropdownMenu (every row state, icons included), Toast's action rows, and Lockup's tinted tone. Nothing to change. If you re-declared --color-accent-* you keep your own hues, since these are scale steps.

  Three of those are kit-extras items, so add -o kit.json will not bring them: Command, Combobox, and Toast. If you have them installed, pull them by name in the same step or they keep the old colours while everything around them changes, which reads as the fix being half-done. See "Pull the extras you already have" below.

• Dark mode: the primary Button rests a step down, and its hover reverses. default now rests on accent-600 and hovers up to accent-500; light still rests on 500 and hovers to 600.

  A saturated accent-500 plate is the loudest thing on a near-black page. The step down quiets it against the page (3.94:1 to 2.78:1) and at the same time raises its label (5.0:1 to 7.07:1). The hover had to flip with it: "one stop deeper" only means more presence when the page is light, so on dark the old hover walked the fill toward the background and the button receded under the pointer. destructive is unchanged.

• Pagination's rows-per-page popup now opens flush with its left edge instead of centered on it. The popup is sized to its trigger with a 128px floor, and a trigger reading "10 per page" is under that floor, so the popup came out wider than the trigger and centering hung the extra off both sides. The select sits at the left edge of the pager row, so that left overhang broke the edge the count and the table above it line up on. Nothing to change; if you were passing align yourself, you still win.

• bare-element-inherited-property, a warning. It does not fail your build today. It will be promoted to an error in a later release, and that promotion gets its own line here.

  It flags a rule in your own CSS whose selector names a bare element with no class, id, or attribute anywhere in it, and which sets a property that inherits: color, font-family, font-size, font-weight, line-height, letter-spacing, text-transform.

  /* flagged */
  span { color: var(--color-muted-foreground); }
  
  /* fine: scoped, so it cannot cross a component boundary */
  .prose span { color: var(--color-muted-foreground); }
  

  An inherited value has nothing to defend itself with. Kit components set colour and type on their root and let the text inside take it, so any rule that names the inner element directly wins, no matter how specific the component's own selector was. A bare span { color } silently repaints the label of every component whose label is a <span>.

  The case this came from cost a long debugging session and looked like a bad port. It was not one. Tabs sets data-[active]:text-accent on the button and lets the label inherit, so the button really was accent while the word on it stayed grey. The component file matched the registry byte for byte, the token resolved identically, SSR emitted data-active on the right element, and the variant compiled into the bundle at winning specificity. Every static check passed. It was visible only by reading computed styles on the live DOM, which is why it is worth a rule.

  Only the generic wrappers are flagged: span, div, li, a, button, label. p, h1-h6 and blockquote are left alone, since those carry meaning and components rarely emit them structurally, so styling them is describing your own prose rather than reaching into a component. Minified and compiled CSS is skipped. A rule that is deliberately global opts out with a ui-md-allow-bare-element comment on it or in the three lines above it.

• The upgrade procedure now ships to docs/ui-md-upgrade.md: the whole sequence (drift check before the pull, pull, changelog diff, the stale-token and import-order traps, the rung conversion, verification) as one tool-neutral checklist any agent or person can run. Point Codex, Cursor, or any AGENTS.md-reading tool at it with one line, which the file's last section spells out. Claude Code users get it wired as a command: the kit also ships a thin skill to .claude/skills/uimd-pull/SKILL.md, so /uimd-pull reads and runs the same file. Not using Claude Code? Delete the skill file; the procedure is not in it.
• verify-ui.mjs gained rule severities and a --strict flag, which is what lets a new rule warn instead of breaking your build on the day it ships.
• Fixed: the checker's class-string scanner did not understand regex literals, so a regex containing an odd number of backticks opened a string it never closed and left the rest of that file unchecked. Five rules shared the blind spot, silently. If a file of yours was quietly exempt, it is not any more, and you may see violations appear in code you did not touch.
• verify-ui.mjs gained --all, which lifts the 20-findings-per-rule display cap; the first consumer conversion had to copy the script out of the kit just to see its whole list. The upgrade procedure also now scopes step 5 to the errors a pull introduced: a pre-existing backlog is its own piece of work, not an upgrade's cost.
• Fixed: the checker now skips every hidden directory (.design-sync, .cursor, and friends), not just a named list. The first consumer run linted a design tool's generated previews as if the project had written them; a generator's output answers to the generator, not the style rules.
• Fixed: the rules file said --spacing-rhythm-heading-sm is 8px. It ships 16px.
• The rules table in the Checking your work section was two rules out of date.

• SiteFooter renders 8px airier. The footer shell's gap between rows, and the vertical gap in its column grid, were a frozen 32px. Both now read the peer rung (40px), so they follow the ladder and answer to a token override. SiteFooterRow's divider padding moved with them, since that padding and the shell gap are one measurement written twice.

• kit-typeface-unwired, as a warning. The kit now installs the geist package: Geist, stylistic sets and all, is the system's typeface, and the token file's letterform tuning is pointed at it. A font cannot wire itself, so this warning fires when a project has neither the two-line Geist wiring in its root layout (import { GeistSans } from "geist/font/sans", then GeistSans.variable on the <html> className) nor a --font-sans-custom override. Un-wired, every page silently renders system-ui. Projects with their own brand face via --font-sans-custom are already clear and change nothing.
• family-without-feature-settings, as a warning. A CSS rule that sets a non-kit font-family must set font-feature-settings in the same block. The kit's Geist-tuned list inherits from body into every element, and stylistic set numbers are per-family: the recorded case was a display face whose same-numbered set substituted a wide space and tripled every word gap, while every static check passed. normal is the safe reset; a face verified to want the inherited list opts out with a ui-md-allow-feature-inherit comment. Minified/compiled CSS is skipped.
• frozen-page-scale-gap, as a warning. Flags a numbered vertical gap of 32px or more: space-y-8, gap-y-10, mt-12, or a bare gap-* on a non-wrapping flex-col. Tailwind inlines that value when it compiles, so the number is frozen and no token override can reach it afterwards. Convert to a rung (<Stack gap="peer">, or the class form gap-(--spacing-rhythm-peer)). Below 32px nothing is flagged. Where the pixel count is the subject, opt the line out with a ui-md-allow-frozen-gap comment. This will become an error in a later release.