@titan-design/react-ui 0.6.0 → 0.7.0

package/src/arch/Architecture.stories.tsx

@@ -0,0 +1,870 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useEffect, useMemo, useState } from 'react'
+import { getSemanticColors } from '../theme/tokens/semantic'
+import graph from './arch-graph.json'
+
+/**
+ * `Docs/Architecture` — a deterministic, regenerable map of the component library.
+ * Generated by `scripts/arch-graph.mjs` (codewatch symbol graph + a light import-parse
+ * of the consuming apps) → `arch-graph.json`. Two first-class sections: the internal
+ * dependency diagram (tiered by composition depth, click a node to pin it and inspect /
+ * render it) and the health audit (dead code, primitive-substitution leaks, extraction
+ * candidates). Regenerate with `node scripts/arch-graph.mjs --reindex`.
+ */
+
+const C = getSemanticColors('dark')
+
+type Comp = (typeof graph.components)[number]
+type Tier = 'atom' | 'molecule' | 'organism' | 'page'
+const TIERS: Tier[] = ['atom', 'molecule', 'organism', 'page']
+const TIER_LABEL: Record<Tier, string> = {
+  atom: 'Atoms',
+  molecule: 'Molecules',
+  organism: 'Organisms',
+  page: 'Pages',
+}
+
+const VERDICT: Record<string, { label: string; color: string }> = {
+  'keep-core': { label: 'Core (lib + app)', color: C['status-success'] },
+  'keep-internal': { label: 'Internal only', color: C['status-info'] },
+  'keep-app': { label: 'App-facing leaf', color: C['brand-secondary'] },
+  'keep-page': { label: 'Shipped page', color: C['status-success'] },
+  'demo-only': { label: 'Demo page (unshipped)', color: C['status-warning'] },
+  remove: { label: 'Throwaway → remove', color: C['text-tertiary'] },
+  dead: { label: 'Dead everywhere', color: C['status-error-vivid'] },
+}
+const verdictColor = (v: string) => VERDICT[v]?.color ?? C['text-tertiary']
+const byName: Record<string, Comp> = Object.fromEntries(graph.components.map((c) => [c.name, c]))
+
+// reverse edges: who composes each component
+const usedByMap: Record<string, string[]> = {}
+for (const [a, b] of graph.edges) (usedByMap[b] ||= []).push(a)
+
+// ---- storybook story index (component file -> its default story id) --------
+function useStoryIndex() {
+  const [map, setMap] = useState<Record<string, string>>({})
+  useEffect(() => {
+    let live = true
+    fetch('index.json')
+      .then((r) => r.json())
+      .then(
+        (idx: {
+          entries?: Record<
+            string,
+            { type?: string; id?: string; importPath?: string; componentPath?: string }
+          >
+        }) => {
+          if (!live) return
+          const m: Record<string, string> = {}
+          for (const e of Object.values(idx.entries ?? {})) {
+            if (e.type !== 'story' || !e.id) continue
+            const cp = (e.componentPath ?? '')
+              .split('/')
+              .pop()
+              ?.replace(/\.(t|j)sx?$/, '')
+            const ip = (e.importPath ?? '')
+              .split('/')
+              .pop()
+              ?.replace(/\.stories\.(t|j)sx?$/, '')
+            const name = cp || ip
+            if (name && !m[name]) m[name] = e.id // first story per component wins
+          }
+          setMap(m)
+        }
+      )
+      .catch(() => {})
+    return () => {
+      live = false
+    }
+  }, [])
+  return map
+}
+
+// ---- layout ---------------------------------------------------------------
+const COL_W = 250
+const NODE_H = 24
+const NODE_GAP = 6
+const ROW = NODE_H + NODE_GAP
+const PAD_TOP = 40
+const NODE_W = 196
+
+function useLayout() {
+  return useMemo(() => {
+    const cols: Record<Tier, Comp[]> = { atom: [], molecule: [], organism: [], page: [] }
+    for (const c of graph.components) cols[c.tier as Tier].push(c)
+    for (const t of TIERS) cols[t].sort((a, b) => b.leak.score - a.leak.score)
+    const pos: Record<string, { x: number; y: number }> = {}
+    TIERS.forEach((t, ci) => {
+      cols[t].forEach((c, ri) => {
+        pos[c.name] = { x: ci * COL_W + 20, y: PAD_TOP + ri * ROW }
+      })
+    })
+    const height = PAD_TOP + Math.max(...TIERS.map((t) => cols[t].length)) * ROW + 20
+    return { cols, pos, height, width: TIERS.length * COL_W + 20 }
+  }, [])
+}
+
+function neighborsOf(active: string | null) {
+  if (!active) return null
+  const set = new Set<string>([active])
+  for (const [a, b] of graph.edges) {
+    if (a === active) set.add(b)
+    if (b === active) set.add(a)
+  }
+  return set
+}
+
+// ---- dependency diagram ---------------------------------------------------
+function Diagram({
+  selected,
+  onSelect,
+  onOpenRender,
+}: {
+  selected: string | null
+  onSelect: (name: string | null) => void
+  onOpenRender: (name: string) => void
+}) {
+  const { cols, pos, height, width } = useLayout()
+  const [hover, setHover] = useState<string | null>(null)
+  const active = selected ?? hover
+  const neighbors = useMemo(() => neighborsOf(active), [active])
+
+  const edgePath = (a: string, b: string) => {
+    const s = pos[a]
+    const t = pos[b]
+    if (!s || !t) return null
+    const x1 = s.x
+    const y1 = s.y + NODE_H / 2
+    const x2 = t.x + NODE_W
+    const y2 = t.y + NODE_H / 2
+    const mx = (x1 + x2) / 2
+    return `M${x1},${y1} C${mx},${y1} ${mx},${y2} ${x2},${y2}`
+  }
+
+  return (
+    <div
+      onClick={() => onSelect(null)}
+      style={{
+        overflow: 'auto',
+        border: `1px solid ${C['border-subtle']}`,
+        borderRadius: 8,
+        background: C['surface-base'],
+      }}
+    >
+      <svg width={width} height={height} style={{ display: 'block', minWidth: '100%' }}>
+        {TIERS.map((t, ci) => (
+          <text
+            key={t}
+            x={ci * COL_W + 20}
+            y={22}
+            fill={C['text-secondary']}
+            fontSize={12}
+            fontWeight={700}
+            fontFamily="Inter, sans-serif"
+          >
+            {TIER_LABEL[t]} · {cols[t].length}
+          </text>
+        ))}
+        {graph.edges.map(([a, b], i) => {
+          const d = edgePath(a, b)
+          if (!d) return null
+          const on = neighbors ? neighbors.has(a) && neighbors.has(b) : false
+          const dim = neighbors && !on
+          return (
+            <path
+              key={i}
+              d={d}
+              fill="none"
+              stroke={on ? C['brand-primary'] : C['border-prominent']}
+              strokeWidth={on ? 1.8 : 1}
+              opacity={dim ? 0.04 : on ? 0.95 : 0.45}
+            />
+          )
+        })}
+        {graph.components.map((c) => {
+          const p = pos[c.name]
+          const isSel = selected === c.name
+          const dim = neighbors ? !neighbors.has(c.name) : false
+          return (
+            <g
+              key={c.name}
+              transform={`translate(${p.x},${p.y})`}
+              opacity={dim ? 0.25 : 1}
+              style={{ cursor: 'pointer' }}
+              onMouseEnter={() => setHover(c.name)}
+              onMouseLeave={() => setHover(null)}
+              onClick={(e) => {
+                e.stopPropagation()
+                onSelect(isSel ? null : c.name)
+              }}
+            >
+              <rect
+                width={NODE_W}
+                height={NODE_H}
+                rx={5}
+                fill={isSel ? C['interactive-selected'] : C['surface-raised']}
+                stroke={isSel ? C['brand-primary'] : verdictColor(c.verdict)}
+                strokeWidth={isSel ? 2 : c.verdict === 'dead' ? 1.6 : 1}
+              />
+              <rect width={4} height={NODE_H} rx={2} fill={verdictColor(c.verdict)} />
+              {c.deadByAssociation && (
+                <rect
+                  width={NODE_W}
+                  height={NODE_H}
+                  rx={5}
+                  fill="none"
+                  stroke={C['status-warning']}
+                  strokeWidth={1}
+                  strokeDasharray="3 3"
+                />
+              )}
+              {c.audited === 'audited' && (
+                <circle cx={NODE_W - 30} cy={NODE_H / 2} r={3} fill={C['status-success']} />
+              )}
+              <text
+                x={11}
+                y={NODE_H / 2 + 4}
+                fill={C['text-primary']}
+                fontSize={11.5}
+                fontFamily="Inter, sans-serif"
+              >
+                {c.name}
+              </text>
+              <text
+                x={NODE_W - 26}
+                y={NODE_H / 2 + 4}
+                textAnchor="end"
+                fill={C['text-tertiary']}
+                fontSize={9.5}
+                fontFamily="monospace"
+              >
+                {c.libDependents}·{c.xproj.total}
+              </text>
+              <g
+                onClick={(e) => {
+                  e.stopPropagation()
+                  onOpenRender(c.name)
+                }}
+                style={{ cursor: 'pointer' }}
+              >
+                <rect
+                  x={NODE_W - 21}
+                  y={4}
+                  width={17}
+                  height={16}
+                  rx={3}
+                  fill={C['surface-elevated']}
+                  stroke={C['border-default']}
+                />
+                <text
+                  x={NODE_W - 12.5}
+                  y={15.5}
+                  textAnchor="middle"
+                  fill={C['text-secondary']}
+                  fontSize={11}
+                  fontFamily="Inter, sans-serif"
+                >
+                  ↗
+                </text>
+              </g>
+            </g>
+          )
+        })}
+      </svg>
+    </div>
+  )
+}
+
+// ---- detail panel (pinned selection) --------------------------------------
+function DepLine({ label, items }: { label: string; items: string[] }) {
+  return (
+    <div style={{ display: 'flex', gap: 8, alignItems: 'baseline', flexWrap: 'wrap' }}>
+      <span style={{ color: C['text-tertiary'], fontSize: 11, minWidth: 74 }}>{label}</span>
+      {items.length ? (
+        items.map((n) => (
+          <span
+            key={n}
+            style={{
+              fontSize: 12,
+              color: C['text-secondary'],
+              background: C['surface-raised'],
+              border: `1px solid ${C['border-subtle']}`,
+              borderRadius: 5,
+              padding: '1px 7px',
+            }}
+          >
+            {n}
+          </span>
+        ))
+      ) : (
+        <span style={{ fontSize: 12, color: C['text-tertiary'] }}>—</span>
+      )}
+    </div>
+  )
+}
+
+function DetailPanel({
+  comp,
+  onOpenRender,
+  onClose,
+}: {
+  comp: Comp
+  onOpenRender: (name: string) => void
+  onClose: () => void
+}) {
+  const usedBy = usedByMap[comp.name] ?? []
+  const v = VERDICT[comp.verdict]
+  return (
+    <div
+      style={{
+        margin: '10px 0',
+        padding: 14,
+        borderRadius: 8,
+        background: C['surface-elevated'],
+        border: `1px solid ${C['border-default']}`,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 8,
+      }}
+    >
+      <div style={{ display: 'flex', alignItems: 'center', gap: 10, flexWrap: 'wrap' }}>
+        <span
+          style={{
+            width: 10,
+            height: 10,
+            borderRadius: 999,
+            background: verdictColor(comp.verdict),
+          }}
+        />
+        <span style={{ fontSize: 16, fontWeight: 700, color: C['text-primary'] }}>{comp.name}</span>
+        <span style={{ fontSize: 12, color: C['text-secondary'] }}>
+          {comp.tier} · {v?.label ?? comp.verdict}
+        </span>
+        <span style={{ fontFamily: 'monospace', fontSize: 12, color: C['text-tertiary'] }}>
+          lib {comp.libDependents} · story {comp.storyRefs} · app {comp.xproj.total}
+        </span>
+        {comp.standard && <Chip color={C['brand-secondary']}>standard</Chip>}
+        <Chip color={comp.audited === 'audited' ? C['status-success'] : C['text-tertiary']}>
+          {comp.audited === 'audited'
+            ? 'audited'
+            : comp.audited === 'reviewing'
+              ? 'reviewing'
+              : 'unaudited'}
+        </Chip>
+        {comp.deadByAssociation && <Chip color={C['status-warning']}>⚠ only dead consumers</Chip>}
+        <div style={{ flex: 1 }} />
+        <button
+          onClick={() => onOpenRender(comp.name)}
+          style={btn(C['brand-primary'], C['on-brand-primary'])}
+        >
+          View rendering ↗
+        </button>
+        <button onClick={onClose} style={btn(C['surface-raised'], C['text-secondary'])}>
+          ✕ unpin
+        </button>
+      </div>
+      <DepLine label="composes ↓" items={comp.dependsOn} />
+      <DepLine label="used-by ↑" items={usedBy} />
+    </div>
+  )
+}
+const btn = (bg: string, fg: string): React.CSSProperties => ({
+  background: bg,
+  color: fg,
+  border: 'none',
+  borderRadius: 6,
+  padding: '5px 11px',
+  fontSize: 12,
+  fontWeight: 600,
+  cursor: 'pointer',
+  fontFamily: 'Inter, sans-serif',
+})
+
+// ---- render modal (embeds the component's Storybook story) -----------------
+function RenderModal({
+  name,
+  storyId,
+  onClose,
+}: {
+  name: string
+  storyId?: string
+  onClose: () => void
+}) {
+  return (
+    <div
+      onClick={onClose}
+      style={{
+        position: 'fixed',
+        inset: 0,
+        background: 'rgba(0,0,0,0.66)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        zIndex: 1000,
+      }}
+    >
+      <div
+        onClick={(e) => e.stopPropagation()}
+        style={{
+          width: 'min(940px, 92vw)',
+          height: 'min(620px, 88vh)',
+          background: C['surface-base'],
+          border: `1px solid ${C['border-default']}`,
+          borderRadius: 10,
+          display: 'flex',
+          flexDirection: 'column',
+          overflow: 'hidden',
+        }}
+      >
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: 10,
+            padding: '10px 14px',
+            borderBottom: `1px solid ${C['border-subtle']}`,
+          }}
+        >
+          <span style={{ fontSize: 15, fontWeight: 700, color: C['text-primary'] }}>{name}</span>
+          <span style={{ fontSize: 12, color: C['text-tertiary'] }}>live Storybook render</span>
+          <div style={{ flex: 1 }} />
+          {storyId && (
+            <a
+              href={`?path=/story/${storyId}`}
+              target="_blank"
+              rel="noreferrer"
+              style={{ ...btn(C['surface-raised'], C['text-secondary']), textDecoration: 'none' }}
+            >
+              open full story ↗
+            </a>
+          )}
+          <button onClick={onClose} style={btn(C['surface-raised'], C['text-secondary'])}>
+            ✕ close
+          </button>
+        </div>
+        {storyId ? (
+          <iframe
+            title={name}
+            src={`iframe.html?id=${storyId}&viewMode=story`}
+            style={{ flex: 1, width: '100%', border: 'none', background: C['background-base'] }}
+          />
+        ) : (
+          <div
+            style={{
+              flex: 1,
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              color: C['text-tertiary'],
+              fontSize: 14,
+              textAlign: 'center',
+              padding: 24,
+            }}
+          >
+            No Storybook story found for{' '}
+            <span style={{ color: C['text-secondary'], margin: '0 5px' }}>{name}</span>{' '}
+            {byName[name]?.verdict === 'remove'
+              ? '(throwaway — slated for removal).'
+              : '(this component has no story to render).'}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+// ---- health tables --------------------------------------------------------
+function Chip({ color, children }: { color: string; children: React.ReactNode }) {
+  return (
+    <span
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 5,
+        padding: '3px 9px',
+        borderRadius: 999,
+        background: C['surface-raised'],
+        border: `1px solid ${C['border-subtle']}`,
+        fontSize: 12,
+        color: C['text-secondary'],
+      }}
+    >
+      <span style={{ width: 8, height: 8, borderRadius: 999, background: color }} />
+      {children}
+    </span>
+  )
+}
+
+function Th({ children, right }: { children: React.ReactNode; right?: boolean }) {
+  return (
+    <th
+      style={{
+        textAlign: right ? 'right' : 'left',
+        padding: '6px 12px',
+        color: C['text-tertiary'],
+        fontSize: 11,
+        fontWeight: 600,
+        textTransform: 'uppercase',
+        letterSpacing: 0.5,
+        borderBottom: `1px solid ${C['border-subtle']}`,
+      }}
+    >
+      {children}
+    </th>
+  )
+}
+function Td({
+  children,
+  right,
+  mono,
+}: {
+  children: React.ReactNode
+  right?: boolean
+  mono?: boolean
+}) {
+  return (
+    <td
+      style={{
+        textAlign: right ? 'right' : 'left',
+        padding: '6px 12px',
+        color: C['text-primary'],
+        fontSize: 13,
+        fontFamily: mono ? 'monospace' : 'inherit',
+        borderBottom: `1px solid ${C['border-subtle']}`,
+      }}
+    >
+      {children}
+    </td>
+  )
+}
+
+function DeadTable() {
+  const dead = graph.components.filter(
+    (c) =>
+      c.verdict === 'dead' ||
+      c.verdict === 'remove' ||
+      c.verdict === 'demo-only' ||
+      c.deadByAssociation
+  )
+  const label = (c: Comp) =>
+    c.deadByAssociation && c.verdict.startsWith('keep')
+      ? { text: 'Only dead consumers', color: C['status-warning'] }
+      : { text: VERDICT[c.verdict]?.label ?? c.verdict, color: verdictColor(c.verdict) }
+  return (
+    <table style={{ width: '100%', borderCollapse: 'collapse' }}>
+      <thead>
+        <tr>
+          <Th>Component</Th>
+          <Th>Tier</Th>
+          <Th>Status</Th>
+          <Th right>lib</Th>
+          <Th right>story</Th>
+          <Th right>app</Th>
+        </tr>
+      </thead>
+      <tbody>
+        {dead.map((c) => {
+          const l = label(c)
+          return (
+            <tr key={c.name}>
+              <Td>{c.name}</Td>
+              <Td>{c.tier}</Td>
+              <Td>
+                <Chip color={l.color}>{l.text}</Chip>
+              </Td>
+              <Td right mono>
+                {c.libDependents}
+              </Td>
+              <Td right mono>
+                {c.storyRefs}
+              </Td>
+              <Td right mono>
+                {c.xproj.total}
+              </Td>
+            </tr>
+          )
+        })}
+      </tbody>
+    </table>
+  )
+}
+
+function StandardCoverageTable() {
+  const cov = graph.summary.standardCoverage
+  const cats = [...new Set(cov.map((s) => s.category))]
+  const statusChip: Record<string, { label: string; color: string }> = {
+    present: { label: 'present', color: C['status-success'] },
+    'present-dead': { label: 'present but dead', color: C['status-warning'] },
+    missing: { label: 'missing', color: C['status-error-vivid'] },
+  }
+  return (
+    <table style={{ width: '100%', borderCollapse: 'collapse' }}>
+      <thead>
+        <tr>
+          <Th>Category</Th>
+          <Th>Standard component</Th>
+          <Th>Status</Th>
+          <Th>Our component</Th>
+        </tr>
+      </thead>
+      <tbody>
+        {cats.flatMap((cat) =>
+          cov
+            .filter((s) => s.category === cat)
+            .map((s) => {
+              const sc = statusChip[s.status]
+              return (
+                <tr key={cat + s.name}>
+                  <Td>{s.category}</Td>
+                  <Td>{s.name}</Td>
+                  <Td>
+                    <Chip color={sc.color}>{sc.label}</Chip>
+                  </Td>
+                  <Td mono>{s.have.length ? s.have.join(', ') : '—'}</Td>
+                </tr>
+              )
+            })
+        )}
+      </tbody>
+    </table>
+  )
+}
+
+function SubstitutionTable() {
+  const sub = graph.summary.substitution
+  const prims = Object.keys(sub['library(titan)'] ?? {})
+  const scopes = Object.keys(sub)
+  return (
+    <table style={{ width: '100%', borderCollapse: 'collapse' }}>
+      <thead>
+        <tr>
+          <Th>Scope</Th>
+          {prims.map((p) => (
+            <Th key={p} right>
+              {p}
+            </Th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {scopes.map((s) => (
+          <tr key={s}>
+            <Td>{s}</Td>
+            {prims.map((p) => {
+              const val = (sub as Record<string, Record<string, number>>)[s][p] ?? 0
+              return (
+                <Td key={p} right mono>
+                  {val > 0 ? val : '·'}
+                </Td>
+              )
+            })}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  )
+}
+
+function ExtractionTable() {
+  return (
+    <table style={{ width: '100%', borderCollapse: 'collapse' }}>
+      <thead>
+        <tr>
+          <Th>Component</Th>
+          <Th>Tier</Th>
+          <Th right>{'<View>'}</Th>
+          <Th right>{'<Text>'}</Th>
+          <Th right>{'style={{'}</Th>
+          <Th right>rawHex</Th>
+          <Th right>loc</Th>
+          <Th right>score</Th>
+        </tr>
+      </thead>
+      <tbody>
+        {graph.summary.extractionTop.map((r) => (
+          <tr key={r.name}>
+            <Td>{r.name}</Td>
+            <Td>{r.tier}</Td>
+            <Td right mono>
+              {r.rawView}
+            </Td>
+            <Td right mono>
+              {r.rawText}
+            </Td>
+            <Td right mono>
+              {r.inlineStyle}
+            </Td>
+            <Td right mono>
+              {r.rawHex > 0 ? r.rawHex : '·'}
+            </Td>
+            <Td right mono>
+              {r.loc}
+            </Td>
+            <Td right mono>
+              {r.score}
+            </Td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  )
+}
+
+function Section({
+  title,
+  subtitle,
+  children,
+}: {
+  title: string
+  subtitle: string
+  children: React.ReactNode
+}) {
+  return (
+    <section style={{ marginTop: 28 }}>
+      <h2
+        style={{
+          color: C['text-primary'],
+          fontSize: 18,
+          fontWeight: 700,
+          margin: 0,
+          fontFamily: 'Inter, sans-serif',
+        }}
+      >
+        {title}
+      </h2>
+      <p
+        style={{
+          color: C['text-tertiary'],
+          fontSize: 13,
+          margin: '4px 0 12px',
+          fontFamily: 'Inter, sans-serif',
+        }}
+      >
+        {subtitle}
+      </p>
+      {children}
+    </section>
+  )
+}
+
+function ArchitecturePage() {
+  const [selected, setSelected] = useState<string | null>(null)
+  const [modalFor, setModalFor] = useState<string | null>(null)
+  const storyIndex = useStoryIndex()
+  const dead = graph.components.filter((c) => c.verdict === 'dead').length
+  const libLeak = graph.summary.substitution['library(titan)']
+  const leakText = (libLeak?.Text ?? 0) + (libLeak?.View ?? 0)
+  const standardDead = graph.summary.standardCoverage.filter(
+    (s) => s.status === 'present-dead'
+  ).length
+  const standardMissing = graph.summary.standardCoverage.filter(
+    (s) => s.status === 'missing'
+  ).length
+  const sel = selected ? byName[selected] : null
+
+  return (
+    <div
+      style={{
+        padding: 28,
+        background: C['background-base'],
+        minHeight: '100vh',
+        fontFamily: 'Inter, sans-serif',
+      }}
+    >
+      <h1 style={{ color: C['text-primary'], fontSize: 26, fontWeight: 800, margin: 0 }}>
+        Component Architecture
+      </h1>
+      <p style={{ color: C['text-secondary'], fontSize: 14, margin: '6px 0 16px', maxWidth: 760 }}>
+        Deterministic dependency + health map from the codewatch symbol graph and the consuming
+        apps. Node label shows <span style={{ fontFamily: 'monospace' }}>lib·app</span> usage.
+        Regenerate:{' '}
+        <span style={{ fontFamily: 'monospace', color: C['text-primary'] }}>
+          node scripts/arch-graph.mjs --reindex
+        </span>
+        .
+      </p>
+      <div style={{ display: 'flex', gap: 10, flexWrap: 'wrap', marginBottom: 8 }}>
+        <Chip color={C['text-secondary']}>{graph.components.length} components</Chip>
+        <Chip color={C['status-error-vivid']}>{dead} dead everywhere</Chip>
+        <Chip color={C['status-warning']}>
+          {graph.summary.deadByAssociation.length} dead-by-association
+        </Chip>
+        <Chip color={C['status-info']}>
+          {graph.summary.auditedCount}/{graph.components.length} audited
+        </Chip>
+        <Chip color={C['brand-secondary']}>
+          {standardDead} standard dead · {standardMissing} missing
+        </Chip>
+        <Chip color={C['status-warning']}>{leakText} raw Text/View leaks in-library</Chip>
+        {graph.summary.consumers.map((c) => (
+          <Chip key={c.name} color={c.present ? C['status-success'] : C['text-tertiary']}>
+            {c.name}
+            {c.present ? '' : ' (absent)'}
+          </Chip>
+        ))}
+      </div>
+
+      <Section
+        title="Dependency diagram"
+        subtitle="Columns by composition depth (leaves = atoms). Hover to trace, click a node to pin it, or press ↗ on any node to render the component live. Border color = verdict; dashed outline = only dead consumers."
+      >
+        <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap', marginBottom: 10 }}>
+          {Object.entries(VERDICT).map(([k, v]) => (
+            <Chip key={k} color={v.color}>
+              {v.label}
+            </Chip>
+          ))}
+        </div>
+        {sel && (
+          <DetailPanel comp={sel} onOpenRender={setModalFor} onClose={() => setSelected(null)} />
+        )}
+        <Diagram selected={selected} onSelect={setSelected} onOpenRender={setModalFor} />
+      </Section>
+
+      <Section
+        title="Standard component coverage"
+        subtitle="The canonical set a design system is expected to provide (curated in annotations.json), cross-referenced against what we ship. 'present but dead' = we built it but nothing uses it."
+      >
+        <StandardCoverageTable />
+      </Section>
+
+      <Section
+        title="Dead & unshipped"
+        subtitle="Zero production dependents in the library AND zero imports across all apps (dead everywhere), or kept alive only by other dead components (only dead consumers). Dashed warning outline in the diagram."
+      >
+        <DeadTable />
+      </Section>
+
+      <Section
+        title="Primitive-substitution leaks"
+        subtitle="Files importing a raw RN primitive that a titan atom already covers (Text→Typography, View→Surface/Stack, Pressable→Button…). The library bypassing its own primitives is the root cause of drift."
+      >
+        <SubstitutionTable />
+      </Section>
+
+      <Section
+        title="Extraction candidates"
+        subtitle="Highest inline-primitive density — repeated raw <View>/<Text>/style blocks and hardcoded hex that could be promoted into reusable primitives. rawHex flags token violations."
+      >
+        <ExtractionTable />
+      </Section>
+
+      {modalFor && (
+        <RenderModal
+          name={modalFor}
+          storyId={storyIndex[modalFor]}
+          onClose={() => setModalFor(null)}
+        />
+      )}
+    </div>
+  )
+}
+
+const meta: Meta = {
+  title: 'Docs/Architecture',
+  parameters: { layout: 'fullscreen' },
+}
+export default meta
+type Story = StoryObj
+
+export const Overview: Story = { render: () => <ArchitecturePage /> }