@ai-matrx/design-system 0.3.0 → 0.4.0

package/dist/styles.css

@@ -0,0 +1,175 @@
+/* @ai-matrx/design-system — REQUIRED structural stylesheet.
+
+   Import once at your app root, BEFORE or AFTER your own CSS (the cascade is
+   settled by layers, not by order — see below):
+
+     import "@ai-matrx/design-system/tokens.css";  // default token VALUES
+     import "@ai-matrx/design-system/styles.css";  // this file — structure
+
+   WHAT LIVES HERE (C26): every CSS rule this package's components REQUIRE to
+   render correctly — layout, blur/border mechanics, mask geometry, safe-area
+   padding, mobile density. Colour and brand enter ONLY through the semantic
+   token vocabulary (`var(--…)`); this file hardcodes no colour. Token VALUES
+   ship separately in `tokens.css` and are meant to be overridden by the host.
+
+   THE CASCADE CONTRACT
+   --------------------
+   Rules that must behave like ordinary utilities (so a host utility on the
+   same element still wins, exactly as it did when these lived in the host's
+   `@layer components` / `@layer utilities`) live in the
+   `matrx-design-system` layer. A host puts that layer LOWEST by declaring the
+   order once, as the FIRST line of its Tailwind/CSS entry:
+
+     @layer matrx-design-system-tokens, matrx-design-system;
+     @import "tailwindcss";
+
+   Rules that must beat utilities (the scroll-fade mask, the mobile-sheet
+   density restatement) are UNLAYERED on purpose, matching how they were
+   authored in matrx-frontend's globals.css. Unlayered CSS beats every layered
+   rule regardless of specificity — that is the only way to re-scale
+   utility-set font sizes, and the only way a mask survives a `mask-*` reset.
+
+   Extracted from matrx-frontend `app/globals.css` (the tap-target precedent);
+   the host originals were deleted in the same session that shipped this file.
+   ========================================================================= */
+
+@layer matrx-design-system {
+  /* -----------------------------------------------------------------------
+     shadow-input — the Input family's resting elevation.
+     Tailwind v4 hosts also generate a `.shadow-input` utility from a
+     `--shadow-input` theme entry; that generated utility sits in
+     `@layer utilities` and therefore WINS over this one, with the identical
+     value. This rule exists so the Input renders correctly in a host that has
+     no such theme entry (a fresh app, a non-Tailwind app).
+     ----------------------------------------------------------------------- */
+  .shadow-input {
+    box-shadow: var(--shadow-input);
+  }
+
+  /* -----------------------------------------------------------------------
+     pb-safe — safe-area bottom padding (BottomSheet body/footer, CommandDialog
+     mobile sheet). max() guarantees a minimum padding even when the inset is
+     0 (env() resolves to 0 on non-notched devices and when viewport-fit=cover
+     is absent).
+     ----------------------------------------------------------------------- */
+  .pb-safe {
+    padding-bottom: max(0.75rem, env(safe-area-inset-bottom, 0px));
+  }
+
+  /* -----------------------------------------------------------------------
+     matrx-glass-thin-border — the glass chrome the BottomSheet close control
+     and drag affordances wear. The STRUCTURE (tinted fill, backdrop blur +
+     saturate, elevation, thin stroke) is package-owned; every colour, blur
+     radius and stroke width resolves from a --matrx-glass-* token, so a host
+     re-tints the whole system by redefining those values and nothing else.
+
+     matrx-frontend authored these with Tailwind's `@apply bg-glass
+     shadow-glass backdrop-blur-glass backdrop-saturate-glass`, whose theme
+     aliases are `var(--matrx-glass-bg)` / `-shadow` / `-blur` / `-saturate`.
+     Expanded to the leaf tokens here so the rule needs no Tailwind.
+     ----------------------------------------------------------------------- */
+  .matrx-glass-thin-border {
+    background-color: var(--matrx-glass-bg);
+    box-shadow: var(--matrx-glass-shadow);
+    -webkit-backdrop-filter: blur(var(--matrx-glass-blur))
+      saturate(var(--matrx-glass-saturate));
+    backdrop-filter: blur(var(--matrx-glass-blur))
+      saturate(var(--matrx-glass-saturate));
+    border: var(--matrx-glass-border-width-thin) solid
+      var(--matrx-glass-border-color);
+  }
+  .matrx-glass-thin-border:hover {
+    background-color: var(--matrx-glass-bg-hover);
+  }
+  .matrx-glass-thin-border:active {
+    background-color: var(--matrx-glass-bg-active);
+  }
+  /* Segmented pills: direct child segments own hover — don't lift the shell. */
+  .matrx-glass-thin-border:has(> a:hover),
+  .matrx-glass-thin-border:has(> a:active) {
+    background-color: var(--matrx-glass-bg);
+  }
+}
+
+/* ────────────────────────────────────────────────────────────────────────
+   Scroll fade — the "there is more below" cue. UNLAYERED on purpose.
+   Driven by `useScrollFade`, which sets the data attributes ONLY on edges
+   that actually overflow. A hard-clipped last row reads as "finished" and the
+   user never scrolls; a permanent fade makes a non-scrolling list's last item
+   look broken. Hence: measured, not assumed.
+
+   mask-image is used (not an overlay element) so the fade works over any
+   background — popovers, drawers, cards — with no extra DOM and no
+   pointer-event interception.
+   ──────────────────────────────────────────────────────────────────────── */
+.matrx-scroll-fade[data-fade-bottom] {
+  mask-image: linear-gradient(
+    to bottom,
+    black calc(100% - 2rem),
+    transparent 100%
+  );
+}
+.matrx-scroll-fade[data-fade-top] {
+  mask-image: linear-gradient(
+    to top,
+    black calc(100% - 2rem),
+    transparent 100%
+  );
+}
+.matrx-scroll-fade[data-fade-top][data-fade-bottom] {
+  mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    black 2rem,
+    black calc(100% - 2rem),
+    transparent 100%
+  );
+}
+
+/* ────────────────────────────────────────────────────────────────────────
+   .matrx-mobile-sheet — ONE mobile density for any desktop panel hosted in a
+   bottom sheet (TabbedBottomSheet sets it; see that file's header).
+
+   The panels a sheet hosts are usually the SAME components a desktop window
+   renders, authored at desktop density — text-[9px]…text-xs and h-7 rows. On
+   a phone that is unreadable, untappable, and inconsistent with the 16px
+   index list one tap away, so the sheet restates the scale once, here,
+   instead of every panel growing an `isMobile` branch (which is what made
+   these surfaces diverge in the first place).
+
+   Deliberately UNLAYERED: Tailwind utilities live in @layer utilities, and
+   unlayered CSS beats every layered rule regardless of specificity — the only
+   way to re-scale utility-set font sizes. Scoped to this class, so the blast
+   radius is exactly the sheet. Font size and control height ONLY — never
+   colour, spacing, or layout.
+
+   Fields are forced to 16px because anything smaller makes iOS Safari zoom the
+   page on focus, which is itself a "the panel resized" bug.
+   ──────────────────────────────────────────────────────────────────────── */
+.matrx-mobile-sheet .text-\[9px\],
+.matrx-mobile-sheet .text-\[10px\],
+.matrx-mobile-sheet .text-\[11px\] {
+  font-size: 0.8125rem;
+  line-height: 1.15rem;
+}
+.matrx-mobile-sheet .text-xs {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+}
+.matrx-mobile-sheet .text-sm {
+  font-size: 0.9375rem;
+  line-height: 1.375rem;
+}
+.matrx-mobile-sheet input,
+.matrx-mobile-sheet textarea,
+.matrx-mobile-sheet select,
+.matrx-mobile-sheet [contenteditable="true"] {
+  font-size: 16px;
+}
+/* h-7 rows (list rows, search fields) are below the 44pt touch target. Raise
+   the floor with min-height — it wins over the utility's height without
+   unpinning it. Square icon buttons (h-7 w-7) are excluded so they stay
+   square. */
+.matrx-mobile-sheet .h-7:not([class*="w-7"]) {
+  min-height: 2.25rem;
+}

package/dist/theme.css

@@ -0,0 +1,56 @@
+/* @ai-matrx/design-system — Tailwind v4 registration (OPTIONAL, Tailwind hosts).
+
+   The package's components are authored in semantic utility classes
+   (`bg-background`, `text-muted-foreground`, `border-border`, …). On a Tailwind
+   v4 host those utilities only exist if (a) the package's built output is a
+   scan source and (b) the semantic colours are mapped in `@theme`. This file is
+   both, so a fresh app is one line from drop-in:
+
+     @import "tailwindcss";
+     @import "@ai-matrx/design-system/theme.css";
+
+   It must be `@import`ed from your Tailwind ENTRY stylesheet (so Tailwind
+   processes it) — never `import`ed from JavaScript; `@theme` is a Tailwind
+   at-rule, not CSS. `tokens.css` (the default VALUES) comes along with it.
+
+   A host that already maps this vocabulary in its own `@theme` — matrx-frontend
+   does, as a superset with its own brand — does not need this file. Nothing
+   here is a brand: every mapping points back at a token whose value the host
+   owns. */
+
+@source "./";
+
+@import "./tokens.css";
+
+@theme inline {
+  --color-background: hsl(var(--background));
+  --color-foreground: hsl(var(--foreground));
+  --color-card: hsl(var(--card));
+  --color-card-foreground: hsl(var(--card-foreground));
+  --color-popover: hsl(var(--popover));
+  --color-popover-foreground: hsl(var(--popover-foreground));
+  --color-primary: hsl(var(--primary));
+  --color-primary-foreground: hsl(var(--primary-foreground));
+  --color-secondary: hsl(var(--secondary));
+  --color-secondary-foreground: hsl(var(--secondary-foreground));
+  --color-muted: hsl(var(--muted));
+  --color-muted-foreground: hsl(var(--muted-foreground));
+  --color-accent: hsl(var(--accent));
+  --color-accent-foreground: hsl(var(--accent-foreground));
+  --color-destructive: hsl(var(--destructive));
+  --color-destructive-foreground: hsl(var(--destructive-foreground));
+  --color-success: hsl(var(--success));
+  --color-success-foreground: hsl(var(--success-foreground));
+  --color-warning: hsl(var(--warning));
+  --color-warning-foreground: hsl(var(--warning-foreground));
+  --color-info: hsl(var(--info));
+  --color-border: hsl(var(--border));
+  --color-input: hsl(var(--input));
+  --color-ring: hsl(var(--ring));
+}
+
+/* NOTE: no `--shadow-*` entry for the input elevation. `styles.css` ships the
+   `.shadow-input` rule itself (reading `--shadow-input` from tokens.css), so
+   adding a Tailwind theme entry of the same name here would only define the
+   token in terms of itself. A host that wants `shadow-input` composable with
+   ring utilities declares `--shadow-input` in its own `@theme`, which wins. */

package/dist/tokens.css

@@ -0,0 +1,156 @@
+/* @ai-matrx/design-system — DEFAULT token values.
+
+   Import once at your app root, before `styles.css`:
+
+     import "@ai-matrx/design-system/tokens.css";
+     import "@ai-matrx/design-system/styles.css";
+
+   WHY THIS FILE EXISTS (C26): the package is opinionated about the token
+   CONTRACT — every colour its components and its structural CSS reference
+   resolves from one of the custom properties below — but the token VALUES are
+   host-owned. This sheet ships a neutral, sensible default for every one of
+   them so the package renders correctly UNTHEMED in a fresh app. It is not a
+   brand: hosts override any subset with their own values and this file gets
+   out of the way.
+
+   HOW OVERRIDING WORKS
+   --------------------
+   Every default is declared inside `@layer matrx-design-system-tokens`, and
+   the host declares that layer FIRST so it sits at the BOTTOM of the cascade:
+
+     @layer matrx-design-system-tokens, matrx-design-system;   ← first line
+     @import "tailwindcss";
+
+   With that one line, ANY host declaration of the same token wins — layered
+   (`@layer base { :root { --primary: … } }`) or unlayered, earlier in the file
+   or later, higher specificity or lower. Without it, layer order falls back to
+   first-appearance order and a host whose own tokens are layered could lose to
+   these defaults; declare it and the question never arises.
+
+   COLOUR FORMAT: bare HSL channels (`240 5% 96%`), consumed as
+   `hsl(var(--background))`. That is the shadcn/Tailwind-v4 convention the
+   whole AI Matrx vocabulary uses, and it is what makes `bg-primary/15` style
+   alpha compositing work.
+
+   TAILWIND v4 HOSTS: these raw values are only half the story — the semantic
+   utilities (`bg-background`, `text-muted-foreground`, …) also need the theme
+   mapping. `@import "@ai-matrx/design-system/theme.css";` from your Tailwind
+   entry does that (and registers the package's dist as a scan source).
+   ========================================================================= */
+
+@layer matrx-design-system-tokens {
+  :root {
+    /* Surfaces */
+    --background: 0 0% 100%;
+    --foreground: 240 10% 4%;
+    --card: 0 0% 100%;
+    --card-foreground: 240 10% 4%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 240 10% 4%;
+
+    /* Brand roles — deliberately neutral. Override these first. */
+    --primary: 240 6% 10%;
+    --primary-foreground: 0 0% 98%;
+    --secondary: 240 5% 96%;
+    --secondary-foreground: 240 6% 10%;
+
+    /* Quiet roles */
+    --muted: 240 5% 96%;
+    --muted-foreground: 240 4% 46%;
+    --accent: 240 5% 96%;
+    --accent-foreground: 240 6% 10%;
+
+    /* Status roles */
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 98%;
+    --success: 142 76% 36%;
+    --success-foreground: 144 70% 98%;
+    --warning: 38 92% 50%;
+    --warning-foreground: 48 96% 98%;
+    --info: 200 98% 39%;
+
+    /* Lines and focus */
+    --border: 240 6% 90%;
+    --input: 240 6% 90%;
+    --ring: 240 5% 65%;
+
+    /* Input elevation — consumed by the `.shadow-input` rule in styles.css
+       and by the Tailwind `shadow-input` utility on Tailwind hosts. */
+    --shadow-input:
+      0px 2px 3px -1px rgba(0, 0, 0, 0.1), 0px 1px 0px 0px rgba(25, 28, 33, 0.02),
+      0px 0px 0px 1px rgba(25, 28, 33, 0.08);
+
+    /* Overlay scrims — the dimming behind Sheet / BottomSheet / CommandDialog.
+       Separate from the colour roles on purpose: a scrim is a neutral
+       darkening of whatever is behind it, not a brand colour. */
+    --matrx-overlay-scrim: rgb(0 0 0 / 0.8);
+    --matrx-overlay-scrim-soft: rgb(0 0 0 / 0.2);
+    /* The drawer (BottomSheet) scrim is deliberately far lighter: the sheet
+       covers most of a phone screen already, so a heavy scrim reads as a
+       broken page rather than as depth. */
+    --matrx-overlay-scrim-drawer: rgb(0 0 0 / 0.08);
+    /* Hairline divider inside glass sheets (BottomSheet footer). */
+    --matrx-sheet-divider: rgb(255 255 255 / 0.06);
+
+    /* Matrx Glass — the physical-material tokens the glass chrome resolves
+       from. Every one is consumed by `.matrx-glass-thin-border` in
+       styles.css; redefine them to re-tint the whole glass system. */
+    --matrx-glass-bg: rgba(210, 225, 255, 0.14);
+    --matrx-glass-bg-hover: rgba(210, 225, 255, 0.22);
+    --matrx-glass-bg-active: rgba(210, 225, 255, 0.32);
+    --matrx-glass-border-color: rgba(180, 205, 255, 0.7);
+    --matrx-glass-border-width: 3.5px;
+    --matrx-glass-border-width-thin: 1.5px;
+    --matrx-glass-blur: 4px;
+    --matrx-glass-saturate: 1.8;
+    --matrx-glass-shadow:
+      0 1px 3px rgba(0, 0, 0, 0.06), 0 1px 2px rgba(0, 0, 0, 0.04);
+    --matrx-glass-shadow-lg:
+      0 4px 16px rgba(0, 0, 0, 0.08), 0 2px 6px rgba(0, 0, 0, 0.04);
+  }
+
+  /* Dark theme. Matches the `.dark`-class convention (Tailwind v4 hosts wire
+     it with `@custom-variant dark (&:where(.dark, .dark *))`); a host using a
+     different dark switch redeclares these under its own selector. */
+  .dark {
+    --background: 240 10% 4%;
+    --foreground: 0 0% 98%;
+    --card: 240 10% 4%;
+    --card-foreground: 0 0% 98%;
+    --popover: 240 10% 4%;
+    --popover-foreground: 0 0% 98%;
+
+    --primary: 0 0% 98%;
+    --primary-foreground: 240 6% 10%;
+    --secondary: 240 4% 16%;
+    --secondary-foreground: 0 0% 98%;
+
+    --muted: 240 4% 16%;
+    --muted-foreground: 240 5% 65%;
+    --accent: 240 4% 16%;
+    --accent-foreground: 0 0% 98%;
+
+    --destructive: 0 72% 60%;
+    --destructive-foreground: 0 86% 97%;
+    --success: 142 69% 58%;
+    --success-foreground: 144 70% 98%;
+    --warning: 48 96% 58%;
+    --warning-foreground: 48 96% 98%;
+    --info: 200 90% 60%;
+
+    --border: 240 4% 16%;
+    --input: 240 4% 16%;
+    --ring: 240 5% 34%;
+
+    --matrx-overlay-scrim-soft: rgb(0 0 0 / 0.3);
+
+    --matrx-glass-bg: rgba(180, 200, 255, 0.05);
+    --matrx-glass-bg-hover: rgba(180, 200, 255, 0.09);
+    --matrx-glass-bg-active: rgba(180, 200, 255, 0.13);
+    --matrx-glass-border-color: rgba(255, 255, 255, 0.07);
+    --matrx-glass-shadow:
+      0 1px 3px rgba(0, 0, 0, 0.2), 0 1px 2px rgba(0, 0, 0, 0.12);
+    --matrx-glass-shadow-lg:
+      0 4px 16px rgba(0, 0, 0, 0.25), 0 2px 6px rgba(0, 0, 0, 0.12);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/design-system",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "AI Matrx semantic React primitives shared across Vite, Next.js, desktop, and customer-built applications.",
   "type": "module",
   "license": "MIT",
@@ -30,9 +30,13 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./styles.css": "./dist/styles.css",
+    "./tokens.css": "./dist/tokens.css",
+    "./theme.css": "./dist/theme.css",
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@ai-matrx/kit": "^0.7.3",
     "@radix-ui/react-dialog": "^1.1.17",
     "@radix-ui/react-label": "^2.1.8",
     "@radix-ui/react-popover": "^1.1.17",
@@ -47,7 +51,6 @@
     "vaul": "^1.1.2"
   },
   "peerDependencies": {
-    "@ai-matrx/kit": ">=0.5.1",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0"
   },
@@ -63,8 +66,7 @@
     "react-dom": "^19.1.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.6",
-    "@ai-matrx/kit": "0.5.1"
+    "vitest": "^4.1.6"
   },
   "publishConfig": {
     "access": "public",
@@ -73,7 +75,9 @@
   "engines": {
     "node": ">=20"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "*.css"
+  ],
   "scripts": {
     "build": "tsup && node ./scripts/stamp-client-boundary.mjs",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",