@ai-matrx/design-system 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## 0.4.0 — 2026-08-30
+
+**The package ships its CSS.** Closes the C26 clause of the all-inclusive
+retrofit row: the package shipped ZERO stylesheets while three host-owned CSS
+contracts were required for its components to render correctly. Any consumer
+that was not matrx-frontend got a broken scroll cue, an unstyled glass control,
+a flat input, and desktop-density text inside a phone sheet.
+
+New exports:
+
+- **`./styles.css` — REQUIRED structural CSS.** Extracted from matrx-frontend
+  `app/globals.css` (the tap-target precedent): the `.matrx-scroll-fade`
+  mask geometry (`useScrollFade`), the `.matrx-mobile-sheet` mobile density
+  restatement (`TabbedBottomSheet`), `.matrx-glass-thin-border` (BottomSheet
+  chrome), `.pb-safe`, `.shadow-input`. Zero hardcoded colour — every colour
+  resolves from a token, asserted by test and by the tarball canary.
+- **`./tokens.css` — DEFAULT token values.** A neutral, sensible default for
+  every token the components and the structural CSS read, light and dark, so
+  the package renders correctly UNTHEMED in a fresh app. Not a brand: values
+  are host-owned and every default sits in the `matrx-design-system-tokens`
+  layer so any host declaration wins.
+- **`./theme.css` — optional Tailwind v4 registration.** Maps the semantic
+  colour utilities onto the tokens and registers the package build as a
+  `@source`, so a fresh Tailwind app is one `@import` from drop-in.
+
+Colour sweep (hardcoded colour in components is banned):
+
+- `Input` — `text-black dark:text-white` → `text-foreground`;
+  `placeholder:text-neutral-400` → `placeholder:text-muted-foreground` (the
+  paired `dark:placeholder-text-neutral-600` was a typo'd class that never
+  existed and is gone); `focus-visible:ring-neutral-400/600` →
+  `focus-visible:ring-ring`; the dark autofill fill-colour now follows
+  `--foreground`. The dark elevation `shadow-[0px_0px_1px_1px_var(--neutral-700)]`
+  referenced a token defined nowhere, so it computed to no shadow — replaced by
+  an honest `dark:shadow-none`, which renders identically.
+- `Badge` — `info` variant `border-blue-200 bg-blue-100 text-blue-800` →
+  `border-info/30 bg-info/15 text-info`; `error` variant → the same
+  `destructive` tokens its twin variant already used.
+- `ScoreRing` — `scoreRingColorClasses` / `scoreAccentBgClasses` now return
+  `success` / `warning` / `destructive` token classes instead of
+  `green-500` / `orange-500` / `red-500`.
+- Overlay scrims and the glass sheet divider are tokens
+  (`--matrx-overlay-scrim`, `--matrx-overlay-scrim-soft`,
+  `--matrx-overlay-scrim-drawer`, `--matrx-sheet-divider`) instead of
+  `bg-black/80`, `bg-black/20 dark:bg-black/30`, an inline `rgba(0,0,0,0.08)`,
+  and `border-white/[0.06]`.
+
+Gate: the tarball canary now asserts all three sheets ship at the exact paths
+their exports point to, that `styles.css` carries each contract rule and no
+hardcoded colour, and that `tokens.css` defaults every token in both themes.
+A new `styles.test.ts` fails the build if a component ever references a bare
+class with no shipped rule, reads a token with no default, or reintroduces a
+palette colour.
+
+### Consumer action
+
+1. **Import the two sheets at your app root** (`styles.css` is required —
+   without it the scroll fade, glass chrome, safe-area padding and input
+   elevation are missing):
+
+   ```tsx
+   import "@ai-matrx/design-system/tokens.css";
+   import "@ai-matrx/design-system/styles.css";
+   ```
+
+2. **Declare the layer order once**, as the first line of your Tailwind/CSS
+   entry, so the package's default token values stay below your own:
+
+   ```css
+   @layer matrx-design-system-tokens, matrx-design-system;
+   ```
+
+3. **Delete your host copies of the moved rules** — `.matrx-scroll-fade[…]`,
+   the `.matrx-mobile-sheet` block, `.matrx-glass-thin-border` (+ its
+   `:hover` / `:active` / `:has(> a:…)` states). They now ship in the package;
+   keeping both means two sources of truth. Rules that are members of a host
+   utility family (`.pb-safe` beside `pt-safe`/`mb-safe`/`mt-safe`) and
+   Tailwind-generated `.shadow-input` legitimately stay host-side — the
+   package versions sit in a lower layer and lose to them by design.
+4. **If you consumed the ScoreRing colour helpers' return strings**, they are
+   now `text-success` / `text-warning` / `text-destructive` (and the `bg-`
+   twins). Define those semantic colours in your theme, or map them.
+5. **A host that already maps the semantic colour vocabulary in its own
+   `@theme` does not need `theme.css`** — importing it would duplicate the
+   mapping.
+
 ## 0.3.1 — 2026-08-30
 
 - `@ai-matrx/kit` is now a REAL dependency (`^0.7.3`) instead of a peer

package/README.md

@@ -13,18 +13,57 @@ import { Badge, Button } from "@ai-matrx/design-system";
 <Badge variant="success">Ready</Badge>
 ```
 
-The package intentionally does not ship product colors. Hosts define the normal Tailwind semantic tokens (`primary`, `background`, `border`, `muted`, `success`, and `warning`), so one component follows each product's theme without forking behavior. A few ported components additionally reference host-owned CSS contracts and degrade gracefully without them: the glass tokens/utilities used by the BottomSheet family, the `.matrx-scroll-fade` styling for `useScrollFade`, and the `shadow-input` utility.
-
 Host-shaped systems are injected, never imported: wrap subtrees in `PortalContainerProvider` to point nested Popover portals at a dialog or popout body, and hand `OverflowToolbar` your menu and tooltip systems through its `renderOverflowMenu` / `renderTooltip` props. `@ai-matrx/kit` is a real dependency (installed automatically).
 
-Tailwind CSS v4 ignores `node_modules` by default. Registry consumers must register the package build beside their Tailwind import:
+## Styling — the package ships its CSS, the host owns the values
+
+The package is **opinionated about the token contract and ships every rule its
+components need to work**; it is **not** opinionated about your colours.
+
+```tsx
+// app root, once
+import "@ai-matrx/design-system/tokens.css"; // default token VALUES  — override these
+import "@ai-matrx/design-system/styles.css"; // structural CSS        — required
+```
+
+```css
+/* your Tailwind/CSS entry — FIRST line, before @import "tailwindcss" */
+@layer matrx-design-system-tokens, matrx-design-system;
+```
+
+- **`styles.css` (required)** — every rule the components need to render right:
+  the `.matrx-scroll-fade` mask geometry behind `useScrollFade`, the
+  `.matrx-mobile-sheet` density restatement `TabbedBottomSheet` sets, the
+  `.matrx-glass-thin-border` chrome, `.pb-safe`, `.shadow-input`. It hardcodes
+  no colour: every colour resolves from a token.
+- **`tokens.css` (default values)** — a neutral, sensible default for every
+  token the package reads, in both themes, so a fresh app renders correctly
+  **unthemed**. This is not a brand.
+- **`theme.css` (Tailwind v4 hosts, optional)** —
+  `@import "@ai-matrx/design-system/theme.css";` from your Tailwind entry maps
+  the semantic colour utilities (`bg-background`, `text-muted-foreground`, …)
+  onto those tokens and registers the package build as a scan source. A host
+  that already maps this vocabulary (matrx-frontend does, as a branded
+  superset) skips this file and keeps its own.
+
+**Overriding with your brand.** Redeclare any token — `--primary`,
+`--background`, the `--matrx-glass-*` material, the overlay scrims — anywhere
+in your own CSS. The package defaults live in the
+`matrx-design-system-tokens` layer, and the one-line `@layer` declaration
+above puts that layer at the bottom of the cascade, so **any** host
+declaration wins: layered or unlayered, before or after, whatever the
+specificity. Declare the layer order once and the question never arises.
+
+Tailwind CSS v4 ignores `node_modules` by default, so a host that does not
+import `theme.css` still registers the package build beside its Tailwind
+import:
 
 ```css
 @import "tailwindcss";
 @source "../node_modules/@ai-matrx/design-system/dist";
 ```
 
-Workspace consumers point `@source` at `apps/shared/design-system/src`. This is required package setup, not an optional styling enhancement.
+Workspace consumers point `@source` at `apps/shared/design-system/src`.
 
 ## Release gate
 

package/dist/index.cjs

@@ -122,8 +122,8 @@ var badgeVariants = (0, import_class_variance_authority.cva)(
         outline: "border-border text-foreground",
         success: "border-transparent bg-success/15 text-success",
         warning: "border-transparent bg-warning/15 text-warning",
-        info: "border-blue-200 bg-blue-100 text-blue-800",
-        error: "border-transparent bg-red-500/15 text-red-700 dark:text-red-400",
+        info: "border-info/30 bg-info/15 text-info",
+        error: "border-transparent bg-destructive/15 text-destructive",
         neutral: "border-border bg-muted text-muted-foreground"
       }
     },
@@ -328,8 +328,8 @@ function BottomSheet({
     /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
       import_vaul.Drawer.Overlay,
       {
-        className: cn("fixed inset-0 z-50 bg-black/80", "fixed inset-0 z-50"),
-        style: { background: "rgba(0, 0, 0, 0.08)" }
+        className: cn("fixed inset-0 z-50 bg-[var(--matrx-overlay-scrim)]", "fixed inset-0 z-50"),
+        style: { background: "var(--matrx-overlay-scrim-drawer)" }
       }
     ),
     /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(
@@ -406,7 +406,7 @@ function BottomSheetFooter({
     "div",
     {
       className: cn(
-        "flex-shrink-0 px-4 py-3 pb-safe border-t border-white/[0.06]",
+        "flex-shrink-0 px-4 py-3 pb-safe border-t border-[var(--matrx-sheet-divider)]",
         className
       ),
       children
@@ -530,7 +530,7 @@ var CommandDialogContent = React5.forwardRef(({ className, children, container,
     isModal ? /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
       DialogPrimitive.Overlay,
       {
-        className: "fixed inset-0 z-[10000] bg-black/20 dark:bg-black/30 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0"
+        className: "fixed inset-0 z-[10000] bg-[var(--matrx-overlay-scrim-soft)] data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0"
       }
     ) : null,
     /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)(
@@ -1124,14 +1124,14 @@ function EditableLabel({
 var React7 = __toESM(require("react"), 1);
 var import_jsx_runtime11 = require("react/jsx-runtime");
 var getVariantStyles = (variant = "default") => {
-  const baseStyles = `flex h-10 w-full border border-border bg-background text-black dark:text-white shadow-input rounded-md px-3 py-2 text-sm file:border-0 file:bg-transparent
-    file:text-sm file:font-medium placeholder:text-neutral-400 dark:placeholder-text-neutral-600
-    focus-visible:outline-none focus-visible:ring-[2px] focus-visible:ring-neutral-400 dark:focus-visible:ring-neutral-600
+  const baseStyles = `flex h-10 w-full border border-border bg-background text-foreground shadow-input rounded-md px-3 py-2 text-sm file:border-0 file:bg-transparent
+    file:text-sm file:font-medium placeholder:text-muted-foreground
+    focus-visible:outline-none focus-visible:ring-[2px] focus-visible:ring-ring
     disabled:cursor-not-allowed disabled:opacity-50
-    dark:shadow-[0px_0px_1px_1px_var(--neutral-700)]
+    dark:shadow-none
     transition duration-400
     [&:-webkit-autofill]:bg-background [&:-webkit-autofill]:shadow-[0_0_0_1000px_hsl(var(--background))_inset] [&:-webkit-autofill]:[caret-color:currentColor]
-    dark:[&:-webkit-autofill]:shadow-[0_0_0_1000px_hsl(var(--background))_inset] dark:[&:-webkit-autofill]:[-webkit-text-fill-color:white]
+    dark:[&:-webkit-autofill]:shadow-[0_0_0_1000px_hsl(var(--background))_inset] dark:[&:-webkit-autofill]:[-webkit-text-fill-color:hsl(var(--foreground))]
     [&:-webkit-autofill:hover]:shadow-[0_0_0_1000px_hsl(var(--background))_inset] [&:-webkit-autofill:focus]:shadow-[0_0_0_1000px_hsl(var(--background))_inset]`;
   switch (variant) {
     case "destructive":
@@ -1410,15 +1410,15 @@ var DEFAULT_SCORE_THRESHOLDS = {
 };
 function scoreRingColorClasses(pct, thresholds = DEFAULT_SCORE_THRESHOLDS) {
   if (pct === null) return "text-muted-foreground";
-  if (pct >= thresholds.good) return "text-green-500";
-  if (pct >= thresholds.warning) return "text-orange-500";
-  return "text-red-500";
+  if (pct >= thresholds.good) return "text-success";
+  if (pct >= thresholds.warning) return "text-warning";
+  return "text-destructive";
 }
 function scoreAccentBgClasses(pct, thresholds = DEFAULT_SCORE_THRESHOLDS) {
   if (pct === null) return "bg-muted-foreground/30";
-  if (pct >= thresholds.good) return "bg-green-500";
-  if (pct >= thresholds.warning) return "bg-orange-500";
-  return "bg-red-500";
+  if (pct >= thresholds.good) return "bg-success";
+  if (pct >= thresholds.warning) return "bg-warning";
+  return "bg-destructive";
 }
 function ScoreRing({
   pct,
@@ -1725,7 +1725,7 @@ var SheetOverlay = React12.forwardRef(({ className, ...props }, ref) => /* @__PU
   SheetPrimitive.Overlay,
   {
     className: cn(
-      "fixed inset-0 z-50 bg-black/80 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      "fixed inset-0 z-50 bg-[var(--matrx-overlay-scrim)] data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
       className
     ),
     ...props,