@master/internal-site 0.0.0-stage → 0.1.1

package/src/demo/foundations/FoundationPalette.astro

@@ -0,0 +1,8 @@
+---
+import { paletteKeys } from '@master/internal-site/css/foundation-data/tokens.ts'
+import FoundationTokensView from '@master/internal-site/demo/foundations/FoundationTokensView.astro'
+
+/** The full palette is the comparison: keep it beside the color lesson. */
+---
+
+<FoundationTokensView namespace="color" keys={paletteKeys} presentation="guide" />

package/src/demo/foundations/FoundationRadius.astro

@@ -0,0 +1,13 @@
+---
+import Demo from '@master/internal-site/demo/Demo.svelte'
+import DemoItem from '@master/internal-site/demo/DemoItem.svelte'
+import DemoLabel from '@master/internal-site/demo/DemoLabel.svelte'
+---
+
+<Demo title="One scale, related surfaces" data-foundation="radius">
+  <div class="grid-cols(3) gap-sm w-full">
+    <div><DemoLabel>r-sm</DemoLabel><DemoItem class="grid (place-content:center) (height:5rem) mt-sm r-sm text-sm">Control</DemoItem></div>
+    <div><DemoLabel>r-lg</DemoLabel><DemoItem class="grid (place-content:center) (height:5rem) mt-sm r-lg text-sm">Panel</DemoItem></div>
+    <div><DemoLabel>r-2xl</DemoLabel><DemoItem class="grid (place-content:center) (height:5rem) mt-sm r-2xl text-sm">Feature</DemoItem></div>
+  </div>
+</Demo>

package/src/demo/foundations/FoundationShapes.astro

@@ -0,0 +1,12 @@
+---
+import IconArrowUp from '@tabler/icons-svelte-runes/icons/arrow-up'
+import Demo from '@master/internal-site/demo/Demo.svelte'
+import DemoLabel from '@master/internal-site/demo/DemoLabel.svelte'
+---
+
+<Demo title="Content-sized pill and width-led circle" data-foundation="shapes" caption="These links share a destination. Their shape is independent of their native navigation behavior.">
+  <div class="flex flex-wrap items-end gap-lg">
+    <div><DemoLabel>pill</DemoLabel><div class="mt-sm"><a href="#use-shape-shortcuts" class="inline-flex items-center justify-center min-h(44) py-sm px-md pill b-solid b(1) b-line-divider text-sm (text-decoration:none) bg-surface-raised fg-text-body">Pills and circles</a></div></div>
+    <div><DemoLabel>w(48) (aspect-ratio:1/1) pill</DemoLabel><div class="mt-sm"><a href="#use-shape-shortcuts" aria-label="Pills and circles" class="inline-flex items-center justify-center w(48) (aspect-ratio:1/1) pill b-solid b(1) b-line-divider bg-surface-raised fg-text-blue"><IconArrowUp size={20} aria-hidden="true" /></a></div></div>
+  </div>
+</Demo>

package/src/demo/foundations/FoundationShrink.astro

@@ -0,0 +1,14 @@
+---
+import DemoContainer from '@master/internal-site/demo/DemoContainer.svelte'
+import DemoItem from '@master/internal-site/demo/DemoItem.svelte'
+---
+
+<DemoContainer client:idle={{ timeout: 500 }} title="Keep long content within its cap" data-foundation="shrink" caption="The row stops at sm. The flexible text region can shrink below its content width.">
+    <article class="flex gap-md w-full max-w-sm mx-auto p-md ui-sheet" data-elevation="1">
+      <DemoItem class="grid shrink(0) (place-content:center) (height:2.5rem) (width:2.5rem) text-sm font-mono">FN</DemoItem>
+      <div class="(flex:1) min-w(0)">
+        <div class="text-sm font-semibold">Project archive</div>
+        <p class="truncate mb(0) mx(0) mt-2xs text-sm fg-text-muted">field-notes-autumn-collection-final-v03.fig</p>
+      </div>
+    </article>
+</DemoContainer>

package/src/demo/foundations/FoundationSizing.astro

@@ -0,0 +1,19 @@
+---
+import Demo from '@master/internal-site/demo/Demo.svelte'
+import DemoItem from '@master/internal-site/demo/DemoItem.svelte'
+import DemoLabel from '@master/internal-site/demo/DemoLabel.svelte'
+import DemoSurface from '@master/internal-site/demo/DemoSurface.svelte'
+---
+
+<Demo title="Fluid space, measured object" data-foundation="sizing">
+  <DemoSurface class="w-full max-w-sm mx-auto p-md">
+    <DemoLabel>w-full · max-w-sm</DemoLabel>
+    <div class="flex items-center gap-md mt-md">
+      <DemoItem class="grid shrink(0) (place-content:center) (height:var(--spacing-2xl)) (width:var(--spacing-2xl)) (aspect-ratio:1/1) pill text-sm font-mono">FN</DemoItem>
+      <div class="wrap-anywhere (flex:1) min-w(0)">
+        <div class="text-sm font-semibold">Field notes</div>
+        <p class="mb(0) mx(0) mt-2xs text-sm fg-text-muted">Measured avatar. Flexible content.</p>
+      </div>
+    </div>
+  </DemoSurface>
+</Demo>

package/src/demo/foundations/FoundationSpecimen.astro

@@ -0,0 +1,20 @@
+---
+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'
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+
+interface Props {
+  name: string
+  title: string
+  scene: DemoScene
+}
+
+/** One type or motion foundation in its own document. */
+const { name, title, scene } = Astro.props
+const section: ReferenceDemoSection = { page: 'foundations', id: name, title, html: [], css: '', classes: [], classLists: [], highlighted: [] }
+---
+
+<Demo title={title} frame="none" data-foundation-type-motion={name} caption={scene.caption}>
+  <DemoViewport client:idle={{ timeout: 500 }} title={title} document={demoDocument(section, scene)} sizing={scene.sizing ?? 'content'} height={scene.height} motion={scene.motion} />
+</Demo>

package/src/demo/foundations/FoundationSurfaces.astro

@@ -0,0 +1,5 @@
+---
+import DemoThemeComparison from '@master/internal-site/demo/DemoThemeComparison.astro'
+---
+
+<DemoThemeComparison name="surfaces" title="Surface hierarchy" html={"<section class=\"p-md r-lg bg-surface-inset\">\n<p class=\"mb-sm font-mono font-xs fg-text-muted\">bg-surface-inset</p>\n<article class=\"p-md r-sm b(1) b-solid b-line-divider bg-surface-raised\">\n<h2 class=\"m(0) text-md font-medium fg-text-strong\">Collection settings</h2>\n<p class=\"mt-xs mb(0) fg-text-muted\">A raised panel on a subdued section.</p>\n</article></section>"} caption="Color separates these surfaces. This example adds no shadow." />

package/src/demo/foundations/FoundationTextHue.astro

@@ -0,0 +1,5 @@
+---
+import DemoThemeComparison from '@master/internal-site/demo/DemoThemeComparison.astro'
+---
+
+<DemoThemeComparison name="text-hue" title="Foreground color by role" html={"<article class=\"p-md r-sm b(1) b-solid b-line-divider bg-surface-raised\">\n<p class=\"m(0) text-sm font-medium fg-text-blue\">Editorial notes</p>\n<h2 class=\"mt-xs mb-sm text-xl font-medium fg-text-strong\">A clearer perspective</h2>\n<p class=\"m(0) fg-text-body\">Use a colored label alongside a clear heading and readable body copy.</p>\n</article>"} caption="fg-text-blue uses the foreground-oriented alias. Check the actual foreground and surface together." />

package/src/demo/foundations/FoundationTextRoles.astro

@@ -0,0 +1,5 @@
+---
+import DemoThemeComparison from '@master/internal-site/demo/DemoThemeComparison.astro'
+---
+
+<DemoThemeComparison name="text-roles" title="Readable hierarchy" html={"<article class=\"grid gap-sm p-md r-lg b(1) b-solid b-line-divider bg-surface-raised fg-text-body\">\n<h2 class=\"m(0) text-lg font-medium fg-text-strong\">Quarterly report</h2>\n<p class=\"m(0)\">The current cycle is on track.</p>\n<p class=\"m(0) text-sm fg-text-muted\">Updated 12 minutes ago</p>\n<button type=\"button\" class=\"fg-text-disabled (cursor:not-allowed)\" disabled>Archive unavailable</button>\n<a class=\"fg-text-link fg-text-link-hover:hover underline\" href=\"/reference/tokens/color-roles#color-text\" target=\"_top\">Explore text roles</a>\n<span class=\"w-fit px-sm py-2xs r-sm bg-surface-inverse fg-text-inverse\">Private note</span>\n</article>"} caption="The archive action is natively disabled. Inverse text is paired with its inverse surface." />

package/src/demo/foundations/FoundationTokens.astro

@@ -0,0 +1,22 @@
+---
+import Code from '@master/internal-site/components/Code.astro'
+import { configuredExampleCSS, configuredMarkupClasses } from '@master/internal-site/css/configured-example.ts'
+import { foundationScene } from '@master/internal-site/css/foundation-data/specimens.ts'
+import DocumentDisclosure from '@master/internal-site/components/DocumentDisclosure.astro'
+import FoundationTokensView from '@master/internal-site/demo/foundations/FoundationTokensView.astro'
+
+interface Props {
+  namespace: string
+  keys?: string[]
+}
+
+const { namespace, keys } = Astro.props
+const scene = keys && namespace !== 'color' && namespace !== 'breakpoints' ? foundationScene(namespace, keys) : undefined
+---
+
+<FoundationTokensView namespace={namespace} keys={keys} presentation="guide">
+  {scene?.html && <DocumentDisclosure slot="source" title="Example code">
+    <Code lang="html" beautify code={scene.html} />
+    <Code lang="css" beautify code={configuredExampleCSS(scene.css ?? '', configuredMarkupClasses(scene.html))} />
+  </DocumentDisclosure>}
+</FoundationTokensView>

package/src/demo/foundations/FoundationTokensView.astro

@@ -0,0 +1,65 @@
+---
+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'
+import ThemeNumberVariableTable from '@master/internal-site/css/ThemeNumberVariableTable.astro'
+import Palette, { type PaletteGroup } from '@master/internal-site/demo/foundations/Palette.svelte'
+import { demoDocument } from '@master/internal-site/demo/reference/document.ts'
+import { defaultValue, foundationScene, specimenCaption, specimenTokens, type FoundationToken } from '@master/internal-site/css/foundation-data/specimens.ts'
+
+interface Props {
+  namespace: string
+  keys?: string[]
+  presentation?: 'guide' | 'reference'
+}
+
+/** Extra example markup, such as a source disclosure, follows the specimens in the `source` slot. */
+const { namespace, keys, presentation = 'reference' } = Astro.props
+const tokens = namespace === 'breakpoints' ? [] : specimenTokens(namespace, keys)
+const tokenKeys = tokens.map(token => token.key).join(' ')
+
+function tokenScene(tokens: FoundationToken[], title: string, compare = false) {
+  const scene = foundationScene(namespace, tokens.map(token => token.key))
+  return scene.html ? { scene, title, compare } : undefined
+}
+
+let palette: PaletteGroup[] = []
+let scenes: NonNullable<ReturnType<typeof tokenScene>>[] = []
+if (namespace === 'color') {
+  const groups = new Map<string, PaletteGroup>()
+  const rest: FoundationToken[] = []
+  for (const token of tokens) {
+    const match = token.key.match(/^(.+)-(\d+)$/)
+    if (!match) { rest.push(token); continue }
+    const [, family, step] = match
+    if (!groups.has(family)) groups.set(family, { family, colors: [] })
+    groups.get(family)!.colors.push({ name: token.name, step: Number(step), value: defaultValue(token) })
+  }
+  palette = [...groups.values()].map(group => ({ ...group, colors: group.colors.sort((a, b) => a.step - b.step) }))
+  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,
+  ].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'))
+  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>}
+    {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></>
+      : 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}>
+          <DemoViewport client:idle={{ timeout: 500 }} title={title} document={demoDocument({ page: 'tokens', id: namespace, title, html: [], css: '', classes: [], classLists: [], highlighted: [] }, scene)} sizing="content" theme={namespace === 'shadow'} motion={scene.motion} />
+        </Demo>)}
+    {namespace === 'container' && <ThemeNumberVariableTable namespace="container" keys={keys} />}
+    <slot name="source" />
+  </div>}

package/src/demo/foundations/FoundationTransition.astro

@@ -0,0 +1,5 @@
+---
+import FoundationSpecimen from '@master/internal-site/demo/foundations/FoundationSpecimen.astro'
+---
+
+<FoundationSpecimen name="state-transition" title="A transition needs two states" scene={{ html: "<label class=\"block w(280) max-w-full font-sm (transform:translateX(96px)):has(input:checked)>span>span@media(screen)\">\n<input type=\"checkbox\" class=\"mr-xs accent-blue\"> Move layer\n<span aria-hidden=\"true\" class=\"block h(64) mt-md p-xs outline(1) outline-dashed outline-line-subtle\"><span id=\"layer\" class=\"grid (place-items:center) h(48) w(128) b(1) b-solid b-blue-60 r-sm font-sm bg-blue-10 fg-blue-80 (transform:none) (transition-property:transform)@media(screen)@motion-safe (transition-duration:var(--duration-slow))@media(screen)@motion-safe (transition-timing-function:var(--easing-overshoot))@media(screen)@motion-safe (transition-delay:150ms)@media(screen)@motion-safe\">Layer 01</span></span>\n</label><div data-ui=\"type-readings\"><span>Duration <output data-style-readout=\"layer\" data-style-property=\"transition-duration\">—</output></span><span>Delay <output data-style-readout=\"layer\" data-style-property=\"transition-delay\">—</output></span></div>", caption: 'The checkbox changes translateX from 0 to 96px. The 300ms transition starts after a 150ms delay. Reduced motion changes the state immediately; print keeps the initial position.' }} />

package/src/demo/foundations/FoundationTypeComparison.astro

@@ -0,0 +1,12 @@
+---
+import FoundationSpecimen from '@master/internal-site/demo/foundations/FoundationSpecimen.astro'
+import { typeSpecimens } from '@master/internal-site/demo/reference/type-specimens.ts'
+import type { ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+
+const authored: ReferenceDemoSection = { page: 'text-size', id: 'type-comparison', title: 'Font size and text scale', css: '', classes: [], classLists: [], highlighted: [], html: [
+  "<!-- font-3xl · inherited leading and tracking -->\n<div class=\"leading-md tracking-normal wrap-anywhere\"><p id=\"target\" class=\"m(0) font-3xl font-regular\">Designing for a clearer reading experience.</p></div>",
+  "<!-- text-3xl · size, leading and tracking -->\n<div class=\"leading-md tracking-normal wrap-anywhere\"><p id=\"target\" class=\"m(0) text-3xl font-regular\">Designing for a clearer reading experience.</p></div>",
+] }
+---
+
+<FoundationSpecimen name="type-comparison" title="One size, two type treatments" scene={typeSpecimens(authored, { properties: ['font-size', 'line-height', 'letter-spacing'], appearance: 'plain', caption: 'Both specimens have the same font size and content. font-3xl inherits the parent’s leading and tracking; text-3xl sets all three properties.' })} />

package/src/demo/foundations/FoundationTypography.astro

@@ -0,0 +1,5 @@
+---
+import FoundationSpecimen from '@master/internal-site/demo/foundations/FoundationSpecimen.astro'
+---
+
+<FoundationSpecimen name="type-hierarchy" title="A readable type hierarchy" scene={{ html: "<article class=\"p-md r-sm b(1) b-solid b-line-divider bg-surface-raised fg-text-body\">\n<p class=\"m(0) text-xs font-regular fg-text-muted\">Field notes / 024</p>\n<h2 class=\"mt-xs mb-sm text-2xl font-regular fg-text-strong\">Make room for the details.</h2>\n<p class=\"m(0) text-sm\">A consistent type scale helps readers move from the main idea to the supporting detail.</p>\n<p class=\"mt-md mb(0) font-mono font-xs fg-text-muted\">4 min read · Updated today</p>\n</article>", caption: 'Size, spacing and text roles establish hierarchy with regular weight. The full body copy stays visible at every preview width.' }} />

package/src/demo/foundations/Palette.svelte

@@ -0,0 +1,37 @@
+<script module lang="ts">
+  export interface PaletteGroup { family: string; colors: { name: string; step: number; value: string }[] }
+</script>
+
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import '@master/internal-site/styles/demo.css'
+  import DemoCopyButton from '@master/internal-site/demo/DemoCopyButton.svelte'
+  import DemoCopyGroup from '@master/internal-site/demo/DemoCopyGroup.svelte'
+
+  /** Wide pages show a hue matrix; narrow pages wrap each hue into two rows. Every chip names its step. */
+  let { groups }: { groups: PaletteGroup[] } = $props()
+  let format = $state('value')
+  const id = $props.id()
+  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
+    <select {id} class="ui-select" data-variant="raised" bind:value={format}>
+      <option value="value">CSS value</option><option value="variable">CSS variable</option>
+    </select>
+  </label>
+  <a class="ui-skip" href={`#${endId}`}>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`}>
+      <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}`} />
+        <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>
+</DemoCopyGroup></div>

package/src/demo/foundations/ShadowScaleDemo.astro

@@ -0,0 +1,22 @@
+---
+import Demo from '@master/internal-site/demo/Demo.svelte'
+import DemoLabel from '@master/internal-site/demo/DemoLabel.svelte'
+
+import { getShadowRows } from '@master/internal-site/css/foundation-data/elevation/shadow-data.ts'
+
+/** Every preset shadow on the same raised surface; used by the design-system review pages. */
+---
+
+<Demo align="start">
+  <div class="container-inline w-full">
+    <div class="grid-cols(1) gap-xl w-full grid-cols(2)@container(width>=18rem)">
+      {getShadowRows().map(({ utility, role, description }) => (
+        <div class={`bg-surface-raised r-lg p-lg ${utility}`}>
+          <DemoLabel>{utility}</DemoLabel>
+          <div class="font-medium fg-text-strong">{role}</div>
+          <p class="mb(0) mx(0) mt-xs text-sm fg-text-muted">{description}</p>
+        </div>
+      ))}
+    </div>
+  </div>
+</Demo>

package/src/demo/illustration-materials.ts

@@ -0,0 +1,180 @@
+/** Illustration primitives shared by the documentation scenes, painted by the site's tokens in `illustration.css`. */
+export type Theme = 'light' | 'dark'
+
+/** The scene is drawn at the article's wide media width, so its sizes match the interface around it. */
+export const sceneWidth = 720
+export const sceneHeight = 480
+
+/** Tabler outline icons, the set the site's interface uses. */
+const icons = {
+  braces: ['M7 4a2 2 0 0 0 -2 2v3a2 3 0 0 1 -2 3a2 3 0 0 1 2 3v3a2 2 0 0 0 2 2', 'M17 4a2 2 0 0 1 2 2v3a2 3 0 0 0 2 3a2 3 0 0 0 -2 3v3a2 2 0 0 1 -2 2'],
+  check: ['M3 12a9 9 0 1 0 18 0a9 9 0 1 0 -18 0', 'M9 12l2 2l4 -4'],
+  code: ['M7 8l-4 4l4 4', 'M17 8l4 4l-4 4', 'M14 4l-4 16'],
+  compare: ['M4 6a2 2 0 1 0 4 0a2 2 0 1 0 -4 0', 'M16 18a2 2 0 1 0 4 0a2 2 0 1 0 -4 0', 'M11 6h5a2 2 0 0 1 2 2v8', 'M14 9l-3 -3l3 -3', 'M13 18h-5a2 2 0 0 1 -2 -2v-8', 'M10 15l3 3l-3 3'],
+  cpu: ['M5 6a1 1 0 0 1 1 -1h12a1 1 0 0 1 1 1v12a1 1 0 0 1 -1 1h-12a1 1 0 0 1 -1 -1l0 -12', 'M9 9h6v6h-6l0 -6', 'M3 10h2', 'M3 14h2', 'M10 3v2', 'M14 3v2', 'M21 10h-2', 'M21 14h-2', 'M14 21v-2', 'M10 21v-2'],
+  file: ['M14 3v4a1 1 0 0 0 1 1h4', 'M17 21h-10a2 2 0 0 1 -2 -2v-14a2 2 0 0 1 2 -2h7l5 5v11a2 2 0 0 1 -2 2', 'M9 17h6', 'M9 13h6'],
+  fileCode: ['M14 3v4a1 1 0 0 0 1 1h4', 'M17 21h-10a2 2 0 0 1 -2 -2v-14a2 2 0 0 1 2 -2h7l5 5v11a2 2 0 0 1 -2 2', 'M10 13l-1 2l1 2', 'M14 13l1 2l-1 2'],
+  filter: ['M4 4h16v2.172a2 2 0 0 1 -.586 1.414l-4.414 4.414v7l-6 2v-8.5l-4.48 -4.928a2 2 0 0 1 -.52 -1.345v-2.227'],
+  layers: ['M12 4l-8 4l8 4l8 -4l-8 -4', 'M4 12l8 4l8 -4', 'M4 16l8 4l8 -4'],
+  refresh: ['M20 11a8.1 8.1 0 0 0 -15.5 -2m-.5 -4v4h4', 'M4 13a8.1 8.1 0 0 0 15.5 2m.5 4v-4h-4'],
+  scan: ['M5 12h14', 'M3 7v-2a2 2 0 0 1 2 -2h2', 'M3 17v2a2 2 0 0 0 2 2h2', 'M17 3h2a2 2 0 0 1 2 2v2', 'M17 21h2a2 2 0 0 0 2 -2v-2'],
+  server: ['M3 7a3 3 0 0 1 3 -3h12a3 3 0 0 1 3 3v2a3 3 0 0 1 -3 3h-12a3 3 0 0 1 -3 -3v-2', 'M3 15a3 3 0 0 1 3 -3h12a3 3 0 0 1 3 3v2a3 3 0 0 1 -3 3h-12a3 3 0 0 1 -3 -3l0 -2', 'M7 8l0 .01', 'M7 16l0 .01'],
+  window: ['M3 7a2 2 0 0 1 2 -2h14a2 2 0 0 1 2 2v10a2 2 0 0 1 -2 2h-14a2 2 0 0 1 -2 -2v-10', 'M6 8h.01', 'M9 8h.01']
+} as const
+
+export type IconName = keyof typeof icons
+export type TextKind = 'title' | 'note' | 'body' | 'edge' | 'code' | 'eyebrow'
+type Align = 'start' | 'center' | 'end'
+type AnnotationTone = 'blue' | 'violet' | 'amber'
+
+export function escapeHtml(value: string) {
+  return value.replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]!)
+}
+
+const box = (x: number, y: number, width?: number, height?: number) =>
+  `left:${x}px;top:${y}px;${width === undefined ? '' : `width:${width}px;`}${height === undefined ? '' : `height:${height}px;`}`
+
+export function drawing(theme: Theme) {
+  const routes: string[] = []
+  const icon = (name: IconName) => `<span class="icon"><svg viewBox="0 0 24 24">${icons[name].map(d => `<path d="${d}"/>`).join('')}</svg></span>`
+  /** A label inside a sheet, chip or mark; every label carries a shared figure label. */
+  const label = (value: string, kind: TextKind = 'title') => `<span class="${kind}" data-label>${escapeHtml(value)}</span>`
+  /** A free label, its box's top edge at y, anchored at x. */
+  const text = (x: number, y: number, value: string, kind: TextKind = 'note', align: Align = 'start') =>
+    `<span class="${kind}${align === 'start' ? '' : ` ${align}`}" style="${box(x, y)}" data-label>${escapeHtml(value)}</span>`
+  const row = (content: string) => `<div class="row">${content}</div>`
+  const rule = '<div class="rule"></div>'
+  /** Placeholder lines for content the figure does not spell out, as percentages of the sheet's inner width. */
+  const bars = (...widths: number[]) => `<div class="bars">${widths.map(width => `<i style="width:${width}%"></i>`).join('')}</div>`
+  /** Omit dimensions for intrinsic content sizing; an anchor keeps positioning independent of the resulting width. */
+  const sheet = (x: number, y: number, width: number | undefined, height: number | undefined, content: string, anchor: Align = 'start') =>
+    `<div class="sheet${anchor === 'start' ? '' : ` anchor-${anchor}`}" style="${box(x, y, width, height)}">${content}</div>`
+  const chip = (x: number, y: number, width: number | undefined, name: IconName, value: string) =>
+    `<div class="chip" style="${box(x, y, width)}">${icon(name)}<span data-label>${escapeHtml(value)}</span></div>`
+  const mark = (x: number, y: number, name: IconName, value: string, align: Align = 'start') =>
+    `<div class="mark${align === 'start' ? '' : ` ${align}`}" style="${box(x, y)}">${icon(name)}${label(value)}</div>`
+  /** A vertical hairline between two places; caption each side with an eyebrow `text`. */
+  const divider = (x: number, top: number, bottom: number) => `<i class="divider" style="${box(x, top, undefined, bottom - top)}"></i>`
+  const window = (x: number, y: number, width: number, height: number, content = '') =>
+    `<div class="window" style="${box(x, y, width, height)}"><div class="toolbar"><i></i><i></i><i></i></div>${content}</div>`
+  /** A measured control specimen: center anchored, with its real padding exposed by inspection guides. */
+  const spacingControl = (x: number, y: number, value: string, padding: number, measurement: string, accent = false) =>
+    `<div class="spacing-study${accent ? ' accented' : ''}" style="${box(x, y)}--sample-padding:${padding}px">
+      <div class="spacing-control"><i class="padding-start"></i>${label(value, 'body')}<i class="padding-end"></i></div>
+      <div class="spacing-ruler"><i></i>${label(measurement, 'edge')}<i></i></div>
+    </div>`
+  /** Matched article specimens isolate selector attachment under the same pointer state. */
+  const selectorSpecimen = (x: number, y: number, test: 'owner' | 'target', title: string, firstLink: string, secondLink: string) =>
+    `<article class="sheet selector-specimen anchor-center" data-test="${test}" style="${box(x, y)}">
+      <p>${label(title)}</p>
+      <a>${label(firstLink, 'body')}<svg class="selector-pointer" viewBox="0 0 24 24" aria-hidden="true"><path d="M4 3l15 9-7 1-3 7z"/></svg></a>
+      <a>${label(secondLink, 'body')}</a>
+    </article>`
+  /** Measured query boundaries share one width scale; heights still follow content. */
+  const queryScopes = (x: number, y: number, viewportWidth: number, containerWidth: number, labels: {
+    viewport: string; media: string; viewportWidth: string; container: string; query: string; containerWidth: string; child: string
+  }) => `<div class="query-scopes anchor-center" style="${box(x, y, viewportWidth)}">
+    <div class="query-ruler">${label(labels.viewportWidth, 'code')}</div>
+    <div class="query-viewport">
+      <div class="query-scope-heading">${label(labels.viewport)}${label(labels.media, 'code')}</div>
+      <div class="query-container-study" style="width:${containerWidth}px">
+        <div class="query-ruler">${label(labels.containerWidth, 'code')}</div>
+        <div class="query-container">${label(labels.container)}${label(labels.query, 'code')}<div class="query-descendant">${label(labels.child, 'body')}</div></div>
+      </div>
+    </div>
+  </div>`
+  /** A file's current contribution; a removed source loses its solid artifact and connection. */
+  const sourceContribution = (x: number, y: number, name: string, source: string, removed = false) =>
+    `<div class="sheet source-contribution anchor-center" style="${box(x, y)}"${removed ? ' data-removed' : ''}>${row(icon('fileCode') + label(name))}${row(label(source, 'code'))}</div>`
+  /** An ordered layer list; unlayered CSS is separated because it is not a sixth named layer. */
+  const priorityStack = (x: number, y: number, layers: readonly string[], unlayered: string) =>
+    `<div class="priority-stack anchor-center" style="${box(x, y)}">${layers.map(value => `<div>${label(value, 'code')}</div>`).join('')}<div class="unlayered">${label(unlayered, 'body')}</div></div>`
+  /** Two DOM scopes expose inherited computed values; sample paint is the literal result being compared. */
+  const variableScope = (x: number, y: number, inline: boolean, labels: {
+    root: string; rootValue: string; resolved: string; omitted: string; region: string; regionValue: string; sample: string; blue: string; plum: string
+  }) => `<div class="variable-scope anchor-center" style="${box(x, y)}" data-inline="${inline}">
+    ${label(labels.root, 'code')}${label(labels.rootValue, 'code')}${label(inline ? labels.omitted : labels.resolved, inline ? 'edge' : 'code')}
+    <div class="variable-region">${label(labels.region, 'code')}${label(labels.regionValue, 'code')}
+      <div class="variable-sample">${label(labels.sample, 'code')}</div>
+      ${label(inline ? labels.plum : labels.blue, 'note')}
+    </div>
+  </div>`
+  /** A native CSS block: indentation and a scope guide expose containment, not execution order. */
+  const codeScope = (opening: string, content: string, tone?: AnnotationTone) =>
+    `<div class="code-scope"${tone ? ` data-tone="${tone}"` : ''}>${label(opening, 'code')}<div class="code-scope-body">${content}</div>${label('}', 'code')}</div>`
+  /** Equal swatches compare actual preset paint; the marked one is an alias target. */
+  const colorScale = (x: number, y: number, hue: string, steps: readonly string[], selected: number, tone: AnnotationTone) =>
+    `<div class="color-scale anchor-center" data-tone="${tone}" style="${box(x, y)}">${steps.map(step => `<div class="color-scale-step"><i class="bg-${hue}-${step}"${Number(step) === selected ? ` data-selected data-anchor="${hue}-selected"` : ''}></i>${label(step, 'code')}</div>`).join('')}</div>`
+  /** Matched content and geometry isolate native light-dark() selection. */
+  const roleSelection = (x: number, y: number, mode: Theme, heading: string, sample: string, surface: string, tone: AnnotationTone) =>
+    `<div class="role-selection anchor-center" data-tone="${tone}" style="${box(x, y)}">
+      <span class="code" data-label data-anchor="${mode}-scheme">${escapeHtml(heading)}</span>
+      <div class="role-selection-sample bg-surface-base" style="color-scheme:${mode}"><span class="fg-text-muted" data-label>${escapeHtml(sample)}</span></div>
+      ${label(surface, 'edge')}
+    </div>`
+  /** The two layouts share actual content; colored bands expose the native spacing. */
+  const spacingSpecimen = (x: number, y: number, kind: 'padding' | 'gap', first: string, second: string) =>
+    `<div class="spacing-sample grid ${kind === 'padding' ? 'p-md' : 'gap-md'} anchor-center" data-kind="${kind}" data-tone="${kind === 'padding' ? 'blue' : 'violet'}" style="${box(x, y)}"><div class="spacing-item">${label(first, 'body')}</div><div class="spacing-item">${label(second, 'body')}</div></div>`
+  /** Parent widths encode the measured constraint. The capped child's height remains intrinsic. */
+  const sizingSpecimen = (x: number, y: number, width: number, available: string, content: string, result: string) =>
+    `<div class="sizing-study" style="${box(x, y, width)}">${label(available, 'note')}<div class="sizing-parent"><div class="sizing-child max-w-3xs">${label(content, 'body')}${label(result, 'code')}</div></div></div>`
+  /** A real child paints into a rounded parent; only the compared clipping policy changes. */
+  const radiusSpecimen = (x: number, y: number, clip: boolean, child: string, parent: string) =>
+    `<div class="radius-sample r-4xl${clip ? ' overflow-hidden' : ''} anchor-center" style="${box(x, y)}"><div class="radius-child">${label(child, 'body')}</div><div class="radius-parent-content">${label(parent, 'body')}</div></div>`
+  /** Matched flow boxes keep their real gap while shadow paint extends beyond them. */
+  const shadowSpecimen = (x: number, y: number, token: string, title: string, content: string, next: string, gap: string) =>
+    `<div class="shadow-study anchor-center" style="${box(x, y)}"><div class="shadow-sample ${escapeHtml(token)}">${label(title, 'title')}${label(content, 'body')}</div><div class="shadow-following">${label(next, 'body')}<div class="shadow-gap">${label(gap, 'edge')}</div></div></div>`
+  /** Actual font properties change independently against the same baseline. */
+  const fontComparison = (x: number, y: number, baseline: string, headings: readonly string[], rows: readonly { class: string, classes: string }[], sample: string) =>
+    `<div class="font-comparison anchor-center" style="${box(x, y)}">${headings.map(value => label(value, 'edge')).join('')}${rows.map(item => `${label(item.class, 'code')}<span class="font-specimen ${escapeHtml(baseline)}" data-label>${escapeHtml(sample)}</span><span class="font-specimen ${escapeHtml(item.classes)}" data-label>${escapeHtml(sample)}</span>`).join('')}</div>`
+  /** Unitless line-height is inherited into real, equally wide text columns. */
+  const leadingComparison = (x: number, y: number, classes: readonly string[], sizes: readonly string[], lines: readonly string[], results: readonly string[]) =>
+    `<div class="leading-study leading-md anchor-center" style="${box(x, y)}">${classes.map((name, i) => `<section class="leading-column" data-tone="${i ? 'violet' : 'blue'}">${label(sizes[i], 'code')}<div class="leading-lines ${escapeHtml(name)}">${lines.map(line => `<span data-label>${escapeHtml(line)}</span>`).join('')}</div>${label(results[i], 'edge')}</section>`).join('')}</div>`
+  /** A real parent supplies computed tracking; only the second child declares it again. */
+  const trackingComparison = (x: number, y: number, classes: readonly string[], sample: string, results: readonly string[]) =>
+    `<div class="tracking-scope font-md tracking-widest anchor-center" style="${box(x, y)}">${classes.map((name, i) => `<section class="tracking-row" data-tone="${i ? 'violet' : 'blue'}">${label(name, 'code')}<div class="tracking-sample ${escapeHtml(name)}" data-label>${escapeHtml(sample)}</div>${label(results[i], 'edge')}</section>`).join('')}</div>`
+  /** Adjacent literal fragments preserve the original string; each bracket follows its fragment's intrinsic width. */
+  const codeParts = (x: number, y: number, parts: ({ id: string, value: string, tone: AnnotationTone } | { value: string })[]) =>
+    `<div class="annotated-code anchor-center" style="${box(x, y)}">${parts.map(part =>
+      'id' in part
+        ? `<span class="code-part" data-tone="${part.tone}">${label(part.value, 'code')}<i class="code-bracket" data-anchor="${escapeHtml(part.id)}"></i></span>`
+        : `<span class="code-part">${label(part.value, 'code')}</span>`).join('')}</div>`
+  const annotation = (x: number, y: number, id: string, title: string, detail: string, tone: AnnotationTone) =>
+    `<div class="annotation anchor-center" style="${box(x, y)}" data-tone="${tone}"><span class="title" data-label data-anchor="${escapeHtml(id)}">${escapeHtml(title)}</span>${label(detail, 'note')}</div>`
+  /** The renderer resolves these leaders after fonts load, so they attach to actual content rather than estimated coordinates. */
+  const leader = (from: string, to: string, viaY: number, tone: AnnotationTone) => {
+    routes.push(`<path data-from="${escapeHtml(from)}" data-to="${escapeHtml(to)}" data-via-y="${viaY}" data-tone="${tone}"/>`)
+    return ''
+  }
+  /** A connector in scene coordinates: arrowed unless it only joins other routes, dashed only for a labelled condition. */
+  const route = (d: string, { arrow = true, dashed = false, emphasis = false } = {}) => {
+    routes.push(`<path d="${d}"${arrow ? ` marker-end="url(#${emphasis ? 'arrow-emphasis' : 'arrow'})"` : ''}${emphasis ? ' data-emphasis' : ''}${dashed ? ' data-dashed' : ''}/>`)
+    return ''
+  }
+
+  function scene(title: string, description: string, content: string) {
+    const asset = (path: string) => new URL(path, import.meta.url).href
+    const html = `<!doctype html>
+<html lang="en" class="${theme}">
+<head>
+<meta charset="utf-8">
+<title>${escapeHtml(title)}</title>
+<link rel="stylesheet" href="${asset('../../../../styles/system/tokens.css')}">
+<link rel="stylesheet" href="${asset('./illustration.css')}">
+</head>
+<body>
+<main class="scene" style="width:${sceneWidth}px;height:${sceneHeight}px" role="img" aria-label="${escapeHtml(description)}">
+<svg class="routes" width="${sceneWidth}" height="${sceneHeight}" viewBox="0 0 ${sceneWidth} ${sceneHeight}" aria-hidden="true">
+<defs><marker id="arrow" viewBox="0 0 8 8" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto" markerUnits="userSpaceOnUse"><path d="M2.5 1l4 3-4 3"/></marker><marker id="arrow-emphasis" viewBox="0 0 8 8" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto" markerUnits="userSpaceOnUse"><path d="M2.5 1l4 3-4 3"/></marker></defs>
+${routes.join('\n')}
+</svg>
+${content}
+</main>
+</body>
+</html>
+`
+    return { width: sceneWidth, height: sceneHeight, title, description, html }
+  }
+
+  return { theme, icon, label, text, row, rule, bars, sheet, chip, mark, divider, window, spacingControl, selectorSpecimen, queryScopes, sourceContribution, priorityStack, variableScope, codeScope, colorScale, roleSelection, spacingSpecimen, sizingSpecimen, radiusSpecimen, shadowSpecimen, fontComparison, leadingComparison, trackingComparison, codeParts, annotation, leader, route, scene }
+}

package/src/demo/maintenance-example.ts

@@ -0,0 +1,62 @@
+/** One authored panel shared by the Guide preview, portable source and verification. */
+const maintenanceExample = {
+  title: 'Independent roles in one panel',
+  source: `@theme {
+  --color-brand: light-dark(#4f46e5, #818cf8);
+  --color-text-on-brand: light-dark(#ffffff, #18181b);
+  --color-information: light-dark(#4f46e5, #c7d2fe);
+}
+
+@utility panel-stack(--gap <number>: 1) {
+  display: flex;
+  flex-direction: column;
+  gap: calc(var(--gap) * 1rem);
+}
+
+@layer components {
+  .card-region { container-type: inline-size; }
+  .card { display: grid; gap: 1rem; }
+  @container (width >= 30rem) {
+    .card { grid-template-columns: 1fr 1fr; }
+  }
+  .button {
+    padding: .625rem 1rem;
+    background-color: var(--color-brand);
+    color: var(--color-text-on-brand);
+  }
+  .button:focus-visible { outline: 2px solid var(--color-text-strong); outline-offset: 2px; }
+  .button:disabled { opacity: .5; cursor: not-allowed; }
+  .progress-fill {
+    transform-origin: left;
+    transform: scaleX(var(--progress, 0));
+    transition: transform 150ms;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .progress-fill { transition: none; }
+  }
+}
+
+[data-theme='dark'] { --color-brand: #c4b5fd; color-scheme: dark; }`,
+  html: `<section class="card-region p-lg r-lg bg-surface-raised">
+  <article class="card">
+    <div class="panel-stack(1.5)">
+      <h2 class="m(0) fg-brand">Workspace</h2>
+      <p class="fg-information">Your files stay available during updates.</p>
+      <div class="flex flex-wrap gap-sm">
+        <button class="button" type="button">Save</button>
+        <button class="button" type="button" disabled>Saving</button>
+      </div>
+    </div>
+    <div aria-hidden="true" class="grid items-center">
+      <div class="(height:.5rem) bg-surface-inset">
+        <div class="progress-fill (height:.5rem) bg-brand" style="--progress:.4"></div>
+      </div>
+    </div>
+  </article>
+</section>`,
+  caption: 'Switch Theme to compare the color roles. The heading, action and progress fill share the brand color; information and action text have their own roles. The buttons demonstrate enabled and disabled states without saving data.',
+  guide: '/guide/global-styles',
+  theme: true,
+}
+
+export default maintenanceExample