@master/internal-site 0.0.0-stage → 0.1.0

package/src/demo/DemoConfiguredExample.astro

@@ -0,0 +1,48 @@
+---
+import Code from '@master/internal-site/components/Code.astro'
+import CodeTabs from '@master/internal-site/components/CodeTabs.astro'
+import Demo from '@master/internal-site/demo/Demo.svelte'
+import DemoGeneratedCSS from '@master/internal-site/demo/DemoGeneratedCSS.svelte'
+import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
+import { demoDocument } from '@master/internal-site/demo/reference/document.ts'
+import { configuredExampleCSS, configuredMarkupClasses } from '@master/internal-site/css/configured-example.ts'
+
+export interface DemoConfiguredExampleProps {
+  name: string
+  title: string
+  source: string
+  /** Trusted site-authored markup; never pass user-provided HTML. */
+  html: string
+  caption: string
+  theme?: boolean
+  code?: boolean
+  /** Render generated utilities inside a real, declarative shadow root. */
+  shadow?: boolean
+  responsive?: boolean
+  /** The lesson is a container, not the viewport: no browser chrome, and the range is named for what it sizes. */
+  container?: boolean
+  motion?: boolean
+  widthPresets?: readonly { label: string; width: number }[]
+}
+type Props = DemoConfiguredExampleProps
+
+/**
+ * One tray: the preview, its CSS and markup, and the closed generated stylesheet share the same literal source.
+ * The CSS is beautified: MDX strips up to two spaces from each line of a multi-line attribute literal.
+ */
+const { name, title, source, html, caption, theme, code = true, shadow = false, responsive, container = false, motion, widthPresets } = Astro.props
+const section = { page: 'project-styles', id: name, title, html: [html], css: source, classes: [], classLists: [], highlighted: [] }
+const generated = configuredExampleCSS(source, configuredMarkupClasses(html))
+const preview = shadow ? `<div data-demo-shadow><template shadowrootmode="open"><style>${generated.replaceAll('</style', '<\\/style')}</style>${html}</template></div>` : html
+const document = demoDocument(section, { html: preview, caption, bodyClass: 'p-md p(8)@media(width<240px)', motion })
+---
+
+<Demo title={title} caption={caption} frame="none" data-project-style={name}>
+  {code && <Fragment slot="source">
+    {source.trim()
+      ? <CodeTabs tabs={[{ name: 'CSS', lang: 'css', beautify: true, code: source }, { name: 'HTML', lang: 'html', beautify: true, code: html }]} />
+      : <Code lang="html" beautify code={html} />}
+    <DemoGeneratedCSS><Code lang="css" beautify code={generated} /></DemoGeneratedCSS>
+  </Fragment>}
+  <DemoViewport client:idle={{ timeout: 500 }} title={title} document={document} theme={theme} responsive={responsive} chrome={container ? false : undefined} rangeLabel={container ? 'Container' : undefined} widthPresets={widthPresets} motion={motion} sizing="content" />
+</Demo>

package/src/demo/DemoContainer.svelte

@@ -0,0 +1,48 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import Demo, { type DemoNode } from '@master/internal-site/demo/Demo.svelte'
+
+  /** One tray whose tools change a real wrapper's width; children own their query container and layout. */
+  let { children, title, caption, maxWidth = 720, ...props }: Omit<HTMLAttributes<HTMLElement>, 'title' | 'style' | 'children'> & {
+    children?: Snippet, title: string, caption?: DemoNode, maxWidth?: number
+  } = $props()
+  let width = $state<number>()
+  let measured = $state(480)
+  let minimumWidth = $state(240)
+  let ready = $state(false)
+  let element = $state<HTMLDivElement>()
+  const id = $props.id()
+  $effect(() => {
+    if (!element) return
+    const target = element
+    const stage = target.parentElement!
+    const limit = maxWidth
+    const observer = new ResizeObserver(() => {
+      measured = Math.round(target.getBoundingClientRect().width)
+      const style = getComputedStyle(stage)
+      const available = stage.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight)
+      minimumWidth = Math.min(240, Math.round(available), limit)
+      ready = true
+    })
+    observer.observe(target)
+    observer.observe(stage)
+    return () => observer.disconnect()
+  })
+  const value = $derived(width ?? Math.min(measured, maxWidth))
+  const range = $derived(Math.max(1, maxWidth - minimumWidth))
+</script>
+
+{#snippet controls()}
+  <label class="ui-label" data-case="as-is" for={id}>Container</label>
+  <input {id} class="ui-range" type="range" min={minimumWidth} max={maxWidth} step="1" disabled={!ready} {value}
+    style:--value={`${((value - minimumWidth) / range) * 100}%`} style:width="128px" style:max-width="100%"
+    oninput={event => { width = Number(event.currentTarget.value) }} />
+  <button type="button" class="ui-button" data-size="sm" disabled={!ready} onclick={() => { width = undefined }}>Fit</button>
+  <output class="ui-label" data-case="as-is">{ready ? `${measured} px · viewport unchanged` : 'Measuring container…'}</output>
+{/snippet}
+
+<Demo {...props} {title} {caption} padding="sm" data-ready={ready} {controls}>
+  <div bind:this={element} data-demo-container="" style:width={width ? `${width}px` : `min(100%, ${maxWidth}px)`} style:max-width="100%">{@render children?.()}</div>
+</Demo>

package/src/demo/DemoControls.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import { styleText, type DemoStyle } from '@master/internal-site/demo/style.ts'
+
+  /** A labelled group of controls. `segmented` draws the sunken track with raised selected buttons. */
+  let { label = 'Demo controls', variant = 'plain', class: className, style, children, ...props }: Omit<HTMLAttributes<HTMLDivElement>, 'style'> & {
+    label?: string
+    variant?: 'plain' | 'segmented'
+    style?: DemoStyle
+    children?: Snippet
+  } = $props()
+</script>
+
+<div {...props} role="group" aria-label={label} class={[variant === 'segmented' ? 'ui-segmented' : 'flex flex-wrap items-center gap-xs', className]} style={styleText(style)}>{@render children?.()}</div>

package/src/demo/DemoCopyButton.svelte

@@ -0,0 +1,50 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+  import type { HTMLButtonAttributes } from 'svelte/elements'
+  import IconCopy from '@tabler/icons-svelte-runes/icons/copy'
+  import { getCopyFeedback, type CopyResult } from '@master/internal-site/demo/copy-feedback.ts'
+  import { styleText, type DemoStyle } from '@master/internal-site/demo/style.ts'
+
+  interface Props extends Omit<HTMLButtonAttributes, 'onclick' | 'value' | 'style' | 'children'> {
+    value: string
+    label: string
+    /** Replaces the copy icon; `null` renders none. */
+    icon?: Snippet | null
+    /** Short status for a specimen that already displays the copied value. */
+    feedback?: 'value' | 'compact'
+    style?: DemoStyle
+    children?: Snippet
+  }
+
+  /** The visible status describes the actual clipboard result, including denial. */
+  let { value, label, icon, feedback = 'value', children, class: className, style, ...props }: Props = $props()
+  const notify = getCopyFeedback()
+  let status = $state<{ message: string, result: CopyResult }>({ message: '', result: undefined })
+  let busy = $state(false)
+  const report = notify ?? ((message: string, result: CopyResult) => { status = { message, result } })
+  async function copy() {
+    if (busy) return
+    busy = true
+    report('Copying…', undefined)
+    try {
+      if (!window.isSecureContext || !navigator.clipboard?.writeText) throw new Error('Clipboard unavailable')
+      await navigator.clipboard.writeText(value)
+      report(feedback === 'compact' ? 'Copied' : `Copied ${value}`, 'success')
+    } catch {
+      report(feedback === 'compact' ? 'Copy unavailable' : `Copy unavailable: ${value}`, 'error')
+    } finally { busy = false }
+  }
+</script>
+
+{#snippet button()}
+  <button data-size={className ? undefined : 'sm'} {...props} type="button" aria-label={label} class={className ?? 'ui-button'} style={styleText(style)} aria-busy={busy} onclick={copy}>
+    {#if icon === undefined}<IconCopy aria-hidden="true" />{:else if icon}{@render icon()}{/if}{@render children?.()}
+  </button>
+{/snippet}
+
+<!-- Grouped buttons report to the shared status and stay direct children of their layout. -->
+{#if notify}
+  {@render button()}
+{:else}
+  <span class="ui-copy">{@render button()}<span class="ui-copy-status" role="status" data-result={status.result}>{status.message}</span></span>
+{/if}

package/src/demo/DemoCopyGroup.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+  import { setCopyFeedback, type CopyResult } from '@master/internal-site/demo/copy-feedback.ts'
+
+  /** One status for a set of copy actions, such as a palette. The buttons must render in this group's Svelte tree. */
+  let { children, instruction = 'Select a swatch to copy its variable.' }: { children?: Snippet, instruction?: string } = $props()
+  let state = $state<{ instruction: string, message: string, result: CopyResult }>()
+  const current = $derived(state?.instruction === instruction ? state : undefined)
+  setCopyFeedback((message, result) => { state = { instruction, message, result } })
+</script>
+
+<div class="grid gap-sm">
+  <p class="m(0) ui-copy"><span class="ui-copy-status" role="status" data-result={current?.result}>{current?.message ?? instruction}</span></p>
+  {@render children?.()}
+</div>

package/src/demo/DemoExample.astro

@@ -0,0 +1,27 @@
+---
+import Demo from '@master/internal-site/demo/Demo.svelte'
+import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
+import { referenceDemoSections } from '@master/internal-site/demo/reference/source.ts'
+import { referenceScenes } from '@master/internal-site/demo/reference/scenes.ts'
+import { demoDocument } from '@master/internal-site/demo/reference/document.ts'
+
+interface Props {
+  page: string
+  section: string
+}
+
+const { page, section } = Astro.props
+const source = (await referenceDemoSections(page)).find(item => item.id === section)
+if (!source) throw new Error(`Missing demo source: ${page}#${section}`)
+const factory = referenceScenes[page]
+if (!factory) throw new Error(`Missing demo scene: ${page}`)
+const scene = factory(source)
+const responsive = source.classes.some(value => /(?:@|&)(?:sm|md|lg|xl|[\d.]+(?:px|rem))\b/.test(value))
+const themed = source.classes.some(value => /@(?:dark|light)\b/.test(value))
+const printable = source.classes.some(value => value.includes('@media(print)'))
+---
+
+<Demo title={source.title} frame="none" caption={scene.caption} data-demo-case={`${page}#${section}`}>
+  <DemoViewport client:idle={{ timeout: 500 }} title={`${page}: ${source.title}`} document={demoDocument(source, scene)} responsive={scene.responsive ?? responsive}
+    theme={scene.theme ?? themed} print={printable} motion={scene.motion} inspect={scene.inspect ?? (section === 'apply-conditionally' ? [page] : undefined)} height={scene.height} maxWidth={scene.maxWidth} sizing={scene.sizing} />
+</Demo>

package/src/demo/DemoFeatureSupport.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import { onMount } from 'svelte'
+
+  /** Reports syntax support only; the example still owns its native CSS behavior. */
+  let { condition }: { condition: string } = $props()
+  // The server and the first client render agree on "unknown"; the browser answers after mount.
+  let mounted = $state(false)
+  onMount(() => { mounted = true })
+  const supported = $derived(mounted ? CSS.supports(condition) : null)
+</script>
+
+<p class="flex flex-wrap items-center gap-xs m(0)" data-supported={supported ?? 'unknown'}>
+  <code class="ui-inline-code">{condition}</code>
+  <span class="ui-badge" data-variant="dot" data-tone={supported ? 'green' : undefined}>
+    {supported === null ? 'Checking…' : supported ? 'Supported' : 'Not supported'}
+  </span>
+</p>

package/src/demo/DemoGeneratedCSS.svelte

@@ -0,0 +1,8 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+
+  /** The complete generated stylesheet stays one native, closed disclosure under the source. */
+  let { children }: { children?: Snippet } = $props()
+</script>
+
+<details class="ui-disclosure"><summary>Generated CSS</summary>{@render children?.()}</details>

package/src/demo/DemoIndex.astro

@@ -0,0 +1,23 @@
+---
+import '@master/internal-site/styles/system/specimens.css'
+
+export interface DemoIndexGroup {
+  title: string
+  links: readonly { href: string, label: string }[]
+}
+
+interface Props {
+  label: string
+  groups: readonly DemoIndexGroup[]
+}
+
+/** Native links keep catalog navigation available before hydration. */
+const { label, groups } = Astro.props
+---
+
+<nav class="grid gap-md" aria-label={label}>
+  {groups.map(group => <div class="grid gap-xs">
+    <p class="m(0) ui-label">{group.title}</p>
+    <ul class="flex flex-wrap gap-2xs m(0) p(0) (list-style:none)">{group.links.map(link => <li><a class="ui-button" data-size="sm" href={link.href}>{link.label}</a></li>)}</ul>
+  </div>)}
+</nav>

package/src/demo/DemoInstallation.astro

@@ -0,0 +1,17 @@
+---
+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'
+
+/** Keep integration examples isolated from article typography and site-only utilities. */
+const html = '<p id="master-check" class="w-fit m(0) p-md b-solid b(1) b-line-divider r-md text-sm font-regular bg-surface-raised fg-text-strong">Hello World</p>'
+const title = 'Check the installed styles'
+const caption = 'A neutral surface, a fine border, small corners and 1rem of padding on every side.'
+const section = { page: 'installation', id: 'check', title, html: [html], css: '', classes: [], classLists: [], highlighted: [] }
+const document = demoDocument(section, { html, caption, bodyClass: 'p-md' })
+---
+
+<Demo title={title} caption={caption} frame="none">
+  <Fragment slot="source"><slot /></Fragment>
+  <DemoViewport client:idle={{ timeout: 500 }} title={title} document={document} sizing="content" />
+</Demo>

package/src/demo/DemoItem.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import { styleText, type DemoStyle } from '@master/internal-site/demo/style.ts'
+  import { tone, type DemoTone } from '@master/internal-site/demo/tone.ts'
+
+  /** A tile that stands for content. Utilities on the item set its size and layout. */
+  let { tone: value = 'neutral', variant = 'soft', class: className, style, children, ...props }: Omit<HTMLAttributes<HTMLDivElement>, 'style'> & {
+    tone?: DemoTone
+    variant?: 'soft' | 'solid' | 'outline' | 'ghost'
+    style?: DemoStyle
+    children?: Snippet
+  } = $props()
+</script>
+
+<div {...props} data-tone={tone(value)} data-variant={variant === 'soft' ? undefined : variant} class={['ui-item', className]} style={styleText(style)}>{@render children?.()}</div>

package/src/demo/DemoLabel.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import { styleText, type DemoStyle } from './style'
+
+  /** Names a condition outside the measured layout. Class names and values keep their case unless `upper` is set. */
+  let { upper = false, class: className, style, children, ...props }: Omit<HTMLAttributes<HTMLSpanElement>, 'style'> & {
+    upper?: boolean
+    style?: DemoStyle
+    children?: Snippet
+  } = $props()
+</script>
+
+<span {...props} data-case={upper ? undefined : 'as-is'} class={['ui-label', className]} style={styleText(style)}>{@render children?.()}</span>

package/src/demo/DemoLegend.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import { styleText, type DemoStyle } from '@master/internal-site/demo/style.ts'
+  import { tone, type DemoTone } from '@master/internal-site/demo/tone.ts'
+
+  let { items, class: className, style, ...props }: Omit<HTMLAttributes<HTMLUListElement>, 'style' | 'children'> & {
+    items: { label: string, tone: DemoTone }[]
+    style?: DemoStyle
+  } = $props()
+</script>
+
+<ul {...props} class={['ui-legend', className]} style={styleText(style)} aria-label="Legend">
+  {#each items as { label, tone: value } (label)}<li><i data-tone={tone(value)} aria-hidden="true"></i>{label}</li>{/each}
+</ul>

package/src/demo/DemoMeasure.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import type { Snippet } from 'svelte'
+
+  /** A dedicated measurement wrapper, never inserted between layout items and their parent. */
+  let { children, label = 'Bounds' }: { children?: Snippet, label?: string } = $props()
+  let element = $state<HTMLDivElement>()
+  let size = $state<{ width: number, height: number }>()
+  $effect(() => {
+    if (!element) return
+    const target = element
+    const observer = new ResizeObserver(() => {
+      const bounds = target.getBoundingClientRect()
+      size = { width: Math.round(bounds.width), height: Math.round(bounds.height) }
+    })
+    observer.observe(target)
+    return () => observer.disconnect()
+  })
+</script>
+
+<div class="ui-measure">
+  <div class="ui-measure-head">
+    <span>{label}</span>
+    <output aria-label={`${label} dimensions`}>{size ? `${size.width} × ${size.height} px` : 'Measuring…'}</output>
+  </div>
+  <div class="ui-measure-rule" aria-hidden="true"></div>
+  <div bind:this={element}>{@render children?.()}</div>
+</div>

package/src/demo/DemoMedia.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import type { ClassValue } from 'svelte/elements'
+  import type { SVGAttributes } from 'svelte/elements'
+  import Image, { type ImageProps as SiteImageProps } from '@master/internal-site/components/Image.svelte'
+  import { styleText, type DemoStyle } from '@master/internal-site/demo/style.ts'
+  import type { DemoTone } from '@master/internal-site/demo/tone.ts'
+
+  // A media specimen exposes its presentation and accessible name, not every
+  // incompatible DOM event signature of both SVG and HTML image elements.
+  interface MediaAttributes {
+    class?: ClassValue
+    id?: string
+    width?: number | `${number}`
+    height?: number | `${number}`
+    'aria-label'?: string
+    'aria-hidden'?: boolean | 'true' | 'false'
+  }
+  type ImageProps = MediaAttributes & Pick<SiteImageProps, 'loading' | 'priority' | 'quality' | 'sizes' | 'fill' | 'placeholder'> & { src: string, alt: string, tone?: never, style?: string }
+  type VectorProps = MediaAttributes & { src?: never, alt?: never, tone?: DemoTone, style?: DemoStyle }
+
+  /** Original artwork in a teaching tone, or a real image with its intrinsic size. */
+  let { src, alt, tone: value = 'neutral', style, ...props }: ImageProps | VectorProps = $props()
+</script>
+
+{#if src !== undefined}
+  {@const imageProps: SiteImageProps = { width: 320, height: 200, ...(props as Omit<ImageProps, 'src' | 'alt' | 'style'>), style: styleText(style), src, alt: alt! }}
+  <Image {...imageProps} />
+{:else}
+  <svg viewBox="0 0 320 200" role="img" aria-label="Sun above two mountain ridges" {...props as SVGAttributes<SVGSVGElement>}
+    style={[`color:var(--ui-tone-${value})`, styleText(style)].filter(Boolean).join(';')}>
+    <rect width="320" height="200" fill="var(--ui-surface-sheet)" />
+    <path d="M0 175V158l92-93 113 110H0Z" fill="currentColor" opacity=".1" />
+    <path d="M74 200 211 83l109 102v15H74Z" fill="currentColor" opacity=".16" />
+    <circle cx="250" cy="49" r="23" fill="currentColor" opacity=".11" />
+    <circle cx="250" cy="49" r="22.5" fill="none" stroke="currentColor" stroke-opacity=".5" />
+    <path d="M0 158 92 65l113 110M74 200 211 83l109 102M0 175h103" fill="none" stroke="currentColor" stroke-opacity=".38" />
+    <path d="M23 183h62m130-6h72" fill="none" stroke="currentColor" stroke-opacity=".18" stroke-width=".75" />
+    <circle cx="92" cy="65" r="2.5" fill="currentColor" />
+    <circle cx="211" cy="83" r="2.5" fill="currentColor" />
+    <rect width="319" height="199" x=".5" y=".5" fill="none" stroke="var(--ui-line-contour)" />
+  </svg>
+{/if}

package/src/demo/DemoMotion.svelte

@@ -0,0 +1,41 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+  import { onMount } from 'svelte'
+  import IconPlayerPause from '@tabler/icons-svelte-runes/icons/player-pause'
+  import IconPlayerPlay from '@tabler/icons-svelte-runes/icons/player-play'
+  import IconRefresh from '@tabler/icons-svelte-runes/icons/refresh'
+
+  /** Play, pause and replay the native animations inside; they start paused and respect reduced motion. */
+  let { children }: { children?: Snippet } = $props()
+  let element = $state<HTMLDivElement>()
+  let playing = $state(false)
+  onMount(() => {
+    const preference = matchMedia('(prefers-reduced-motion: reduce)')
+    const sync = () => {
+      element?.getAnimations({ subtree: true }).forEach(animation => animation.pause())
+      playing = false
+    }
+    sync()
+    preference.addEventListener('change', sync)
+    return () => preference.removeEventListener('change', sync)
+  })
+  const control = (action: 'play' | 'pause' | 'restart') => {
+    element?.getAnimations({ subtree: true }).forEach(animation => {
+      if (action === 'restart') animation.currentTime = 0
+      if (action === 'pause') animation.pause()
+      else animation.play()
+    })
+    playing = action !== 'pause'
+  }
+</script>
+
+<div class="grid gap-md w-full">
+  <div bind:this={element} data-playback={playing ? 'playing' : 'paused'}>{@render children?.()}</div>
+  <div class="ui-player" role="group" aria-label="Animation controls" data-state={playing ? 'playing' : 'paused'}>
+    <button type="button" class="ui-button" data-size="sm" onclick={() => control(playing ? 'pause' : 'play')}>
+      {#if playing}<IconPlayerPause aria-hidden="true" />{:else}<IconPlayerPlay aria-hidden="true" />{/if}{playing ? 'Pause' : 'Play'}
+    </button>
+    <button type="button" class="ui-button" data-size="sm" data-variant="quiet" onclick={() => control('restart')}><IconRefresh aria-hidden="true" />Replay</button>
+    <span class="ui-player-time"><output>{playing ? 'Playing' : 'Paused'}</output></span>
+  </div>
+</div>

package/src/demo/DemoPageViewport.astro

@@ -0,0 +1,17 @@
+---
+import Demo from '@master/internal-site/demo/Demo.svelte'
+import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
+
+interface Props {
+  src: string
+  title: string
+  height?: number
+}
+
+/** Site-owned example pages share the same keyboard-accessible viewport controls. */
+const { src, title, height = 420 } = Astro.props
+---
+
+<Demo title={title} frame="none" caption="Adjust the iframe viewport. Scroll inside the preview to see all content.">
+  <DemoViewport client:idle={{ timeout: 500 }} src={src} title={title} height={height} responsive />
+</Demo>

package/src/demo/DemoPalette.astro

@@ -0,0 +1,29 @@
+---
+import '@master/internal-site/styles/system/specimens.css'
+import Demo from '@master/internal-site/demo/Demo.svelte'
+import DemoPaletteGroups from '@master/internal-site/demo/DemoPaletteGroups.svelte'
+import { getThemeVariables } from '@master/internal-site/css/theme-variables.ts'
+
+interface Props {
+  families?: string[]
+}
+
+const { families } = Astro.props
+const groups = new Map<string, { name: string, step: number, value: string }[]>()
+for (const variable of getThemeVariables('color')) {
+  const match = variable.name?.match(/^color-(.+)-(\d+)$/)
+  if (!match || typeof variable.value !== 'string' || (families && !families.includes(match[1]))) continue
+  const [, family, step] = match
+  if (!groups.has(family)) groups.set(family, [])
+  groups.get(family)!.push({ name: variable.name!, step: Number(step), value: variable.value })
+}
+// The copy group and its chips are one island, so every chip reports to the shared status.
+const palette = [...groups].map(([family, colors]) => ({
+  family,
+  colors: colors.sort((a, b) => a.step - b.step).map(({ name, value }) => ({ name, value }))
+}))
+---
+
+<Demo title="Preset palette" padding="sm" data-foundation-palette caption="Each swatch shows the fixed preset value in both themes.">
+  <DemoPaletteGroups client:idle={{ timeout: 500 }} groups={palette} />
+</Demo>

package/src/demo/DemoPaletteGroups.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import DemoCopyButton from '@master/internal-site/demo/DemoCopyButton.svelte'
+  import DemoCopyGroup from '@master/internal-site/demo/DemoCopyGroup.svelte'
+
+  /** DemoPalette's chips: one copy group, so every chip reports to the same status. */
+  let { groups }: { groups: { family: string, colors: { name: string, value: string }[] }[] } = $props()
+</script>
+
+<div class="w-full"><DemoCopyGroup><div class="ui-palette">
+  {#each groups as { family, colors } (family)}<div class="ui-palette-row" role="group" aria-label={`${family} palette`}>
+    <span>{family}</span>
+    {#each colors as { name, value } (name)}<DemoCopyButton value={`var(--${name})`} label={`Copy ${name}`} icon={null} class="ui-palette-chip" style={`background-color:${value}`} title={`${name}: ${value}`} />{/each}
+  </div>{/each}
+</div></DemoCopyGroup></div>

package/src/demo/DemoScrollArea.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import { styleText, type DemoStyle } from '@master/internal-site/demo/style.ts'
+
+  /** A local, keyboard-reachable scroll region. Name it with aria-label. */
+  let { class: className, tabindex = 0, style, children, ...props }: Omit<HTMLAttributes<HTMLDivElement>, 'style'> & {
+    style?: DemoStyle
+    children?: Snippet
+  } = $props()
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<div {...props} {tabindex} class={['ui-scroll', className]} style={styleText(style)}>{@render children?.()}</div>

package/src/demo/DemoStyleComparison.astro

@@ -0,0 +1,25 @@
+---
+import Demo from '@master/internal-site/demo/Demo.svelte'
+import DemoViewport from '@master/internal-site/demo/DemoViewport.svelte'
+
+export interface DemoStyleComparisonProps {
+  /** Trusted site-authored HTML only. Both previews receive this exact markup. */
+  html: string
+  css: string
+  height?: number
+  sizing?: 'viewport' | 'content'
+  caption?: string
+}
+type Props = DemoStyleComparisonProps
+
+/** Native browser defaults versus supplied CSS, without a flashing transition. */
+const { html, css, height = 320, sizing = 'viewport', caption } = Astro.props
+const document = (styles: string) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><style>${styles.replaceAll('</style', '<\\/style')}</style></head><body>${html}</body></html>`
+---
+
+<Demo title="Browser defaults and author CSS" description="The same HTML in two documents" frame="none" caption={caption}>
+  <div class="ui-compare">
+    <figure><figcaption>Browser defaults</figcaption><DemoViewport client:idle={{ timeout: 500 }} title="Browser defaults" document={document('')} height={height} sizing={sizing} /></figure>
+    <figure><figcaption>CSS applied</figcaption><DemoViewport client:idle={{ timeout: 500 }} title="CSS applied" document={document(css)} height={height} sizing={sizing} /></figure>
+  </div>
+</Demo>

package/src/demo/DemoSurface.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import { styleText, type DemoStyle } from '@master/internal-site/demo/style.ts'
+
+  /** A sheet on the stage. Geometry and padding stay with the example. */
+  let { elevation = 'flat', class: className, style, children, ...props }: Omit<HTMLAttributes<HTMLDivElement>, 'style'> & {
+    elevation?: 'flat' | 'raised'
+    style?: DemoStyle
+    children?: Snippet
+  } = $props()
+</script>
+
+<div {...props} data-elevation={elevation === 'flat' ? 'flat' : '1'} class={['ui-sheet', className]} style={styleText(style)}>{@render children?.()}</div>

package/src/demo/DemoSwatch.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+  import '@master/internal-site/styles/system/specimens.css'
+  import type { Snippet } from 'svelte'
+  import type { HTMLAttributes } from 'svelte/elements'
+  import { styleText, type DemoStyle } from '@master/internal-site/demo/style.ts'
+
+  /** A named role with its actual paint. class and style paint the face. */
+  let { label, value, class: className, style, children, ...props }: Omit<HTMLAttributes<HTMLDivElement>, 'style'> & {
+    label: string
+    value?: string
+    style?: DemoStyle
+    children?: Snippet
+  } = $props()
+</script>
+
+<figure class="ui-swatch">
+  <div {...props} aria-hidden={props['aria-hidden'] ?? (children == null ? true : undefined)} class={['ui-swatch-paint', className]} style={styleText(style)}>{@render children?.()}</div>
+  <figcaption><b>{label}</b>{#if value}<code>{value}</code>{/if}</figcaption>
+</figure>

package/src/demo/DemoThemeComparison.astro

@@ -0,0 +1,30 @@
+---
+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'
+
+export interface DemoThemeComparisonProps {
+  name: string
+  title: string
+  /** Trusted site-authored HTML with complete, scannable Master CSS classes. */
+  html: string
+  css?: string
+  caption?: string
+  height?: number
+  print?: boolean
+}
+type Props = DemoThemeComparisonProps
+
+/** Independent documents keep mode variables and native state inside each specimen. */
+const { name, title, html, css = '', caption, height = 240, print = false } = Astro.props
+const document = (mode: 'light' | 'dark') => demoDocument({ page: 'foundations', id: name, title, html: [html], css, classes: [], classLists: [], highlighted: [] }, { html, bodyClass: 'p-md p(8)@media(width<240px) bg-surface-base fg-text-body', caption: '' }, mode)
+---
+
+<Demo title={title} frame="none" caption={caption} data-foundation-paint={name}>
+  <div class="ui-compare">
+    {(['light', 'dark'] as const).map(mode => <figure data-theme-specimen={mode}>
+      <figcaption>{mode === 'light' ? 'Light' : 'Dark'}</figcaption>
+      <DemoViewport client:idle={{ timeout: 500 }} title={`${title} · ${mode}`} document={document(mode)} initialTheme={mode} print={print} height={height} sizing="content" />
+    </figure>)}
+  </div>
+</Demo>