@open-mercato/core 0.6.7-develop.6785.1.1dd7cfac55 → 0.6.7-develop.6795.1.8a3f27921c

package/src/modules/data_sync/api/runs.ts

@@ -1,5 +1,6 @@
 import { NextResponse } from 'next/server'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { organizationScopeRequiredResponse, resolveActiveOrganizationId } from '@open-mercato/shared/lib/auth/organizationScope'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { listSyncRunsQuerySchema } from '../data/validators'
 import type { SyncRunService } from '../lib/sync-run-service'
@@ -15,9 +16,13 @@ export const openApi = {
 
 export async function GET(req: Request) {
   const auth = await getAuthFromRequest(req)
-  if (!auth?.tenantId || !auth.orgId) {
+  if (!auth?.tenantId) {
     return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   }
+  const organizationId = resolveActiveOrganizationId(auth)
+  if (!organizationId) {
+    return organizationScopeRequiredResponse()
+  }
 
   const url = new URL(req.url)
   const parsed = listSyncRunsQuerySchema.safeParse({
@@ -38,7 +43,7 @@ export async function GET(req: Request) {
   const syncRunService = container.resolve('dataSyncRunService') as SyncRunService
 
   const { items, total } = await syncRunService.listRuns(parsed.data, {
-    organizationId: auth.orgId as string,
+    organizationId,
     tenantId: auth.tenantId,
   })
 

package/src/modules/data_sync/api/schedules/[id]/route.ts

@@ -1,6 +1,7 @@
 import { NextResponse } from 'next/server'
 import { z } from 'zod'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { organizationScopeRequiredResponse, resolveActiveOrganizationId } from '@open-mercato/shared/lib/auth/organizationScope'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
 import { readOptimisticLockExpected } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
@@ -30,9 +31,13 @@ export const openApi = {
 
 export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }> | { id?: string } }) {
   const auth = await getAuthFromRequest(req)
-  if (!auth?.tenantId || !auth.orgId) {
+  if (!auth?.tenantId) {
     return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   }
+  const organizationId = resolveActiveOrganizationId(auth)
+  if (!organizationId) {
+    return organizationScopeRequiredResponse()
+  }
 
   const rawParams = (ctx.params && typeof (ctx.params as Promise<unknown>).then === 'function')
     ? await (ctx.params as Promise<{ id?: string }>)
@@ -46,7 +51,7 @@ export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }>
   const container = await createRequestContainer()
   const scheduleService = container.resolve('dataSyncScheduleService') as SyncScheduleService
   const schedule = await scheduleService.getById(parsedParams.data.id, {
-    organizationId: auth.orgId as string,
+    organizationId,
     tenantId: auth.tenantId,
   })
 
@@ -59,9 +64,13 @@ export async function GET(req: Request, ctx: { params?: Promise<{ id?: string }>
 
 export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }> | { id?: string } }) {
   const auth = await getAuthFromRequest(req)
-  if (!auth?.tenantId || !auth.orgId) {
+  if (!auth?.tenantId) {
     return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   }
+  const organizationId = resolveActiveOrganizationId(auth)
+  if (!organizationId) {
+    return organizationScopeRequiredResponse()
+  }
 
   const rawParams = (ctx.params && typeof (ctx.params as Promise<unknown>).then === 'function')
     ? await (ctx.params as Promise<{ id?: string }>)
@@ -80,7 +89,7 @@ export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }>
 
   const container = await createRequestContainer()
   const scheduleService = container.resolve('dataSyncScheduleService') as SyncScheduleService
-  const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+  const scope = { organizationId, tenantId: auth.tenantId }
   const current = await scheduleService.getById(parsedParams.data.id, scope)
 
   if (!current) {
@@ -141,9 +150,13 @@ export async function PUT(req: Request, ctx: { params?: Promise<{ id?: string }>
 
 export async function DELETE(req: Request, ctx: { params?: Promise<{ id?: string }> | { id?: string } }) {
   const auth = await getAuthFromRequest(req)
-  if (!auth?.tenantId || !auth.orgId) {
+  if (!auth?.tenantId) {
     return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   }
+  const organizationId = resolveActiveOrganizationId(auth)
+  if (!organizationId) {
+    return organizationScopeRequiredResponse()
+  }
 
   const rawParams = (ctx.params && typeof (ctx.params as Promise<unknown>).then === 'function')
     ? await (ctx.params as Promise<{ id?: string }>)
@@ -156,7 +169,7 @@ export async function DELETE(req: Request, ctx: { params?: Promise<{ id?: string
 
   const container = await createRequestContainer()
   const scheduleService = container.resolve('dataSyncScheduleService') as SyncScheduleService
-  const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+  const scope = { organizationId, tenantId: auth.tenantId }
 
   const guardResult = await validateCrudMutationGuard(container, {
     tenantId: auth.tenantId,

package/src/modules/data_sync/api/schedules/route.ts

@@ -1,5 +1,6 @@
 import { NextResponse } from 'next/server'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { organizationScopeRequiredResponse, resolveActiveOrganizationId } from '@open-mercato/shared/lib/auth/organizationScope'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
 import { createSyncScheduleSchema, listSyncSchedulesQuerySchema } from '../../data/validators'
@@ -24,9 +25,13 @@ export const openApi = {
 
 export async function GET(req: Request) {
   const auth = await getAuthFromRequest(req)
-  if (!auth?.tenantId || !auth.orgId) {
+  if (!auth?.tenantId) {
     return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   }
+  const organizationId = resolveActiveOrganizationId(auth)
+  if (!organizationId) {
+    return organizationScopeRequiredResponse()
+  }
 
   const url = new URL(req.url)
   const parsed = listSyncSchedulesQuerySchema.safeParse({
@@ -43,7 +48,7 @@ export async function GET(req: Request) {
 
   const container = await createRequestContainer()
   const scheduleService = container.resolve('dataSyncScheduleService') as SyncScheduleService
-  const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+  const scope = { organizationId, tenantId: auth.tenantId }
   const { items, total } = await scheduleService.listSchedules(parsed.data, scope)
 
   return NextResponse.json({
@@ -57,9 +62,13 @@ export async function GET(req: Request) {
 
 export async function POST(req: Request) {
   const auth = await getAuthFromRequest(req)
-  if (!auth?.tenantId || !auth.orgId) {
+  if (!auth?.tenantId) {
     return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   }
+  const organizationId = resolveActiveOrganizationId(auth)
+  if (!organizationId) {
+    return organizationScopeRequiredResponse()
+  }
 
   const payload = await readJsonSafe(req)
   const parsed = createSyncScheduleSchema.safeParse(payload)
@@ -69,7 +78,7 @@ export async function POST(req: Request) {
 
   const container = await createRequestContainer()
   const scheduleService = container.resolve('dataSyncScheduleService') as SyncScheduleService
-  const scope = { organizationId: auth.orgId as string, tenantId: auth.tenantId }
+  const scope = { organizationId, tenantId: auth.tenantId }
 
   const guardResult = await validateCrudMutationGuard(container, {
     tenantId: auth.tenantId,

package/src/modules/data_sync/api/validate.ts

@@ -1,5 +1,6 @@
 import { NextResponse } from 'next/server'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { organizationScopeRequiredResponse, resolveActiveOrganizationId } from '@open-mercato/shared/lib/auth/organizationScope'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getIntegration } from '@open-mercato/shared/modules/integrations/types'
 import type { CredentialsService } from '../../integrations/lib/credentials-service'
@@ -17,9 +18,13 @@ export const openApi = {
 
 export async function POST(req: Request) {
   const auth = await getAuthFromRequest(req)
-  if (!auth?.tenantId || !auth.orgId) {
+  if (!auth?.tenantId) {
     return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   }
+  const organizationId = resolveActiveOrganizationId(auth)
+  if (!organizationId) {
+    return organizationScopeRequiredResponse()
+  }
 
   const parsed = validateConnectionSchema.safeParse(await req.json())
   if (!parsed.success) {
@@ -39,7 +44,7 @@ export async function POST(req: Request) {
   const container = await createRequestContainer()
   const credentialsService = container.resolve('integrationCredentialsService') as CredentialsService
   const credentials = await credentialsService.resolve(integration.id, {
-    organizationId: auth.orgId as string,
+    organizationId,
     tenantId: auth.tenantId,
   })
 
@@ -50,7 +55,7 @@ export async function POST(req: Request) {
   const mapping = await adapter.getMapping({
     entityType: parsed.data.entityType,
     scope: {
-      organizationId: auth.orgId as string,
+      organizationId,
       tenantId: auth.tenantId,
     },
   })
@@ -64,7 +69,7 @@ export async function POST(req: Request) {
     credentials,
     mapping,
     scope: {
-      organizationId: auth.orgId as string,
+      organizationId,
       tenantId: auth.tenantId,
     },
   })

package/src/modules/design_system/AGENTS.md

@@ -0,0 +1,34 @@
+# Design System Module — Agent Guidelines
+
+Live component gallery at `/backend/design-system`, gated by `design_system.view`. Entries are plain data (`gallery/entries/<family>.tsx`) listed in the family manifest (`gallery/registry.ts`) and lazy-loaded per family. The gallery is a DS consumer: it must showcase the DS without ever violating it.
+
+## Registry Contract
+
+- `gallery/types.ts` defines `GalleryVariant` / `GalleryEntry` / `GalleryFamily` — do not extend them casually; the shapes are the spec contract (`.ai/specs/2026-07-05-ds-live-component-gallery.md`).
+- A family = one manifest row in `galleryFamilies` + one `entries/<id>.tsx` exporting `entries: GalleryEntry[]`.
+- Every variant keeps `render` and `code` side by side in one object literal; review them together — colocation is the drift defense.
+
+## Always
+
+1. **MUST keep every variant `code` snippet containing the entry's `importPath`** — enforced by `gallery/__tests__/registry-integrity.test.ts`.
+2. **MUST update the coverage allowlist honestly** — when adding a primitive entry, delete its row from `PENDING_FAMILIES` in `gallery/__tests__/gallery-coverage.test.ts`; when a new primitive lands without an entry, add it there with a one-line reason. `PENDING_FAMILIES` must only shrink as families land.
+3. **MUST use semantic tokens only** in gallery chrome (`border-border`, `bg-background`, `bg-muted`, `text-muted-foreground`) and lucide icons only.
+4. **MUST route all gallery chrome strings through `i18n/` in all four locales** (en, pl, es, de) via `useT()`. Component titles and variant names (`Button`, `destructive-soft`) are proper nouns and stay untranslated.
+5. **MUST render entries with inline mock props only** — the gallery never calls tenant APIs and never renders tenant data.
+6. **MUST keep `figmaNodeId` in `<page>:<node>` format** pointing into `DS_FIGMA_FILE`; omit it when unknown — never guess node ids.
+
+## Never
+
+- Never add gallery-specific props or code to `packages/ui` — the gallery consumes primitives exactly as any other module does.
+- Never hardcode colors, arbitrary sizes, or full-pill chips in gallery chrome.
+- Never add API routes, entities, DI registrations, or tenant-scoped anything to this module.
+- Never remove a file from the primitives coverage enumeration by loosening the test — only entries or allowlist rows with reasons.
+
+## Validation Commands
+
+```bash
+yarn generate
+yarn workspace @open-mercato/core test --testPathPattern design_system
+yarn workspace @open-mercato/core typecheck
+yarn i18n:check-hardcoded
+```

package/src/modules/design_system/acl.ts

@@ -0,0 +1,5 @@
+export const features = [
+  { id: 'design_system.view', title: 'View the design system gallery', module: 'design_system' },
+]
+
+export default features

package/src/modules/design_system/backend/design-system/page.meta.ts

@@ -0,0 +1,11 @@
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['design_system.view'],
+  pageTitle: 'Design system',
+  pageTitleKey: 'design_system.nav.title',
+  pageGroup: 'Developer',
+  pageGroupKey: 'design_system.nav.group',
+  pageOrder: 900,
+  icon: 'shapes',
+  breadcrumb: [{ label: 'Design system', labelKey: 'design_system.nav.title' }],
+}

package/src/modules/design_system/backend/design-system/page.tsx

@@ -0,0 +1,14 @@
+"use client"
+
+import { Page, PageBody } from '@open-mercato/ui/backend/Page'
+import { GalleryShell } from '../../gallery/components/GalleryShell'
+
+export default function DesignSystemGalleryPage() {
+  return (
+    <Page>
+      <PageBody>
+        <GalleryShell />
+      </PageBody>
+    </Page>
+  )
+}

package/src/modules/design_system/gallery/components/CodeSnippet.tsx

@@ -0,0 +1,55 @@
+'use client'
+
+import * as React from 'react'
+import { Copy } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { IconButton } from '@open-mercato/ui/primitives/icon-button'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+
+export function CodeSnippet({ code }: { code: string }) {
+  const t = useT()
+  const copyLabel = t('design_system.gallery.copy', 'Copy code')
+
+  const onCopy = React.useCallback(async () => {
+    try {
+      if (navigator.clipboard) {
+        await navigator.clipboard.writeText(code)
+      } else {
+        // Non-secure contexts (plain-HTTP self-hosted installs) have no
+        // navigator.clipboard — fall back to the legacy selection API.
+        const holder = document.createElement('textarea')
+        holder.value = code
+        holder.setAttribute('readonly', '')
+        holder.style.position = 'fixed'
+        holder.style.opacity = '0'
+        document.body.appendChild(holder)
+        holder.select()
+        const copied = document.execCommand('copy')
+        holder.remove()
+        if (!copied) throw new Error('[internal] execCommand copy failed')
+      }
+      flash(t('design_system.gallery.copied', 'Snippet copied to clipboard'), 'success')
+    } catch {
+      flash(t('design_system.gallery.copyFailed', 'Could not copy the snippet'), 'error')
+    }
+  }, [code, t])
+
+  return (
+    <div className="relative rounded-md border border-border bg-muted/50">
+      <pre className="overflow-x-auto p-3 pr-12 text-xs leading-relaxed">
+        <code>{code}</code>
+      </pre>
+      <IconButton
+        type="button"
+        variant="ghost"
+        size="sm"
+        className="absolute right-1.5 top-1.5"
+        aria-label={copyLabel}
+        title={copyLabel}
+        onClick={onCopy}
+      >
+        <Copy />
+      </IconButton>
+    </div>
+  )
+}

package/src/modules/design_system/gallery/components/EntryCard.tsx

@@ -0,0 +1,95 @@
+'use client'
+
+import * as React from 'react'
+import { Check, ExternalLink, X } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { LinkButton } from '@open-mercato/ui/primitives/link-button'
+import type { GalleryEntry } from '../types'
+import { DS_DOCS_URL, figmaNodeUrl } from '../registry'
+import { VariantPreview } from './VariantPreview'
+import { CodeSnippet } from './CodeSnippet'
+
+export function EntryCard({ entry }: { entry: GalleryEntry }) {
+  const t = useT()
+
+  return (
+    <section
+      id={`gallery-entry-${entry.id}`}
+      aria-labelledby={`gallery-entry-${entry.id}-title`}
+      className="scroll-mt-4 space-y-4 rounded-lg border border-border bg-card p-4"
+    >
+      <div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
+        <div className="min-w-0 space-y-1">
+          <h3 id={`gallery-entry-${entry.id}-title`} className="text-base font-semibold leading-tight">
+            {entry.title}
+          </h3>
+          {entry.descriptionKey ? (
+            <p className="text-sm text-muted-foreground">{t(entry.descriptionKey, entry.title)}</p>
+          ) : null}
+          <code className="block truncate text-xs text-muted-foreground">{entry.importPath}</code>
+        </div>
+        <div className="flex shrink-0 items-center gap-3">
+          {entry.figmaNodeId ? (
+            <LinkButton asChild size="sm">
+              <a href={figmaNodeUrl(entry.figmaNodeId)} target="_blank" rel="noreferrer">
+                {t('design_system.gallery.openInFigma', 'Open in Figma')}
+                <ExternalLink />
+              </a>
+            </LinkButton>
+          ) : null}
+          {entry.docsAnchor ? (
+            <LinkButton asChild size="sm" variant="gray">
+              <a href={`${DS_DOCS_URL}${entry.docsAnchor}`} target="_blank" rel="noreferrer">
+                {t('design_system.gallery.viewDocs', 'View docs')}
+                <ExternalLink />
+              </a>
+            </LinkButton>
+          ) : null}
+        </div>
+      </div>
+      {entry.usage && (entry.usage.do?.length || entry.usage.dont?.length) ? (
+        <div className="grid gap-4 rounded-md border border-border bg-muted/30 p-4 sm:grid-cols-2">
+          {entry.usage.do?.length ? (
+            <div className="space-y-1.5">
+              <div className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+                {t('design_system.gallery.usageDo', 'Do')}
+              </div>
+              <ul className="space-y-1.5">
+                {entry.usage.do.map((rule) => (
+                  <li key={rule} className="flex items-start gap-2 text-sm text-foreground">
+                    <Check aria-hidden className="mt-0.5 size-3.5 shrink-0 text-status-success-icon" />
+                    <span>{rule}</span>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ) : null}
+          {entry.usage.dont?.length ? (
+            <div className="space-y-1.5">
+              <div className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+                {t('design_system.gallery.usageDont', "Don't")}
+              </div>
+              <ul className="space-y-1.5">
+                {entry.usage.dont.map((rule) => (
+                  <li key={rule} className="flex items-start gap-2 text-sm text-foreground">
+                    <X aria-hidden className="mt-0.5 size-3.5 shrink-0 text-status-error-icon" />
+                    <span>{rule}</span>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+      <div className="space-y-4">
+        {entry.variants.map((variant) => (
+          <div key={variant.id} className="space-y-2">
+            <div className="text-sm font-medium text-foreground">{variant.title}</div>
+            <VariantPreview>{variant.render()}</VariantPreview>
+            <CodeSnippet code={variant.code} />
+          </div>
+        ))}
+      </div>
+    </section>
+  )
+}

package/src/modules/design_system/gallery/components/GalleryShell.tsx

@@ -0,0 +1,206 @@
+'use client'
+
+import * as React from 'react'
+import { useSearchParams } from 'next/navigation'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { SectionPage } from '@open-mercato/ui/backend/section-page'
+import type { SectionNavGroup } from '@open-mercato/ui/backend/section-page'
+import { SearchInput } from '@open-mercato/ui/primitives/search-input'
+import { Skeleton } from '@open-mercato/ui/primitives/skeleton'
+import { EmptyState } from '@open-mercato/ui/primitives/empty-state'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { ErrorMessage } from '@open-mercato/ui/backend/detail'
+import type { GalleryEntry, GalleryFamily } from '../types'
+import { GALLERY_BASE_PATH, galleryFamilies } from '../registry'
+import { EntryCard } from './EntryCard'
+
+/** 'buttons' → 'Buttons' — untranslated fallback when a family labelKey has no message. */
+function familyLabelFallback(id: string): string {
+  return id.charAt(0).toUpperCase() + id.slice(1).replace(/[-_]/g, ' ')
+}
+
+function matchesQuery(entry: GalleryEntry, query: string): boolean {
+  const needle = query.trim().toLowerCase()
+  if (!needle) return true
+  if (entry.id.toLowerCase().includes(needle) || entry.title.toLowerCase().includes(needle)) return true
+  if (entry.keywords?.some((keyword) => keyword.toLowerCase().includes(needle))) return true
+  // 'radiobutton' should still find 'radio' — match when the query CONTAINS the id/title too.
+  return needle.includes(entry.id.toLowerCase()) || needle.includes(entry.title.toLowerCase())
+}
+
+type LoadedEntries = Record<string, GalleryEntry[]>
+
+export function GalleryShell() {
+  const t = useT()
+  const searchParams = useSearchParams()
+  const [loaded, setLoaded] = React.useState<LoadedEntries>({})
+  const [failed, setFailed] = React.useState<Record<string, boolean>>({})
+  const [search, setSearch] = React.useState('')
+  const pendingRef = React.useRef(new Set<string>())
+
+  const familyParam = searchParams?.get('family') ?? null
+  const entryParam = searchParams?.get('entry') ?? null
+
+  // Clicking a family in the section nav exits search mode — otherwise the
+  // query keeps precedence and family navigation appears dead.
+  React.useEffect(() => {
+    setSearch('')
+  }, [familyParam])
+  const activeFamily: GalleryFamily | undefined =
+    galleryFamilies.find((family) => family.id === familyParam) ?? galleryFamilies[0]
+  const activeFamilyId = activeFamily?.id ?? null
+
+  const loadFamily = React.useCallback((family: GalleryFamily) => {
+    if (pendingRef.current.has(family.id)) return
+    pendingRef.current.add(family.id)
+    setFailed((prev) => (prev[family.id] ? { ...prev, [family.id]: false } : prev))
+    family
+      .load()
+      .then((mod) => {
+        setLoaded((prev) => (prev[family.id] ? prev : { ...prev, [family.id]: mod.entries }))
+      })
+      .catch(() => {
+        pendingRef.current.delete(family.id)
+        setFailed((prev) => ({ ...prev, [family.id]: true }))
+      })
+  }, [])
+
+  // Lazy-load the active family; when searching, load every family so results
+  // span the whole gallery.
+  const searching = search.trim().length > 0
+  React.useEffect(() => {
+    if (searching) {
+      for (const family of galleryFamilies) loadFamily(family)
+    } else if (activeFamily) {
+      loadFamily(activeFamily)
+    }
+  }, [searching, activeFamily, loadFamily])
+
+  // Deep link: ?entry=<id> scrolls the entry into view once its family loaded.
+  const activeEntries = activeFamilyId ? loaded[activeFamilyId] : undefined
+  React.useEffect(() => {
+    if (!entryParam || searching || !activeEntries) return
+    const node = document.getElementById(`gallery-entry-${entryParam}`)
+    node?.scrollIntoView({ block: 'start' })
+  }, [entryParam, searching, activeEntries])
+
+  const sections: SectionNavGroup[] = React.useMemo(
+    () => [
+      {
+        id: 'families',
+        label: 'Families',
+        labelKey: 'design_system.gallery.familiesGroup',
+        items: galleryFamilies.map((family) => ({
+          id: family.id,
+          label: familyLabelFallback(family.id),
+          labelKey: family.labelKey,
+          icon: family.icon,
+          href: `${GALLERY_BASE_PATH}?family=${family.id}`,
+        })),
+      },
+    ],
+    [],
+  )
+
+  const renderFamilySkeleton = () => (
+    <div className="space-y-4" data-testid="gallery-family-skeleton">
+      <Skeleton className="h-40 w-full" />
+      <Skeleton className="h-40 w-full" />
+    </div>
+  )
+
+  const renderSearchResults = () => {
+    const groups = galleryFamilies
+      .map((family) => ({
+        family,
+        entries: (loaded[family.id] ?? []).filter((entry) => matchesQuery(entry, search)),
+      }))
+      .filter((group) => group.entries.length > 0)
+    const stillLoading = galleryFamilies.some((family) => !loaded[family.id] && !failed[family.id])
+    if (groups.length === 0 && stillLoading) return renderFamilySkeleton()
+    if (groups.length === 0) {
+      return (
+        <EmptyState
+          title={t('design_system.gallery.noResults', 'No components match your search')}
+        />
+      )
+    }
+    return (
+      <div className="space-y-8">
+        {groups.map(({ family, entries }) => (
+          <div key={family.id} className="space-y-4">
+            <h2 className="text-sm font-medium uppercase tracking-wider text-muted-foreground">
+              {t(family.labelKey, familyLabelFallback(family.id))}
+            </h2>
+            {entries.map((entry) => (
+              <EntryCard key={entry.id} entry={entry} />
+            ))}
+          </div>
+        ))}
+      </div>
+    )
+  }
+
+  const renderActiveFamily = () => {
+    if (!activeFamily) return null
+    const entries = loaded[activeFamily.id]
+    if (!entries && failed[activeFamily.id]) {
+      return (
+        <ErrorMessage
+          label={t('design_system.gallery.loadFailed', 'Could not load this family')}
+          action={
+            <Button type="button" variant="outline" size="sm" onClick={() => loadFamily(activeFamily)}>
+              {t('design_system.gallery.retry', 'Retry')}
+            </Button>
+          }
+        />
+      )
+    }
+    if (!entries) return renderFamilySkeleton()
+    return (
+      <div className="space-y-4">
+        <h2 className="text-lg font-semibold">
+          {t(activeFamily.labelKey, familyLabelFallback(activeFamily.id))}
+        </h2>
+        {entries.length > 1 ? (
+          <nav
+            aria-label={t('design_system.gallery.familyContents', 'Components in this family')}
+            className="flex flex-wrap items-center gap-1.5 rounded-md border border-border bg-muted/30 p-2"
+          >
+            {entries.map((entry) => (
+              <a
+                key={entry.id}
+                href={`#gallery-entry-${entry.id}`}
+                className="rounded-md border border-border bg-background px-2 py-1 text-xs text-foreground transition-colors hover:bg-muted focus-visible:outline-none focus-visible:shadow-focus"
+              >
+                {entry.title}
+              </a>
+            ))}
+          </nav>
+        ) : null}
+        {entries.map((entry) => (
+          <EntryCard key={entry.id} entry={entry} />
+        ))}
+      </div>
+    )
+  }
+
+  return (
+    <SectionPage
+      title="Design system"
+      titleKey="design_system.nav.title"
+      sections={sections}
+      activePath={activeFamilyId ? `${GALLERY_BASE_PATH}?family=${activeFamilyId}` : GALLERY_BASE_PATH}
+    >
+      <div className="mx-auto w-full max-w-5xl space-y-6">
+        <SearchInput
+          value={search}
+          onChange={setSearch}
+          placeholder={t('design_system.gallery.searchPlaceholder', 'Search components…')}
+          aria-label={t('design_system.gallery.searchPlaceholder', 'Search components…')}
+        />
+        {searching ? renderSearchResults() : renderActiveFamily()}
+      </div>
+    </SectionPage>
+  )
+}

package/src/modules/design_system/gallery/components/VariantPreview.tsx

@@ -0,0 +1,15 @@
+'use client'
+
+import * as React from 'react'
+
+/**
+ * Bordered stage a variant renders inside. Chrome uses semantic tokens only —
+ * the stage must never impose colors of its own on the previewed component.
+ */
+export function VariantPreview({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="flex flex-wrap items-center gap-3 rounded-md border border-border bg-background p-4">
+      {children}
+    </div>
+  )
+}