@discourser/design-system 0.25.3 → 0.27.0

package/src/stories/foundations/TokenReference.stories.tsx

@@ -0,0 +1,970 @@
+/**
+ * Token Reference — auto-generated from docs/token-name-mapping.json
+ *
+ * This file imports the JSON directly. It is always current — no manual
+ * editing required. To update the tables, run:
+ *
+ *   pnpm figma:export
+ *
+ * then rebuild Storybook. The JSON is regenerated by
+ * scripts/export-figma-tokens.ts as part of that command.
+ */
+
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { CSSProperties } from 'react';
+import tokenMap from '../../../docs/token-name-mapping.json';
+
+// ── Types inferred from the JSON shape ───────────────────────────────────────
+
+interface SemanticEntry {
+  figmaPath: string;
+  pandaToken: string;
+  cssProperty: string;
+  exampleUsage: string;
+  note?: string;
+}
+
+interface SpacingShapeEntry {
+  figmaPath: string;
+  pandaToken: string;
+  pandaCategory: string;
+  cssProperty: string;
+  exampleUsage: string;
+}
+
+interface EffectStyleEntry {
+  figmaEffectStyle: string;
+  pandaToken: string;
+  pandaCategory: string;
+  cssProperty: string;
+  description: string;
+  exampleUsage: string;
+}
+
+interface PandaOnlyEntry {
+  pandaToken: string;
+  cssProperty: string;
+  notes?: string;
+  exampleUsage: string;
+}
+
+interface ShadowAliasEntry {
+  pandaToken: string;
+  cssProperty: string;
+  resolvesTo: string;
+  description?: string;
+  exampleUsage: string;
+}
+
+interface TextStyleEntry {
+  figmaTextStyle: string;
+  figmaDescription: string;
+  ddsTokenPath: string;
+  pandaTextStyle: string;
+  fontFamily: string;
+  fontStyle: string;
+  fontWeight: number;
+  fontSize: number;
+  lineHeightPx: number;
+  letterSpacing: number;
+  isDefaultWeight: boolean;
+  exampleUsage: string;
+}
+
+// ── Shared style helpers ─────────────────────────────────────────────────────
+
+const T: Record<string, CSSProperties> = {
+  page: {
+    fontFamily: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif',
+    fontSize: '14px',
+    color: '#1a1a1a',
+    maxWidth: '1100px',
+  },
+  section: {
+    marginBottom: '56px',
+  },
+  h2: {
+    fontSize: '20px',
+    fontWeight: '600',
+    margin: '0 0 4px',
+    color: '#111',
+  },
+  meta: {
+    fontSize: '12px',
+    color: '#888',
+    margin: '0 0 20px',
+    fontFamily: 'monospace',
+  },
+  table: {
+    width: '100%',
+    borderCollapse: 'collapse' as const,
+    fontSize: '13px',
+  },
+  th: {
+    textAlign: 'left' as const,
+    padding: '8px 12px',
+    background: '#f4f4f4',
+    borderBottom: '2px solid #e0e0e0',
+    fontWeight: '600',
+    fontSize: '12px',
+    color: '#444',
+    whiteSpace: 'nowrap' as const,
+  },
+  td: {
+    padding: '8px 12px',
+    borderBottom: '1px solid #f0f0f0',
+    verticalAlign: 'middle' as const,
+  },
+  mono: {
+    fontFamily: 'monospace',
+    fontSize: '12px',
+    background: '#f5f5f5',
+    padding: '2px 5px',
+    borderRadius: '3px',
+    color: '#333',
+    whiteSpace: 'nowrap' as const,
+    display: 'inline-block' as const,
+  },
+  pill: {
+    display: 'inline-block' as const,
+    fontSize: '10px',
+    fontWeight: '600',
+    padding: '1px 6px',
+    borderRadius: '10px',
+    background: '#e8f0e0',
+    color: '#3a5a18',
+    marginLeft: '6px',
+    verticalAlign: 'middle' as const,
+  },
+  warning: {
+    display: 'inline-block' as const,
+    fontSize: '10px',
+    fontWeight: '600',
+    padding: '1px 6px',
+    borderRadius: '10px',
+    background: '#fff3cd',
+    color: '#856404',
+    marginLeft: '6px',
+    verticalAlign: 'middle' as const,
+  },
+};
+
+function rowBg(i: number): CSSProperties {
+  return { background: i % 2 === 0 ? '#fff' : '#fafafa' };
+}
+
+// ── Color swatch using CSS custom property directly ──────────────────────────
+// We use the cssProperty value from the JSON (e.g. --colors-surface-container)
+// to render a live swatch via inline style. This bypasses Panda's static
+// extraction requirement and works with any token at runtime.
+
+function Swatch({ cssVar, size = 32 }: { cssVar: string; size?: number }) {
+  return (
+    <div
+      style={{
+        display: 'inline-flex',
+        gap: '4px',
+        alignItems: 'center',
+      }}
+    >
+      {/* Light swatch */}
+      <div
+        title={`Light: var(${cssVar})`}
+        style={{
+          width: size,
+          height: size,
+          borderRadius: '4px',
+          border: '1px solid rgba(0,0,0,0.12)',
+          background: `var(${cssVar})`,
+          flexShrink: 0,
+        }}
+      />
+      {/* Dark swatch — forced via data-theme attribute */}
+      <div
+        data-theme="dark"
+        title={`Dark: var(${cssVar})`}
+        style={{
+          width: size,
+          height: size,
+          borderRadius: '4px',
+          border: '1px solid rgba(255,255,255,0.15)',
+          background: `var(${cssVar})`,
+          flexShrink: 0,
+        }}
+      />
+    </div>
+  );
+}
+
+function SpacingSwatch({
+  cssVar,
+  category,
+}: {
+  cssVar: string;
+  category: string;
+}) {
+  if (category !== 'spacing') {
+    // For radii — show a box with the corner radius applied
+    return (
+      <div
+        title={`var(${cssVar})`}
+        style={{
+          width: 32,
+          height: 32,
+          background: '#4C662B',
+          borderRadius: `var(${cssVar})`,
+          flexShrink: 0,
+          border: '1px solid rgba(0,0,0,0.1)',
+        }}
+      />
+    );
+  }
+  // For spacing — show a bar whose width is the spacing value
+  return (
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: '4px',
+        minWidth: '80px',
+      }}
+    >
+      <div
+        title={`var(${cssVar})`}
+        style={{
+          height: '20px',
+          width: `var(${cssVar})`,
+          minWidth: '2px',
+          background: '#4C662B',
+          borderRadius: '2px',
+          flexShrink: 0,
+        }}
+      />
+    </div>
+  );
+}
+
+function ShadowSwatch({ cssVar }: { cssVar: string }) {
+  return (
+    <div
+      title={`var(${cssVar})`}
+      style={{
+        width: 40,
+        height: 32,
+        borderRadius: '6px',
+        background: '#fff',
+        boxShadow: `var(${cssVar})`,
+        border: '1px solid rgba(0,0,0,0.06)',
+        flexShrink: 0,
+      }}
+    />
+  );
+}
+
+function TypeSwatch({
+  fontFamily,
+  fontWeight,
+  fontSize,
+}: {
+  fontFamily: string;
+  fontWeight: number;
+  fontSize: number;
+}) {
+  // Clamp display size so table rows don't get too tall
+  const displaySize = Math.min(fontSize, 22);
+  return (
+    <span
+      style={{
+        fontFamily,
+        fontWeight,
+        fontSize: `${displaySize}px`,
+        lineHeight: 1,
+        color: '#1a1a1a',
+        whiteSpace: 'nowrap',
+      }}
+    >
+      Aa
+    </span>
+  );
+}
+
+// ── Storybook meta ────────────────────────────────────────────────────────────
+
+const meta = {
+  title: 'Foundations/Token Reference',
+  parameters: { layout: 'padded' },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ── Story 1: Semantic Colors ─────────────────────────────────────────────────
+
+export const SemanticColors: Story = {
+  name: '1 · Semantic Colors',
+  render: () => {
+    const entries = tokenMap.semantic as SemanticEntry[];
+    const pandaOnly = (tokenMap.semanticPandaOnly ?? []) as PandaOnlyEntry[];
+
+    // Mismatches flagged in token-name-mapping.md
+    const mismatches = new Set([
+      'surfaceVariant',
+      'inverseSurface',
+      'inverseOnSurface',
+      'inversePrimary',
+    ]);
+
+    return (
+      <div style={T.page}>
+        <div style={T.section}>
+          <h2 style={T.h2}>Semantic Colors</h2>
+          <p style={T.meta}>
+            {entries.length} entries · source: Figma &quot;Semantic&quot;
+            collection · auto-generated from docs/token-name-mapping.json v
+            {tokenMap.version}
+          </p>
+
+          <table style={T.table}>
+            <thead>
+              <tr>
+                <th style={T.th}>Swatch (L / D)</th>
+                <th style={T.th}>Figma Variable Path</th>
+                <th style={T.th}>Panda CSS Token</th>
+                <th style={T.th}>CSS Custom Property</th>
+                <th style={T.th}>Code Usage</th>
+              </tr>
+            </thead>
+            <tbody>
+              {entries.map((e, i) => (
+                <tr key={e.figmaPath} style={rowBg(i)}>
+                  <td style={T.td}>
+                    <Swatch cssVar={e.cssProperty} />
+                  </td>
+                  <td style={T.td}>
+                    <span style={T.mono}>{e.figmaPath}</span>
+                  </td>
+                  <td style={T.td}>
+                    <span style={T.mono}>{e.pandaToken}</span>
+                    {mismatches.has(e.pandaToken) && (
+                      <span
+                        style={T.warning}
+                        title="Not dot-notation — see mismatch notes"
+                      >
+                        ⚠ flat
+                      </span>
+                    )}
+                  </td>
+                  <td style={T.td}>
+                    <span style={{ ...T.mono, color: '#666' }}>
+                      {e.cssProperty}
+                    </span>
+                  </td>
+                  <td style={T.td}>
+                    <span style={{ ...T.mono, background: '#eef4e8' }}>
+                      {e.exampleUsage}
+                    </span>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+
+          {pandaOnly.length > 0 && (
+            <>
+              <h3
+                style={{
+                  fontSize: '15px',
+                  fontWeight: '600',
+                  margin: '32px 0 12px',
+                  color: '#333',
+                }}
+              >
+                Panda-only tokens (no Figma variable)
+              </h3>
+              <table style={T.table}>
+                <thead>
+                  <tr>
+                    <th style={T.th}>Swatch (L / D)</th>
+                    <th style={T.th}>Panda CSS Token</th>
+                    <th style={T.th}>CSS Custom Property</th>
+                    <th style={T.th}>Code Usage</th>
+                    <th style={T.th}>Notes</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {pandaOnly.map((e, i) => (
+                    <tr key={e.pandaToken} style={rowBg(i)}>
+                      <td style={T.td}>
+                        <Swatch cssVar={e.cssProperty} />
+                      </td>
+                      <td style={T.td}>
+                        <span style={T.mono}>{e.pandaToken}</span>
+                      </td>
+                      <td style={T.td}>
+                        <span style={{ ...T.mono, color: '#666' }}>
+                          {e.cssProperty}
+                        </span>
+                      </td>
+                      <td style={T.td}>
+                        <span style={{ ...T.mono, background: '#eef4e8' }}>
+                          {e.exampleUsage}
+                        </span>
+                      </td>
+                      <td style={{ ...T.td, color: '#666', fontSize: '12px' }}>
+                        {e.notes ?? '—'}
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </>
+          )}
+
+          <div
+            style={{
+              marginTop: '20px',
+              padding: '12px 16px',
+              background: '#fff8e1',
+              borderRadius: '6px',
+              fontSize: '12px',
+              color: '#555',
+              lineHeight: 1.6,
+            }}
+          >
+            <strong>⚠ Mismatch tokens</strong> — five tokens do NOT follow
+            dot-notation despite slash-path Figma naming:{' '}
+            <code>surfaceVariant</code>, <code>inverseSurface</code>,{' '}
+            <code>inverseOnSurface</code>, <code>inversePrimary</code>,{' '}
+            <code>inverseSecondary</code>, <code>inverseTertiary</code>. Use the
+            Panda CSS token column exactly — never derive it from the Figma path
+            by replacing <code>/</code> with <code>.</code>.
+          </div>
+        </div>
+      </div>
+    );
+  },
+};
+
+// ── Story 2: Spacing & Shape ─────────────────────────────────────────────────
+
+export const SpacingAndShape: Story = {
+  name: '2 · Spacing & Shape',
+  render: () => {
+    const entries = tokenMap.spacingAndShape as SpacingShapeEntry[];
+
+    const categories = ['spacing', 'radii', 'borderWidths', 'durations'];
+
+    return (
+      <div style={T.page}>
+        {categories.map((cat) => {
+          const rows = entries.filter((e) => e.pandaCategory === cat);
+          if (rows.length === 0) return null;
+
+          const catLabel: Record<string, string> = {
+            spacing: 'Spacing',
+            radii: 'Border Radii (M3 base tokens)',
+            borderWidths: 'Border Widths',
+            durations: 'Motion Durations',
+          };
+
+          return (
+            <div key={cat} style={T.section}>
+              <h2 style={T.h2}>{catLabel[cat] ?? cat}</h2>
+              <p style={T.meta}>
+                {rows.length} entries · Figma &quot;Spacing &amp; Shape&quot;
+                collection · v{tokenMap.version}
+              </p>
+
+              <table style={T.table}>
+                <thead>
+                  <tr>
+                    {cat === 'spacing' || cat === 'radii' ? (
+                      <th style={T.th}>Visual</th>
+                    ) : null}
+                    <th style={T.th}>Figma Variable Path</th>
+                    <th style={T.th}>Panda CSS Token</th>
+                    <th style={T.th}>CSS Custom Property</th>
+                    <th style={T.th}>Code Usage</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {rows.map((e, i) => (
+                    <tr key={e.figmaPath} style={rowBg(i)}>
+                      {cat === 'spacing' || cat === 'radii' ? (
+                        <td style={T.td}>
+                          <SpacingSwatch
+                            cssVar={e.cssProperty}
+                            category={cat}
+                          />
+                        </td>
+                      ) : null}
+                      <td style={T.td}>
+                        <span style={T.mono}>{e.figmaPath}</span>
+                      </td>
+                      <td style={T.td}>
+                        <span style={T.mono}>{e.pandaToken}</span>
+                        {cat === 'radii' && (
+                          <span
+                            style={{
+                              ...T.warning,
+                              background: '#e8f0e0',
+                              color: '#3a5a18',
+                            }}
+                            title="Use l1/l2/l3/full in component code, not this M3 base token"
+                          >
+                            base
+                          </span>
+                        )}
+                      </td>
+                      <td style={T.td}>
+                        <span style={{ ...T.mono, color: '#666' }}>
+                          {e.cssProperty}
+                        </span>
+                      </td>
+                      <td style={T.td}>
+                        <span style={{ ...T.mono, background: '#eef4e8' }}>
+                          {e.exampleUsage}
+                        </span>
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+
+              {cat === 'radii' && (
+                <div
+                  style={{
+                    marginTop: '12px',
+                    padding: '12px 16px',
+                    background: '#e8f0e0',
+                    borderRadius: '6px',
+                    fontSize: '12px',
+                    color: '#3a5a18',
+                    lineHeight: 1.6,
+                  }}
+                >
+                  <strong>Use DDS canonical radii in component code</strong> —
+                  not these M3 base tokens. <code>l1</code> = 2px (checkboxes,
+                  breadcrumbs) · <code>l2</code> = 6px (buttons, inputs, badges)
+                  · <code>l3</code> = 8px (cards, dialogs, popovers) ·{' '}
+                  <code>full</code> = 9999px (avatars, pills, switches)
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    );
+  },
+};
+
+// ── Story 3: Elevation & Shadows ─────────────────────────────────────────────
+
+export const ElevationAndShadows: Story = {
+  name: '3 · Elevation & Shadows',
+  render: () => {
+    const baseLevels = tokenMap.effectStyles as EffectStyleEntry[];
+    const aliases = (tokenMap.shadowSemanticAliases ??
+      []) as ShadowAliasEntry[];
+
+    return (
+      <div style={T.page}>
+        <div style={T.section}>
+          <h2 style={T.h2}>Base Elevation Levels (M3)</h2>
+          <p style={T.meta}>
+            {baseLevels.length} levels · Figma effect styles · v
+            {tokenMap.version}
+          </p>
+
+          <table style={T.table}>
+            <thead>
+              <tr>
+                <th style={T.th}>Visual</th>
+                <th style={T.th}>Figma Effect Style</th>
+                <th style={T.th}>Panda Base Token</th>
+                <th style={T.th}>CSS Custom Property</th>
+                <th style={T.th}>Description</th>
+                <th style={T.th}>Code Usage</th>
+              </tr>
+            </thead>
+            <tbody>
+              {baseLevels.map((e, i) => (
+                <tr key={e.figmaEffectStyle} style={rowBg(i)}>
+                  <td style={T.td}>
+                    <ShadowSwatch cssVar={e.cssProperty} />
+                  </td>
+                  <td style={T.td}>
+                    <span style={T.mono}>{e.figmaEffectStyle}</span>
+                  </td>
+                  <td style={T.td}>
+                    <span style={T.mono}>{e.pandaToken}</span>
+                    <span
+                      style={T.warning}
+                      title="Use semantic alias (xs/sm/md/lg/xl) in component code"
+                    >
+                      base
+                    </span>
+                  </td>
+                  <td style={T.td}>
+                    <span style={{ ...T.mono, color: '#666' }}>
+                      {e.cssProperty}
+                    </span>
+                  </td>
+                  <td style={{ ...T.td, color: '#555', fontSize: '12px' }}>
+                    {e.description}
+                  </td>
+                  <td style={T.td}>
+                    <span
+                      style={{
+                        ...T.mono,
+                        background: '#fff3cd',
+                        color: '#856404',
+                      }}
+                    >
+                      {e.exampleUsage}
+                    </span>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+
+          <div
+            style={{
+              marginTop: '12px',
+              padding: '12px 16px',
+              background: '#fff3cd',
+              borderRadius: '6px',
+              fontSize: '12px',
+              color: '#856404',
+              lineHeight: 1.6,
+            }}
+          >
+            <strong>Do not use base level tokens in component code.</strong> Use
+            the semantic aliases below (xs/sm/md/lg/xl).
+          </div>
+        </div>
+
+        {aliases.length > 0 && (
+          <div style={T.section}>
+            <h2 style={T.h2}>Semantic Shadow Aliases</h2>
+            <p style={T.meta}>
+              {aliases.length} aliases · src/preset/shadows.ts · use these in
+              components and recipes
+            </p>
+
+            <table style={T.table}>
+              <thead>
+                <tr>
+                  <th style={T.th}>Visual</th>
+                  <th style={T.th}>Panda Token</th>
+                  <th style={T.th}>CSS Custom Property</th>
+                  <th style={T.th}>Resolves To</th>
+                  <th style={T.th}>Description</th>
+                  <th style={T.th}>Code Usage</th>
+                </tr>
+              </thead>
+              <tbody>
+                {aliases.map((e, i) => (
+                  <tr key={e.pandaToken} style={rowBg(i)}>
+                    <td style={T.td}>
+                      <ShadowSwatch cssVar={e.cssProperty} />
+                    </td>
+                    <td style={T.td}>
+                      <span style={{ ...T.mono, fontWeight: '600' }}>
+                        {e.pandaToken}
+                      </span>
+                    </td>
+                    <td style={T.td}>
+                      <span style={{ ...T.mono, color: '#666' }}>
+                        {e.cssProperty}
+                      </span>
+                    </td>
+                    <td style={T.td}>
+                      <span style={T.mono}>{e.resolvesTo}</span>
+                    </td>
+                    <td style={{ ...T.td, color: '#555', fontSize: '12px' }}>
+                      {e.description ?? '—'}
+                    </td>
+                    <td style={T.td}>
+                      <span style={{ ...T.mono, background: '#eef4e8' }}>
+                        {e.exampleUsage}
+                      </span>
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+      </div>
+    );
+  },
+};
+
+// ── Story 4: Typography ───────────────────────────────────────────────────────
+
+export const Typography: Story = {
+  name: '4 · Typography',
+  render: () => {
+    const entries = tokenMap.textStyles as TextStyleEntry[];
+
+    // Group by pandaTextStyle (scale step)
+    const groups = entries.reduce<Record<string, TextStyleEntry[]>>(
+      (acc, e) => {
+        if (!acc[e.pandaTextStyle]) acc[e.pandaTextStyle] = [];
+        acc[e.pandaTextStyle].push(e);
+        return acc;
+      },
+      {},
+    );
+
+    const categoryOrder = [
+      'displayLarge',
+      'displayMedium',
+      'displaySmall',
+      'headlineLarge',
+      'headlineMedium',
+      'headlineSmall',
+      'titleLarge',
+      'titleMedium',
+      'titleSmall',
+      'bodyLarge',
+      'bodyMedium',
+      'bodySmall',
+      'labelLarge',
+      'labelMedium',
+      'labelSmall',
+    ];
+
+    const categoryLabel: Record<string, string> = {
+      displayLarge: 'Display',
+      headlineLarge: 'Headline',
+      titleLarge: 'Title',
+      bodyLarge: 'Body',
+      labelLarge: 'Label',
+    };
+
+    let rowIndex = 0;
+
+    return (
+      <div style={T.page}>
+        <h2 style={T.h2}>Typography — All Weight Variants</h2>
+        <p style={T.meta}>
+          {entries.length} entries ({categoryOrder.length} scale steps × weight
+          variants) · auto-generated from docs/token-name-mapping.json v
+          {tokenMap.version}
+        </p>
+
+        <table style={T.table}>
+          <thead>
+            <tr>
+              <th style={T.th}>Preview</th>
+              <th style={T.th}>Figma Text Style</th>
+              <th style={T.th}>DDS Token Path</th>
+              <th style={T.th}>Panda textStyle</th>
+              <th style={T.th}>Font / Weight</th>
+              <th style={T.th}>Size / LH</th>
+              <th style={T.th}>Code Usage</th>
+            </tr>
+          </thead>
+          <tbody>
+            {categoryOrder.flatMap((step) => {
+              const rows = groups[step] ?? [];
+              return rows.map((e) => {
+                const i = rowIndex++;
+                const isDefault = e.isDefaultWeight;
+                return (
+                  <tr key={e.figmaTextStyle} style={rowBg(i)}>
+                    <td style={T.td}>
+                      <TypeSwatch
+                        fontFamily={e.fontFamily}
+                        fontWeight={e.fontWeight}
+                        fontSize={e.fontSize}
+                      />
+                    </td>
+                    <td style={T.td}>
+                      <span style={T.mono}>{e.figmaTextStyle}</span>
+                      {/* Section label at first row of each category */}
+                      {categoryLabel[step] && rows.indexOf(e) === 0 && (
+                        <span
+                          style={{
+                            display: 'block',
+                            fontSize: '10px',
+                            fontWeight: '700',
+                            color: '#4C662B',
+                            textTransform: 'uppercase',
+                            letterSpacing: '0.05em',
+                            marginTop: '2px',
+                          }}
+                        >
+                          ── {categoryLabel[step]}
+                        </span>
+                      )}
+                    </td>
+                    <td style={T.td}>
+                      <span style={{ ...T.mono, fontSize: '11px' }}>
+                        {e.ddsTokenPath}
+                      </span>
+                    </td>
+                    <td style={T.td}>
+                      <span style={T.mono}>{e.pandaTextStyle}</span>
+                      {isDefault && (
+                        <span
+                          style={T.pill}
+                          title="Default weight for this scale step"
+                        >
+                          default
+                        </span>
+                      )}
+                    </td>
+                    <td style={T.td}>
+                      <span style={{ ...T.mono, fontSize: '11px' }}>
+                        {e.fontFamily.split(',')[0].replace(/"/g, '')}
+                      </span>
+                      <span
+                        style={{
+                          display: 'block',
+                          fontFamily: 'monospace',
+                          fontSize: '11px',
+                          color: '#777',
+                        }}
+                      >
+                        {e.fontStyle} ({e.fontWeight})
+                      </span>
+                    </td>
+                    <td style={T.td}>
+                      <span
+                        style={{
+                          fontFamily: 'monospace',
+                          fontSize: '11px',
+                          color: '#444',
+                        }}
+                      >
+                        {e.fontSize}px / {e.lineHeightPx}px
+                        {e.letterSpacing !== 0 && (
+                          <span style={{ color: '#999' }}>
+                            {' '}
+                            ls:{e.letterSpacing}
+                          </span>
+                        )}
+                      </span>
+                    </td>
+                    <td style={T.td}>
+                      <span
+                        style={{
+                          ...T.mono,
+                          background: '#eef4e8',
+                          fontSize: '11px',
+                        }}
+                      >
+                        {e.exampleUsage}
+                      </span>
+                      {!isDefault && (
+                        <span
+                          style={{
+                            display: 'block',
+                            fontFamily: 'monospace',
+                            fontSize: '10px',
+                            color: '#888',
+                            marginTop: '2px',
+                          }}
+                        >
+                          + fontWeight=&quot;{e.fontStyle.toLowerCase()}&quot;
+                        </span>
+                      )}
+                    </td>
+                  </tr>
+                );
+              });
+            })}
+          </tbody>
+        </table>
+
+        <div
+          style={{
+            marginTop: '20px',
+            padding: '12px 16px',
+            background: '#f0f4ff',
+            borderRadius: '6px',
+            fontSize: '12px',
+            color: '#334',
+            lineHeight: 1.7,
+          }}
+        >
+          <strong>How to read this table:</strong> The <em>Panda textStyle</em>{' '}
+          sets geometry (size, line-height, letter-spacing, font-family). The
+          default weight variant is applied automatically. To use a non-default
+          weight, add <code>fontWeight</code> separately.
+          <br />
+          Example:{' '}
+          <code>
+            &lt;Text textStyle=&quot;headlineSmall&quot;
+            fontWeight=&quot;semibold&quot;&gt;
+          </code>
+          <br />
+          The <em>DDS Token Path</em> is what the Figma text style description
+          field encodes (
+          <code>dds:typography.scale.headlineSmall.weights.semiBold</code>) —
+          the most direct resolution path from MCP output.
+        </div>
+      </div>
+    );
+  },
+};
+
+// ── Story 5: Full Reference (all sections on one page) ───────────────────────
+
+export const FullReference: Story = {
+  name: '5 · Full Reference',
+  render: () => (
+    <div style={T.page}>
+      <div
+        style={{
+          padding: '16px 20px',
+          background: '#eef4e8',
+          borderRadius: '8px',
+          marginBottom: '40px',
+          fontSize: '13px',
+          color: '#3a5a18',
+          lineHeight: 1.7,
+        }}
+      >
+        <strong>Token Reference — v{tokenMap.version}</strong>
+        <br />
+        Generated:{' '}
+        {tokenMap.generatedAt
+          ? new Date(tokenMap.generatedAt).toLocaleString()
+          : 'unknown'}
+        <br />
+        Sources:{' '}
+        {(tokenMap.generatedFrom as string[]).map((f, i) => (
+          <span key={f}>
+            <code
+              style={{
+                fontSize: '11px',
+                background: '#d4e8c4',
+                padding: '1px 4px',
+                borderRadius: '3px',
+              }}
+            >
+              {f}
+            </code>
+            {i < tokenMap.generatedFrom.length - 1 ? ' · ' : ''}
+          </span>
+        ))}
+        <br />
+        <strong>To update:</strong> run <code>pnpm figma:export</code> then
+        rebuild Storybook.
+      </div>
+
+      {/* Render all four sections inline */}
+      {SemanticColors.render && SemanticColors.render({} as never, {} as never)}
+      {SpacingAndShape.render &&
+        SpacingAndShape.render({} as never, {} as never)}
+      {ElevationAndShadows.render &&
+        ElevationAndShadows.render({} as never, {} as never)}
+      {Typography.render && Typography.render({} as never, {} as never)}
+    </div>
+  ),
+};