@master/internal-site 0.0.0-stage → 0.1.0

package/src/demo/reference/frame.css

@@ -0,0 +1,118 @@
+@font-face { font-family: Geist; font-style: normal; font-weight: 100 900; src: url('/fonts/GeistVariable.woff2') format('woff2'); font-display: swap; }
+@font-face { font-family: 'IBM Plex Mono'; src: url('/fonts/IBMPlexMono-Regular.woff2') format('woff2'); font-display: swap; }
+
+@layer defaults {
+  html { color-scheme: light dark; background: var(--ui-surface-stage); }
+  html.light { color-scheme: light; }
+  html.dark { color-scheme: dark; }
+  body { margin: 0; padding: 24px; font-family: Geist, system-ui, sans-serif; font-size: 13px; line-height: 1.6; color: var(--ui-text-body); }
+  *, ::before, ::after { box-sizing: border-box; }
+  p { margin: 0 0 12px; }
+  img, svg { vertical-align: middle; }
+  button, input, textarea, select { font: inherit; color: inherit; }
+  button, input, textarea, select {
+    border: 1px solid var(--ui-line-divider); border-radius: 4px; background: var(--ui-surface-sheet); padding: 8px 12px;
+  }
+  button { cursor: pointer; }
+  button:hover { border-color: var(--ui-line-mark); }
+  input:not([type='checkbox']):not([type='radio']):not([type='range']), textarea { max-width: 100%; }
+  input[type='checkbox'], input[type='radio'] { width: 16px; height: 16px; }
+  a { color: var(--ui-tone-blue); }
+  :focus-visible { outline: 2px solid var(--ui-focus); outline-offset: 3px; }
+  /* Captions and readings inside a specimen are small sans with tabular figures, like every caption in the system. */
+  [data-ui='label'] { margin-bottom: 10px; color: var(--ui-text-muted); font: 400 12px/1.6 var(--font-family-sans, system-ui, sans-serif); font-variant-numeric: tabular-nums; overflow-wrap: anywhere; }
+  [data-ui='tile'], [data-ui='inline'] {
+    --sample-tone: var(--ui-tone-blue);
+    padding: 12px; border: 1px solid color-mix(in srgb, var(--sample-tone) 40%, transparent); border-radius: 4px;
+    background: color-mix(in srgb, var(--sample-tone) 10%, var(--ui-surface-sheet)); color: var(--ui-text-body);
+    font-size: 12px; text-align: center;
+  }
+  [data-tone='neutral'] { --sample-tone: var(--ui-tone-neutral); }
+  [data-tone='violet'] { --sample-tone: var(--ui-tone-violet); }
+  [data-tone='amber'] { --sample-tone: var(--ui-tone-amber); }
+  [data-ui='comparison'] { display: grid; grid-template-columns: repeat(auto-fit,minmax(min(100%,160px),1fr)); gap: 24px; }
+  [data-ui='comparison'] > section { min-width: 0; }
+  [data-ui='comparison'][data-scenario='box-sizing'] { grid-template-columns: repeat(auto-fit,minmax(min(100%,200px),1fr)); }
+  [data-ui='comparison'][data-scenario='containment'] { grid-template-columns: repeat(auto-fit,minmax(min(100%,280px),1fr)); }
+  [data-ui='surface'], [data-ui='type-frame'] { padding: 16px; border: 1px solid var(--ui-line-divider); border-radius: 4px; background: var(--ui-surface-sheet); }
+  [data-ui='type-frame'] { margin-bottom: 16px; }
+  [data-ui='type-example'] + [data-ui='type-example'] { margin-top: 24px; }
+  [data-ui='type-example'] { --type-tone: var(--ui-tone-blue); }
+  [data-ui='type-example'][data-tone='violet'] { --type-tone: var(--ui-tone-violet); }
+  [data-ui='type-surface'] { padding: 16px; border: 1px solid var(--ui-line-divider); border-radius: 4px; background: var(--ui-surface-sheet); }
+  :where([data-ui='type-target']:not([data-appearance='plain'])) { outline: 1px solid color-mix(in srgb,var(--type-tone) 24%,transparent); background: color-mix(in srgb,var(--type-tone) 5%,transparent); }
+  [data-ui='type-readings'] { display: flex; flex-wrap: wrap; gap: 6px 20px; margin-top: 10px; color: var(--ui-text-muted); font: 400 12px/1.6 var(--font-family-sans, system-ui, sans-serif); font-variant-numeric: tabular-nums; overflow-wrap: anywhere; }
+  [data-ui='type-readings'] > span { min-width: 0; }
+
+  [data-ui='flex'] { display: flex; gap: 12px; min-height: 160px; border: 1px dashed var(--ui-line-divider); padding: 12px; }
+  [data-ui='flex'] > [data-ui='tile'] { min-width: 40px; }
+  [data-scenario='visibility'] { min-height: 0; }
+  [data-scenario='visibility'] > [data-ui='tile'] { flex: 1; }
+  :where([data-ui='flex-layout']) { outline: 1px dashed var(--ui-line-divider); }
+  :where([data-ui='flex-cell']) {
+    --sample-tone: var(--ui-tone-blue);
+    outline: 1px solid color-mix(in srgb, var(--sample-tone) 45%, transparent); outline-offset: -1px; border-radius: 4px;
+    color: var(--ui-text-body); font-size: 12px;
+  }
+  [data-ui='flex-cell'] { background: color-mix(in srgb, var(--sample-tone) 10%, var(--ui-surface-sheet)); }
+  [data-ui='layout-example'] + [data-ui='layout-example'] { margin-top: 24px; }
+  [data-ui='layout-readings'] { display: flex; flex-wrap: wrap; gap: 8px 20px; margin-top: 12px; color: var(--ui-text-muted); font: 400 12px/1.6 var(--font-family-sans, system-ui, sans-serif); font-variant-numeric: tabular-nums; }
+  [data-ui='float-context'] { display: flow-root; width: 100%; min-height: 200px; }
+  [data-ui='float-image'] { width: 128px; height: 90px; margin-bottom: 12px; border-radius: 4px; }
+  [data-ui='float-quote'] { width: 128px; margin-bottom: 12px; border-inline-start: 2px solid var(--ui-tone-violet); padding: 12px; background: var(--ui-surface-sheet); }
+  [data-ui='columns'] { columns: 2; height: 230px; column-gap: 16px; }
+  [data-ui='columns'] > [data-ui='tile'] { margin-bottom: 12px; }
+  [data-scenario='prose-flow'] { height: auto; }
+  [data-scenario='prose-flow'] :is(h2,h3) { margin: 0 0 12px; padding: 12px; border: 1px solid var(--ui-tone-blue); background: var(--ui-surface-sheet); color: var(--ui-tone-blue); font-size: 14px; font-weight: 550; }
+  [data-scenario='fragmentation'] > [data-ui='tile'] { margin: 0; border-radius: 0; text-align: left; }
+  [data-ui='contain'] { width: 180px; height: 120px; border: 1px dashed var(--ui-tone-blue); padding: 16px; }
+  [data-ui='display'] { gap: 12px; }
+  [data-ui='inline'] { padding: 3px 8px; }
+  [data-ui='inline-layout'] { gap: 8px; padding: 8px; border: 1px solid color-mix(in srgb,var(--ui-tone-blue) 45%,transparent); border-radius: 4px; vertical-align: middle; }
+  [data-ui='table'] { width: 100%; border: 1px solid var(--ui-line-divider); border-spacing: 8px; }
+  [data-ui='table'] :is(td,th,.table-cell) { border: 1px solid var(--ui-line-divider); padding: 12px; background: var(--ui-surface-sheet); }
+  [data-ui='table'] :is(thead,tfoot,.table-header-group,.table-footer-group) { color: var(--ui-tone-blue); font-weight: 550; }
+  [data-ui='table'] [data-ui='collapse-row'] > td { background: color-mix(in srgb,var(--ui-tone-blue) 10%,var(--ui-surface-sheet)); }
+  [data-ui='table'] .table-caption { padding: 8px; }
+  [data-ui='position-context'] { outline: 1px dashed var(--ui-line-divider); }
+  [data-ui='original-slot'] { outline: 1px dashed var(--ui-tone-violet); }
+  [data-ui='local-context'] { outline: 1px dashed var(--ui-tone-blue); }
+  [data-ui='local-card'] { background: var(--ui-surface-sheet); border-radius: 4px; }
+  [data-ui='fixed-search'] { box-shadow: 0 2px 8px #0001; }
+  [data-ui='asset-collection'] > div { margin-bottom: 8px; }
+  [data-ui='scroll'] { border: 1px solid var(--ui-line-divider); }
+  [data-ui='isolation-backdrop'] { border-radius: 4px; }
+  [data-ui='blend-layer'] { color: #fff; font-weight: 550; text-align: center; border-radius: 3px; }
+  [data-ui='box-size-guide'] { width: 160px; border-top: 1px dashed var(--ui-tone-violet); padding-top: 12px; }
+  [data-ui='text'] { margin: 0; }
+  [data-ui='display-text'] { margin: 0; font-size: 32px; line-height: 1.35; font-weight: 550; }
+  [data-ui='list'] { padding-left: 28px; max-width: 320px; }
+  [data-ui='media-sample'] { width: 100%; height: 170px; object-fit: cover; background: var(--ui-surface-sheet); outline: 1px solid var(--ui-line-divider); }
+  [data-ui='media-sample'][data-ratio] { height: auto; }
+  [data-ui='truncate'] { padding: 12px; border: 1px solid var(--ui-line-divider); border-radius: 4px; }
+  [data-ui='overflow-frame'] { border: 1px dashed var(--ui-tone-violet); }
+  [data-ui='overflow-content'] { display: flex; flex-direction: column; justify-content: space-between; padding: 16px; background: repeating-linear-gradient(135deg,transparent 0 23px,var(--ui-line-hair) 23px 24px),color-mix(in srgb,var(--ui-tone-blue) 10%,var(--ui-surface-sheet)); }
+  [data-ui='overflow-content'] > :last-child { align-self: end; color: var(--ui-tone-violet); }
+  [data-scenario='scroll-containers'] { grid-template-columns: repeat(auto-fit,minmax(min(100%,224px),1fr)); }
+  [data-ui='scroll-actions'] { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 12px; }
+  :where([data-ui='scrollport'], [data-ui='nested-outer']) { outline: 1px solid var(--ui-line-divider); border-radius: 4px; }
+  [data-ui='scroll-panel'] { padding: 16px; border: 1px solid var(--ui-line-divider); background: var(--ui-surface-sheet); font-size: 13px; }
+  [data-ui='scroll-panel'] strong { font-weight: 550; }
+  [data-ui='scroll-panel'] p { margin: 12px 0 0; color: var(--ui-text-muted); max-width: 36ch; }
+  [data-ui='scroll-panel']:nth-of-type(even) { background: color-mix(in srgb,var(--ui-tone-violet) 8%,var(--ui-surface-sheet)); }
+  [data-ui='scroll-panel'][data-target] { border-color: var(--ui-tone-blue); background: color-mix(in srgb,var(--ui-tone-blue) 10%,var(--ui-surface-sheet)); }
+  [data-ui='scroll-header'] { padding: 12px 16px; border-bottom: 1px solid var(--ui-tone-blue); background: var(--ui-surface-sheet); color: var(--ui-tone-blue); }
+  [data-ui='scroll-actions'] a { padding: 8px 12px; border: 1px solid var(--ui-line-divider); border-radius: 4px; background: var(--ui-surface-sheet); text-decoration: none; }
+  [data-ui='scroll-readings'] { display: flex; flex-wrap: wrap; gap: 8px 20px; padding-block: 12px; font: 400 12px/1.6 var(--font-family-sans, system-ui, sans-serif); font-variant-numeric: tabular-nums; color: var(--ui-text-muted); }
+  [data-ui='scroll-readings'] output { color: var(--ui-text-body); }
+  [data-scenario='nested-scrolling'] { grid-template-columns: repeat(auto-fit,minmax(min(100%,200px),1fr)); }
+  :where([data-ui='nested-inner']) { outline: 1px solid var(--ui-tone-blue); border-radius: 3px; }
+  [data-ui='nested-content'] { display: flex; flex-direction: column; justify-content: space-between; padding: 12px; background: color-mix(in srgb,var(--ui-tone-violet) 8%,var(--ui-surface-sheet)); }
+  [data-ui='nested-inner'] > [data-ui='nested-content'] { background: color-mix(in srgb,var(--ui-tone-blue) 10%,var(--ui-surface-sheet)); }
+  [data-ui='nested-content'] > span { align-self: end; font: 400 12px/1.6 var(--font-family-sans, system-ui, sans-serif); font-variant-numeric: tabular-nums; color: var(--ui-text-muted); }
+  html[data-demo-paused] * { animation-play-state: paused !important; }
+  @media (prefers-reduced-motion: reduce) {
+    html:not([data-motion-allowed]) *, html:not([data-motion-allowed]) ::before, html:not([data-motion-allowed]) ::after { animation-play-state: paused !important; transition-duration: 0s !important; scroll-behavior: auto !important; }
+  }
+  @media (width < 360px) { body { padding: 16px; } }
+}

package/src/demo/reference/grid.ts

@@ -0,0 +1,42 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { label } from '@master/internal-site/demo/reference/html.ts'
+import { paintLayout } from '@master/internal-site/demo/reference/layout-html.ts'
+
+const comparisons: Record<string, string[]> = {
+  'fill-by-column': ['Row flow', 'Column flow'],
+  'fill-gaps-densely': ['Sparse · keep moving forward', 'Dense · fill earlier holes'],
+  'place-an-item-by-columns': ['Column lines 2 → 4', 'Column lines 1 → −1'],
+  'place-an-item-by-rows': ['Row lines 1 → 3', 'Row lines 1 → −1'],
+}
+
+/** Track definitions and placement come only from each section's complete HTML. */
+export function grid(section: ReferenceDemoSection): DemoScene {
+  const { page, id } = section
+  const item = ['grid-area', 'grid-column', 'grid-row'].includes(page)
+  const property = ({ 'grid-columns': 'grid-template-columns', 'grid-rows': 'grid-template-rows' } as Record<string, string>)[page] ?? page
+  const names = id === 'use-minmax'
+    ? page === 'grid-template-columns' ? ['Automatic track minimum', 'Zero track minimum'] : ['One line · minimum height', 'Four lines · content height']
+    : comparisons[id]
+  const html = section.html.map((source, index) => {
+    const prefix = section.html.length > 1 ? `example-${index}-` : ''
+    const layout = `${prefix}layout`, target = `${prefix}target`
+    const reading = (name: string, element: string, value: string) => `<span>${name} <output data-style-readout="${element}" data-style-property="${value}"${/grid-template-(columns|rows)/.test(value) ? ' data-round-pixels' : ''}>—</output></span>`
+    const placement = item ? reading('Blue placement', target, property) : ''
+    const areas = page === 'grid-template-areas' ? reading('Areas', layout, 'grid-template-areas') : ''
+    return `<section data-ui="layout-example">${names ? label(names[index]) : ''}${paintLayout(source, prefix, index === 0 ? item ? 'target' : 'layout' : '')}<div data-ui="layout-readings">${reading('Columns', layout, 'grid-template-columns')}${reading('Rows', layout, 'grid-template-rows')}${reading('Flow', layout, 'grid-auto-flow')}${placement}${areas}<span>Blue item <output data-size-readout="${target}">—</output></span><span>Blue offset <output data-position-readout="${target}" data-position-origin="${layout}">—</output></span></div></section>`
+  }).join('')
+  const captions: Record<string, string> = {
+    'grid-area': 'The blue region follows its authored line boundaries or area name. Siblings occupy the same real grid; labels do not add cells.',
+    'grid-auto-columns': 'The violet first column is explicit. The blue column and its following sibling use the implicit-column size.',
+    'grid-auto-rows': 'The first row is explicit. The blue item belongs to an implicit row created for additional content.',
+    'grid-auto-flow': id === 'fill-gaps-densely' ? 'Compare the position of 03, then focus 01 and press Tab. Visual packing changes; source-order keyboard traversal does not.' : 'Read the numbers in DOM order. Track definitions stay the same while placement searches across rows or down columns.',
+    'grid-column': 'Column lines bound each track. The blue width includes every track and internal gap in its span.',
+    'grid-row': 'Row lines bound each track. The blue height includes every track and internal gap in its span.',
+    'grid-columns': 'The columns share the width left after gaps. Additional items create new rows while preserving source order.',
+    'grid-rows': 'Follow the numbers down each column. The fixed container height makes the equal row sizes measurable.',
+    'grid-template-areas': 'Header, Nav and Content keep their area names. The parent supplies both the region map and its track sizes.',
+    'grid-template-columns': id === 'use-minmax' ? 'The content stays 192px wide in both examples. The blue cell clips excess content when its track is allowed to shrink.' : 'Fixed tracks and gaps reserve space first. Fractional tracks divide what remains, subject to their minimums.',
+    'grid-template-rows': id === 'use-minmax' ? 'The taller content grows the first row; the fractional second row receives less of the fixed height.' : 'The row readings include every resolved track. The gap is space between tracks, not part of their individual heights.',
+  }
+  return { html, caption: captions[page], sizing: 'content', inspect: id === 'apply-conditionally' ? [] : undefined }
+}

package/src/demo/reference/html.ts

@@ -0,0 +1,40 @@
+import type { ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+
+export const prose = 'Good tools make room for clear thinking. Arrange the canvas, explore a small detail, and see how each decision changes the whole composition.'
+export const longText = 'Design systems give teams a shared language for building thoughtful interfaces. A clear hierarchy helps people find what matters, while consistent spacing makes each relationship easier to understand.'
+export const artwork = '/demo/landscape.svg'
+export const mask = '/demo/mask.svg'
+
+export function escape(value: string) {
+  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
+}
+
+export function classValue(value = '') {
+  return escape(value.replaceAll('/hero.jpg', artwork).replaceAll('/mask.png', mask).replaceAll('/marker.svg', '/demo/marker.svg'))
+}
+
+export function tile(label: string, classes = '', tone = 'blue', style = '', attributes = '') {
+  return `<div data-ui="tile" data-tone="${tone}"${classes ? ' data-target' : ''} class="${classValue(classes)}"${style ? ` style="${escape(style)}"` : ''}${attributes ? ` ${attributes}` : ''}>${label}</div>`
+}
+
+export function label(text: string) { return `<div data-ui="label">${escape(text)}</div>` }
+
+export function specimen(content: string, classes = '', attrs = '') {
+  return `<div data-target class="${classValue(classes)}" ${attrs}>${content}</div>`
+}
+
+export function samples(section: ReferenceDemoSection): string[] {
+  return section.classLists.filter(Boolean)
+}
+
+export function comparison(samples: { name: string, content: string }[]) {
+  return `<div data-ui="comparison">${samples.map(sample => `<section>${label(sample.name)}${sample.content}</section>`).join('')}</div>`
+}
+
+export function image(classes = '', attrs = '') {
+  return `<img${classes ? ' data-target' : ''} src="${artwork}" alt="Sun above layered mountains" class="${classValue(classes)}" ${attrs}>`
+}
+
+export function numbered(count = 4, classes = '') {
+  return Array.from({ length: count }, (_, index) => tile(String(index + 1).padStart(2, '0'), classes, index === 1 ? 'violet' : 'blue')).join('')
+}

package/src/demo/reference/interaction.ts

@@ -0,0 +1,42 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { typeSpecimens } from '@master/internal-site/demo/reference/type-specimens.ts'
+
+const properties: Record<string, string[]> = {
+  'accent-color': ['accent-color'], 'appearance': ['appearance'],
+  'caret-color': ['caret-color', 'color'], 'cursor': ['cursor'],
+  'pointer-events': ['pointer-events'], 'resize': ['resize'],
+  'screen-readers': ['position', 'width', 'height'],
+  'touch-action': ['touch-action'], 'user-drag': ['-webkit-user-drag'],
+  'user-select': ['user-select'],
+}
+const captions: Record<string, string> = {
+  'accent-color': 'Use the actual checkbox, radio group and range. The browser and platform decide how a requested accent is painted; the controls retain their native keyboard behavior.',
+  'appearance': 'The full authored select and its options remain native. Change its value with the platform picker or keyboard; appearance changes paint without replacing the accessible label.',
+  'caret-color': 'Focus and edit the named text field. The insertion caret, text color, focus outline and mouse pointer are separate. Native blinking may hide the caret in a still image.',
+  'cursor': 'The cursor is a platform-rendered affordance. Try the real disclosure, reset control or native draggable image; the cursor itself does not implement the action.',
+  'pointer-events': 'Pointer hit testing and keyboard access are independent. Use the real checkbox or reset button to verify the action; transparent overlays keep their authored geometry.',
+  'resize': 'Drag the native resize handle where supported. The readout measures the real control box as it changes. Editing and scrolling remain available when handles are absent.',
+  'screen-readers': 'Visible annotations explain the actual accessible name or description. Use Tab to reach the visible native control; its hidden label is not a separate focus target.',
+  'touch-action': 'Swipe on a touch device to test native panning. Keyboard scrolling remains available. The rules allow or restrict browser gestures; no custom drawing or drag handler is supplied.',
+  'user-drag': 'Try a native pointer drag in a supporting browser. The event readout observes actual drag starts; vendor property support and touch behavior depend on the platform.',
+  'user-select': 'Use the platform’s text-selection gesture on the authored content. Selection rules do not disable native control actions or protect text from copying.',
+}
+
+/** Native controls, their labels and the complete teaching context stay authored in MDX. */
+export function interaction(section: ReferenceDemoSection): DemoScene {
+  const scene = typeSpecimens(section, {
+    appearance: 'plain', properties: properties[section.page], caption: captions[section.page],
+    measure: section.page === 'resize', measureLabel: 'Control box',
+  })
+  if (section.page === 'touch-action' || section.page === 'user-drag') {
+    scene.html = scene.html.replace(/(<div data-ui="type-readings">)([\s\S]*?)(<\/div>)/g, (_, open: string, readings: string, close: string) => {
+      const target = readings.match(/data-style-readout="([^"]+)"/)?.[1]
+      return section.page === 'touch-action' && section.id !== 'optimize-tap-controls'
+        ? `${open}${readings}<span>Scroll <output data-scroll-readout="${target}">—</output></span>${close}`
+        : section.page === 'user-drag'
+          ? `${open}${readings.replace('data-style-property="-webkit-user-drag"', 'data-style-property="-webkit-user-drag" data-empty-value="Not exposed"')}<span>Native drag <output data-drag-readout="${target}">No start observed</output></span>${close}`
+          : `${open}${readings}${close}`
+    })
+  }
+  return scene
+}

package/src/demo/reference/layout-html.ts

@@ -0,0 +1,10 @@
+/** Paint known authored boxes without supplying layout, sizing or positioning. */
+export function paintLayout(source: string, prefix: string, inspected: string, measured = 'target') {
+  return source.replace(/<([a-z]+)(\s[^>]*|)>/g, (tag: string, element: string, attributes: string) => {
+    const id = attributes.match(/\bid="([\w-]+)"/)?.[1]
+    if (!id || !/^(?:layout|target|peer|item-\d+)$/.test(id)) return tag
+    const layout = id === 'layout'
+    const tone = id === measured ? 'blue' : id === 'peer' || id === 'item-2' ? 'violet' : 'neutral'
+    return `<${element}${attributes.replace(`id="${id}"`, `id="${prefix}${id}"`)} data-ui="${layout ? 'flex-layout' : 'flex-cell'}"${layout ? '' : ` data-tone="${tone}"`}${id === inspected ? ' data-target' : ''}>`
+  })
+}

package/src/demo/reference/layout.ts

@@ -0,0 +1,102 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { classValue, comparison, image, label, longText, numbered, prose, specimen, tile } from '@master/internal-site/demo/reference/html.ts'
+
+export function flow(section: ReferenceDemoSection): DemoScene {
+  const { page, id, classLists: lists } = section
+  const target = lists[0] ?? ''
+  if (page === 'clear') {
+    const cleared = lists.find(value => value.includes('(clear:')) ?? '(clear:both)'
+    const left = lists.find(value => value.includes('(float:left)')) ?? '(float:left) (width:34%) (height:4.5rem)'
+    const right = lists.find(value => value.includes('(float:right)')) ?? '(float:right) (width:34%) (height:8.5rem)'
+    const conditional = id === 'apply-conditionally'
+    return {
+      html: `<div data-ui="float-context">${tile('Left float', left, 'neutral').replace(' data-target', '')}${tile('Right float', right, 'violet').replace(' data-target', '')}${tile(conditional ? 'Focus with Tab' : 'Clear target', cleared, 'blue', 'width:58%;min-height:56px', conditional ? 'tabindex="0"' : '')}</div>`,
+      caption: conditional ? 'Focus the blue element with Tab to clear both floats. The same change applies in the wider viewport and print preview.' : id === 'clearing-right-floats' ? 'The blue block clears the right float. Its text still wraps around the taller left float, whose box overlaps the blue background.' : 'The blue element clears the requested side. Unequal float heights make left, right and both visibly different.',
+      inspect: ['clear'], sizing: 'content',
+    }
+  }
+  if (page === 'float') {
+    return {
+      html: `<div data-ui="float-context">${id === 'float-elements-to-the-right' ? `<aside data-target data-ui="float-quote" class="${classValue(target)}">Good tools make room for clear thinking.</aside>` : image(target, 'data-ui="float-image"')}<p>${longText} ${prose}</p></div>`,
+      caption: 'Follow how the paragraph wraps beside the floated object, then returns to the full line width.', height: 300, sizing: 'content',
+    }
+  }
+  if (page === 'box-sizing') {
+    return {
+      html: comparison((lists.length ? lists : ['box-border', 'box-content']).map(value => ({ name: value, content: `${label('160px reference')}<div data-ui="box-size-guide">${tile('Content', value)}</div>` }))).replace('data-ui="comparison"', 'data-ui="comparison" data-scenario="box-sizing"'),
+      caption: 'The dashed reference is 160px wide. Border-box fits inside it; content-box adds its padding and border to that width.', inspect: ['box-sizing', 'width'], sizing: 'content',
+    }
+  }
+  if (page === 'column-count' || page === 'column-width' || page === 'column-span') {
+    const html = section.html[0]
+      .replace(/<(article|div) class="/, `<$1 data-ui="columns" data-scenario="prose-flow"${page !== 'column-span' ? ' data-target' : ''} class="`)
+      .replace(/<(h2|h3) class="/, '<$1 data-target class="')
+    return {
+      html,
+      caption: page !== 'column-span' ? 'Read down each column, then across to the next. The container grows naturally instead of forcing overflow columns.' : 'The highlighted heading belongs to the column flow. With all, it crosses the column set and the following text resumes below it.',
+      sizing: 'content',
+    }
+  }
+  if (page.startsWith('break-')) {
+    const parent = lists.find(value => /columns:|column-count:/.test(value)) ?? '(column-count:2) (height:12.5rem) (column-fill:auto)'
+    const values = lists.length > 1 ? lists.slice(1, 5) : ['h(130)', target, 'h(60)', 'h(40)']
+    const preview = (baseline: boolean) => `<div data-ui="columns" data-scenario="fragmentation" class="${classValue(parent)}">${values.map((value, index) => tile(index === 1 ? '02 · Target' : `0${index + 1}`, value, index === 1 ? 'blue' : 'neutral', baseline && index === 1 ? `${page}:auto` : '').replace(baseline || index !== 1 ? ' data-target' : ' data-unused', '')).join('')}</div>`
+    const caption = page === 'break-inside' ? 'Both column sets are 200px tall. The blue block can split in the automatic flow; avoid keeps it together when the condition applies.' : `Both column sets are 200px tall. The forced break moves content to the next column ${page === 'break-before' ? 'before' : 'after'} the blue block when the condition applies.`
+    return { html: comparison([{ name: 'Automatic breaks', content: preview(true) }, { name: 'With class', content: preview(false) }]), caption, sizing: 'content' }
+  }
+  if (page === 'contain') {
+    const panel = (baseline: boolean) => `<div data-ui="contain"${baseline ? ' style="contain:none"' : ' data-target'} class="${classValue(target)}">${tile('Wide content', lists[1], 'violet').replace(' data-target', '')}</div>`
+    return {
+      html: comparison([{ name: 'No containment', content: panel(true) }, { name: 'With class', content: panel(false) }]).replace('data-ui="comparison"', 'data-ui="comparison" data-scenario="containment"'),
+      caption: 'Both violet blocks keep their full width. Paint containment changes which part is visible, without resizing the child.', inspect: ['contain'], sizing: 'content',
+    }
+  }
+  if (page === 'visibility') {
+    if (section.classes.some(value => value.includes('collapse'))) {
+      const table = (collapsed: boolean) => `<table data-ui="table"><tbody><tr><td>01</td><td>First row</td></tr><tr data-ui="collapse-row"${collapsed ? ' data-target' : ''} class="${classValue(collapsed ? target : '')}"><td>02</td><td>Middle row</td></tr><tr><td>03</td><td>Last row</td></tr></tbody></table>`
+      return { html: comparison([{ name: 'Visible middle row', content: table(false) }, { name: 'Collapsed middle row', content: table(true) }]), caption: 'Compare the gap between rows 01 and 03. Collapsing a table row removes its space; hidden visibility on an ordinary block does not.', inspect: ['visibility'], sizing: 'content' }
+    }
+    return { html: `<div data-ui="flex" data-scenario="visibility">${tile('01', '', 'neutral')}${tile('02', target)}${tile('03', '', 'violet')}</div>`, caption: 'Item 02 receives the visibility class. Its space remains even when it is invisible.', inspect: ['visibility'], sizing: 'content' }
+  }
+  return display(section)
+}
+
+function display(section: ReferenceDemoSection): DemoScene {
+  const { id, classLists: lists } = section
+  const target = lists[0] ?? 'block'
+  let html: string
+  if (id.includes('table')) {
+    html = section.html[0].replace("<div class=\"table\">", "<div class=\"table\" data-ui=\"table\" data-target>")
+  } else if (id === 'contents') {
+    html = `<div data-ui="flex" class="${classValue(target)}">${tile('01', lists[1])}<div class="contents">${tile('02', lists[3], 'violet')}${tile('03', lists[4], 'violet')}</div>${tile('04', lists[5])}</div>`
+  } else if (id === 'flow-root') {
+    html = `<div class="flow-root" data-ui="surface">${image(lists[1], 'data-ui="float-image"')}<p>${prose}</p></div>`
+  } else if (id === 'hidden') {
+    html = `<div data-ui="flex" class="${classValue(target)}">${tile('01')}${tile('02', 'hidden')}${tile('03', '', 'violet')}</div>`
+  } else if (id === 'inline-grid') {
+    html = `<p>Before <span data-ui="inline-layout" data-target class="${classValue(target)}">${['01', '02', '03', '04'].map(value => `<span data-ui="tile">${value}</span>`).join('')}</span> after. The grid stays in the surrounding text flow.</p>`
+  } else if (id === 'inline-flex') {
+    html = `<p>Before <span data-ui="inline-layout" data-target class="${classValue(target)}"><span aria-hidden="true">●</span><span>In progress</span></span> after. The badge stays in the surrounding text flow.</p>`
+  } else if (id === 'list-item') {
+    html = `<div data-ui="list">${['01', '02', '03'].map(value => `<div data-ui="inline" data-target class="list-item">${value}</div>`).join('')}</div>`
+  } else if (id === 'block--inline') {
+    const variants = ['block', 'inline', 'inline-block']
+    html = variants.map(value => `<p>Before <span data-ui="inline" data-target class="${classValue(value)}">${value}</span> after. Follow where this line continues.</p>`).join('')
+  } else {
+    html = specimen(numbered(id === 'grid' ? 4 : 3), target, 'data-ui="display"')
+  }
+  const captions: Record<string, string> = {
+    'block--inline': 'A block starts a new line. Inline and inline-block boxes remain beside the surrounding text.',
+    flex: 'The three direct children share a flex row with the authored gap.',
+    'inline-flex': 'The badge aligns its children with flex while staying in the paragraph’s line of text.',
+    grid: 'Four direct children occupy two explicitly defined grid columns.',
+    'inline-grid': 'The four cells form a grid inside one inline box; the paragraph continues beside it.',
+    table: 'Header, body and footer groups share the same table columns. This CSS-only structure has no native table semantics.',
+    contents: 'The violet items belong to the contents wrapper. All four items participate in the outer flex layout.',
+    'flow-root': 'The outlined parent contains the floated image as well as the paragraph.',
+    'list-item': 'Each element produces its own list marker. Use native list elements when the content is a semantic list.',
+    hidden: 'Item 02 is still in the DOM, but hidden removes its box and its space.',
+    'apply-conditionally': 'Resize to switch between grid and flex. Print preview uses ordinary block flow at every page width.',
+  }
+  return { html, caption: captions[id], height: 280, sizing: 'content' }
+}

package/src/demo/reference/media.ts

@@ -0,0 +1,29 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { typeSpecimens } from '@master/internal-site/demo/reference/type-specimens.ts'
+
+const properties: Record<string, string[]> = {
+  'object-fit': ['object-fit', 'object-position'],
+  'object-position': ['object-position', 'object-fit'],
+  'fill': ['fill', 'stroke'],
+  'stroke': ['stroke', 'stroke-width', 'fill'],
+  'stroke-width': ['stroke-width', 'stroke'],
+}
+const captions: Record<string, string> = {
+  'object-fit': 'The source is 320 × 200. The measured box belongs to the image element; fitting changes the content inside it.',
+  'object-position': 'The 240 × 100 image box contains a 240 × 150 cover image. Positioning changes its crop without moving the element.',
+  'fill': 'The shapes and paint are explicitly authored. Fill is inherited independently of stroke; controls retain their native accessible names.',
+  'stroke': 'Paint, width and paths remain explicit. The values are inherited by the actual shapes, including the icon inside a native control.',
+  'stroke-width': 'The 24 × 24 viewBox scales into a 96 × 96 viewport. Computed width and final painted thickness are different measurements.',
+}
+
+/** Preserve actual image content boxes, SVG viewports and inherited paint. */
+export function media(section: ReferenceDemoSection): DemoScene {
+  return {
+    ...typeSpecimens(section, {
+      appearance: 'plain',
+      properties: section.id === 'apply-conditionally' && /^(fill|stroke)$/.test(section.page) ? [section.page] : properties[section.page],
+      measure: true, caption: captions[section.page],
+    }),
+    theme: section.id === 'use-theme-colors' || undefined,
+  }
+}

package/src/demo/reference/positioning.ts

@@ -0,0 +1,90 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { classValue, comparison, label, tile } from '@master/internal-site/demo/reference/html.ts'
+
+const context = (content: string, classes: string, attrs = '') => `<div data-ui="position-context" class="${classValue(classes)}" ${attrs}>${content}</div>`
+const quiet = (html: string) => html.replaceAll(' data-target', '')
+
+/** Offsets and containing blocks come from the adjacent authored example. */
+export function position(section: ReferenceDemoSection): DemoScene {
+  const { id, classLists: lists } = section
+  if (id.includes('static') || id.includes('relative')) {
+    return {
+      html: `${label('Dashed outline · original slot')}<div data-ui="original-slot" class="${classValue(lists[0])}">${tile('Target', lists[1])}</div>${quiet(tile('Next in flow', lists[2], 'violet'))}`,
+      caption: id.includes('static') ? 'The inset values are ignored. The target stays inside its original slot.' : 'The target moves 20px right and down. Its original slot and the next box stay in place.',
+      height: 250, inspect: ['position', 'top', 'left'],
+    }
+  }
+  if (id.includes('fixed')) {
+    return {
+      html: `<div class="${classValue(lists[0])}"><input type="search" aria-label="Filter assets" placeholder="Filter assets" data-target data-ui="fixed-search" class="${classValue(lists[1])}"><div data-ui="asset-collection" class="${classValue(lists[2])}">${Array.from({ length: 10 }, (_, i) => tile(`Asset ${String(i + 1).padStart(2, '0')}`, '', i % 2 ? 'neutral' : 'blue')).join('')}</div></div>`,
+      caption: 'Scroll inside the preview. The field stays fixed to this iframe viewport while the collection moves beneath it.',
+      height: 300, inspect: ['position'],
+    }
+  }
+  if (id.includes('sticky')) {
+    return {
+      html: `<div data-ui="scroll" class="${classValue(lists[0])}" tabindex="0" aria-label="Scrollable asset list">${quiet(tile('Scroll down', lists[1], 'neutral'))}${tile('Pinned collection', lists[2])}<div data-ui="asset-collection" class="${classValue(lists[3])}">${Array.from({ length: 8 }, (_, i) => tile(`Asset ${i + 1}`, '', 'neutral')).join('')}</div></div>`,
+      caption: 'Focus the list and scroll with the arrow keys. The blue row sticks to its top edge after the first row scrolls away.',
+      height: 288, inspect: ['position', 'top'],
+    }
+  }
+  const conditional = id === 'apply-conditionally'
+  return {
+    html: `${label('Containing block · relative parent')}${context(tile(conditional ? 'Focus with Tab' : 'Target', lists[1], 'blue', '', conditional ? 'tabindex="0"' : ''), lists[0])}`,
+    caption: conditional ? 'Focus the blue box or widen to sm. Absolute positioning moves it to the parent’s bottom-right corner.' : 'Top and right insets measure from this parent’s padding edge. The child contributes no height to normal flow.',
+    height: 244, inspect: conditional ? ['position', 'right', 'bottom'] : ['position', 'top', 'right'],
+  }
+}
+
+export function inset(section: ReferenceDemoSection): DemoScene {
+  const { id, classLists: lists } = section
+  const conditional = id === 'apply-conditionally'
+  const child = id === 'pin-one-side'
+    ? `<button type="button" data-target class="${classValue(lists[1])}">Close</button>`
+    : tile(conditional ? 'Focus with Tab' : id === 'center-overlays-with-inset' ? 'Overlay' : 'Inset on all four sides', lists[1], 'blue', '', conditional ? 'tabindex="0"' : '')
+  return {
+    html: `${label('Dashed boundary · positioned parent')}${context(child, lists[0])}`,
+    caption: conditional ? 'The box stretches between four insets. Focus increases the space around it; the viewport condition sets a larger resting inset.' : id === 'pin-one-side' ? 'Only the top and right edges are pinned. The button keeps its content width and height.' : 'Automatic width and height let the opposing insets determine the overlay’s dimensions.',
+    inspect: id === 'pin-one-side' ? ['top', 'right'] : ['top', 'right', 'bottom', 'left'], height: 244,
+  }
+}
+
+function negativeLayer(lists: string[]): DemoScene {
+  return {
+    html: `<article data-ui="local-card" class="${classValue(lists[0])}">${tile('', lists[1], 'blue', '', 'aria-hidden="true"')}<p>Foreground content</p></article>`,
+    caption: 'The isolated parent contains the negative layer. The blue decoration paints above the parent’s surface and behind its text.',
+    inspect: ['z-index'], height: 208,
+  }
+}
+
+export function stacking(section: ReferenceDemoSection): DemoScene {
+  const { id, classLists: lists } = section
+  if (id.includes('negative')) return negativeLayer(lists)
+  const layer = (text: string, classes: string, tone: string) => tile(text, classes, tone, 'display:grid;align-content:end;text-align:right;padding:4px 12px')
+  if (id.includes('local')) {
+    return {
+      html: `${label('Context 0 contains child 99 · sibling 1 paints above both')}${context(`<article data-ui="local-context" class="${classValue(lists[1])}">${tile('Child 99', lists[2], 'blue', 'text-left')}</article>${layer('Sibling 1', lists[3], 'violet')}`, lists[0])}`,
+      caption: 'Z-index values are compared within their own stacking context. Raising the child to 99 cannot lift its parent above sibling 1.', sizing: 'content',
+    }
+  }
+  const conditional = id === 'apply-conditionally'
+  return {
+    html: `${label(conditional ? 'Blue target · violet comparison' : 'Larger z-index paints above smaller values')}${context(conditional
+      ? tile('Focus with Tab', lists[1], 'blue', '', 'tabindex="0"') + quiet(layer('Layer 10', lists[2], 'violet'))
+      : lists.slice(1).map((value, index) => layer(`Layer ${30 - index * 10}`, value, index === 1 ? 'violet' : index === 2 ? 'neutral' : 'blue')).join(''), lists[0])}`,
+    caption: conditional ? 'Focus the blue box to bring it forward. Widening to sm gives it the same higher paint order.' : 'All three boxes are absolute children of one isolated parent. Their visible edges reveal the paint order.',
+    inspect: ['z-index'], sizing: 'content',
+  }
+}
+
+export function isolation(section: ReferenceDemoSection): DemoScene {
+  const { id, classLists: lists } = section
+  if (id === 'protect-layered-components') return negativeLayer(lists)
+  const conditional = id === 'apply-conditionally'
+  const sample = (baseline: boolean) => `<div data-ui="isolation-backdrop" class="${classValue(lists[0])}"><section${baseline ? '' : ' data-target'} class="${classValue(baseline ? '(isolation:auto)' : lists[1])}"${conditional && !baseline ? ' tabindex="0"' : ''}><div data-ui="blend-layer" class="${classValue(lists[2])}">${conditional && !baseline ? 'Focus with Tab' : 'Blend layer'}</div></section></div>`
+  return {
+    html: comparison([{ name: 'Automatic · external blend', content: sample(true) }, { name: 'With class', content: sample(false) }]),
+    caption: 'Both blue backgrounds sit outside the tested section. An isolated section prevents its purple child from blending with that external backdrop.',
+    inspect: ['isolation'], sizing: 'content',
+  }
+}