@master/internal-site 0.1.2 → 0.1.3

package/src/layouts/Document.astro

@@ -52,6 +52,9 @@ if (['dark', 'light'].includes(value)) document.documentElement.style.colorSchem
     <link blocking="render" rel="preload" as="font" href="/fonts/IBMPlexMono-Regular.woff2" crossorigin="anonymous" />
     {(site.locale === 'tw' || basePathname === '/brand') && <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+TC:wght@100..900&display=swap" rel="stylesheet" />}
     <style is:inline blocking="render" set:html={fontCSS}></style>
+    {/* client:load islands can hydrate while a streamed body is still parsing.
+        Their request-local context must already exist, even with cached CSS/JS. */}
+    <script is:inline type="application/json" id={siteContextElementId} set:html={siteContextJSON}></script>
     {assets.links.map((href) => <link rel="stylesheet" href={href} />)}
     {assets.styles.map((css) => <style is:inline set:html={css}></style>)}
     <title>{head.title}</title>
@@ -62,7 +65,6 @@ if (['dark', 'light'].includes(value)) document.documentElement.style.colorSchem
     <slot />
     {/* After the content, so persisted code tabs apply in the first pass, before paint. */}
     {!bare && <script is:inline set:html={`(${codeTabsBootstrap.toString()})();`}></script>}
-    <script is:inline type="application/json" id={siteContextElementId} set:html={siteContextJSON}></script>
     <script>
       import '../docs-shell/scripts/document'
       import '../docs-shell/scripts/code'

package/src/public/icons/json.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M5.759 3.975h1.783V5.76H5.759v4.458A1.783 1.783 0 0 1 3.975 12a1.783 1.783 0 0 1 1.784 1.783v4.459h1.783v1.783H5.759c-.954-.24-1.784-.803-1.784-1.783v-3.567a1.783 1.783 0 0 0-1.783-1.783H1.3v-1.783h.892a1.783 1.783 0 0 0 1.783-1.784V5.76A1.783 1.783 0 0 1 5.76 3.975m12.483 0a1.783 1.783 0 0 1 1.783 1.784v3.566a1.783 1.783 0 0 0 1.783 1.784h.892v1.783h-.892a1.783 1.783 0 0 0-1.783 1.783v3.567a1.783 1.783 0 0 1-1.783 1.783h-1.784v-1.783h1.784v-4.459A1.783 1.783 0 0 1 20.025 12a1.783 1.783 0 0 1-1.783-1.783V5.759h-1.784V3.975h1.784M12 14.675a.892.892 0 0 1 .892.892.892.892 0 0 1-.892.892.892.892 0 0 1-.891-.892.892.892 0 0 1 .891-.892m-3.566 0a.892.892 0 0 1 .891.892.892.892 0 0 1-.891.892.892.892 0 0 1-.892-.892.892.892 0 0 1 .892-.892m7.133 0a.892.892 0 0 1 .891.892.892.892 0 0 1-.891.892.892.892 0 0 1-.892-.892.892.892 0 0 1 .892-.892z" fill="#fbc02d"/></svg>

package/src/scripts/atomic-class-authoring.ts

@@ -0,0 +1,98 @@
+/** Repository authoring policy only. Native CSS and runtime parsing are unchanged. */
+import { createToolingSessionSync } from '@master/css-tooling/node'
+import type { MasterCSSManifest } from '@master/css-schema/manifest'
+import preset from '@master/css-preset/default-manifest.json' with { type: 'json' }
+
+export const compositeClassProperties = new Set(`all animation animation-range background border border-block border-block-end border-block-start border-bottom border-image border-inline border-inline-end border-inline-start border-left border-right border-top column-rule columns container flex flex-flow font font-synthesis font-variant grid grid-template line-clamp list-style mask mask-border offset outline scroll-timeline text-decoration text-emphasis text-wrap transition view-timeline white-space -webkit-text-stroke -webkit-mask -webkit-mask-box-image`.split(' '))
+const axisProperties = new Set(`background-position background-repeat border-block-color border-block-style border-block-width border-color border-inline-color border-inline-style border-inline-width border-radius border-style border-width contain-intrinsic-size gap grid-area grid-column grid-row inset inset-block inset-inline margin margin-block margin-inline mask-position mask-repeat overflow overscroll-behavior padding padding-block padding-inline place-content place-items place-self scroll-margin scroll-margin-block scroll-margin-inline scroll-padding scroll-padding-block scroll-padding-inline -webkit-mask-position -webkit-mask-repeat`.split(' '))
+
+export function atomicClassIssue(className: string): string | undefined {
+  const match = /^\(([a-z-]+):(.+)$/.exec(className)
+  if (!match) return
+  const [, property, tail] = match
+  if (!compositeClassProperties.has(property) && !axisProperties.has(property)) return
+  let depth = 0
+  let value = ''
+  let quote = ''
+  // The value ends at the closing parenthesis of the `(property:value)` head.
+  for (let index = 0; index < tail.length; index++) {
+    const char = tail[index]
+    if (char === '\\') { value += char + (tail[++index] ?? ''); continue }
+    if (quote) { if (char === quote) quote = ''; value += char; continue }
+    if (char === '"' || char === "'") { quote = char; value += char; continue }
+    if (char === '(') depth++
+    if (char === ')' && !depth--) break
+    value += !depth && (char === '|' || char === '/' || char === ',') ? '\0' : char
+  }
+  // A single grid line, named area, or span is one placement setting.
+  if (property.startsWith('grid-') && !tail.includes('/')) return
+  const parts = value.split('\0')
+  if (compositeClassProperties.has(property) && parts.length > 1) return `Express independent settings of ${property} separately`
+  if (new Set(parts).size > 1) return `Express different edges or axes of ${property} independently`
+}
+
+export function createAtomicClassAudit() {
+  const session = createToolingSessionSync({ manifest: preset as unknown as MasterCSSManifest })
+  return {
+    inspect(source: string, languageId: string) {
+      const positions = session.analyzeLintDocument(source, languageId).classPositions
+      const issues = positions.flatMap(position => {
+        const message = atomicClassIssue(position.token)
+        return message ? [{ ...position, message }] : []
+      })
+      const contexts = new Map<string, typeof positions[number][]>()
+      for (const position of positions) {
+        const key = `${position.contextRange.start}:${position.contextRange.end}`
+        const group = contexts.get(key) ?? []
+        group.push(position)
+        contexts.set(key, group)
+      }
+      for (const group of contexts.values()) {
+        for (const conflict of session.lintClassNames(group.map(item => item.token)).partialConflicts) {
+          const position = group.find(item => item.token === conflict.className)!
+          issues.push({ ...position, message: `Overlapping class ${conflict.conflict}; express each edge independently` })
+        }
+      }
+      return issues
+    },
+    dispose: () => session.dispose()
+  }
+}
+
+/** Inventory is explicit so adding a framework or relocating content cannot silently shrink coverage. */
+export async function auditAuthoringRoots(roots: { name: string, directory: string, patterns?: string[] }[]) {
+  const { default: glob } = await import('fast-glob')
+  const { readFile } = await import('node:fs/promises')
+  const { resolve, extname } = await import('node:path')
+  const audit = createAtomicClassAudit()
+  const inventory: string[] = []
+  const failures: { file: string, line: number, token: string, message: string }[] = []
+  try {
+    for (const root of roots) {
+      const files = await glob(root.patterns ?? ['**/*.{astro,svelte,mdx,html,ts,tsx,js,jsx,vue}'], {
+        cwd: root.directory,
+        ignore: ['**/node_modules/**', '**/dist/**', '**/out/**', '**/.astro/**', '**/.cache/**', '**/*.test.*', '**/*.spec.*', '**/tests/**']
+      })
+      if (!files.length) throw new Error(`Empty authoring audit root: ${root.name}`)
+      for (const file of files.sort()) {
+        const name = `${root.name}/${file}`
+        inventory.push(name)
+        const source = await readFile(resolve(root.directory, file), 'utf8')
+        const extension = extname(file)
+        const language = ({ '.astro': 'astro', '.svelte': 'svelte', '.mdx': 'mdx', '.vue': 'vue' } as Record<string, string>)[extension] ?? (/\.[jt]sx?$/.test(file) ? 'typescriptreact' : 'html')
+        const add = (text: string, languageId: string, offset = 0) => {
+          for (const issue of audit.inspect(text, languageId)) {
+            failures.push({ file: name, line: source.slice(0, offset + issue.range.start).split('\n').length, token: issue.token, message: issue.message })
+          }
+        }
+        add(source, language)
+        // Preserve the existing policy's escaped HTML generator coverage.
+        if (language === 'typescriptreact') for (const match of source.matchAll(/"(?:\\.|[^"\\])*"/g)) {
+          if (!match[0].includes('class=\\"')) continue
+          add(JSON.parse(match[0]), 'html', match.index)
+        }
+      }
+    }
+  } finally { audit.dispose() }
+  return { inventory, failures }
+}

package/src/scripts/style-delivery.mjs

@@ -0,0 +1,110 @@
+/** Audit the built CSS graph. Bytes are asset sizes, not browser transfer estimates. */
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises'
+import { resolve, relative, dirname } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { createHash } from 'node:crypto'
+import { gzipSync, brotliCompressSync } from 'node:zlib'
+
+export async function filesAt(root) {
+  const files = []
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const file = resolve(root, entry.name)
+    if (entry.isDirectory()) files.push(...await filesAt(file))
+    else files.push(file)
+  }
+  return files.sort()
+}
+const hash = text => createHash('sha256').update(text).digest('hex')
+const sizes = text => ({ bytes: Buffer.byteLength(text), gzip: gzipSync(text).length, brotli: brotliCompressSync(text).length })
+const attributes = text => Object.fromEntries([...text.matchAll(/([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)].map(m => [m[1], m[2] ?? m[3]]))
+export const importsOf = css => [...css.replace(/\/\*[\s\S]*?\*\//g, '').matchAll(/@import\s+(?:url\(\s*)?["']([^"']+)["']/g)].map(m => m[1])
+const families = ['sidebar', 'toc', 'pager', 'tree', 'tray', 'switch', 'range', 'chart', 'code', 'table']
+
+export async function auditStyles(directory) {
+  const root = resolve(directory), assets = {}, routes = {}
+  const origin = 'https://style-audit.invalid'
+  async function asset(href) {
+    if (assets[href]) return assets[href]
+    const file = resolve(root, '.' + decodeURIComponent(href))
+    if (!file.startsWith(root + '/')) throw new Error(`CSS escapes output: ${href}`)
+    const css = await readFile(file, 'utf8')
+    return assets[href] = { ...sizes(css), sha256: hash(css), imports: importsOf(css), css }
+  }
+  for (const file of await filesAt(root)) {
+    if (!file.endsWith('.html')) continue
+    const html = await readFile(file, 'utf8'), seen = new Set()
+    const pathname = '/' + relative(root, file).replaceAll('\\', '/')
+    const route = pathname === '/index.html' ? '/' : pathname.replace(/(?:\/index)?\.html$/, '')
+    let depth = 0
+    async function walk(href, parent, level, ancestors = []) {
+      const url = new URL(href, origin + parent)
+      if (url.origin !== origin || url.protocol !== 'https:') return
+      const key = url.pathname
+      if (ancestors.includes(key)) throw new Error(`Cyclic CSS import: ${[...ancestors, key].join(' -> ')}`)
+      depth = Math.max(depth, level)
+      const item = await asset(key)
+      seen.add(key)
+      for (const dep of item.imports) await walk(dep, key, level + 1, [...ancestors, key])
+    }
+    const links = [...html.matchAll(/<link\b([^>]+)>/g)].map(m => attributes(m[1])).filter(a => a.rel === 'stylesheet').map(a => a.href)
+    for (const href of links) await walk(href, pathname, 1)
+    const inline = [...html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/g)].map(m => m[1])
+    for (const css of inline) for (const href of importsOf(css)) await walk(href, pathname, 1)
+    const texts = [...seen].map(href => assets[href].css)
+    const delivered = [...texts, ...inline].join('\n')
+    const totals = [...seen].map(href => assets[href]).concat(inline.map(sizes))
+    routes[route] = {
+      links, assets: [...seen], files: seen.size, depth,
+      ...Object.fromEntries(['bytes', 'gzip', 'brotli'].map(k => [k, totals.reduce((n, x) => n + x[k], 0)])),
+      inlineBytes: inline.reduce((n, s) => n + Buffer.byteLength(s), 0),
+      families: Object.fromEntries(families.map(name => [name, new RegExp(`(?:^|[;{}])\\s*\\.ui-${name}\\s*\\{`).test(delivered)])),
+      foundationCount: [...delivered.matchAll(/body,\s*:host\s*\{\s*font-family:\s*var\(--font-family-sans\)/g)].length,
+      uncompiled: /(?:^|[;{}])\s*@(apply|compose|reference|prune|light|dark|variant|theme|mixin|utility|master|source|safelist|blocklist)\b/.test(delivered),
+      layerOrder: [...new Set([...delivered.matchAll(/@layer\s+([\w-]+(?:\s*,\s*[\w-]+)*)\s*[;{]/g)].flatMap(m => m[1].split(/\s*,\s*/)))],
+    }
+  }
+  return { version: 1, routes, assets: Object.fromEntries(Object.entries(assets).map(([href, { css, ...item }]) => [href, item])) }
+}
+
+/** Exact per-route ceilings. New routes require an explicit reviewed budget. */
+export function assertStyleBudget(report, budget) {
+  const failures = []
+  if (!Object.keys(report.routes).length) throw new Error('Empty style delivery inventory')
+  for (const [route, item] of Object.entries(report.routes)) {
+    const cap = budget.routes[route]
+    if (!cap) { failures.push(`${route}: missing reviewed budget`); continue }
+    for (const key of ['files', 'depth', 'gzip', 'brotli', 'inlineBytes']) {
+      if (item[key] > cap[key]) failures.push(`${route}: ${key} ${item[key]} > ${cap[key]}`)
+    }
+    if (item.foundationCount !== 1) failures.push(`${route}: foundation count ${item.foundationCount}`)
+    if (item.layerOrder.join(',') !== 'theme,base,defaults,components,utilities') failures.push(`${route}: layer order`)
+    if (item.uncompiled) failures.push(`${route}: uncompiled directives`)
+    if (['/', '/404', '/tw', '/tw/404'].includes(route)) {
+      for (const name of ['sidebar', 'toc', 'pager', 'switch', 'range']) if (item.families[name]) failures.push(`${route}: unrelated ${name}`)
+    }
+  }
+  for (const route of Object.keys(budget.routes)) if (!report.routes[route]) failures.push(`${route}: missing route`)
+  if (failures.length) throw new Error(failures.join('\n'))
+}
+
+export function compareStyles(before, after) {
+  return Object.entries(after.routes).map(([route, b]) => {
+    const a = before.routes[route]
+    return { route, ...(a ? Object.fromEntries(['files', 'depth', 'bytes', 'gzip', 'brotli'].map(k => [k, b[k] - a[k]])) : { added: true }) }
+  })
+}
+
+export async function runStyleAudit(args) {
+  const [root, output, comparison, cap] = args
+  const baseline = comparison === '--budget' ? undefined : comparison
+  const budget = cap
+  if (!root || !output) throw new Error('Usage: node style-delivery.mjs <built-output> <report.json> [baseline.json]')
+  const report = await auditStyles(root)
+  await mkdir(dirname(resolve(output)), { recursive: true })
+  await writeFile(output, JSON.stringify(report, null, 2) + '\n')
+  if (budget) assertStyleBudget(report, JSON.parse(await readFile(budget, 'utf8')))
+  if (baseline) console.log(JSON.stringify(compareStyles(JSON.parse(await readFile(baseline, 'utf8')), report), null, 2))
+  else console.log(`${Object.keys(report.routes).length} routes, ${Object.keys(report.assets).length} CSS assets audited`)
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) await runStyleAudit(process.argv.slice(2))

package/src/sections/blog.astro

@@ -2,7 +2,7 @@
 import DocumentShell from './document.astro'
 import DocHeader from '@master/internal-site/components/DocHeader.svelte'
 
-export const bodyClass = '(background-repeat:no-repeat) (background-image:linear-gradient(oklch(100%|0|none),var(--color-zinc-0)|100vh,var(--color-zinc-0))) (background-size:cover) (background-image:linear-gradient(var(--color-zinc-90),var(--color-zinc-95)|100vh,var(--color-zinc-95)))@apply(--site-dark)'
+export const bodyClass = 'blog-page'
 ---
 
 <DocumentShell>

package/src/sections/guide.astro

@@ -14,11 +14,10 @@ const sidebarCategories = pageCategories.map(({ name, pages }) => ({
   name,
   pages: pages.map(({ title, pathname, other }: { title: MetadataTitle, pathname: string, other?: { subject: string } }) => other ? { title, pathname, other } : { title, pathname })
 }))
-const menuCategories = sidebarCategories.map(category => ({ ...category, pages: category.pages.filter(page => page.pathname.split('/').length === 3) }))
 ---
 
 <DocumentShell>
-  <DocHeader client:load contained documentNavigation={menuCategories} documentNavigationTitle="Guide" />
+  <DocHeader client:load contained />
   <DocWrapper>
     <DocSidebar client:load pageCategories={sidebarCategories} />
     <slot />

package/src/styles/blog-article.css

@@ -91,6 +91,16 @@
 
   /* ───────────────────────── Masthead ───────────────────────── */
 
+  .blog-article-cover {
+    display: block;
+    width: 100%;
+    height: auto;
+    margin-top: 2rem;
+    border-radius: var(--ui-radius-xl);
+    outline: 1px solid var(--ui-line-contour);
+    outline-offset: -1px;
+  }
+
   .blog-article-masthead {
     position: relative;
     min-width: 0;
@@ -650,13 +660,6 @@
   }
 }
 
-/* The page ground runs under the overscroll and behind the footer. */
-:root:has(.blog-article-page),
-:root:has(.blog-article-page) > body {
-  background-color: light-dark(var(--color-zinc-0), var(--color-zinc-95));
-  background-image: none;
-}
-
 /* Paper is white whatever the screen's scheme: every token resolves its light value. */
 @media print {
   :root:has(.blog-article-page) {

package/src/styles/blog-materials.css

@@ -40,6 +40,19 @@
  * Accessibility: reduced motion drops transitions; more contrast lifts quiet text, contours and guides; forced
  * colors and print use Canvas / CanvasText and drop the decorative guides.
  */
+/* The canvas continues through the footer and overscroll in either theme. */
+:root:has(body.blog-page),
+body.blog-page {
+  background-color: light-dark(var(--color-zinc-0), var(--color-zinc-95));
+  background-image: none;
+}
+
+@media print {
+  :root:has(body.blog-page) {
+    color-scheme: light;
+  }
+}
+
 @layer components {
   .blog-materials {
     /* The page's own ground, the same the footer stands on, so the index never sits in a tray. */

package/src/styles/demo.css

@@ -7,7 +7,6 @@
   .ui-tray > .ui-disclosure > :not(summary) { margin-inline: calc(var(--ui-space-sm) * -1); }
   /* The panel's own padding is part of the summary's inset: its chevron starts where the code lines start. */
   .ui-tray > details.ui-disclosure > summary { padding-inline: calc(var(--ui-space-md) - var(--ui-space-sm)); }
-  .ui-tray > .ui-disclosure .ui-code { border-radius: 0 0 var(--ui-radius-xl) var(--ui-radius-xl); background: transparent; box-shadow: inset 0 1px 0 var(--ui-line-hair); }
 
   /* A copy group's instruction is a caption over its swatches, not a button's status: one start-aligned sans line. */
   p.ui-copy > .ui-copy-status { max-width: none; color: var(--ui-text-muted); font: var(--ui-weight-regular) var(--ui-text-caption)/1.5 var(--font-family-sans); text-align: start; }

package/src/styles/docs-shell/code.css

@@ -1,61 +1,5 @@
-/*
- * Code panels (`ui-code`, styles/system/code.css) as the site renders them: Shiki lines are `ui-code-line` parts, the
- * copy action sits in the bar or, without one, in the corner, and tab panels all show on paper and without scripts.
- */
-@layer components {
-  /* The file's name keeps its width; a long result wraps in the room left beside the copy button. */
-  .ui-code-bar > .ui-code-file { flex: 1 0 auto; }
-  .ui-code-bar > .ui-copy { flex: 0 1 auto; min-width: 0; margin-left: auto; }
-  /* Without a bar the copy takes the panel's corner (`--code-corner`, code.css). A long line scrolls under it: the panel's own face fades in behind the button and runs to the edge, so code never runs through it. */
-  .ui-code > .ui-copy { position: absolute; z-index: 1; top: var(--code-corner); right: var(--code-corner); padding-left: var(--ui-space-sm); border-radius: var(--ui-radius-md); background: linear-gradient(90deg, transparent, var(--ui-surface-code) var(--ui-space-sm));
-    /* The face runs on to the panel's contour (1px short of the edge), so a scrolled line never shows again past the button. */
-    box-shadow: calc(var(--code-corner) - 1px) 0 0 var(--ui-surface-code); }
-  .ui-code:has(> .ui-copy) .ui-code-line { padding-right: 3rem; }
-  /* A shell command is read whole: it wraps under a hanging indent instead of hiding its flags behind the copy button. */
-  :is(.ui-code, [role="tabpanel"])[data-lang="bash"] > pre, .ui-code[data-lang="sh"] > pre, .ui-code[data-lang="shell"] > pre { white-space: pre-wrap; overflow-wrap: anywhere; }
-  :is(.ui-code, [role="tabpanel"])[data-lang="bash"] > pre .ui-code-line, .ui-code:is([data-lang="sh"], [data-lang="shell"]) > pre .ui-code-line { padding-left: calc(var(--ui-space-md) + 2ch); text-indent: -2ch; }
-  /* Flags wrap whole: a token never breaks at its own hyphen, so `--yes` cannot split into `-` and `-yes`. */
-  :is(.ui-code, [role="tabpanel"])[data-lang="bash"] > pre .ui-code-line > span, .ui-code:is([data-lang="sh"], [data-lang="shell"]) > pre .ui-code-line > span { display: inline-block; text-indent: 0; }
-  /* Plain text, such as a prompt for an agent, is prose set in mono: it wraps at the panel like prose. */
-  :is(.ui-code, [role="tabpanel"])[data-lang="text"] > pre { white-space: pre-wrap; overflow-wrap: break-word; }
-  .ui-copy-status:empty { display: none; }
-
-  /* A Generated CSS disclosure right after its source closes the same panel: one frame, the output under a hairline,
-     as in a demo tray. Alone (after a table or a paragraph) it stays a quiet disclosure. */
-  .ui-prose > .ui-code:has(+ .ui-disclosure[data-generated]) { margin-bottom: 0; border-end-start-radius: 0; border-end-end-radius: 0; box-shadow: inset 1px 0 0 var(--ui-line-contour), inset -1px 0 0 var(--ui-line-contour), inset 0 1px 0 var(--ui-line-contour); }
-  .ui-prose > .ui-code + .ui-disclosure[data-generated] {
-    max-width: none; margin-top: 0; margin-inline: calc(var(--bleed) * -1); padding-inline: var(--ui-space-md);
-    border-radius: 0 0 var(--ui-radius-xl) var(--ui-radius-xl); background: var(--ui-surface-code);
-    box-shadow: inset 0 0 0 1px var(--ui-line-contour), 0 1px 0 var(--ui-lip);
-  }
-  .ui-prose > .ui-code + .ui-disclosure[data-generated] > summary { margin-inline: calc(var(--ui-space-md) * -1); padding-inline: var(--ui-space-md); box-shadow: inset 0 1px 0 var(--ui-line-hair); }
-  .ui-prose > .ui-code + .ui-disclosure[data-generated] > .ui-code { margin-inline: calc(var(--ui-space-md) * -1); border-radius: 0 0 var(--ui-radius-xl) var(--ui-radius-xl); background: transparent; box-shadow: inset 0 1px 0 var(--ui-line-hair); }
-  .ui-copy > .ui-copy-status { min-width: 0; max-width: 16rem; text-align: end; line-height: 1.3; }
-
-  /* @WARN and @ERROR marks: a wavy underline in the status tone instead of a wash. */
-  .ui-code-line mark[data-tone] { padding: 0; background: none; box-shadow: none; text-decoration: underline wavy 1px; text-underline-offset: 3px; }
-  .ui-code-line mark[data-tone="warning"] { text-decoration-color: var(--ui-status-warning); }
-  .ui-code-line mark[data-tone="danger"] { text-decoration-color: var(--ui-status-danger); }
-  /* [!code focus] blurs the other lines until the pointer reaches the code. */
-  .ui-code pre.has-focused .ui-code-line { transition: filter var(--ui-duration-base) var(--ui-ease); }
-  .ui-code pre.has-focused:not(:hover, :focus-visible) .ui-code-line:not(.focus) { filter: blur(3px); }
-  .ui-code ::selection { background: color-mix(in oklab, var(--ui-code-function) 22%, transparent); }
-
-  [data-code-tabs] > [role="tabpanel"] > .ui-code-file { display: none; }
-  @media (scripting: none), print {
-    [data-code-tabs] > .ui-code-bar { display: none; }
-    [data-code-tabs] > [role="tabpanel"][hidden] { display: block; }
-    [data-code-tabs] > [role="tabpanel"] > .ui-code-file { display: flex; padding: var(--ui-space-sm) var(--ui-space-md) 0; }
-    .ui-copy { display: none; }
-  }
-  @media print {
-    .ui-code { break-inside: avoid; }
-    /* Paper cannot scroll: keep complete commands and long source lines readable. */
-    .ui-code pre { overflow: visible; white-space: pre-wrap; overflow-wrap: anywhere; }
-    .ui-code pre.has-focused .ui-code-line { filter: none; }
-  }
-  @media (prefers-reduced-motion: reduce) { .ui-code pre.has-focused .ui-code-line { transition: none; } }
-  @media (forced-colors: active) { .ui-code { border: 1px solid CanvasText; } }
-
-  .ui-tree img { flex: none; align-self: center; width: 14px; height: 14px; }
-}
+/* Compatibility code entry; owners use these same leaves directly. */
+@import '../system/code-panel.css';
+@import '../system/code-tabs.css';
+@import '../system/copy.css';
+@import '../system/disclosure.css';

package/src/styles/docs-shell/documentation-search.css

@@ -29,6 +29,7 @@
   .ui-results > li > a:focus-visible { @apply --ui-focus-ring; outline-offset: -2px; }
   .ui-dialog-foot { flex: none; }
   .ui-dialog-foot > span:last-child { margin-left: auto; }
+  .ui-search-shortcut { white-space: nowrap; }
   .ui-dialog-foot .ui-kbd svg { width: 12px; height: 12px; }
   @media (width < 48rem) {
     .ui-dialog[data-variant="search"] { width: 100%; max-width: 100%; height: 100dvh; max-height: 100dvh; margin: 0; border-radius: 0; }

package/src/styles/docs-shell/header.css

@@ -1,73 +1,2 @@
-/*
- * The site header (`ui-header`, styles/system/shell.css) placed for the site: it sticks above documentation pages and
- * overlays the homepage and blog as a stickable header that slides away while reading down (`data-tucked`) and is
- * transparent at the top of the page (`data-background="transparent"`).
- */
-@layer components {
-  .ui-header { padding-top: env(safe-area-inset-top); padding-inline: max(var(--ui-space-xl), env(safe-area-inset-left)) max(var(--ui-space-xl), env(safe-area-inset-right)); height: calc(3.75rem + env(safe-area-inset-top)); box-sizing: border-box; }
-  .ui-header[data-variant="stickable"] { position: fixed; inset: 0 0 auto; width: 100%; transition: translate var(--ui-duration-base) var(--ui-ease), background-color var(--ui-duration-base), box-shadow var(--ui-duration-base); }
-  .ui-header[data-tucked] { translate: 0 -100%; }
-  /* A focused control stays on screen after the header has tucked away, revealed at once. */
-  .ui-header:focus-within { translate: none; transition-duration: 0s; }
-  .ui-header[data-background="transparent"] { background: transparent; box-shadow: none; -webkit-backdrop-filter: none; backdrop-filter: none; }
-  /* Without scripts the header never leaves its transparent top state, so it scrolls away instead of covering content. */
-  @media (scripting: none) { .ui-header[data-background="transparent"] { position: absolute; } }
-  @media (prefers-reduced-motion: reduce) { .ui-header, .ui-header[data-variant="stickable"] { transition: none; } }
-  @media print { .ui-header { display: none; } }
-
-  .ui-header-brand { display: inline-flex; align-items: center; min-height: 2.75rem; border-radius: var(--ui-radius-sm); }
-  .ui-header-brand:focus-visible { @apply --ui-focus-ring; outline-offset: 2px; }
-  /* The version chip opens the native version list laid over it. */
-  .ui-header .ui-version { position: relative; cursor: pointer; }
-  .ui-header .ui-version > svg { width: 12px; height: 12px; color: var(--ui-text-muted); }
-  .ui-header .ui-version:hover { color: var(--ui-text-strong); }
-  .ui-header-nav > a > .ui-badge { margin-left: var(--ui-space-2xs); }
-  /* External destinations carry a small raised arrow beside the label or icon. */
-  .ui-header-nav > a:has(.ui-header-external) { position: relative; padding-right: 1.125rem; }
-  .ui-header-nav > a > .ui-header-external, .ui-header-end > .ui-button > .ui-header-external { position: absolute; top: .375rem; right: .125rem; width: .625rem; height: .625rem; pointer-events: none; }
-  .ui-header-end > .ui-button > .ui-header-external { top: .125rem; right: 0; }
-  .ui-header-end > .ui-button[data-disabled] { color: var(--ui-text-disabled); pointer-events: none; }
-  /* The community and preference icons are words in the bar, not buttons: ink under the pointer, no material. */
-  .ui-header-end > .ui-button[data-shape="icon"] { width: 2.25rem; min-height: 2.25rem; }
-  .ui-header-end > .ui-button > svg, .ui-header-menu > svg, .ui-dialog-bar > .ui-button > svg { width: 1.125rem; height: 1.125rem; }
-  .ui-header-end > .ui-button[data-variant="quiet"]:where(:hover):not(:disabled) { background: transparent; box-shadow: none; }
-
-  /* Icon-only controls name themselves with an ink tooltip under the pointer or keyboard focus. */
-  .ui-header-end > :is(a, button, label) { position: relative; }
-  .ui-header-end > * > .ui-tooltip { top: calc(100% + 8px); left: 50%; translate: -50% 0; opacity: 0; visibility: hidden; transition: opacity var(--ui-duration-quick), visibility 0s linear var(--ui-duration-quick); }
-  .ui-header-end > :is(:hover, :focus-visible, :has(:focus-visible)) > .ui-tooltip { opacity: 1; visibility: visible; transition-delay: 400ms, 400ms; }
-  .ui-header-end > :last-child > .ui-tooltip { left: auto; right: 0; translate: none; }
-  .ui-header-end > :last-child > .ui-tooltip::before { left: auto; right: calc(1rem - 4px); translate: none; }
-  @media (hover: none) { .ui-header-end > * > .ui-tooltip { display: none; } }
-
-  /* Search: a quiet hairline pill that leads the end group — the glass and its shortcut, ink under the pointer. */
-  /* The round end takes a little more room than the glass's side; the gap to the first icon matches the icons' own spacing. */
-  .ui-header-search { appearance: none; display: inline-flex; align-items: center; gap: .4375rem; height: 1.875rem; margin-right: var(--ui-space-xs); padding: 0 .8125rem 0 .6875rem; border: 0; border-radius: var(--ui-radius-pill);
-    background: transparent; color: var(--ui-text-muted); box-shadow: inset 0 0 0 1px var(--ui-line-contour); font: var(--ui-weight-regular) .75rem/1 var(--font-family-sans); cursor: pointer;
-    transition: color var(--ui-duration-quick), box-shadow var(--ui-duration-quick), background-color var(--ui-duration-quick); }
-  .ui-header-search:hover { color: var(--ui-text-strong); background: var(--ui-surface-chip); box-shadow: inset 0 0 0 1px var(--ui-line-strong); }
-  .ui-header-search:focus-visible { @apply --ui-focus-ring; outline-offset: 2px; }
-  .ui-header-search > svg { flex: none; width: 1rem; height: 1rem; }
-  .ui-header-search > .ui-kbd { min-width: 0; height: auto; padding: 0; background: none; color: inherit; box-shadow: none; font: var(--ui-weight-regular) .6875rem/1 var(--font-family-sans); letter-spacing: .04em; }
-
-  /* The compact header: the menu at the start, the brand centred, search at the end. */
-  .ui-header-menu { display: none; }
-  @media (width < 64rem) {
-    .ui-header { gap: var(--ui-space-xs); padding-inline: max(var(--ui-space-xs), env(safe-area-inset-left)) max(var(--ui-space-xs), env(safe-area-inset-right)); }
-    .ui-header-menu { display: inline-flex; }
-    .ui-header-brand { margin-inline: auto; }
-    .ui-header > :is(.ui-version, .ui-header-nav), .ui-header-end > :not(.ui-header-search) { display: none; }
-    .ui-header-end { margin-left: 0; }
-    /* On a phone search is a plain glass in a full target. */
-    .ui-header-search { justify-content: center; width: 2.375rem; height: 2.375rem; margin: 0; padding: 0; border-radius: var(--ui-radius-md); box-shadow: none; }
-    .ui-header-search:hover { background: transparent; box-shadow: none; }
-    .ui-header-search > svg { width: 1.125rem; height: 1.125rem; }
-    .ui-header-search > .ui-kbd { display: none; }
-    /* The menu and search buttons keep the brand centred between equal ends. */
-    .ui-header:not(:has(.ui-header-search)) .ui-header-end { width: 2.375rem; }
-  }
-  @media (width >= 64rem) {
-    /* The homepage's wide header leaves search out. */
-    .ui-header-search[data-compact] { display: none; }
-  }
-}
+/* Compatibility entry; the component owns base and adaptation together. */
+@import '../system/header-core.css';

package/src/styles/docs-shell/menu.css

@@ -1,19 +1,39 @@
-/*
- * The compact header's menu: a `ui-dialog` that fills the viewport below 64rem (`data-variant="sheet"`), with a bar
- * (close, brand) and a reading-width body of navigation groups, the section's chapters and the preferences.
- */
+/* Primary navigation fills the compact viewport; documents stay in their section indexes. */
 @layer components {
-  html:has(.ui-dialog[data-variant="sheet"][open]) { overflow: hidden; scrollbar-gutter: stable; }
-  .ui-dialog[data-variant="sheet"] { position: fixed; inset: 0; width: 100%; max-width: 100%; height: 100dvh; max-height: 100dvh; margin: 0; overflow-y: auto; overscroll-behavior: contain; border-radius: 0; background: var(--ui-surface-canvas); box-shadow: none; }
-  .ui-dialog[data-variant="sheet"]::backdrop { background: transparent; }
-  .ui-dialog-bar { position: sticky; top: 0; z-index: 1; display: grid; grid-template-columns: 2.375rem minmax(0, 1fr) 2.375rem; align-items: center; height: calc(3.75rem + env(safe-area-inset-top)); padding: env(safe-area-inset-top) max(var(--ui-space-xs), env(safe-area-inset-right)) 0 max(var(--ui-space-xs), env(safe-area-inset-left));
-    background: color-mix(in oklab, var(--ui-surface-canvas) 82%, transparent); -webkit-backdrop-filter: blur(16px) saturate(1.3); backdrop-filter: blur(16px) saturate(1.3); box-shadow: inset 0 -1px 0 var(--ui-line-hair); }
-  .ui-dialog-bar > .ui-header-brand { justify-self: center; }
-  .ui-dialog[data-variant="sheet"] > .ui-dialog-body { display: grid; gap: var(--ui-space-xl); max-width: 36rem; margin-inline: auto; padding: var(--ui-space-lg) max(var(--ui-space-md), env(safe-area-inset-right)) max(var(--ui-space-2xl), env(safe-area-inset-bottom)) max(var(--ui-space-md), env(safe-area-inset-left)); }
-  .ui-dialog[data-variant="sheet"] .ui-nav-link { gap: .625rem; min-height: 2.75rem; }
-  .ui-dialog[data-variant="sheet"] .ui-nav-link > svg { flex: none; color: var(--ui-text-muted); }
-  .ui-dialog[data-variant="sheet"] .ui-nav-link > svg:last-child:not(:first-child) { margin-left: auto; }
-  .ui-dialog[data-variant="sheet"] .ui-disclosure > .ui-sidebar { padding: 0 0 var(--ui-space-md); }
-  .ui-dialog-fields { display: grid; gap: var(--ui-space-md); }
-  .ui-dialog-fields > h4 { margin: 0; padding-left: .625rem; color: var(--ui-text-muted); @apply --ui-label-type; }
+  html:has(.ui-mobile-menu[open]) { overflow: hidden; scrollbar-gutter: stable; }
+  /* Tabler's two paths morph into a small X inside the shared header target. */
+  .ui-menu-glyph > path { transform-box: fill-box; transform-origin: center; transition: transform 320ms cubic-bezier(.22, 1, .36, 1); }
+  .ui-menu-glyph[data-open="true"] > path { transform: translateY(4px) rotate(45deg) scaleX(1.06066); }
+  .ui-menu-glyph[data-open="true"] > path + path { transform: translateY(-4px) rotate(-45deg) scaleX(1.06066); }
+
+  .ui-dialog.ui-mobile-menu { position: fixed; inset: 0; width: 100%; max-width: 100%; height: 100dvh; max-height: 100dvh; margin: 0; padding: 0; overflow-y: auto; overscroll-behavior: contain; border-radius: 0; background: var(--ui-surface-canvas); box-shadow: none; opacity: 0; transition: opacity 180ms ease-out; }
+  .ui-dialog.ui-mobile-menu[open] { display: flex; flex-direction: column; }
+  .ui-dialog.ui-mobile-menu[data-open="true"] { opacity: 1; transition-duration: 320ms; }
+  .ui-dialog.ui-mobile-menu::backdrop { background: transparent; -webkit-backdrop-filter: none; backdrop-filter: none; }
+  .ui-mobile-menu-bar { position: sticky; top: 0; z-index: 1; flex: none; display: grid; grid-template-columns: var(--ui-header-target) minmax(0, 1fr) var(--ui-header-target); align-items: center; height: calc(3.75rem + env(safe-area-inset-top)); padding: env(safe-area-inset-top) max(var(--ui-space-xs), env(safe-area-inset-right)) 0 max(var(--ui-space-xs), env(safe-area-inset-left)); background: var(--ui-surface-canvas); }
+  .ui-mobile-menu-bar > .ui-header-brand { justify-self: center; margin: 0; }
+  .ui-mobile-menu-body { flex: 1; display: flex; flex-direction: column; gap: 4rem; width: 100%; max-width: 48rem; margin-inline: auto; padding: clamp(3rem, 10dvh, 6rem) max(clamp(1.5rem, 6vw, 3rem), env(safe-area-inset-right)) max(1.5rem, env(safe-area-inset-bottom)) max(clamp(1.5rem, 6vw, 3rem), env(safe-area-inset-left)); transform: translateY(-8px); transition: transform 180ms ease-out; }
+  .ui-mobile-menu[data-open="true"] .ui-mobile-menu-body { transform: translateY(0); transition: transform 320ms cubic-bezier(.22, 1, .36, 1); }
+  .ui-mobile-menu-nav { display: grid; gap: .5rem; }
+  .ui-mobile-menu-link { display: flex; align-items: baseline; gap: .5rem; width: fit-content; max-width: 100%; min-height: 2.75rem; padding-block: .375rem; border: 0; background: none; color: var(--ui-text-strong); font: 500 clamp(2.25rem, 11vw, 3.5rem)/1.3 var(--font-family-sans); letter-spacing: -.045em; text-decoration: none; overflow-wrap: anywhere; opacity: 0; transform: translateY(10px); transition: opacity 180ms ease-out, transform 180ms ease-out, color var(--ui-duration-quick); }
+  .ui-mobile-menu-link > span { min-width: 0; }
+  .ui-mobile-menu-link > svg { flex: none; align-self: flex-start; margin-top: .65em; color: var(--ui-text-muted); }
+  .ui-mobile-menu[data-open="true"] .ui-mobile-menu-link { opacity: 1; transform: translateY(0); transition: opacity 320ms ease-out, transform 320ms cubic-bezier(.22, 1, .36, 1), color var(--ui-duration-quick); transition-delay: calc(var(--menu-order) * 40ms), calc(var(--menu-order) * 40ms), 0s; }
+  .ui-mobile-menu-link[aria-current] > span { text-decoration: underline; text-decoration-thickness: 1px; text-underline-offset: .2em; text-decoration-color: var(--ui-line-mark); }
+  .ui-mobile-menu-link:focus-visible, .ui-mobile-menu-community > a:focus-visible { @apply --ui-focus-ring; outline-offset: 5px; border-radius: var(--ui-radius-sm); }
+  .ui-mobile-menu-footer { display: grid; gap: 1rem; margin-top: auto; }
+  .ui-mobile-menu-community { display: flex; flex-wrap: wrap; gap: .5rem; margin-left: -.75rem; }
+  .ui-mobile-menu-community > a { position: relative; display: inline-flex; align-items: center; justify-content: center; min-width: 2.75rem; min-height: 2.75rem; padding: .5rem .75rem; color: var(--ui-text-muted); text-decoration: none; transition: color var(--ui-duration-quick); }
+  .ui-mobile-menu-community > a > .ui-menu-external { position: absolute; top: calc(50% - .875rem); right: calc(50% - 1rem); width: .625rem; height: .625rem; pointer-events: none; }
+  .ui-mobile-menu-preferences { display: flex; flex-wrap: wrap; align-items: center; gap: .25rem .75rem; padding-top: 1rem; border-top: 1px solid var(--ui-line-hair); }
+  .ui-mobile-menu-preferences > .ui-select { width: auto; max-width: 100%; min-height: 2.75rem; padding-left: 0; padding-right: 1.5rem; background-color: transparent; background-position: right .125rem center; border-radius: var(--ui-radius-sm); box-shadow: none; color: var(--ui-text-muted); font-size: .8125rem; }
+  .ui-mobile-menu-preferences > .ui-select:focus-visible { @apply --ui-focus-ring; outline-offset: 3px; }
+  @media (hover: hover) {
+    .ui-mobile-menu-link:hover, .ui-mobile-menu-community > a:hover { color: var(--ui-text-body); }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .ui-dialog.ui-mobile-menu[data-open], .ui-mobile-menu-body, .ui-mobile-menu-link, .ui-menu-glyph[data-open] > path,
+    .ui-mobile-menu[data-open="true"] .ui-mobile-menu-body, .ui-mobile-menu[data-open="true"] .ui-mobile-menu-link { transition: none; }
+    .ui-mobile-menu-body, .ui-mobile-menu-link { transform: none; }
+  }
 }

package/src/styles/docs-shell/page-content.css

@@ -1,37 +1,2 @@
-/*
- * The page's contents (`ui-toc`, styles/system/shell.css) as the site uses them: the documentation rail (docs.css
- * places it), the narrow-screen disclosure under the page head, and a blog post's margin contents. Sections nest
- * their subsections; the entry being read carries `aria-current="location"`.
- */
-@layer components {
-  .ui-toc a { overflow-wrap: anywhere; text-wrap: pretty; }
-  .ui-toc a code { font-family: var(--font-family-mono); font-size: .9em; }
-  /* A section whose subsection is being read keeps a step of ink. */
-  .ui-toc li:has(> ol [aria-current="location"]) > a { color: var(--ui-text-body); }
-  /* A long list folds: every section stays listed, only the one being read opens its subsections. */
-  .ui-toc ol[data-fold] > li:not(:has([aria-current="location"])) > ol { display: none; }
-  .ui-toc-actions > a:focus-visible { @apply --ui-focus-ring; outline-offset: 2px; border-radius: var(--ui-radius-xs); }
-  .ui-toc-actions > a { text-decoration: none; transition: color var(--ui-duration-quick); }
-  .ui-toc-actions > a:hover { color: var(--ui-text-strong); }
-  /* The rail scrolls and clips, so its rings sit inside the entry. */
-  .ui-toc[data-rail] a:focus-visible { outline-offset: -2px; }
-  @media (pointer: coarse) {
-    .ui-toc { --toc-row-padding: .8125rem; }
-    .ui-toc a { min-height: 2.75rem; }
-    .ui-toc-actions > a { min-height: 2.75rem; }
-  }
-  @media (forced-colors: active) { .ui-toc a[aria-current="location"] { text-decoration: underline; } }
-  @media print { .ui-toc { display: none; } }
-
-  /* Narrow screens: the same contents, closed between hairlines under the page head. */
-  [data-contents-disclosure] { margin-block: 0 var(--ui-space-xl); }
-  [data-contents-disclosure] > .ui-toc { padding: 0 0 var(--ui-space-md); }
-  @media (width >= 80rem) { [data-contents-disclosure] { display: none; } }
-  /* Hidden beside the rail, the disclosure no longer closes the text before the next section, so that heading takes its own hairline again. The page head
-     already parts the page from its first section, and the blog switches its disclosure by its own width. */
-  @media (width >= 80rem) {
-    .ui-docs-article > [data-contents-disclosure]:not(:first-child, .ui-pagehead + *) + h2, .ui-docs-article > [data-contents-disclosure]:not(:first-child, .ui-pagehead + *) + a[id]:empty + h2,
-    .ui-docs-article > [data-contents-disclosure]:not(:first-child, .ui-pagehead + *) + hr + h2, .ui-docs-article > [data-contents-disclosure]:not(:first-child, .ui-pagehead + *) + hr + a[id]:empty + h2 { --section-rule: block; }
-  }
-  @media print { [data-contents-disclosure] { display: none; } }
-}
+/* Compatibility entry; the component owns base and adaptation together. */
+@import '../system/toc.css';