@open-mercato/core 0.7.1-develop.7203.1.9396450b78 → 0.8.1-develop.7204.1.83330e271e

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

@@ -1,9 +1,11 @@
 'use client'
 
 import * as React from 'react'
-import { useSearchParams } from 'next/navigation'
+import { GalleryLink as Link, navigateGallery } from './GalleryLink'
+import { ArrowLeft, Home, BookOpen, Grid2X2, Palette } from 'lucide-react'
+import { useRouter, useSearchParams } from 'next/navigation'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
-import { SectionPage } from '@open-mercato/ui/backend/section-page'
+import { GalleryNavigation } from './GalleryNavigation'
 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'
@@ -13,6 +15,12 @@ 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'
+import { DesignSystemHome, DesignSystemPrinciples } from './DesignSystemHome'
+import { StyleAgents } from './StyleAgents'
+import { ComponentIndex } from './ComponentIndex'
+import { FoundationGuide } from './FoundationGuide'
+import { IconsBrowser } from './IconsBrowser'
+import { fullWidthEntryIds } from '../presentation'
 
 /** 'buttons' → 'Buttons' — untranslated fallback when a family labelKey has no message. */
 function familyLabelFallback(id: string): string {
@@ -28,27 +36,77 @@ function matchesQuery(entry: GalleryEntry, query: string): boolean {
   return needle.includes(entry.id.toLowerCase()) || needle.includes(entry.title.toLowerCase())
 }
 
+/** A half-width card with no neighbour before the next full-width card would leave a hole, so it spans the row too. */
+export function resolveFullWidthIds(entryIds: string[], fullWidthIds: ReadonlySet<string>): Set<string> {
+  const resolved = new Set(entryIds.filter(id => fullWidthIds.has(id)))
+  let unpaired: string | null = null
+  for (const id of entryIds) {
+    if (resolved.has(id)) {
+      if (unpaired) resolved.add(unpaired)
+      unpaired = null
+    } else {
+      unpaired = unpaired ? null : id
+    }
+  }
+  if (unpaired) resolved.add(unpaired)
+  return resolved
+}
+
+/**
+ * The backend shell centres `main` once the viewport outgrows its max width, which would leave the
+ * library navigation floating mid-screen. Pull the gallery back by that centring margin so the
+ * navigation stays docked next to the application sidebar at every width.
+ */
+function useShellDockOffset(rootRef: React.RefObject<HTMLElement | null>): number {
+  const [offset, setOffset] = React.useState(0)
+  React.useLayoutEffect(() => {
+    const main = rootRef.current?.closest('main')
+    const column = main?.parentElement
+    if (!main || !column || typeof ResizeObserver === 'undefined') return
+    const measure = () => setOffset(Math.max(0, Math.round(main.getBoundingClientRect().left - column.getBoundingClientRect().left)))
+    measure()
+    const observer = new ResizeObserver(measure)
+    observer.observe(column)
+    return () => observer.disconnect()
+  }, [rootRef])
+  return offset
+}
+
 type LoadedEntries = Record<string, GalleryEntry[]>
 
+const componentFamilies = galleryFamilies.filter(family => !['foundations', 'library'].includes(family.id))
+
 export function GalleryShell() {
   const t = useT()
+  const router = useRouter()
   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 rootRef = React.useRef<HTMLDivElement>(null)
+  const dockOffset = useShellDockOffset(rootRef)
 
   const familyParam = searchParams?.get('family') ?? null
   const entryParam = searchParams?.get('entry') ?? null
+  const variantParam = searchParams?.get('variant') ?? null
+  const showingPrinciples = searchParams?.get('view') === 'principles' && !familyParam
+  const showingComponents = searchParams?.get('view') === 'components' && !familyParam
+  const showingStyleAgents = searchParams?.get('view') === 'style-agents' && !familyParam
+  const showingHome = !familyParam && !showingPrinciples && !showingComponents && !showingStyleAgents
+  const showingFoundations = familyParam === 'foundations'
+  const showingAssets = familyParam === 'icons'
+  const showingInventory = familyParam === 'library'
+  const showingEntry = Boolean(entryParam) && !showingFoundations && !showingAssets && !showingInventory
+
 
-  // Clicking a family in the section nav exits search mode — otherwise the
-  // query keeps precedence and family navigation appears dead.
   React.useEffect(() => {
     setSearch('')
-  }, [familyParam])
+  }, [familyParam, entryParam, showingPrinciples, showingComponents, showingStyleAgents])
   const activeFamily: GalleryFamily | undefined =
     galleryFamilies.find((family) => family.id === familyParam) ?? galleryFamilies[0]
   const activeFamilyId = activeFamily?.id ?? null
+  const activeNavigationPath = showingStyleAgents ? `${GALLERY_BASE_PATH}?view=style-agents` : showingHome ? GALLERY_BASE_PATH : showingPrinciples ? `${GALLERY_BASE_PATH}?view=principles` : showingComponents ? `${GALLERY_BASE_PATH}?view=components` : `${GALLERY_BASE_PATH}?family=${activeFamilyId}${(showingFoundations || showingEntry) && entryParam ? `&entry=${entryParam}` : ''}`
 
   const loadFamily = React.useCallback((family: GalleryFamily) => {
     if (pendingRef.current.has(family.id)) return
@@ -71,36 +129,54 @@ export function GalleryShell() {
   React.useEffect(() => {
     if (searching) {
       for (const family of galleryFamilies) loadFamily(family)
-    } else if (activeFamily) {
+    } else if (showingComponents) {
+      for (const family of componentFamilies) loadFamily(family)
+    } else if (activeFamily && !showingHome && !showingPrinciples && !showingStyleAgents) {
       loadFamily(activeFamily)
     }
-  }, [searching, activeFamily, loadFamily])
+  }, [searching, activeFamily, loadFamily, showingHome, showingPrinciples, showingComponents, showingStyleAgents])
 
-  // 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}`)
+    if (searching || (showingFoundations && entryParam && !activeEntries)) return
+    const variantId = entryParam === 'file-upload' && variantParam === 'drag-and-drop' ? 'default' : variantParam
+    const targetId = showingFoundations && entryParam ? `gallery-entry-${entryParam}` : entryParam && variantId && variantId !== '__all' ? `gallery-variant-${entryParam}-${variantId}` : 'gallery-page-heading'
+    const node = document.getElementById(targetId) ?? document.getElementById('gallery-page-heading')
     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}`,
-        })),
-      },
-    ],
-    [],
-  )
+  }, [familyParam, entryParam, variantParam, searching, activeEntries, showingFoundations, showingHome, showingPrinciples, showingComponents, showingStyleAgents])
+
+  const sections: SectionNavGroup[] = React.useMemo(() => {
+    const familyItem = (family: GalleryFamily) => ({
+      id: family.id,
+      label: familyLabelFallback(family.id),
+      labelKey: family.labelKey,
+      icon: family.icon,
+      href: `${GALLERY_BASE_PATH}?family=${family.id}`,
+      ...(!['library', 'icons'].includes(family.id) ? { children: (loaded[family.id] ?? []).map(entry => ({
+        id: `entry:${entry.id}`, label: entry.title,
+        ...(family.id === 'foundations' ? { labelKey: `design_system.foundations.${entry.id}.title` } : {}),
+        href: `${GALLERY_BASE_PATH}?family=${family.id}&entry=${entry.id}`,
+      })) } : {}),
+    })
+    return [
+      { id: 'guide', label: '', items: [
+        { id: '__home', label: 'Start', labelKey: 'design_system.portal.nav.home', icon: <Home className="size-4" />, href: GALLERY_BASE_PATH },
+        { id: '__style-agents', label: 'Style agents', labelKey: 'design_system.styleAgents.title', icon: <Palette className="size-4" />, href: `${GALLERY_BASE_PATH}?view=style-agents` },
+        ...galleryFamilies.filter(family => family.id === 'foundations').map(familyItem),
+      ] },
+      { id: 'families', label: 'Components', labelKey: 'design_system.portal.nav.components', items: [
+        { id: '__components', label: 'All components', labelKey: 'design_system.gallery.navigation.allComponents', icon: <Grid2X2 className="size-4" />, href: `${GALLERY_BASE_PATH}?view=components` },
+        ...componentFamilies.map(familyItem),
+      ] },
+      { id: 'resources', label: 'Resources', labelKey: 'design_system.gallery.navigation.resources', items: [
+        { id: '__principles', label: 'Guidelines', labelKey: 'design_system.portal.nav.principles', icon: <BookOpen className="size-4" />, href: `${GALLERY_BASE_PATH}?view=principles` },
+        ...galleryFamilies.filter(family => family.id === 'library').map(familyItem),
+      ] },
+    ]
+  }, [loaded])
+  const selectedEntry = entryParam ? activeEntries?.find(entry => entry.id === entryParam) : undefined
+  const familyTitle = activeFamily ? t(activeFamily.labelKey, familyLabelFallback(activeFamily.id)) : t('design_system.nav.title')
+  const pageTitle = showingComponents ? t('design_system.portal.nav.components') : showingEntry && selectedEntry ? selectedEntry.title : familyTitle
 
   const renderFamilySkeleton = () => (
     <div className="space-y-4" data-testid="gallery-family-skeleton">
@@ -133,7 +209,7 @@ export function GalleryShell() {
               {t(family.labelKey, familyLabelFallback(family.id))}
             </h2>
             {entries.map((entry) => (
-              <EntryCard key={entry.id} entry={entry} />
+              <EntryCard key={entry.id} entry={entry} summary href={`${GALLERY_BASE_PATH}?family=${family.id}&entry=${entry.id}`} onNavigate={() => setSearch('')} />
             ))}
           </div>
         ))}
@@ -157,50 +233,60 @@ export function GalleryShell() {
       )
     }
     if (!entries) return renderFamilySkeleton()
+    if (activeFamily.id === 'icons') return <IconsBrowser entryId={entryParam ?? undefined} variantId={variantParam ?? undefined} onNavigate={(entryId, variantId) => {
+      const href = `${GALLERY_BASE_PATH}?family=icons&entry=${entryId}${variantId ? `&variant=${variantId}` : ''}`
+      if (!navigateGallery(href)) router.push(href, { scroll: false })
+    }} />
+    if (activeFamily.id === 'foundations') return <FoundationGuide entries={entries} />
+    const sourceLibraryRender = activeFamily.id === 'library' && entries.length === 1 && !entryParam
+      ? entries[0]?.variants[0]?.render
+      : undefined
+    if (sourceLibraryRender) {
+      const SourceLibraryRender = sourceLibraryRender
+      return <div className="space-y-4">
+        <SourceLibraryRender />
+      </div>
+    }
+    const selectedEntry = entries.find(entry => entry.id === entryParam) ?? (entries.length === 1 ? entries[0] : undefined)
+    const familyFullWidthIds = resolveFullWidthIds(entries.map(entry => entry.id), fullWidthEntryIds)
     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} />
-        ))}
+        {selectedEntry ? <>
+          <EntryCard key={selectedEntry.id} entry={selectedEntry} hideTitle fullWidth={fullWidthEntryIds.has(selectedEntry.id)} />
+        </> : <div className="grid grid-cols-1 gap-4 @3xl:grid-cols-2">{entries.map(entry => <EntryCard key={entry.id} entry={entry} summary summaryPreview fullWidth={familyFullWidthIds.has(entry.id)} href={`${GALLERY_BASE_PATH}?family=${activeFamily.id}&entry=${entry.id}`} />)}</div>}
       </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
+    <div ref={rootRef} className="flex min-w-0 flex-col lg:flex-row" style={dockOffset ? { marginLeft: -dockOffset, width: `calc(100% + ${dockOffset}px)` } : undefined}>
+      <GalleryNavigation sections={sections} activePath={activeNavigationPath} activeFamilyId={familyParam} onNavigate={() => setSearch('')} failed={failed} onExpand={id => {
+        const family = galleryFamilies.find(family => family.id === id)
+        if (family) loadFamily(family)
+      }} onRetry={id => {
+        const family = galleryFamilies.find(family => family.id === id)
+        if (family) loadFamily(family)
+      }} />
+      <div className="min-w-0 flex-1 py-4 lg:pl-6">
+      <div className="@container mx-auto w-full max-w-6xl space-y-6">
+        {showingStyleAgents ? <StyleAgents /> : showingHome ? <DesignSystemHome /> : showingPrinciples ? <div id="gallery-page-heading" className="scroll-mt-36 lg:scroll-mt-24 space-y-8 py-8"><h1 className="text-3xl font-medium tracking-tight">{t('design_system.portal.nav.principles')}</h1><DesignSystemPrinciples /></div> : <>
+        <header id="gallery-page-heading" className="scroll-mt-36 lg:scroll-mt-24 space-y-3">
+          {selectedEntry && showingEntry ? <Button asChild variant="outline" size="sm"><Link href={`${GALLERY_BASE_PATH}?family=${activeFamilyId}`}><ArrowLeft aria-hidden />{t('design_system.gallery.backToNamedFamily', { family: familyTitle })}</Link></Button> : null}
+          {!showingComponents && (!selectedEntry || !showingEntry) ? <Button asChild variant="outline" size="sm"><Link href={`${GALLERY_BASE_PATH}?view=components`}><ArrowLeft aria-hidden />{t('design_system.gallery.backToNamedFamily', { family: t('design_system.portal.nav.components') })}</Link></Button> : null}
+          <h1 className="text-3xl font-semibold tracking-tight">{pageTitle}</h1>
+          {showingEntry && selectedEntry?.descriptionKey ? <p className="max-w-prose text-sm leading-relaxed text-muted-foreground">{t(selectedEntry.descriptionKey)}</p> : null}
+          {showingComponents ? <p className="text-base text-muted-foreground">{t('design_system.portal.componentsDescription')}</p> : null}
+        </header>
+        {!showingAssets && !showingInventory && !showingEntry ? <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()}
+        /> : null}
+        {searching ? renderSearchResults() : showingComponents ? <ComponentIndex families={componentFamilies} loaded={loaded} failed={failed} onRetry={loadFamily} /> : renderActiveFamily()}
+        </>}
       </div>
-    </SectionPage>
+      </div>
+    </div>
   )
 }

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

@@ -0,0 +1,40 @@
+'use client'
+
+import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@open-mercato/ui/primitives/select'
+import { SourceIconCatalogue } from '../demos/source-icons'
+import { SourceArtworkCatalogue } from '../demos/source-artwork'
+import { IconGrid } from '../demos/registered-icons'
+import type { SourceArtworkGroup } from '@open-mercato/ui/assets/source-artwork'
+
+const collections: { id: string; entryId: string; variantId: string; group?: SourceArtworkGroup }[] = [
+  { id: 'icons', entryId: 'source-icons', variantId: 'catalogue' },
+  { id: 'brands', entryId: 'source-artwork', variantId: 'brands', group: 'brand' },
+  { id: 'flags', entryId: 'source-artwork', variantId: 'flags', group: 'country-flags' },
+  { id: 'emoji', entryId: 'source-artwork', variantId: 'emoji', group: 'emojies' },
+  { id: 'badges', entryId: 'source-artwork', variantId: 'store-badges', group: 'appstore-badges' },
+  { id: 'thumbnails', entryId: 'source-artwork', variantId: 'thumbnails', group: 'thumbnails' },
+  { id: 'cursors', entryId: 'source-artwork', variantId: 'cursors', group: 'others' },
+  { id: 'registered', entryId: 'icon-registry', variantId: 'registry' },
+]
+
+export function IconsBrowser({ entryId, variantId, onNavigate }: {
+  entryId?: string
+  variantId?: string
+  onNavigate: (entryId: string, variantId?: string) => void
+}) {
+  const t = useT()
+  const collection = collections.find(item => item.entryId === entryId && item.variantId === variantId)
+    ?? collections.find(item => item.entryId === entryId)
+    ?? collections[0]
+  const collectionControl = <Select value={collection.id} onValueChange={value => {
+      const next = collections.find(item => item.id === value)
+      if (next) onNavigate(next.entryId, next.variantId)
+    }}>
+      <SelectTrigger className="w-64 max-w-full" aria-label={t('design_system.gallery.assets.collection')}><SelectValue /></SelectTrigger>
+      <SelectContent>{collections.map(item => <SelectItem key={item.id} value={item.id}>{t(`design_system.gallery.assets.${item.id}`)}</SelectItem>)}</SelectContent>
+    </Select>
+  return collection.group ? <SourceArtworkCatalogue key={collection.id} group={collection.group} collectionControl={collectionControl} />
+    : collection.id === 'registered' ? <IconGrid collectionControl={collectionControl} /> : <SourceIconCatalogue collectionControl={collectionControl} />
+}

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

@@ -0,0 +1,90 @@
+'use client'
+
+import * as React from 'react'
+import { GalleryLink as Link } from './GalleryLink'
+import { ArrowRight } from 'lucide-react'
+import { LinkButton } from '@open-mercato/ui/primitives/link-button'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { EmptyState } from '@open-mercato/ui/primitives/empty-state'
+import { Pagination } from '@open-mercato/ui/primitives/pagination'
+import { SearchInput } from '@open-mercato/ui/primitives/search-input'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@open-mercato/ui/primitives/select'
+import { GALLERY_BASE_PATH } from '../registry'
+import { sourceLibrary } from '../source-library.generated'
+
+const pageSize = 12
+const allGroups = '__all'
+const groupTranslationKey = (group: string) => `design_system.gallery.sourceLibrary.groups.${group.toLowerCase().replace(/\s+/g, '-')}`
+
+export function SourceLibrary() {
+  const t = useT()
+  const storyTitle = (story: { family: string; entryId: string; title: string }) => story.family === 'foundations'
+    ? t(`design_system.foundations.${story.entryId}.title`, story.title)
+    : story.title
+  const [query, setQuery] = React.useState('')
+  const [group, setGroup] = React.useState(allGroups)
+  const [page, setPage] = React.useState(1)
+  const groups = React.useMemo(() => Array.from(new Set(sourceLibrary.pages.map(item => item.group))), [])
+  const needle = query.trim().toLowerCase()
+  const filtered = sourceLibrary.pages.filter(item => {
+    const matchesGroup = group === allGroups || item.group === group
+    const translatedName = t(`design_system.gallery.sourceLibrary.names.${item.id}`, item.name)
+    const translatedGroup = t(groupTranslationKey(item.group), item.group)
+    const searchTerms = t(`design_system.gallery.sourceLibrary.searchTerms.${item.id}`, '')
+    const searchable = `${item.name} ${translatedName} ${item.group} ${translatedGroup} ${searchTerms} ${item.stories.map(story => `${story.title} ${storyTitle(story)}`).join(' ')} ${item.sets.map(set => `${set.name} ${Object.values(set.axes).flat().join(' ')}`).join(' ')} ${item.standalone.map(asset => asset.name).join(' ')}`
+    return matchesGroup && searchable.toLowerCase().includes(needle)
+  })
+  const visible = filtered.slice((page - 1) * pageSize, page * pageSize)
+
+  return <div className="w-full min-w-0 space-y-4" data-example="native-source-library">
+    <p className="text-sm text-muted-foreground">{t('design_system.gallery.sourceLibrary.boundary')}</p>
+    <div className="flex flex-col gap-3 sm:flex-row">
+      <SearchInput className="sm:flex-1" value={query} onChange={value => { setQuery(value); setPage(1) }} aria-label={t('design_system.gallery.sourceLibrary.search')} placeholder={t('design_system.gallery.sourceLibrary.search')} />
+      <Select value={group} onValueChange={value => { setGroup(value); setPage(1) }}>
+        <SelectTrigger className="w-full sm:w-64" aria-label={t('design_system.gallery.sourceLibrary.group')}><SelectValue /></SelectTrigger>
+        <SelectContent>
+          <SelectItem value={allGroups}>{t('design_system.gallery.sourceLibrary.allGroups')}</SelectItem>
+          {groups.map(value => <SelectItem key={value} value={value}>{t(groupTranslationKey(value), value)}</SelectItem>)}
+        </SelectContent>
+      </Select>
+    </div>
+    <p role="status" className="text-sm text-muted-foreground">{t('design_system.gallery.sourceLibrary.count', { visible: filtered.length, total: sourceLibrary.pages.length })}</p>
+    {visible.length ? <div className="divide-y divide-border rounded-lg border border-border bg-card">{visible.map(item => {
+      const variantCount = item.sets.reduce((total, set) => total + set.count, 0)
+      const hasInventory = item.sets.length > 0 || item.standaloneCount > 0 || item.frameCount > 0
+      return <article key={item.id} className="grid min-w-0 gap-4 p-5 lg:grid-cols-3">
+        <header className="space-y-1">
+          <h3 className="text-base font-semibold leading-tight">{t(`design_system.gallery.sourceLibrary.names.${item.id}`, item.name)}</h3>
+          <p className="text-xs text-muted-foreground">{t(groupTranslationKey(item.group), item.group)}</p>
+        </header>
+        <div className="min-w-0 space-y-3 lg:col-span-2">
+          {item.stories.length ? <ul className="flex flex-wrap gap-x-6 gap-y-3" aria-label={t('design_system.gallery.sourceLibrary.examples')}>
+            {item.stories.map(story => <li key={`${story.family}:${story.entryId}`}>
+              <LinkButton asChild variant="black">
+                <Link href={`${GALLERY_BASE_PATH}?family=${story.family}&entry=${story.entryId}`}>
+                  {storyTitle(story)}<ArrowRight className="size-4 text-muted-foreground" aria-hidden="true" />
+                </Link>
+              </LinkButton>
+            </li>)}
+          </ul> : <p className="text-sm text-muted-foreground">{t('design_system.gallery.sourceLibrary.referenceOnly')}</p>}
+          {hasInventory ? <section className="text-sm">
+            <h4 className="text-xs font-medium text-muted-foreground">{t('design_system.gallery.sourceLibrary.details')}</h4>
+            <div className="mt-3 space-y-4 border-l border-border pl-4">
+              <div className="flex flex-wrap gap-x-4 gap-y-1 text-xs text-muted-foreground">
+                {item.sets.length ? <span>{t('design_system.gallery.sourceLibrary.componentSets', { count: item.sets.length })}</span> : null}
+                {variantCount ? <span>{t('design_system.gallery.sourceLibrary.variants', { count: variantCount })}</span> : null}
+                {item.frameCount ? <span>{t('design_system.gallery.sourceLibrary.frames', { count: item.frameCount })}</span> : null}
+                {item.standaloneCount ? <span>{t('design_system.gallery.sourceLibrary.assets', { count: item.standaloneCount })}</span> : null}
+              </div>
+              {item.sets.map(set => <section key={set.id} className="space-y-2">
+                <h4 className="text-sm font-medium">{set.name}</h4>
+                <dl className="space-y-2">{Object.entries(set.axes).map(([axis, values]) => <div key={axis} className="text-xs"><dt className="font-medium">{axis}</dt><dd className="break-words text-muted-foreground">{(values as string[]).join(' · ')}</dd></div>)}</dl>
+              </section>)}
+            </div>
+          </section> : null}
+        </div>
+      </article>
+    })}</div> : <EmptyState title={t('design_system.gallery.noResults')} />}
+    {filtered.length > pageSize ? <Pagination page={page} pageSize={pageSize} total={filtered.length} showPageSize={false} onPageChange={setPage} aria-label={t('design_system.gallery.sourceLibrary.pages')} /> : null}
+  </div>
+}

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

@@ -0,0 +1,115 @@
+'use client'
+
+import * as React from 'react'
+import { Check, ImagePlus, RotateCcw, Upload, X } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { SimpleTooltip } from '@open-mercato/ui/primitives/tooltip'
+import { getBrandStyle, saveBrandStyle, type BrandStyle } from '@open-mercato/ui/theme/brand-style'
+import { ColorPlayground } from './ColorPlayground'
+import { BrandStylePreview } from './BrandStylePreview'
+import { readThemeTokens, type ThemeTokens } from './themeTokens'
+import type { Shade } from './colorStudio'
+import type { ColorStudio } from './colorStudio'
+import { readBrandLogo, studioBrandStyle } from './styleAgentBranding'
+
+function brandPreview(studio: ColorStudio, logo: string | null) {
+  const style = studioBrandStyle(studio, logo)
+  return { light: style.light, dark: style.dark }
+}
+
+export function StyleAgents() {
+  const t = useT()
+  const input = React.useRef<HTMLInputElement>(null)
+  const uploadVersion = React.useRef(0)
+  const [initial, setInitial] = React.useState<BrandStyle | null | undefined>(undefined)
+  const [hostTokens, setHostTokens] = React.useState<ThemeTokens | null>(null)
+  const [logo, setLogo] = React.useState<string | null>(null)
+  const [draft, setDraft] = React.useState<{ studio: ColorStudio; valid: boolean } | null>(null)
+  const [uploading, setUploading] = React.useState(false)
+  const [notice, setNotice] = React.useState('')
+  const [error, setError] = React.useState('')
+  React.useEffect(() => {
+    setHostTokens(readThemeTokens(document.styleSheets))
+    const applied = getBrandStyle()
+    setInitial(applied)
+    setLogo(applied?.logo ?? null)
+    return () => { uploadVersion.current += 1 }
+  }, [])
+  const updateStudio = React.useCallback((studio: ColorStudio, valid: boolean) => {
+    setDraft({ studio, valid })
+    setNotice('')
+  }, [])
+
+  async function upload(file: File | undefined) {
+    if (!file) return
+    const version = ++uploadVersion.current
+    setUploading(true)
+    setError('')
+    setNotice('')
+    try {
+      const data = await readBrandLogo(file)
+      if (uploadVersion.current === version) setLogo(data)
+    } catch (failure) {
+      if (uploadVersion.current === version) setError(failure instanceof Error ? failure.message : 'fileDecode')
+    } finally {
+      if (uploadVersion.current === version) setUploading(false)
+    }
+  }
+
+  function apply() {
+    if (!draft?.valid || uploading) return
+    try {
+      saveBrandStyle(studioBrandStyle(draft.studio, logo))
+      setError('')
+      setNotice('applied')
+    } catch { setError('saveFailed'); setNotice('') }
+  }
+
+  function restore() {
+    try {
+      saveBrandStyle(null)
+      setError('')
+      setNotice('restored')
+    } catch { setError('saveFailed'); setNotice('') }
+  }
+
+  return <div className="space-y-8 pb-8" data-example="style-agents">
+    <header id="gallery-page-heading" className="scroll-mt-36 space-y-3 lg:scroll-mt-24">
+      <div className="flex flex-wrap items-start justify-between gap-4">
+        <div className="space-y-3">
+          <h1 className="text-3xl font-medium tracking-tight">{t('design_system.styleAgents.title')}</h1>
+          <p className="max-w-3xl text-sm leading-relaxed text-muted-foreground">{t('design_system.styleAgents.description')}</p>
+        </div>
+        <div className="flex flex-wrap items-center gap-2">
+          <SimpleTooltip content={t('design_system.styleAgents.restoreHint')}>
+            <Button type="button" variant="ghost" onClick={restore}><RotateCcw aria-hidden />{t('design_system.styleAgents.restore')}</Button>
+          </SimpleTooltip>
+          <Button type="button" onClick={apply} disabled={!draft?.valid || uploading}><Check aria-hidden />{t('design_system.styleAgents.apply')}</Button>
+        </div>
+      </div>
+      {notice ? <p role="status" className="text-sm text-status-success-text">{t(`design_system.styleAgents.${notice}`)}</p> : null}
+      {error ? <p role="alert" className="text-sm text-status-error-text">{t(`design_system.styleAgents.${error}`)}</p> : null}
+    </header>
+    <section className="grid gap-6 rounded-xl border border-border bg-card p-5 sm:p-6 lg:grid-cols-2" aria-label={t('design_system.styleAgents.identity')}>
+      <div className="space-y-4">
+        <div className="space-y-1"><h2 className="text-lg font-medium">{t('design_system.styleAgents.logo')}</h2><p className="text-xs leading-relaxed text-muted-foreground">{t('design_system.styleAgents.logoHint')}</p></div>
+        <div className="flex min-h-28 items-center justify-center rounded-lg border border-dashed border-border bg-background p-6">
+          {logo ? <img src={logo} alt={t('design_system.styleAgents.logoPreview')} className="max-h-20 max-w-full object-contain" /> : <ImagePlus className="size-8 text-muted-foreground" aria-hidden />}
+        </div>
+        <input ref={input} type="file" accept="image/png,image/jpeg,image/webp" className="sr-only" aria-label={t('design_system.styleAgents.upload')} onChange={event => { void upload(event.target.files?.[0]); event.target.value = '' }} />
+        <div className="flex flex-wrap gap-2">
+          <Button type="button" variant="outline" onClick={() => input.current?.click()}><Upload aria-hidden />{t(`design_system.styleAgents.${uploading ? 'uploading' : 'upload'}`)}</Button>
+          {logo ? <Button type="button" variant="ghost" onClick={() => { uploadVersion.current += 1; setUploading(false); setLogo(null); setNotice(''); setError('') }}><X aria-hidden />{t('design_system.styleAgents.removeLogo')}</Button> : null}
+        </div>
+      </div>
+      <div className="flex flex-col justify-between gap-5">
+        <div className="space-y-3"><h2 className="text-lg font-medium">{t('design_system.styleAgents.applyTitle')}</h2><p className="text-sm leading-relaxed text-muted-foreground">{t('design_system.styleAgents.scope')}</p><p className="text-xs leading-relaxed text-muted-foreground">{t('design_system.styleAgents.tokenScope')}</p></div>
+
+      </div>
+    </section>
+    {draft ? <BrandStylePreview {...brandPreview(draft.studio, logo)} hostTokens={hostTokens} logo={logo} /> : null}
+    {initial !== undefined ? <ColorPlayground initialView="light" initialSeeds={initial?.seeds} initialActionShades={initial?.actionShades as { light?: Shade; dark?: Shade } | undefined} logo={logo} onStudioChange={updateStudio} /> : null}
+
+  </div>
+}

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

@@ -0,0 +1,76 @@
+'use client'
+
+import * as React from 'react'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { DataTable } from '@open-mercato/ui/backend/DataTable'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { readThemeTokens, type ThemeTokens } from './themeTokens'
+
+const referenceTokens = [
+  'brand-lime', 'brand-yellow', 'brand-violet', 'background', 'foreground',
+  'card', 'card-foreground', 'muted', 'muted-foreground', 'primary', 'primary-foreground',
+  'primary-hover', 'border', 'input', 'ring', 'destructive',
+  'status-info-bg', 'status-info-text', 'status-success-bg', 'status-success-text',
+  'status-warning-bg', 'status-warning-text', 'status-error-bg', 'status-error-text',
+]
+type TokenRow = { token: string; light: string; dark: string }
+
+function displayColor(value: string, context: CanvasRenderingContext2D | null) {
+  if (!context || !CSS.supports('color', value)) return value
+  context.clearRect(0, 0, 1, 1)
+  context.fillStyle = value
+  context.fillRect(0, 0, 1, 1)
+  const [red, green, blue, alpha] = context.getImageData(0, 0, 1, 1).data
+  return '#' + [red, green, blue, ...(alpha === 255 ? [] : [alpha])].map(channel => channel.toString(16).padStart(2, '0')).join('').toUpperCase()
+}
+
+export function ThemeTokenReference() {
+  const t = useT()
+  const [tokens, setTokens] = React.useState<ThemeTokens | null>(null)
+  React.useEffect(() => {
+    const values = readThemeTokens(document.styleSheets)
+    const canvas = document.createElement('canvas')
+    canvas.width = 1
+    canvas.height = 1
+    const context = canvas.getContext('2d', { willReadFrequently: true })
+    for (const theme of ['light', 'dark'] as const) {
+      for (const token of referenceTokens) {
+        const value = values[theme][`--${token}`]
+        if (value) values[theme][`--${token}`] = displayColor(value, context)
+      }
+    }
+    setTokens(values)
+  }, [])
+  const rows = referenceTokens.map(token => ({ token: `--${token}`, light: tokens?.light[`--${token}`] ?? '—', dark: tokens?.dark[`--${token}`] ?? '—' }))
+  async function copyToken(token: string) {
+    try {
+      await navigator.clipboard.writeText(token)
+      flash(t('design_system.gallery.tokenCopied', { token }), 'success')
+    } catch { flash(t('design_system.gallery.tokenCopyFailed'), 'error') }
+  }
+  const columns: ColumnDef<TokenRow, unknown>[] = [
+    { accessorKey: 'token', header: t('design_system.foundations.token'), cell: ({ row }) => <Button type="button" variant="ghost" className="h-auto justify-start px-0 py-2 font-mono text-xs" aria-label={t('design_system.gallery.copyToken', { token: row.original.token })} onClick={() => copyToken(row.original.token)}>{row.original.token}</Button> },
+    ...(['light', 'dark'] as const).map(theme => ({
+      accessorKey: theme,
+      header: t(`design_system.foundations.${theme}`),
+      cell: ({ row }: { row: { original: TokenRow } }) => <span className="flex items-center gap-3 py-2"><span aria-hidden className="size-6 shrink-0 rounded-full border border-border" style={{ backgroundColor: row.original[theme] === '—' ? undefined : row.original[theme] }} /><code className="text-xs text-muted-foreground">{row.original[theme]}</code></span>,
+    })),
+  ]
+  return <div className="space-y-4">
+    <h3 className="text-xl font-medium">{t('design_system.foundations.themeReference')}</h3>
+    <p className="max-w-prose text-sm leading-relaxed text-muted-foreground">{t('design_system.foundations.themeDescription')}</p>
+    {tokens ? <div className="grid gap-4 sm:grid-cols-2">
+      {(['light', 'dark'] as const).map(theme => <div key={theme} className="space-y-6 rounded-lg border p-6" style={{ backgroundColor: tokens[theme]['--background'], color: tokens[theme]['--foreground'], borderColor: tokens[theme]['--border'] }}>
+        <p className="text-base font-medium">{t(`design_system.foundations.${theme}`)}</p>
+        <div className="flex flex-wrap items-center gap-3">
+          <Button type="button" style={{ backgroundColor: tokens[theme]['--primary'], color: tokens[theme]['--primary-foreground'] }}>{t('design_system.gallery.samples.primaryAction')}</Button>
+          <span className="inline-flex h-9 items-center rounded-md border px-4 text-sm" style={{ borderColor: tokens[theme]['--border'] }}>Aa</span>
+        </div>
+        <code className="text-xs" style={{ color: tokens[theme]['--muted-foreground'] }}>{tokens[theme]['--background']} / {tokens[theme]['--foreground']}</code>
+      </div>)}
+    </div> : null}
+    <DataTable columns={columns} data={rows} isLoading={!tokens} />
+  </div>
+}

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

@@ -6,9 +6,9 @@ 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 }) {
+export function VariantPreview({ children, framed = true }: { children: React.ReactNode; framed?: boolean }) {
   return (
-    <div className="flex flex-wrap items-center gap-3 rounded-md border border-border bg-background p-4">
+    <div className={framed ? 'flex min-w-0 flex-wrap items-start gap-4 rounded-lg border border-border bg-background p-4 sm:p-6 [&>*]:min-w-0' : 'min-w-0 [&>*]:min-w-0'}>
       {children}
     </div>
   )