@umituz/web-dashboard 4.0.0 → 4.1.1

package/README.md

@@ -14,11 +14,8 @@ Your bundler compiles it alongside your app; no prebuilt bundle ships.
 
 - **Billing moved to [@umituz/web-polar-payment](https://github.com/umituz/web-polar-payment)**
   under the `./portal` entry point. The old `./billing*` entry points are gone.
-- **`@umituz/web-design-system` is no longer a dependency.** The primitives
-  (`Button`, `Input`, `Checkbox`, `Skeleton`, `cn`) live in `./primitives`.
 - **Styling is shipped, not assumed.** Import `@umituz/web-dashboard/styles.css`
-  (and optionally `tokens.css`) once; all components use `udb-*` BEM classes.
-  Tailwind, design-system tokens and utility classes are gone from the package.
+  once; all components use `udb-*` BEM classes.
 - **No i18n runtime.** `react-i18next` is out; hosts bridge their own `t` via
   `<DashboardI18nProvider t={i18n.t}>` (see below). Without a provider,
   keys humanize to readable English.
@@ -30,6 +27,31 @@ Your bundler compiles it alongside your app; no prebuilt bundle ships.
   texora/visora pattern (one module list drives routes + nav + guards) as
   reusable building blocks.
 
+## What changed in 4.1
+
+- **The design system is back — for real this time.** 4.0 dropped
+  `@umituz/web-design-system` entirely; 4.1 makes it a runtime dependency
+  again and actually renders it:
+  - `./primitives` (`Button`, `Input`, `Checkbox`, `Skeleton`, `cn`) are thin
+    adapters that **delegate to the DS components** — the dashboard prop API
+    is unchanged, call sites need zero edits.
+  - `UserManagementTable` renders the DS `DataTable`; `MetricCard` composes
+    the DS `MetricCard`; `AnalyticsCard` is built on DS `Card` primitives.
+  - `styles.css` imports `@umituz/web-design-system/styles.css` transitively
+    (Tailwind v4 precompiled) — hosts still import only the dashboard
+    stylesheet.
+- **`--u-*` tokens are now bridges.** `tokens.css` maps every color/radius/
+  shadow token to the DS `--color-*`/`--radius-*` variables (with the old
+  literal as fallback). Override either side; dark mode (`data-udb-theme="dark"`)
+  now sets DS variables and the bridge flows through.
+- **Primitive base CSS is gone from `dashboard.css`.** Only dashboard-owned
+  modifiers remain (`udb-btn__spinner`, `udb-input--error/--with-toggle`,
+  `udb-skeleton--*`, `udb-card--sm/--lg`, `udb-table` for the permission
+  matrix); bases come from the DS stylesheet.
+- **Peer footprint**: pulling the dashboard in transitively installs the DS's
+  Radix UI peers (npm 7+ handles this automatically; only imported components
+  end up in the bundle).
+
 ## Installation
 
 ```bash
@@ -38,7 +60,7 @@ import "@umituz/web-dashboard/styles.css";
 ```
 
 Peers: `react` + `react-dom` (^18 or ^19) and `react-router-dom` (^6 or ^7).
-Runtime deps: `clsx` + `lucide-react`. Nothing else.
+Runtime deps: `@umituz/web-design-system` + `lucide-react`. Nothing else.
 
 ### Tailwind hosts
 
@@ -48,8 +70,12 @@ resets: import the package stylesheet **after** your base layer.
 
 ### Theming & dark mode
 
-Override the `--u-*` custom properties (see `tokens.css` for the full list).
-Dark mode is host-driven: put `data-udb-theme="dark"` on any ancestor.
+`tokens.css` bridges every `--u-*` token to a design-system variable
+(`--u-color-primary: var(--color-primary, #2563eb)`), so you can theme two
+ways: override the `--u-*` bridge heads, or set the DS `--color-*`/`--radius-*`
+variables (e.g. from your own Tailwind `@theme`). Dark mode is host-driven:
+put `data-udb-theme="dark"` on any ancestor — the dashboard dark block sets
+the DS variables and both layers switch together.
 
 ## Entry points
 
@@ -175,7 +201,7 @@ readably. The per-domain key catalogs are the string contract:
 import { AUTH_KEYS } from "@umituz/web-dashboard/auth";
 import { ANALYTICS_KEYS } from "@umituz/web-dashboard/analytics";
 import { ONBOARDING_KEYS } from "@umituz/web-dashboard/onboarding";
-import { SETTINGS_ADMIN_KEYS } from "@umituz/web-dashboard/settings/utils/i18nKeys";
+import { SETTINGS_ADMIN_KEYS } from "@umituz/web-dashboard/settings/utils";
 import { PERMISSIONS_KEYS } from "@umituz/web-dashboard/permissions";
 import { SESSION_KEYS } from "@umituz/web-dashboard/session";
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-dashboard",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "description": "Installable app skeleton for the fleet — layouts, auth, onboarding, analytics (dependency-free SVG charts), calendar, i18n injection, permissions/session/module registry; ships its own udb-* stylesheet and --u-* tokens",
   "type": "module",
   "main": "./src/index.ts",
@@ -71,10 +71,11 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "dependencies": {
-    "clsx": "^2.1.1",
+    "@umituz/web-design-system": "^4.0.2",
     "lucide-react": "^0.577.0"
   },
   "devDependencies": {
+    "@types/node": "^22.20.5",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@typescript-eslint/eslint-plugin": "^8.57.2",

package/src/domains/analytics/components/AnalyticsCard.tsx

@@ -1,21 +1,25 @@
 /**
- * Analytics Card Component
- *
- * Configurable analytics card with chart or metrics. Surface comes
- * from the shared `udb-card` helper; size modifiers shrink/grow the
- * padding ("full" shares the md default).
+ * Analytics Card — chart/metric container on the design-system Card.
+ * Size modifiers ("sm"/"lg") are dashboard-owned padding overrides.
  */
 
 import { Loader2, AlertCircle } from "lucide-react";
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+} from "@umituz/web-design-system/organisms";
 import { cn } from "../../../primitives";
 import type { AnalyticsCardProps } from "../types/analytics";
 import { MetricCard } from "./MetricCard";
 import { AnalyticsChart } from "./AnalyticsChart";
 
 const SURFACE_CLASS = {
-  sm: 'udb-card--sm',
+  sm: "udb-card--sm",
   md: undefined,
-  lg: 'udb-card--lg',
+  lg: "udb-card--lg",
   full: undefined,
 } as const;
 
@@ -32,50 +36,45 @@ export const AnalyticsCard = ({
 }: AnalyticsCardProps) => {
   if (loading) {
     return (
-      <div className={cn("udb-card", SURFACE_CLASS[size], className)}>
+      <Card className={cn(SURFACE_CLASS[size], className)}>
         <div className="udb-analytics-card__status" role="status">
           <Loader2 className="udb-spin udb-analytics-card__spinner" aria-hidden="true" />
         </div>
-      </div>
+      </Card>
     );
   }
 
   if (error) {
     return (
-      <div className={cn("udb-card", SURFACE_CLASS[size], className)}>
+      <Card className={cn(SURFACE_CLASS[size], className)}>
         <div className="udb-analytics-card__status udb-analytics-card__status--error" role="alert">
           <AlertCircle className="udb-analytics-card__error-icon" aria-hidden="true" />
           <p className="udb-analytics-card__error-text">{error}</p>
         </div>
-      </div>
+      </Card>
     );
   }
 
   return (
-    <div className={cn("udb-card", SURFACE_CLASS[size], className)}>
-      {/* Header */}
+    <Card className={cn(SURFACE_CLASS[size], className)}>
       {(title || description) && (
-        <div className="udb-analytics-card__header">
-          {title && <h3 className="udb-analytics-card__title">{title}</h3>}
-          {description && <p className="udb-analytics-card__description">{description}</p>}
-        </div>
-      )}
-
-      {/* Chart */}
-      {chart && <AnalyticsChart config={chart} />}
-
-      {/* Metrics */}
-      {metrics && metrics.length > 0 && (
-        <div className="udb-analytics-card__metrics">
-          {metrics.map((metric) => (
-            <MetricCard key={metric.id} metric={metric} size="sm" />
-          ))}
-        </div>
+        <CardHeader>
+          {title && <CardTitle>{title}</CardTitle>}
+          {description && <CardDescription>{description}</CardDescription>}
+        </CardHeader>
       )}
-
-      {/* Custom Content */}
-      {children}
-    </div>
+      <CardContent>
+        {chart && <AnalyticsChart config={chart} />}
+        {metrics && metrics.length > 0 && (
+          <div className="udb-analytics-card__metrics">
+            {metrics.map((metric) => (
+              <MetricCard key={metric.id} metric={metric} size="sm" />
+            ))}
+          </div>
+        )}
+        {children}
+      </CardContent>
+    </Card>
   );
 };
 

package/src/domains/analytics/components/MetricCard.tsx

@@ -1,14 +1,12 @@
 /**
- * MetricCard
- *
- * Single KPI tile with a trend indicator. Colors and sizes come
- * from `--u-*` tokens via the `udb-metric-*` classes (no hardcoded
- * green/orange) and a11y role=button when interactive.
+ * MetricCard — dashboard logic (growth, i18n, a11y) on top of the
+ * design-system MetricCard presentation.
  */
 
-import { ArrowUp, ArrowDown, Minus } from "lucide-react";
+import {
+  MetricCard as DSMetricCard,
+} from "@umituz/web-design-system/organisms";
 import { useT } from "../../../i18n";
-import { cn } from "../../../primitives";
 import type { MetricCardProps } from "../types/analytics";
 import { formatMetricValue, calculateGrowth, getTrend } from "../utils/analytics";
 import { ANALYTICS_KEYS } from "../utils/i18nKeys";
@@ -25,61 +23,27 @@ export const MetricCard = ({
 
   const hasPrevious = metric.previousValue !== undefined;
   const growth = hasPrevious ? calculateGrowth(metric.value, metric.previousValue as number) : null;
-  const trend = growth !== null ? getTrend(growth) : 'stable';
-
-  const TrendIcon = trend === 'up' ? ArrowUp : trend === 'down' ? ArrowDown : Minus;
-
-  const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
-    if (!onClick) return;
-    if (e.key === 'Enter' || e.key === ' ') {
-      e.preventDefault();
-      onClick();
-    }
-  };
+  const trend = growth !== null ? getTrend(growth) : "stable";
 
   return (
-    <div
-      role={onClick ? 'button' : undefined}
-      tabIndex={onClick ? 0 : undefined}
-      aria-label={onClick ? `${metric.name} — ${formatMetricValue(metric)}` : undefined}
+    <DSMetricCard
+      className={className}
+      title={metric.name}
+      value={formatMetricValue(metric)}
+      icon={showIcon ? metric.icon : undefined}
+      iconColor="text-primary"
+      size={size}
+      trend={
+        showTrend && growth !== null && trend !== "stable"
+          ? {
+              value: growth,
+              label: t(ANALYTICS_KEYS.common.lastPeriod),
+            }
+          : undefined
+      }
+      trendValueFormatter={(v) => `${Math.abs(v).toFixed(1)}%`}
       onClick={onClick}
-      onKeyDown={onClick ? handleKeyDown : undefined}
-      className={cn(
-        'udb-metric',
-        `udb-metric--${size}`,
-        onClick && 'udb-metric--interactive',
-        className,
-      )}
-    >
-      <div className="udb-metric__head">
-        <div className="udb-metric__body">
-          <p className="udb-metric__name">{metric.name}</p>
-
-          <div className="udb-metric__value">{formatMetricValue(metric)}</div>
-
-          {showTrend && hasPrevious && growth !== null && (
-            <div
-              className={cn('udb-metric__trend', `udb-metric__trend--${trend}`)}
-              aria-label={t(ANALYTICS_KEYS.metric.change)}
-            >
-              <TrendIcon className="udb-metric__trend-icon" aria-hidden="true" />
-              <span className="udb-metric__trend-value">
-                {Math.abs(growth).toFixed(1)}%
-              </span>
-              <span className="udb-metric__trend-period">
-                {t(ANALYTICS_KEYS.common.lastPeriod)}
-              </span>
-            </div>
-          )}
-        </div>
-
-        {showIcon && metric.icon && (
-          <div className="udb-metric__icon-box">
-            <metric.icon className="udb-metric__icon" aria-hidden="true" />
-          </div>
-        )}
-      </div>
-    </div>
+    />
   );
 };
 

package/src/domains/settings/components/UserManagementTable.tsx

@@ -1,11 +1,10 @@
 /**
  * UserManagementTable — admin skeleton for the users screen.
  * Config-driven: rows and role catalog come in as props, role
- * changes delegate out. No fetching, no package-side copy beyond
- * the empty state.
+ * changes delegate out.
  */
 
-import { Users } from "lucide-react";
+import { DataTable, type Column } from "@umituz/web-design-system/organisms";
 import { useT } from "../../../i18n";
 import { SETTINGS_ADMIN_KEYS } from "../utils/i18nKeys";
 import type { RoleKey, RoleInfo } from "../../permissions/types";
@@ -32,55 +31,38 @@ export const UserManagementTable = ({
 }: UserManagementTableProps) => {
   const t = useT();
 
-  if (users.length === 0) {
-    return (
-      <div className="udb-empty">
-        <div className="udb-empty__icon">
-          <Users className="udb-empty__glyph" aria-hidden="true" />
-        </div>
-        <p className="udb-empty__text">{t(SETTINGS_ADMIN_KEYS.users.empty)}</p>
-      </div>
-    );
-  }
+  const columns: Column<ManagedUser>[] = [
+    { id: "name", header: t("settings.users.columns.name"), accessor: "name" },
+    { id: "email", header: t("settings.users.columns.email"), accessor: "email" },
+    {
+      id: "role",
+      header: t("settings.users.columns.role"),
+      accessor: (user) =>
+        onRoleChange ? (
+          <select
+            className="udb-period-select__select"
+            value={user.role}
+            aria-label={t("settings.users.columns.role")}
+            onChange={(e) => onRoleChange(user.id, e.target.value as RoleKey)}
+          >
+            {roles.map((role) => (
+              <option key={role.key} value={role.key}>
+                {role.label}
+              </option>
+            ))}
+          </select>
+        ) : (
+          roles.find((role) => role.key === user.role)?.label ?? user.role
+        ),
+    },
+  ];
 
   return (
-    <div className="udb-table__wrap">
-      <table className="udb-table">
-        <thead>
-          <tr>
-            <th className="udb-table__th">{t("settings.users.columns.name")}</th>
-            <th className="udb-table__th">{t("settings.users.columns.email")}</th>
-            <th className="udb-table__th">{t("settings.users.columns.role")}</th>
-          </tr>
-        </thead>
-        <tbody>
-          {users.map((user) => (
-            <tr key={user.id} className="udb-table__row">
-              <td className="udb-table__td">{user.name}</td>
-              <td className="udb-table__td">{user.email}</td>
-              <td className="udb-table__td">
-                {onRoleChange ? (
-                  <select
-                    className="udb-period-select__select"
-                    value={user.role}
-                    aria-label={t("settings.users.columns.role")}
-                    onChange={(e) => onRoleChange(user.id, e.target.value)}
-                  >
-                    {roles.map((role) => (
-                      <option key={role.key} value={role.key}>
-                        {role.label}
-                      </option>
-                    ))}
-                  </select>
-                ) : (
-                  roles.find((role) => role.key === user.role)?.label ?? user.role
-                )}
-              </td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
-    </div>
+    <DataTable
+      data={users}
+      columns={columns}
+      emptyState={{ title: t(SETTINGS_ADMIN_KEYS.users.empty) }}
+    />
   );
 };
 

package/src/domains/settings/utils/index.ts

@@ -9,3 +9,4 @@ export {
   getSettingsDefaultRoute,
   generateSettingsKey,
 } from './settings';
+export { SETTINGS_ADMIN_KEYS } from './i18nKeys';

package/src/i18n/defaultT.ts

@@ -29,6 +29,6 @@ const interpolate = (text: string, params?: Record<string, unknown>): string =>
 
 export const defaultT: TranslateFn = (key, params) => {
   const segments = key.split(".").filter(Boolean);
-  const source = segments.length > 0 ? segments[segments.length - 1] : key;
+  const source = segments[segments.length - 1] ?? key;
   return interpolate(humanizeSegment(source), params);
 };

package/src/primitives/Button.tsx

@@ -1,29 +1,23 @@
 /**
- * Button — camp-agnostic action button (`udb-btn`).
- *
- * Clones only the surface this package actually uses: variants
- * default/destructive/outline/ghost, sizes default/sm/icon. No `asChild`
- * (radix-free), no variant library — classes come from `styles.css`.
+ * Button — delegates to the design system.
+ * Dashboard surface: variants default/destructive/outline/ghost,
+ * sizes default/sm/icon. Call-site API unchanged.
  */
 
-import { forwardRef, type ButtonHTMLAttributes } from 'react';
-import { cn } from './cn';
+import { forwardRef } from 'react';
+import { Button as DSButton } from '@umituz/web-design-system/atoms';
 
 export type ButtonVariant = 'default' | 'destructive' | 'outline' | 'ghost';
 export type ButtonSize = 'default' | 'sm' | 'icon';
 
-export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   variant?: ButtonVariant;
   size?: ButtonSize;
 }
 
 export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
-  ({ className, variant = 'default', size = 'default', ...props }, ref) => (
-    <button
-      ref={ref}
-      className={cn('udb-btn', `udb-btn--${variant}`, `udb-btn--${size}`, className)}
-      {...props}
-    />
+  ({ variant = 'default', size = 'default', ...props }, ref) => (
+    <DSButton ref={ref} variant={variant} size={size} {...props} />
   ),
 );
 

package/src/primitives/Checkbox.tsx

@@ -1,40 +1,17 @@
 /**
- * Checkbox — native checkbox with a boolean-change callback (`udb-checkbox`).
- *
- * Keeps the `onCheckedChange` convenience this package relies on; every
- * other native attribute passes straight through.
+ * Checkbox — delegates to the design system (native + onCheckedChange).
  */
 
-import { forwardRef, useCallback, type InputHTMLAttributes } from 'react';
-import { cn } from './cn';
+import { forwardRef } from 'react';
+import { Checkbox as DSCheckbox } from '@umituz/web-design-system/atoms';
 
-export interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+export interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> {
   checked?: boolean;
   onCheckedChange?: (checked: boolean) => void;
 }
 
-export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(
-  ({ className, checked, onCheckedChange, onChange, ...props }, ref) => {
-    // Memoized so parent re-renders don't recreate the handler identity.
-    const handleChange = useCallback(
-      (e: React.ChangeEvent<HTMLInputElement>) => {
-        onCheckedChange?.(e.target.checked);
-        onChange?.(e);
-      },
-      [onCheckedChange, onChange],
-    );
-
-    return (
-      <input
-        ref={ref}
-        type="checkbox"
-        checked={checked}
-        onChange={handleChange}
-        className={cn('udb-checkbox', className)}
-        {...props}
-      />
-    );
-  },
-);
+export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>((props, ref) => (
+  <DSCheckbox ref={ref} {...props} />
+));
 
 Checkbox.displayName = 'Checkbox';

package/src/primitives/Input.tsx

@@ -1,18 +1,22 @@
 /**
- * Input — text input field (`udb-input`).
- *
- * Minimal clone of the surface this package uses: a native input with
- * token-driven styling. Everything else passes through untouched.
+ * Input — delegates to the design system.
+ * Native `size` (character width) has no DS counterpart; it maps to a
+ * `ch`-based width so the original prop API keeps working.
  */
 
-import { forwardRef, type InputHTMLAttributes } from 'react';
-import { cn } from './cn';
+import { forwardRef } from 'react';
+import { Input as DSInput } from '@umituz/web-design-system/atoms';
 
-export type InputProps = InputHTMLAttributes<HTMLInputElement>;
+export type InputProps = React.InputHTMLAttributes<HTMLInputElement>;
 
 export const Input = forwardRef<HTMLInputElement, InputProps>(
-  ({ className, type = 'text', ...props }, ref) => (
-    <input ref={ref} type={type} className={cn('udb-input', className)} {...props} />
+  ({ type = 'text', size: nativeSize, style, ...props }, ref) => (
+    <DSInput
+      ref={ref}
+      type={type}
+      {...props}
+      style={nativeSize != null ? { width: `${nativeSize}ch`, ...style } : style}
+    />
   ),
 );
 

package/src/primitives/Skeleton.tsx

@@ -1,26 +1,6 @@
 /**
- * Skeleton — loading placeholder (`udb-skeleton`).
- *
- * The pulse animation is defined in `styles.css` (a CSS file can ship
- * keyframes; inline styles cannot).
+ * Skeleton — re-exported from the design system (variant API identical).
  */
 
-import { forwardRef, type HTMLAttributes } from 'react';
-import { cn } from './cn';
-
-export interface SkeletonProps extends HTMLAttributes<HTMLDivElement> {
-  variant?: 'text' | 'circular' | 'rectangular';
-}
-
-export const Skeleton = forwardRef<HTMLDivElement, SkeletonProps>(
-  ({ className, variant = 'rectangular', ...props }, ref) => (
-    <div
-      ref={ref}
-      className={cn('udb-skeleton', `udb-skeleton--${variant}`, className)}
-      role="status"
-      {...props}
-    />
-  ),
-);
-
-Skeleton.displayName = 'Skeleton';
+export { Skeleton } from '@umituz/web-design-system/atoms';
+export type { SkeletonProps } from '@umituz/web-design-system/atoms';

package/src/primitives/cn.ts

@@ -1,15 +1,10 @@
 /**
- * cn — conditional className join (clsx only).
+ * cn — conditional className join, delegated to the design system.
  *
- * Deliberately drops the old tailwind-merge layer: v4 ships its own
- * `udb-*` class vocabulary where overrides append instead of conflicting,
- * so plain conditional joining is the whole job.
+ * The design system's `cn` (clsx + tailwind-merge) understands both the
+ * `udb-*` vocabulary (unknown classes pass through untouched) and real
+ * Tailwind utilities a host may pass, resolving conflicts by last-wins.
  */
 
-import { clsx, type ClassValue } from 'clsx';
-
-export type { ClassValue };
-
-export function cn(...inputs: ClassValue[]): string {
-  return clsx(inputs);
-}
+export { cn } from '@umituz/web-design-system/utils/cn';
+export type { ClassValue } from '@umituz/web-design-system/utils/cn';

package/src/styles/dashboard.css

@@ -10,12 +10,15 @@
  *   tokens (see `tokens.css`); override them for theming and dark mode.
  *
  * Sections:
- *   1. Scope & reset       5. Sidebar            9. Onboarding
- *   2. Primitives          6. Header / menus    10. Settings
- *   3. Layout helpers      7. Auth              11. Analytics
- *   4. App shell           8. Forms (auth)      12. Shared blocks
+ *   1. Scope & reset       5. Header/menus      9. Settings
+ *   2. Layout helpers      6. Auth             10. Analytics
+ *   3. App shell           7. Forms (auth)     11. Shared blocks
+ *   4. Sidebar             8. Onboarding
  */
 
+@import "@umituz/web-design-system/styles.css";
+@import "./tokens.css";
+
 /* ============================================================
  * 1. Scope & reset
  * ============================================================ */
@@ -50,191 +53,7 @@
 }
 
 /* ============================================================
- * 2. Primitives — Button
- * ============================================================ */
-
-.udb-btn {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  gap: var(--u-space-2);
-  white-space: nowrap;
-  border: 1px solid transparent;
-  border-radius: var(--u-radius-md);
-  font-family: inherit;
-  font-size: var(--u-font-size-md);
-  font-weight: var(--u-font-weight-medium);
-  line-height: 1;
-  cursor: pointer;
-  text-decoration: none;
-  transition: background-color 0.15s ease, color 0.15s ease,
-    border-color 0.15s ease, transform 0.1s ease;
-}
-
-.udb-btn:focus-visible {
-  outline: none;
-  box-shadow: 0 0 0 2px var(--u-color-surface), 0 0 0 4px var(--u-color-ring);
-}
-
-.udb-btn:disabled {
-  pointer-events: none;
-  opacity: 0.55;
-}
-
-.udb-btn:active:not(:disabled) {
-  transform: scale(0.97);
-}
-
-.udb-btn svg {
-  pointer-events: none;
-  width: 1em;
-  height: 1em;
-  flex-shrink: 0;
-}
-
-/* Variants */
-.udb-btn--default {
-  background: var(--u-color-primary);
-  color: var(--u-color-primary-contrast);
-}
-
-.udb-btn--default:hover:not(:disabled) {
-  background: var(--u-color-primary-hover);
-}
-
-.udb-btn--destructive {
-  background: var(--u-color-danger);
-  color: var(--u-color-danger-contrast);
-}
-
-.udb-btn--destructive:hover:not(:disabled) {
-  background: var(--u-color-danger-hover);
-}
-
-.udb-btn--outline {
-  background: var(--u-color-surface);
-  color: var(--u-color-text);
-  border-color: var(--u-color-border-strong);
-}
-
-.udb-btn--outline:hover:not(:disabled) {
-  background: var(--u-color-surface-muted);
-}
-
-.udb-btn--ghost {
-  background: transparent;
-  color: var(--u-color-text);
-}
-
-.udb-btn--ghost:hover:not(:disabled) {
-  background: var(--u-color-surface-muted);
-}
-
-/* Sizes */
-.udb-btn--default {
-  height: 40px;
-  padding: 0 var(--u-space-4);
-}
-
-.udb-btn--sm {
-  height: 32px;
-  padding: 0 var(--u-space-3);
-  font-size: var(--u-font-size-sm);
-}
-
-.udb-btn--icon {
-  height: 36px;
-  width: 36px;
-  padding: 0;
-}
-
-/* ============================================================
- * 2. Primitives — Input / Checkbox / Skeleton
- * ============================================================ */
-
-.udb-input {
-  display: block;
-  width: 100%;
-  height: 40px;
-  padding: 0 var(--u-space-3);
-  background: var(--u-color-surface);
-  border: 1px solid var(--u-color-border-strong);
-  border-radius: var(--u-radius-md);
-  color: var(--u-color-text);
-  font-family: inherit;
-  font-size: var(--u-font-size-md);
-}
-
-.udb-input::placeholder {
-  color: var(--u-color-muted);
-}
-
-.udb-input:focus-visible {
-  outline: none;
-  border-color: var(--u-color-primary);
-  box-shadow: 0 0 0 3px var(--u-color-ring);
-}
-
-.udb-input:disabled {
-  cursor: not-allowed;
-  opacity: 0.55;
-  background: var(--u-color-surface-muted);
-}
-
-.udb-checkbox {
-  width: 18px;
-  height: 18px;
-  margin: 0;
-  accent-color: var(--u-color-primary);
-  cursor: pointer;
-  flex-shrink: 0;
-}
-
-.udb-checkbox:disabled {
-  cursor: not-allowed;
-  opacity: 0.55;
-}
-
-.udb-checkbox:focus-visible {
-  outline: none;
-  box-shadow: 0 0 0 3px var(--u-color-ring);
-  border-radius: var(--u-radius-sm);
-}
-
-.udb-skeleton {
-  background: var(--u-color-surface-muted);
-  animation: udb-pulse 1.6s ease-in-out infinite;
-  border-radius: var(--u-radius-md);
-}
-
-.udb-skeleton--text {
-  height: 16px;
-  width: 100%;
-}
-
-.udb-skeleton--circular {
-  height: 48px;
-  width: 48px;
-  border-radius: 50%;
-}
-
-.udb-skeleton--rectangular {
-  height: 96px;
-  width: 100%;
-}
-
-@keyframes udb-pulse {
-  0%,
-  100% {
-    opacity: 1;
-  }
-  50% {
-    opacity: 0.55;
-  }
-}
-
-/* ============================================================
- * 3. Layout helpers
+ * 2. Layout helpers
  * ============================================================ */
 
 .udb-stack {
@@ -254,14 +73,6 @@
   grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
 }
 
-.udb-card {
-  background: var(--u-color-surface);
-  border: 1px solid var(--u-color-border);
-  border-radius: var(--u-radius-lg);
-  padding: var(--u-space-6);
-  box-shadow: var(--u-shadow-sm);
-}
-
 .udb-card--sm {
   padding: var(--u-space-4);
 }
@@ -271,7 +82,7 @@
 }
 
 /* ============================================================
- * 4. App shell
+ * 3. App shell
  * ============================================================ */
 
 .udb-layout {
@@ -376,7 +187,7 @@
 }
 
 /* ============================================================
- * 5. Sidebar
+ * 4. Sidebar
  * ============================================================ */
 
 .udb-sidebar {
@@ -589,7 +400,7 @@
 }
 
 /* ============================================================
- * 6. Header / menus / notifications / profile
+ * 5. Header / menus / notifications / profile
  * ============================================================ */
 
 .udb-header {
@@ -1015,7 +826,7 @@
 }
 
 /* ============================================================
- * 7. Auth pages
+ * 6. Auth pages
  * ============================================================ */
 
 .udb-auth {
@@ -1208,7 +1019,7 @@
 }
 
 /* ============================================================
- * 8. Forms (auth + generic fields)
+ * 7. Forms (auth + generic fields)
  * ============================================================ */
 
 /* Shared spinner (also used by onboarding/analytics icons). */
@@ -1551,7 +1362,7 @@
 }
 
 /* ============================================================
- * 9. Onboarding wizard
+ * 8. Onboarding wizard
  * ============================================================ */
 
 .udb-onboarding {
@@ -2202,7 +2013,7 @@
 }
 
 /* ============================================================
- * 10. Settings
+ * 9. Settings
  * ============================================================ */
 
 .udb-settings {
@@ -2452,7 +2263,7 @@
 }
 
 /* ============================================================
- * 11. Analytics
+ * 10. Analytics
  * ============================================================ */
 
 .udb-analytics {
@@ -2572,131 +2383,6 @@
   cursor: pointer;
 }
 
-/* KPI tile. */
-.udb-metric {
-  background: var(--u-color-surface);
-  border: 1px solid var(--u-color-border);
-  border-radius: var(--u-radius-lg);
-  padding: var(--u-space-6);
-  box-shadow: var(--u-shadow-sm);
-}
-
-.udb-metric--sm {
-  padding: var(--u-space-4);
-}
-
-.udb-metric--lg {
-  padding: var(--u-space-8);
-}
-
-.udb-metric--interactive {
-  cursor: pointer;
-  transition: border-color 0.15s ease, box-shadow 0.15s ease;
-}
-
-.udb-metric--interactive:hover {
-  border-color: var(--u-color-primary);
-}
-
-.udb-metric--interactive:focus-visible {
-  outline: none;
-  box-shadow: 0 0 0 3px var(--u-color-ring);
-}
-
-.udb-metric__head {
-  display: flex;
-  align-items: flex-start;
-  justify-content: space-between;
-  gap: var(--u-space-3);
-}
-
-.udb-metric__body {
-  flex: 1;
-  min-width: 0;
-}
-
-.udb-metric__name {
-  margin: 0 0 var(--u-space-1);
-  font-size: var(--u-font-size-md);
-  font-weight: var(--u-font-weight-medium);
-  color: var(--u-color-muted);
-}
-
-.udb-metric__value {
-  font-size: var(--u-font-size-3xl);
-  font-weight: var(--u-font-weight-bold);
-  letter-spacing: -0.02em;
-  line-height: 1.2;
-  color: var(--u-color-text);
-}
-
-.udb-metric--sm .udb-metric__name {
-  font-size: var(--u-font-size-sm);
-}
-
-.udb-metric--sm .udb-metric__value {
-  font-size: var(--u-font-size-xl);
-}
-
-.udb-metric--lg .udb-metric__name {
-  font-size: var(--u-font-size-lg);
-}
-
-.udb-metric--lg .udb-metric__value {
-  font-size: var(--u-font-size-4xl);
-}
-
-/* Trend row: one modifier tones the icon + value together;
- * the "vs last period" label stays muted. */
-.udb-metric__trend {
-  display: flex;
-  align-items: center;
-  gap: var(--u-space-1);
-  margin-top: var(--u-space-2);
-  color: var(--u-color-muted);
-}
-
-.udb-metric__trend--up {
-  color: var(--u-color-success);
-}
-
-.udb-metric__trend--down {
-  color: var(--u-color-danger);
-}
-
-.udb-metric__trend-icon {
-  width: 16px;
-  height: 16px;
-  flex-shrink: 0;
-}
-
-.udb-metric__trend-value {
-  font-size: var(--u-font-size-md);
-  font-weight: var(--u-font-weight-medium);
-}
-
-.udb-metric__trend-period {
-  font-size: var(--u-font-size-md);
-  color: var(--u-color-muted);
-}
-
-.udb-metric__icon-box {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 48px;
-  height: 48px;
-  flex-shrink: 0;
-  border-radius: var(--u-radius-md);
-  background: var(--u-color-primary-soft);
-}
-
-.udb-metric__icon {
-  width: 24px;
-  height: 24px;
-  color: var(--u-color-primary);
-}
-
 /* Chart card internals. */
 .udb-analytics-card__status {
   display: flex;
@@ -2810,7 +2496,7 @@
 }
 
 /* ============================================================
- * 12. Shared blocks — empty state, tables, org switcher, matrix,
+ * 11. Shared blocks — empty state, tables, org switcher, matrix,
  *     audit list (used by guards, session and settings skeletons)
  * ============================================================ */
 

package/src/styles/tokens.contract.test.ts

@@ -63,4 +63,29 @@ describe("dashboard stylesheet token contract", () => {
   it("provides dark-mode overrides", () => {
     expect(tokensCss).toContain('[data-udb-theme="dark"]');
   });
+
+  it("bridges core tokens to design-system variables with fallbacks", () => {
+    const BRIDGED = [
+      ["--u-color-primary", "var(--color-primary, #2563eb)"],
+      ["--u-color-bg", "var(--color-background, #f8fafc)"],
+      ["--u-color-danger", "var(--color-destructive, #dc2626)"],
+      ["--u-radius-md", "var(--radius-md, 8px)"],
+      ["--u-shadow-lg", "var(--shadow-lg,"],
+      ["--u-font-sans", "var(--font-sans,"],
+    ] as const;
+    for (const [token, bridge] of BRIDGED) {
+      expect(tokensCss).toContain(`${token}: ${bridge}`);
+    }
+  });
+
+  it("derives hover/soft shades from the bridged base color", () => {
+    expect(tokensCss).toMatch(/--u-color-primary-hover: var\(--color-primary-hover, color-mix\(/);
+    expect(tokensCss).toMatch(/--u-color-primary-soft: var\(--color-primary-soft, color-mix\(/);
+  });
+
+  it("pulls the design-system stylesheet transitively", () => {
+    const imports = [...dashboardCss.matchAll(/@import\s+"([^"]+)"/g)].map((m) => m[1]);
+    expect(imports[0]).toBe("@umituz/web-design-system/styles.css");
+    expect(imports).toContain("./tokens.css");
+  });
 });

package/src/styles/tokens.css

@@ -1,53 +1,51 @@
 /**
  * @umituz/web-dashboard — design tokens (`--u-*`)
  *
- * The whole visual surface of the package is driven by these custom
- * properties. Hosts restyle everything (including dark mode) by
- * overriding them — no utility framework, no host theme variables.
- *
- * Dark mode: add `data-udb-theme="dark"` on any ancestor (typically
- * <html> or the layout root). The package never switches themes on
- * its own — the host decides.
+ * Colors, radii, fonts and shadows are bridged to the design system's
+ * `--color-*` / `--radius-*` / `--font-*` / `--shadow-*` variables; each
+ * bridge keeps its previous value as fallback. Dark mode: add
+ * `data-udb-theme="dark"` on any ancestor — the dark block re-sets the
+ * design-system variables and every bridge follows automatically.
  */
 
 :root {
-  /* Palette — surfaces & text */
-  --u-color-bg: #f8fafc;
-  --u-color-surface: #ffffff;
-  --u-color-surface-muted: #f1f5f9;
-  --u-color-text: #0f172a;
-  --u-color-muted: #64748b;
-  --u-color-border: #e2e8f0;
+  /* Surfaces & text */
+  --u-color-bg: var(--color-background, #f8fafc);
+  --u-color-surface: var(--color-card, #ffffff);
+  --u-color-surface-muted: var(--color-muted, #f1f5f9);
+  --u-color-text: var(--color-foreground, #0f172a);
+  --u-color-muted: var(--color-muted-foreground, #64748b);
+  --u-color-border: var(--color-border, #e2e8f0);
   --u-color-border-strong: #cbd5e1;
 
-  /* Palette — brand */
-  --u-color-primary: #2563eb;
-  --u-color-primary-hover: #1d4ed8;
-  --u-color-primary-contrast: #ffffff;
-  --u-color-primary-soft: rgba(37, 99, 235, 0.1);
-  --u-color-secondary: #8b5cf6;
-
-  /* Palette — semantic */
-  --u-color-danger: #dc2626;
-  --u-color-danger-hover: #b91c1c;
-  --u-color-danger-contrast: #ffffff;
-  --u-color-danger-soft: rgba(220, 38, 38, 0.1);
-  --u-color-success: #16a34a;
-  --u-color-success-soft: rgba(22, 163, 74, 0.12);
-  --u-color-warning: #d97706;
-  --u-color-warning-soft: rgba(217, 119, 6, 0.15);
+  /* Brand (hover/soft derive from the base color) */
+  --u-color-primary: var(--color-primary, #2563eb);
+  --u-color-primary-hover: var(--color-primary-hover, color-mix(in oklab, var(--color-primary, #2563eb) 86%, #000));
+  --u-color-primary-contrast: var(--color-primary-foreground, #ffffff);
+  --u-color-primary-soft: var(--color-primary-soft, color-mix(in srgb, var(--color-primary, #2563eb) 10%, transparent));
+  --u-color-secondary: var(--color-secondary, #8b5cf6);
+
+  /* Semantic */
+  --u-color-danger: var(--color-destructive, #dc2626);
+  --u-color-danger-hover: var(--color-destructive-hover, color-mix(in oklab, var(--color-destructive, #dc2626) 85%, #000));
+  --u-color-danger-contrast: var(--color-destructive-foreground, #ffffff);
+  --u-color-danger-soft: var(--color-destructive-soft, color-mix(in srgb, var(--color-destructive, #dc2626) 10%, transparent));
+  --u-color-success: var(--color-success, #16a34a);
+  --u-color-success-soft: var(--color-success-soft, color-mix(in srgb, var(--color-success, #16a34a) 12%, transparent));
+  --u-color-warning: var(--color-warning, #d97706);
+  --u-color-warning-soft: var(--color-warning-soft, color-mix(in srgb, var(--color-warning, #d97706) 15%, transparent));
 
   /* Focus */
-  --u-color-ring: rgba(37, 99, 235, 0.45);
+  --u-color-ring: var(--color-ring, rgba(37, 99, 235, 0.45));
 
   /* Radii */
-  --u-radius-sm: 6px;
-  --u-radius-md: 8px;
-  --u-radius-lg: 12px;
-  --u-radius-xl: 16px;
+  --u-radius-sm: var(--radius-sm, 6px);
+  --u-radius-md: var(--radius-md, 8px);
+  --u-radius-lg: var(--radius-lg, 12px);
+  --u-radius-xl: var(--radius-xl, 16px);
   --u-radius-pill: 9999px;
 
-  /* Spacing scale (4px base) */
+  /* Spacing (4px base) */
   --u-space-1: 4px;
   --u-space-2: 8px;
   --u-space-3: 12px;
@@ -58,8 +56,8 @@
   --u-space-8: 40px;
 
   /* Typography */
-  --u-font-sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto,
-    "Helvetica Neue", Arial, "Noto Sans", sans-serif;
+  --u-font-sans: var(--font-sans, ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, "Noto Sans", sans-serif);
   --u-font-size-xs: 11px;
   --u-font-size-sm: 12px;
   --u-font-size-md: 14px;
@@ -72,17 +70,17 @@
   --u-font-weight-medium: 500;
   --u-font-weight-bold: 700;
 
-  /* Layout metrics */
+  /* Layout */
   --u-sidebar-width: 240px;
   --u-sidebar-width-collapsed: 64px;
   --u-header-height: 56px;
 
   /* Elevation */
-  --u-shadow-sm: 0 1px 2px rgba(15, 23, 42, 0.06);
-  --u-shadow-md: 0 4px 12px rgba(15, 23, 42, 0.08);
-  --u-shadow-lg: 0 12px 32px rgba(15, 23, 42, 0.14);
+  --u-shadow-sm: var(--shadow-sm, 0 1px 2px rgba(15, 23, 42, 0.06));
+  --u-shadow-md: var(--shadow-md, 0 4px 12px rgba(15, 23, 42, 0.08));
+  --u-shadow-lg: var(--shadow-lg, 0 12px 32px rgba(15, 23, 42, 0.14));
 
-  /* Sidebar palette (distinct surface so hosts can tint it) */
+  /* Sidebar palette */
   --u-sidebar-bg: var(--u-color-surface);
   --u-sidebar-text: var(--u-color-text);
   --u-sidebar-muted: var(--u-color-muted);
@@ -92,33 +90,27 @@
 }
 
 [data-udb-theme="dark"] {
-  --u-color-bg: #0b1120;
-  --u-color-surface: #111827;
-  --u-color-surface-muted: #1e293b;
-  --u-color-text: #f1f5f9;
-  --u-color-muted: #94a3b8;
-  --u-color-border: #1f2a3c;
-  --u-color-border-strong: #334155;
+  --color-background: #0b1120;
+  --color-card: #111827;
+  --color-muted: #1e293b;
+  --color-foreground: #f1f5f9;
+  --color-muted-foreground: #94a3b8;
+  --color-border: #1f2a3c;
 
-  --u-color-primary: #3b82f6;
-  --u-color-primary-hover: #60a5fa;
-  --u-color-primary-contrast: #ffffff;
-  --u-color-primary-soft: rgba(59, 130, 246, 0.16);
+  --color-primary: #3b82f6;
+  --color-primary-foreground: #ffffff;
+  --color-secondary: #a78bfa;
 
-  --u-color-secondary: #a78bfa;
+  --color-destructive: #ef4444;
+  --color-destructive-foreground: #ffffff;
+  --color-success: #22c55e;
+  --color-warning: #f59e0b;
 
-  --u-color-danger: #ef4444;
-  --u-color-danger-hover: #f87171;
-  --u-color-danger-contrast: #ffffff;
-  --u-color-danger-soft: rgba(239, 68, 68, 0.16);
-  --u-color-success: #22c55e;
-  --u-color-success-soft: rgba(34, 197, 94, 0.16);
-  --u-color-warning: #f59e0b;
-  --u-color-warning-soft: rgba(245, 158, 11, 0.16);
+  --color-ring: rgba(96, 165, 250, 0.5);
 
-  --u-color-ring: rgba(96, 165, 250, 0.5);
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4);
+  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.45);
+  --shadow-lg: 0 12px 32px rgba(0, 0, 0, 0.55);
 
-  --u-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4);
-  --u-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.45);
-  --u-shadow-lg: 0 12px 32px rgba(0, 0, 0, 0.55);
+  --u-color-border-strong: #334155;
 }