@vvedantb/ui 0.6.1 → 0.7.1

package/README.md

@@ -299,7 +299,7 @@ import {
 - `SidebarPanel`: legacy (still supported) `headerTrailing`, `onClose`, `closeLabel` and `closeButtonClassName`; compose `Sidebar.Panel` parts instead. `title`, `headerTrailing`, `onClose` (adds the close button; pass it on the mobile drawer only), `closeLabel`, `closeButtonClassName`, `collapsed` (`md:hidden`), `className`, `children`.
 - `SidebarAccountMenu`: legacy (still supported) `badge`, `triggerProps`, `contentProps` and `stackedLabel`; compose `Sidebar.Account*` parts instead. `name`, `email` (two-line label when set), `stackedLabel` (two-line layout even without `email`, default `false`), `imageUrl` (initials without it), `align` (`"center"`), `side` (`"right"`), `sideOffset` (8), `collisionPadding`, `contentClassName`, `children` (menu items). 0.5.2 adds `badge` (unread dot beside the trigger, in a `relative` wrapper around the menu, so the trigger's dimming and press scale skip it: `true` shows it, `false` fades it out, omitted renders no wrapper and no dot), `triggerProps` (spread onto the trigger `Button` after the defaults; `className` merges last) and `contentProps` (spread onto `DropdownMenuContent`, for example `fitViewport` or `aria-label`; no `className`, use `contentClassName`). `SidebarAccountMenuPlaceholder` is the tile-sized loading box.
 - `SignOutDialog`: legacy (still supported) `question` and `title`; compose `ConfirmDialog` parts with `alert={false}` for other copy. `open`, `onOpenChange` (not called with `false` while `pending`), `pending`, `onConfirm`, `description`, `contentClassName`, `title` (`"Sign out"`), `question` (`"Sign out of your account?"`).
-- Class helpers: `railTileClass`, `railTileStateClass(active)`, `railBadgeClass`, `sidebarNavRowClass(isIconOnly)`, `sidebarNavLinkTextClass(isActive)`, `sidebarSectionLabelClass`.
+- Class helpers: `railTileClass`, `railTileStateClass(active)`, `railBadgeClass`, `sidebarNavRowClass(isIconOnly)`, `sidebarNavLinkTextClass(isActive)`, `sidebarNavItemClass({ active, iconOnly })`, `sidebarNavIconClass(active)`, `sidebarSectionLabelClass`. See [Menu item corners and sidebar nav rows (0.7.1)](#menu-item-corners-and-sidebar-nav-rows-071).
 
 ### Header actions and account badge (0.5.2)
 
@@ -385,7 +385,7 @@ function PanelWidth() {
 
 Shadcn-style building blocks. The prop-driven components above are thin compositions of them and render the same DOM.
 
-Convention: compound parts are static members of a namespace object, `<Namespace>.<Part>`. There are three namespaces: `ConfirmDialog.*`, `AppShell.*` and `Sidebar.*`. `ConfirmDialog` and `AppShell` stay callable with their legacy props. `Sidebar` is a plain object. Prop types are exported flat, for example `ConfirmDialogRootProps`, `AppShellMainProps` and `SidebarRailItemProps`. Every part that renders an element merges `className` last and forwards native props.
+Convention: compound parts are static members of a namespace object, `<Namespace>.<Part>`. There are four namespaces: `ConfirmDialog.*`, `AppShell.*`, `Sidebar.*` and (0.7.0) `EmptyState.*` (see [Spinner, empty state, tabs, badge and kbd](#spinner-empty-state-tabs-badge-and-kbd-070)). `ConfirmDialog` and `AppShell` stay callable with their legacy props. `Sidebar` is a plain object. Prop types are exported flat, for example `ConfirmDialogRootProps`, `AppShellMainProps` and `SidebarRailItemProps`. Every part that renders an element merges `className` last and forwards native props.
 
 ### `ConfirmDialog.*`
 
@@ -434,6 +434,7 @@ Convention: compound parts are static members of a namespace object, `<Namespace
 | `PanelHeader` | Padded header row for `PanelTitle` and `PanelActions`. |
 | `PanelTitle` / `PanelActions` | The `<h2>` and the trailing actions. |
 | `PanelClose` | Ghost close button. `label` (`"Close navigation"`). Without `onClick` it closes the drawer. |
+| `NavItem` | Panel nav row (`sidebarNavItemClass`). `active` (fill, `font-medium`, `aria-current="page"`), `iconOnly`, `icon` (element; gets `sidebarNavIconClass`), `asChild` for a router link. A `<button type="button">` without `asChild`. |
 | `AccountMenu` | Dropdown root. `badge` adds the unread dot (`AccountBadge`) in a `relative` wrapper. |
 | `AccountTrigger` | Rail-tile-sized avatar button. `userName` (default `title` and `aria-label`, and the initials), `imageUrl`, plus `Button` props; native `name` goes to the button. |
 | `AccountAvatar` | Avatar image or initials. `userName`, `imageUrl`. |
@@ -559,6 +560,145 @@ A full shell:
 </AppShell.Root>
 ```
 
+## Spinner, empty state, tabs, badge and kbd (0.7.0)
+
+All of these are opt-in. Without the new props, components render as in 0.6.1.
+
+```tsx
+import {
+  Badge, Button, EmptyState, Kbd, Spinner, Tabs, TabsList, TabsTrigger,
+} from "@vvedantb/ui";
+
+<Button disabled={saving}>
+  {saving ? <Spinner size={14} tone="inherit" decorative className="mr-1.5" /> : null}
+  Save
+</Button>
+
+<EmptyState.Root className="h-full">
+  <EmptyState.Icon icon={IconFolder} />
+  <EmptyState.Description>No files yet.</EmptyState.Description>
+</EmptyState.Root>
+
+<EmptyState.Root variant="panel">
+  <EmptyState.Icon icon={IconLink} />
+  <EmptyState.Title>No linked items</EmptyState.Title>
+  <EmptyState.Description>Link one to see it here.</EmptyState.Description>
+  <EmptyState.Actions><Button size="sm">Link</Button></EmptyState.Actions>
+</EmptyState.Root>
+
+<Tabs value={active}>
+  <TabsList>
+    <TabsTrigger value="keys" asChild>
+      <Link to="/settings/keys">Keys</Link>
+    </TabsTrigger>
+  </TabsList>
+</Tabs>
+
+<Tabs value={feature} onValueChange={setFeature}>
+  <TabsList variant="soft" aria-label="Features">
+    <TabsTrigger value="notes"><IconNotes size={15} />Notes</TabsTrigger>
+  </TabsList>
+</Tabs>
+
+<Badge variant="destructive-soft">Revoked</Badge>
+<Kbd variant="subtle">Esc</Kbd>
+```
+
+- `Spinner` `size`: `"sm"`, `"md"` (default) and `"lg"` add a `size-*` class; a number is passed to the icon as its pixel size and adds no size class. `stroke` sets the stroke width. `tone`: `"muted"` (default) adds `text-muted-foreground`; `"inherit"` adds no colour class, so the spinner takes the current text colour. A colour class in `className` also replaces the muted default. `decorative` renders `aria-hidden="true"` with no `role="status"` or `aria-label`; use it where the parent already has a label, such as a busy button. Without it, `aria-label` in props replaces `"Loading"`.
+- `EmptyState.*`: composable "nothing here yet" block. Parts read the Root `variant`.
+
+| Part | Purpose |
+| --- | --- |
+| `Root` | `<div>`, centred column. `variant`: `"default"` (`px-4 py-20`, open) or `"panel"` (`rounded-lg bg-surface-secondary px-4 py-10`). |
+| `Icon` | `icon` component (for example a Tabler icon). `default`: the bare icon, `size` 40, `mb-3 text-muted-foreground`. `panel`: the icon (`size` 22, `stroke` 1.5, `text-muted-foreground`) in an `h-11 w-11 rounded-lg bg-surface-tertiary` tile. `size` and `stroke` override; `className` goes on the outer element (icon or tile). |
+| `Title` | `<p>`, `text-sm font-medium text-foreground`; `default` adds `mb-1`. `asChild` renders your element (for example an `h3`) instead. |
+| `Description` | `<p>`, `text-sm text-muted-foreground`; `panel` adds `mt-1 max-w-[240px]`. |
+| `Actions` | `<div>`, `mt-4`. |
+
+- `TabsList` `variant="soft"`: borderless pills that wrap and centre (`flex flex-wrap items-center justify-center gap-1.5`). Triggers inside it are `rounded-full px-4 py-2 text-sm`, muted until active, filled with `bg-surface-secondary` when active or hovered, and `relative overflow-hidden` so a child such as a progress bar can sit on the bottom edge. It uses no `t-tabs` CSS and has no focus ring of its own. `pills` and `segmented` are unchanged. Link tabs work with any variant: `TabsTrigger asChild` around the router link (Radix sets `role="tab"`, `data-state` and roving focus on it). The package does not depend on a router.
+- `Badge` `variant="destructive-soft"`: neutral border with a faint danger tint (`border-border bg-danger/10 text-danger`). Resolves to the same classes as a default badge with `className="bg-danger/10 text-danger"`. `variant="success"` already resolves to the same classes as a default badge with `className="border-success/25 bg-success/12 text-success"`.
+- `Kbd` `variant="subtle"`: a plain filled key for inline hints, `rounded bg-surface-secondary px-1.5 py-0.5 text-foreground`. No fixed height, font or size, so it follows the surrounding text.
+
+## Menu item corners and sidebar nav rows (0.7.1)
+
+Visual change. Values in brackets are at the default `--radius: 1rem` and `--spacing: 0.25rem`.
+
+The radius utilities now come with `tokens.css` (and `compat-shadcn-rgb.css`), so an app that imports `@vvedantb/ui/tokens` has them without another import:
+
+| Utility | Value | Used by |
+| --- | --- | --- |
+| `rounded-surface` | `clamp(0.75rem, var(--radius), 1rem)` (16px) | Opt-in surfaces (Toaster `toastRadius="surface"`, `SessionsHoverCard`). Was in `utilities.css`. |
+| `rounded-menu-item` | `min(var(--radius), 0.5rem)` (8px) | Menu items and sidebar nav rows. |
+| `rounded-control` | `min(var(--radius), 0.625rem)` (10px) | Apps. |
+
+The root `cn` knows these are radius classes, so `cn("rounded-lg", "rounded-menu-item")` keeps only the last one.
+
+### Menu items
+
+| Piece | Before | From 0.7.1 |
+| --- | --- | --- |
+| `DropdownMenu` and `ContextMenu` item, sub-trigger, checkbox item and radio item | `rounded-md`, `calc(var(--radius) - 2px)` (14px) | `rounded-menu-item` (8px) |
+| Menu surface | `rounded-lg` (16px) | unchanged |
+
+### Sidebar panel nav rows
+
+Rows in the panel beside the rail. Rail tiles are unchanged.
+
+| Piece | Before | From 0.7.1 |
+| --- | --- | --- |
+| Radius | none in the helper (apps added `rounded-lg`, 16px) | `rounded-menu-item` (8px) |
+| Padding | `px-3 py-1.5` (12px / 6px) | `px-4 py-1.5` (16px / 6px) |
+| Icon gap | `gap-3` (12px) | `gap-2` (8px) |
+| Text | none in the helper (apps added `text-sm`, 14px / 20px) | `text-[0.8125rem] leading-[18px] tracking-[0.005em]` (13px / 18px) |
+| Row height | 32px with `text-sm` | 30px |
+| Width | none in the helper | `flex w-full items-center` |
+| Idle text | `text-muted`, `hover:text-foreground` | `font-normal text-foreground/80`, `hover:text-foreground` |
+| Active text | `text-foreground` | `font-medium text-foreground` |
+| Hover and active fill | none in the helper | `hover:bg-surface-tertiary` (idle rows), `bg-surface-tertiary` (active row), same radius |
+| Press | none | `active:scale-[0.99]`, `transition-[scale,background-color,color] duration-150 ease-smooth` |
+| Focus ring | none | `focus-visible:ring-2 focus-visible:ring-foreground/35`, no outline |
+| Icon-only row | `justify-center px-0 py-1.5` | same, plus the radius, text, fill and focus classes above |
+| Icon (`sidebarNavIconClass`) | none (apps used 18px in a 20px box) | `size-[19px] shrink-0`; `text-muted-foreground` idle, `text-foreground` active |
+| Section label | `px-3 py-1 text-[11px]` | `px-4 py-1 text-[11px] leading-4` (16px line). Colour still comes from the app's `.sidebar-section-label` rule. |
+
+The hover fill is static: it does not slide between rows. While another row is hovered, the active row keeps its fill.
+
+One call per row:
+
+```tsx
+<nav className="px-2">
+  <p className={sidebarSectionLabelClass}>Library</p>
+  <div className="space-y-1">
+    <Link to="/home" aria-current={active ? "page" : undefined} className={sidebarNavItemClass({ active, iconOnly })}>
+      <IconHome size={19} className={sidebarNavIconClass(active)} />
+      {iconOnly ? null : <span className="truncate">Home</span>}
+    </Link>
+  </div>
+</nav>
+```
+
+Or the part, with the router link as the child:
+
+```tsx
+<Sidebar.NavItem asChild active={active} iconOnly={iconOnly} icon={<IconHome />}>
+  <Link to="/home">{iconOnly ? null : <span className="truncate">Home</span>}</Link>
+</Sidebar.NavItem>
+```
+
+- `px-2` on the list is the panel inset: rows are full width inside it. `space-y-1` (4px) separates rows.
+- `sidebarNavRowClass(isIconOnly)` and `sidebarNavLinkTextClass(isActive)` now return the classes above, so existing calls change look. `sidebarNavItemClass` is the two merged.
+- Classes an app added beside the helpers, such as `rounded-lg text-sm font-medium tracking-normal transition-colors duration-200`, are now redundant. Through the root `cn` they lose to the helper when passed before it. Passed after it, or joined without `cn`, they override the new radius, size and weight. Remove them, and remove app-side active fills such as `bg-surface-tertiary`.
+
+Colour mapping. The package has no sidebar colour tokens, so the rows use the nearest general token:
+
+| Role | Reference look (light / dark, sRGB) | Package token (light / dark, sRGB) |
+| --- | --- | --- |
+| Hover and active fill | 233 234 236 / 28 28 28 | `surface-tertiary`: 234 234 234 / about 39 39 39. Light matches; dark is a step lighter. It is the rail tile's active fill too, so a rail tile and a nav row stay the same. |
+| Active text and icon | 9 9 11 / 250 250 250 | `foreground`: 24 24 24 / 252 252 252 |
+| Idle text (80%) | 24 24 25 / 251 252 253 | `foreground` at 80% |
+| Idle icon | 100 101 103 / 159 160 162 | `muted-foreground` (`--muted`): 114 114 114 / 160 160 160 |
+| Focus ring (35%) | 9 9 11 / 250 250 250 | `foreground` at 35% |
+
 ## Toaster
 
 ```tsx
@@ -584,7 +724,7 @@ Opt-in props (all default to the current look):
 
 | Prop | Values | Effect |
 | --- | --- | --- |
-| `toastRadius` | `"lg"` (default), `"surface"`, `"control"` | `rounded-lg`, `rounded-surface` (from `tokens/css/utilities.css`) or `rounded-field` (the input radius). |
+| `toastRadius` | `"lg"` (default), `"surface"`, `"control"` | `rounded-lg`, `rounded-surface` (from `tokens.css`, or the compat file) or `rounded-field` (the input radius). |
 | `density` | `"default"`, `"compact"` | Current padding and text, or `gap-2 px-3 py-2 text-xs` with `text-xs` descriptions. |
 | `toastIcons` | `"default"`, `"filled24"` | Sonner icons or 24px filled success, info, warning and error icons, a matching loader and a 14px close cross. |
 | `closeButtonStyle` | `"default"`, `"hoverChip"` | Text-style close button or a round chip at the top-right, shown on hover and always on small screens. It turns on `closeButton` unless you set it. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: one JavaScript entry (primitives, shell pieces, app helpers, native tokens), design-token CSS, shared Tailwind v4 CSS and a Tailwind preset.",
   "type": "module",

package/shell/src/Sidebar.tsx

@@ -9,7 +9,7 @@ import {
   AccountSeparator,
   AccountTrigger,
 } from "./SidebarAccountMenu";
-import { Panel, PanelActions, PanelClose, PanelHeader, PanelTitle } from "./SidebarPanel";
+import { NavItem, Panel, PanelActions, PanelClose, PanelHeader, PanelTitle } from "./SidebarPanel";
 import { Rail, RailBody, RailFooter, RailHeader, RailItem, RailSeparator } from "./SidebarRail";
 
 export type {
@@ -36,6 +36,7 @@ export type {
   SidebarPanelHeaderProps,
   SidebarPanelRootProps,
   SidebarPanelTitleProps,
+  SidebarNavItemProps,
 } from "./SidebarPanel";
 export type {
   SidebarAccountAvatarProps,
@@ -68,6 +69,7 @@ export const Sidebar = {
   PanelTitle,
   PanelActions,
   PanelClose,
+  NavItem,
   AccountMenu,
   AccountTrigger,
   AccountAvatar,

package/shell/src/SidebarPanel.tsx

@@ -1,8 +1,9 @@
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
+import { Slot, Slottable } from "@radix-ui/react-slot";
 import { IconX } from "@tabler/icons-react";
 import { Button, type ButtonProps } from "../../src/ui/button";
 import { cn } from "../../src/utils/cn";
-import { panelCloseButtonClass, sidebarHeaderRowClass } from "./app-shell-classes";
+import { panelCloseButtonClass, sidebarHeaderRowClass, sidebarNavIconClass, sidebarNavItemClass } from "./app-shell-classes";
 import { useOptionalSidebar } from "./SidebarChrome";
 
 export type SidebarPanelProps = {
@@ -131,3 +132,38 @@ export function PanelClose({ label = "Close navigation", onClick, className, chi
     </Button>
   );
 }
+
+export type SidebarNavItemProps = ComponentPropsWithoutRef<"button"> & {
+  /** Current route: static fill, `font-medium`, `aria-current="page"`. */
+  active?: boolean;
+  /** Collapsed panel: centred icon, no horizontal padding. */
+  iconOnly?: boolean;
+  /** Leading icon element; gets `sidebarNavIconClass(active)` merged onto it. */
+  icon?: ReactElement;
+  /** Render the single child element (for example a router link) as the row. */
+  asChild?: boolean;
+};
+
+/** Panel nav row (`sidebarNavItemClass`). Renders a native `<button>`, or its child with `asChild`. */
+export function NavItem({
+  active = false,
+  iconOnly = false,
+  icon,
+  asChild = false,
+  className,
+  children,
+  ...props
+}: SidebarNavItemProps) {
+  const Row = asChild ? Slot : "button";
+  return (
+    <Row
+      type={asChild ? undefined : "button"}
+      {...props}
+      aria-current={active ? "page" : undefined}
+      className={cn(sidebarNavItemClass({ active, iconOnly }), className)}
+    >
+      {icon ? <Slot className={sidebarNavIconClass(active)}>{icon}</Slot> : null}
+      <Slottable>{children}</Slottable>
+    </Row>
+  );
+}

package/shell/src/app-shell-classes.ts

@@ -19,18 +19,50 @@ export function railTileStateClass(active: boolean): string {
 /** Count badge pinned to the bottom-right of a rail tile. */
 export const railBadgeClass = "absolute -bottom-0.5 -right-0.5 flex h-4 min-w-4 items-center justify-center rounded-full bg-accent px-1 text-[10px] font-semibold leading-none text-accent-foreground"; // check-tokens-allow: accent
 
-/** Static section label, sentence case, padded to match nav rows. */
+/**
+ * Static section label above a group of panel nav rows. `px-4` lines the text
+ * up with the nav row icons; the colour comes from the app's
+ * `.sidebar-section-label` rule.
+ */
 export const sidebarSectionLabelClass =
-  "sidebar-section-label px-3 py-1 text-[11px] font-medium tracking-[-0.01em]";
+  "sidebar-section-label px-4 py-1 text-[11px] leading-4 font-medium tracking-[-0.01em]";
 
-/** Nav link text: muted until active. */
+/**
+ * Nav row state: idle rows are `foreground/80` and get the fill on hover;
+ * the active row is `font-medium text-foreground` on a static fill.
+ */
 export function sidebarNavLinkTextClass(isActive: boolean): string {
-  return cn(isActive ? "text-foreground" : "text-muted hover:text-foreground"); // check-tokens-allow: text-muted
+  return isActive
+    ? "bg-surface-tertiary font-medium text-foreground"
+    : "font-normal text-foreground/80 hover:bg-surface-tertiary hover:text-foreground";
 }
 
-/** Padding for main sidebar nav rows. */
+/**
+ * Panel nav row layout: full width, `rounded-menu-item` (8px), 13px / 18px
+ * text, focus ring and press scale. Icon-only rows centre the icon.
+ */
 export function sidebarNavRowClass(isIconOnly: boolean): string {
-  return cn(isIconOnly ? "justify-center px-0 py-1.5" : "gap-3 px-3 py-1.5");
+  return cn(
+    "group flex w-full items-center rounded-menu-item py-1.5 text-[0.8125rem] leading-[18px] tracking-[0.005em] transition-[scale,background-color,color] duration-150 ease-smooth active:scale-[0.99] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-foreground/35",
+    isIconOnly ? "justify-center px-0" : "gap-2 px-4",
+  );
+}
+
+export type SidebarNavItemClassOptions = {
+  /** Current route. */
+  active?: boolean;
+  /** Collapsed panel: centred icon, no horizontal padding. */
+  iconOnly?: boolean;
+};
+
+/** Whole panel nav row: `sidebarNavRowClass` plus `sidebarNavLinkTextClass`. */
+export function sidebarNavItemClass({ active = false, iconOnly = false }: SidebarNavItemClassOptions = {}): string {
+  return cn(sidebarNavRowClass(iconOnly), sidebarNavLinkTextClass(active));
+}
+
+/** Nav row icon (put it on the `<svg>`): 19px, muted until active. */
+export function sidebarNavIconClass(active: boolean): string {
+  return cn("size-[19px] shrink-0", active ? "text-foreground" : "text-muted-foreground");
 }
 
 /** Sidebar header row: the panel title and its trailing actions. */

package/shell/src/index.ts

@@ -45,7 +45,10 @@ export {
   railBadgeClass,
   railTileClass,
   railTileStateClass,
+  sidebarNavIconClass,
+  sidebarNavItemClass,
   sidebarNavLinkTextClass,
   sidebarNavRowClass,
   sidebarSectionLabelClass,
 } from "./app-shell-classes.js";
+export type { SidebarNavItemClassOptions } from "./app-shell-classes.js";

package/src/index.ts

@@ -21,6 +21,7 @@ export * from "./ui/dialog";
 export * from "./ui/alert-dialog";
 export * from "./ui/confirm-dialog";
 export * from "./ui/dropdown-menu";
+export * from "./ui/empty-state";
 export * from "./ui/hover-card";
 export * from "./ui/input";
 export * from "./ui/label";
@@ -157,10 +158,13 @@ export {
   railBadgeClass,
   railTileClass,
   railTileStateClass,
+  sidebarNavIconClass,
+  sidebarNavItemClass,
   sidebarNavLinkTextClass,
   sidebarNavRowClass,
   sidebarSectionLabelClass,
 } from "../shell/src/app-shell-classes";
+export type { SidebarNavItemClassOptions } from "../shell/src/app-shell-classes";
 
 // App helpers: confirm skip, update watcher, settings chrome, stable auth.
 export * from "../app/src/index";

package/src/ui/_menu-classes.alt.ts

@@ -17,13 +17,13 @@ export const menuContentClass = [
 ].join(" ");
 
 export const menuSubTriggerClass =
-  "flex cursor-pointer select-none items-center gap-2 rounded-md px-2.5 py-2 text-sm text-foreground outline-hidden transition-[background-color,color,transform] duration-150 ease-out active:scale-[0.99] focus:bg-default focus:text-foreground data-highlighted:bg-default data-highlighted:text-foreground data-[state=open]:bg-default data-disabled:cursor-not-allowed [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0";
+  "flex cursor-pointer select-none items-center gap-2 rounded-menu-item px-2.5 py-2 text-sm text-foreground outline-hidden transition-[background-color,color,transform] duration-150 ease-out active:scale-[0.99] focus:bg-default focus:text-foreground data-highlighted:bg-default data-highlighted:text-foreground data-[state=open]:bg-default data-disabled:cursor-not-allowed [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0";
 
 export const menuItemClass =
-  "relative flex cursor-pointer select-none items-center gap-2 rounded-md px-2.5 py-2 text-sm outline-hidden transition-[background-color,color,transform] duration-150 ease-out active:scale-[0.99] focus:bg-default focus:text-foreground data-highlighted:bg-default data-highlighted:text-foreground data-disabled:pointer-events-none data-disabled:cursor-not-allowed data-disabled:opacity-50 [&>svg]:size-4 [&>svg]:shrink-0 [&_svg]:pointer-events-none";
+  "relative flex cursor-pointer select-none items-center gap-2 rounded-menu-item px-2.5 py-2 text-sm outline-hidden transition-[background-color,color,transform] duration-150 ease-out active:scale-[0.99] focus:bg-default focus:text-foreground data-highlighted:bg-default data-highlighted:text-foreground data-disabled:pointer-events-none data-disabled:cursor-not-allowed data-disabled:opacity-50 [&>svg]:size-4 [&>svg]:shrink-0 [&_svg]:pointer-events-none";
 
 export const menuCheckboxRadioItemClass =
-  "relative flex cursor-pointer select-none items-center rounded-md py-2 pl-8 pr-2.5 text-sm outline-hidden transition-[background-color,color,transform] duration-150 ease-out active:scale-[0.99] focus:bg-default focus:text-foreground data-highlighted:bg-default data-highlighted:text-foreground data-disabled:pointer-events-none data-disabled:cursor-not-allowed data-disabled:opacity-50";
+  "relative flex cursor-pointer select-none items-center rounded-menu-item py-2 pl-8 pr-2.5 text-sm outline-hidden transition-[background-color,color,transform] duration-150 ease-out active:scale-[0.99] focus:bg-default focus:text-foreground data-highlighted:bg-default data-highlighted:text-foreground data-disabled:pointer-events-none data-disabled:cursor-not-allowed data-disabled:opacity-50";
 
 export const menuLabelClass =
   "px-2.5 py-1.5 text-xs font-semibold uppercase tracking-widest text-muted-foreground";

package/src/ui/_menu-classes.ts

@@ -14,13 +14,13 @@ export const menuContentClass = [
 ].join(" ");
 
 export const menuSubTriggerClass =
-  "flex cursor-pointer select-none items-center gap-2 rounded-md px-2.5 py-2 max-sm:min-h-10 text-sm text-foreground outline-none transition-[background-color,color] focus:bg-default focus:text-foreground data-[highlighted]:bg-default data-[highlighted]:text-foreground data-[state=open]:bg-default data-[disabled]:cursor-not-allowed [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0";
+  "flex cursor-pointer select-none items-center gap-2 rounded-menu-item px-2.5 py-2 max-sm:min-h-10 text-sm text-foreground outline-none transition-[background-color,color] focus:bg-default focus:text-foreground data-[highlighted]:bg-default data-[highlighted]:text-foreground data-[state=open]:bg-default data-[disabled]:cursor-not-allowed [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0";
 
 export const menuItemClass =
-  "relative flex cursor-pointer select-none items-center gap-2 rounded-md px-2.5 py-2 max-sm:min-h-10 text-sm outline-none transition-[background-color,color] focus:bg-default focus:text-foreground data-[highlighted]:bg-default data-[highlighted]:text-foreground data-[disabled]:pointer-events-none data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50 [&>svg]:size-4 [&>svg]:shrink-0 [&_svg]:pointer-events-none";
+  "relative flex cursor-pointer select-none items-center gap-2 rounded-menu-item px-2.5 py-2 max-sm:min-h-10 text-sm outline-none transition-[background-color,color] focus:bg-default focus:text-foreground data-[highlighted]:bg-default data-[highlighted]:text-foreground data-[disabled]:pointer-events-none data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50 [&>svg]:size-4 [&>svg]:shrink-0 [&_svg]:pointer-events-none";
 
 export const menuCheckboxRadioItemClass =
-  "relative flex cursor-pointer select-none items-center rounded-md py-2 max-sm:min-h-10 pl-8 pr-2.5 text-sm outline-none transition-[background-color,color] focus:bg-default focus:text-foreground data-[highlighted]:bg-default data-[highlighted]:text-foreground data-[disabled]:pointer-events-none data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50";
+  "relative flex cursor-pointer select-none items-center rounded-menu-item py-2 max-sm:min-h-10 pl-8 pr-2.5 text-sm outline-none transition-[background-color,color] focus:bg-default focus:text-foreground data-[highlighted]:bg-default data-[highlighted]:text-foreground data-[disabled]:pointer-events-none data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50";
 
 export const menuLabelClass =
   "px-2.5 py-1.5 text-xs font-semibold uppercase tracking-widest text-muted-foreground";

package/src/ui/badge.tsx

@@ -9,6 +9,8 @@ const badgeVariants = cva(
         default: "border-border bg-default text-foreground",
         secondary: "border-separator bg-default text-default-foreground",
         destructive: "border-danger/25 bg-danger/12 text-danger",
+        // Neutral border with a faint danger tint, e.g. a revoked or expired status.
+        "destructive-soft": "border-border bg-danger/10 text-danger",
         outline: "border-separator bg-transparent text-muted-foreground",
         success: "border-success/25 bg-success/12 text-success",
         warning: "border-warning/25 bg-warning/12 text-warning",

package/src/ui/empty-state.tsx

@@ -0,0 +1,119 @@
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cn } from "../utils/cn";
+
+// `default`: open centred block, large bare icon, one muted line (a page or list body).
+// `panel`: filled rounded block with the icon in a tile (a detail panel or modal section).
+export type EmptyStateVariant = "default" | "panel";
+
+const EmptyStateContext = React.createContext<EmptyStateVariant>("default");
+
+export type EmptyStateRootProps = React.ComponentProps<"div"> & {
+  /** Layout for the other parts. Default `"default"`. */
+  variant?: EmptyStateVariant;
+};
+
+function Root({ variant = "default", className, ...props }: EmptyStateRootProps) {
+  return (
+    <EmptyStateContext value={variant}>
+      <div
+        {...props}
+        className={cn(
+          "flex flex-col items-center justify-center text-center",
+          variant === "panel" ? "rounded-lg bg-surface-secondary px-4 py-10" : "px-4 py-20",
+          className,
+        )}
+      />
+    </EmptyStateContext>
+  );
+}
+Root.displayName = "EmptyState.Root";
+
+export type EmptyStateIconProps = {
+  /** Icon component, e.g. a Tabler icon. */
+  icon: React.ComponentType<{ size?: number | string; stroke?: number | string; className?: string }>;
+  /** Pixel size. Default 40 (`default`) or 22 (`panel`). */
+  size?: number;
+  /** Stroke width. Default the icon's own (`default`) or 1.5 (`panel`). */
+  stroke?: number;
+  /** Classes for the outer element: the icon (`default`) or its tile (`panel`). */
+  className?: string;
+};
+
+function Icon({ icon: IconComponent, size, stroke, className }: EmptyStateIconProps) {
+  if (React.use(EmptyStateContext) === "panel") {
+    return (
+      <div
+        className={cn(
+          "mb-3 flex h-11 w-11 items-center justify-center rounded-lg bg-surface-tertiary",
+          className,
+        )}
+      >
+        <IconComponent size={size ?? 22} className="text-muted-foreground" stroke={stroke ?? 1.5} />
+      </div>
+    );
+  }
+  return (
+    <IconComponent
+      size={size ?? 40}
+      stroke={stroke}
+      className={cn("mb-3 text-muted-foreground", className)}
+    />
+  );
+}
+Icon.displayName = "EmptyState.Icon";
+
+export type EmptyStateTitleProps = React.ComponentProps<"p"> & {
+  /** Render the child element (e.g. an `h3`) with the title classes. */
+  asChild?: boolean;
+};
+
+function Title({ asChild = false, className, ...props }: EmptyStateTitleProps) {
+  const Comp = asChild ? Slot : "p";
+  return (
+    <Comp
+      {...props}
+      className={cn(
+        "text-sm font-medium text-foreground",
+        React.use(EmptyStateContext) === "default" && "mb-1",
+        className,
+      )}
+    />
+  );
+}
+Title.displayName = "EmptyState.Title";
+
+export type EmptyStateDescriptionProps = React.ComponentProps<"p">;
+
+function Description({ className, ...props }: EmptyStateDescriptionProps) {
+  return (
+    <p
+      {...props}
+      className={cn(
+        React.use(EmptyStateContext) === "panel" && "mt-1 max-w-[240px]",
+        "text-sm text-muted-foreground",
+        className,
+      )}
+    />
+  );
+}
+Description.displayName = "EmptyState.Description";
+
+export type EmptyStateActionsProps = React.ComponentProps<"div">;
+
+function Actions({ className, ...props }: EmptyStateActionsProps) {
+  return <div {...props} className={cn("mt-4", className)} />;
+}
+Actions.displayName = "EmptyState.Actions";
+
+/**
+ * Composable "nothing here yet" block: `EmptyState.Root` sets the variant, the
+ * other parts read it. Render only the parts you need.
+ */
+export const EmptyState = {
+  Root,
+  Icon,
+  Title,
+  Description,
+  Actions,
+};

package/src/ui/kbd.tsx

@@ -1,14 +1,24 @@
 import * as React from "react";
 import { cn } from "../utils/cn";
 
-const Kbd = React.forwardRef<HTMLElement, React.HTMLAttributes<HTMLElement>>(
-  ({ className, ...props }, ref) => (
+// `subtle`: plain filled key for inline hints; size and font come from the
+// surrounding text.
+const kbdVariantClasses = {
+  default:
+    "pointer-events-none inline-flex h-5 select-none items-center gap-1 rounded-md bg-surface-secondary px-1.5 font-mono text-[10px] font-medium text-muted-foreground",
+  subtle: "rounded bg-surface-secondary px-1.5 py-0.5 text-foreground",
+};
+
+export type KbdProps = React.HTMLAttributes<HTMLElement> & {
+  /** Default `"default"`. */
+  variant?: keyof typeof kbdVariantClasses;
+};
+
+const Kbd = React.forwardRef<HTMLElement, KbdProps>(
+  ({ className, variant = "default", ...props }, ref) => (
     <kbd
       ref={ref}
-      className={cn(
-        "pointer-events-none inline-flex h-5 select-none items-center gap-1 rounded-md bg-surface-secondary px-1.5 font-mono text-[10px] font-medium text-muted-foreground",
-        className,
-      )}
+      className={cn(kbdVariantClasses[variant], className)}
       {...props}
     />
   ),

package/src/ui/spinner.tsx

@@ -7,18 +7,34 @@ const sizeClasses = {
   lg: "size-8",
 };
 
+export type SpinnerProps = Omit<React.ComponentPropsWithoutRef<"svg">, "size" | "stroke"> & {
+  /** Named size (a `size-*` class) or a pixel size passed to the icon (no size class). Default `"md"`. */
+  size?: "sm" | "md" | "lg" | number;
+  /** Icon stroke width. Default the icon's own (2). */
+  stroke?: number | string;
+  /** `"muted"` adds `text-muted-foreground`; `"inherit"` adds no colour class, so the icon uses `currentColor`. Default `"muted"`. */
+  tone?: "muted" | "inherit";
+  /** Hide from assistive tech (`aria-hidden`, no `role="status"` or label), e.g. inside a labelled button. Default `false`. */
+  decorative?: boolean;
+};
+
 function Spinner({
   size = "md",
+  tone = "muted",
+  decorative = false,
   className,
   ...props
-}: Omit<React.ComponentPropsWithoutRef<"svg">, "size" | "stroke"> & {
-  size?: "sm" | "md" | "lg";
-}) {
+}: SpinnerProps) {
   return (
     <IconLoader2
-      role="status"
-      aria-label="Loading"
-      className={cn("animate-spin text-muted-foreground", sizeClasses[size], className)}
+      {...(decorative ? { "aria-hidden": true } : { role: "status", "aria-label": "Loading" })}
+      size={typeof size === "number" ? size : undefined}
+      className={cn(
+        "animate-spin",
+        tone === "muted" && "text-muted-foreground",
+        typeof size === "number" ? undefined : sizeClasses[size],
+        className,
+      )}
       {...props}
     />
   );

package/src/ui/tabs.tsx

@@ -8,7 +8,11 @@ const Tabs = TabsPrimitive.Root;
 
 // `pills` (default): isolated rounded pills with a gap, no shared track.
 // `segmented`: connected bar with a sliding pill, kept for marketing surfaces.
-type TabsListVariant = "pills" | "segmented";
+// `soft`: borderless wrapping pills, the active one filled. Uses no `t-tabs`
+// CSS, so triggers can hold an absolutely placed child (e.g. a progress bar).
+type TabsListVariant = "pills" | "segmented" | "soft";
+
+const TabsListVariantContext = React.createContext<TabsListVariant>("pills");
 
 const TabsList = React.forwardRef<
   React.ComponentRef<typeof TabsPrimitive.List>,
@@ -82,21 +86,26 @@ const TabsList = React.forwardRef<
   }, [variant]);
 
   return (
-    <TabsPrimitive.List
-      ref={mergedRef}
-      className={cn(
-        "t-tabs max-sm:max-w-full max-sm:justify-center-safe max-sm:overflow-x-auto max-sm:scrollbar-none",
-        variant === "segmented" ? "t-tabs--segmented" : "t-tabs--pills",
-        className,
-      )}
-      data-variant={variant}
-      {...props}
-    >
-      {variant === "segmented" ? (
-        <span ref={pillRef} className="t-tabs-pill" aria-hidden="true" />
-      ) : null}
-      {children}
-    </TabsPrimitive.List>
+    <TabsListVariantContext value={variant}>
+      <TabsPrimitive.List
+        ref={mergedRef}
+        className={cn(
+          variant === "soft"
+            ? "flex flex-wrap items-center justify-center gap-1.5"
+            : "t-tabs max-sm:max-w-full max-sm:justify-center-safe max-sm:overflow-x-auto max-sm:scrollbar-none",
+          variant === "segmented" && "t-tabs--segmented",
+          variant === "pills" && "t-tabs--pills",
+          className,
+        )}
+        data-variant={variant}
+        {...props}
+      >
+        {variant === "segmented" ? (
+          <span ref={pillRef} className="t-tabs-pill" aria-hidden="true" />
+        ) : null}
+        {children}
+      </TabsPrimitive.List>
+    </TabsListVariantContext>
   );
 });
 TabsList.displayName = TabsPrimitive.List.displayName;
@@ -108,7 +117,9 @@ const TabsTrigger = React.forwardRef<
   <TabsPrimitive.Trigger
     ref={ref}
     className={cn(
-      "t-tab inline-flex items-center justify-center gap-1.5 whitespace-nowrap text-sm font-medium ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+      React.use(TabsListVariantContext) === "soft"
+        ? "relative flex items-center gap-2 overflow-hidden rounded-full px-4 py-2 text-sm text-muted-foreground transition-[transform,background-color] hover:bg-surface-secondary active:scale-[0.97] data-[state=active]:bg-surface-secondary data-[state=active]:text-foreground"
+        : "t-tab inline-flex items-center justify-center gap-1.5 whitespace-nowrap text-sm font-medium ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
       className,
     )}
     {...props}

package/src/utils/cn.ts

@@ -1,12 +1,14 @@
 import { type ClassValue, clsx } from "clsx";
 import { extendTailwindMerge } from "tailwind-merge";
 
-// `rounded-field` is a custom radius token — teach twMerge it conflicts with
-// `rounded-none` / `rounded-md` / etc. so Input overrides actually win.
+// `rounded-field` and the tokens.css radii (`rounded-surface`,
+// `rounded-menu-item`, `rounded-control`) are custom radius tokens — teach
+// twMerge they conflict with `rounded-none` / `rounded-md` / etc. so the last
+// radius class wins.
 const twMerge = extendTailwindMerge({
   extend: {
     theme: {
-      borderRadius: ["field"],
+      borderRadius: ["field", "surface", "menu-item", "control"],
     },
   },
 });

package/tokens/README.md

@@ -6,17 +6,17 @@ Design tokens and shared Tailwind v4 CSS for the vvedantb web apps. The CSS and
 
 | Export | File | What it is |
 | --- | --- | --- |
-| `@vvedantb/ui/tokens`, `@vvedantb/ui/tokens/tokens.css` | `src/tokens.css` | Colour, radius, shadow, ease and font tokens (`@theme`), light/dark variables, `dark` variant, `*` border and `body` defaults. In 0.2.1 it also defines shadcn-style aliases (`primary`, `muted-foreground`, `secondary`, `destructive`, `card`, `popover`, `input`, `ring`) that point at the same tokens. |
+| `@vvedantb/ui/tokens`, `@vvedantb/ui/tokens/tokens.css` | `src/tokens.css` | Colour, radius, shadow, ease and font tokens (`@theme`), light/dark variables, `dark` variant, the radius utilities `rounded-surface` (`clamp(0.75rem, var(--radius), 1rem)`), `rounded-menu-item` (`min(var(--radius), 0.5rem)`) and `rounded-control` (`min(var(--radius), 0.625rem)`) (0.7.1; `rounded-surface` was in `utilities.css` before), `*` border and `body` defaults. In 0.2.1 it also defines shadcn-style aliases (`primary`, `muted-foreground`, `secondary`, `destructive`, `card`, `popover`, `input`, `ring`) that point at the same tokens. |
 | `tokens` and `Tokens` from `@vvedantb/ui` | `src/native.ts` | JS colours, radii and spacing for React Native. `@vvedantb/native-ui` keeps its own copy in `src/tokens.ts`; a test keeps the two equal. |
 | `@vvedantb/ui/tokens/css/base.css` | `src/css/base.css` | `html` touch/accent, `::selection`, control transitions, pointer cursor, range accent (`@layer base`). |
 | `@vvedantb/ui/tokens/css/dialog.css` | `src/css/dialog.css` | Unlayered `max-width: none` for `@vvedantb/ui` compact (bottom-sheet) dialogs. |
 | `@vvedantb/ui/tokens/css/modal.css` | `src/css/modal.css` | `.t-modal`, `.is-open`, `.is-closing` and `t-modal-presence-wait` (`@layer components`). |
 | `@vvedantb/ui/tokens/css/tabs.css` | `src/css/tabs.css` | `.t-tab`, active colour, `.t-tabs-pill`, small-screen `.t-tabs` scrolling. |
 | `@vvedantb/ui/tokens/css/tabs-pills.css` | `src/css/tabs-pills.css` | `--tabs-*` colour variables, `.t-tabs--segmented`, `.t-tabs--pills` and pill hover / active fills. |
-| `@vvedantb/ui/tokens/css/utilities.css` | `src/css/utilities.css` | `@utility hit-target`, `@utility reveal-on-hover` and `@utility rounded-surface` (`clamp(0.75rem, var(--radius), 1rem)`). |
+| `@vvedantb/ui/tokens/css/utilities.css` | `src/css/utilities.css` | `@utility hit-target` and `@utility reveal-on-hover`. `rounded-surface` moved to `tokens.css` in 0.7.1. |
 | `@vvedantb/ui/tokens/css/scrollbar-thin.css` | `src/css/scrollbar-thin.css` | `.scrollbar-thin` (`@layer utilities`, always emitted). |
 | `@vvedantb/ui/tokens/css/animations.css` | `src/css/animations.css` | `animate-aurora`, `animate-fade-in-up`, `animate-indeterminate` as `@theme` (CSS-first apps). |
-| `@vvedantb/ui/tokens/css/compat-shadcn-rgb.css`, `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | `src/css/compat-shadcn-rgb.css` | Replaces `tokens.css` for apps with shadcn-style `R G B` channel variables. Defines only the UI-only `--color-*` names as `rgb(var(--x) / alpha)` references, `--radius-field`, `--scrollbar`, `--field-radius` and a `glass-panel-strong` fallback. Import it **or** `tokens.css`, never both. |
+| `@vvedantb/ui/tokens/css/compat-shadcn-rgb.css`, `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | `src/css/compat-shadcn-rgb.css` | Replaces `tokens.css` for apps with shadcn-style `R G B` channel variables. Defines only the UI-only `--color-*` names as `rgb(var(--x) / alpha)` references, `--radius-field`, `--scrollbar`, `--field-radius`, the same three radius utilities as `tokens.css` and a `glass-panel-strong` fallback. Import it **or** `tokens.css`, never both. |
 | `@vvedantb/ui/tokens/css/index.css` | `src/css/index.css` | base + dialog + utilities + scrollbar-thin + animations, for new CSS-first apps. |
 | `@vvedantb/ui/tokens/tailwind-preset` | `src/tailwind-preset.mjs` (+ `.d.mts`) | Tailwind preset for apps that load a JS config with `@config`. |
 

package/tokens/src/css/compat-shadcn-rgb.css

@@ -65,6 +65,20 @@
   --radius-field: min(calc(var(--radius) + 0.25rem), 1.25rem);
 }
 
+/* The radius utilities from tokens.css, which this file replaces. They read
+   the app's `--radius`. */
+@utility rounded-surface {
+  border-radius: clamp(0.75rem, var(--radius), 1rem);
+}
+
+@utility rounded-menu-item {
+  border-radius: min(var(--radius), 0.5rem);
+}
+
+@utility rounded-control {
+  border-radius: min(var(--radius), 0.625rem);
+}
+
 :root {
   --scrollbar: rgb(var(--muted-foreground) / 0.35);
   --field-radius: min(calc(var(--radius) + 0.25rem), 1.25rem);

package/tokens/src/css/utilities.css

@@ -32,8 +32,3 @@
     }
   }
 }
-
-/* Surface radius: follows the theme `--radius`, kept between 0.75rem and 1rem. */
-@utility rounded-surface {
-  border-radius: clamp(0.75rem, var(--radius), 1rem);
-}

package/tokens/src/tokens.css

@@ -94,6 +94,22 @@
   --font-instrumentSans: "Instrument Sans", system-ui, sans-serif;
 }
 
+/* Radius utilities that follow the theme `--radius` (values at the default
+   1rem in brackets). Surfaces: kept between 0.75rem and 1rem (16px). Menu
+   items and sidebar nav rows: capped at 0.5rem (8px) so they sit inside the
+   surface corner. Controls: capped at 0.625rem (10px). */
+@utility rounded-surface {
+  border-radius: clamp(0.75rem, var(--radius), 1rem);
+}
+
+@utility rounded-menu-item {
+  border-radius: min(var(--radius), 0.5rem);
+}
+
+@utility rounded-control {
+  border-radius: min(var(--radius), 0.625rem);
+}
+
 @layer base {
   :root,
   .light,