@awarebydefault/display-case 1.0.0

package/src/ui/design-system/tokens/spacing.css

@@ -0,0 +1,48 @@
+/* ============================================================
+   Display Case — Spacing, radius, border & elevation tokens
+   Dense, rem-based spacing keeps the chrome compact so the
+   exhibit gets the room. Corners are modest (5px controls,
+   8px panels). Elevation is mostly border-led — the one place
+   we lift is floating overlays (menus, popovers).
+   ============================================================ */
+
+:root {
+  /* --- Spacing scale (rem) ----------------------------------- */
+  --dc-space-0: 0;
+  --dc-space-1: 0.125rem; /* 2px  — icon gaps                  */
+  --dc-space-2: 0.25rem; /* 4px  — control padding-y          */
+  --dc-space-3: 0.375rem; /* 6px  — nav-case padding           */
+  --dc-space-4: 0.5rem; /* 8px  — control padding-x, gaps    */
+  --dc-space-5: 0.625rem; /* 10px — header padding-y           */
+  --dc-space-6: 0.75rem; /* 12px — sidebar / panel padding    */
+  --dc-space-8: 1rem; /* 16px — header padding-x, stage gap*/
+  --dc-space-10: 1.25rem; /* 20px — main padding               */
+  --dc-space-12: 1.5rem; /* 24px                              */
+  --dc-space-16: 2rem; /* 32px — empty-state inset          */
+
+  /* --- Layout sizes ------------------------------------------ */
+  --dc-sidebar-w: 15rem; /* fixed nav column                  */
+  --dc-doc-panel-w: 22rem; /* docs aside                        */
+
+  /* --- Radius (modest, precise) ------------------------------ */
+  --dc-radius-sm: 5px; /* buttons, inputs, chips, nav rows     */
+  --dc-radius-md: 8px; /* panels, stage frame, doc panel       */
+  --dc-radius-lg: 12px; /* overlays / large callouts            */
+  --dc-radius-full: 999px;
+
+  /* --- Borders ----------------------------------------------- */
+  --dc-border-width: 1px;
+  --dc-border-line: var(--dc-border-width) solid var(--dc-border);
+
+  /* --- Elevation (rare — borders do most of the work) -------- */
+  --dc-shadow-none: none;
+  --dc-shadow-sm: 0 1px 2px rgba(33, 29, 24, 0.05);
+  --dc-shadow-overlay: 0 12px 32px -8px rgba(33, 29, 24, 0.22);
+
+  /* --- Motion ------------------------------------------------ */
+  --dc-ease: cubic-bezier(0.2, 0.8, 0.2, 1);
+  --dc-duration-fast: 0.12s; /* chevron rotate, hover fills */
+  --dc-duration-base: 0.2s;
+  --dc-transition-fast: var(--dc-duration-fast) var(--dc-ease);
+  --dc-transition-base: var(--dc-duration-base) var(--dc-ease);
+}

package/src/ui/design-system/tokens/typography.css

@@ -0,0 +1,49 @@
+/* ============================================================
+   Display Case — Typography tokens
+   Hanken Grotesk drives the chrome (warm, legible, quiet).
+   JetBrains Mono carries developer texture — labels, code,
+   values, the wordmark. The chrome lives at small sizes so the
+   showcased component owns the visual weight.
+   ============================================================ */
+
+:root {
+  /* --- Families ---------------------------------------------- */
+  --dc-font-sans:
+    "Hanken Grotesk", ui-sans-serif, system-ui, -apple-system, "Segoe UI",
+    Roboto, sans-serif;
+  --dc-font-mono:
+    "JetBrains Mono", ui-monospace, "SF Mono", "Cascadia Code", Menlo, Consolas,
+    monospace;
+
+  /* --- Size scale (px; dense chrome) ------------------------- */
+  --dc-text-2xs: 10px; /* compact chrome — undocked tweaks     */
+  --dc-text-xs: 11px; /* eyebrow labels, dim hints            */
+  --dc-text-sm: 12px; /* zoom %, secondary, captions          */
+  --dc-text-base: 14px; /* the chrome baseline                  */
+  --dc-text-md: 16px; /* icon glyphs, emphasis                */
+  --dc-text-lg: 20px;
+  --dc-text-xl: 28px; /* doc panel headings                   */
+  --dc-text-2xl: 40px; /* wordmark / specimen display          */
+
+  /* --- Weights ----------------------------------------------- */
+  --dc-weight-normal: 400;
+  --dc-weight-medium: 500; /* active nav, control labels       */
+  --dc-weight-semibold: 600; /* title, group labels              */
+  --dc-weight-bold: 700; /* wordmark, rare emphasis          */
+
+  /* --- Line height ------------------------------------------- */
+  --dc-leading-tight: 1.2;
+  --dc-leading-normal: 1.45;
+  --dc-leading-relaxed: 1.6; /* doc / markdown copy              */
+
+  /* --- Letter spacing ---------------------------------------- */
+  --dc-tracking-label: 0.08em; /* uppercase mono eyebrow labels    */
+  --dc-tracking-tight: -0.01em; /* display / wordmark               */
+  --dc-tracking-normal: 0;
+
+  /* --- Composite role tokens --------------------------------- */
+  /* Uppercase mono eyebrow — the signature label treatment. */
+  --dc-eyebrow:
+    var(--dc-weight-medium) var(--dc-text-xs) / var(--dc-leading-tight)
+    var(--dc-font-mono);
+}

package/src/ui/markdown.test.tsx

@@ -0,0 +1,54 @@
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { DocMarkdown } from './markdown'
+
+describe('DocMarkdown', () => {
+  test('renders the placard CommonMark + GFM subset', () => {
+    const html = renderToStaticMarkup(
+      <DocMarkdown
+        source={[
+          '# Title',
+          '',
+          'A **bold** and *italic* word with `code`.',
+          '',
+          '- one',
+          '- two',
+          '',
+          '[link](https://example.com)',
+          '',
+          '```ts',
+          'const x = 1',
+          '```',
+        ].join('\n')}
+      />,
+    )
+    expect(html).toContain('class="dc-doc-md"')
+    expect(html).toMatch(/<h1[^>]*>Title<\/h1>/)
+    expect(html).toContain('<strong>bold</strong>')
+    expect(html).toContain('<em>italic</em>')
+    expect(html).toContain('<code>code</code>')
+    expect(html).toContain('<li>one</li>')
+    expect(html).toMatch(/<a[^>]*href="https:\/\/example\.com"/)
+    expect(html).toContain('<pre>')
+    expect(html).toContain('const x = 1')
+  })
+
+  test('applies GFM extensions like tables and strikethrough', () => {
+    const html = renderToStaticMarkup(
+      <DocMarkdown source={'| A | B |\n| - | - |\n| 1 | 2 |\n\n~~gone~~'} />,
+    )
+    expect(html).toMatch(/<table/)
+    expect(html).toMatch(/<th[^>]*>A<\/th>/)
+    expect(html).toMatch(/<td[^>]*>1<\/td>/)
+    expect(html).toContain('<del>gone</del>')
+  })
+
+  test('does not inject raw HTML from the source into the chrome', () => {
+    const html = renderToStaticMarkup(
+      <DocMarkdown source={'<script>alert(1)</script>\n\n<b>x</b> text'} />,
+    )
+    // disableParsingRawHTML: tags are escaped to text, never live elements.
+    expect(html).not.toContain('<script>')
+    expect(html).not.toContain('<b>x</b>')
+  })
+})

package/src/ui/markdown.tsx

@@ -0,0 +1,19 @@
+import Markdown from 'markdown-to-jsx'
+
+/**
+ * Renders a component's authored `.placard.md` as full CommonMark + GFM via
+ * `markdown-to-jsx` — a ~zero-dependency renderer that emits React elements
+ * (no `dangerouslySetInnerHTML`). Raw HTML is intentionally NOT rendered
+ * (`disableParsingRawHTML`), so a doc file can't inject markup into the chrome.
+ * Syntax highlighting is a deliberate non-goal — fenced code renders as plain
+ * styled <pre><code>.
+ */
+const OPTIONS = { disableParsingRawHTML: true } as const
+
+export function DocMarkdown({ source }: { source: string }) {
+  return (
+    <div className="dc-doc-md">
+      <Markdown options={OPTIONS}>{source}</Markdown>
+    </div>
+  )
+}

package/src/ui/primer-mount.tsx

@@ -0,0 +1,76 @@
+import type { ReactNode } from 'react'
+import { StrictMode } from 'react'
+import { createRoot, hydrateRoot } from 'react-dom/client'
+import { PrimerRoot } from './primer'
+
+/**
+ * Entry point for the isolated `/render/primer` document. Mounts the compiled MDX
+ * primer into #root and sets the initial theme from the URL (`?theme=`); later
+ * theme changes arrive over `postMessage` (handled in {@link PrimerRoot}).
+ *
+ * Driven two ways, mirroring the `/render` frame:
+ *  - **Standalone** (direct navigation / snapshot): theme comes from the URL.
+ *  - **Embedded** (browse chrome iframe): the chrome pushes theme + scroll
+ *    messages and reads back the section list + active section.
+ */
+type MDXContent = (props: { components?: unknown }) => ReactNode
+
+/**
+ * Neutralize anchor clicks that would unload the primer frame. Authored prose
+ * can contain real `<a href>` links; in this isolated frame a click would do a
+ * full-document navigation and sever the chrome↔frame handshake. In-page hash
+ * links and `target=_blank` are harmless and left alone.
+ */
+function blockFrameNavigation(): void {
+  document.addEventListener(
+    'click',
+    (e) => {
+      if (
+        e.defaultPrevented ||
+        e.button !== 0 ||
+        e.metaKey ||
+        e.ctrlKey ||
+        e.shiftKey ||
+        e.altKey
+      ) {
+        return
+      }
+      const anchor = (e.target as HTMLElement | null)?.closest?.('a')
+      const href = anchor?.getAttribute('href')
+      if (!anchor || !href) return
+      if (anchor.target && anchor.target !== '_self') return
+      const url = new URL(href, window.location.href)
+      if (url.pathname === window.location.pathname && url.hash !== '') return
+      e.preventDefault()
+    },
+    true,
+  )
+}
+
+export function mountPrimer(Content: MDXContent): void {
+  blockFrameNavigation()
+  const params = new URLSearchParams(window.location.search)
+  const theme = params.get('theme') === 'dark' ? 'dark' : 'light'
+  document.documentElement.dataset.theme = theme
+  document.documentElement.dataset.themePref = theme
+
+  const rootEl = document.getElementById('root') as HTMLElement
+  const tree = (
+    <StrictMode>
+      <PrimerRoot content={Content} />
+    </StrictMode>
+  )
+  // Adopt the server-rendered primer when present (`data-ssr="1"`); otherwise
+  // mount fresh (a browser-only specimen forced a client-render fallback).
+  if (rootEl.dataset.ssr === '1') {
+    hydrateRoot(rootEl, tree, {
+      onRecoverableError: (err) =>
+        console.warn(
+          '[display-case] primer adopt mismatch; client re-rendered:',
+          err,
+        ),
+    })
+  } else {
+    createRoot(rootEl).render(tree)
+  }
+}

package/src/ui/primer.css

@@ -0,0 +1,175 @@
+.dc-primer {
+  height: 100vh;
+  overflow-y: auto;
+  background: var(--dc-bg);
+  color: var(--dc-fg);
+  font-family: var(--dc-font-sans);
+  font-size: var(--dc-text-base);
+  line-height: var(--dc-leading-relaxed);
+}
+.dc-primer-inner {
+  max-width: 56rem;
+  margin: 0 auto;
+  padding: var(--dc-space-16) var(--dc-space-12) 6rem;
+}
+
+/* Prose — quiet, legible long-form copy. */
+.dc-primer h1 {
+  font-size: var(--dc-text-2xl);
+  font-weight: var(--dc-weight-bold);
+  letter-spacing: var(--dc-tracking-tight);
+  line-height: var(--dc-leading-tight);
+  margin: 0 0 var(--dc-space-8);
+}
+.dc-primer h2 {
+  font-size: var(--dc-text-xl);
+  font-weight: var(--dc-weight-semibold);
+  letter-spacing: var(--dc-tracking-tight);
+  line-height: var(--dc-leading-tight);
+  margin: 3rem 0 var(--dc-space-8);
+  scroll-margin-top: var(--dc-space-8);
+}
+.dc-primer h3 {
+  font-size: var(--dc-text-lg);
+  font-weight: var(--dc-weight-semibold);
+  margin: var(--dc-space-12) 0 var(--dc-space-4);
+}
+.dc-primer p {
+  margin: 0 0 var(--dc-space-8);
+  color: var(--dc-fg);
+}
+.dc-primer a {
+  color: var(--dc-brand);
+  text-decoration: none;
+}
+.dc-primer a:hover {
+  text-decoration: underline;
+}
+.dc-primer strong {
+  font-weight: var(--dc-weight-semibold);
+}
+.dc-primer ul,
+.dc-primer ol {
+  margin: 0 0 var(--dc-space-8);
+  padding-left: var(--dc-space-12);
+}
+.dc-primer li {
+  margin: var(--dc-space-2) 0;
+}
+.dc-primer code {
+  font-family: var(--dc-font-mono);
+  font-size: 0.9em;
+  background: var(--dc-bg-subtle);
+  border: var(--dc-border-line);
+  border-radius: var(--dc-radius-sm);
+  padding: 0.05em 0.35em;
+}
+.dc-primer pre {
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-sm);
+  line-height: var(--dc-leading-normal);
+  background: var(--dc-bg-subtle);
+  border: var(--dc-border-line);
+  border-radius: var(--dc-radius-md);
+  padding: var(--dc-space-8);
+  overflow-x: auto;
+  margin: 0 0 var(--dc-space-8);
+}
+.dc-primer pre code {
+  background: none;
+  border: 0;
+  padding: 0;
+}
+
+/* Tables (GFM) — border-led and flat, like every other Vitrine surface: a
+   hairline frame, a quiet mono header on the subtle fill, and hairline row
+   rules. Authored as Markdown pipe-tables; this gives them the chrome's look
+   without per-document styling. */
+.dc-primer table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 0 0 var(--dc-space-8);
+  font-size: var(--dc-text-sm);
+  border: var(--dc-border-line);
+}
+.dc-primer thead th {
+  text-align: left;
+  padding: var(--dc-space-5) var(--dc-space-6);
+  background: var(--dc-bg-subtle);
+  color: var(--dc-fg-muted);
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-2xs);
+  font-weight: var(--dc-weight-medium);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  border-bottom: var(--dc-border-line);
+}
+.dc-primer tbody td {
+  padding: var(--dc-space-5) var(--dc-space-6);
+  vertical-align: top;
+  color: var(--dc-fg);
+}
+.dc-primer tbody tr + tr td {
+  border-top: var(--dc-border-line);
+}
+
+/* Display — the specimen card contract. The title and subtitle sit as plain
+   wall-text *above* the box; the box holds only the live specimen. */
+.dc-display {
+  margin: 0 0 var(--dc-space-12);
+  scroll-margin-top: var(--dc-space-8);
+}
+.dc-display-head {
+  margin-bottom: var(--dc-space-5);
+}
+.dc-display-title {
+  font-size: var(--dc-text-lg);
+  font-weight: var(--dc-weight-semibold);
+  letter-spacing: var(--dc-tracking-tight);
+  line-height: var(--dc-leading-tight);
+  color: var(--dc-fg);
+}
+.dc-display-sub {
+  margin-top: var(--dc-space-1);
+  font-size: var(--dc-text-sm);
+  color: var(--dc-fg-muted);
+}
+.dc-display-specimen {
+  border: var(--dc-border-line);
+  border-radius: var(--dc-radius-md);
+  background: var(--dc-bg);
+  padding: var(--dc-space-12);
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--dc-space-8);
+  align-items: center;
+  justify-content: center;
+}
+/* A forced-theme specimen re-scopes the design tokens for its subtree, so it
+   must repaint its own surface (the value the consumer app would give it). */
+.dc-display-specimen[data-theme] {
+  background: var(--dc-bg);
+  color: var(--dc-fg);
+}
+/* App surface — opt in (appSurface) to paint the consumer design system's own
+   canvas (--color-bg/--color-fg, the same tokens the /render frame paints)
+   instead of the Vitrine's --dc-bg, so a specimen sits on the exact background
+   the real app gives it. Degrades to --dc-bg when the consumer defines no
+   --color-bg. Listed after the [data-theme] rule (equal specificity → source
+   order wins), and the [data-theme] combination is spelled out so a forced-theme
+   app-surface specimen resolves the themed --color-bg of its own subtree. */
+.dc-display-specimen[data-app-surface],
+.dc-display-specimen[data-app-surface][data-theme] {
+  background: var(--color-bg, var(--dc-bg));
+  color: var(--color-fg, var(--dc-fg));
+}
+/* Flush — the specimen draws no frame or padding of its own. A single
+   self-bordered child (e.g. a DefinitionList) fills the box edge-to-edge and
+   supplies the one border, so there's no box-within-a-box; the rounded, clipped
+   background still backs the child's corners. */
+.dc-display-specimen[data-flush] {
+  display: block;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+}