@tristan2828/ui-foundation 3.1.2 → 3.3.0

package/conventions/AGENTS.md

@@ -51,6 +51,13 @@ is right. Do not disable, skip, or work around it.
 - NEVER import `@tristan2828/ui-foundation/gateway` outside
   `src/api/gateway/`. Components and hooks call a gateway module through
   TanStack Query. (Enforced: no-restricted-imports.)
+- NEVER add a database table or column without a comment. The migration
+  that creates it also runs `COMMENT ON TABLE` / `COMMENT ON COLUMN`,
+  saying what it holds in words someone with only database access can use:
+  units, what null means, which table an id points at. A second agent with
+  credentials and no repo reads the schema alone. Applies to an app with a
+  Postgres backend. (Enforced: `backend/scripts/check_db_comments.py`, run
+  by `scripts/check-backend-postgres.sh` after `alembic upgrade head`.)
 - NEVER let a backend-shaped response reach a component. Paginated data is
   `Page<T>`. Failures are `AppError`. Queries are `QuerySpec`. The gateway
   translates; nothing above it knows the wire format. (Enforced: gateway

package/conventions/docs/cell-patterns.md

@@ -5,10 +5,14 @@ first attempt gets wrong — **not components**: the lookup maps are always
 per-entity, and only the shape is reusable. Copy the markup into your
 `<entity>-columns.tsx`.
 
-Every pattern below was chosen for a real column, from a page of
+Patterns 1–10 were each chosen for a real column, from a page of
 alternatives ([`column-options.md`](column-options.md)), not designed in the abstract.
-A pattern that proves generic is worth raising for the foundation, so it
-ships here for every app.
+Patterns from 11 on are marked **Unproven**: written ahead of a real
+column, so no app has tested them on real data yet. Prefer a proven
+pattern when one fits. When you use an unproven one, say so in the
+entity's plan, and raise what you learned for the foundation, so the
+entry can lose its label. A pattern that proves generic is worth raising
+too, so it ships here for every app.
 
 ## The rules that apply to every cell
 
@@ -223,3 +227,102 @@ A one-to-many value (`★ 4.7 (3)` opening a per-person breakdown).
 - **Cost:** the detail can't be scanned down the column, and an average
   can't be sorted server-side without a backend change
   (`enableSorting: false`).
+
+## 11. Number or currency — *Unproven*
+
+A count, a quantity, a price.
+
+```tsx
+// Module scope: one formatter per column, not one per cell render.
+const priceFormatter = new Intl.NumberFormat(undefined, { style: 'currency', currency: 'USD' })
+
+cell: ({ getValue }) => {
+  const value = getValue<string | null>()
+  return value == null ? emptyCell : <span className="tabular-nums">{priceFormatter.format(Number(value))}</span>
+}
+```
+
+- `tabular-nums` gives every digit the same width, so values line up down
+  the column even when left-aligned.
+- **Zero is a value, not an empty cell.** Test `value == null`, never
+  falsiness, or `0` renders as an em dash.
+- An API `format: decimal` arrives as a **string**. `Number()` is exact
+  enough to display (about 15 significant digits). Never add up money in
+  floats on the client: totals come from the backend.
+- **Right-aligning isn't available yet.** `DataTable`'s `meta.align` only
+  supports `'center'`, and a right-aligned cell under a left-aligned header
+  looks broken. Stay left-aligned until a real column needs
+  `align: 'right'`, then raise it for the foundation.
+- The currency code comes from the data or the plan, never a guess. The
+  template's `USD` is the demo's.
+- **Cost:** none to speak of. It's the plain-text pattern with formatting.
+
+## 12. Boolean — *Unproven*
+
+A yes/no field.
+
+```tsx
+cell: ({ getValue }) => {
+  const value = getValue<boolean | null>()
+  if (value == null) return emptyCell
+  return value ? (
+    <span className="inline-flex items-center gap-1">
+      <CheckIcon aria-hidden="true" className="size-4 text-success-text" />
+      Yes
+    </span>
+  ) : (
+    <span className="text-muted-foreground">No</span>
+  )
+}
+```
+
+- **The word carries the value.** The check only reinforces it, so the
+  cell survives greyscale and a screen reader hears "Yes".
+- **Never a checkbox** in a read-only cell. It looks editable, and people
+  will try to click it.
+- "No" is muted, not red. False is rarely bad. If it is, the field is
+  really an enum with a verdict, and pattern 5 fits better.
+- **Nullable means three states.** `null` is the em dash, distinct from
+  "No". Check the schema before collapsing them.
+- **Cost:** a column that is mostly "Yes" is noise. If almost every row
+  shares the value, consider showing only the exception.
+
+## 13. Progress bar — *Unproven*
+
+A percentage, or a count out of a total (`7 of 12 done`).
+
+- The package doesn't ship `progress`. Install shadcn's into
+  `src/components/ui/` (`npx shadcn@<tools.shadcn> add progress`, after
+  checking its dependencies against `deps-allowlist.json`).
+- **Always print the number** beside the bar (`72%`, `7 / 12`). The bar
+  shows roughly how far; the number says exactly.
+- Fix the bar's width (`w-24`) so bars compare down the column. A bar that
+  stretches with the column compares nothing.
+- The default colour is `bg-primary`. Tone it (`bg-success`) only when the
+  value means something, like "complete", and say that in the plan.
+- Clamp to the schema's range. A value of 105% from bad data shouldn't
+  draw past the track.
+- Give each bar a row-specific `aria-label` (`${row.original.name}
+  progress`).
+- **Cost:** a bar takes far more width than the number it replaces. On a
+  wide table, the plain number from pattern 11 usually wins.
+
+## 14. Avatar and name — *Unproven*
+
+A person: an assignee or an owner.
+
+- The package doesn't ship `avatar`. Install shadcn's the same way as
+  pattern 13.
+- **Always render the fallback** (initials). Images fail, load slowly, or
+  aren't set, and the cell must still look intentional.
+- The image is decorative (`alt=""`) because the name is right beside
+  it. Otherwise a screen reader reads the name twice.
+- `size-6` keeps the row height unchanged at `compact` density
+  ([`design-language.md`](design-language.md) "Density").
+- Initials on `bg-muted text-muted-foreground`. Categorical colours
+  would make every person look like a category.
+- Avatar URLs load from wherever the API points. Use `loading="lazy"` so a
+  25-row page doesn't fetch every image up front.
+- **Cost:** a column of faces draws the eye more than any other cell. Use
+  it when *who* matters most in the row, not as decoration.
+

package/conventions/docs/design-language.md

@@ -8,16 +8,24 @@ composites don't grow that way; they are built against a real app's screen.
 
 ## Semantic tones
 
-Three tones carry meaning: **success**, **warning**, **destructive**. Grey
-is not a tone — it is the absence of one, and most values should stay grey.
+Four tones carry meaning: **success**, **warning**, **destructive** and
+**info**. Grey is not a tone — it is the absence of one, and most values
+should stay grey.
+
+The first three say good or bad. **Info** says neither: *notice this*,
+without a verdict. It is for a state that is worth seeing but isn't good
+news or bad news: in progress, new, scheduled, beta. If the honest answer
+to "is this good?" is "neither, but it matters right now", it's info. If
+the answer is "neither, and it doesn't", it's grey: info is still a
+colour, and the "about a third" limit below counts it.
 
 Each tone has two kinds of token, and picking the wrong one is the single
 most common way to ship an unreadable label:
 
 | Token | For | Why it can't be the other one |
 |---|---|---|
-| `--success` / `--warning` / `--destructive` (+ `-foreground`) | a **solid fill**, always with white text on it | chosen to contrast with *white*, so on the page background it's too light in light mode |
-| `--success-text` / `--warning-text` / `--destructive-text` | the tone as **text, a border or an icon** on the page background | chosen to contrast with *the page*, so as a fill under white text it's needlessly dark |
+| `--success` / `--warning` / `--destructive` / `--info` (+ `-foreground`) | a **solid fill**, always with white text on it | chosen to contrast with *white*, so on the page background it's too light in light mode |
+| `--success-text` / `--warning-text` / `--destructive-text` / `--info-text` | the tone as **text, a border or an icon** on the page background | chosen to contrast with *the page*, so as a fill under white text it's needlessly dark |
 
 Only the `*-text` tokens are remapped in `.dark`. A solid fill keeps one
 shade in both themes, because it always carries white text and the page
@@ -25,20 +33,22 @@ behind it never enters the calculation.
 
 Measured ratios (WCAG 2.x, sRGB) are recorded next to each primitive in
 the package's `styles/theme.css`, and its `e2e/storybook-visual.spec.ts` re-checks all
-nine tone/style combinations with axe against the rendered DOM in both
+twelve tone/style combinations with axe against the rendered DOM in both
 themes. **A new tone or style is not done until it appears in that story.**
 
 ## The three badge styles
 
 `Badge` ships each tone in three styles. They are not interchangeable:
 
-- **Outline** — `outline-success`, `outline-warning`, `outline-destructive`.
+- **Outline** — `outline-success`, `outline-warning`, `outline-destructive`,
+  `outline-info`.
   The default choice, and the one proven across real columns. Quiet enough
   to repeat down 25 rows without the column becoming a wall of color.
-- **Tinted** — `tinted-success`, `tinted-warning`, `tinted-destructive`. A
+- **Tinted** — `tinted-success`, `tinted-warning`, `tinted-destructive`,
+  `tinted-info`. A
   low-alpha wash of the tone with `*-text` on top. More presence than
   outline; use when the value is the point of the row, not a detail of it.
-- **Solid** — `success`, `warning`, `destructive`. The loudest. Use for one
+- **Solid** — `success`, `warning`, `destructive`, `info`. The loudest. Use for one
   value that must be impossible to miss, rarely for a whole column: solid
   reads as an alert, and a column of alerts reads as noise.
 
@@ -75,7 +85,7 @@ Two rules that keep this honest:
 
 ## Categorical colour
 
-Tones say good or bad. A value that is merely *different* from its
+Tones say good, bad or *notice this*. A value that is merely *different* from its
 neighbours — a genre, a team, a category — needs a different mechanism, and
 it is `--category-1` through `--category-8`.
 
@@ -98,7 +108,9 @@ Four things about them:
 
 - **The hues avoid red, green and amber**, which the tones already spend. A
   category drawn in red reads as "this one is bad" even when nothing is
-  wrong.
+  wrong. Info's blue came later, and slots 1, 6 and 8 sit near it: a table
+  that shows an info badge keeps its categories off those three, so a blue
+  genre isn't read as "notice this".
 - **They are ordered by distinctness, not by hue angle.** An app using
   three categories gets three obviously different colours. Past about five,
   hue alone stops separating them — slots 3 and 7 are both yellow-greens —
@@ -114,3 +126,57 @@ Four things about them:
 
 If you find yourself wanting a ninth, that is usually a sign the column
 should be showing a shape or a label rather than more colours.
+
+## Typography
+
+Five roles cover every screen. Each is one class that sets size, line
+height and weight together, from tokens in the package's `styles/theme.css`:
+
+| Class | For | Size / weight |
+|---|---|---|
+| `type-page-title` | the screen's one `<h1>` (a table's title, a form's title) | 18px / 600 |
+| `type-section-title` | a heading inside a screen (a form section, a card group) | 16px / 600 |
+| `type-body` | running text, table cells, form text, the pagination summary | 14px / 400 |
+| `type-label` | column headers, field labels, a small heading over a group | 14px / 500 |
+| `type-caption` | counts, metadata, helper text under a field | 12px / 400 |
+
+- **Use a role instead of size and weight classes,** not as well as them.
+  `type-page-title` replaces `text-lg font-semibold`. Combining a role with
+  `text-sm`, `font-medium` or `leading-*` makes two classes set the same
+  property, and which one wins depends on the order of rules in the
+  stylesheet, not on the order in `className`.
+- **Colour stays separate:** `type-caption text-muted-foreground`. A role
+  never sets a colour, so any text token pairs with it.
+- **Why `type-*` and not `text-*`:** `cn` (tailwind-merge) treats an
+  unknown `text-*` class as a colour, so
+  `cn('text-page-title', 'text-foreground')` would silently drop the title.
+- A shadcn primitive keeps its own sizes (`CardTitle`, `Button`). Don't put
+  a role on one: its built-in size classes would then compete with the role.
+
+## Density
+
+Tables have three densities, set with `data-density` on **any ancestor**
+(a wrapper `<div>`, a route's layout, or `<html>` for the whole app). It is
+a token set, not a `DataTable` prop:
+
+```tsx
+<div data-density="compact">
+  <DataTable … />
+</div>
+```
+
+| `data-density` | Cell padding (vertical) | Header height | For |
+|---|---|---|---|
+| `compact` | 4px | 32px | wide tables people scan, many rows per screen |
+| *(unset)* | 8px | 40px | the default |
+| `comfortable` | 12px | 48px | short tables, or rows people read rather than scan |
+
+- Density changes padding only. Text keeps `type-body`, so compact never
+  drops below a readable size.
+- Pick **one density per screen**. Two tables at different densities side
+  by side look like a mistake.
+- Under the hood, the table primitive's cells read `--table-cell-px`,
+  `--table-cell-py` and `--table-head-height`, and the `data-density`
+  selectors in `styles/theme.css` set them. The package's Storybook check
+  measures that each step really changes the row height.
+

package/dist/components/app/app-shell.js

@@ -69,7 +69,7 @@ export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true }
                                                                 ? location.pathname === to
                                                                 : location.pathname.startsWith(to);
                                                             return (_jsx(SidebarMenuItem, { children: _jsxs(SidebarMenuButton, { isActive: isActive, tooltip: label, render: _jsx(NavLink, { to: to, end: end }), children: [_jsx(Icon, {}), _jsx("span", { children: label })] }) }, to));
-                                                        }) }) })] }), sidebarExtra] }), _jsx(SidebarFooter, { children: _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate text-xs text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
+                                                        }) }) })] }), sidebarExtra] }), _jsx(SidebarFooter, { children: _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
                                                     setIsLoggingOut(true);
                                                     logout().catch(() => setIsLoggingOut(false));
                                                 }, children: _jsx(LogOutIcon, {}) })] }) })] }) }), _jsxs(SidebarInset, { className: "min-w-0", children: [_jsxs("header", { className: "flex h-14 shrink-0 items-center gap-2 border-b border-border px-4", children: [_jsx(SidebarTrigger, {}), _jsx("div", { className: "flex-1" }), _jsx(ThemeToggle, {})] }), _jsx("div", { className: "flex-1 p-6", children: _jsx(Outlet, {}) })] })] }), _jsx(Toaster, { position: "top-center" })] }));

package/dist/components/app/data-table.js

@@ -163,5 +163,5 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                                                         : 'none', children: header.isPlaceholder ? null : canSort ? (_jsxs("button", { type: "button", className: cn('flex items-center gap-1 text-foreground', header.column.columnDef.meta?.align === 'center' && 'w-full justify-center'), onClick: header.column.getToggleSortingHandler(), children: [flexRender(header.column.columnDef.header, header.getContext()), sortDirection === 'asc' ? (_jsx(ArrowUpIcon, { className: "size-3.5 text-muted-foreground" })) : sortDirection === 'desc' ? (_jsx(ArrowDownIcon, { className: "size-3.5 text-muted-foreground" })) : (_jsx(ArrowUpDownIcon, { className: "size-3.5 text-muted-foreground/50" }))] })) : (flexRender(header.column.columnDef.header, header.getContext())) }, header.id));
                                     }) }, headerGroup.id))) }), _jsx(TableBody, { children: table.getRowModel().rows.map((row) => (_jsx(TableRow, { className: cn((pinFirstColumn || pinLastColumn) && ROW_GROUP_CLASS), children: row.getVisibleCells().map((cell, index) => (_jsx(TableCell, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn &&
                                             index === row.getVisibleCells().length - 1 &&
-                                            PINNED_LAST_COLUMN_CLASS, cell.column.columnDef.meta?.align === 'center' && 'text-center'), children: flexRender(cell.column.columnDef.cell, cell.getContext()) }, cell.id))) }, row.id))) })] }), pinFirstColumn && isOverflowing && (_jsx("div", { ref: barRef, "aria-hidden": "true", tabIndex: -1, "data-slot": "bottom-scrollbar", className: "sticky bottom-0 z-20 h-4 overflow-x-auto border-t border-border bg-background", children: _jsx("div", { style: { width: scrollWidth, height: 1 } }) })), _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("p", { className: "text-sm text-muted-foreground", children: [total === 0 ? 0 : (page - 1) * pageSize + 1, '–', Math.min(page * pageSize, total), " of ", total] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Previous page", disabled: page <= 1, onClick: () => onPageChange(page - 1), children: _jsx(ChevronLeftIcon, {}) }), _jsxs("span", { className: "text-sm text-muted-foreground", children: ["Page ", page, " of ", pageCount] }), _jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Next page", disabled: page >= pageCount, onClick: () => onPageChange(page + 1), children: _jsx(ChevronRightIcon, {}) })] })] })] }))] }));
+                                            PINNED_LAST_COLUMN_CLASS, cell.column.columnDef.meta?.align === 'center' && 'text-center'), children: flexRender(cell.column.columnDef.cell, cell.getContext()) }, cell.id))) }, row.id))) })] }), pinFirstColumn && isOverflowing && (_jsx("div", { ref: barRef, "aria-hidden": "true", tabIndex: -1, "data-slot": "bottom-scrollbar", className: "sticky bottom-0 z-20 h-4 overflow-x-auto border-t border-border bg-background", children: _jsx("div", { style: { width: scrollWidth, height: 1 } }) })), _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("p", { className: "type-body text-muted-foreground", children: [total === 0 ? 0 : (page - 1) * pageSize + 1, '–', Math.min(page * pageSize, total), " of ", total] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Previous page", disabled: page <= 1, onClick: () => onPageChange(page - 1), children: _jsx(ChevronLeftIcon, {}) }), _jsxs("span", { className: "type-body text-muted-foreground", children: ["Page ", page, " of ", pageCount] }), _jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Next page", disabled: page >= pageCount, onClick: () => onPageChange(page + 1), children: _jsx(ChevronRightIcon, {}) })] })] })] }))] }));
 }

package/dist/components/app/entity-form.js

@@ -4,5 +4,5 @@ import { Button } from '../ui/button.js';
 import { FieldGroup } from '../ui/field.js';
 import { Spinner } from '../ui/spinner.js';
 export function EntityForm({ title, onSubmit, isSubmitting, submitError, submitLabel, onCancel, danger, children, }) {
-    return (_jsxs("form", { onSubmit: onSubmit, noValidate: true, className: "flex max-w-xl flex-col gap-6", children: [_jsx("h1", { className: "text-lg font-semibold text-foreground", children: title }), _jsx(FieldGroup, { children: children }), submitError && (_jsx(ErrorState, { error: submitError, className: "border border-dashed border-destructive/30" })), _jsxs("div", { className: `flex items-center gap-2 ${danger ? 'justify-between' : 'justify-end'}`, children: [danger, _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, disabled: isSubmitting, children: "Cancel" }), _jsxs(Button, { type: "submit", disabled: isSubmitting, children: [isSubmitting && _jsx(Spinner, { className: "size-4" }), submitLabel] })] })] })] }));
+    return (_jsxs("form", { onSubmit: onSubmit, noValidate: true, className: "flex max-w-xl flex-col gap-6", children: [_jsx("h1", { className: "type-page-title text-foreground", children: title }), _jsx(FieldGroup, { children: children }), submitError && (_jsx(ErrorState, { error: submitError, className: "border border-dashed border-destructive/30" })), _jsxs("div", { className: `flex items-center gap-2 ${danger ? 'justify-between' : 'justify-end'}`, children: [danger, _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, disabled: isSubmitting, children: "Cancel" }), _jsxs(Button, { type: "submit", disabled: isSubmitting, children: [isSubmitting && _jsx(Spinner, { className: "size-4" }), submitLabel] })] })] })] }));
 }

package/dist/components/ui/badge.d.ts

@@ -1,7 +1,7 @@
 import { useRender } from "@base-ui/react/use-render";
 import { type VariantProps } from "class-variance-authority";
 declare const badgeVariants: (props?: ({
-    variant?: "link" | "success" | "default" | "outline" | "secondary" | "ghost" | "destructive" | "warning" | "outline-success" | "outline-warning" | "outline-destructive" | "tinted-success" | "tinted-warning" | "tinted-destructive" | null | undefined;
+    variant?: "link" | "success" | "default" | "outline" | "secondary" | "ghost" | "destructive" | "warning" | "info" | "outline-success" | "outline-warning" | "outline-info" | "outline-destructive" | "tinted-success" | "tinted-warning" | "tinted-info" | "tinted-destructive" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare function Badge({ className, variant, render, ...props }: useRender.ComponentProps<"span"> & VariantProps<typeof badgeVariants>): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export { Badge, badgeVariants };

package/dist/components/ui/badge.js

@@ -10,14 +10,16 @@ const badgeVariants = cva("group/badge inline-flex h-5 w-fit shrink-0 items-cent
             destructive: "bg-destructive text-destructive-foreground focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 [a]:hover:bg-destructive/90",
             success: "bg-success text-success-foreground focus-visible:ring-success/20 dark:focus-visible:ring-success/40 [a]:hover:bg-success/90",
             warning: "bg-warning text-warning-foreground focus-visible:ring-warning/20 dark:focus-visible:ring-warning/40 [a]:hover:bg-warning/90",
+            info: "bg-info text-info-foreground focus-visible:ring-info/20 dark:focus-visible:ring-info/40 [a]:hover:bg-info/90",
             outline: "border-border text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground",
-            // Three tones x three styles. The *-text tokens, never the solid
+            // Four tones x three styles. The *-text tokens, never the solid
             // fill tokens: `border-destructive`/`text-destructive` would use
             // the shade chosen to carry white text, which is too light to read
             // against the page in light mode and too dark in dark mode. See
             // styles/theme.css and conventions/docs/design-language.md.
             "outline-success": "border-success-text text-success-text",
             "outline-warning": "border-warning-text text-warning-text",
+            "outline-info": "border-info-text text-info-text",
             "outline-destructive": "border-destructive-text text-destructive-text",
             // The fill is the solid token at low alpha (a wash of the tone),
             // while the text is the *-text shade — mixing the two is the point.
@@ -25,6 +27,7 @@ const badgeVariants = cva("group/badge inline-flex h-5 w-fit shrink-0 items-cent
             // against a near-black page.
             "tinted-success": "bg-success/15 text-success-text dark:bg-success/20",
             "tinted-warning": "bg-warning/15 text-warning-text dark:bg-warning/20",
+            "tinted-info": "bg-info/15 text-info-text dark:bg-info/20",
             "tinted-destructive": "bg-destructive/15 text-destructive-text dark:bg-destructive/20",
             ghost: "hover:bg-muted hover:text-muted-foreground dark:hover:bg-muted/50",
             link: "text-primary underline-offset-4 hover:underline",

package/dist/components/ui/table.js

@@ -33,11 +33,15 @@ function TableFooter({ className, ...props }) {
 function TableRow({ className, ...props }) {
     return (_jsx("tr", { "data-slot": "table-row", className: cn("border-b transition-colors hover:bg-muted/50 has-aria-expanded:bg-muted/50 data-[state=selected]:bg-muted", className), ...props }));
 }
+// Patched (ui-foundation): padding and header height come from the
+// --table-* density tokens in styles/theme.css instead of upstream's fixed
+// h-10 / p-2, so data-density on an ancestor retunes every table. The
+// defaults equal upstream's values.
 function TableHead({ className, ...props }) {
-    return (_jsx("th", { "data-slot": "table-head", className: cn("h-10 px-2 text-left align-middle font-medium whitespace-nowrap text-foreground [&:has([role=checkbox])]:pr-0", className), ...props }));
+    return (_jsx("th", { "data-slot": "table-head", className: cn("h-(--table-head-height) px-(--table-cell-px) text-left align-middle font-medium whitespace-nowrap text-foreground [&:has([role=checkbox])]:pr-0", className), ...props }));
 }
 function TableCell({ className, ...props }) {
-    return (_jsx("td", { "data-slot": "table-cell", className: cn("p-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0", className), ...props }));
+    return (_jsx("td", { "data-slot": "table-cell", className: cn("px-(--table-cell-px) py-(--table-cell-py) align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0", className), ...props }));
 }
 function TableCaption({ className, ...props }) {
     return (_jsx("caption", { "data-slot": "table-caption", className: cn("mt-4 text-sm text-muted-foreground", className), ...props }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.1.2",
+  "version": "3.3.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {

package/styles/index.css

@@ -44,6 +44,9 @@
     --color-warning: var(--warning);
     --color-warning-foreground: var(--warning-foreground);
     --color-warning-text: var(--warning-text);
+    --color-info: var(--info);
+    --color-info-foreground: var(--info-foreground);
+    --color-info-text: var(--info-text);
     --color-category-1: var(--category-1);
     --color-category-2: var(--category-2);
     --color-category-3: var(--category-3);
@@ -75,6 +78,34 @@
     --radius-4xl: calc(var(--radius) * 2.6);
 }
 
+/* Typography roles: one class sets size, line height and weight together,
+   from the --type-* tokens in theme.css. */
+@utility type-page-title {
+  font-size: var(--type-page-title-size);
+  line-height: var(--type-page-title-leading);
+  font-weight: var(--type-page-title-weight);
+}
+@utility type-section-title {
+  font-size: var(--type-section-title-size);
+  line-height: var(--type-section-title-leading);
+  font-weight: var(--type-section-title-weight);
+}
+@utility type-body {
+  font-size: var(--type-body-size);
+  line-height: var(--type-body-leading);
+  font-weight: var(--type-body-weight);
+}
+@utility type-label {
+  font-size: var(--type-label-size);
+  line-height: var(--type-label-leading);
+  font-weight: var(--type-label-weight);
+}
+@utility type-caption {
+  font-size: var(--type-caption-size);
+  line-height: var(--type-caption-leading);
+  font-weight: var(--type-caption-weight);
+}
+
 @layer base {
   * {
     @apply border-border outline-ring/50;

package/styles/theme.css

@@ -53,6 +53,9 @@
   --amber-700: oklch(0.555 0.163 48.998); /* white on it: 5.05 */
   --amber-800: oklch(0.47 0.14 48.998); /* on white: 7.20 */
   --amber-400: oklch(0.828 0.189 84.429); /* on near-black: 11.53 */
+  --blue-700: oklch(0.52 0.17 255); /* white on it: 5.59 */
+  --blue-800: oklch(0.45 0.15 255); /* on white: 7.54 */
+  --blue-400: oklch(0.75 0.12 255); /* on near-black: 8.90 */
   /*
    * Categorical slots. For values that differ from each other but are not
    * better or worse than each other — a genre, a team, a category. Tones
@@ -65,7 +68,8 @@
    *
    * Hues avoid the red and green bands that destructive/success already
    * spend, and the amber that warning does — a category drawn in red reads
-   * as "bad". They are ordered by distinctness, not by hue angle, so an app
+   * as "bad". The blue slots (1, 6, 8) sit near info's hue, which came
+   * later: a table using info keeps its categories off those three. They are ordered by distinctness, not by hue angle, so an app
    * using only the first three gets three obviously different colours.
    * Past about five, hue alone stops separating them and the glyph has to
    * carry the meaning; see docs/design-language.md.
@@ -95,6 +99,41 @@
 
   --radius-base: 0.625rem;
 
+  /*
+   * Typography roles (conventions/docs/design-language.md "Typography").
+   * Each role is a size, a line height and a weight, consumed only through
+   * the type-* utilities in index.css. Named type-*, not text-*: the class
+   * merger (cn, tailwind-merge) reads an unknown text-* class as a colour,
+   * so `cn('text-page-title', 'text-foreground')` would drop the title.
+   * The values are what the package and template already used, so moving
+   * onto a role changes nothing visible.
+   */
+  --type-page-title-size: 1.125rem; /* was text-lg font-semibold */
+  --type-page-title-leading: 1.75rem;
+  --type-page-title-weight: 600;
+  --type-section-title-size: 1rem;
+  --type-section-title-leading: 1.5rem;
+  --type-section-title-weight: 600;
+  --type-body-size: 0.875rem; /* text-sm: tables, forms, most UI text */
+  --type-body-leading: 1.25rem;
+  --type-body-weight: 400;
+  --type-label-size: 0.875rem; /* column headers, field labels */
+  --type-label-leading: 1.25rem;
+  --type-label-weight: 500;
+  --type-caption-size: 0.75rem; /* counts, metadata, helper text */
+  --type-caption-leading: 1rem;
+  --type-caption-weight: 400;
+
+  /*
+   * Table density (design-language.md "Density"). The table primitive's
+   * cells read these, so density is a CSS choice, not a DataTable prop: an
+   * app sets data-density on any ancestor (a wrapper, a route, <html>).
+   * The default is what the table always had.
+   */
+  --table-cell-px: 0.5rem;
+  --table-cell-py: 0.5rem;
+  --table-head-height: 2.5rem;
+
   /* Layer 2 — semantic (light) */
   --background: var(--white);
   --foreground: var(--black);
@@ -116,7 +155,9 @@
   --success-foreground: var(--white);
   --warning: var(--amber-700);
   --warning-foreground: var(--white);
-  /* The three pairs above are a SOLID fill plus its own text color, and
+  --info: var(--blue-700);
+  --info-foreground: var(--white);
+  /* The four pairs above are a SOLID fill plus its own text color, and
      nothing else. Used as text or a border on the page's own background —
      an outline badge, a tinted chip, an icon tint — a fill shade is the
      wrong value: it was picked to carry white, not to read against the
@@ -125,6 +166,7 @@
   --destructive-text: var(--red-700);
   --success-text: var(--green-800);
   --warning-text: var(--amber-800);
+  --info-text: var(--blue-800);
   /* Categorical slots — a glyph tint, never a fill behind text. */
   --category-1: var(--category-1-700);
   --category-2: var(--category-2-700);
@@ -153,6 +195,16 @@
   --sidebar-ring: var(--gray-400);
 }
 
+[data-density="compact"] {
+  --table-cell-py: 0.25rem;
+  --table-head-height: 2rem;
+}
+
+[data-density="comfortable"] {
+  --table-cell-py: 0.75rem;
+  --table-head-height: 3rem;
+}
+
 .dark {
   /* Layer 2 — semantic (dark). Only this block is remapped; Layer 1 is not. */
   --background: var(--black);
@@ -175,12 +227,15 @@
   --success-foreground: var(--white);
   --warning: var(--amber-700);
   --warning-foreground: var(--white);
+  --info: var(--blue-700);
+  --info-foreground: var(--white);
   /* Solid fills keep one shade in both themes — they always carry white
      text, so the page behind them never enters the calculation. Only the
      *-text shades flip, because those read against the page. */
   --destructive-text: var(--red-400);
   --success-text: var(--green-400);
   --warning-text: var(--amber-400);
+  --info-text: var(--blue-400);
   /* Categorical slots — lighter shades to read against the dark page. */
   --category-1: var(--category-1-400);
   --category-2: var(--category-2-400);