@master/internal-site 0.0.0-stage → 0.1.0

package/src/css/NamespaceUtilityTable.astro

@@ -0,0 +1,50 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import { siteOf } from '@master/internal-site/astro/site-context'
+import { uniqueId } from '@master/internal-site/utils/unique-id'
+import InlineCode from '@master/internal-site/components/InlineCode.astro'
+import RenderNode from '@master/internal-site/components/RenderNode.astro'
+import { filterNamespaceKeys } from '@master/internal-site/css/manifest-utilities.ts'
+import type { NamespaceUtilityGroup } from '@master/internal-site/components/document-types.ts'
+
+export type { NamespaceUtilityGroup } from '@master/internal-site/components/document-types.ts'
+
+interface Props {
+  groups: NamespaceUtilityGroup[]
+}
+
+const { t } = siteOf(Astro)
+const captionId = uniqueId(Astro, 'namespace-utility-table')
+const groups = Astro.props.groups
+  .map((group) => ({
+    ...group,
+    keys: filterNamespaceKeys(group)
+  }))
+  .filter((group) => group.keys.length)
+const hasDescriptions = groups.some((group) => group.description)
+---
+
+{/* The table's narrow overflow region must be focusable for native keyboard scrolling. */}
+<div class="ui-table" role="region" aria-labelledby={captionId} tabindex="0">
+  <table>
+    <caption id={captionId} class="sr-only">{t('Utility groups table')}</caption>
+    <thead>
+      <tr>
+        <th scope="col">{t('Group')}</th>
+        <th scope="col">{t('Utility keys')}</th>
+        {hasDescriptions && <th scope="col">{t('Description')}</th>}
+      </tr>
+    </thead>
+    <tbody>
+      {
+        groups.map((group) => (
+          <tr>
+            <th scope="row">{t(group.label)}</th>
+            <td>{group.keys.map((key, index) => <span><InlineCode code={key} />{index !== group.keys.length - 1 && ', '}</span>)}</td>
+            {hasDescriptions && <td>{typeof group.description === 'string' ? t(group.description) : <RenderNode node={group.description} />}</td>}
+          </tr>
+        ))
+      }
+    </tbody>
+  </table>
+</div>

package/src/css/StylesheetExample.astro

@@ -0,0 +1,15 @@
+---
+import DocumentCodeExample from '@master/internal-site/components/DocumentCodeExample.astro'
+import { stylesheetExampleCSS } from '@master/internal-site/css/stylesheet-example.ts'
+
+interface Props {
+  title: string
+  source: string
+}
+
+/** Server-only: source and its complete compiled CSS, without a simulated preview. */
+const { title, source } = Astro.props
+const css = await stylesheetExampleCSS(source)
+---
+
+<DocumentCodeExample title={title} language="css" source={source} result={css} resultKind="generated-css" />

package/src/css/ThemeNumberVariableTable.astro

@@ -0,0 +1,57 @@
+---
+import '@master/internal-site/styles/system/data.css'
+import { siteOf } from '@master/internal-site/astro/site-context'
+import { uniqueId } from '@master/internal-site/utils/unique-id'
+import InlineCode from '@master/internal-site/components/InlineCode.astro'
+import { getThemeNumericVariableEntries } from '@master/internal-site/css/theme-variables.ts'
+
+interface Props {
+  namespace: string
+  keys?: string[]
+  variablePrefix?: string
+  descriptions?: Record<string, string>
+  representation?: 'spacing'
+  referenceUnits?: boolean
+}
+
+const formatRem = (value: number) => `${Number(value.toFixed(4))}rem`
+const formatPx = (value: number) => `${Number(value.toFixed(4))}px`
+
+const { t } = siteOf(Astro)
+const captionId = uniqueId(Astro, 'theme-number-variable-table')
+const { namespace, variablePrefix = namespace, descriptions, representation, referenceUnits = true } = Astro.props
+const entries = getThemeNumericVariableEntries(namespace).filter(entry => !Astro.props.keys || Astro.props.keys.includes(entry.key))
+const hasDescriptions = descriptions && entries.some(({ key }) => descriptions[key])
+const hasSpacingRepresentation = representation === 'spacing'
+const referenceUnit = entries.every(({ unit }) => unit === 'rem') ? 'px' : 'rem'
+---
+
+{/* Numeric tables scroll within the document column and need native keyboard access. */}
+<div class="ui-table" role="region" aria-labelledby={captionId} tabindex="0">
+  <table>
+    <caption id={captionId} class="sr-only">{t(namespace === 'breakpoint' ? 'Viewport breakpoints' : 'Numeric theme variables')}</caption>
+    <thead>
+      <tr>
+        <th scope="col">{t(namespace === 'breakpoint' ? 'Query' : 'Token')}</th>
+        <th scope="col">{t(namespace === 'breakpoint' ? 'Minimum width' : 'Value')}</th>
+        {referenceUnits && <th scope="col" data-align="end">{referenceUnit}</th>}
+        {hasSpacingRepresentation && <th scope="col">{t('Representation')}</th>}
+        {hasDescriptions && <th scope="col" class="(min-width:12rem)">{t('Description')}</th>}
+      </tr>
+    </thead>
+    <tbody>
+      {
+        entries.map((entry) => (
+          <tr>
+            <th scope="row"><InlineCode code={namespace === 'breakpoint' ? `@${entry.key}` : `--${variablePrefix}-${entry.key}`} /></th>
+            <td><InlineCode code={entry.value} /></td>
+            {referenceUnits && <td data-align="end">{referenceUnit === 'px' ? formatPx(entry.px) : formatRem(entry.rem)}</td>}
+            {/* The hatched width is the measured space itself. */}
+            {hasSpacingRepresentation && <td><span aria-hidden="true" class="ui-preview" style={{ width: entry.value, background: 'var(--ui-hatch)' }} /></td>}
+            {hasDescriptions && <td>{t(descriptions?.[entry.key])}</td>}
+          </tr>
+        ))
+      }
+    </tbody>
+  </table>
+</div>

package/src/css/configured-example.ts

@@ -0,0 +1,53 @@
+import { compileManifestSync } from '@master/css-compiler/node'
+import { createRenderSessionSync } from '@master/css/node'
+import { cssSyntaxStatus, validateRuleDeclarations } from '@master/css-tooling/validator'
+import preset from '@master/internal-site/css/preset-manifest.ts'
+
+/** Only site-authored literal HTML is accepted by the configured preview components. */
+export function configuredMarkupClasses(html: string) {
+  return [...new Set([...html.matchAll(/\bclass="([^"]*)"/g)].flatMap(match => match[1].split(/\s+/)).filter(Boolean))]
+}
+
+export function configuredMarkupMarkdown(source: string, html: string, css = configuredExampleCSS(source, configuredMarkupClasses(html))) {
+  return `${source.trim() ? `\`\`\`css\n${source}\n\`\`\`\n\n` : ''}\`\`\`html\n${html}\n\`\`\`\n\n\`\`\`css disclosure=generated-css\n${css}\n\`\`\``
+}
+
+export function configuredExampleHTML(classes: string[], element: 'div' | 'button' = 'div', label = 'Example') {
+  return `<${element}${element === 'button' ? ' type="button"' : ''} class="${classes.join(' ')}">${label}</${element}>`
+}
+
+// Pages and generated content repeat the same configurations; each compile costs tens of milliseconds.
+const configurations = new Map<string, ReturnType<typeof compileManifestSync>>()
+const examples = new Map<string, string>()
+
+function compileConfiguration(source: string) {
+  let result = configurations.get(source)
+  if (result) return result
+  result = compileManifestSync(source, { baseManifest: preset })
+  const errors = result.diagnostics.filter(diagnostic => diagnostic.severity === 'error')
+  if (errors.length) throw new Error(`Invalid documentation configuration: ${JSON.stringify(errors)}`)
+  configurations.set(source, result)
+  return result
+}
+
+/** Compile the complete configuration before validating any class that depends on it. */
+export function configuredExampleCSS(source: string, classes: string[]) {
+  const key = JSON.stringify([source, classes])
+  const cached = examples.get(key)
+  if (cached !== undefined) return cached
+  const result = compileConfiguration(source)
+  const engine = createRenderSessionSync({ manifest: result.manifest })
+  try {
+    engine.ensureStylesheetResources(result.css)
+    const snapshot = engine.ensureClassRules(classes)
+    for (const className of classes) {
+      if (!result.nativeClassNames.includes(className) && (snapshot.invalidClassNames.includes(className) || snapshot.classRules[className].some(rule => cssSyntaxStatus(rule.text) === 'invalid' || validateRuleDeclarations(rule.text).some(declaration => declaration.status === 'invalid')))) {
+        throw new Error(`Invalid configured documentation class: ${className}`)
+      }
+    }
+    // Resource registration retains dependencies; the compiler owns the native rules.
+    const css = [result.css, snapshot.cssText].filter(Boolean).join('\n\n')
+    examples.set(key, css)
+    return css
+  } finally { engine.dispose() }
+}

package/src/css/foundation-data/elevation/shadow-data.ts

@@ -0,0 +1,52 @@
+import { getThemeVariables } from '@master/internal-site/css/theme-variables.ts'
+
+const shadowRoles: Record<string, { utility: string, role: string, description: string }> = {
+  xs: {
+    utility: 'shadow-xs',
+    role: 'Quiet separation',
+    description: 'Small controls, table rows, and subtle raised states.'
+  },
+  sm: {
+    utility: 'shadow-sm',
+    role: 'Standard surface',
+    description: 'Cards, reusable panels, and quiet product surfaces.'
+  },
+  md: {
+    utility: 'shadow-md',
+    role: 'Temporary lift',
+    description: 'Hover lift, floating toolbars, and command surfaces.'
+  },
+  lg: {
+    utility: 'shadow-lg',
+    role: 'Detached overlay',
+    description: 'Dropdowns, popovers, toasts, and menus.'
+  },
+  xl: {
+    utility: 'shadow-xl',
+    role: 'Workflow interruption',
+    description: 'Drawers, dialogs, and focused panels.'
+  },
+  '2xl': {
+    utility: 'shadow-2xl',
+    role: 'Blocking layer',
+    description: 'Modals and spotlight surfaces above a dimmed page.'
+  },
+  inset: {
+    utility: 'shadow-inset',
+    role: 'Sunken well',
+    description: 'Inputs, tracks, pressed states, and recessed wells.'
+  }
+}
+
+export function getShadowRows() {
+  return getThemeVariables('shadow').flatMap(({ key }) => {
+    const role = shadowRoles[key]
+    if (!role) return []
+
+    return [{
+      key,
+      token: `--shadow-${key}`,
+      ...role
+    }]
+  })
+}

package/src/css/foundation-data/sizing/scale-data.ts

@@ -0,0 +1,37 @@
+export const sizingRoles = [
+  {
+    utility: 'w-<token>, width:<value>',
+    role: 'Physical width',
+    description: 'Set the width of wrappers, columns, panels, media, and proportional regions.'
+  },
+  {
+    utility: 'h-<token>, height:<value>',
+    role: 'Physical height',
+    description: 'Set the height of fixed regions, viewport sections, media slots, and controls.'
+  },
+  {
+    utility: '(width:*), (height:*)',
+    role: 'Equal axes',
+    description: 'Set both dimensions explicitly when the element is square by design.'
+  },
+  {
+    utility: 'min-w-<token>, min-h-<token>',
+    role: 'Lower bound',
+    description: 'Prevent collapse, allow flex children to shrink, or set a minimum usable region.'
+  },
+  {
+    utility: 'max-w-<token>, max-h-<token>',
+    role: 'Upper bound',
+    description: 'Cap growth for page wrappers, readable measures, panels, menus, and media.'
+  },
+  {
+    utility: '(flex-basis:*)',
+    role: 'Flex starting size',
+    description: 'Give flex items a shared starting main-axis size before free space is distributed.'
+  },
+  {
+    utility: '@sm, @container(...)',
+    role: 'Sizing boundary',
+    description: 'Change sizing at the viewport or component container that owns the decision.'
+  }
+]

package/src/css/foundation-data/specimen-content.ts

@@ -0,0 +1,10 @@
+import { foundationScene, specimenTokens, tokenAdvice } from '@master/internal-site/css/foundation-data/specimens.ts'
+import { configuredMarkupMarkdown } from '@master/internal-site/css/configured-example.ts'
+
+export function specimenFactsMarkdown(namespace: string, keys?: string[]) {
+  return specimenTokens(namespace, keys).map(token => `- \`--${token.name}\`: ${token.values.map(value => `\`${value.value}\` (${value.path.join(' → ')})`).join('; ')}${tokenAdvice(namespace, token.key) ? ` — ${tokenAdvice(namespace, token.key)}` : ''}`).join('\n')
+}
+export function selectedSpecimensMarkdown(namespace: string, keys: string[]) {
+  const scene = foundationScene(namespace, keys)
+  return `${scene.caption}\n\n${specimenFactsMarkdown(namespace, keys)}${scene.html && namespace !== 'color' ? `\n\n${configuredMarkupMarkdown(scene.css ?? '', scene.html)}` : ''}`
+}

package/src/css/foundation-data/specimens.ts

@@ -0,0 +1,96 @@
+import { namespaceTokens, selectFoundationTokens } from '@master/internal-site/css/foundation-data/tokens.ts'
+import { getShadowRows } from '@master/internal-site/css/foundation-data/elevation/shadow-data.ts'
+import { escape } from '@master/internal-site/demo/reference/html.ts'
+import type { DemoScene } from '@master/internal-site/demo/reference/types.ts'
+
+export type FoundationToken = ReturnType<typeof namespaceTokens>[number]
+export function specimenTokens(namespace: string, keys?: string[]) {
+  return keys ? selectFoundationTokens(namespace, keys) : namespaceTokens(namespace)
+}
+export const defaultValue = (token: FoundationToken) => token.values.find(value => value.path.length === 1 && value.path[0] === ':root,:host')?.value ?? token.values[0]?.value ?? ''
+export const primaryTokens = (tokens: FoundationToken[]) => tokens.filter(token => !token.key.includes('--'))
+export function tokenClass(namespace: string, key: string) {
+  const prefixes: Record<string, string> = { color: 'bg', 'color-surface': 'bg-surface', 'color-line': 'b-line', 'color-text': 'fg-text', radius: 'r', spacing: 'gap', container: 'max-w', 'font-family': 'font', 'font-size': 'font', 'font-weight': 'font', duration: 'animation', easing: 'animation' }
+  return `${prefixes[namespace] ?? namespace}-${key}`
+}
+const descriptions: Record<string, Record<string, string>> = {
+  'color-surface': { base: 'Root page or app background.', inset: 'Recessed regions and inset sections.', raised: 'Raised cards, controls, and stacked surfaces.', floating: 'Floating dialogs, popovers, and menus.', inverse: 'High-contrast inverse surfaces.' },
+  'color-line': { divider: 'Decorative dividers; not required control boundaries.', control: 'Required control boundaries on opaque preset surfaces.', subtle: 'Low-contrast hairlines and soft outlines.' },
+  'color-text': { body: 'Default readable foreground text.', strong: 'Headings, labels, and emphasized text.', muted: 'Secondary text on base, inset, or raised; use body on floating.', disabled: 'Unavailable actions and disabled controls.', inverse: 'Text on inverse surfaces.', link: 'Default inline links.', 'link-hover': 'Interactive link hover state.' },
+}
+export function tokenAdvice(namespace: string, key: string) {
+  if (namespace === 'shadow') { const row = getShadowRows().find(row => row.key === key); return row ? `${row.role}. ${row.description}` : '' }
+  return descriptions[namespace]?.[key] ?? (namespace === 'color-text' ? `Mode-aware ${key} foreground text.` : namespace === 'color' ? `${key} color; inspect the authored value and scope below.` : '')
+}
+export const specimenCaption: Record<string, string> = {
+  color: 'Numbered palette steps keep their colors across light and dark modes. Choose a swatch to copy its original CSS value or variable reference.',
+  'color-surface': 'Compare complete surfaces in light and dark. Inverse surfaces use inverse text. Role descriptions are design guidance, not component restrictions.',
+  'color-line': 'Each token paints a boundary, with identical line width in both modes. Divider and subtle are decorative; control is intended for required boundaries.',
+  'color-text': 'Each token paints real text, on its intended surface, in both modes. Check contrast in your actual composition.',
+  radius: 'The highlighted corner shows the radius on equal-sized shapes.',
+  shadow: 'The same raised surface, radius and padding at every level. The full shadow has room to spread. Suggested uses are design guidance.',
+  spacing: 'Pink stripes show the actual gap between equal blocks. Pixel equivalents assume a 16px root; authored rem values follow the root font size.',
+  container: 'Bars show relative width caps on one shared scale. Exact values remain in the table; changing a size token does not change a container-query threshold.',
+  'font-size': 'Actual preset font sizes, without scaling or fixed-height clipping. Large specimens wrap within the reading column.',
+  text: 'Each treatment applies its actual size, line height and tracking. Weight, family and color are separate choices.',
+  'font-family': 'Compare the same sentence and letterforms in each font stack. Available system fonts determine the rendered face.',
+  'font-weight': 'Identical text, size and family isolate the selected weight. The available font determines which weights it can draw.',
+  leading: 'The same multi-line paragraph at every line height. Compare reading rhythm and block height.',
+  tracking: 'The same long phrase at every letter spacing. Compare the space between glyphs without changing size.',
+  animate: 'Every animation specimen starts paused. Play, Pause and Replay control the native timelines; reduced motion keeps the content still. Complete shorthand values are listed below.',
+  duration: 'All markers travel the same path with linear timing; only duration changes. Start paused, then Play or Replay together. Reduced motion keeps them still.',
+  easing: 'All markers travel the same path over one second; only timing changes. Overshoot and rewind may pass the endpoints. Reduced motion keeps them still.',
+}
+const label = (namespace: string, token: FoundationToken) => namespace === 'shadow'
+  ? `<div data-ui="label"><code>${escape(tokenClass(namespace, token.key))}</code><span class="sr-only"> · --${escape(token.name)}</span></div>`
+  : `<div data-ui="label"><code>${escape(tokenClass(namespace, token.key))}</code> · <code>--${escape(token.name)}</code>${['color', 'color-line', 'color-surface', 'color-text'].includes(namespace) ? '' : ` · ${escape(defaultValue(token))}`}</div>`
+const paragraph = 'Good typography makes room for the reader. A comfortable measure and a steady rhythm help the eye move from one line to the next, keeping the focus on the ideas rather than the interface.'
+
+/** Site-authored presentation only. Classes and var() references are resolved by the public compiler. */
+export function foundationScene(namespace: string, selected?: string[]): DemoScene {
+  const tokens = primaryTokens(specimenTokens(namespace, selected))
+  const caption = specimenCaption[namespace]
+  const scene: DemoScene = { html: '', caption, sizing: 'content', bodyClass: 'bg-surface-base fg-text-body', css: '' }
+  if (namespace === 'color') {
+    if (tokens.every(token => !/-\d+$/.test(token.key))) scene.caption = 'General hue aliases keep a fixed swatch in both modes. Native values such as currentColor and transparent keep their CSS meaning.'
+    scene.html = `<div data-foundation="colors">${tokens.map(token => `<section>${label(namespace, token)}<div data-color-swatch role="img" class="bg-${token.key}" aria-label="${escape(token.key)} swatch"></div><p data-ui="label">${escape(defaultValue(token))}</p></section>`).join('')}</div>`
+    scene.css = '[data-foundation="colors"] { display:grid; grid-template-columns:repeat(auto-fit,minmax(min(100%,140px),1fr)); gap:24px; } [data-color-swatch] { height:64px; border-radius:var(--radius-sm); outline:1px solid var(--color-line-divider); outline-offset:-1px; }'
+  } else if (namespace.startsWith('color-')) {
+    scene.html = `<div data-foundation="roles">${tokens.map(token => {
+      const advice = tokenAdvice(namespace, token.key)
+      const utility = tokenClass(namespace, token.key)
+      const inverse = token.key === 'inverse'
+      const preview = namespace === 'color-text'
+        ? `<div class="p-lg r-sm ${inverse ? 'bg-surface-inverse' : 'bg-surface-raised'}"><p data-role-preview="text" class="m(0) text-xl font-medium ${utility}">The details make the difference.</p><p class="m(0) text-sm ${utility}">0123456789 · ${escape(token.key)}</p></div>`
+        : namespace === 'color-line'
+          ? `<div data-role-preview="line" class="p-lg r-sm b(1) b-solid bg-surface-raised ${utility}"><span class="text-sm">${escape(token.key === 'control' ? 'Email address' : 'Collection details')}</span><div class="mt-md bt(1) bt-solid ${utility}"></div></div>`
+          : `<div data-role-preview="surface" class="p-lg r-sm ${utility} ${inverse ? 'fg-text-inverse' : 'fg-text-body'}"><strong class="text-md">${escape(token.key)}</strong><p class="m(0) text-sm">A surface for your content.</p></div>`
+      return `<section>${label(namespace, token)}${preview}<p data-ui="label">${escape(advice)}</p></section>`
+    }).join('')}</div>`
+    scene.css = '[data-foundation="roles"] { display:grid; grid-template-columns:minmax(0,1fr); gap:24px; overflow-wrap:anywhere; }'
+  } else if (namespace === 'radius') {
+    scene.html = `<div data-foundation="radius">${tokens.map(token => `<section><div data-ui="label"><code>r-${escape(token.key)}</code></div><div data-radius-shape class="r-${token.key}"></div><div data-ui="label"><code>${escape(defaultValue(token))}</code></div><span class="sr-only">--${escape(token.name)}</span></section>`).join('')}</div>`
+    scene.css = 'body { padding:32px 24px; } [data-foundation="radius"] { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:32px 20px; } @media (min-width:528px) { [data-foundation="radius"] { grid-template-columns:repeat(4,minmax(0,1fr)); } } [data-foundation="radius"] section { display:grid; align-content:start; justify-items:start; gap:12px; } [data-foundation="radius"] [data-ui="label"] { margin:0; font-size:12px; } [data-radius-shape] { position:relative; width:76px; height:76px; border:4px solid var(--color-line-divider); } [data-radius-shape]::after { content:""; position:absolute; inset:-4px; border:4px solid var(--color-text-pink); border-radius:inherit; mask-image:conic-gradient(black 0deg 90deg,transparent 90deg 360deg); }'
+  } else if (namespace === 'shadow') {
+    scene.html = `<div data-foundation="shadow">${tokens.map(token => `<section>${label(namespace, token)}<article data-shadow-card class="p-lg r-lg bg-surface-raised shadow-${token.key}"><div class="text-md font-medium fg-text-strong">${escape(getShadowRows().find(row => row.key === token.key)?.role ?? token.key)}</div><p class="mt-xs mb(0) text-sm fg-text-muted">${escape(getShadowRows().find(row => row.key === token.key)?.description ?? '')}</p></article></section>`).join('')}</div>`
+    scene.css = 'body { padding:32px 32px 64px; } [data-foundation="shadow"] { display:grid; grid-template-columns:repeat(auto-fit,minmax(min(100%,192px),1fr)); gap:48px 40px; } [data-shadow-card] { min-height:144px; } [data-foundation="shadow"] [data-ui="label"] { font-size:12px; }'
+  } else if (['font-family', 'font-size', 'font-weight', 'text', 'leading', 'tracking'].includes(namespace)) {
+    scene.html = `<div data-foundation="typography">${tokens.map(token => {
+      const utility = tokenClass(namespace, token.key)
+      const text = namespace === 'leading' ? paragraph : namespace === 'font-family' ? 'The quick brown fox jumps over the lazy dog. 0123456789' : ['font-size', 'text'].includes(namespace) ? 'Design for people.' : namespace === 'tracking' ? 'Make space for extraordinary ideas.' : 'A thoughtful balance. Aa 0123456789'
+      return `<section>${label(namespace, token)}<p data-type-target class="m(0) ${['font-size', 'text', 'leading'].includes(namespace) ? '' : 'font-xl'} ${utility}">${text}</p></section>`
+    }).join('')}</div>`
+    scene.css = '[data-foundation="typography"] { display:grid; gap:32px; } [data-foundation="typography"] > section + section { border-top:1px solid var(--color-line-divider); padding-top:24px; } [data-type-target] { overflow-wrap:anywhere; }'
+    if (namespace === 'leading') scene.css += ' [data-type-target] { max-width:38ch; font-size:16px; }'
+  } else if (['animate', 'duration', 'easing'].includes(namespace)) {
+    scene.motion = true
+    scene.html = `<div data-foundation="motion">${tokens.map(token => `<section>${label(namespace, token)}<div data-motion-path><div id="motion-${token.key}" data-motion-marker class="bg-blue-60 r-sm ${namespace === 'animate' ? `animate-${token.key}@motion-safe (animation-iteration-count:1)@motion-safe` : `(animation-name:foundation-travel)@motion-safe (animation-duration:${namespace === 'duration' ? `var(--${token.name})` : '1s'}) (animation-timing-function:${namespace === 'easing' ? `var(--${token.name})` : 'linear'}) (animation-fill-mode:both)`}">${namespace === 'animate' ? 'M' : '→'}</div></div><output data-ui="label" data-animation-readout="motion-${token.key}">Paused</output></section>`).join('')}</div>`
+    scene.css = '@keyframes foundation-travel { from { left:0; } to { left:calc(100% - 40px); } } [data-foundation="motion"] { display:grid; gap:24px; } [data-motion-path] { position:relative; height:64px; margin:12px 24px; border-bottom:1px dashed var(--color-line-divider); } [data-motion-marker] { position:relative; display:grid; place-items:center; width:40px; height:40px; color:white; } @media(prefers-reduced-motion:reduce) { [data-motion-marker] { animation:none!important; } }'
+  } else if (namespace === 'container') {
+    const max = Math.max(...tokens.map(token => token.numeric?.value ?? 0))
+    scene.html = tokens.map(token => `<section>${label(namespace, token)}<div data-size-bar style="width:${(token.numeric?.value ?? 0) / max * 100}%" class="bg-blue-60 r-xs"></div></section>`).join('')
+    scene.css = '[data-size-bar] { height:16px; margin-bottom:24px; }'
+  }
+  if (namespace === 'radius' || namespace === 'shadow') scene.css += ' body { background-image:linear-gradient(135deg,var(--color-line-subtle) 4.5%,transparent 0,transparent 50%,var(--color-line-subtle) 0,var(--color-line-subtle) 54.5%,transparent 0); background-size:7.5px 7.5px; }'
+  return scene
+}

package/src/css/foundation-data/tokens.ts

@@ -0,0 +1,32 @@
+import { flattenMasterCSSManifestVariables } from '@master/css-schema/manifest'
+import { tokenFamilies } from '@master/internal-site/css/manifest-utilities.ts'
+import preset from '@master/internal-site/css/preset-manifest.ts'
+
+/** Authored facts only: scope/dependency resolution remains owned by the engine. */
+export const foundationTokens = flattenMasterCSSManifestVariables(preset.variables)
+export const foundationFamilies = tokenFamilies
+export function namespaceTokens(namespace: string) {
+  return foundationTokens.filter(token => token.namespace === namespace)
+}
+
+/** The Guide's visual palette and its portable export use the same fixed steps. */
+export const paletteKeys = namespaceTokens('color').filter(token => /^.+-\d+$/.test(token.key)).map(token => token.key)
+export function namespaceFamilies(namespace: string) {
+  return foundationFamilies.filter(family => family.namespaces.includes(namespace.startsWith('color-') ? 'color' : namespace))
+}
+export function selectFoundationTokens(namespace: string, keys: string[]) {
+  const entries = namespaceTokens(namespace)
+  return keys.map(key => {
+    const token = entries.find(token => token.key === key)
+    if (!token) throw new Error(`Unknown ${namespace} token: ${key}`)
+    return token
+  })
+}
+
+/** Presentation choices only; token values and output semantics remain source-owned. */
+export const tokenSpecimenProperties: Record<string, string> = {
+  radius: 'borderRadius', shadow: 'boxShadow', 'font-family': 'fontFamily',
+  'font-size': 'fontSize', 'font-weight': 'fontWeight', leading: 'lineHeight', tracking: 'letterSpacing', text: 'fontSize',
+}
+export const hasTokenSpecimens = (namespace: string) => namespace.startsWith('color') || Object.hasOwn(tokenSpecimenProperties, namespace)
+  || ['spacing', 'container', 'animate', 'duration', 'easing'].includes(namespace)

package/src/css/generate-preset-css.ts

@@ -0,0 +1,12 @@
+import { createPresetEngine } from '@master/internal-site/css/preset-css.ts'
+
+const engine = createPresetEngine()
+
+export function generatePresetCSS(classNames: readonly string[]): string {
+  try {
+    engine.ensureClassRules(classNames)
+    return engine.snapshot().text
+  } finally {
+    engine.deleteClassRules(classNames)
+  }
+}

package/src/css/highlight.ts

@@ -0,0 +1,34 @@
+import type { LanguageRegistration, ShikiTransformer } from 'shiki/core'
+import {
+  getMasterCSSShikiLanguageId,
+  isMasterCSSClassListLanguage,
+  isMasterCSSShikiSupportedLanguage,
+  type MasterCSSShikiOptions,
+  transformerMasterCSS,
+} from '@master/css-language-service/shiki'
+import { createLanguageSessionSync, type MasterCSSLanguageSession } from '@master/css-tooling/language/node'
+import defaultManifest from '@master/css-preset/default-manifest.json' with { type: 'json' }
+import grammar from '@master/css-language-service/syntaxes/master-css.tmLanguage.json' with { type: 'json' }
+import type { MasterCSSManifest } from '@master/css-schema/manifest'
+import { createCodeHighlighter } from '@master/internal-site/utils/highlight-code-core'
+import { cssInjectionHosts } from '@master/internal-site/utils/css-modern-grammar'
+
+const sessions = new WeakMap<MasterCSSManifest, MasterCSSLanguageSession>()
+
+export default createCodeHighlighter({
+  languages: [{ ...(grammar as unknown as LanguageRegistration), injectTo: cssInjectionHosts }],
+  resolveLanguage: language => isMasterCSSClassListLanguage(language) ? 'plaintext' : getMasterCSSShikiLanguageId(language) ?? language,
+  transformers(language, options) {
+    const classList = isMasterCSSClassListLanguage(language)
+    if (!classList && !isMasterCSSShikiSupportedLanguage(language)) return []
+    const settings = options.masterCSS as MasterCSSShikiOptions | undefined
+    const manifest = settings?.manifest ?? settings?.settings?.manifest ?? defaultManifest as MasterCSSManifest
+    let session = settings?.session ?? sessions.get(manifest)
+    if (!session) {
+      const created = createLanguageSessionSync({ manifest })
+      sessions.set(manifest, created)
+      session = created
+    }
+    return [transformerMasterCSS({ ...settings, session, classList }) as unknown as ShikiTransformer]
+  },
+})

package/src/css/manifest-utilities.ts

@@ -0,0 +1,29 @@
+import type { MasterCSSTokenFamily } from '@master/css-tooling/language'
+import { createToolingSessionSync } from '@master/css-tooling/node'
+import preset from './preset-manifest'
+
+const session = createToolingSessionSync({ manifest: preset })
+const catalog = (() => { try { return session.tokenFamilies() } finally { session.dispose() } })()
+
+/** Build-time Rust analysis; client code only reads serializable display facts. */
+export const tokenFamilies = (catalog.families as MasterCSSTokenFamily[]).map(family => ({
+  ...family,
+  property: family.properties.join(', '),
+  namespaces: [family.namespace]
+}))
+
+export function getVariableNamespacePublicKeys(namespace: string) {
+  return tokenFamilies.filter(family => family.namespace === namespace).map(family => family.prefix).sort()
+}
+
+export function getTokenNamespacePublicKeys(namespace: string) {
+  return tokenFamilies.filter(family => family.argument === 'value' && family.namespace === namespace).map(family => family.prefix).sort()
+}
+
+/** Keep curated documentation groups aligned with the loaded namespace consumers. */
+export function filterNamespaceKeys(group: { keys: string[], namespace?: string, namespaces?: string[] }) {
+  const namespaces = group.namespaces || (group.namespace ? [group.namespace] : [])
+  if (!namespaces.length) return group.keys
+  const keys = new Set(namespaces.flatMap(getVariableNamespacePublicKeys))
+  return group.keys.filter(key => keys.has(key))
+}