@open-mercato/core 0.7.1-develop.7202.1.a52dc6707c → 0.8.0

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

@@ -0,0 +1,65 @@
+'use client'
+
+import * as React from 'react'
+import { Plus } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Alert, AlertDescription, AlertTitle } from '@open-mercato/ui/primitives/alert'
+import { Banner } from '@open-mercato/ui/primitives/banner'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { CompactButton } from '@open-mercato/ui/primitives/compact-button'
+import { KeyIcon, KeyIconGlyph } from '@open-mercato/ui/primitives/key-icon'
+import { EmptyStateIllustration } from '@open-mercato/ui/primitives/empty-state-illustration'
+
+function CompactButtons() {
+  const t = useT()
+  const [pressed, setPressed] = React.useState<Record<string, boolean>>({})
+  return <div className="flex flex-wrap items-center gap-4">
+    {(['stroke', 'ghost', 'white', 'modifiable'] as const).map(appearance => <div key={appearance} className={appearance === 'modifiable' ? 'rounded-md bg-primary p-2 text-primary-foreground' : 'p-2'}>
+      <CompactButton type="button" appearance={appearance} size={24}
+        aria-label={t('design_system.gallery.examples.buttons.compactAction')}
+        aria-pressed={pressed[appearance] ?? false}
+        onClick={() => setPressed(current => ({ ...current, [appearance]: !current[appearance] }))}>
+        <Plus aria-hidden />
+      </CompactButton>
+    </div>)}
+  </div>
+}
+
+function KeyIcons() {
+  const t = useT()
+  return <div className="flex flex-wrap items-center gap-4">
+    {(['gray', 'blue', 'green', 'orange', 'purple'] as const).map((color, index) => <KeyIcon key={color} color={color} size={40} appearance={index < 2 ? 'stroke' : 'lighter'} aria-label={t(`design_system.gallery.examples.keyComponents.color.${color}`)}><KeyIconGlyph /></KeyIcon>)}
+  </div>
+}
+
+function AlertSpecimen() {
+  const t = useT()
+  return <Alert status="information" style="light" size="default" className="w-full">
+    <AlertTitle>{t('design_system.gallery.samples.banner.title')}</AlertTitle>
+    <AlertDescription>{t('design_system.gallery.samples.banner.description')}</AlertDescription>
+  </Alert>
+}
+
+function BannerSpecimen() {
+  const t = useT()
+  const [dismissed, setDismissed] = React.useState(false)
+  const [expanded, setExpanded] = React.useState(false)
+  if (dismissed) return <Button variant="outline" size="sm" onClick={() => { setDismissed(false); setExpanded(false) }}>{t('design_system.gallery.samples.banner.restore')}</Button>
+  return <div className="w-full space-y-3">
+    <Banner status="information" style="lighter" title={t('design_system.gallery.samples.banner.title')}
+      onDismiss={() => setDismissed(true)}
+      action={<Button variant="link" className="h-auto p-0 text-inherit underline" aria-expanded={expanded} onClick={() => setExpanded(value => !value)}>{t('design_system.gallery.samples.banner.details')}</Button>} />
+    {expanded ? <p role="status" className="text-sm text-muted-foreground">{t('design_system.gallery.samples.banner.detailsBody')}</p> : null}
+  </div>
+}
+
+export function getCompactEntrySpecimen(entryId: string): React.ReactNode | undefined {
+  switch (entryId) {
+    case 'compact-button': return <CompactButtons />
+    case 'key-icon': return <KeyIcons />
+    case 'alert': return <AlertSpecimen />
+    case 'banner': return <BannerSpecimen />
+    case 'empty-state-illustration': return <EmptyStateIllustration kind="mercato-records" />
+    default: return undefined
+  }
+}

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

@@ -0,0 +1,47 @@
+'use client'
+
+import * as React from 'react'
+import { GalleryLink as Link } from './GalleryLink'
+import { ArrowRight } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { Skeleton } from '@open-mercato/ui/primitives/skeleton'
+import { GALLERY_BASE_PATH } from '../registry'
+import type { GalleryEntry, GalleryFamily } from '../types'
+import { FamilyEntryPreview } from './FamilyEntryPreview'
+
+const representativeEntries: Record<string, string> = {
+  inputs: 'input',
+  dates: 'date-picker',
+  filters: 'quick-filters',
+  scaffolding: 'section-header',
+  notifications: 'notification-item',
+  schedule: 'schedule-agenda',
+  messages: 'message-object-preview',
+}
+
+export function ComponentIndex({ families, loaded, failed, onRetry }: {
+  families: GalleryFamily[]
+  loaded: Record<string, GalleryEntry[]>
+  failed: Record<string, boolean>
+  onRetry: (family: GalleryFamily) => void
+}) {
+  const t = useT()
+  return <div className="columns-1 gap-6 @3xl:columns-2">
+    {families.map(family => {
+      const entries = loaded[family.id]
+      const entry = entries?.find(candidate => candidate.id === representativeEntries[family.id]) ?? entries?.[0]
+      return <section key={family.id} aria-labelledby={`gallery-family-${family.id}`} className="relative mb-6 min-w-0 break-inside-avoid rounded-lg border border-border bg-card">
+        <h2 id={`gallery-family-${family.id}`} className="text-base font-semibold">
+          <Link href={`${GALLERY_BASE_PATH}?family=${family.id}`} className="flex items-center justify-between gap-3 p-5 after:absolute after:inset-0 after:rounded-lg hover:bg-muted/30 focus-visible:outline-none focus-visible:after:shadow-focus">
+            <span className="flex items-center gap-3">{family.icon}{t(family.labelKey, family.id)}</span>
+            <ArrowRight aria-hidden className="size-4 shrink-0 text-muted-foreground" />
+          </Link>
+        </h2>
+        <div className="min-h-40 border-t border-border bg-muted/20 p-5">
+          {entry ? <div inert aria-hidden="true" className="flex min-h-28 min-w-0 flex-wrap items-center gap-3 [&>*]:max-w-full"><FamilyEntryPreview entry={entry} /></div> : failed[family.id] ? <div className="space-y-3"><p className="text-sm text-muted-foreground">{t('design_system.gallery.loadFailed', 'Could not load this family')}</p><Button type="button" variant="outline" size="sm" className="relative z-10" onClick={() => onRetry(family)}>{t('design_system.gallery.retry', 'Retry')}</Button></div> : <Skeleton className="h-28 w-full" />}
+        </div>
+      </section>
+    })}
+  </div>
+}

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

@@ -0,0 +1,66 @@
+'use client'
+
+import * as React from 'react'
+import { GalleryLink as Link } from './GalleryLink'
+import { ArrowRight, Code2, Keyboard, Layers, Palette } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { GALLERY_BASE_PATH } from '../registry'
+
+const paths = {
+  foundations: `${GALLERY_BASE_PATH}?family=foundations`,
+  components: `${GALLERY_BASE_PATH}?view=components`,
+  button: `${GALLERY_BASE_PATH}?family=buttons&entry=button`,
+  patterns: `${GALLERY_BASE_PATH}?family=scaffolding`,
+}
+
+const principles = [
+  { id: 'semantics', icon: Palette, href: `${paths.foundations}&entry=color-roles` },
+  { id: 'states', icon: Layers, href: `${GALLERY_BASE_PATH}?family=feedback` },
+  { id: 'keyboard', icon: Keyboard, href: `${GALLERY_BASE_PATH}?family=overlays` },
+  { id: 'handoff', icon: Code2, href: paths.button },
+] as const
+
+export function DesignSystemPrinciples() {
+  const t = useT()
+  return <section className="space-y-8" aria-labelledby="ds-principles-title">
+    <div className="max-w-2xl space-y-3">
+      <p className="text-xs font-medium uppercase tracking-widest text-muted-foreground">{t('design_system.portal.principles.eyebrow')}</p>
+      <h2 id="ds-principles-title" className="text-2xl font-semibold tracking-tight">{t('design_system.portal.principles.title')}</h2>
+      <p className="text-base leading-relaxed text-muted-foreground">{t('design_system.portal.principles.description')}</p>
+    </div>
+    <div className="grid gap-x-8 gap-y-6 sm:grid-cols-2">
+      {principles.map(({ id, icon: Icon, href }) => <article key={id} className="space-y-3 border-t border-border py-6">
+        <Icon className="size-5 text-muted-foreground" aria-hidden />
+        <h3 className="text-lg font-medium">{t(`design_system.portal.principles.${id}.title`)}</h3>
+        <p className="max-w-prose text-sm leading-relaxed text-muted-foreground">{t(`design_system.portal.principles.${id}.description`)}</p>
+        <Link href={href} className="inline-flex items-center gap-2 rounded-sm text-sm underline underline-offset-4 focus-visible:outline-none focus-visible:shadow-focus">{t('design_system.portal.seeExamples')}<ArrowRight className="size-4" aria-hidden /></Link>
+      </article>)}
+    </div>
+  </section>
+}
+
+export function DesignSystemHome() {
+  const t = useT()
+  return <div className="space-y-12 pb-8" data-example="design-system-home">
+    <header id="gallery-page-heading" className="scroll-mt-36 border-b border-border pb-8 lg:scroll-mt-24">
+      <div className="max-w-3xl space-y-6">
+        <p className="text-xs font-medium uppercase tracking-widest text-muted-foreground">{t('design_system.portal.eyebrow')}</p>
+        <h1 className="max-w-2xl text-3xl font-medium leading-tight tracking-tight sm:text-5xl">{t('design_system.portal.title')}</h1>
+        <p className="max-w-xl text-base leading-relaxed text-muted-foreground">{t('design_system.portal.description')}</p>
+        <div className="flex flex-wrap gap-3">
+          <Button asChild size="lg"><Link href={paths.components}>{t('design_system.portal.browse')}<ArrowRight aria-hidden /></Link></Button>
+          <Button asChild size="lg" variant="outline"><Link href={paths.foundations}>{t('design_system.portal.start')}</Link></Button>
+        </div>
+      </div>
+    </header>
+
+    <section className="space-y-4 rounded-xl border border-border bg-card p-6">
+      <Palette className="size-6 text-muted-foreground" aria-hidden />
+      <h2 className="text-2xl font-medium">{t('design_system.styleAgents.title')}</h2>
+      <p className="max-w-2xl text-sm leading-relaxed text-muted-foreground">{t('design_system.styleAgents.description')}</p>
+      <Button asChild variant="outline"><Link href={`${GALLERY_BASE_PATH}?view=style-agents`}>{t('design_system.styleAgents.open')}<ArrowRight aria-hidden /></Link></Button>
+    </section>
+
+  </div>
+}

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

@@ -1,43 +1,50 @@
 'use client'
 
 import * as React from 'react'
-import { Check, ExternalLink, X } from 'lucide-react'
+import { GalleryLink as Link } from './GalleryLink'
+import { ArrowRight, 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 { DS_DOCS_URL } from '../registry'
 import { VariantPreview } from './VariantPreview'
 import { CodeSnippet } from './CodeSnippet'
+import { FamilyEntryPreview } from './FamilyEntryPreview'
+import { EntryHeader } from './EntryHeader'
 
-export function EntryCard({ entry }: { entry: GalleryEntry }) {
+type EntryCardProps = {
+  entry: GalleryEntry
+  href?: string
+  summary?: boolean
+  summaryPreview?: boolean
+  onNavigate?: () => void
+  hideTitle?: boolean
+  fullWidth?: boolean
+}
+
+export function EntryCard({ entry, href, summary = false, summaryPreview = false, onNavigate, hideTitle = false, fullWidth = false }: EntryCardProps) {
   const t = useT()
+  const availableVariants = React.useMemo(() => entry.id === 'file-upload' ? entry.variants.filter(variant => variant.id !== 'drag-and-drop') : entry.variants, [entry.id, entry.variants])
+
 
   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"
+      aria-label={hideTitle ? entry.title : undefined}
+      aria-labelledby={hideTitle ? undefined : `gallery-entry-${entry.id}-title`}
+      className={summary ? `relative min-w-0 rounded-lg border border-border bg-card p-4 sm:p-5 ${summaryPreview ? `flex flex-col gap-4 ${fullWidth ? '@3xl:col-span-2' : ''}` : 'space-y-4'}` : 'min-w-0 space-y-6'}
     >
-      <div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
-        <div className="min-w-0 space-y-1">
+      {!hideTitle ? <div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
+        <div className="min-w-0 flex-1 space-y-1">
           <h3 id={`gallery-entry-${entry.id}-title`} className="text-base font-semibold leading-tight">
-            {entry.title}
+            {href ? <Link href={href} onNavigate={onNavigate} className="flex items-center justify-between gap-3 rounded-sm after:absolute after:inset-0 after:rounded-lg focus-visible:outline-none focus-visible:after:shadow-focus">{entry.title}{summaryPreview ? <ArrowRight className="size-4 shrink-0 text-muted-foreground" aria-hidden /> : null}</Link> : entry.title}
           </h3>
-          {entry.descriptionKey ? (
+          {entry.descriptionKey && !summaryPreview ? (
             <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 ? (
+        <div className="flex shrink-0 flex-wrap items-center gap-3">
+          {entry.docsAnchor && !summary ? (
             <LinkButton asChild size="sm" variant="gray">
               <a href={`${DS_DOCS_URL}${entry.docsAnchor}`} target="_blank" rel="noreferrer">
                 {t('design_system.gallery.viewDocs', 'View docs')}
@@ -46,19 +53,35 @@ export function EntryCard({ entry }: { entry: GalleryEntry }) {
             </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">
+      </div> : null}
+      {summary && summaryPreview && entry.variants.length ? <div inert aria-hidden="true" className="flex flex-1">
+        <div className="flex min-h-32 min-w-0 flex-1 flex-wrap items-center gap-4 rounded-md bg-muted/20 p-4 [&>*]:max-w-full">
+          <FamilyEntryPreview entry={entry} />
+        </div>
+      </div> : null}
+      {!summary ? <EntryHeader entry={entry} variants={availableVariants} /> : null}
+      {!summary ? <div className="space-y-8">
+        {availableVariants.map((variant) => (
+          <div key={variant.id} id={`gallery-variant-${entry.id}-${variant.id}`} className="scroll-mt-36 lg:scroll-mt-24 space-y-3">
+            {availableVariants.length > 1 ? <h2 className="text-lg font-medium">{t(`design_system.gallery.variantTitles.${variant.title}`, variant.title)}</h2> : null}
+            <CodeSnippet code={variant.code} preview={<VariantPreview framed={!fullWidth}>{variant.render()}</VariantPreview>} />
+          </div>
+        ))}
+      </div> : null}
+      {!summary && entry.usage && (entry.usage.do?.length || entry.usage.dont?.length) ? (
+        <section className="rounded-md border border-border">
+          <h3 className="p-4 text-sm font-medium">{t('design_system.portal.nav.principles')}</h3>
+          <div className="grid gap-4 border-t border-border 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) => (
+                {entry.usage.do.map((rule, index) => (
                   <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>
+                    <span>{t(`design_system.gallery.usage.${entry.id}.do.${index}`, rule)}</span>
                   </li>
                 ))}
               </ul>
@@ -70,26 +93,18 @@ export function EntryCard({ entry }: { entry: GalleryEntry }) {
                 {t('design_system.gallery.usageDont', "Don't")}
               </div>
               <ul className="space-y-1.5">
-                {entry.usage.dont.map((rule) => (
+                {entry.usage.dont.map((rule, index) => (
                   <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>
+                    <span>{t(`design_system.gallery.usage.${entry.id}.dont.${index}`, 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>
+      ) : null}
     </section>
   )
 }

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

@@ -0,0 +1,80 @@
+'use client'
+
+import * as React from 'react'
+import { Copy, LayoutTemplate } from 'lucide-react'
+import { useSearchParams } from 'next/navigation'
+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'
+import type { GalleryEntry, GalleryVariant } from '../types'
+import { GALLERY_BASE_PATH } from '../registry'
+import { GalleryLink as Link } from './GalleryLink'
+import { copyTextToClipboard } from './CodeSnippet'
+
+const VARIANT_INDEX_THRESHOLD = 4
+
+export function isPatternEntry(entry: GalleryEntry): boolean {
+  return entry.importPath.includes('/design_system/gallery/')
+}
+
+export function resolveImportStatement(entry: GalleryEntry): string {
+  const escapedPath = entry.importPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const statement = new RegExp(`import[^;'"]*?from\\s+['"]${escapedPath}['"]`)
+  for (const variant of entry.variants) {
+    const match = variant.code.match(statement)
+    if (match) return match[0].replace(/\s+/g, ' ')
+  }
+  return entry.importPath
+}
+
+export function EntryHeader({ entry, variants }: { entry: GalleryEntry; variants: GalleryVariant[] }) {
+  const t = useT()
+  const searchParams = useSearchParams()
+  const familyId = searchParams?.get('family') ?? null
+  const importStatement = React.useMemo(() => resolveImportStatement(entry), [entry])
+  const copyLabel = t('design_system.gallery.copyImport', 'Copy import')
+
+  const onCopy = React.useCallback(async () => {
+    try {
+      await copyTextToClipboard(importStatement)
+      flash(t('design_system.gallery.importCopied', 'Import copied to clipboard'), 'success')
+    } catch {
+      flash(t('design_system.gallery.copyFailed', 'Could not copy the snippet'), 'error')
+    }
+  }, [importStatement, t])
+
+  return (
+    <div className="space-y-4" data-testid="gallery-entry-header">
+      {isPatternEntry(entry) ? (
+        <p className="flex items-start gap-2 rounded-md border border-status-info-border bg-status-info-bg p-3 text-sm text-status-info-text">
+          <LayoutTemplate aria-hidden className="mt-0.5 size-4 shrink-0 text-status-info-icon" />
+          <span>{t('design_system.gallery.patternNote', 'This is a sample layout composed from library components, not an importable component. Use it as a pattern.')}</span>
+        </p>
+      ) : (
+        <div className="flex min-w-0 items-center gap-2 rounded-md border border-border bg-muted/50 py-1 pl-3 pr-1">
+          <span className="shrink-0 text-xs font-medium uppercase tracking-wider text-muted-foreground">{t('design_system.gallery.importLabel', 'Import')}</span>
+          <code className="min-w-0 flex-1 overflow-x-auto whitespace-nowrap py-1 text-xs">{importStatement}</code>
+          <IconButton type="button" variant="ghost" size="sm" aria-label={copyLabel} title={copyLabel} onClick={onCopy}><Copy /></IconButton>
+        </div>
+      )}
+      {variants.length >= VARIANT_INDEX_THRESHOLD ? (
+        <nav aria-label={t('design_system.gallery.variantsNav', 'Variants')} className="space-y-2">
+          <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">{t('design_system.gallery.variantsNav', 'Variants')} ({variants.length})</p>
+          <ul className="flex flex-wrap gap-x-4 gap-y-1">
+            {variants.map((variant) => {
+              const label = t(`design_system.gallery.variantTitles.${variant.title}`, variant.title)
+              const className = 'rounded-sm text-sm text-muted-foreground underline-offset-4 hover:text-foreground hover:underline focus-visible:outline-none focus-visible:shadow-focus'
+              return (
+                <li key={variant.id}>
+                  {familyId
+                    ? <Link href={`${GALLERY_BASE_PATH}?family=${familyId}&entry=${entry.id}&variant=${variant.id}`} className={className}>{label}</Link>
+                    : <a href={`#gallery-variant-${entry.id}-${variant.id}`} className={className}>{label}</a>}
+                </li>
+              )
+            })}
+          </ul>
+        </nav>
+      ) : null}
+    </div>
+  )
+}

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

@@ -0,0 +1,22 @@
+'use client'
+
+import * as React from 'react'
+import { SourceIcon } from '@open-mercato/ui/assets/source-icons'
+import type { GalleryEntry } from '../types'
+import { representativeVariantIds } from '../presentation'
+import { getCompactEntrySpecimen } from './CompactEntrySpecimen'
+
+export function FamilyEntryPreview({ entry }: { entry: GalleryEntry }) {
+  const compact = getCompactEntrySpecimen(entry.id)
+  if (compact !== undefined) return compact
+
+  if (entry.id === 'button') return <>{entry.variants.filter(variant => ['default', 'outline', 'ghost'].includes(variant.id)).map(variant => <React.Fragment key={variant.id}>{variant.render()}</React.Fragment>)}</>
+
+  if (entry.id === 'icon-registry') return <div className="grid grid-cols-4 gap-6">{(['activity', 'arrow-right', 'bell', 'calendar', 'check', 'house', 'plus', 'search'] as const).map(name => <SourceIcon key={name} name={name} aria-hidden="true" className="size-6" />)}</div>
+
+  const overviewVariant = [representativeVariantIds[entry.id], 'default']
+    .map(id => entry.variants.find(variant => variant.id === id))
+    .find(Boolean) ?? entry.variants[0]
+  if (entry.id === 'table') return <div className="w-full min-w-0 overflow-x-auto">{overviewVariant?.render()}</div>
+  return overviewVariant?.render() ?? null
+}

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

@@ -0,0 +1,43 @@
+'use client'
+
+import * as React from 'react'
+import { GalleryLink as Link } from './GalleryLink'
+import { ArrowRight } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Button } from '@open-mercato/ui/primitives/button'
+import type { GalleryEntry } from '../types'
+import { CodeSnippet } from './CodeSnippet'
+import { ThemeTokenReference } from './ThemeTokenReference'
+import { GALLERY_BASE_PATH } from '../registry'
+
+export function FoundationGuide({ entries }: { entries: GalleryEntry[] }) {
+  const t = useT()
+  return <div className="space-y-12 pb-12">
+    <p className="max-w-2xl text-base leading-relaxed text-muted-foreground">{t('design_system.foundations.intro')}</p>
+    {entries.some(entry => entry.id === 'brand-colors' || entry.id === 'color-tokens') ? <div className="flex flex-wrap items-center justify-between gap-4 rounded-lg border border-border bg-muted/30 p-4">
+      <p className="max-w-xl text-sm text-muted-foreground">{t('design_system.styleAgents.referenceHint')}</p>
+      <Button asChild variant="outline"><Link href={`${GALLERY_BASE_PATH}?view=style-agents`}>{t('design_system.styleAgents.open')}<ArrowRight aria-hidden /></Link></Button>
+    </div> : null}
+    {entries.map(entry => <section key={entry.id} id={`gallery-entry-${entry.id}`} aria-labelledby={`gallery-entry-${entry.id}-title`} className="min-w-0 scroll-mt-36 lg:scroll-mt-24 space-y-8 border-t border-border pt-8">
+      <header className="max-w-2xl space-y-3">
+        <h2 id={`gallery-entry-${entry.id}-title`} className="text-2xl font-medium tracking-tight">{t(`design_system.foundations.${entry.id}.title`, entry.title)}</h2>
+        <p className="text-base leading-relaxed text-muted-foreground">{t(`design_system.foundations.${entry.id}.description`)}</p>
+      </header>
+      <CodeSnippet code={entry.variants.map(variant => variant.code).join('\n\n')} preview={<div className="space-y-8">{entry.variants.map(variant => <div key={variant.id} id={`gallery-variant-${entry.id}-${variant.id}`} className="min-w-0 scroll-mt-36 space-y-4 lg:scroll-mt-24">
+        {entry.variants.length > 1 && entry.id !== 'typography' ? <h3 className="text-sm font-medium text-muted-foreground">{t(`design_system.foundations.variants.${variant.id}`, variant.title)}</h3> : null}
+        <div className="min-w-0 overflow-x-auto py-2">{variant.render()}</div>
+      </div>)}
+      {entry.id === 'color-tokens' ? <ThemeTokenReference /> : null}
+      </div>} />
+      {entry.usage ? <section className="rounded-md border border-border">
+        <h3 className="p-4 text-sm font-medium">{t('design_system.portal.nav.principles')}</h3>
+        <div className="grid gap-6 border-t border-border p-4 sm:grid-cols-2">
+          {(['do', 'dont'] as const).map(kind => entry.usage?.[kind]?.length ? <div key={kind} className="space-y-3">
+            <h3 className="text-sm font-medium">{t(kind === 'do' ? 'design_system.gallery.usageDo' : 'design_system.gallery.usageDont')}</h3>
+            <ul className="list-disc space-y-2 pl-4 text-sm leading-relaxed text-muted-foreground">{entry.usage[kind]?.map((rule, index) => <li key={rule}>{t(`design_system.gallery.usage.${entry.id}.${kind}.${index}`, rule)}</li>)}</ul>
+          </div> : null)}
+        </div>
+      </section> : null}
+    </section>)}
+  </div>
+}

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

@@ -0,0 +1,19 @@
+'use client'
+
+import * as React from 'react'
+import Link from 'next/link'
+import { GALLERY_BASE_PATH } from '../registry'
+
+export function navigateGallery(href: string): boolean {
+  const target = new URL(href, window.location.href)
+  if (target.origin !== window.location.origin || target.pathname !== GALLERY_BASE_PATH || window.location.pathname !== GALLERY_BASE_PATH) return false
+  if (target.href !== window.location.href) window.history.pushState(null, '', target.href)
+  return true
+}
+
+export function GalleryLink({ onNavigate, ...props }: React.ComponentProps<typeof Link>) {
+  return <Link {...props} prefetch={false} onNavigate={event => {
+    if (typeof props.href === 'string' && navigateGallery(props.href)) event.preventDefault()
+    onNavigate?.(event)
+  }} />
+}

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

@@ -0,0 +1,86 @@
+'use client'
+
+import * as React from 'react'
+import { GalleryLink as Link } from './GalleryLink'
+import { ChevronRight, Menu, X } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { cn } from '@open-mercato/shared/lib/utils'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { IconButton } from '@open-mercato/ui/primitives/icon-button'
+import { Skeleton } from '@open-mercato/ui/primitives/skeleton'
+import type { SectionNavGroup, SectionNavItem } from '@open-mercato/ui/backend/section-page'
+import { useInjectedMenuItems } from '@open-mercato/ui/backend/injection/useInjectedMenuItems'
+import { mergeMenuItems } from '@open-mercato/ui/backend/injection/mergeMenuItems'
+import { resolveInjectedIcon } from '@open-mercato/ui/backend/injection/resolveInjectedIcon'
+
+export function GalleryNavigation({ sections, activePath, activeFamilyId, onExpand, onNavigate, failed, onRetry }: {
+  sections: SectionNavGroup[]
+  activePath: string
+  activeFamilyId: string | null
+  onExpand: (id: string) => void
+  onNavigate: () => void
+  failed: Record<string, boolean>
+  onRetry: (id: string) => void
+}) {
+  const t = useT()
+  const prefix = React.useId()
+  const [mobileOpen, setMobileOpen] = React.useState(false)
+  const [expanded, setExpanded] = React.useState<Record<string, boolean>>({})
+  const { items: injectedItems } = useInjectedMenuItems('menu:sidebar:settings:design_system')
+  React.useEffect(() => {
+    if (activeFamilyId) setExpanded(previous => ({ ...previous, [activeFamilyId]: true }))
+    setMobileOpen(false)
+  }, [activeFamilyId, activePath])
+
+  const navigate = () => { setMobileOpen(false); onNavigate() }
+  const itemLabel = (item: SectionNavItem) => t(item.labelKey ?? item.label, item.label)
+  const renderLink = (item: SectionNavItem, nested = false) => {
+    const active = activePath === item.href
+    return <Button asChild variant="ghost" size="sm" className={cn('w-full min-w-0 justify-start gap-2 rounded-md px-3 text-left text-sm font-normal text-muted-foreground', !nested && 'w-0 flex-1', active && 'bg-accent font-semibold text-accent-foreground', nested && 'border-l-2 rounded-l-none', nested && (active ? 'border-foreground' : 'border-transparent'))}>
+      <Link href={item.href} aria-current={active ? 'page' : undefined} onClick={navigate}>
+        {!nested && item.icon ? <span className="shrink-0" aria-hidden>{item.icon}</span> : null}
+        <span className="min-w-0 truncate">{itemLabel(item)}</span>
+      </Link>
+    </Button>
+  }
+  const renderItem = (item: SectionNavItem) => {
+    const expandable = item.children !== undefined
+    const open = expanded[item.id] ?? false
+    const label = itemLabel(item)
+    const contentId = `${prefix}-${item.id}`
+    return <li key={item.id} className="min-w-0">
+      <div className="flex min-w-0 items-center gap-1">
+        {renderLink(item)}
+        {expandable ? <IconButton type="button" variant="ghost" size="sm" className="shrink-0 text-muted-foreground" aria-label={t(open ? 'design_system.gallery.navigation.collapse' : 'design_system.gallery.navigation.expand', { category: label })} aria-expanded={open} aria-controls={contentId} onClick={() => {
+          setExpanded(previous => ({ ...previous, [item.id]: !open }))
+          if (!open) onExpand(item.id)
+        }}><ChevronRight className={cn('size-4 transition-transform', open && 'rotate-90')} /></IconButton> : null}
+      </div>
+      {expandable && open ? <div id={contentId} className="mb-2 ml-5 mt-1 border-l border-border pl-2">
+        {failed[item.id] ? <Button type="button" variant="ghost" size="sm" onClick={() => onRetry(item.id)}>{t('design_system.gallery.retry')}</Button> : item.children?.length ? <ul className="space-y-0.5">{item.children.map(child => <li key={child.id}>{renderLink(child, true)}</li>)}</ul> : <div className="space-y-2 p-2" role="status" aria-label={t('common.loading', 'Loading…')}><Skeleton className="h-5 w-3/4" /><Skeleton className="h-5 w-1/2" /></div>}
+      </div> : null}
+    </li>
+  }
+  return <aside className="sticky top-16 z-20 min-w-0 bg-background lg:top-20 lg:w-60 lg:shrink-0 lg:self-start lg:border-r lg:border-border">
+    <Button type="button" variant="outline" className="my-2 w-full justify-between lg:hidden" aria-expanded={mobileOpen} aria-controls={`${prefix}-navigation`} onClick={() => setMobileOpen(value => !value)}>
+      {t('design_system.gallery.navigation.browse')}{mobileOpen ? <X aria-hidden /> : <Menu aria-hidden />}
+    </Button>
+    <nav id={`${prefix}-navigation`} aria-label={t('design_system.gallery.navigation.label')} className={cn('max-h-screen overflow-y-auto overscroll-contain py-4 pr-3 pb-24 lg:block', !mobileOpen && 'hidden')}>
+      <Link href="/backend/design-system" onClick={navigate} className="mb-5 block px-3 text-base font-semibold tracking-tight">{t('design_system.nav.title')}</Link>
+      <div className="space-y-5">{sections.map(section => {
+        const additions = injectedItems.filter(item => (item.groupId ?? section.id) === section.id)
+        const items = mergeMenuItems(section.items.map(item => ({ id: item.id, item })), additions).flatMap(item => {
+          if (item.source === 'built-in') {
+            const original = section.items.find(candidate => candidate.id === item.id)
+            return original ? [original] : []
+          }
+          return item.href ? [{ id: item.id, label: item.label ?? item.id, labelKey: item.labelKey, href: item.href, icon: resolveInjectedIcon(item.icon) }] : []
+        })
+        return <section key={section.id}>
+          {section.label ? <p className="mb-2 px-3 text-xs font-medium uppercase tracking-wider text-muted-foreground">{t(section.labelKey ?? section.label, section.label)}</p> : null}
+          <ul className="space-y-1">{items.map(item => renderItem(item))}</ul>
+        </section>
+      })}</div>
+    </nav>
+  </aside>
+}