@master/internal-site 0.0.0-stage → 0.1.1

package/src/demo/specimens/width.json

@@ -0,0 +1,56 @@
+[
+  {
+    "page": "width",
+    "id": "set-a-fixed-or-fluid-width",
+    "title": "Set a fixed or fluid width",
+    "html": [
+      "<!-- Fixed · 192px -->\n<div id=\"layout\" class=\"(width:17.5rem) max-w-full\" role=\"group\" aria-label=\"Available space\">\n  <div id=\"target\" class=\"(width:12rem) p-sm\">Fixed width</div>\n</div>",
+      "<!-- Fluid · 100% -->\n<div id=\"layout\" class=\"(width:17.5rem) max-w-full\" role=\"group\" aria-label=\"Available space\">\n  <div id=\"target\" class=\"w-full p-sm\">Full width</div>\n</div>"
+    ],
+    "css": "",
+    "classes": [
+      "(width:17.5rem)",
+      "max-w-full",
+      "(width:12rem)",
+      "p-sm",
+      "w-full"
+    ],
+    "classLists": [
+      "(width:17.5rem) max-w-full",
+      "(width:12rem) p-sm",
+      "(width:17.5rem) max-w-full",
+      "w-full p-sm"
+    ],
+    "highlighted": []
+  },
+  {
+    "page": "width",
+    "id": "use-intrinsic-width-keywords",
+    "title": "Use intrinsic width keywords",
+    "html": [
+      "<!-- Minimum content -->\n<div id=\"layout\" class=\"(width:7rem)\" role=\"group\" aria-label=\"Available space\">\n  <div id=\"target\" class=\"w-min p-sm font-md font-mono (line-height:24px)\">Design systems</div>\n</div>",
+      "<!-- Fit content -->\n<div id=\"layout\" class=\"(width:7rem)\" role=\"group\" aria-label=\"Available space\">\n  <div id=\"target\" class=\"w-fit p-sm font-md font-mono (line-height:24px)\">Design systems</div>\n</div>",
+      "<!-- Maximum content -->\n<div id=\"layout\" class=\"(width:7rem)\" role=\"group\" aria-label=\"Available space\">\n  <div id=\"target\" class=\"w-max p-sm font-md font-mono (line-height:24px)\">Design systems</div>\n</div>"
+    ],
+    "css": "",
+    "classes": [
+      "(width:7rem)",
+      "w-min",
+      "p-sm",
+      "font-md",
+      "font-mono",
+      "(line-height:24px)",
+      "w-fit",
+      "w-max"
+    ],
+    "classLists": [
+      "(width:7rem)",
+      "w-min p-sm font-md font-mono (line-height:24px)",
+      "(width:7rem)",
+      "w-fit p-sm font-md font-mono (line-height:24px)",
+      "(width:7rem)",
+      "w-max p-sm font-md font-mono (line-height:24px)"
+    ],
+    "highlighted": []
+  }
+]

package/src/demo/specimens/will-change.json

@@ -0,0 +1,50 @@
+[
+  {
+    "page": "will-change",
+    "id": "reset-when-the-hint-is-no-longer-useful",
+    "title": "Reset when the hint is no longer useful",
+    "html": [
+      "<!-- Auto → prepare → press → auto -->\n<div class=\"p-lg\">\n  <div class=\"relative h(96) w(160) outline(1) outline-dashed outline-line-subtle\">\n    <button id=\"target\" type=\"button\"\n      class=\"grid (place-items:center) h(96) w(160) p-sm\n             b(1) b-solid b-blue-60 r-sm font-sm bg-blue-10\n             fg-blue-80 (transform:none) (will-change:auto)\n             outline(2):focus-visible outline-solid:focus-visible outline-blue:focus-visible\n             outline-offset(3):focus-visible\n             (transform:none)@media(print)\n             (transition-property:transform)@motion-safe (transition-duration:var(--duration-fast))@motion-safe (transition-timing-function:ease-out)@motion-safe\n             (will-change:auto)@media(print)\n             (will-change:transform):hover@media(screen)\n             (will-change:transform):focus-visible@media(screen)\n             (transform:translateY(-8px)):active@media(screen)\">\n      Prepare and press\n    </button>\n  </div>\n</div>"
+    ],
+    "css": "",
+    "classes": [
+      "p-lg",
+      "relative",
+      "h(96)",
+      "w(160)",
+      "outline(1)",
+      "outline-dashed",
+      "outline-line-subtle",
+      "grid",
+      "(place-items:center)",
+      "p-sm",
+      "b(1)",
+      "b-solid",
+      "b-blue-60",
+      "r-sm",
+      "font-sm",
+      "bg-blue-10",
+      "fg-blue-80",
+      "(transform:none)",
+      "(will-change:auto)",
+      "outline(2):focus-visible",
+      "outline-solid:focus-visible",
+      "outline-blue:focus-visible",
+      "outline-offset(3):focus-visible",
+      "(transform:none)@media(print)",
+      "(transition-property:transform)@motion-safe",
+      "(transition-duration:var(--duration-fast))@motion-safe",
+      "(transition-timing-function:ease-out)@motion-safe",
+      "(will-change:auto)@media(print)",
+      "(will-change:transform):hover@media(screen)",
+      "(will-change:transform):focus-visible@media(screen)",
+      "(transform:translateY(-8px)):active@media(screen)"
+    ],
+    "classLists": [
+      "p-lg",
+      "relative h(96) w(160) outline(1) outline-dashed outline-line-subtle",
+      "grid (place-items:center) h(96) w(160) p-sm b(1) b-solid b-blue-60 r-sm font-sm bg-blue-10 fg-blue-80 (transform:none) (will-change:auto) outline(2):focus-visible outline-solid:focus-visible outline-blue:focus-visible outline-offset(3):focus-visible (transform:none)@media(print) (transition-property:transform)@motion-safe (transition-duration:var(--duration-fast))@motion-safe (transition-timing-function:ease-out)@motion-safe (will-change:auto)@media(print) (will-change:transform):hover@media(screen) (will-change:transform):focus-visible@media(screen) (transform:translateY(-8px)):active@media(screen)"
+    ],
+    "highlighted": []
+  }
+]

package/src/demo/specimens/writing-mode.json

@@ -0,0 +1,26 @@
+[
+  {
+    "page": "writing-mode",
+    "id": "use-vertical-right-to-left-flow",
+    "title": "Use vertical right-to-left flow",
+    "html": [
+      "<!-- (writing-mode:vertical-rl) -->\n<p id=\"target\" lang=\"zh-Hant\" class=\"h(128) w(120) m(0) font-md (line-height:24px) (writing-mode:vertical-rl)\">清晰設計讓每個想法都有空間</p>",
+      "<!-- (writing-mode:vertical-lr) -->\n<p id=\"target\" lang=\"zh-Hant\" class=\"h(128) w(120) m(0) font-md (line-height:24px) (writing-mode:vertical-lr)\">清晰設計讓每個想法都有空間</p>"
+    ],
+    "css": "",
+    "classes": [
+      "h(128)",
+      "w(120)",
+      "m(0)",
+      "font-md",
+      "(line-height:24px)",
+      "(writing-mode:vertical-rl)",
+      "(writing-mode:vertical-lr)"
+    ],
+    "classLists": [
+      "h(128) w(120) m(0) font-md (line-height:24px) (writing-mode:vertical-rl)",
+      "h(128) w(120) m(0) font-md (line-height:24px) (writing-mode:vertical-lr)"
+    ],
+    "highlighted": []
+  }
+]

package/src/demo/specimens/z-index.json

@@ -0,0 +1,35 @@
+[
+  {
+    "page": "z-index",
+    "id": "prefer-local-stacking-contexts",
+    "title": "Prefer local stacking contexts",
+    "html": [
+      "<div class=\"relative (height:11rem)\">\n  <article class=\"relative (z-index:0) isolate (height:10rem) (width:12rem)\">\n    <div class=\"absolute left-md top-md (z-index:99) (height:6rem) (width:10rem)\">Child 99</div>\n  </article>\n  <div class=\"absolute left-2xl top-2xl (z-index:1) (height:6rem) (width:10rem)\">Sibling 1</div>\n</div>"
+    ],
+    "css": "",
+    "classes": [
+      "relative",
+      "(height:11rem)",
+      "(z-index:0)",
+      "isolate",
+      "(height:10rem)",
+      "(width:12rem)",
+      "absolute",
+      "left-md",
+      "top-md",
+      "(z-index:99)",
+      "(height:6rem)",
+      "(width:10rem)",
+      "left-2xl",
+      "top-2xl",
+      "(z-index:1)"
+    ],
+    "classLists": [
+      "relative (height:11rem)",
+      "relative (z-index:0) isolate (height:10rem) (width:12rem)",
+      "absolute left-md top-md (z-index:99) (height:6rem) (width:10rem)",
+      "absolute left-2xl top-2xl (z-index:1) (height:6rem) (width:10rem)"
+    ],
+    "highlighted": []
+  }
+]

package/src/demo/style.ts

@@ -0,0 +1,15 @@
+/** A style declaration as Svelte renders it: text, or an object such as `.astro` callers write. */
+export type DemoStyle = string | Record<string, string | number | null | undefined>
+
+const unitless = /^(?:--|opacity$|z-?index$|flex(?:-?grow|-?shrink)?$|order$|font-?weight$|line-?height$|zoom$|scale$|aspect-?ratio$)/i
+
+/** Object styles follow Astro's style objects: camelCase names become kebab-case, and numbers on length properties become pixels. */
+export function styleText(style: DemoStyle | null | undefined) {
+  if (style == null || typeof style === 'string') return style || undefined
+  const declarations = Object.entries(style).flatMap(([name, value]) => {
+    if (value == null || value === '') return []
+    const property = name.startsWith('--') ? name : name.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`)
+    return [`${property}:${typeof value === 'number' && value !== 0 && !unitless.test(name) ? `${value}px` : value}`]
+  })
+  return declarations.join(';') || undefined
+}

package/src/demo/tone.ts

@@ -0,0 +1,4 @@
+/** Teaching tones: neutral context, blue subject, violet comparison, amber measured, green and red outcomes. Name each one with a legend or label. */
+export type DemoTone = 'neutral' | 'blue' | 'violet' | 'amber' | 'green' | 'red'
+
+export const tone = (value: DemoTone) => value === 'neutral' ? undefined : value

package/src/demo/useDemoViewTransition.svelte.ts

@@ -0,0 +1,71 @@
+import { flushSync, onMount } from 'svelte'
+import { createSubscriber } from 'svelte/reactivity'
+
+const reducedMotion = '(prefers-reduced-motion: reduce)'
+const subscribe = createSubscriber(update => {
+  const media = matchMedia(reducedMotion)
+  media.addEventListener('change', update)
+  return () => media.removeEventListener('change', update)
+})
+function browserMode() {
+  return matchMedia(reducedMotion).matches ? 'Reduced motion · instant update'
+    : typeof document.startViewTransition === 'function' ? 'Native view transition' : 'API unavailable · instant update'
+}
+
+/**
+ * Use inside a dedicated example document so the root snapshot cannot capture the docs.
+ * Call it during component initialization. `mode` is reactive: read it from the returned object.
+ */
+export function useDemoViewTransition() {
+  let active: ViewTransition | null = null
+  let revision = 0
+  // The server and the first client render agree on "Ready"; the browser's mode follows after mount.
+  let mounted = $state(false)
+  onMount(() => {
+    mounted = true
+    const media = matchMedia(reducedMotion)
+    const changed = () => { if (media.matches) active?.skipTransition() }
+    media.addEventListener('change', changed)
+    return () => {
+      revision++
+      active?.skipTransition()
+      media.removeEventListener('change', changed)
+    }
+  })
+
+  function run(update: () => void, focus?: () => HTMLElement | null | undefined) {
+    const request = ++revision
+    active?.skipTransition()
+    const commit = () => {
+      if (request !== revision) return
+      flushSync(update)
+      const target = focus?.()
+      target?.focus({ preventScroll: true })
+      if (target) {
+        const bounds = target.getBoundingClientRect()
+        const offset = bounds.top < 16 ? bounds.top - 16 : bounds.bottom > innerHeight - 16 ? bounds.bottom - innerHeight + 16 : 0
+        if (offset) window.scrollBy({ top: offset, behavior: 'instant' })
+      }
+    }
+    if (!document.startViewTransition || matchMedia(reducedMotion).matches) {
+      commit()
+      return
+    }
+    const transition = document.startViewTransition(commit)
+    active = transition
+    // Rapid selections can skip a snapshot; the DOM update still runs.
+    void transition.ready.catch(() => {})
+    // A failed update is an application error, not a reason to repeat the update.
+    void transition.updateCallbackDone.catch(error => { reportError(error) })
+    const finished = () => { if (active === transition) active = null }
+    void transition.finished.then(finished, finished)
+  }
+  return {
+    run,
+    get mode() {
+      if (!mounted) return 'Ready'
+      subscribe()
+      return browserMode()
+    }
+  }
+}

package/src/docs-shell/common/i18n.config.d.ts

@@ -0,0 +1,2 @@
+declare const config: { defaultLocale: string; locales: readonly string[]; hreflangOfLocale: Record<string, string>; nameOfLocale: Record<string, string> }
+export default config

package/src/docs-shell/common/i18n.config.js

@@ -0,0 +1,13 @@
+const i18n = {
+  defaultLocale: 'en',
+  locales: ['en', 'tw'],
+  hreflangOfLocale: {
+    tw: 'zh-TW'
+  },
+  nameOfLocale: {
+    tw: '中文 (臺灣)',
+    en: 'English'
+  }
+}
+
+export default i18n

package/src/docs-shell/common/svgo.config.d.ts

@@ -0,0 +1,2 @@
+declare const config: import('svgo').Config
+export default config

package/src/docs-shell/common/svgo.config.js

@@ -0,0 +1,11 @@
+export default {
+  plugins: [
+    {
+      name: 'preset-default',
+    },
+    // Titles name files, not page content; svgo 4 no longer removes them by default.
+    'removeTitle',
+    // Prefix ids from the SVG file name so server and client renders stay identical.
+    'prefixIds',
+  ],
+}

package/src/docs-shell/components/ArticleHeader.astro

@@ -0,0 +1,65 @@
+---
+import '../../styles/docs-shell/docs.css'
+import IconAlertTriangle from '@tabler/icons-svelte-runes/icons/alert-triangle'
+import ChevronLeftSvg from '../../public/images/chevron-left.svg'
+import Link from './Link.svelte'
+import dayjs from 'dayjs'
+import { createTranslation } from '../utils/i18n'
+import { siteOf } from '../../astro/site-context'
+import PackageBadges from './PackageBadges.astro'
+import PageContentDisclosure from './PageContentDisclosure.astro'
+import HeaderIcon from './HeaderIcon.astro'
+import RenderNode from './RenderNode.astro'
+
+interface Props {
+  h1Class?: string
+  metadata: any
+  /** A brand name from `data/brands`, drawn beside the title. */
+  icon?: string
+  /** Markup after the title. */
+  end?: unknown
+  date?: string | number | Date
+  center?: boolean
+  locale: string
+  categoryLink?: string | boolean
+  dictionaries: Record<string, () => Promise<any>>
+  toc?: any[] | null
+  subtitle?: string
+  [key: string]: any
+}
+
+const { h1Class, metadata, icon, end, date, center, locale, categoryLink, dictionaries, toc, subtitle } = Astro.props
+const $ = await createTranslation(locale, dictionaries)
+const { i18n } = siteOf(Astro)
+// Text a translated page still shows in its source language says so, for screen readers and Han type rules.
+const sourceLanguage = locale !== i18n.defaultLocale ? (i18n.hreflangOfLocale as Record<string, string>)[i18n.defaultLocale] ?? i18n.defaultLocale : undefined
+const languageOf = (text?: string) => sourceLanguage && text && !text.startsWith('`') && $(text) === text ? sourceLanguage : undefined
+const kickers = [
+  metadata.category && { text: $(metadata.category), lang: languageOf(metadata.category) },
+  date && { text: dayjs(date).format('MMMM D, YYYY') }
+].filter(Boolean) as { text: string, lang?: string }[]
+---
+
+<div class="ui-pagehead" data-align={center ? 'center' : undefined}>
+  {kickers.map(({ text, lang }) => categoryLink
+    ? <Link href={typeof categoryLink === 'string' ? categoryLink : './'} lang={lang} class="ui-pagehead-kicker">
+      <ChevronLeftSvg aria-hidden="true" />
+      {text}
+    </Link>
+    : <span class="ui-pagehead-kicker" lang={lang}>{text}</span>)}
+  <div class="ui-pagehead-title">
+    <h1 class={h1Class} lang={languageOf(metadata.title.absolute || metadata.title)}>
+      {$(metadata.title.absolute || metadata.title)}
+      {metadata.type === 'entity' && locale !== 'en' && <span lang={sourceLanguage}> {metadata.title}</span>}
+      {metadata.unfinished && <span class="ui-pagehead-unfinished" aria-hidden="true">🚧</span>}
+    </h1>
+    {end != null && <RenderNode node={end} />}
+    {icon && <div class="ui-pagehead-icon"><HeaderIcon name={icon as any} /></div>}
+  </div>
+  <p lang={languageOf(metadata.description)}>{$(metadata.description)}</p>
+  {subtitle && <p lang={languageOf(subtitle)}>{$(subtitle)}</p>}
+  {metadata.package && <PackageBadges {...metadata.package} translate={$} />}
+  {(metadata.unfinished || metadata.disabled) &&
+    <div class="ui-callout" data-tone="warning" role="note"><IconAlertTriangle aria-hidden="true" /><div>{$('This page is still under construction and some content may not be complete.')}</div></div>}
+</div>
+{!!toc?.length && <PageContentDisclosure items={toc.map((item: any) => ({ ...item, title: $(item.title), lang: languageOf(item.title) }))} label={$('On this page')} />}

package/src/docs-shell/components/ArticleTOC.astro

@@ -0,0 +1,18 @@
+---
+import { siteOf } from '../../astro/site-context'
+import PageContentDisclosure from './PageContentDisclosure.astro'
+
+interface Props {
+  data: { id: string, title: string, level: number }[]
+}
+
+/**
+ * A page's contents placed in its text: the same disclosure, drawn as the same ruler, that documentation pages show
+ * under their header on narrow screens. Its label is in the reader's language, even inside text still in its source
+ * language.
+ */
+const { t, i18n: { hreflangOfLocale }, locale } = siteOf(Astro)
+const items = (Astro.props.data ?? []).filter((item): item is { id: string, title: string, level: 2 | 3 } => item.level === 2 || item.level === 3)
+---
+
+{items.some((item) => item.level === 2) && <PageContentDisclosure items={items} label={t('On this page')} labelLang={hreflangOfLocale?.[locale] ?? locale} />}

package/src/docs-shell/components/Callout.astro

@@ -0,0 +1,26 @@
+---
+import IconAlertTriangle from '@tabler/icons-svelte-runes/icons/alert-triangle'
+import IconCheck from '@tabler/icons-svelte-runes/icons/check'
+import IconInfoCircle from '@tabler/icons-svelte-runes/icons/info-circle'
+import IconX from '@tabler/icons-svelte-runes/icons/x'
+
+const icons = {
+  info: IconInfoCircle,
+  warning: IconAlertTriangle,
+  do: IconCheck,
+  dont: IconX
+}
+
+interface Props {
+  tone: keyof typeof icons
+}
+
+/** A `ui-callout`: one icon and one status tint around a short note. Markdown writes it as `(i)`, `(!)`, `(o)` or `(x)`. */
+const { tone } = Astro.props
+const Icon = icons[tone]
+---
+
+<div class="ui-callout" data-tone={tone} role="note">
+  <Icon aria-hidden="true" stroke={1.5} />
+  <div><p><slot /></p></div>
+</div>

package/src/docs-shell/components/Code.astro

@@ -0,0 +1,25 @@
+---
+import type { HTMLAttributes } from 'astro/types'
+import { toHtml } from 'hast-util-to-html'
+import highlightCode from '../utils/highlight-code'
+import { slotText } from '../utils/slot-text'
+import CodeView from './CodeView.astro'
+import type { CodeProp } from './code-props'
+
+type Props = CodeProp & Omit<HTMLAttributes<'div'>, 'class'> & {
+  /** The source; text children work too, as in `<Code lang="html">{`<div>`}</Code>`. */
+  code?: string
+}
+
+const { code: source, ...props } = Astro.props
+const code = source ?? await slotText(Astro.slots) ?? ''
+const hast = await highlightCode(code, {
+  lang: props.lang,
+  beautify: !!props.beautify,
+  dedent: props.dedent,
+  className: props.preClassName,
+  masterCSS: props.masterCSS
+})
+---
+
+<CodeView {...props}><Fragment set:html={toHtml(hast)} /></CodeView>

package/src/docs-shell/components/CodeCopyButton.astro

@@ -0,0 +1,25 @@
+---
+import IconCheck from '@tabler/icons-svelte-runes/icons/check'
+import IconCopy from '@tabler/icons-svelte-runes/icons/copy'
+
+interface Props {
+  text?: string
+  name?: string
+  class?: string
+}
+
+/**
+ * Copies the code it belongs to through `docs-shell/scripts/code`: the icon swaps and the status beside it says what
+ * happened (`data-result`). Pass `text` only when it differs from the rendered code lines.
+ */
+const { text, name, class: className } = Astro.props
+const label = name ? `Copy ${name}` : 'Copy code'
+---
+
+<span class:list={['ui-copy', className]}>
+  <span class="ui-copy-status" role="status"></span>
+  <button type="button" class="ui-button" data-variant="quiet" data-shape="icon" data-size="sm" aria-label={label} title={label} data-code-copy={name ?? ''} data-code-copy-text={text}>
+    <IconCopy size={16} stroke={1.5} aria-hidden="true" />
+    <IconCheck size={16} stroke={1.6} aria-hidden="true" class="ui-result-icon" />
+  </button>
+</span>

package/src/docs-shell/components/CodeTabBar.astro

@@ -0,0 +1,40 @@
+---
+import CodeCopyButton from './CodeCopyButton.astro'
+
+type Tab = { name?: string, lang: string, ext?: string }
+
+interface Props {
+  tabs: Tab[]
+  currentName?: string
+  class?: string
+  /** Accepted for older callers; the bar names the file and nothing else. */
+  showControls?: boolean
+  copyable?: boolean
+  /** Tab lists switch panels through `docs-shell/scripts/code`. */
+  idPrefix?: string
+}
+
+/** The `ui-code-bar`: the file's name, or `ui-tabs` that switch panels, and the copy action. */
+const { tabs, currentName, class: className, copyable = true, idPrefix } = Astro.props
+---
+
+<div class={className ? `ui-code-bar ${className}` : 'ui-code-bar'}>
+  {idPrefix
+    ? <div class="ui-tabs" role="tablist" aria-label="Code examples">
+      {tabs.map(({ name, lang }, index) => {
+        const tabName = name ?? lang
+        const active = currentName === tabName
+        return <button
+          type="button"
+          role="tab"
+          id={`${idPrefix}-tab-${index}`}
+          aria-controls={`${idPrefix}-panel-${index}`}
+          aria-selected={active ? 'true' : 'false'}
+          tabindex={active ? 0 : -1}
+          data-code-tabs-tab-name={tabName}
+        >{tabName}</button>
+      })}
+    </div>
+    : <span class="ui-code-file">{tabs[0]?.name}</span>}
+  {copyable && <CodeCopyButton name={currentName} />}
+</div>

package/src/docs-shell/components/CodeTabs.astro

@@ -0,0 +1,53 @@
+---
+import '../../styles/docs-shell/code.css'
+import { toHtml } from 'hast-util-to-html'
+import highlightCode from '../utils/highlight-code'
+import { uniqueId } from '../utils/unique-id'
+import CodeTabBar from './CodeTabBar.astro'
+import type { CodeTab } from './code-props'
+
+interface Props {
+  tabs: CodeTab[]
+  tabbarClassName?: string
+  showControls?: boolean
+  class?: string
+  localStorageKey?: string
+}
+
+/**
+ * One `ui-code` panel with `ui-tabs`. Every panel is rendered; the first is shown. `docs-shell/scripts/code` switches
+ * tabs, and a storage key restores and shares the choice across tab sets.
+ */
+const { tabs, tabbarClassName, class: className, localStorageKey } = Astro.props
+const panels = await Promise.all(tabs.map(async (tab) => ({
+  ...tab,
+  name: tab.name ?? tab.lang,
+  html: toHtml(await highlightCode(tab.code, tab))
+})))
+const idPrefix = uniqueId(Astro, 'code-tabs')
+const current = panels[0]
+---
+
+<div
+  class:list={['ui-code', className]}
+  data-code-tabs=""
+  data-code-tabs-current-name={current.name}
+  data-code-tabs-storage-key={localStorageKey}
+  data-numbers={panels.some(tab => tab.number) ? '' : undefined}
+>
+  <CodeTabBar class={tabbarClassName} currentName={current.name} tabs={panels} idPrefix={idPrefix} />
+  {panels.map((tab, index) => (
+    <div
+      role="tabpanel"
+      id={`${idPrefix}-panel-${index}`}
+      aria-labelledby={`${idPrefix}-tab-${index}`}
+      data-code-tabs-panel-name={tab.name}
+      data-lang={tab.lang}
+      hidden={index !== 0}
+    >
+      {/* Paper and pages without scripts show every panel under its name. */}
+      <span class="ui-code-file" aria-hidden="true">{tab.name}</span>
+      <Fragment set:html={tab.html} />
+    </div>
+  ))}
+</div>

package/src/docs-shell/components/CodeView.astro

@@ -0,0 +1,23 @@
+---
+import '../../styles/docs-shell/code.css'
+
+import type { HTMLAttributes } from 'astro/types'
+import type { CodeProp } from './code-props'
+import CodeTabBar from './CodeTabBar.astro'
+import CodeCopyButton from './CodeCopyButton.astro'
+
+type Props = CodeProp & Omit<HTMLAttributes<'div'>, 'class'>
+
+/**
+ * A `ui-code` panel without loading the highlighting pipeline: a bar naming the file when it has a `name`, otherwise a
+ * copy button in the corner. The default slot is the highlighted `<pre>`. Copy controls read the rendered Shiki lines;
+ * see `docs-shell/scripts/code`.
+ */
+const { lang, class: className, name, tabbarClassName, copyable = true, number, ext } = Astro.props
+---
+
+<div class:list={['ui-code', className]} data-lang={lang} data-numbers={number ? '' : undefined}>
+  {name && <CodeTabBar tabs={[{ name, lang, ext }]} currentName={name} class={tabbarClassName} copyable={copyable} />}
+  {!name && copyable && <CodeCopyButton />}
+  <slot />
+</div>

package/src/docs-shell/components/Do.astro

@@ -0,0 +1,5 @@
+---
+import Callout from './Callout.astro'
+---
+
+<Callout tone="do"><slot /></Callout>

package/src/docs-shell/components/DoNot.astro

@@ -0,0 +1,5 @@
+---
+import Callout from './Callout.astro'
+---
+
+<Callout tone="dont"><slot /></Callout>

package/src/docs-shell/components/DocArticle.astro

@@ -0,0 +1,14 @@
+---
+import '../../styles/docs-shell/docs.css'
+import '../../styles/docs-shell/prose.css'
+import type { HTMLAttributes } from 'astro/types'
+
+interface Props extends HTMLAttributes<'article'> {
+  aside?: boolean
+}
+
+/** The article column; with `aside` it narrows to leave room for the page's contents rail. */
+const { aside, class: className, ...props } = Astro.props
+---
+
+<article {...props} class:list={['ui-docs-article ui-prose', className]} data-aside={aside ? '' : undefined}><slot /></article>