@datatechsolutions/ui 3.3.0 → 3.4.0

package/dist/{workflow-api-client-DoYj7nHz.d.mts → workflow-api-client-CpFl3WcG.d.mts}

@@ -1,5 +1,5 @@
 import { WorkflowGraph, WorkflowRun, AgentRule, WorkflowTool, AgentTool, Workflow, VariableValue, AgentModel } from './astrlabe/contracts.mjs';
-import { A as AgentWithPrompts } from './index-VI9gyJXl.mjs';
+import { A as AgentWithPrompts } from './index-BNRGVAS5.mjs';
 import { AgentPrompt } from '@datatechsolutions/shared-domain/ports/workflow';
 import { AgentConfigLike, DataSource } from '@datatechsolutions/shared-domain/common';
 import * as react_jsx_runtime from 'react/jsx-runtime';

package/dist/{workflow-api-client-BKD8OfP_.d.ts → workflow-api-client-uLICOanv.d.ts}

@@ -1,5 +1,5 @@
 import { WorkflowGraph, WorkflowRun, AgentRule, WorkflowTool, AgentTool, Workflow, VariableValue, AgentModel } from './astrlabe/contracts.js';
-import { A as AgentWithPrompts } from './index-CoB18TbG.js';
+import { A as AgentWithPrompts } from './index-CnCY-b5V.js';
 import { AgentPrompt } from '@datatechsolutions/shared-domain/ports/workflow';
 import { AgentConfigLike, DataSource } from '@datatechsolutions/shared-domain/common';
 import * as react_jsx_runtime from 'react/jsx-runtime';

package/dist/workflow-canvas--qaYKuMm.d.ts

@@ -0,0 +1,113 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ComponentProps } from 'react';
+import { WorkflowTool, AgentTool, AgentRule, AgentModel, WorkflowGraph, LogicNodeConfig } from './astrlabe/contracts.js';
+import { A as AgentWithPrompts, W as WorkflowEntityDefinition } from './index-CnCY-b5V.js';
+import { NodeTypes } from '@xyflow/react';
+
+type ModelProvider = {
+    id: string;
+    name: string;
+    /** The provider's runtime SDK / endpoint family. Different from the
+     *  model families it CAN serve (see `servedFamilies`). E.g., a
+     *  Bedrock provider has `provider: 'amazon'` but
+     *  `servedFamilies: ['anthropic', 'amazon', 'meta', 'openai']`. */
+    provider: string;
+    modelCount: number;
+    configured: boolean;
+    /** Which model families this provider can serve at run-time. Used
+     *  to compute the cartesian (model × provider) available to an
+     *  agent. Defaults to `[provider]` when omitted (i.e., direct API
+     *  providers that only serve their own family). */
+    servedFamilies?: string[];
+    /** Optional masked API key for display (`sk-prod-•••3742`). */
+    apiKeyMasked?: string;
+    /** ARN/SSM path of the secret, displayed read-only. */
+    credentialRef?: string;
+    /** ISO timestamp of last successful auth handshake. */
+    lastVerifiedAt?: string;
+};
+type NodePaletteProps = {
+    agents: AgentWithPrompts[];
+    tools: WorkflowTool[];
+    agentTools?: AgentTool[];
+    rules: AgentRule[];
+    entities?: WorkflowEntityDefinition[];
+    modelProviders?: ModelProvider[];
+    onCreateAgent?: () => void;
+    onCreateTool?: () => void;
+    onCreateAgentTool?: () => void;
+    onCreateRule?: () => void;
+    onCreateDatasource?: () => void;
+    onConfigureProvider?: (providerId: string) => void;
+};
+declare function NodePalette({ agents, tools, agentTools, rules, entities, modelProviders, onCreateAgent, onCreateTool, onCreateAgentTool, onCreateRule, onCreateDatasource, onConfigureProvider }: NodePaletteProps): react_jsx_runtime.JSX.Element;
+
+type AgentModalRenderProps = {
+    agent: AgentWithPrompts | null;
+    models: AgentModel[];
+    open: boolean;
+    isCreateMode: boolean;
+    onClose: () => void;
+    onSaved: () => void;
+};
+type LogicNodeModalRenderProps = {
+    nodeId: string | null;
+    nodeLabel: string;
+    config: LogicNodeConfig | null;
+    open: boolean;
+    onClose: () => void;
+    onSave: (nodeId: string, updatedConfig: LogicNodeConfig) => void;
+    entities: WorkflowEntityDefinition[];
+};
+type WorkflowCanvasProps = {
+    agents: AgentWithPrompts[];
+    models: AgentModel[];
+    /** Configured LLM provider connections (account-level credentials).
+     *  Forwarded to AgentModal so the agent's "Model" tab can list the
+     *  providers/credentials available to bind to. Optional — empty
+     *  means no provider has been configured yet (modal shows empty
+     *  state pointing the user to Settings). */
+    modelProviders?: ModelProvider[];
+    tools?: WorkflowTool[];
+    agentTools?: AgentTool[];
+    rules?: AgentRule[];
+    entities?: WorkflowEntityDefinition[];
+    datasources?: Array<{
+        id: string;
+        name: string;
+        dialect: string;
+    }>;
+    onLoadTables?: (datasourceId: string) => Promise<string[]>;
+    onLoadSchema?: (datasourceId: string, table: string) => Promise<Array<{
+        name: string;
+        type: string;
+        nullable?: boolean;
+    }>>;
+    initialGraph?: WorkflowGraph | null;
+    onGraphChange?: (graph: WorkflowGraph) => void;
+    onEditTool?: (tool: WorkflowTool) => void;
+    onToggleTool?: (tool: WorkflowTool) => void;
+    onEditRule?: (rule: AgentRule) => void;
+    onToggleRule?: (rule: AgentRule) => void;
+    onCancelCreateAgent?: () => void;
+    onAgentSaved?: () => void;
+    isCreatingAgent?: boolean;
+    /** Custom node type components — merged with built-in edge types */
+    nodeTypes?: NodeTypes;
+    /** Optional: render the AgentModal externally (frontend provides the component) */
+    renderAgentModal?: (props: AgentModalRenderProps) => React.ReactNode;
+    /** Optional: render a custom LogicNodeModal; defaults to internal modal */
+    renderLogicNodeModal?: (props: LogicNodeModalRenderProps) => React.ReactNode;
+};
+declare function WorkflowCanvas(props: WorkflowCanvasProps): react_jsx_runtime.JSX.Element;
+
+type BuilderCanvasProps = ComponentProps<typeof WorkflowCanvas>;
+type WorkspaceProps = {
+    locale?: string;
+    messages?: Record<string, unknown>;
+    className?: string;
+    workflowId?: string;
+} & Partial<BuilderCanvasProps>;
+declare function Workspace({ locale, messages, className, workflowId, ...canvasProps }: WorkspaceProps): react_jsx_runtime.JSX.Element;
+
+export { type ModelProvider as M, NodePalette as N, type WorkspaceProps as W, Workspace as a };

package/dist/workflow-canvas-B80fmD_n.d.mts

@@ -0,0 +1,113 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ComponentProps } from 'react';
+import { WorkflowTool, AgentTool, AgentRule, AgentModel, WorkflowGraph, LogicNodeConfig } from './astrlabe/contracts.mjs';
+import { A as AgentWithPrompts, W as WorkflowEntityDefinition } from './index-BNRGVAS5.mjs';
+import { NodeTypes } from '@xyflow/react';
+
+type ModelProvider = {
+    id: string;
+    name: string;
+    /** The provider's runtime SDK / endpoint family. Different from the
+     *  model families it CAN serve (see `servedFamilies`). E.g., a
+     *  Bedrock provider has `provider: 'amazon'` but
+     *  `servedFamilies: ['anthropic', 'amazon', 'meta', 'openai']`. */
+    provider: string;
+    modelCount: number;
+    configured: boolean;
+    /** Which model families this provider can serve at run-time. Used
+     *  to compute the cartesian (model × provider) available to an
+     *  agent. Defaults to `[provider]` when omitted (i.e., direct API
+     *  providers that only serve their own family). */
+    servedFamilies?: string[];
+    /** Optional masked API key for display (`sk-prod-•••3742`). */
+    apiKeyMasked?: string;
+    /** ARN/SSM path of the secret, displayed read-only. */
+    credentialRef?: string;
+    /** ISO timestamp of last successful auth handshake. */
+    lastVerifiedAt?: string;
+};
+type NodePaletteProps = {
+    agents: AgentWithPrompts[];
+    tools: WorkflowTool[];
+    agentTools?: AgentTool[];
+    rules: AgentRule[];
+    entities?: WorkflowEntityDefinition[];
+    modelProviders?: ModelProvider[];
+    onCreateAgent?: () => void;
+    onCreateTool?: () => void;
+    onCreateAgentTool?: () => void;
+    onCreateRule?: () => void;
+    onCreateDatasource?: () => void;
+    onConfigureProvider?: (providerId: string) => void;
+};
+declare function NodePalette({ agents, tools, agentTools, rules, entities, modelProviders, onCreateAgent, onCreateTool, onCreateAgentTool, onCreateRule, onCreateDatasource, onConfigureProvider }: NodePaletteProps): react_jsx_runtime.JSX.Element;
+
+type AgentModalRenderProps = {
+    agent: AgentWithPrompts | null;
+    models: AgentModel[];
+    open: boolean;
+    isCreateMode: boolean;
+    onClose: () => void;
+    onSaved: () => void;
+};
+type LogicNodeModalRenderProps = {
+    nodeId: string | null;
+    nodeLabel: string;
+    config: LogicNodeConfig | null;
+    open: boolean;
+    onClose: () => void;
+    onSave: (nodeId: string, updatedConfig: LogicNodeConfig) => void;
+    entities: WorkflowEntityDefinition[];
+};
+type WorkflowCanvasProps = {
+    agents: AgentWithPrompts[];
+    models: AgentModel[];
+    /** Configured LLM provider connections (account-level credentials).
+     *  Forwarded to AgentModal so the agent's "Model" tab can list the
+     *  providers/credentials available to bind to. Optional — empty
+     *  means no provider has been configured yet (modal shows empty
+     *  state pointing the user to Settings). */
+    modelProviders?: ModelProvider[];
+    tools?: WorkflowTool[];
+    agentTools?: AgentTool[];
+    rules?: AgentRule[];
+    entities?: WorkflowEntityDefinition[];
+    datasources?: Array<{
+        id: string;
+        name: string;
+        dialect: string;
+    }>;
+    onLoadTables?: (datasourceId: string) => Promise<string[]>;
+    onLoadSchema?: (datasourceId: string, table: string) => Promise<Array<{
+        name: string;
+        type: string;
+        nullable?: boolean;
+    }>>;
+    initialGraph?: WorkflowGraph | null;
+    onGraphChange?: (graph: WorkflowGraph) => void;
+    onEditTool?: (tool: WorkflowTool) => void;
+    onToggleTool?: (tool: WorkflowTool) => void;
+    onEditRule?: (rule: AgentRule) => void;
+    onToggleRule?: (rule: AgentRule) => void;
+    onCancelCreateAgent?: () => void;
+    onAgentSaved?: () => void;
+    isCreatingAgent?: boolean;
+    /** Custom node type components — merged with built-in edge types */
+    nodeTypes?: NodeTypes;
+    /** Optional: render the AgentModal externally (frontend provides the component) */
+    renderAgentModal?: (props: AgentModalRenderProps) => React.ReactNode;
+    /** Optional: render a custom LogicNodeModal; defaults to internal modal */
+    renderLogicNodeModal?: (props: LogicNodeModalRenderProps) => React.ReactNode;
+};
+declare function WorkflowCanvas(props: WorkflowCanvasProps): react_jsx_runtime.JSX.Element;
+
+type BuilderCanvasProps = ComponentProps<typeof WorkflowCanvas>;
+type WorkspaceProps = {
+    locale?: string;
+    messages?: Record<string, unknown>;
+    className?: string;
+    workflowId?: string;
+} & Partial<BuilderCanvasProps>;
+declare function Workspace({ locale, messages, className, workflowId, ...canvasProps }: WorkspaceProps): react_jsx_runtime.JSX.Element;
+
+export { type ModelProvider as M, NodePalette as N, type WorkspaceProps as W, Workspace as a };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datatechsolutions/ui",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -145,7 +145,11 @@
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",
-    "lint": "tsc --noEmit",
+    "lint": "tsc --noEmit && npm run lint:button",
+    "lint:button": "node scripts/check-raw-button.mjs",
+    "lint:button:baseline": "node scripts/check-raw-button.mjs --baseline",
+    "storybook": "storybook dev -p 6006 --no-open",
+    "build-storybook": "storybook build -o storybook-static",
     "verify:publish": "npm run build && npm run lint && npm run test",
     "prepublishOnly": "npm run verify:publish"
   },
@@ -158,8 +162,7 @@
     "typescript": "^5.3.0"
   },
   "peerDependencies": {
-    "@datatechsolutions/shared-domain": "^3.5.73",
-    "@datatechsolutions/windsock": "^1.5.0",
+    "@datatechsolutions/shared-domain": "workspace:*",
     "@headlessui/react": ">=2",
     "@heroicons/react": ">=2",
     "@radix-ui/react-dialog": ">=1",
@@ -178,7 +181,12 @@
     "zustand": ">=5"
   },
   "devDependencies": {
-    "@datatechsolutions/shared-domain": "^3.5.73",
+    "@datatechsolutions/shared-domain": "workspace:*",
+    "@storybook/addon-a11y": "^10.4.0",
+    "@storybook/addon-docs": "^10.4.0",
+    "@storybook/addon-themes": "^10.4.0",
+    "@storybook/react-vite": "^10.4.0",
+    "@tailwindcss/vite": "^4.3.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
@@ -190,6 +198,8 @@
     "@vitest/coverage-v8": "^4.0.18",
     "@xyflow/react": "^12.10.0",
     "jsdom": "^28.1.0",
+    "storybook": "^10.4.0",
+    "tailwindcss": "^4.3.0",
     "tsup": "^8.5.0",
     "vitest": "^4.0.16",
     "zustand": "^5.0.11"

package/src/styles/liquid-glass.css

@@ -3,6 +3,110 @@
    Translucent surfaces with backdrop-blur and inner highlights.
    ───────────────────────────────────────────────────── */
 
+/* ── Design tokens ─────────────────────────────────────
+   Versioned tokens — radius, elevation, motion.
+   These are the only knobs that should appear in component
+   styles. If you find yourself reaching for a hard-coded
+   shadow / radius / duration, promote it here first.
+   See DESIGN_SYSTEM.md → "Tokens" for usage guidance.
+   ───────────────────────────────────────────────────── */
+
+:root {
+  /* Radius scale — applied via `rounded-[var(--radius-md)]` or via
+     the `.r-{step}` utilities below. */
+  --radius-sm:   0.5rem;     /* 8px  — chips, tight controls */
+  --radius-md:   0.75rem;    /* 12px — inputs, small cards   */
+  --radius-lg:   1rem;       /* 16px — buttons, list items   */
+  --radius-xl:   1.25rem;    /* 20px — cards, panels         */
+  --radius-2xl:  1.5rem;     /* 24px — modals, hero surfaces */
+  --radius-pill: 9999px;     /* full round                   */
+
+  /* Elevation scale — semantic box-shadow tokens. The names map to
+     the surface's *role*, not a numeric depth, so consumers don't
+     have to remember whether a modal is z-3 or z-4. */
+  --elevation-flat:
+    0 1px 2px 0 rgba(15, 23, 42, 0.04);
+  --elevation-raised:
+    0 4px 12px -2px rgba(15, 23, 42, 0.08),
+    0 2px 4px -2px rgba(15, 23, 42, 0.04);
+  --elevation-floating:
+    0 12px 24px -8px rgba(15, 23, 42, 0.12),
+    0 4px 8px -4px rgba(15, 23, 42, 0.06);
+  --elevation-modal:
+    0 40px 100px -30px rgba(0, 0, 0, 0.45),
+    0 16px 40px -12px rgba(0, 0, 0, 0.18);
+  --elevation-orbital:
+    0 60px 160px -40px rgba(99, 102, 241, 0.35),
+    0 20px 60px -20px rgba(168, 85, 247, 0.22);
+
+  /* Motion: duration scale (matches Tailwind `duration-*` arbitrary
+     values). Animations: any consumer should pick a duration token
+     instead of inventing a number.
+
+     - xs (90ms)  — micro feedback (toggle thumb, hover tint)
+     - sm (150ms) — button press, popover open
+     - md (240ms) — card hover, drawer slide
+     - lg (360ms) — page transitions, modal enter */
+  --duration-xs: 90ms;
+  --duration-sm: 150ms;
+  --duration-md: 240ms;
+  --duration-lg: 360ms;
+
+  /* Motion: easing curves. `standard` is the default product curve;
+     `emphasized` is for entering elements; `decelerate` for arrivals;
+     `accelerate` for departures. */
+  --ease-standard:    cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-emphasized:  cubic-bezier(0.2, 0, 0, 1);
+  --ease-decelerate:  cubic-bezier(0, 0, 0.2, 1);
+  --ease-accelerate:  cubic-bezier(0.4, 0, 1, 1);
+  --ease-ios:         cubic-bezier(0.25, 0.46, 0.45, 0.94);
+}
+
+/* Dark mode keeps the same radius/duration tokens; only elevation
+   bumps darker so glass surfaces still feel lifted on dark grounds. */
+:is(.dark) {
+  --elevation-flat:
+    0 1px 2px 0 rgba(0, 0, 0, 0.4);
+  --elevation-raised:
+    0 4px 12px -2px rgba(0, 0, 0, 0.5),
+    0 2px 4px -2px rgba(0, 0, 0, 0.3);
+  --elevation-floating:
+    0 12px 24px -8px rgba(0, 0, 0, 0.6),
+    0 4px 8px -4px rgba(0, 0, 0, 0.4);
+  --elevation-modal:
+    0 40px 100px -30px rgba(0, 0, 0, 0.7),
+    0 16px 40px -12px rgba(0, 0, 0, 0.5);
+}
+
+/* Honor `prefers-reduced-motion` at the token layer — any consumer
+   reading `var(--duration-md)` automatically gets 0ms when the user
+   opts out. WCAG 2.3.3. */
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --duration-xs: 0ms;
+    --duration-sm: 0ms;
+    --duration-md: 0ms;
+    --duration-lg: 0ms;
+  }
+}
+
+/* ── Token utility classes ─────────────────────────────
+   Tiny wrappers so consumers can write `.r-md` instead of
+   `[border-radius:var(--radius-md)]`. */
+
+.r-sm   { border-radius: var(--radius-sm); }
+.r-md   { border-radius: var(--radius-md); }
+.r-lg   { border-radius: var(--radius-lg); }
+.r-xl   { border-radius: var(--radius-xl); }
+.r-2xl  { border-radius: var(--radius-2xl); }
+.r-pill { border-radius: var(--radius-pill); }
+
+.elevation-flat     { box-shadow: var(--elevation-flat); }
+.elevation-raised   { box-shadow: var(--elevation-raised); }
+.elevation-floating { box-shadow: var(--elevation-floating); }
+.elevation-modal    { box-shadow: var(--elevation-modal); }
+.elevation-orbital  { box-shadow: var(--elevation-orbital); }
+
 /* ── Surfaces ──────────────────────────────────────── */
 
 .liquid-surface {
@@ -354,6 +458,169 @@
   color: white;
 }
 
+/* ── Button — gradient (primary CTA, indigo→purple) ─
+   Same crystal-illuminated mechanic as the ios-glass-* variants:
+   neutral glass at rest, fills with translucent indigo→purple
+   gradient on hover + inner highlight + tinted drop shadow. The
+   gradient is ONLY visible on hover — at rest the button looks
+   identical to ios-glass-blue's neutral state. */
+
+.liquid-button-gradient {
+  /* Rest: same neutral glass as .liquid-button (so all CTAs read as
+     the same family at rest — gradient is the hover signal). */
+  background: rgb(255 255 255 / 0.35);
+  border: 1px solid rgb(255 255 255 / 0.5);
+  color: rgb(15 23 42); /* slate-900 — visible on glass at rest */
+  box-shadow:
+    0 8px 32px -8px rgb(0 0 0 / 0.12),
+    inset 0 1px 2px 0 rgb(255 255 255 / 0.25);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  transition: background 0.3s ease, box-shadow 0.3s ease, color 0.3s ease, border-color 0.3s ease;
+}
+
+.liquid-button-gradient:hover {
+  /* Hover: gradient fills + inner highlight + violet/indigo glow */
+  background: linear-gradient(
+    135deg,
+    rgba(99, 102, 241, 0.85) 0%,    /* indigo-500 */
+    rgba(139, 92, 246, 0.85) 50%,   /* violet-500 */
+    rgba(168, 85, 247, 0.85) 100%   /* purple-500 */
+  );
+  border-color: rgba(255, 255, 255, 0.45);
+  color: #ffffff;
+  box-shadow:
+    inset 0 1px 2px rgba(255, 255, 255, 0.6),
+    inset 0 -1px 1px rgba(0, 0, 0, 0.12),
+    0 12px 32px -8px rgba(99, 102, 241, 0.55),
+    0 0 24px -4px rgba(168, 85, 247, 0.35);
+  backdrop-filter: blur(12px) saturate(1.6);
+  -webkit-backdrop-filter: blur(12px) saturate(1.6);
+}
+
+.dark .liquid-button-gradient {
+  background: linear-gradient(
+    140deg,
+    rgba(30, 41, 59, 0.5) 0%,
+    rgba(15, 23, 42, 0.4) 45%,
+    rgba(15, 23, 42, 0.3) 100%
+  );
+  border-color: rgba(255, 255, 255, 0.18);
+  color: #ffffff;
+  box-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.18),
+    0 10px 22px -16px rgba(0, 0, 0, 0.75);
+}
+
+/* ── Avatar — crystal disc ───────────────────────────
+   Reusable shell that turns any avatar (image OR initials) into a
+   translucent crystal puck. Same family as .liquid-button-gradient
+   at rest — inner highlight on the top edge, tinted drop shadow,
+   saturate boost. Interactive avatars (AvatarButton) get a brighter
+   hover illuminate, matching the crystal-iluminado pattern. */
+
+.liquid-avatar {
+  position: relative;
+  overflow: hidden;
+  /* Slightly saturated so initials/photo colors look vivid through
+     the glass, not muted. */
+  filter: saturate(1.1);
+  /* OUTER shadow only — the inner highlight lives in `::after` so it
+     renders ABOVE the image content (an inset shadow would be hidden
+     by an opaque <img>). */
+  box-shadow:
+    0 4px 14px -3px rgba(15, 23, 42, 0.22),
+    0 1px 3px rgba(15, 23, 42, 0.08);
+}
+
+/* Specular highlight — soft white sheen across the top-left AND a
+   crisp 1px inner-edge highlight, both rendered on top of the
+   avatar content (image or initials) so the crystal effect survives
+   even when a photo fills the disc. */
+.liquid-avatar::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  pointer-events: none;
+  z-index: 1;
+  background: radial-gradient(
+    120% 80% at 30% 0%,
+    rgba(255, 255, 255, 0.45) 0%,
+    rgba(255, 255, 255, 0.12) 30%,
+    transparent 60%
+  );
+  /* Inner edge highlight — drawn via inset box-shadow on the pseudo
+     element so it sits over the image content. */
+  box-shadow:
+    inset 0 1.5px 2px rgba(255, 255, 255, 0.7),
+    inset 0 -1px 1.5px rgba(0, 0, 0, 0.08);
+  mix-blend-mode: screen;
+  transition: opacity 0.25s ease, box-shadow 0.25s ease;
+}
+
+.dark .liquid-avatar {
+  box-shadow:
+    0 6px 18px -4px rgba(0, 0, 0, 0.55),
+    0 1px 3px rgba(0, 0, 0, 0.3);
+}
+
+.dark .liquid-avatar::after {
+  background: radial-gradient(
+    120% 80% at 30% 0%,
+    rgba(255, 255, 255, 0.25) 0%,
+    rgba(255, 255, 255, 0.06) 30%,
+    transparent 60%
+  );
+  box-shadow:
+    inset 0 1.5px 2px rgba(255, 255, 255, 0.28),
+    inset 0 -1px 1.5px rgba(0, 0, 0, 0.4);
+}
+
+/* Interactive variant — hover illuminates the sheen + adds a soft
+   indigo glow, same crystal-iluminado mechanic as the buttons. */
+.liquid-avatar-interactive {
+  transition: transform 0.2s ease, box-shadow 0.3s ease;
+  cursor: pointer;
+}
+
+.liquid-avatar-interactive:hover {
+  transform: translateY(-1px);
+  /* `--avatar-glow` defaults to indigo; tone-styled avatars override
+     it inline so each avatar's hover glow matches its own tint. */
+  box-shadow:
+    inset 0 2px 3px rgba(255, 255, 255, 0.7),
+    inset 0 -1px 1.5px rgba(0, 0, 0, 0.06),
+    0 8px 22px -4px var(--avatar-glow, rgba(99, 102, 241, 0.35)),
+    0 2px 6px rgba(15, 23, 42, 0.12);
+}
+
+.liquid-avatar-interactive:hover::after {
+  opacity: 1.4;
+}
+
+.dark .liquid-avatar-interactive:hover {
+  box-shadow:
+    inset 0 2px 3px rgba(255, 255, 255, 0.32),
+    inset 0 -1px 1.5px rgba(0, 0, 0, 0.4),
+    0 10px 26px -6px rgba(129, 132, 251, 0.45),
+    0 2px 6px rgba(0, 0, 0, 0.4);
+}
+
+.dark .liquid-button-gradient:hover {
+  background: linear-gradient(
+    135deg,
+    rgba(129, 132, 251, 0.85) 0%,
+    rgba(167, 132, 246, 0.85) 50%,
+    rgba(196, 125, 247, 0.85) 100%
+  );
+  border-color: rgba(255, 255, 255, 0.35);
+  box-shadow:
+    inset 0 1px 2px rgba(255, 255, 255, 0.35),
+    0 14px 36px -10px rgba(129, 132, 251, 0.65),
+    0 0 28px -4px rgba(196, 125, 247, 0.45);
+}
+
 /* ── Filter pills — colored glassmorphism ──────────── */
 
 .liquid-pill {
@@ -519,10 +786,24 @@
 .liquid-pill:hover .liquid-pill-dismiss { opacity: 0.8; }
 
 /* ── Focus ring utilities ────────────────────────────
-   Replace verbose inline focus ring Tailwind classes with a single class.
-   Uses CSS outline (non-conflicting with box-shadow) for focus indicators.
+   Canonical focus indicator for the design system.
+
+   Use `.focus-ring` on any interactive element — it ships the
+   indigo 2px outline at /70 opacity with a 1px offset, matching
+   the WCAG 1.4.11 (≥ 3:1 non-text contrast) + 2.4.7 (visible
+   focus) floor documented in DESIGN_SYSTEM.md.
+
+   The legacy `.focus-ring-{color}` classes remain for cases where
+   a component owns its own accent color (e.g. emerald confirm
+   buttons), but new code should default to `.focus-ring`.
    ───────────────────────────────────────────────────── */
 
+.focus-ring:focus { outline: none; }
+.focus-ring:focus-visible {
+  outline: 2px solid color-mix(in oklab, var(--color-indigo-500) 70%, transparent);
+  outline-offset: 1px;
+}
+
 .focus-ring-blue:focus { outline: none; }
 .focus-ring-blue:focus-visible {
   outline: 2px solid var(--color-blue-500);