@master/internal-site 0.0.0-stage → 0.1.1

package/src/demo/reference/scenes.ts

@@ -0,0 +1,197 @@
+import { transitions } from '@master/internal-site/demo/reference/transitions.ts'
+import { transforms } from '@master/internal-site/demo/reference/transforms.ts'
+import { shapes } from '@master/internal-site/demo/reference/shapes.ts'
+import { media } from '@master/internal-site/demo/reference/media.ts'
+import { borderPaint } from '@master/internal-site/demo/reference/border-paint.ts'
+import { edges } from '@master/internal-site/demo/reference/edges.ts'
+import { overscroll, scrolling } from '@master/internal-site/demo/reference/scrolling.ts'
+import { flexbox } from '@master/internal-site/demo/reference/flexbox.ts'
+import { alignment } from '@master/internal-site/demo/reference/alignment.ts'
+import { grid } from '@master/internal-site/demo/reference/grid.ts'
+import { position, inset, stacking, isolation } from '@master/internal-site/demo/reference/positioning.ts'
+import { overflow } from '@master/internal-site/demo/reference/clipping.ts'
+import type { SceneFactory } from '@master/internal-site/demo/reference/types.ts'
+import { flow } from '@master/internal-site/demo/reference/layout.ts'
+import { sizing } from '@master/internal-site/demo/reference/sizing.ts'
+import { textEffects } from '@master/internal-site/demo/reference/text-effects.ts'
+import { textFlow } from '@master/internal-site/demo/reference/text-flow.ts'
+import { typeSpecimens } from '@master/internal-site/demo/reference/type-specimens.ts'
+import { typography } from '@master/internal-site/demo/reference/typography.ts'
+import { effects } from '@master/internal-site/demo/reference/effects.ts'
+import { backgrounds } from '@master/internal-site/demo/reference/backgrounds.ts'
+import { interaction } from '@master/internal-site/demo/reference/interaction.ts'
+import { animations } from '@master/internal-site/demo/reference/animations.ts'
+
+/** Explicit utility ownership: no catch-all scene can silently satisfy coverage. */
+export const referenceScenes: Record<string, SceneFactory> = {
+  'accent-color': interaction,
+  'animate': animations,
+  'clamp-lines': textFlow,
+  'column-count': flow,
+  'column-width': flow,
+  'white-space-collapse': textFlow,
+  'text-wrap-mode': textFlow,
+  'text-wrap-style': textFlow,
+  'align-content': alignment,
+  'align-items': alignment,
+  'align-self': alignment,
+  'animation-delay': animations,
+  'animation-direction': animations,
+  'animation-duration': animations,
+  'animation-fill-mode': animations,
+  'animation-iteration-count': animations,
+  'animation-name': animations,
+  'animation-play-state': animations,
+  'animation-timing-function': animations,
+  'appearance': interaction,
+  'aspect-ratio': sizing,
+  'backdrop-filter': effects,
+  'background-attachment': backgrounds,
+  'background-blend-mode': backgrounds,
+  'background-clip': backgrounds,
+  'background-color': backgrounds,
+  'background-image': backgrounds,
+  'background-origin': backgrounds,
+  'background-position': backgrounds,
+  'background-repeat': backgrounds,
+  'background-size': backgrounds,
+  'border-collapse': borderPaint,
+  'border-color': edges,
+  'border-image-outset': borderPaint,
+  'border-image-repeat': borderPaint,
+  'border-image-slice': borderPaint,
+  'border-image-source': borderPaint,
+  'border-image-width': borderPaint,
+  'border-radius': edges,
+  'border-style': edges,
+  'border-width': edges,
+  'box-decoration-break': borderPaint,
+  'box-shadow': edges,
+  'box-sizing': flow,
+  'break-after': flow,
+  'break-before': flow,
+  'break-inside': flow,
+  'caret-color': interaction,
+  'clear': flow,
+  'clip-path': effects,
+  'color': backgrounds,
+  'column-span': flow,
+  'contain': flow,
+  'content': typography,
+  'counter-increment': typography,
+  'counter-reset': typography,
+  'counter-set': typography,
+  'cursor': interaction,
+  'direction': textFlow,
+  'display': flow,
+  'fill': media,
+  'filter': effects,
+  'flex-basis': flexbox,
+  'flex-direction': flexbox,
+  'flex-grow': flexbox,
+  'flex-shrink': flexbox,
+  'flex-wrap': flexbox,
+  'float': flow,
+  'font-family': typeSpecimens,
+  'font-feature-settings': typeSpecimens,
+  'font-size': typeSpecimens,
+  'font-style': typeSpecimens,
+  'font-variant-numeric': typeSpecimens,
+  'font-weight': typeSpecimens,
+  'gap': sizing,
+  'grid-area': grid,
+  'grid-auto-columns': grid,
+  'grid-auto-flow': grid,
+  'grid-auto-rows': grid,
+  'grid-column': grid,
+  'grid-columns': grid,
+  'grid-row': grid,
+  'grid-rows': grid,
+  'grid-template-areas': grid,
+  'grid-template-columns': grid,
+  'grid-template-rows': grid,
+  'height': sizing,
+  'hyphens': textFlow,
+  'inset': inset,
+  'isolation': isolation,
+  'justify-content': alignment,
+  'justify-items': alignment,
+  'justify-self': alignment,
+  'letter-spacing': typeSpecimens,
+  'line-height': typeSpecimens,
+  'list-style-image': typography,
+  'list-style-position': typography,
+  'list-style-type': typography,
+  'margin': sizing,
+  'mask-image': effects,
+  'max-height': sizing,
+  'max-width': sizing,
+  'min-height': sizing,
+  'min-width': sizing,
+  'mix-blend-mode': effects,
+  'object-fit': media,
+  'object-position': media,
+  'opacity': effects,
+  'order': flexbox,
+  'outline-color': edges,
+  'outline-offset': edges,
+  'outline-style': edges,
+  'outline-width': edges,
+  'overflow': overflow,
+  'overflow-wrap': textFlow,
+  'overscroll-behavior': overscroll,
+  'padding': sizing,
+  'place-content': alignment,
+  'place-items': alignment,
+  'place-self': alignment,
+  'pointer-events': interaction,
+  'position': position,
+  'resize': interaction,
+  'screen-readers': interaction,
+  'scroll-behavior': scrolling,
+  'scroll-margin': scrolling,
+  'scroll-padding': scrolling,
+  'scroll-snap-align': scrolling,
+  'scroll-snap-stop': scrolling,
+  'scroll-snap-type': scrolling,
+  'shape-image-threshold': shapes,
+  'shape-margin': shapes,
+  'shape-outside': shapes,
+  'stroke': media,
+  'stroke-width': media,
+  'text-align': textFlow,
+  'text-decoration-color': textEffects,
+  'text-decoration-line': textEffects,
+  'text-decoration-style': textEffects,
+  'text-decoration-thickness': textEffects,
+  'text-fill-color': textEffects,
+  'text-indent': textFlow,
+  'text-orientation': textFlow,
+  'text-overflow': textFlow,
+  'text-rendering': textFlow,
+  'text-shadow': textEffects,
+  'text-size': typeSpecimens,
+  'text-stroke-color': textEffects,
+  'text-stroke-width': textEffects,
+  'text-transform': textFlow,
+  'text-underline-offset': textEffects,
+  'touch-action': interaction,
+  'transform': transforms,
+  'transform-box': transforms,
+  'transform-origin': transforms,
+  'transform-style': transforms,
+  'transition-delay': transitions,
+  'transition-duration': transitions,
+  'transition-property': transitions,
+  'transition-timing-function': transitions,
+  'user-drag': interaction,
+  'user-select': interaction,
+  'vertical-align': typeSpecimens,
+  'visibility': flow,
+  'width': sizing,
+  'will-change': transforms,
+  'word-break': textFlow,
+  'word-spacing': typeSpecimens,
+  'writing-mode': textFlow,
+  'z-index': stacking,
+}

package/src/demo/reference/scrolling.ts

@@ -0,0 +1,66 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { classValue, comparison, label } from '@master/internal-site/demo/reference/html.ts'
+
+const positionReadout = (id: string) => `<output data-scroll-readout="${id}">x 0 · y 0 px</output>`
+const scrollActions = (content: string) => `<div data-ui="scroll-actions" role="group" aria-label="Scroll destinations">${content}</div>`
+const destination = (id: string, name: string) => `<button type="button" data-scroll-to="${id}">${name}</button>`
+
+/** Keep all layout, overflow and snap prerequisites in the portable authored HTML. */
+function decorate(html: string, target: string) {
+  return html.replace(/<(div|section|article|header|nav|a)(\s[^>]*|)>/g, (tag: string, element: string, attributes: string) => {
+    const id = attributes.match(/\bid="([^"]+)"/)?.[1]
+    const ui = id === 'scrollport' ? 'scrollport'
+      : id && /^(?:overview|details|resources|panel-\d)$/.test(id) ? 'scroll-panel'
+        : element === 'header' ? 'scroll-header' : element === 'nav' ? 'scroll-actions' : undefined
+    const href = element === 'a' && attributes.match(/\bhref="#([\w-]+)"/)?.[1]
+    return `<${element}${attributes}${ui ? ` data-ui="${ui}"` : ''}${id === target ? ' data-target' : ''}${href ? ` data-scroll-to="${href}"` : ''}>`
+  })
+}
+
+export function overscroll(section: ReferenceDemoSection): DemoScene {
+  const horizontal = section.id === 'keep-horizontal-gestures-local'
+  const sample = (baseline: boolean) => {
+    const prefix = baseline ? 'auto' : 'class'
+    const outer = `${prefix}-outer`, inner = `${prefix}-inner`
+    const html = section.html[0]
+      .replace('id="outer-scroll"', `id="${outer}" data-ui="nested-outer"`)
+      .replace('id="inner-scroll"', `id="${inner}" data-ui="nested-inner"${baseline ? ' style="overscroll-behavior:auto"' : ' data-target'}`)
+      .replace(/<div class="([^\"]+)">(Inner collection|Outer collection continues)<\/div>/g, (_, classes: string, text: string) => `<div data-ui="nested-content" class="${classValue(classes)}">${text}<span aria-hidden="true">${text.startsWith('Inner') ? 'Inner end' : 'Outer end'}</span></div>`)
+    return `${scrollActions(`<button type="button" data-scroll-container="${inner}" data-scroll-edge="end">Inner to end</button><button type="button" data-scroll-container="${outer}" data-scroll-edge="start">Reset outer</button>`)}${html}<div data-ui="scroll-readings"><span>Inner ${positionReadout(inner)}</span><span>Outer ${positionReadout(outer)}</span></div>`
+  }
+  return {
+    html: comparison([{ name: 'Automatic · allows chaining', content: sample(true) }, { name: 'With class', content: sample(false) }]).replace('data-ui="comparison"', 'data-ui="comparison" data-scenario="nested-scrolling"'),
+    caption: horizontal ? 'Send the inner track to its right edge, then scroll horizontally over it. The outer x value exposes whether the gesture chains.' : 'Send the inner list to its bottom edge, then continue scrolling over it. Compare the outer y value; the iframe keeps both experiments separate from the document.',
+    inspect: ['overscroll-behavior-x', 'overscroll-behavior-y'], sizing: 'content',
+  }
+}
+
+export function scrolling(section: ReferenceDemoSection): DemoScene {
+  const { page, id } = section
+  const source = section.html[0]
+  const panels = source.includes('id="panel-1"')
+  const target = page === 'scroll-margin' ? panels ? 'panel-2' : 'details'
+    : page === 'scroll-snap-align' ? id === 'disable-item-snapping' ? 'panel-2' : 'panel-4' : page === 'scroll-snap-stop' ? 'panel-2' : 'scrollport'
+  let controls = source.includes('<nav') ? '' : scrollActions(panels
+    ? (source.includes('id="panel-6"') ? [1, 2, 4, 6] : [1, 2, 3, 4]).map(index => destination(`panel-${index}`, `Panel ${index}`)).join('')
+    : destination('overview', 'Overview') + destination('details', 'Details') + destination('resources', 'Resources'))
+  if (page === 'scroll-snap-stop') {
+    controls = scrollActions('<button type="button" data-scroll-container="scrollport" data-scroll-edge="start">Reset</button><button type="button" data-scroll-by="scrollport" data-scroll-distance="600">Advance</button>')
+  }
+  const captions: Record<string, string> = {
+    'scroll-behavior': id === 'keep-static-output-immediate' ? 'Choose a destination to make an immediate native jump.' : 'Choose a destination to trigger native navigation. Smooth timing belongs to the browser; reduced motion keeps navigation immediate.',
+    'scroll-margin': 'The blue target owns the scroll margin. Choose it to inspect the inset; its layout size and the spacing between items stay unchanged.',
+    'scroll-padding': 'The scroll container owns the viewing inset. Choose an interior target to see its alignment without reaching the track’s boundary.',
+    'scroll-snap-align': id === 'disable-item-snapping' ? 'The second panel remains in the layout but supplies no snap position. The other panels keep their start-aligned stops.' : 'Choose Panel 4 or scroll the track. Snap alignment determines where the selected item settles within the viewing area.',
+    'scroll-snap-stop': 'Reset, then Advance by the same immediate 600px request. Always stops a directional scroll at the next eligible point; normal allows it to pass.',
+    'scroll-snap-type': id === 'apply-conditionally' ? 'Resize to change both the track direction and snapping axis. The panels use the same responsive classes as the displayed HTML.' : 'Scroll the actual track. Mandatory requires an available stop; proximity leaves the browser discretion about nearby positions.',
+  }
+  const inset = page === 'scroll-margin' || page === 'scroll-padding'
+    ? `<span>Target inset <output data-scroll-offset="${panels ? 'panel-2' : 'details'}" data-scrollport="scrollport" data-scroll-axis="${panels ? 'x' : 'y'}">—</output></span>` : ''
+  const property = page === 'scroll-margin' ? panels ? 'scroll-margin-left' : 'scroll-margin-top'
+    : page === 'scroll-padding' ? panels ? 'scroll-padding-left' : 'scroll-padding-top' : page
+  return {
+    html: `${controls}${decorate(source, target)}<div data-ui="scroll-readings"><span>Scroll ${positionReadout('scrollport')}</span>${inset}</div>${page === 'scroll-snap-stop' ? label('Advance is a relative scroll request; direct endpoint navigation can skip a stop.') : ''}`,
+    caption: captions[page], inspect: [property], sizing: 'content',
+  }
+}

package/src/demo/reference/shapes.ts

@@ -0,0 +1,22 @@
+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[]> = {
+  'shape-outside': ['shape-outside'],
+  'shape-margin': ['shape-outside', 'shape-margin'],
+  'shape-image-threshold': ['shape-outside', 'shape-image-threshold'],
+}
+
+const captions: Record<string, string> = {
+  'shape-outside': 'The artwork and float box are explicit. Shape-outside changes the space available to adjacent inline content without clipping the artwork.',
+  'shape-margin': 'The same painted circle and ordinary margins are preserved. Shape-margin expands the wrap boundary within the float’s margin box.',
+  'shape-image-threshold': 'Image paint is unchanged. The browser extracts the wrap shape from pixels whose alpha exceeds the threshold; a basic shape uses its own geometry.',
+}
+
+/** Keep actual float placement, inline flow and image-alpha geometry in authored HTML. */
+export function shapes(section: ReferenceDemoSection): DemoScene {
+  return typeSpecimens(section, {
+    appearance: 'plain', properties: properties[section.page],
+    measure: true, caption: captions[section.page],
+  })
+}

package/src/demo/reference/sizing.ts

@@ -0,0 +1,43 @@
+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 properties: Record<string, string[]> = {
+  width: ['width'], height: ['height'],
+  'min-width': ['min-width'], 'min-height': ['min-height'],
+  'max-width': ['max-width'], 'max-height': ['max-height'],
+  'aspect-ratio': ['aspect-ratio'], gap: ['row-gap', 'column-gap'], margin: ['margin'], padding: ['padding'],
+}
+
+/** The displayed HTML owns every dimension, constraint, gap and content item. */
+export function sizing(section: ReferenceDemoSection): DemoScene {
+  const { page, id } = section
+  const viewportHeight = ['use-viewport-and-intrinsic-values', 'build-viewport-sections', 'use-viewport-caps'].includes(id)
+  const responsive = page === 'width' && id === 'use-container-widths-for-wrappers'
+    || page === 'max-width' && id === 'use-viewport-and-container-caps'
+  const html = section.html.map((source, index) => {
+    const prefix = section.html.length > 1 ? `example-${index}-` : ''
+    const layout = `${prefix}layout`, target = `${prefix}target`, content = `${prefix}item-3`
+    const title = source.match(/^<!-- ([^>]+) -->/)?.[1]
+    const subject = page === 'gap' ? layout : target
+    const style = properties[page].map(property => `<span>${property} <output data-style-readout="${subject}" data-style-property="${property}" data-round-pixels>—</output></span>`).join('')
+    const contentReading = page === 'padding' ? `<span>Content <output data-size-readout="${content}">—</output></span><span>Content inset <output data-position-readout="${content}" data-position-origin="${target}">—</output></span>` : ''
+    const scroll = page === 'max-height' && source.includes('tabindex="0"') ? `<span>Scroll <output data-scroll-readout="${target}">—</output></span>` : ''
+    const position = page === 'margin' ? `<span>Blue offset <output data-position-readout="${target}" data-position-origin="${layout}">—</output></span>` : ''
+    const readingSpace = page === 'min-height' && id === 'let-content-define-the-final-size' && index === 0 ? ' class="mt-xl"' : ''
+    return `<section data-ui="layout-example">${title ? label(title) : ''}${paintLayout(source, prefix, index === 0 ? page === 'gap' ? 'layout' : 'target' : '')}<div data-ui="layout-readings"${readingSpace}><span>Parent <output data-size-readout="${layout}">—</output></span><span>Blue box <output data-size-readout="${target}">—</output></span>${style}${contentReading}${position}${scroll}</div></section>`
+  }).join('')
+  const captions: Record<string, string> = {
+    width: 'The dashed outline is the authored containing block. Read the actual blue border-box width alongside its parent.',
+    height: viewportHeight ? 'This is a real 320px-tall viewport. Scroll inside it to compare the viewport-based and content-based heights.' : 'The parent and blue box are measured separately. Percentage height needs a definite reference in these normal-flow examples.',
+    'min-width': 'Compare the preferred width with its actual lower bound. The blue measurement includes padding but excludes its decorative outline.',
+    'min-height': viewportHeight ? 'The blue minimum is 100% of this 320px viewport. Scroll inside to reach the lower edge; the frame does not grow with its content.' : 'A minimum establishes a floor. Real content can make the blue box taller than that floor.',
+    'max-width': 'The maximum limits the preferred width. A viewport cap, a parent percentage and a theme token use different references.',
+    'max-height': 'The blue box is measured independently of its content. Named scroll regions keep excess content reachable with a keyboard or pointer.',
+    'aspect-ratio': 'The ratio is a preferred constraint. An automatic dimension can follow it; two definite dimensions take precedence.',
+    gap: 'The parent owns the gaps. The colored children have no margins; extra space at the outer edge is not a gap.',
+    margin: 'Margin is outside the painted blue border box. The dashed parent shows its actual position and surrounding space.',
+    padding: 'Blue surrounds the neutral content. The content inset reports physical left and top padding; the padding value lists the physical sides.',
+  }
+  return { html, caption: captions[page], height: viewportHeight ? 320 : undefined, sizing: viewportHeight ? 'viewport' : 'content', responsive: responsive || undefined, inspect: id === 'apply-conditionally' ? [] : undefined }
+}

package/src/demo/reference/source.ts

@@ -0,0 +1,8 @@
+import { readFile } from 'node:fs/promises'
+import type { ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+
+/** Authored specimens retained for the site design-system gallery, independent of retired articles. */
+export async function referenceDemoSections(page: string): Promise<ReferenceDemoSection[]> {
+  if (!/^[a-z][a-z0-9-]+$/.test(page)) throw new Error(`Invalid demo specimen: ${page}`)
+  return JSON.parse(await readFile(new URL(`../specimens/${page}.json`, import.meta.url), 'utf8'))
+}

package/src/demo/reference/text-effects.ts

@@ -0,0 +1,37 @@
+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[]> = {
+  'text-decoration': ['text-decoration-line', 'text-decoration-style', 'text-decoration-color', 'text-decoration-thickness'],
+  'text-decoration-color': ['color', 'text-decoration-color', 'text-decoration-line'],
+  'text-decoration-line': ['text-decoration-line', 'text-decoration-style', 'text-decoration-color'],
+  'text-decoration-style': ['text-decoration-line', 'text-decoration-style', 'text-decoration-thickness'],
+  'text-decoration-thickness': ['text-decoration-line', 'text-decoration-thickness', 'text-underline-offset'],
+  'text-underline-offset': ['text-underline-offset', 'text-decoration-thickness'],
+  'text-fill-color': ['color', '-webkit-text-fill-color'],
+  'text-shadow': ['text-shadow'],
+  'text-stroke': ['-webkit-text-stroke-width', '-webkit-text-stroke-color', '-webkit-text-fill-color'],
+  'text-stroke-color': ['-webkit-text-stroke-color', '-webkit-text-stroke-width', '-webkit-text-fill-color'],
+  'text-stroke-width': ['-webkit-text-stroke-width', '-webkit-text-stroke-color'],
+}
+const captions: Record<string, string> = {
+  'text-decoration': 'The readings describe the element that originates the decoration. A descendant can have no decoration of its own while the ancestor’s line still paints through its inline text.',
+  'text-decoration-color': 'Compare the actual foreground and line colors. A transparent decoration hides its paint without hiding the glyphs.',
+  'text-decoration-line': 'Choose the decoration line independently from its style, color and thickness.',
+  'text-decoration-style': 'The authored underline supplies a real line. Its style changes the pattern while preserving its thickness.',
+  'text-decoration-thickness': 'The computed value can remain auto or from-font; those keywords are not pixel measurements. Explicit thickness changes paint without resizing the text box.',
+  'text-underline-offset': 'The underline moves relative to the text baseline. Offset does not add padding or increase the line box.',
+  'text-fill-color': 'Glyph fill is independent of the foreground color. The plain surface adds no fill, stroke or background to the subject.',
+  'text-shadow': 'These are native glyph shadows. The surrounding surface gives the paint room; the shadow does not increase the text’s layout box.',
+  'text-stroke': 'The authored width, edge color and fill determine the visible glyph. A transparent fill needs a visible outline; zero-width strokes paint no edge.',
+  'text-stroke-color': 'Every specimen supplies a nonzero stroke width. Changing edge color leaves the fill and font geometry intact.',
+  'text-stroke-width': 'Compare the same glyphs at the same font size. The width changes the painted edge; box measurements expose the unchanged layout geometry.',
+}
+
+/** Leave the authored glyph paint untouched; keep labels and readings outside it. */
+export function textEffects(section: ReferenceDemoSection): DemoScene {
+  return typeSpecimens(section, {
+    properties: properties[section.page], caption: captions[section.page],
+    appearance: 'plain', measure: true,
+  })
+}

package/src/demo/reference/text-flow.ts

@@ -0,0 +1,41 @@
+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[]> = {
+  'text-align': ['text-align', 'direction'], 'text-indent': ['text-indent'],
+  'text-transform': ['text-transform'], 'text-wrap-mode': ['text-wrap-mode'], 'text-wrap-style': ['text-wrap-style'],
+  'white-space-collapse': ['white-space-collapse'], 'word-break': ['word-break'],
+  'overflow-wrap': ['overflow-wrap'], 'hyphens': ['hyphens'],
+  'clamp-lines': ['-webkit-line-clamp', 'display', 'overflow'],
+  'text-overflow': ['text-overflow', 'white-space', 'overflow'],
+  'direction': ['direction', 'unicode-bidi'],
+  'writing-mode': ['writing-mode', 'text-orientation'],
+  'text-orientation': ['writing-mode', 'text-orientation'],
+  'text-rendering': ['text-rendering'],
+}
+const captions: Record<string, string> = {
+  'text-align': 'The blue outline is the paragraph’s box. Alignment moves its inline content; it does not position the paragraph itself.',
+  'text-indent': 'Follow the first line’s starting edge. Later lines retain their normal position inside the same paragraph.',
+  'text-transform': 'The browser changes the presentation. The authored words, language and underlying text remain intact.',
+  'text-wrap-mode': 'Wrapping controls whether text fits within the available inline size.',
+  'text-wrap-style': 'The text and line width are identical across the comparison. Exact breaks depend on the browser’s wrapping algorithm and loaded font.',
+  'white-space-collapse': 'The specimens preserve the exact spaces and line breaks in the adjacent source. Annotation text stays outside that context.',
+  'word-break': 'Real text and native line-breaking rules determine the result. Any deliberate overflow remains available in the named scroll region.',
+  'overflow-wrap': 'Compare the authored constraints and actual box sizes. Emergency breaks and intrinsic width are separate parts of text layout.',
+  'hyphens': 'Automatic hyphenation depends on the declared language and the browser’s dictionaries. Manual soft hyphens provide explicit opportunities.',
+  'clamp-lines': 'Clamping limits the visible lines. Preserve the complete source and provide another reading path whenever the omitted text is needed.',
+  'text-overflow': 'A marker needs actual clipped inline content. The example owns its width, display, wrapping and overflow rules.',
+  'direction': 'Language and semantic direction remain in the markup. CSS direction sets the local base direction without reversing the source characters.',
+  'writing-mode': 'Writing mode sets line orientation and block progression. The authored dimensions make the column direction visible.',
+  'text-orientation': 'These are native vertical text runs. Compare Latin and CJK glyph orientation without rotating the entire element.',
+  'text-rendering': 'This is a rendering hint, not a measured speed or quality improvement. Visible differences depend on the browser, platform and font.',
+}
+
+/** Use the authored language, whitespace, nested context and clipping prerequisites. */
+export function textFlow(section: ReferenceDemoSection): DemoScene {
+  return typeSpecimens(section, {
+    properties: properties[section.page], measure: true,
+    caption: captions[section.page],
+    pseudo: section.page === 'text-transform' && section.id === 'sentence' ? '::first-letter' : undefined,
+  })
+}

package/src/demo/reference/transforms.ts

@@ -0,0 +1,26 @@
+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[]> = {
+  'transform': ['transform', 'transform-origin'],
+  'transform-origin': ['transform-origin', 'transform'],
+  'transform-box': ['transform-box'],
+  'transform-style': ['transform-style', 'opacity'],
+  'will-change': ['will-change', 'transform', 'opacity'],
+}
+const captions: Record<string, string> = {
+  'transform': 'The authored guide keeps the original layout slot visible. Client bounds follow the transformed element’s getBoundingClientRect, not its unchanged layout dimensions.',
+  'transform-origin': 'The reference dimensions, pivot and transform are authored together. Markers stay outside the transformed element; the guides reveal displacement while client bounds report transformed width and height.',
+  'transform-box': 'The complete HTML or SVG preserves source geometry. Reference boxes control percentages and pivots; client bounds use getBoundingClientRect and do not include an SVG stroke’s full paint.',
+  'transform-style': 'The parent, front layer and perspective form a real 3D context. Compare the child’s geometry: grouping effects can flatten it even when the computed keyword remains preserve-3d.',
+  'will-change': 'The readout observes the actual hint. Native controls remain visible and operable; this specimen does not measure speed or prove compositing-layer promotion.',
+}
+
+/** Keep native control states, SVG coordinates and nested 3D contexts in authored HTML. */
+export function transforms(section: ReferenceDemoSection): DemoScene {
+  return typeSpecimens(section, {
+    appearance: 'plain', properties: properties[section.page],
+    measure: section.page !== 'transform-style', measureLabel: 'Client bounds',
+    caption: captions[section.page],
+  })
+}

package/src/demo/reference/transitions.ts

@@ -0,0 +1,24 @@
+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[]> = {
+  'transition': ['transition-property', 'transition-duration', 'transition-timing-function', 'transition-delay'],
+  'transition-property': ['transition-property', 'transition-duration'],
+  'transition-duration': ['transition-duration', 'transition-timing-function'],
+  'transition-delay': ['transition-delay', 'transition-duration'],
+  'transition-timing-function': ['transition-timing-function', 'transition-duration'],
+}
+const captions: Record<string, string> = {
+  'transition': 'The native control changes an authored CSS endpoint. The transition comes from the displayed classes; reduced motion and print keep the update immediate.',
+  'transition-property': 'Each control changes the same authored endpoints. Only properties in the selected list interpolate; unrelated changes remain immediate.',
+  'transition-duration': 'The control, travel distance and easing stay explicit. Duration is the interpolation interval, independent of any start delay.',
+  'transition-delay': 'The visible control changes the endpoint before the layer starts moving. Each changing child owns its duration and delay; they are not inherited.',
+  'transition-timing-function': 'The native transition keeps its authored duration and endpoints. Compare how the curve distributes progress, or how steps advances at discrete boundaries.',
+}
+
+/** Native controls and complete authored states own each transition timeline. */
+export function transitions(section: ReferenceDemoSection): DemoScene {
+  return typeSpecimens(section, {
+    appearance: 'plain', properties: properties[section.page], caption: captions[section.page],
+  })
+}

package/src/demo/reference/type-specimens.ts

@@ -0,0 +1,56 @@
+import type { DemoScene, ReferenceDemoSection } from '@master/internal-site/demo/reference/types.ts'
+import { escape, label } from '@master/internal-site/demo/reference/html.ts'
+
+const properties: Record<string, string[]> = {
+  'font-family': ['font-family'], 'font-size': ['font-size', 'line-height'],
+  'font-weight': ['font-weight'], 'font-style': ['font-style'],
+  'font-feature-settings': ['font-feature-settings'], 'font-variant-numeric': ['font-variant-numeric'],
+  'letter-spacing': ['letter-spacing'], 'word-spacing': ['word-spacing'],
+  'line-height': ['font-size', 'line-height'], 'vertical-align': ['vertical-align'],
+  'text-size': ['font-size', 'line-height', 'letter-spacing'],
+}
+
+/** Keep authored inline contexts, inheritance, font resources and table structure intact. */
+export function typeSpecimens(section: ReferenceDemoSection, options?: { properties: string[], caption: string, measure?: boolean, measureLabel?: string, pseudo?: string, appearance?: 'plain' }): DemoScene {
+  const { page, id } = section
+  let head = '', bodyClass = ''
+  const html = section.html.map((source, index) => {
+    const prefix = section.html.length > 1 ? `example-${index}-` : ''
+    const title = source.match(/^<!-- ([^>]+) -->/)?.[1]
+    head += source.match(/<head>([\s\S]*?)<\/head>/)?.[1] ?? ''
+    const body = source.match(/<body(?: class="([^"]*)")?>([\s\S]*?)<\/body>/)
+    if (body) { bodyClass = body[1] ?? ''; source = body[2] }
+    const target = `${prefix}target`
+    const ids = new Set([...source.matchAll(/\bid="([^"]+)"/g)].map(match => match[1]))
+    let content = source.replace(/\bid="([^"]+)"/g, (_, name: string) => `id="${prefix}${name}"${name === 'target' ? ` data-target data-ui="type-target"${options?.appearance ? ` data-appearance="${options.appearance}"` : ''}` : ''}`)
+    // Independent comparisons scope both IDs and their native/accessible references.
+    if (prefix) {
+      content = content.replace(/\b(for|list|headers|aria-labelledby|aria-describedby|aria-controls|aria-activedescendant|aria-details|aria-errormessage|aria-owns|aria-flowto|popovertarget)="([^"]+)"/g,
+        (_, attribute: string, value: string) => `${attribute}="${value.split(/\s+/).map(id => ids.has(id) ? prefix + id : id).join(' ')}"`)
+      content = content.replace(/\bhref="#([^"]+)"/g, (attribute, id: string) => ids.has(id) ? `href="#${prefix}${id}"` : attribute)
+    }
+    const observed = options?.properties ?? (page === 'font-feature-settings' && id === 'prefer-semantic-numeric-utilities' ? [...properties[page], 'font-variant-numeric'] : properties[page])
+    const readings = observed.map(property => `<span>${options?.pseudo ? `${escape(options.pseudo)} ` : ''}${property} <output data-style-readout="${target}" data-style-property="${property}" ${options?.pseudo ? `data-style-pseudo="${escape(options.pseudo)}" ` : ''}${/^(font-size|line-height)$/.test(property) ? 'data-round-pixels' : ''}>—</output></span>`).join('')
+    const runs = ['ones', 'eights', 'inherited'].filter(name => source.includes(`id="${name}"`)).map(name => `<span>${name} <output data-size-readout="${prefix}${name}">—</output></span>`).join('')
+    const size = options?.measure ? `<span>${escape(options.measureLabel ?? 'Box')} <output data-size-readout="${target}">—</output></span>` : source.match(/id="target" class="[^"]*\binline-block\b/) && /letter-spacing|word-spacing/.test(page) ? `<span>Run box <output data-size-readout="${target}">—</output></span>` : ''
+    const family = page === 'font-family' && id === 'google-fonts' ? 'Roboto'
+      : page === 'font-family' && id === 'self-hosted-fonts' ? 'Geist'
+        : page === 'font-variant-numeric' && id === 'show-slashed-zeroes' ? 'JetBrains Mono' : undefined
+    const loading = family ? `<span>${escape(family)} <output data-font-status="${escape(family)}">Checking font…</output></span>` : ''
+    return `<section data-ui="type-example" data-tone="${index % 2 ? 'violet' : 'blue'}">${title ? label(title) : ''}<div data-ui="type-surface">${content}</div><div data-ui="type-readings">${readings}${runs}${size}${loading}</div></section>`
+  }).join('')
+  const captions: Record<string, string> = {
+    'font-family': 'The examples keep their real inheritance and font sources. A computed family list names the requested stack; it does not identify which face rendered every glyph.',
+    'font-size': 'Read the computed font size and line height separately. The preview grows with its content, so a larger type size remains visible.',
+    'font-weight': 'The local variable font supports 100–900. Every specimen keeps the same text; available faces determine the result in another family.',
+    'font-style': id === 'reset-font-style' ? 'The blue child resets its inherited slant. The surrounding words keep their italic style.' : 'The readout follows the styled subject. The selected font and available faces determine whether the browser uses a designed or synthesized slant.',
+    'font-feature-settings': 'Glyph-run measurements include the actual text advance. Raw feature settings are reported independently of numeric variants.',
+    'font-variant-numeric': 'The selected font must support the feature. Compare actual digits as well as computed values; equal digit counts make advances comparable.',
+    'letter-spacing': 'The label, computed value and comparison stay outside the text context. Tracking can also change wrapping.',
+    'line-height': 'The readout is the computed line height, not glyph height. Mixed sizes, inline objects and inherited values can affect the final line box.',
+    'word-spacing': 'The value adds to the normal word separator. Compare the same content at the same size to isolate the effect.',
+    'vertical-align': 'These are actual inline boxes and table cells. The annotations are outside the formatting context and cannot become extra inline content.',
+    'text-size': 'One utility controls three properties. Compare the actual size, leading and tracking at the preview’s reading width.',
+  }
+  return { html, head, bodyClass, caption: options?.caption ?? captions[page], sizing: 'content', responsive: page === 'font-size' && id === 'use-an-explicit-font-size' || undefined, inspect: [] }
+}

package/src/demo/reference/types.ts

@@ -0,0 +1,30 @@
+export interface ReferenceDemoSection {
+  page: string
+  id: string
+  title: string
+  html: string[]
+  css: string
+  classes: string[]
+  classLists: string[]
+  highlighted: string[]
+}
+
+export interface DemoScene {
+  html: string
+  /** Trusted resources and body classes from authored whole-document examples. */
+  head?: string
+  bodyClass?: string
+  /** Supporting interface only; taught class examples must remain independent of private ui-* styles. */
+  systemButtons?: boolean
+  caption: string
+  height?: number
+  maxWidth?: number
+  sizing?: 'viewport' | 'content'
+  inspect?: string[]
+  motion?: boolean
+  theme?: boolean
+  responsive?: boolean
+  css?: string
+}
+
+export type SceneFactory = (section: ReferenceDemoSection) => DemoScene

package/src/demo/reference/typography.ts

@@ -0,0 +1,32 @@
+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[]> = {
+  content: ['content'],
+  'counter-increment': ['counter-increment'],
+  'counter-reset': ['counter-reset'],
+  'counter-set': ['counter-set', 'counter-increment'],
+  'list-style': ['list-style-type', 'list-style-position', 'list-style-image'],
+  'list-style-image': ['list-style-image', 'list-style-type', 'list-style-position'],
+  'list-style-position': ['list-style-position', 'list-style-type'],
+  'list-style-type': ['list-style-type', 'list-style-position', 'list-style-image'],
+}
+const captions: Record<string, string> = {
+  content: 'The readout observes the actual ::after pseudo-element. The link remains a native, keyboard-accessible anchor with meaningful text in the HTML.',
+  'counter-increment': 'The first heading or item supplies the reported increment. The visible prefixes are resolved by the browser’s native counter, not inserted numbers.',
+  'counter-reset': 'The readout reports the scope’s initial counter declaration. Each item then changes the value before its generated prefix is painted.',
+  'counter-set': 'The readout follows the element that sets the counter. Reset, increment and set are separate operations; following elements continue from the resulting value.',
+  'list-style': 'The authored list keeps real list items and room for outside markers. Read the type, position and image properties independently.',
+  'list-style-image': 'These are native image markers. The image takes precedence over the type; the type remains available when the image is absent or unavailable.',
+  'list-style-position': 'Identical content and width reveal the wrapped-line alignment. Marker position is independent of the surrounding label and property readout.',
+  'list-style-type': 'Marker appearance does not change the list’s HTML meaning. The readout distinguishes the requested type from a potentially overriding image.',
+}
+
+/** Keep counter scopes, descendant selectors and semantic list structure exactly as authored. */
+export function typography(section: ReferenceDemoSection): DemoScene {
+  if (!properties[section.page]) throw new Error(`Unassigned typography recipe: ${section.page}#${section.id}`)
+  return typeSpecimens(section, {
+    properties: properties[section.page], caption: captions[section.page],
+    appearance: 'plain', pseudo: section.page === 'content' ? '::after' : undefined,
+  })
+}