@master/internal-site 0.1.2 → 0.2.0

package/src/demo/DemoSurface.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import '@master/internal-site/styles/system/sheet.css'
+
   import '@master/internal-site/styles/system/specimens.css'
   import type { Snippet } from 'svelte'
   import type { HTMLAttributes } from 'svelte/elements'

package/src/demo/DemoThemeComparison.astro

@@ -1,4 +1,7 @@
 ---
+import { siteOf } from '@master/internal-site/astro/site-context.ts'
+const { t } = siteOf(Astro)
+import '@master/internal-site/styles/system/compare.css'
 import Demo from '@master/internal-site/demo/Demo.svelte'
 import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
 import { demoDocument } from '@master/internal-site/demo/reference/document.ts'
@@ -23,8 +26,8 @@ const document = (mode: 'light' | 'dark') => demoDocument({ page: 'foundations',
 <Demo title={title} frame="none" caption={caption} data-foundation-paint={name}>
   <div class="ui-compare">
     {(['light', 'dark'] as const).map(mode => <figure data-theme-specimen={mode}>
-      <figcaption>{mode === 'light' ? 'Light' : 'Dark'}</figcaption>
-      <DemoViewport client:idle={{ timeout: 500 }} title={`${title} · ${mode}`} document={document(mode)} initialTheme={mode} print={print} height={height} sizing="content" />
+      <figcaption>{mode === 'light' ? t('Light') : t('Dark')}</figcaption>
+      <DemoViewport client:idle={{ timeout: 500 }} title={`${t(title)} · ${mode === 'light' ? t('Light') : t('Dark')}`} document={document(mode)} initialTheme={mode} print={print} height={height} sizing="content" />
     </figure>)}
   </div>
 </Demo>

package/src/demo/DemoTokenTable.astro

@@ -1,5 +1,7 @@
 ---
-import '@master/internal-site/styles/system/data.css'
+import { siteOf } from '@master/internal-site/astro/site-context.ts'
+const { t } = siteOf(Astro)
+import '@master/internal-site/styles/system/table.css'
 import InlineCode from '@master/internal-site/components/InlineCode.astro'
 import RenderNode from '@master/internal-site/components/RenderNode.astro'
 
@@ -22,8 +24,8 @@ const { rows, descriptionTitle = 'Role' } = Astro.props
 ---
 
 {/* Narrow token inventories need native keyboard scrolling. */}
-<div class="ui-table" role="region" aria-label={`${descriptionTitle} token table`} tabindex="0"><table>
-  <thead><tr><th scope="col">Token / class</th><th scope="col" class="(min-width:12rem)">{descriptionTitle}</th></tr></thead>
+<div class="ui-table" role="region" aria-label={t('{label} token table').replace('{label}', t(descriptionTitle))} tabindex="0"><table>
+  <thead><tr><th scope="col">{t('Token / class')}</th><th scope="col" class="(min-width:12rem)">{t(descriptionTitle)}</th></tr></thead>
   <tbody>{rows.map(({ token, utilities, value, description, preview }) => <tr>
     <td>
       <div class="whitespace-nowrap">{preview != null && <RenderNode node={preview} />}<code>{token}</code></div>

package/src/demo/DemoViewTransition.astro

@@ -1,4 +1,6 @@
 ---
+import { siteOf } from '@master/internal-site/astro/site-context'
+const { t } = siteOf(Astro)
 import Demo from '@master/internal-site/demo/Demo.svelte'
 import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
 
@@ -14,5 +16,5 @@ const title = articles ? 'From collection to article' : 'A change of view'
 
 <Demo title={title} frame="none" data-view-transition={example}
   caption={articles ? 'Open an article, then return to its card. Each image and title keeps a unique snapshot name. Keyboard focus follows the view change.' : 'Choose a view. The panel and heading use named snapshots; unsupported browsers and reduced motion use the same immediate update.'}>
-  <DemoViewport client:idle={{ timeout: 500 }} title={title} src={origin + (articles ? '/examples/article-transitions' : '/examples/view-transitions')} height={articles ? 640 : 340} sizing="viewport" />
+  <DemoViewport client:idle={{ timeout: 500 }} title={t(title)} src={origin + (articles ? '/examples/article-transitions' : '/examples/view-transitions')} height={articles ? 640 : 340} sizing="viewport" />
 </Demo>

package/src/demo/DemoViewport.svelte

@@ -28,6 +28,13 @@
 </script>
 
 <script lang="ts">
+  import { getSite } from '@master/internal-site/site'
+  const { t } = getSite()
+  import '@master/internal-site/styles/interface.css'
+  import '@master/internal-site/styles/system/browser.css'
+  import '@master/internal-site/styles/system/range.css'
+  import '@master/internal-site/styles/system/segmented.css'
+
   import { untrack } from 'svelte'
   import IconMoon from '@tabler/icons-svelte-runes/icons/moon'
   import IconPlayerPause from '@tabler/icons-svelte-runes/icons/player-pause'
@@ -287,38 +294,38 @@
   {#if chrome}<div class="ui-browser-bar" aria-hidden="true"><span class="ui-browser-dots"><i></i><i></i><i></i></span></div>{/if}
   <div bind:this={body} class="ui-browser-body">
     <div class="ui-browser-viewport" style:width={width ? `${width}px` : `min(100%, ${maxWidth}px)`}>
-      <iframe bind:this={frame} {title} srcdoc={source} {src} loading="lazy" data-ready={ready} data-sizing={sizing}
+      <iframe bind:this={frame} title={t(title)} srcdoc={source} {src} loading="lazy" data-ready={ready} data-sizing={sizing}
         style:height={`${sizing === 'content' ? contentHeight ?? height : height}px`} onload={load}></iframe>
       {#if responsive}<span class="ui-resize" aria-hidden="true" onpointerdown={drag}></span>{/if}
     </div>
   </div>
 </div>
 {#if responsive || motion || print || theme || Boolean(inspect?.length)}
-  <div class="ui-browser-tools" role="group" aria-label={`${title} controls`}>
+  <div class="ui-browser-tools" role="group" aria-label={t('{label} controls').replace('{label}', t(title))}>
     {#if responsive}
-      {#if widthPresets?.length}<div class="ui-segmented" role="group" aria-label={`${rangeLabel} presets`}>
+      {#if widthPresets?.length}<div class="ui-segmented" role="group" aria-label={t('{label} presets').replace('{label}', t(rangeLabel))}>
         {#each widthPresets as preset (preset.label)}<button type="button" disabled={!ready}
-          aria-pressed={width === preset.width} onclick={() => { width = preset.width }}>{preset.label}</button>{/each}
+          aria-pressed={width === preset.width} onclick={() => { width = preset.width }}>{t(preset.label)}</button>{/each}
       </div>{/if}
       <span class="ui-browser-range">
-        <label class="ui-label" data-case="as-is" for={widthId}>{rangeLabel}</label>
+        <label class="ui-label" data-case="as-is" for={widthId}>{t(rangeLabel)}</label>
         <input id={widthId} class="ui-range" disabled={!ready} type="range" min={range.min} max={range.max} step="1" value={range.value}
           style:--value={`${((range.value - range.min) / Math.max(1, range.max - range.min)) * 100}%`}
           oninput={event => { width = Number(event.currentTarget.value) }} />
         {#if ready}<output class="ui-browser-size" for={widthId}>{fitWidth} px</output>{/if}
       </span>
-      <button type="button" disabled={!ready} class="ui-button" data-size="sm" onclick={() => { width = undefined }}>Fit</button>
+      <button type="button" disabled={!ready} class="ui-button" data-size="sm" onclick={() => { width = undefined }}>{t('Fit')}</button>
     {/if}
-    {#if theme}<button type="button" disabled={!ready} class="ui-button" data-size="sm" aria-pressed={isDark} title="Toggle dark theme" onclick={() => { dark = !isDark }}>
-      {#if isDark}<IconMoon aria-hidden="true" />{:else}<IconSun aria-hidden="true" />{/if}Theme
+    {#if theme}<button type="button" disabled={!ready} class="ui-button" data-size="sm" aria-pressed={isDark} title={t('Toggle dark theme')} onclick={() => { dark = !isDark }}>
+      {#if isDark}<IconMoon aria-hidden="true" />{:else}<IconSun aria-hidden="true" />{/if}{t('Theme')}
     </button>{/if}
     {#if motion}
       <button type="button" disabled={!ready} class="ui-button" data-size="sm" onclick={() => animate(playing ? 'pause' : 'play')}>
-        {#if playing}<IconPlayerPause aria-hidden="true" />{:else}<IconPlayerPlay aria-hidden="true" />{/if}{playing ? 'Pause' : 'Play'}
+        {#if playing}<IconPlayerPause aria-hidden="true" />{:else}<IconPlayerPlay aria-hidden="true" />{/if}{playing ? t('Pause') : t('Play')}
       </button>
-      <button type="button" disabled={!ready} class="ui-button" data-size="sm" data-variant="quiet" onclick={() => animate('restart')}><IconRefresh aria-hidden="true" />Replay</button>
+      <button type="button" disabled={!ready} class="ui-button" data-size="sm" data-variant="quiet" onclick={() => animate('restart')}><IconRefresh aria-hidden="true" />{t('Replay')}</button>
     {/if}
-    {#if print}<button type="button" disabled={!ready} class="ui-button" data-size="sm" onclick={() => frame?.contentWindow?.print()}><IconPrinter aria-hidden="true" />Print preview</button>{/if}
+    {#if print}<button type="button" disabled={!ready} class="ui-button" data-size="sm" onclick={() => frame?.contentWindow?.print()}><IconPrinter aria-hidden="true" />{t('Print preview')}</button>{/if}
     {#if properties}<output aria-live="polite">{properties}</output>{/if}
   </div>
 {/if}

package/src/demo/DemoWaterfall.astro

@@ -1,5 +1,7 @@
 ---
-import '@master/internal-site/styles/system/data.css'
+import { siteOf } from '@master/internal-site/astro/site-context'
+const { t } = siteOf(Astro)
+import '@master/internal-site/styles/system/waterfall.css'
 import Demo from '@master/internal-site/demo/Demo.svelte'
 import type { DemoWaterfallProps } from '@master/internal-site/demo/demo-waterfall.ts'
 
@@ -15,7 +17,7 @@ for (const { label, start, end } of rows) {
 
 <Demo title={title} description={description} caption={caption} padding="sm" aria-label={title}>
   <div class="w-full ui-waterfall">
-    <div class="ui-waterfall-axis" aria-hidden="true"><span /><div class="relative"><span>Earlier</span>{marker && <span class="absolute font-medium fg-text-strong (translate:-50%)" style={{ left: `${marker.position}%` }}>{marker.label}</span>}<span>Later</span></div></div>
+    <div class="ui-waterfall-axis" aria-hidden="true"><span /><div class="relative"><span>{t("Earlier")}</span>{marker && <span class="absolute font-medium fg-text-strong (translate:-50%)" style={{ left: `${marker.position}%` }}>{marker.label}</span>}<span>{t("Later")}</span></div></div>
     {/* Preserve WebKit list semantics without list markers. */}
     <ul role="list" class="grid gap-2xs m(0) p(0) (list-style:none)">
       {rows.map(({ label, start, end, tone = 'blue' }) => <li class="ui-waterfall-row">

package/src/demo/ProjectStyleExample.astro

@@ -1,6 +1,8 @@
 ---
 import DemoConfiguredExample from '@master/internal-site/demo/DemoConfiguredExample.astro'
 import { projectStyleExample, type ProjectStyleName } from '@master/internal-site/demo/project-style-examples.ts'
+import { documentCopyOf, siteOf } from '@master/internal-site/astro/site-context'
+import { demoCopy } from '@master/internal-site/utils/document-copy.js'
 
 interface Props {
   name: ProjectStyleName
@@ -8,6 +10,7 @@ interface Props {
 }
 
 const { name, code = true } = Astro.props
+const example = demoCopy(documentCopyOf(Astro), siteOf(Astro).locale, `ProjectStyleExample:${name}`, projectStyleExample(name))
 ---
 
-<DemoConfiguredExample name={name} {...projectStyleExample(name)} code={code} />
+<DemoConfiguredExample name={name} {...example} code={code} />

package/src/demo/foundations/FoundationDialog.astro

@@ -1,8 +1,12 @@
 ---
+import '@master/internal-site/styles/interface.css'
 import FoundationSpecimen from '@master/internal-site/demo/foundations/FoundationSpecimen.astro'
+import { dialogCopy } from './dialog-copy.js'
+interface Props { title?: string; caption?: string }
+const { title = dialogCopy.title, caption = dialogCopy.caption } = Astro.props
 ---
 
-<FoundationSpecimen name="dialog-entrance" title="Motion follows a real action" scene={{ systemButtons: true, sizing: 'viewport', height: 340, css: `@theme {
+<FoundationSpecimen name="dialog-entrance" title={title} scene={{ systemButtons: true, sizing: 'viewport', height: 340, css: `@theme {
   --duration-enter: 180ms;
   --easing-emphasized: cubic-bezier(.16, 1, .3, 1);
   --animate-dialog-in: dialog-in var(--duration-enter) var(--easing-emphasized) both;
@@ -11,4 +15,4 @@ import FoundationSpecimen from '@master/internal-site/demo/foundations/Foundatio
     from { translate: 0 0.5rem; opacity: 0; }
     to { translate: 0; opacity: 1; }
   }
-`, html: "<article class=\"p-md r-sm b(1) b-solid b-line-divider bg-surface-raised\"><h2 class=\"m(0) text-lg font-regular\">Collection settings</h2><p class=\"mt-xs mb-md fg-text-muted\">Open a native dialog to preview its entrance.</p><button id=\"open\" type=\"button\" class=\"ui-button\">Open details</button></article>\n<dialog id=\"details\" aria-labelledby=\"dialog-title\" aria-describedby=\"dialog-description\" class=\"(width:calc(100%-32px)) max-w-xs m-auto p-md r-lg b(1) b-solid b-line-divider bg-surface-floating fg-text-body shadow-xl animate-dialog-in@media(screen)@motion-safe\">\n<h2 id=\"dialog-title\" class=\"m(0) text-lg font-regular fg-text-strong\">Collection details</h2><p id=\"dialog-description\" class=\"mt-sm mb-md\">This dialog has a finite entrance. Closing it is immediate.</p><form method=\"dialog\"><button class=\"ui-button\" autofocus>Close details</button></form>\n</dialog><script>const dialog = document.getElementById('details'); const openButton = document.getElementById('open'); openButton.addEventListener('click', () => dialog.showModal()); dialog.addEventListener('close', () => openButton.focus());</script>", caption: 'The dialog enters once on opening. Escape or Close details returns focus to its trigger. Reduced motion opens it immediately. Its modal boundary stays inside this preview.' }} />
+`, html: "<article class=\"p-md r-sm b(1) b-solid b-line-divider bg-surface-raised\"><h2 class=\"m(0) text-lg font-regular\">Collection settings</h2><p class=\"mt-xs mb-md fg-text-muted\">Open a native dialog to preview its entrance.</p><button id=\"open\" type=\"button\" class=\"ui-button\">Open details</button></article>\n<dialog id=\"details\" aria-labelledby=\"dialog-title\" aria-describedby=\"dialog-description\" class=\"(width:calc(100%-32px)) max-w-xs m-auto p-md r-lg b(1) b-solid b-line-divider bg-surface-floating fg-text-body shadow-xl animate-dialog-in@media(screen)@motion-safe\">\n<h2 id=\"dialog-title\" class=\"m(0) text-lg font-regular fg-text-strong\">Collection details</h2><p id=\"dialog-description\" class=\"mt-sm mb-md\">This dialog has a finite entrance. Closing it is immediate.</p><form method=\"dialog\"><button class=\"ui-button\" autofocus>Close details</button></form>\n</dialog><script>const dialog = document.getElementById('details'); const openButton = document.getElementById('open'); openButton.addEventListener('click', () => dialog.showModal()); dialog.addEventListener('close', () => openButton.focus());</script>", caption }} />

package/src/demo/foundations/FoundationMedia.astro

@@ -1,4 +1,5 @@
 ---
+import '@master/internal-site/styles/system/sheet.css'
 import DemoContainer from '@master/internal-site/demo/DemoContainer.svelte'
 import DemoLabel from '@master/internal-site/demo/DemoLabel.svelte'
 import DemoMedia from '@master/internal-site/demo/DemoMedia.svelte'

package/src/demo/foundations/FoundationShrink.astro

@@ -1,4 +1,5 @@
 ---
+import '@master/internal-site/styles/system/sheet.css'
 import DemoContainer from '@master/internal-site/demo/DemoContainer.svelte'
 import DemoItem from '@master/internal-site/demo/DemoItem.svelte'
 ---

package/src/demo/foundations/FoundationTokensView.astro

@@ -1,4 +1,6 @@
 ---
+import { siteOf } from '@master/internal-site/astro/site-context.ts'
+const { t } = siteOf(Astro)
 import Demo from '@master/internal-site/demo/Demo.svelte'
 import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
 import DemoThemeComparison from '@master/internal-site/demo/DemoThemeComparison.astro'
@@ -17,6 +19,13 @@ interface Props {
 const { namespace, keys, presentation = 'reference' } = Astro.props
 const tokens = namespace === 'breakpoints' ? [] : specimenTokens(namespace, keys)
 const tokenKeys = tokens.map(token => token.key).join(' ')
+const namespaceTitles: Record<string, string> = {
+  'color-surface': t('Surface colors'), 'color-line': t('Line colors'), 'color-text': t('Text colors'),
+  shadow: t('Shadow scale'), radius: t('Corner radius scale'), container: t('Container widths'),
+  'font-family': t('Font families'), 'font-size': t('Font sizes'), 'font-weight': t('Font weights'),
+  text: t('Text styles'), leading: t('Line heights'), tracking: t('Letter spacing'),
+  animate: t('Animations'), duration: t('Animation durations'), easing: t('Timing functions'),
+}
 
 function tokenScene(tokens: FoundationToken[], title: string, compare = false) {
   const scene = foundationScene(namespace, tokens.map(token => token.key))
@@ -39,22 +48,24 @@ if (namespace === 'color') {
   const aliases = rest.filter(token => defaultValue(token).startsWith('var('))
   const specials = rest.filter(token => !aliases.includes(token))
   scenes = [
-    aliases.length > 0 ? tokenScene(aliases, 'Hue aliases', true) : undefined,
-    specials.length > 0 ? tokenScene(specials, 'Special colors', true) : undefined,
+    aliases.length > 0 ? tokenScene(aliases, t('Hue aliases'), true) : undefined,
+    specials.length > 0 ? tokenScene(specials, t('Special colors'), true) : undefined,
   ].filter(scene => scene !== undefined)
 } else if (namespace !== 'breakpoints' && namespace !== 'spacing') {
-  const scene = tokenScene(tokens, namespace === 'shadow' ? 'Shadow scale' : namespace === 'radius' ? 'Corner radius scale' : namespace.replaceAll('-', ' '), namespace.startsWith('color-') || (namespace === 'shadow' && presentation === 'reference'))
+  const title = namespaceTitles[namespace]
+  if (!title) throw new Error(`Missing foundation title: ${namespace}`)
+  const scene = tokenScene(tokens, title, namespace.startsWith('color-') || (namespace === 'shadow' && presentation === 'reference'))
   scenes = scene ? [scene] : []
 }
 ---
 
 {namespace === 'breakpoints' ? <ThemeNumberVariableTable namespace="breakpoint" />
   : namespace === 'color' ? <div data-foundation-tokens={namespace} data-token-keys={tokenKeys}>
-    {palette.length > 0 && <Demo title="Fixed color steps" padding="sm" caption={specimenCaption.color}><Palette client:idle={{ timeout: 500 }} groups={palette} /></Demo>}
+    {palette.length > 0 && <Demo title={t('Fixed color steps')} padding="sm" caption={specimenCaption.color}><Palette client:idle={{ timeout: 500 }} groups={palette} /></Demo>}
     {scenes.map(({ scene, title }) => <DemoThemeComparison name={`tokens-${namespace}`} title={title} html={scene.html!} css={scene.css} caption={scene.caption} />)}
   </div>
   : <div data-foundation-tokens={namespace} data-token-keys={tokenKeys}>
-    {namespace === 'spacing' ? <><ThemeNumberVariableTable namespace="spacing" keys={keys} representation="spacing" referenceUnits={presentation !== 'guide'} /><p class="m(0) font-xs fg-text-muted">{presentation === 'guide' ? 'The striped area is the actual gap between two equal blocks.' : specimenCaption.spacing}</p></>
+    {namespace === 'spacing' ? <><ThemeNumberVariableTable namespace="spacing" keys={keys} representation="spacing" referenceUnits={presentation !== 'guide'} /><p class="m(0) font-xs fg-text-muted">{presentation === 'guide' ? t('The striped area is the actual gap between two equal blocks.') : t(specimenCaption.spacing)}</p></>
       : scenes.map(({ scene, title, compare }) => compare
         ? <DemoThemeComparison name={`tokens-${namespace}`} title={title} html={scene.html!} css={scene.css} caption={scene.caption} />
         : <Demo title={title} frame="none" caption={scene.caption}>

package/src/demo/foundations/Palette.svelte

@@ -3,6 +3,10 @@
 </script>
 
 <script lang="ts">
+  import { getSite } from '@master/internal-site/site'
+  const { t } = getSite()
+  import '@master/internal-site/styles/system/fields.css'
+
   import '@master/internal-site/styles/system/specimens.css'
   import '@master/internal-site/styles/demo.css'
   import DemoCopyButton from '@master/internal-site/demo/DemoCopyButton.svelte'
@@ -15,23 +19,23 @@
   const endId = `${id}-end`
 </script>
 
-<div class="w-full"><DemoCopyGroup instruction={format === 'value' ? 'Choose a swatch to copy its original CSS color value.' : 'Choose a swatch to copy its CSS variable reference.'}>
-  <label class="w-fit ui-field" for={id}>Copy as
+<div class="w-full"><DemoCopyGroup instruction={format === 'value' ? t('Choose a swatch to copy its original CSS color value.') : t('Choose a swatch to copy its CSS variable reference.')}>
+  <label class="w-fit ui-field" for={id}>{t('Copy as')}
     <select {id} class="ui-select" data-variant="raised" bind:value={format}>
-      <option value="value">CSS value</option><option value="variable">CSS variable</option>
+      <option value="value">{t('CSS value')}</option><option value="variable">{t('CSS variable')}</option>
     </select>
   </label>
-  <a class="ui-skip" href={`#${endId}`}>Skip color swatches</a>
+  <a class="ui-skip" href={`#${endId}`}>{t('Skip color swatches')}</a>
   <div class="ui-palette">
-    {#each groups as group (group.family)}<div class="ui-palette-row" role="group" aria-label={`${group.family} palette`}>
+    {#each groups as group (group.family)}<div class="ui-palette-row" role="group" aria-label={t('{family} palette').replace('{family}', group.family)}>
       <span>{group.family}</span>
       {#each group.colors as color (color.name)}<div class="ui-palette-cell">
         <DemoCopyButton icon={null} class="ui-palette-chip" style={`background-color:${color.value}`}
           value={format === 'value' ? color.value : `var(--${color.name})`}
-          label={`Copy ${color.name} ${format === 'value' ? 'CSS value' : 'CSS variable'}`} title={`${color.name}: ${color.value}`} />
+          label={format === 'value' ? t('Copy {name} CSS value').replace('{name}', color.name) : t('Copy {name} CSS variable').replace('{name}', color.name)} title={`${color.name}: ${color.value}`} />
         <span aria-hidden="true">{color.step}</span>
       </div>{/each}
     </div>{/each}
   </div>
-  <div id={endId} tabindex="-1"><span class="sr-only">End of color palette</span></div>
+  <div id={endId} tabindex="-1"><span class="sr-only">{t('End of color palette')}</span></div>
 </DemoCopyGroup></div>

package/src/demo/foundations/dialog-copy.d.ts

@@ -0,0 +1 @@
+export declare const dialogCopy: { title: string; caption: string }

package/src/demo/foundations/dialog-copy.js

@@ -0,0 +1,5 @@
+/** Reader-facing copy; the executable dialog specimen stays English. */
+export const dialogCopy = {
+  title: 'Motion follows a real action',
+  caption: 'The dialog enters once on opening. Escape or Close details returns focus to its trigger. Reduced motion opens it immediately. Its modal boundary stays inside this preview.'
+}

package/src/demo/illustration-materials.ts

@@ -159,7 +159,7 @@ export function drawing(theme: Theme) {
 <head>
 <meta charset="utf-8">
 <title>${escapeHtml(title)}</title>
-<link rel="stylesheet" href="${asset('../../../../styles/system/tokens.css')}">
+<link rel="stylesheet" href="${asset('../styles/system/tokens.css')}">
 <link rel="stylesheet" href="${asset('./illustration.css')}">
 </head>
 <body>

package/src/demo/illustration.css

@@ -0,0 +1,218 @@
+/*
+ * Illustration primitives drawn with the site's own tokens (`styles/system/tokens.css`), at 1:1 with the
+ * article: the 720px scene shows at the wide media width (712px on desktop), so a 14px label reads as 14px.
+ * Artifacts are sheets, operations are control-sized chips, groups are eyebrow captions over a hairline partition:
+ * the figure is a tray's stage, so nothing in it forms another nested frame. Nothing invents a colour.
+ */
+@font-face { font-family: Geist; font-weight: 100 900; src: url("../public/fonts/GeistVariable.woff2") format("woff2"); }
+@font-face { font-family: "IBM Plex Mono"; font-weight: 400; src: url("../public/fonts/IBMPlexMono-Regular.woff2") format("woff2"); }
+
+:root { color-scheme: light; }
+:root.dark { color-scheme: dark; }
+* { box-sizing: border-box; }
+body {
+  margin: 0; overflow: hidden;
+  background: var(--ui-stage-light), var(--ui-surface-stage);
+  color: var(--ui-text-body); font: var(--ui-weight-regular) 13px/20px Geist, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+.scene { position: relative; overflow: hidden; }
+.scene > * { position: absolute; }
+
+/* Routes: one hairline ink, a chevron head, dashes only for a labelled condition */
+.routes { inset: 0; overflow: visible; }
+.routes path { fill: none; stroke: var(--ui-line-mark); stroke-width: 1; stroke-linecap: round; stroke-linejoin: round; }
+.routes path[data-dashed] { stroke-dasharray: 3 4; }
+.routes marker path { stroke: var(--ui-text-disabled); stroke-width: 1.25; }
+.routes path[marker-end] { stroke: var(--ui-text-disabled); }
+
+/* Type: the documentation's small sizes at its light regular weight */
+.title { color: var(--ui-text-strong); font-size: 14px; font-weight: var(--ui-weight-medium); line-height: 20px; white-space: nowrap; }
+.note { color: var(--ui-text-muted); font-size: 13px; line-height: 20px; white-space: nowrap; }
+.body { color: var(--ui-text-body); font-size: 13px; line-height: 20px; white-space: nowrap; }
+.edge { color: var(--ui-text-muted); font-size: 12px; line-height: 16px; white-space: nowrap; }
+.code { color: var(--ui-text-body); font: 400 12.5px/20px "IBM Plex Mono", monospace; white-space: nowrap; }
+.eyebrow { color: var(--ui-text-muted); font-size: 11px; font-weight: var(--ui-weight-medium); line-height: 16px; letter-spacing: .14em; text-transform: uppercase; white-space: nowrap; }
+.center { translate: -50% 0; text-align: center; }
+.end { translate: -100% 0; text-align: right; }
+.icon { flex: none; width: 16px; height: 16px; color: var(--ui-text-muted); }
+.icon svg { display: block; width: 100%; height: 100%; fill: none; stroke: currentColor; stroke-width: 1.75; stroke-linecap: round; stroke-linejoin: round; }
+
+/* An artifact: the sheet face at rise-1, the small card radius */
+.sheet {
+  display: flex; flex-direction: column; width: max-content; gap: 4px; padding: 13px 16px 14px;
+  border-radius: var(--ui-radius-xl);
+  background: linear-gradient(180deg, var(--ui-surface-sheet), var(--ui-surface-sheet-lo));
+  box-shadow: var(--ui-elevation-rise-1);
+}
+.anchor-center { translate: -50% 0; }
+.anchor-end { translate: -100% 0; }
+.sheet > .row { display: flex; align-items: center; gap: 8px; min-height: 20px; }
+.sheet > .rule { height: 1px; margin: 7px -16px 5px; background: var(--ui-line-hair); }
+.sheet .bars { display: grid; gap: 9px; padding-top: 8px; }
+.sheet .bars i { display: block; height: 5px; border-radius: 3px; background: var(--ui-line-divider); }
+
+/* An operation: a control-sized chip, like a button at rest */
+.chip {
+  display: flex; align-items: center; justify-content: center; gap: 8px; height: 32px; padding: 0 12px 0 10px;
+  border-radius: var(--ui-radius-md);
+  background: linear-gradient(180deg, var(--ui-surface-sheet), var(--ui-surface-sheet-lo));
+  box-shadow: var(--ui-elevation-rise-1);
+  color: var(--ui-text-strong); font-size: 13.5px; font-weight: var(--ui-weight-medium); white-space: nowrap;
+}
+
+/* A plain mark: an icon beside a title, with no frame */
+.mark { display: flex; align-items: center; gap: 8px; }
+
+/* A boundary between two places: one hairline partition, each side captioned by an eyebrow */
+.divider { width: 1px; background: var(--ui-line-divider); }
+
+/* A window: one contour, a tray-tone toolbar with its dots only */
+.window { overflow: hidden; border-radius: var(--ui-radius-xl); background: var(--ui-surface-stage); box-shadow: var(--ui-elevation-rise-1); }
+.window > .toolbar { display: flex; align-items: center; gap: 6px; height: 32px; padding: 0 12px; background: var(--ui-surface-tray); }
+.window > .toolbar i { width: 7px; height: 7px; border-radius: 50%; background: var(--ui-line-strong); }
+.window > .bars { display: grid; gap: 10px; padding: 18px 20px; }
+.window > .bars i { display: block; height: 5px; border-radius: 3px; background: var(--ui-line-divider); }
+.window > .bars i:first-child { height: 8px; border-radius: 4px; background: var(--ui-line-strong); }
+
+/* Inspection guides expose a control's padding; they are annotations, not part of the taught button. */
+.spacing-study { --sample-ink: var(--ui-text-muted); translate: -50% 0; }
+.spacing-study.accented { --sample-ink: var(--ui-tone-blue); }
+.spacing-control {
+  position: relative; display: flex; align-items: center; justify-content: center;
+  min-height: 38px; padding: 8px var(--sample-padding); border: 1px solid var(--ui-line-divider);
+  border-radius: var(--ui-radius-md); background: var(--ui-surface-sheet); box-shadow: var(--ui-elevation-rise-1);
+}
+.spacing-control > .body { color: var(--ui-text-strong); font-size: 14px; font-weight: 400; line-height: 1.2; }
+.spacing-control > i { position: absolute; inset-block: 0; width: var(--sample-padding); background: color-mix(in oklch, var(--sample-ink) 10%, transparent); }
+.spacing-control > .padding-start { left: 0; border-right: 1px dotted var(--sample-ink); border-radius: var(--ui-radius-md) 0 0 var(--ui-radius-md); }
+.spacing-control > .padding-end { right: 0; border-left: 1px dotted var(--sample-ink); border-radius: 0 var(--ui-radius-md) var(--ui-radius-md) 0; }
+.spacing-ruler { display: flex; align-items: center; justify-content: space-between; gap: 6px; margin: 16px 1px 0; }
+.spacing-ruler > .edge { color: var(--sample-ink); }
+.spacing-ruler > i { flex: none; position: relative; width: var(--sample-padding); height: 7px; border-inline: 1px solid var(--sample-ink); }
+.spacing-ruler > i::after { content: ''; position: absolute; top: 3px; inset-inline: 0; border-top: 1px solid var(--sample-ink); }
+
+/* Equal-area swatches show real color. Only the target outline belongs to the annotation. */
+.color-scale { display: flex; gap: 16px; width: max-content; }
+.color-scale-step { display: grid; justify-items: center; gap: 10px; }
+.color-scale-step > i { display: block; width: 40px; aspect-ratio: 1; border-radius: var(--ui-radius-sm); box-shadow: inset 0 0 0 1px var(--ui-line-hair); }
+.color-scale-step > i[data-selected] { outline: 1px solid var(--annotation-ink); outline-offset: 5px; }
+.role-selection { display: grid; justify-items: center; gap: 18px; width: max-content; }
+.role-selection > .code { color: var(--annotation-ink); }
+.role-selection-sample { padding: 20px 24px; border-radius: var(--ui-radius-lg); box-shadow: var(--ui-elevation-rise-1); }
+.role-selection-sample > span { font: var(--ui-weight-regular) 14px/1.5 Geist, sans-serif; }
+.spacing-sample { width: max-content; outline: 1px dashed var(--annotation-ink); }
+.spacing-sample[data-kind="padding"] { background: color-mix(in oklch, var(--annotation-ink) 12%, var(--ui-surface-stage)); }
+.spacing-item { position: relative; padding: 10px 12px; background: var(--ui-surface-sheet); box-shadow: inset 0 0 0 1px var(--ui-line-divider); }
+.spacing-sample[data-kind="gap"] > .spacing-item + .spacing-item::before { content: ''; position: absolute; inset-inline: 0; bottom: 100%; height: var(--spacing-md); background: color-mix(in oklch, var(--annotation-ink) 12%, var(--ui-surface-stage)); }
+.sizing-study { display: grid; gap: 16px; }
+.sizing-parent { outline: 1px dashed var(--ui-text-muted); }
+.sizing-child { display: flex; justify-content: space-between; gap: 16px; padding: 16px; background: var(--ui-surface-sheet); box-shadow: inset 0 0 0 1px var(--ui-line-divider); }
+.radius-sample { width: 224px; background: var(--ui-surface-sheet); outline: 1px dashed var(--ui-text-muted); }
+.radius-child { padding: 16px 20px; background: color-mix(in oklch, var(--ui-tone-blue) 16%, var(--ui-surface-sheet)); }
+.radius-parent-content { padding: 24px 20px; }
+.shadow-study { display: grid; gap: 16px; width: max-content; }
+.shadow-sample { display: grid; gap: 8px; padding: 24px; border-radius: var(--ui-radius-lg); background: var(--ui-surface-sheet); }
+.shadow-following { position: relative; padding: 10px 24px; box-shadow: inset 0 1px 0 var(--ui-line-divider); }
+.shadow-gap { position: absolute; right: -24px; top: -16px; width: 0; height: 16px; border-inline-start: 1px solid var(--ui-tone-blue); }
+.shadow-gap::before, .shadow-gap::after { content: ''; position: absolute; left: -3px; width: 5px; border-top: 1px solid var(--ui-tone-blue); }
+.shadow-gap::before { top: 0; }
+.shadow-gap::after { bottom: 0; }
+.shadow-gap > .edge { display: block; width: max-content; margin-inline-start: 8px; color: var(--ui-tone-blue); line-height: 16px; }
+.font-comparison { display: grid; grid-template-columns: repeat(3, max-content); align-items: baseline; gap: 24px 36px; }
+.font-specimen { line-height: 1.5; color: var(--ui-text-strong); }
+.leading-study { display: grid; grid-template-columns: repeat(2, max-content); gap: 72px; }
+.leading-column { display: grid; align-content: start; gap: 16px; }
+.leading-lines { width: 12rem; color: var(--ui-text-strong); }
+.leading-lines > span { display: block; background: color-mix(in oklch, var(--annotation-ink) 8%, transparent); box-shadow: inset 0 -1px 0 color-mix(in oklch, var(--annotation-ink) 30%, transparent); }
+.leading-column > .edge { color: var(--annotation-ink); }
+.tracking-scope { display: grid; grid-template-columns: repeat(2, max-content); align-items: baseline; gap: 12px 28px; padding: 24px; border: 1px solid var(--ui-line-divider); border-radius: var(--ui-radius-lg); }
+.tracking-row { display: contents; }
+.tracking-row > .code { grid-column: 1 / -1; }
+.tracking-row + .tracking-row > .code { margin-top: 20px; }
+.tracking-row > :not(.tracking-sample) { letter-spacing: normal; }
+.tracking-sample { width: max-content; line-height: 1.5; color: var(--ui-text-strong); box-shadow: inset 0 -1px 0 var(--annotation-ink); }
+.tracking-row > .edge { color: var(--annotation-ink); }
+
+/* Syntax anatomy: one intact string with exact ranges and nearby, directly attached explanations. */
+[data-tone="blue"] { --annotation-ink: var(--ui-tone-blue); }
+[data-tone="violet"] { --annotation-ink: var(--ui-tone-violet); }
+[data-tone="amber"] { --annotation-ink: color-mix(in srgb, var(--ui-tone-amber) 75%, var(--ui-text-strong)); }
+.annotated-code { display: flex; width: max-content; }
+.code-part { position: relative; padding-block: 4px; background: color-mix(in oklch, var(--annotation-ink) 8%, transparent); }
+.code-part > .code { color: var(--annotation-ink); }
+.code-part:first-child { border-radius: var(--ui-radius-sm) 0 0 var(--ui-radius-sm); }
+.code-part:last-child { border-radius: 0 var(--ui-radius-sm) var(--ui-radius-sm) 0; }
+.code-bracket { position: absolute; inset-inline: 1px; bottom: -9px; height: 5px; border: 1px solid var(--annotation-ink); border-top: 0; }
+.annotation { display: flex; flex-direction: column; align-items: center; gap: 6px; width: max-content; }
+.annotation > .title { color: var(--annotation-ink); }
+.routes path[data-from] { stroke: color-mix(in srgb, var(--annotation-ink) 65%, var(--ui-line-mark)); }
+
+/* A shared stylesheet reaches every consumer; conversion and verification have different scopes. */
+.migration-reach { left: 50%; top: 50%; translate: -50% -50%; display: flex; flex-direction: column; align-items: center; width: max-content; }
+.migration-reach > .sheet { position: static; }
+.migration-trunk { position: relative; height: 76px; border-left: 1px solid var(--ui-line-mark); }
+.migration-trunk > .edge { position: absolute; left: 12px; top: 24px; }
+.migration-consumers { display: grid; grid-template-columns: repeat(3, 1fr); column-gap: 28px; }
+.migration-consumer { position: relative; display: flex; flex-direction: column; align-items: center; gap: 10px; padding-top: 42px; }
+.migration-consumer::before { content: ''; position: absolute; top: 0; height: 26px; left: 50%; border-left: 1px solid var(--ui-line-mark); }
+.migration-consumer::after { content: ''; position: absolute; top: 0; left: -14px; right: -14px; border-top: 1px solid var(--ui-line-mark); }
+.migration-consumer:first-child::after { left: 50%; }
+.migration-consumer:last-child::after { right: 50%; }
+.migration-screen { display: flex; align-items: center; gap: 8px; padding: 8px 12px; border-radius: var(--ui-radius-md); }
+.migration-consumer.is-batch .migration-screen { background: color-mix(in oklch, var(--ui-tone-blue) 8%, transparent); outline: 1px solid color-mix(in oklch, var(--ui-tone-blue) 45%, transparent); }
+.migration-consumer.is-batch .migration-screen > :is(.title, .icon) { color: var(--ui-tone-blue); }
+.migration-verification { position: relative; align-self: stretch; display: flex; justify-content: center; margin-top: 28px; padding-top: 24px; }
+.migration-verification::before { content: ''; position: absolute; top: 0; inset-inline: 0; height: 8px; border: 1px solid var(--ui-line-mark); border-top: 0; }
+
+/* Same DOM and pointer state; only the suffix's test location changes. */
+.selector-specimen > p { margin: 0 0 8px; }
+.selector-specimen > a { position: relative; display: block; padding: 6px 26px 6px 0; border-radius: var(--ui-radius-xs); }
+.selector-specimen[data-test="owner"] { outline: 1px dashed var(--ui-tone-blue); outline-offset: 3px; }
+.selector-specimen[data-test="target"] > a:first-of-type { outline: 1px dashed var(--ui-tone-blue); outline-offset: 3px; }
+.selector-specimen[data-test="owner"] > a > .body,
+.selector-specimen[data-test="target"] > a:first-of-type > .body { text-decoration: underline; text-underline-offset: 3px; }
+.selector-pointer { position: absolute; top: 15px; right: 4px; width: 20px; height: 20px; fill: var(--ui-surface-sheet); stroke: var(--ui-text-strong); stroke-width: 1.25; stroke-linejoin: round; }
+
+/* Native code containment: an intrinsic block with indentation, braces and a measured scope guide. */
+.code-scope { display: flex; flex-direction: column; width: max-content; }
+.code-scope > .code { color: var(--annotation-ink, var(--ui-text-body)); }
+.code-scope-body { padding-left: 16px; border-left: 1px solid color-mix(in srgb, var(--annotation-ink, var(--ui-text-muted)) 35%, transparent); }
+.code-scope-body > .code-scope { --annotation-ink: var(--ui-text-body); }
+.code-scope-body > .code-scope[data-tone="violet"] { --annotation-ink: var(--ui-tone-violet); }
+
+/* Computed-variable comparison: nested boundaries mean DOM scopes; swatches are literal teaching results. */
+.variable-scope { display: flex; flex-direction: column; gap: 4px; width: max-content; padding: 12px; border: 1px solid var(--ui-line-divider); border-radius: var(--ui-radius-lg); }
+.variable-scope > .code:first-child { color: var(--ui-text-strong); margin-bottom: 3px; }
+.variable-region { display: flex; flex-direction: column; gap: 4px; margin-top: 8px; padding: 10px; border-left: 1px solid var(--ui-line-strong); background: var(--ui-surface-tray); border-radius: 0 var(--ui-radius-sm) var(--ui-radius-sm) 0; }
+.variable-sample { margin-top: 8px; padding: 8px 12px; border-radius: var(--ui-radius-sm); background: #1d4ed8; }
+.variable-sample > .code { color: white; }
+.variable-scope[data-inline="true"] .variable-sample { background: #86198f; }
+.variable-scope .edge { line-height: 20px; }
+
+/* Layer order is a ranked list. The final entry lies outside the five named layers. */
+.priority-stack { display: flex; flex-direction: column; gap: 8px; width: max-content; }
+.priority-stack > div { padding: 6px 28px; text-align: center; background: var(--ui-surface-sheet); border-radius: var(--ui-radius-sm); box-shadow: 0 0 0 1px var(--ui-line-hair); }
+.priority-stack > .unlayered { position: relative; margin-top: 12px; background: none; box-shadow: none; }
+.priority-stack > .unlayered::before { content: ''; position: absolute; top: -10px; inset-inline: 0; height: 1px; background: var(--ui-line-divider); }
+
+.routes path[data-emphasis], .routes marker#arrow-emphasis path { stroke: var(--ui-text-muted); }
+
+/* A removed input remains as context, with no live dependency edge. */
+.source-contribution[data-removed] { background: none; box-shadow: none; outline: 1px dashed var(--ui-line-strong); }
+.source-contribution[data-removed] .title { color: var(--ui-text-muted); text-decoration: line-through; }
+
+/* A shared measured width scale distinguishes the viewport from a query container. */
+.query-scopes { --query-ink: var(--ui-tone-blue); }
+.query-ruler { display: flex; align-items: center; gap: 8px; margin-bottom: 12px; }
+.query-ruler::before, .query-ruler::after { content: ''; flex: 1; height: 8px; border-top: 1px solid var(--query-ink); }
+.query-ruler::before { border-left: 1px solid var(--query-ink); }
+.query-ruler::after { border-right: 1px solid var(--query-ink); }
+.query-ruler > .code { color: var(--query-ink); }
+.query-viewport { display: flex; flex-direction: column; align-items: center; gap: 22px; padding: 16px 0 22px; border: 1px solid var(--ui-line-strong); border-radius: var(--ui-radius-md); }
+.query-scope-heading { display: flex; align-items: center; justify-content: space-between; width: 100%; padding-inline: 16px; }
+.query-scope-heading > .code { color: var(--query-ink); }
+.query-container-study { --query-ink: var(--ui-tone-violet); }
+.query-container { display: flex; flex-direction: column; align-items: center; gap: 6px; padding: 14px 12px; border: 1px solid var(--ui-line-divider); border-radius: var(--ui-radius-sm); background: var(--ui-surface-sheet); }
+.query-container > .code { color: var(--query-ink); }
+.query-descendant { margin-top: 8px; padding: 8px 12px; border-radius: var(--ui-radius-sm); background: var(--ui-surface-tray); }

package/src/docs-shell/common/i18n.config.d.ts

@@ -1,2 +1,2 @@
-declare const config: { defaultLocale: string; locales: readonly string[]; hreflangOfLocale: Record<string, string>; nameOfLocale: Record<string, string> }
+declare const config: { defaultLocale: string; locales: readonly string[]; hreflangOfLocale: Record<string, string>; nameOfLocale: Record<string, string>; localizableOrigins: Record<string, readonly string[]> }
 export default config

package/src/docs-shell/common/i18n.config.js

@@ -1,13 +1,5 @@
-const i18n = {
-  defaultLocale: 'en',
-  locales: ['en', 'tw'],
-  hreflangOfLocale: {
-    tw: 'zh-TW'
-  },
-  nameOfLocale: {
-    tw: '中文 (臺灣)',
-    en: 'English'
-  }
-}
+import { defaultLocale, locales, hreflangOfLocale, nameOfLocale, localizableOrigins } from './locales.js'
 
-export default i18n
+const i18n = { defaultLocale, locales, hreflangOfLocale, nameOfLocale, localizableOrigins }
+
+export default i18n

package/src/docs-shell/common/locales.d.ts

@@ -0,0 +1,8 @@
+export declare const locales: readonly ['en', 'tw', 'ja', 'ko', 'cn']
+export declare const defaultLocale: 'en'
+export type Locale = typeof locales[number]
+export declare const hreflangOfLocale: Record<string, string>
+export declare const nameOfLocale: Record<string, string>
+export declare const localizableOrigins: Record<string, readonly string[]>
+export declare function languageOf(locale: string): string
+export declare function formatDate(value: string | number | Date, locale: string, options?: Intl.DateTimeFormatOptions): string

package/src/docs-shell/common/locales.js

@@ -0,0 +1,18 @@
+/** URL prefixes stay stable; document language tags use standard BCP 47 values. */
+export const locales = ['en', 'tw', 'ja', 'ko', 'cn']
+export const defaultLocale = 'en'
+export const hreflangOfLocale = { en: 'en', tw: 'zh-TW', ja: 'ja', ko: 'ko', cn: 'zh-CN' }
+export const nameOfLocale = { en: 'English', tw: '繁體中文（台灣）', ja: '日本語', ko: '한국어', cn: '简体中文' }
+/** Only first-party page links inherit the reader's language across sites. */
+export const localizableOrigins = {
+  'https://master.co': ['blog', 'brand', 'design-system'],
+  'https://css.master.co': ['guide', 'reference', 'benchmarks', 'roadmap'],
+  'https://rc.css.master.co': ['guide', 'reference', 'benchmarks', 'roadmap']
+}
+
+export function languageOf(locale) { return hreflangOfLocale[locale] ?? locale }
+
+/** UTC keeps publication dates identical in static builds and hydrated islands. */
+export function formatDate(value, locale, options = {}) {
+  return new Intl.DateTimeFormat(languageOf(locale), { year: 'numeric', month: 'long', day: 'numeric', timeZone: 'UTC', ...options }).format(new Date(value))
+}