@sovereignfs/ui 0.21.0

package/dist/tokens/primitives.css

@@ -0,0 +1,99 @@
+/*
+ * Sovereign Design System — primitive tokens.
+ *
+ * Raw, context-free scales: the palette, spacing, type, and radii. These are
+ * fixed — tenant theming never overrides primitives (it overrides the semantic
+ * layer in semantic.css). Plugin code should reference SEMANTIC colour tokens,
+ * not these primitives directly.
+ */
+:root {
+  /* Neutral grey scale (monochrome identity) */
+  --sv-white: #ffffff;
+
+  /* Status colour primitives — amber (warning), green (success), red (error), blue (info).
+     Kept minimal: only the swatches the semantic status tokens reference.
+     Hex values align with the v3.1 design spec. */
+  --sv-amber-100: #fff7ed;
+  --sv-amber-200: #fed7aa;
+  --sv-amber-800: #b45309;
+  --sv-amber-900: #92400e;
+  --sv-green-100: #ecfdf3;
+  --sv-green-200: #bbf7d0;
+  --sv-green-800: #167c4a;
+  --sv-green-900: #14532d;
+  --sv-red-100: #fef2f2;
+  --sv-red-200: #fecaca;
+  --sv-red-700: #b91c1c;
+  --sv-red-800: #991b1b;
+  --sv-red-900: #7f1d1d;
+  --sv-blue-100: #eff6ff;
+  --sv-blue-200: #dbeafe;
+  --sv-blue-800: #1d4ed8;
+  --sv-blue-900: #1e3a8a;
+  --sv-black: #000000;
+  --sv-grey-50: #fafafa;
+  --sv-grey-100: #f4f4f5;
+  --sv-grey-200: #e4e4e7;
+  --sv-grey-300: #d4d4d8;
+  --sv-grey-400: #a1a1aa;
+  --sv-grey-500: #71717a;
+  --sv-grey-600: #52525b;
+  --sv-grey-700: #3f3f46;
+  --sv-grey-800: #27272a;
+  --sv-grey-900: #18181b;
+  --sv-grey-950: #09090b;
+
+  /* Spacing scale (4px base) */
+  --sv-space-1: 0.25rem;
+  --sv-space-2: 0.5rem;
+  --sv-space-3: 0.75rem;
+  --sv-space-4: 1rem;
+  --sv-space-5: 1.25rem;
+  --sv-space-6: 1.5rem;
+  --sv-space-8: 2rem;
+  --sv-space-10: 2.5rem;
+  --sv-space-12: 3rem;
+  --sv-space-16: 4rem;
+
+  /* Typography
+     Default pair: Hanken Grotesk (body) + JetBrains Mono (code/identifiers).
+     Operators supply the web font via <link> or instance CSS; the fallback
+     stack applies when the font is not loaded. */
+  --sv-font-family:
+    'Hanken Grotesk', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial,
+    sans-serif;
+  --sv-font-family-mono:
+    'JetBrains Mono', ui-monospace, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
+  --sv-font-size-label: 0.6875rem; /* 11px — all-caps section labels */
+  --sv-font-size-xs: 0.75rem; /* 12px — mono identifiers */
+  --sv-font-size-caption: 0.8125rem; /* 13px — secondary / supporting copy */
+  --sv-font-size-sm: 0.875rem; /* 14px — body copy */
+  --sv-font-size-md: 1rem; /* 16px */
+  --sv-font-size-lg: 1.125rem; /* 18px */
+  --sv-font-size-xl: 1.25rem; /* 20px */
+  --sv-font-size-2xl: 1.5rem; /* 24px */
+  --sv-font-weight-regular: 400;
+  --sv-font-weight-medium: 500;
+  --sv-font-weight-semibold: 600;
+  --sv-font-weight-bold: 700;
+
+  /* Icon sizes — scale tokens used directly by the Icon component */
+  --sv-icon-size-sm: 1rem; /* 16px — inline with body text */
+  --sv-icon-size-md: 1.25rem; /* 20px — standard affordance */
+  --sv-icon-size-lg: 1.5rem; /* 24px — prominent / standalone */
+
+  /* Border radii (v3.1 spec values) */
+  --sv-radius-sm: 0.375rem; /* 6px — badge, tag */
+  --sv-radius-md: 0.5rem; /* 8px — button, input */
+  --sv-radius-lg: 0.6875rem; /* 11px — sidebar icon, card */
+  --sv-radius-xl: 0.75rem; /* 12px — card, panel */
+  --sv-radius-2xl: 0.875rem; /* 14px — popover */
+  --sv-radius-3xl: 1.25rem; /* 20px — bottom sheet (Drawer top corners) */
+  --sv-radius-full: 9999px; /* pill / avatar */
+
+  /* Touch targets — minimum hit-area dimension for interactive controls.
+     44px follows the WCAG 2.5.5 / Apple HIG / Material guideline for reliable
+     touch without a pointing device. Applied to icon-only controls on mobile
+     (avatar, footer button, Drawer nav items). */
+  --sv-touch-target-min: 44px;
+}

package/dist/tokens/semantic.css

@@ -0,0 +1,111 @@
+/*
+ * Sovereign Design System — semantic tokens.
+ *
+ * Contextual roles mapped from primitives. THIS is the theming surface: dark
+ * mode and tenant theming work by overriding these values at :root (or under
+ * [data-theme]) — no component changes required. Every value here references a
+ * primitive token; none is a hardcoded literal (except shadows and the scrim,
+ * which compose rgba layers).
+ *
+ * Identity is monochrome: the accent is near-black on light, near-white on dark.
+ * A tenant gives Sovereign its own colour by overriding --sv-color-accent.
+ */
+:root {
+  --sv-color-surface: var(--sv-white);
+  --sv-color-surface-sunken: var(--sv-grey-50);
+  --sv-color-surface-raised: var(--sv-white);
+
+  --sv-color-text-primary: var(--sv-grey-950);
+  --sv-color-text-muted: var(--sv-grey-500);
+  --sv-color-text-subtle: var(--sv-grey-400);
+  --sv-color-text-on-accent: var(--sv-white);
+
+  --sv-color-border: var(--sv-grey-200);
+  --sv-color-border-strong: var(--sv-grey-300);
+
+  --sv-color-accent: var(--sv-grey-900);
+  --sv-color-accent-hover: var(--sv-grey-700);
+
+  --sv-color-focus-ring: var(--sv-grey-900);
+
+  /* Status surfaces — error (red), warning (amber), success (green).
+     Use these for banners, badges, and inline validation UI.
+     Never hardcode colour hex in components — reference these tokens. */
+  --sv-color-error-surface: var(--sv-red-100);
+  --sv-color-error-text: var(--sv-red-800);
+  --sv-color-error-border: var(--sv-red-200);
+  --sv-color-warning-surface: var(--sv-amber-100);
+  --sv-color-warning-text: var(--sv-amber-800);
+  --sv-color-warning-border: var(--sv-amber-200);
+  --sv-color-success-surface: var(--sv-green-100);
+  --sv-color-success-text: var(--sv-green-800);
+  --sv-color-success-border: var(--sv-green-200);
+
+  /* Info surfaces — blue palette. Use for informational banners and badges.
+     Never hardcode colour hex in components — reference these tokens. */
+  --sv-color-info-surface: var(--sv-blue-100);
+  --sv-color-info-text: var(--sv-blue-800);
+  --sv-color-info-border: var(--sv-blue-200);
+
+  /* Overlay surfaces (Dialog/Sheet): the scrim behind a dialog and the panel's
+     elevation shadow. Composed rgba layers, like --sv-shadow-card. */
+  --sv-color-scrim: rgba(0, 0, 0, 0.5);
+
+  --sv-shadow-card: 0 1px 2px rgba(0, 0, 0, 0.06), 0 1px 3px rgba(0, 0, 0, 0.1);
+  --sv-shadow-hover: 0 2px 6px rgba(0, 0, 0, 0.08); /* e1 — card hover lift */
+  --sv-shadow-popover:
+    0 4px 16px rgba(0, 0, 0, 0.14), 0 2px 6px rgba(0, 0, 0, 0.08); /* e2 — floating panels */
+  --sv-shadow-overlay: 0 10px 38px rgba(0, 0, 0, 0.18), 0 6px 12px rgba(0, 0, 0, 0.12);
+
+  /*
+   * Instance identity tokens (RFC 0027 / RFC 0032 rename). Distinct namespace from --sv-color-*:
+   * these hold URLs (not colours) and are set once by the operator, not swapped
+   * with dark mode. Set by InstanceProvider server component from instance_config DB.
+   * CSS: background-image: var(--sv-instance-logo);
+   *   or <img src="var(--sv-instance-logo)"> is NOT correct — use the InstanceProvider
+   *   prop `instanceName` and the /api/instance/* routes for the actual URLs.
+   */
+  --sv-instance-logo: none;
+  --sv-instance-logo-dark: none;
+  --sv-instance-favicon: none;
+}
+
+[data-theme='dark'] {
+  --sv-color-surface: var(--sv-grey-950);
+  --sv-color-surface-sunken: var(--sv-grey-900);
+  --sv-color-surface-raised: var(--sv-grey-900);
+
+  --sv-color-text-primary: var(--sv-grey-50);
+  --sv-color-text-muted: var(--sv-grey-400);
+  --sv-color-text-subtle: var(--sv-grey-600);
+  --sv-color-text-on-accent: var(--sv-grey-950);
+
+  --sv-color-border: var(--sv-grey-800);
+  --sv-color-border-strong: var(--sv-grey-700);
+
+  --sv-color-accent: var(--sv-grey-50);
+  --sv-color-accent-hover: var(--sv-grey-200);
+
+  --sv-color-focus-ring: var(--sv-grey-100);
+
+  --sv-color-error-surface: var(--sv-red-900);
+  --sv-color-error-text: var(--sv-red-200);
+  --sv-color-error-border: var(--sv-red-700);
+  --sv-color-warning-surface: var(--sv-amber-900);
+  --sv-color-warning-text: var(--sv-amber-200);
+  --sv-color-warning-border: var(--sv-amber-800);
+  --sv-color-success-surface: var(--sv-green-900);
+  --sv-color-success-text: var(--sv-green-200);
+  --sv-color-success-border: var(--sv-green-800);
+
+  --sv-color-info-surface: var(--sv-blue-900);
+  --sv-color-info-text: var(--sv-blue-100);
+  --sv-color-info-border: var(--sv-blue-800);
+
+  --sv-color-scrim: rgba(0, 0, 0, 0.65);
+
+  --sv-shadow-card: 0 1px 2px rgba(0, 0, 0, 0.4), 0 1px 3px rgba(0, 0, 0, 0.5);
+  --sv-shadow-hover: 0 2px 6px rgba(0, 0, 0, 0.3);
+  --sv-shadow-popover: 0 4px 16px rgba(0, 0, 0, 0.5), 0 2px 6px rgba(0, 0, 0, 0.3);
+  --sv-shadow-overlay: 0 10px 38px rgba(0, 0, 0, 0.6), 0 6px 12px rgba(0, 0, 0, 0.5);
+}

package/dist/tokens.css

@@ -0,0 +1,5 @@
+/* Convenience entry that loads both token tiers. The runtime shell imports this
+ * once so --sv-* variables are available globally (primitives first, then the
+ * semantic layer that maps them). */
+@import './tokens/primitives.css';
+@import './tokens/semantic.css';

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@sovereignfs/ui",
+  "version": "0.21.0",
+  "type": "module",
+  "description": "Sovereign Design System — design tokens and React components.",
+  "license": "AGPL-3.0-or-later",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./tokens.css": "./dist/tokens.css",
+    "./tokens/primitives.css": "./dist/tokens/primitives.css",
+    "./tokens/semantic.css": "./dist/tokens/semantic.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "NOTICE"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@storybook/addon-a11y": "^10.4.6",
+    "@storybook/addon-themes": "^10.4.6",
+    "@storybook/react-vite": "^10.4.6",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "storybook": "^10.4.6",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "@sovereignfs/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build --output-dir storybook-static",
+    "typecheck": "tsc --noEmit"
+  },
+  "types": "./dist/index.d.ts"
+}

package/src/components/Avatar/Avatar.module.css

@@ -0,0 +1,38 @@
+.avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  background: var(--sv-color-surface-raised);
+  border: 1px solid var(--sv-color-border);
+  overflow: hidden;
+  flex-shrink: 0;
+  font-weight: var(--sv-font-weight-medium);
+  color: var(--sv-color-text-primary);
+  font-family: var(--sv-font-family);
+}
+
+.sm {
+  width: 24px;
+  height: 24px;
+  font-size: var(--sv-font-size-label);
+}
+
+.md {
+  width: 32px;
+  height: 32px;
+  font-size: var(--sv-font-size-xs);
+}
+
+.lg {
+  width: 40px;
+  height: 40px;
+  font-size: var(--sv-font-size-sm);
+}
+
+.img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}

package/src/components/Avatar/Avatar.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import { useState } from 'react';
+import styles from './Avatar.module.css';
+
+export interface AvatarProps {
+  name: string;
+  src?: string;
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+}
+
+function initials(name: string): string {
+  const parts = name.trim().split(/\s+/);
+  if (parts.length === 1) return (parts[0] ?? '').slice(0, 2).toUpperCase();
+  return ((parts[0]?.[0] ?? '') + (parts[parts.length - 1]?.[0] ?? '')).toUpperCase();
+}
+
+const sizeClass: Record<NonNullable<AvatarProps['size']>, string> = {
+  sm: styles.sm as string,
+  md: styles.md as string,
+  lg: styles.lg as string,
+};
+
+export function Avatar({ name, src, size = 'md', className }: AvatarProps) {
+  const [imgFailed, setImgFailed] = useState(false);
+  const cls = [styles.avatar, sizeClass[size], className].filter(Boolean).join(' ');
+
+  if (src && !imgFailed) {
+    return (
+      <span className={cls} aria-label={name}>
+        <img src={src} alt={name} className={styles.img} onError={() => setImgFailed(true)} />
+      </span>
+    );
+  }
+
+  return (
+    <span className={cls} aria-label={name}>
+      {initials(name)}
+    </span>
+  );
+}

package/src/components/Badge/Badge.module.css

@@ -0,0 +1,88 @@
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--sv-space-1);
+  border-radius: var(--sv-radius-sm);
+  font-family: var(--sv-font-family);
+  font-size: var(--sv-font-size-xs);
+  line-height: 1;
+  white-space: nowrap;
+  user-select: none;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+/* role — neutral fill, border, title case */
+.role {
+  padding: 2px var(--sv-space-2);
+  background: var(--sv-color-surface-sunken);
+  border: 1px solid var(--sv-color-border);
+  color: var(--sv-color-text-primary);
+  font-size: var(--sv-font-size-label);
+  font-weight: var(--sv-font-weight-semibold);
+}
+
+/* status — tinted chip with leading colour dot; colour set by chip* classes below */
+.status {
+  padding: 2px var(--sv-space-2) 2px var(--sv-space-1);
+  font-weight: var(--sv-font-weight-medium);
+}
+
+.chipGreen {
+  background: var(--sv-color-success-surface);
+  border: 1px solid var(--sv-color-success-border);
+  color: var(--sv-color-success-text);
+}
+
+.chipAmber {
+  background: var(--sv-color-warning-surface);
+  border: 1px solid var(--sv-color-warning-border);
+  color: var(--sv-color-warning-text);
+}
+
+.chipRed {
+  background: var(--sv-color-error-surface);
+  border: 1px solid var(--sv-color-error-border);
+  color: var(--sv-color-error-text);
+}
+
+.chipNeutral {
+  background: var(--sv-color-surface-sunken);
+  border: 1px solid var(--sv-color-border);
+  color: var(--sv-color-text-muted);
+}
+
+/* mono — monospace font, neutral surface, for type tags / versions */
+.mono {
+  padding: 2px var(--sv-space-2);
+  background: var(--sv-color-surface-sunken);
+  border: 1px solid var(--sv-color-border);
+  color: var(--sv-color-text-muted);
+  font-family: var(--sv-font-family-mono);
+  font-size: var(--sv-font-size-xs);
+}
+
+/* Status dot */
+.dot {
+  display: inline-block;
+  width: 6px;
+  height: 6px;
+  border-radius: var(--sv-radius-full);
+  flex-shrink: 0;
+}
+
+.dotGreen {
+  background: var(--sv-color-success-text);
+}
+
+.dotRed {
+  background: var(--sv-color-error-text);
+}
+
+.dotAmber {
+  background: var(--sv-color-warning-text);
+}
+
+.dotGrey {
+  background: var(--sv-color-text-muted);
+}

package/src/components/Badge/Badge.stories.tsx

@@ -0,0 +1,118 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Badge } from './Badge';
+import type { BadgeStatus } from './Badge';
+
+const meta = {
+  title: 'Components/Badge',
+  component: Badge,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Compact label for roles (`role`), lifecycle states (`status`), and type/version tags (`mono`). RSC-safe — no state.',
+      },
+    },
+  },
+  argTypes: {
+    variant: { control: 'select', options: ['role', 'status', 'mono'] },
+    status: {
+      control: 'select',
+      options: ['active', 'enabled', 'deactivated', 'failed', 'invited', 'pending', 'neutral'],
+    },
+  },
+  args: { children: 'Badge' },
+} satisfies Meta<typeof Badge>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+
+export const Role: Story = { args: { variant: 'role', children: 'Owner' } };
+export const RoleAdmin: Story = { args: { variant: 'role', children: 'Admin' } };
+export const RoleUser: Story = { args: { variant: 'role', children: 'User' } };
+export const RoleAuditor: Story = { args: { variant: 'role', children: 'Auditor' } };
+
+export const StatusActive: Story = {
+  args: { variant: 'status', status: 'active', children: 'Active' },
+};
+export const StatusDeactivated: Story = {
+  args: { variant: 'status', status: 'deactivated', children: 'Deactivated' },
+};
+export const StatusInvited: Story = {
+  args: { variant: 'status', status: 'invited', children: 'Invited' },
+};
+export const StatusFailed: Story = {
+  args: { variant: 'status', status: 'failed', children: 'Failed' },
+};
+export const StatusPending: Story = {
+  args: { variant: 'status', status: 'pending', children: 'Pending' },
+};
+
+export const MonoPlatform: Story = { args: { variant: 'mono', children: 'platform' } };
+export const MonoCommunity: Story = { args: { variant: 'mono', children: 'community' } };
+export const MonoVersion: Story = { args: { variant: 'mono', children: 'v0.1.0' } };
+
+/** All variants and statuses at a glance. */
+export const AllVariants: Story = {
+  render: (_args) => {
+    const roleLabels = ['Owner', 'Admin', 'User', 'Auditor'];
+    const statuses: { status: BadgeStatus; label: string }[] = [
+      { status: 'active', label: 'Active' },
+      { status: 'enabled', label: 'Enabled' },
+      { status: 'deactivated', label: 'Deactivated' },
+      { status: 'failed', label: 'Failed' },
+      { status: 'invited', label: 'Invited' },
+      { status: 'pending', label: 'Pending' },
+      { status: 'neutral', label: 'Neutral' },
+    ];
+    const monoLabels = ['platform', 'community', 'serve-route', 'v0.1.0', 'admin-only'];
+
+    const groupStyle: React.CSSProperties = { display: 'flex', flexWrap: 'wrap', gap: 8 };
+    const sectionStyle: React.CSSProperties = { display: 'flex', flexDirection: 'column', gap: 8 };
+    const headingStyle: React.CSSProperties = {
+      fontSize: 11,
+      fontWeight: 600,
+      letterSpacing: '0.05em',
+      textTransform: 'uppercase',
+      color: 'var(--sv-color-text-muted)',
+      fontFamily: 'var(--sv-font-family)',
+    };
+
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 24, padding: 16 }}>
+        <div style={sectionStyle}>
+          <span style={headingStyle}>Role</span>
+          <div style={groupStyle}>
+            {roleLabels.map((l) => (
+              <Badge key={l} variant="role">
+                {l}
+              </Badge>
+            ))}
+          </div>
+        </div>
+        <div style={sectionStyle}>
+          <span style={headingStyle}>Status</span>
+          <div style={groupStyle}>
+            {statuses.map(({ status, label }) => (
+              <Badge key={status} variant="status" status={status}>
+                {label}
+              </Badge>
+            ))}
+          </div>
+        </div>
+        <div style={sectionStyle}>
+          <span style={headingStyle}>Mono</span>
+          <div style={groupStyle}>
+            {monoLabels.map((l) => (
+              <Badge key={l} variant="mono">
+                {l}
+              </Badge>
+            ))}
+          </div>
+        </div>
+      </div>
+    );
+  },
+};

package/src/components/Badge/Badge.tsx

@@ -0,0 +1,59 @@
+import type { ReactNode } from 'react';
+import styles from './Badge.module.css';
+
+export type BadgeVariant = 'role' | 'status' | 'mono';
+export type BadgeStatus =
+  | 'active'
+  | 'enabled'
+  | 'deactivated'
+  | 'failed'
+  | 'invited'
+  | 'pending'
+  | 'neutral';
+
+export interface BadgeProps {
+  variant?: BadgeVariant;
+  /** Only relevant when variant="status" — determines the dot colour. */
+  status?: BadgeStatus;
+  children: ReactNode;
+}
+
+const STATUS_DOT_CLASS: Record<BadgeStatus, string> = {
+  active: styles.dotGreen as string,
+  enabled: styles.dotGreen as string,
+  deactivated: styles.dotRed as string,
+  failed: styles.dotRed as string,
+  invited: styles.dotAmber as string,
+  pending: styles.dotAmber as string,
+  neutral: styles.dotGrey as string,
+};
+
+const STATUS_CHIP_CLASS: Record<BadgeStatus, string> = {
+  active: styles.chipGreen as string,
+  enabled: styles.chipGreen as string,
+  deactivated: styles.chipRed as string,
+  failed: styles.chipRed as string,
+  invited: styles.chipAmber as string,
+  pending: styles.chipAmber as string,
+  neutral: styles.chipNeutral as string,
+};
+
+/**
+ * Badge — compact label for roles, lifecycle states, and type/version tags.
+ *
+ * - `role`   neutral surface + border, semibold — for Owner / Admin / User
+ * - `status` tinted chip with leading colour dot — for Active / Deactivated / etc.
+ * - `mono`   monospace font, neutral surface — for platform / community / v0.1.0
+ */
+export function Badge({ variant = 'role', status = 'neutral', children }: BadgeProps) {
+  const isStatus = variant === 'status';
+  const dotClass = isStatus ? STATUS_DOT_CLASS[status] : undefined;
+  const chipClass = isStatus ? STATUS_CHIP_CLASS[status] : undefined;
+
+  return (
+    <span className={[styles.badge, styles[variant], chipClass].filter(Boolean).join(' ')}>
+      {isStatus && <span className={[styles.dot, dotClass].join(' ')} aria-hidden />}
+      {children}
+    </span>
+  );
+}

package/src/components/Badge/__tests__/Badge.test.tsx

@@ -0,0 +1,64 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { Badge } from '../Badge';
+
+describe('Badge', () => {
+  it('renders its children', () => {
+    render(<Badge>Owner</Badge>);
+    expect(screen.getByText('Owner')).toBeDefined();
+  });
+
+  it('defaults to role variant', () => {
+    render(<Badge>Admin</Badge>);
+    expect(screen.getByText('Admin').closest('span')?.className).toContain('role');
+  });
+
+  it('applies mono variant class', () => {
+    render(<Badge variant="mono">platform</Badge>);
+    expect(screen.getByText('platform').closest('span')?.className).toContain('mono');
+  });
+
+  it('renders status variant with a dot element', () => {
+    const { container } = render(
+      <Badge variant="status" status="active">
+        Active
+      </Badge>,
+    );
+    const dots = container.querySelectorAll('[aria-hidden]');
+    expect(dots.length).toBe(1);
+    expect(dots.item(0).className).toContain('dotGreen');
+  });
+
+  it('uses red dot for deactivated status', () => {
+    const { container } = render(
+      <Badge variant="status" status="deactivated">
+        Deactivated
+      </Badge>,
+    );
+    expect(container.querySelector('[aria-hidden]')?.className).toContain('dotRed');
+  });
+
+  it('uses amber dot for invited status', () => {
+    const { container } = render(
+      <Badge variant="status" status="invited">
+        Invited
+      </Badge>,
+    );
+    expect(container.querySelector('[aria-hidden]')?.className).toContain('dotAmber');
+  });
+
+  it('uses grey dot for neutral status', () => {
+    const { container } = render(
+      <Badge variant="status" status="neutral">
+        Neutral
+      </Badge>,
+    );
+    expect(container.querySelector('[aria-hidden]')?.className).toContain('dotGrey');
+  });
+
+  it('does not render a dot for role variant', () => {
+    const { container } = render(<Badge variant="role">Owner</Badge>);
+    expect(container.querySelectorAll('[aria-hidden]').length).toBe(0);
+  });
+});