@tristan2828/ui-foundation 3.1.2 → 3.2.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/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 —

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.1.2",
+  "version": "3.2.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);

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.
@@ -116,7 +120,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 +131,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);
@@ -175,12 +182,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);