@master/internal-site 0.2.6 → 0.2.8

package/src/docs-shell/data/legacy-design-routes.json

@@ -0,0 +1,176 @@
+{
+  "version": 1,
+  "locales": [
+    "en",
+    "tw",
+    "ja",
+    "ko",
+    "cn"
+  ],
+  "routes": [
+    {
+      "source": "/design-system/authoring",
+      "status": 410
+    },
+    {
+      "source": "/design-system",
+      "status": 301,
+      "destination": "https://design.master.co/principles",
+      "markdownDestination": "https://design.master.co/guidelines/principles.md"
+    },
+    {
+      "source": "/design-system/review/agent",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/asset",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/axes",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/badge",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/catalog",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/chart-group",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/code",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/comparison",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/container",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/controls",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/copy",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/data-table",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/demo",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/documentation-index",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/documents",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/feature-support",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/home-icons",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/item",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/label",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/legend",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/measure",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/media",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/metrics",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/motion",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/numeric-table",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/package-api",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/palette",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/parameters",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/scroll",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/source",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/steps",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/stylesheet",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/surface",
+      "status": 301,
+      "destination": "https://design.master.co/foundations/elevation",
+      "markdownDestination": "https://design.master.co/guidelines/foundations/elevation.md"
+    },
+    {
+      "source": "/design-system/review/swatch",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/tooling",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/utility-table",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/viewport",
+      "status": 410
+    },
+    {
+      "source": "/design-system/review/waterfall",
+      "status": 410
+    }
+  ]
+}

package/src/docs-shell/remark/markdown-components.js

@@ -57,7 +57,7 @@ function fenceProps(node) {
 // of every component also propagates every component's styles to every MDX page.
 const componentPaths = {
   a: 'markdown/Anchor.astro', h2: 'markdown/Heading2.astro', h3: 'markdown/Heading3.astro',
-  img: 'Image.svelte', Image: 'Image.svelte', table: 'markdown/Table.astro',
+  img: 'Image.svelte', Image: 'Image.svelte', table: 'markdown/Table.astro', th: 'markdown/TableHead.astro', td: 'markdown/TableCell.astro', tr: 'markdown/TableRow.astro',
   Code: 'Code.astro', InlineCode: 'InlineCode.astro', PMAction: 'PMAction.astro',
   Do: 'Do.astro', DoNot: 'DoNot.astro', Info: 'Info.astro', Warn: 'Warn.astro',
   InteractingIndicator: 'InteractingIndicator.astro'
@@ -68,7 +68,7 @@ function documentComponents(tree) {
   visit(tree, node => {
     if (node.type === 'link' || node.type === 'linkReference') used.add('a')
     if (node.type === 'image' || node.type === 'imageReference') used.add('img')
-    if (node.type === 'table') used.add('table')
+    if (node.type === 'table') for (const part of ['table', 'th', 'td', 'tr']) used.add(part)
     if (node.type === 'heading' && [2, 3].includes(node.depth)) used.add(`h${node.depth}`)
     if (['mdxJsxFlowElement', 'mdxJsxTextElement'].includes(node.type) && node.name in componentPaths) used.add(node.name)
   })

package/src/docs-shell/utils/snackbar.ts

@@ -7,7 +7,7 @@ export async function snackbar(text: string, { placement }: any = {}) {
   }
   // A floating `ui-sheet`; placement is inline so a message never needs a utility class the page has not generated.
   const element = document.createElement('div')
-  element.className = 'ui-sheet'
+  element.className = 'sheet'
   element.dataset.elevation = '3'
   element.setAttribute('role', 'status')
   Object.assign(element.style, {

package/src/examples/article-transitions/page.astro

@@ -1,5 +1,4 @@
 ---
-import '@master/internal-site/examples/scene.css'
 import '@master/internal-site/examples/article-transitions/transitions.css'
 import ArticleTransitionScene from '@master/internal-site/examples/components/ArticleTransitionScene.svelte'
 ---

package/src/examples/components/ArticleTransitionScene.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import '@master/internal-site/styles/system/button-feedback.css'
   import '@master/internal-site/styles/system/buttons.css'
-  import '@master/internal-site/styles/system/sheet.css'
+  import '@master/internal-site/styles/system/sheet.ts'
 
   import Image from '@master/internal-site/components/Image.svelte'
   import IconArrowLeft from '@tabler/icons-svelte-runes/icons/arrow-left'
@@ -54,14 +54,14 @@
     <DemoLabel>Field notes / Collection 01</DemoLabel>
     <span class="text-xs fg-text-muted" role="status">{selected ? 'Article detail' : '2 articles'} · {transition.mode}</span>
   </div>
-  <article data-article-detail hidden={!selected} class="overflow-hidden ui-sheet" data-elevation="1">
+  <article data-article-detail hidden={!selected} class="overflow-hidden sheet sheet-raised ui-sheet">
     <Image alt={detail.imageAlt} src={detail.image} loading="eager" sizes="(max-width: 600px) 100vw, 600px"
       style={`view-transition-name:article-${detail.id}-image`} class="block h-auto w-full (aspect-ratio:16/9) object-cover article-capture" />
     <div class="p-lg">
       <time datetime={detail.id === 'aurora' ? '2026-05-12' : '2026-05-09'} style={`view-transition-name:article-${detail.id}-date`} class="text-xs fg-text-muted article-capture">{detail.date}</time>
       <h1 bind:this={heading} tabindex="-1" style={`view-transition-name:article-${detail.id}-title`} class="mb(0) mt-sm text-2xl font-regular outline-solid:focus-visible outline(2):focus-visible outline-text-link:focus-visible outline-offset-4xs:focus-visible article-capture">{detail.title}</h1>
       <p class="mb(0) mt-md text-sm fg-text-muted">{detail.description} The image, title and date keep their names in both views. Each snapshot can move to its new bounds while surrounding content fades.</p>
-      <button type="button" class="mt-lg ui-button" onclick={() => { const id = detail.id; transition.run(() => { selectedId = undefined }, () => buttons.get(id) ?? null) }}>
+      <button type="button" class="mt-lg btn" onclick={() => { const id = detail.id; transition.run(() => { selectedId = undefined }, () => buttons.get(id) ?? null) }}>
         <IconArrowLeft aria-hidden="true" />Back to collection
       </button>
     </div>
@@ -77,7 +77,7 @@
             <h2 style={`view-transition-name:article-${article.id}-title`} class="mb(0) mt-xs text-lg font-regular article-capture">{article.title}</h2>
             <p class="mb-md mt-sm text-sm fg-text-muted">{article.description}</p>
             <button {@attach cardButton(article.id)}
-              type="button" class="self-start mt-auto ui-button" aria-label={`Read ${article.title}`}
+              type="button" class="self-start mt-auto btn" aria-label={`Read ${article.title}`}
               onclick={() => transition.run(() => { selectedId = article.id }, () => heading ?? null)}>
               Read article<IconArrowUpRight aria-hidden="true" />
             </button>

package/src/examples/components/ViewTransitionScene.svelte

@@ -18,7 +18,7 @@
 <main class="wrap-anywhere p-md bg-surface-base fg-text-body">
   <DemoControls label="Choose a view" variant="segmented">
     {#each views as view (view.id)}
-      <button type="button" aria-pressed={activeId === view.id}
+      <button class="segmented-item" type="button" aria-pressed={activeId === view.id}
         onclick={() => { if (view.id !== activeId) transition.run(() => { activeId = view.id }) }}>{view.title}</button>
     {/each}
   </DemoControls>

package/src/examples/view-transitions/page.astro

@@ -1,5 +1,4 @@
 ---
-import '@master/internal-site/examples/scene.css'
 import '@master/internal-site/examples/view-transitions/transitions.css'
 import ViewTransitionScene from '@master/internal-site/examples/components/ViewTransitionScene.svelte'
 ---

package/src/layouts/Document.astro

@@ -46,6 +46,7 @@ const applyTheme = () => {
   const value = preference === 'system' ? darkScheme.matches ? 'dark' : 'light' : preference;
   root.classList.remove('dark', 'light');
   root.classList.add(value);
+  root.dataset.theme = value;
   root.style.colorScheme = ['dark', 'light'].includes(value) ? value : '';
 };
 applyTheme();

package/src/scripts/legacy-design-routes.ts

@@ -0,0 +1,76 @@
+/** Shared, exact legacy URLs. Consumers enable emission only after destination deployment. */
+export interface LegacyDesignManifest {
+  version: number
+  locales: readonly string[]
+  routes: readonly { source: string; status: number; destination?: string; markdownDestination?: string; localizedMarkdownDestinations?: Readonly<Record<string, string>>; localizedDestinations?: Readonly<Record<string, string>> }[]
+}
+
+function entries(manifest: LegacyDesignManifest) {
+  if (manifest.version !== 1) throw new Error('Unsupported legacy design route manifest version')
+  const prefixes = ['', ...manifest.locales.map(locale => `/${locale}`)]
+  const result: { source: string; status: 301 | 410; destination?: string; markdownDestination?: string; localizedMarkdownDestinations?: Readonly<Record<string, string>>; localizedDestinations?: Readonly<Record<string, string>> }[] = []
+  const seen = new Set<string>()
+  for (const route of manifest.routes) {
+    if (!/^\/design-system(?:\/[a-z0-9-]+)*$/.test(route.source)) throw new Error(`Invalid exact legacy route: ${route.source}`)
+    if (route.status !== 301 && route.status !== 410) throw new Error(`Invalid legacy status: ${route.status}`)
+    if (route.status === 301 && (!route.destination || new URL(route.destination).protocol !== 'https:')) throw new Error(`Missing HTTPS destination: ${route.source}`)
+    if (route.markdownDestination && new URL(route.markdownDestination).protocol !== 'https:') throw new Error('Invalid Markdown destination')
+    for (const [locale, destination] of Object.entries({ ...route.localizedDestinations, ...route.localizedMarkdownDestinations })) {
+      if (!manifest.locales.includes(locale) || new URL(destination).protocol !== 'https:') throw new Error(`Invalid localized destination: ${locale}`)
+    }
+    for (const prefix of prefixes) for (const suffix of ['', '/', '.html', '.md']) {
+      const source = prefix + route.source + suffix
+      if (seen.has(source)) throw new Error(`Duplicate legacy route: ${source}`)
+      seen.add(source)
+      let destination: string | undefined
+      if (route.status === 301) {
+        // Preserve a language only when the manifest names an existing translated page.
+        const locale = prefix.slice(1)
+        const markdown = suffix === '.md' ? route.localizedMarkdownDestinations?.[locale] ?? route.markdownDestination : undefined
+        const url = new URL(markdown ?? route.localizedDestinations?.[locale] ?? route.destination!)
+        url.pathname = url.pathname.replace(/\/$/, '') + (suffix === '.md' && !markdown ? '.md' : '')
+        destination = url.href
+      }
+      result.push({ source, status: route.status, ...(destination ? { destination } : {}) })
+    }
+  }
+  return result
+}
+
+/** Cloudflare Pages redirects support moved URLs; 410 responses belong to the worker. */
+export function legacyDesignRedirects(manifest: LegacyDesignManifest): string[] {
+  return entries(manifest).filter(route => route.status === 301).map(route => `${route.source} ${route.destination} 301`)
+}
+
+/** Requests within these compact patterns still use exact route matching in the worker. */
+export function legacyDesignWorkerRoutes(manifest: LegacyDesignManifest) {
+  entries(manifest)
+  return {
+    version: 1,
+    include: ['', ...manifest.locales.map(locale => `/${locale}`)].flatMap(prefix => ['', '/', '.html', '.md', '/*'].map(suffix => `${prefix}/design-system${suffix}`)),
+    exclude: [],
+  }
+}
+
+/** Pages Functions bypass _redirects, so the worker handles both moved and retired URLs. */
+export function legacyDesignWorker(manifest: LegacyDesignManifest): string {
+  const routes = Object.fromEntries(entries(manifest).map(({ source, ...route }) => [source, route]))
+  return `const routes = ${JSON.stringify(routes)};
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    const route = Object.hasOwn(routes, url.pathname) ? routes[url.pathname] : undefined;
+    if (!route) return env.ASSETS.fetch(request);
+    if (route.status === 301) {
+      const destination = new URL(route.destination);
+      destination.search = url.search;
+      return Response.redirect(destination.href, 301);
+    }
+    return new Response(request.method === 'HEAD' ? null : 'This review page has been retired.\\n', {
+      status: 410,
+      headers: { 'Content-Type': 'text/plain; charset=utf-8', 'X-Robots-Tag': 'noindex', 'Cache-Control': 'public, max-age=3600' }
+    });
+  }
+};
+`
+}

package/src/scripts/style-delivery.mjs

@@ -19,7 +19,27 @@ const hash = text => createHash('sha256').update(text).digest('hex')
 const sizes = text => ({ bytes: Buffer.byteLength(text), gzip: gzipSync(text).length, brotli: brotliCompressSync(text).length })
 const attributes = text => Object.fromEntries([...text.matchAll(/([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)].map(m => [m[1], m[2] ?? m[3]]))
 export const importsOf = css => [...css.replace(/\/\*[\s\S]*?\*\//g, '').matchAll(/@import\s+(?:url\(\s*)?["']([^"']+)["']/g)].map(m => m[1])
-const families = ['sidebar', 'toc', 'pager', 'tree', 'tray', 'switch', 'range', 'chart', 'code', 'table']
+// Keep the report vocabulary stable while ownership moves from site controls to UI.
+const families = {
+  sidebar: ['ui-sidebar'], toc: ['ui-toc'], pager: ['ui-pager', 'pager'],
+  tree: ['ui-tree', 'tree'], tray: ['ui-tray', 'tray'], switch: ['ui-switch', 'switch'],
+  range: ['ui-range', 'slider'], chart: ['ui-chart'], code: ['ui-code', 'code', 'window'],
+  table: ['ui-table', 'table'], button: ['ui-button', 'btn'], input: ['ui-input', 'input'],
+  select: ['ui-select', 'select'], window: ['window'],
+}
+
+function deliveredFamilies(css) {
+  // Ignore comments, declaration strings and quoted attribute values. Inspect rule
+  // preludes so nested/compound selectors count, without matching class prefixes.
+  const unquoted = css.replace(/\/\*[\s\S]*?\*\/|"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'/g, '')
+    // Shared navigation names optional transition participants on every route;
+    // naming a sidebar or contents rail does not deliver its component styles.
+    .replace(/[^{};]+\{(?:\s*view-transition-(?:name|class)\s*:[^;{}]+;?\s*)+\}/g, '')
+  const selectors = [...unquoted.matchAll(/([^{};]+)\{/g)].map(match => match[1].trim()).filter(prelude => !prelude.startsWith('@')).join('\n')
+  return Object.fromEntries(Object.entries(families).map(([name, classes]) => [name,
+    new RegExp(`(?<!\\\\)\\.(?:${classes.join('|')})(?![\\w\\\\-]|[^\\x00-\\x7f])`).test(selectors)
+  ]))
+}
 
 export async function auditStyles(directory) {
   const root = resolve(directory), assets = {}, routes = {}
@@ -59,7 +79,7 @@ export async function auditStyles(directory) {
       ...Object.fromEntries(['bytes', 'gzip', 'brotli'].map(k => [k, totals.reduce((n, x) => n + x[k], 0)])),
       inlineSHA256: hash(inline.join('\n')),
       inlineBytes: inline.reduce((n, s) => n + Buffer.byteLength(s), 0),
-      families: Object.fromEntries(families.map(name => [name, new RegExp(`(?:^|[;{}])\\s*\\.ui-${name}\\s*\\{`).test(delivered)])),
+      families: deliveredFamilies(delivered),
       foundationCount: [...delivered.matchAll(/body,\s*:host\s*\{\s*font-family:\s*var\(--font-family-sans\)/g)].length,
       uncompiled: /(?:^|[;{}])\s*@(apply|compose|reference|prune|light|dark|variant|theme|mixin|utility|master|source|safelist|blocklist)\b/.test(delivered),
       layerOrder: [...new Set([...delivered.matchAll(/@layer\s+([\w-]+(?:\s*,\s*[\w-]+)*)\s*[;{]/g)].flatMap(m => m[1].split(/\s*,\s*/)))],

package/src/sections/document.astro

@@ -5,4 +5,4 @@ import SearchDialog from '@master/internal-site/components/SearchDialog.svelte'
 ---
 
 <slot />
-<SearchDialog client:idle={{ timeout: 500 }} />
+<SearchDialog client:load />

package/src/styles/docs-shell/documentation-search.css

@@ -1,3 +1,4 @@
+@import '../system/dialog.css';
 /*
  * The documentation search (`ui-dialog` with `ui-dialog-search`, `ui-results` and `ui-dialog-foot`): a floating sheet
  * near the top of the viewport whose results scroll between the field and the key hints; a full screen on phones.
@@ -12,13 +13,13 @@
   .ui-dialog-search input::placeholder { color: var(--ui-text-muted); }
   .ui-dialog-search input::-webkit-search-cancel-button { display: none; }
   .ui-dialog-close > span:last-child { display: none; }
-  .ui-dialog-close > .ui-kbd { box-shadow: none; background: none; }
+  .ui-dialog-close > .kbd { box-shadow: none; background: none; }
   .ui-dialog[data-variant="search"] > .ui-dialog-body { flex: 1; min-height: 0; overflow-y: auto; overscroll-behavior: contain; scrollbar-width: thin; }
   .ui-dialog-status { margin: 0; padding: var(--ui-space-sm) var(--ui-space-md) 0; color: var(--ui-text-muted); @apply --ui-label-type; }
   .ui-dialog-note { display: flex; flex-wrap: wrap; align-items: center; gap: var(--ui-space-xs); padding: var(--ui-space-sm) var(--ui-space-md) var(--ui-space-lg); }
   .ui-dialog-note > p { width: 100%; margin: 0; color: var(--ui-text-body); font-size: .8125rem; line-height: 1.6; }
-  .ui-dialog-note > .ui-button code { font: var(--ui-weight-regular) .75rem/1 var(--font-family-mono); }
-  .ui-dialog-note > .ui-button svg { width: 14px; height: 14px; color: var(--ui-text-muted); }
+  .ui-dialog-note > .btn code { font: var(--ui-weight-regular) .75rem/1 var(--font-family-mono); }
+  .ui-dialog-note > .btn svg { width: 14px; height: 14px; color: var(--ui-text-muted); }
   .ui-dialog-note[data-align="center"] { flex-direction: column; padding-block: var(--ui-space-xl); color: var(--ui-text-muted); text-align: center; }
   .ui-dialog-note[data-align="center"] > b { color: var(--ui-text-strong); font-size: var(--ui-text-small); font-weight: var(--ui-weight-strong); }
   .ui-results:empty { display: none; }
@@ -30,10 +31,10 @@
   .ui-dialog-foot { flex: none; }
   .ui-dialog-foot > span:last-child { margin-left: auto; }
   .ui-search-shortcut { white-space: nowrap; }
-  .ui-dialog-foot .ui-kbd svg { width: 12px; height: 12px; }
+  .ui-dialog-foot .kbd svg { width: 12px; height: 12px; }
   @media (width < 48rem) {
     .ui-dialog[data-variant="search"] { width: 100%; max-width: 100%; height: 100dvh; max-height: 100dvh; margin: 0; border-radius: 0; }
-    .ui-dialog-close > .ui-kbd, .ui-dialog-foot { display: none; }
+    .ui-dialog-close > .kbd, .ui-dialog-foot { display: none; }
     .ui-dialog-close > span:last-child { display: inline; }
   }
   @media (forced-colors: active) {

package/src/styles/docs-shell/materials.css

@@ -1,25 +1,13 @@
-/*
- * Site utility tokens. The design system lives in styles/system (--ui-* roles, ui-* components);
- * these @theme names only expose that ladder to Master CSS utilities used in content and on the homepage
- * (bg-surface-canvas, b-line-contour, shadow-raised …). Values always resolve to the system roles.
- */
+/* Site vocabulary adapts the public UI theme without defining another material palette. */
 @theme {
-  --color-surface-canvas: var(--ui-surface-canvas);
-  --color-surface-shell: var(--ui-surface-tray);
-  --color-surface-ink: var(--ui-surface-ink);
-  --color-text-subtle: var(--ui-text-muted);
-  --color-line-contour: var(--ui-line-contour);
-  /* Media uses a quiet 10% black/white perimeter in the active theme. */
+  --color-surface-canvas: var(--color-surface-base);
+  --color-surface-shell: var(--color-surface-tray);
+  --color-surface-ink: var(--color-surface-inverse);
+  --color-text-subtle: var(--color-text-muted);
   --opacity-media-ring: 0.1;
-  --color-line-media: light-dark(color(srgb 0 0 0 / var(--opacity-media-ring)), color(srgb 1 1 1 / var(--opacity-media-ring)));
-}
-
-@theme {
-  --shadow-edge: inset 0 1px 0 var(--ui-highlight);
-  --shadow-contact: 0 1px 1px -.5px var(--ui-shade-1), 0 2px 2px -1px var(--ui-shade-2), 0 4px 4px -2px var(--ui-shade-3);
-  --shadow-raised: var(--ui-elevation-rise-1);
-  --shadow-floating-contact: 0 1px 1px -.5px var(--ui-shade-1), 0 3px 3px -1.5px var(--ui-shade-2), 0 6px 6px -3px var(--ui-shade-3), 0 12px 12px -6px var(--ui-shade-4), 0 24px 24px -12px var(--ui-shade-4), 0 48px 48px -24px var(--ui-shade-5);
-  --shadow-floating: var(--ui-elevation-rise-3);
-  --shadow-pressed-contact: inset 0 1px 2px light-dark(oklch(18% 0 none / .07), oklch(0% 0 none / .5));
-  --shadow-pressed: var(--ui-elevation-sink);
+  --color-line-media: var(--color-line-image-strong);
+  --shadow-edge: inset 0 1px 0 var(--color-highlight);
+  --shadow-contact: var(--shadow-raised);
+  --shadow-floating-contact: var(--shadow-floating);
+  --shadow-pressed-contact: var(--shadow-pressed);
 }

package/src/styles/docs-shell/menu.css

@@ -6,10 +6,10 @@
   .ui-menu-glyph[data-open="true"] > path { transform: translateY(4px) rotate(45deg) scaleX(1.06066); }
   .ui-menu-glyph[data-open="true"] > path + path { transform: translateY(-4px) rotate(-45deg) scaleX(1.06066); }
 
-  .ui-dialog.ui-mobile-menu { position: fixed; inset: 0; width: 100%; max-width: 100%; height: 100dvh; max-height: 100dvh; margin: 0; padding: 0; overflow-y: auto; overscroll-behavior: contain; border-radius: 0; background: var(--ui-surface-canvas); box-shadow: none; opacity: 0; transition: opacity 180ms ease-out; }
-  .ui-dialog.ui-mobile-menu[open] { display: flex; flex-direction: column; }
-  .ui-dialog.ui-mobile-menu[data-open="true"] { opacity: 1; transition-duration: 320ms; }
-  .ui-dialog.ui-mobile-menu::backdrop { background: transparent; -webkit-backdrop-filter: none; backdrop-filter: none; }
+  .ui-mobile-menu { position: fixed; inset: 0; width: 100%; max-width: 100%; height: 100dvh; max-height: 100dvh; margin: 0; padding: 0; overflow-y: auto; overscroll-behavior: contain; border: 0; border-radius: 0; color: var(--ui-text-body); background: var(--ui-surface-canvas); box-shadow: none; opacity: 0; transition: opacity 180ms ease-out; }
+  .ui-mobile-menu[open] { display: flex; flex-direction: column; }
+  .ui-mobile-menu[data-open="true"] { opacity: 1; transition-duration: 320ms; }
+  .ui-mobile-menu::backdrop { background: transparent; -webkit-backdrop-filter: none; backdrop-filter: none; }
   .ui-mobile-menu-bar { position: sticky; top: 0; z-index: 1; flex: none; display: grid; grid-template-columns: var(--ui-header-target) minmax(0, 1fr) var(--ui-header-target); align-items: center; height: calc(3.75rem + env(safe-area-inset-top)); padding: env(safe-area-inset-top) max(var(--ui-space-xs), env(safe-area-inset-right)) 0 max(var(--ui-space-xs), env(safe-area-inset-left)); background: var(--ui-surface-canvas); }
   .ui-mobile-menu-bar > .ui-header-brand { justify-self: center; margin: 0; }
   .ui-mobile-menu-body { flex: 1; display: flex; flex-direction: column; gap: 4rem; width: 100%; max-width: 48rem; margin-inline: auto; padding: clamp(3rem, 10dvh, 6rem) max(clamp(1.5rem, 6vw, 3rem), env(safe-area-inset-right)) max(1.5rem, env(safe-area-inset-bottom)) max(clamp(1.5rem, 6vw, 3rem), env(safe-area-inset-left)); transform: translateY(-8px); transition: transform 180ms ease-out; }
@@ -21,18 +21,18 @@
   .ui-mobile-menu[data-open="true"] .ui-mobile-menu-link { opacity: 1; transform: translateY(0); transition: opacity 320ms ease-out, transform 320ms cubic-bezier(.22, 1, .36, 1), color var(--ui-duration-quick); transition-delay: calc(var(--menu-order) * 40ms), calc(var(--menu-order) * 40ms), 0s; }
   .ui-mobile-menu-link[aria-current] > span { text-decoration: underline; text-decoration-thickness: 1px; text-underline-offset: .2em; text-decoration-color: var(--ui-line-mark); }
   .ui-mobile-menu-link:focus-visible, .ui-mobile-menu-community > a:focus-visible { @apply --ui-focus-ring; outline-offset: 5px; border-radius: var(--ui-radius-sm); }
-  .ui-mobile-menu-footer { display: grid; gap: 1rem; margin-top: auto; }
+  .ui-mobile-menu-footer { display: grid; grid-template-columns: minmax(0, 1fr); gap: 1rem; margin-top: auto; }
   .ui-mobile-menu-community { display: flex; flex-wrap: wrap; gap: .5rem; margin-left: -.75rem; }
   .ui-mobile-menu-community > a { position: relative; display: inline-flex; align-items: center; justify-content: center; min-width: 2.75rem; min-height: 2.75rem; padding: .5rem .75rem; color: var(--ui-text-muted); text-decoration: none; transition: color var(--ui-duration-quick); }
   .ui-mobile-menu-community > a > .ui-menu-external { position: absolute; top: calc(50% - .875rem); right: calc(50% - 1rem); width: .625rem; height: .625rem; pointer-events: none; }
   .ui-mobile-menu-preferences { display: flex; flex-wrap: wrap; align-items: center; gap: .25rem .75rem; padding-top: 1rem; border-top: 1px solid var(--ui-line-hair); }
-  .ui-mobile-menu-preferences > .ui-select { width: auto; max-width: 100%; min-height: 2.75rem; padding-left: 0; padding-right: 1.5rem; background-color: transparent; background-position: right .125rem center; border-radius: var(--ui-radius-sm); box-shadow: none; color: var(--ui-text-muted); font-size: .8125rem; }
-  .ui-mobile-menu-preferences > .ui-select:focus-visible { @apply --ui-focus-ring; outline-offset: 3px; }
+  .ui-mobile-menu-preferences > .select { width: auto; max-width: 100%; min-height: 2.75rem; padding-left: 0; padding-right: 1.5rem; background-color: transparent; background-position: right .125rem center; border-radius: var(--ui-radius-sm); box-shadow: none; color: var(--ui-text-muted); font-size: .8125rem; }
+  .ui-mobile-menu-preferences > .select:focus-visible { @apply --ui-focus-ring; outline-offset: 3px; }
   @media (hover: hover) {
     .ui-mobile-menu-link:hover, .ui-mobile-menu-community > a:hover { color: var(--ui-text-body); }
   }
   @media (prefers-reduced-motion: reduce) {
-    .ui-dialog.ui-mobile-menu[data-open], .ui-mobile-menu-body, .ui-mobile-menu-link, .ui-menu-glyph[data-open] > path,
+    .ui-mobile-menu[data-open], .ui-mobile-menu-body, .ui-mobile-menu-link, .ui-menu-glyph[data-open] > path,
     .ui-mobile-menu[data-open="true"] .ui-mobile-menu-body, .ui-mobile-menu[data-open="true"] .ui-mobile-menu-link { transition: none; }
     .ui-mobile-menu-body, .ui-mobile-menu-link { transform: none; }
   }

package/src/styles/docs-shell/segments.css

@@ -1,11 +1,11 @@
 @layer components {
   /* Related views switch with the system's segmented control; the panels keep their own frames. */
   .segment-views, .segment-panel { min-width: 0; }
-  .segment-views > .ui-segmented { margin-bottom: var(--ui-space-sm); }
+  .segment-views > .segmented { margin-bottom: var(--ui-space-sm); }
   .segment-panel-label { display: none; }
   .segment-panel:focus-visible { @apply --ui-focus-ring; outline-offset: 3px; border-radius: var(--ui-radius-sm); }
   @media (scripting: none), print {
-    .segment-views > .ui-segmented { display: none; }
+    .segment-views > .segmented { display: none; }
     .segment-panel[hidden] { display: block !important; }
     .segment-panel + .segment-panel { margin-top: var(--ui-space-xl); }
     .segment-panel-label { display: block; margin-bottom: var(--ui-space-md); color: var(--ui-text-strong); font-size: var(--ui-text-small); font-weight: var(--ui-weight-medium); }

package/src/styles/docs-shell/theme.css

@@ -12,8 +12,8 @@
   --font-mono: "IBM Plex Mono";
   --font-feature-sans: "ss02", "ss03", "ss04", "ss06", "ss07", "ss08";
   --font-feature-mono: "cv01", "cv02", "cv29";
-  --radius-card: 0.75rem;
-  --radius-panel: 1rem;
+  --radius-card: var(--radius-control-lg);
+  --radius-panel: var(--radius-surface);
 }
 
 @keyframes slide-to-right {
@@ -32,11 +32,6 @@
   --tiny-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='8' height='8' viewBox='0 0 8 8'%3E%3Cg fill='black' fill-opacity='0.1'%3E%3Cpath fill-rule='evenodd' d='M0 0h4v4H0V0zm4 4h4v4H4V4z'/%3E%3C/g%3E%3C/svg%3E");
   --color-primary: light-dark(var(--color-yellow-40), var(--color-yellow-50));
   --color-accent: light-dark(var(--color-zinc-90), var(--color-zinc-5));
-  --color-focus: light-dark(var(--color-zinc-90), var(--color-zinc-5));
-  --color-text-success: light-dark(var(--color-green-70), var(--color-green-40));
-  --color-text-danger: light-dark(var(--color-red-60), var(--color-red-30));
-  --color-info: light-dark(var(--color-cyan-40), var(--color-cyan-50));
-  --color-text-info: light-dark(var(--color-cyan-70), var(--color-cyan-40));
 }
 
 @layer defaults {
@@ -45,11 +40,6 @@
     --tiny-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='8' height='8' viewBox='0 0 8 8'%3E%3Cg fill='black' fill-opacity='0.1'%3E%3Cpath fill-rule='evenodd' d='M0 0h4v4H0V0zm4 4h4v4H4V4z'/%3E%3C/g%3E%3C/svg%3E");
     --color-primary: var(--color-yellow-40);
     --color-accent: var(--color-zinc-90);
-    --color-focus: var(--color-zinc-90);
-    --color-text-success: var(--color-green-70);
-    --color-text-danger: var(--color-red-60);
-    --color-info: var(--color-cyan-40);
-    --color-text-info: var(--color-cyan-70);
   }
 }
 
@@ -59,10 +49,5 @@
     --tiny-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='8' height='8' viewBox='0 0 8 8'%3E%3Cg fill='white' fill-opacity='0.1'%3E%3Cpath fill-rule='evenodd' d='M0 0h4v4H0V0zm4 4h4v4H4V4z'/%3E%3C/g%3E%3C/svg%3E");
     --color-primary: var(--color-yellow-50);
     --color-accent: var(--color-zinc-5);
-    --color-focus: var(--color-zinc-5);
-    --color-text-success: var(--color-green-40);
-    --color-text-danger: var(--color-red-30);
-    --color-info: var(--color-cyan-50);
-    --color-text-info: var(--color-cyan-40);
   }
 }

package/src/styles/foundation.css

@@ -1,3 +1,4 @@
+@import '@master/ui/theme.css';
 @import './docs-shell/theme.css';
 @import './system/mixins.css';
 @import './system/tokens.css';

package/src/styles/site-contract.md

@@ -0,0 +1,31 @@
+# Master site composition
+
+Master UI owns reusable components, their theme, materials, states and contracts. Master Design owns design principles and usage guidance at https://design.master.co. This package owns the website shell, reading layout, preview orchestration and content rendering.
+
+Import the UI theme through foundation and component styles through their narrow owning entry. Do not import the complete UI library into every page. The `--ui-*` variables retained by the site are composition aliases to UI tokens or site-only reading, teaching and brand values, not an independent theme. Generic controls use the UI contract classes directly.
+
+Keep header, sidebar, reading measure, contents rail, breakpoints and homepage composition stable. UI controls retain their public internal geometry. Site adapters retain link navigation semantics, overlay native preferences, table scrolling, preview isolation and code-copy orchestration. Never attach a second behavior controller to a node already owned by a site island.
+
+Import `styles/system/table.ts`, `tray.ts` and `sheet.ts` from site components. These entries share canonical UI styles as module dependencies and add only their site composition CSS. The matching `.css` entrypoints remain for compatibility; nesting them inside new CSS collections can compile the same UI surface more than once. Bare examples import the styles of their actual components rather than the full controls or surfaces collections.
+
+Foundation, interface, documents and component styles retain separate route boundaries. Every class needed after hydration must be visible to prerender. Build tools stay server-only. Request context and initial HTML must remain isolated and deterministic.
+
+## Shell
+
+The shell follows the original documentation layout, refined:
+
+- **Header** 60px, 32px gutters. Community and language actions share square 36px desktop / 44px compact targets, centred 18px Tabler icons at 1.5 stroke, and an 8px gap. Desktop search retains its 30px hairline pill, 16px glass and visible ⌘K; compact search uses the same 44px target and 18px icon as its neighbours; the homepage's wide header leaves it out. Section links are plain words (body ink, current one in strong ink at medium weight), no pill. The version is plain text with a chevron. Version chevrons retain their original muted 12px size; external-link indicators remain small raised 10px marks. Text links/version controls share the target height with content-sized widths. Controls only change ink on hover. The separator has 4px margins plus the 8px control gap on each side.
+- **Sidebar** 276px with a 32px start gutter aligned with the logo; it starts with its first group, whose caption stands level with the page kicker and the contents caption (y = header + 56px). Group captions are muted eyebrows; entries are 14px muted on one hairline guide, 32px rows; the current entry inks a short 2px bar on the guide and takes medium weight.
+- **Contents rail** (252px) is a ruler: h2 entries have 24px ticks and h3 entries have 12px ticks with their right ends aligned before the text; titles share a second edge without indentation. The current entry takes strong ink and medium weight without changing its tick length. 13px entries in 34px rows (44px touch targets); "On this page" is a muted eyebrow on the title edge, level with the page kicker. Long lists fold inactive subsections without adding icons; following the section opens them.
+- **Page head** a muted eyebrow kicker, a regular-weight title (fluid 30–38px), an 18px lead (a second lead line, such as a layout's subtitle, at reading size), then 48px of space — no rule — before the reading starts.
+- **Page tabs** between sibling documents (`Tabs`, `ui-segmented[data-variant="underline"]`) are words on one hairline, the current one underlined in ink — the original's tabs, not a raised segmented thumb.
+- **Compact menu** below 64rem is a full-height modal: Tabler’s two-line menu at 18px / 1.5 stroke becomes a small close glyph in a 44px target, brand stays centred, search sits opposite. Primary links use fluid 36–56px medium-weight type and generous space; chapters belong to the section indexes. Community icons and native preferences sit beneath the navigation, at the bottom when space permits. External community icons carry the same raised 10px marker as header actions, anchored 11px right / 9px above the icon centre. The surface enters over 320ms, links follow at 40ms intervals, and closing takes 180ms; reduced motion removes transitions.
+- **Search trigger** (`ui-search-trigger`, on the 404) is a quiet row over one hairline with a flat `⌘K` hint; results in the dialog take a chip wash, never a raised frame. The desktop dialog footer teaches “Search anytime” with ⌘ + K keycaps on Apple devices or Ctrl + K elsewhere.
+- **Pager** is one hairline over two links, 80px below the article: an eyebrow (Previous / Next) over a 16px title with a muted arrow; ink on hover, no boxes.
+- **Steps** hang on one hairline rail from flat 28px numbered rings (canvas face, strong contour, sans tabular figures) and take the wide column. A step title is 16px medium; its text is 14/1.8. A row step puts its text on two fifths and its code on three once the list is 46rem wide (narrower, the code stacks under its text). A preview after the steps hangs like any surface and the rail runs into it.
+- **Footer** in the documentation takes the article's wide column from the text's edge; elsewhere it is 72rem. Groups keep 11rem columns from the start (`auto-fill`), so a wide footer leaves the rest to the canvas. Link groups (Docs, Resources, Community, Legal — the license and the trademark policy) under strong-ink eyebrows, 14px links on a 32px pitch. One quiet base row under a hairline, every word 12px tracked .04em: the notice at the start, the theme and language preferences at the end, each an icon and its value with no "Theme:" or "Language:" label (the selects keep those names for assistive technology). No search field — the header carries search.
+
+
+## Verification
+
+Use packed consumers, real SSR and hydration, light/dark desktop and compact widths, keyboard and touch, reduced motion and forced colors. Compare shell geometry against the recorded baseline. Keep preview documents isolated from site CSS.

package/src/styles/system/badge-tones.css

@@ -0,0 +1,4 @@
+/* A comparison annotation keeps its teaching hue; Master UI owns the badge recipe. */
+@layer components {
+  .demo-badge-violet { --badge-tone: var(--ui-tone-violet); }
+}

package/src/styles/system/badge.ts

@@ -0,0 +1,2 @@
+import '@master/ui/components/badge.css'
+import './badge-tones.css'