@filipgutica/ui 1.8.1 → 1.10.0

package/README.md

@@ -50,9 +50,10 @@ cancelable `closeAutoFocus` event and focus that heading.
 
 `UiTabs` renders every labelled panel during SSR and initial hydration. After
 mounting, it adds keyboard-accessible tabs and hides inactive panels without
-unmounting them. Use unique item values and keep page anchor headings outside
-the panels. Re-align an initial hash after layout settles if enhancement changes
-the page height.
+unmounting them. A tab strip narrower than its tabs scrolls, fades each clipped
+edge, and keeps the selected tab in view when it resizes. Use unique item values
+and keep page anchor headings outside the panels. Re-align an initial hash after
+layout settles if enhancement changes the page height.
 
 Track page sections from a component's setup function:
 
@@ -68,7 +69,10 @@ The returned readonly ref contains the last supplied heading above the root's
 CSS `scroll-padding-top` inset, or the final section at the document bottom.
 IDs must remain stable and in page order; missing elements are ignored after
 mounting. Bind matching links to `aria-current="location"`. Scrolling, resizing,
-layout changes, completed transitions, and restored pages update the value.
+layout changes, completed transitions, and restored pages update the value. After
+a jump to a section, through a `#id` link, a hash change, or a deep link, that
+section stays current until the reader scrolls away from where the jump lands, so
+a page too short to bring it to the top still marks it.
 The composable does not change focus, the URL, or browser history, and removes
 its listeners and observer when the component unmounts. During SSR it returns
 the first supplied ID without accessing browser globals.
@@ -122,8 +126,9 @@ import { UiSiteHeader } from '@filipgutica/ui/site'
 
 `project` is `wtree`, `annoterm`, `devps`, `workbench`, `filip-stack`, or `ui`. The project
 menu is a native disclosure that works without JavaScript; Escape closes it and
-returns focus to its button. Without a default slot the header renders a
-System, Light, and Dark picker. A page with its own appearance control passes it
+returns focus to its button. Inside `.fg-site-docs`, at 640px and below, the
+header hides `links` so it fits one row, so repeat those destinations in the footer. Without a
+default slot the header renders a System, Light, and Dark picker. A page with its own appearance control passes it
 in the default slot and uses `useSiteAppearance({ applyToRoot: false })` when it
 owns the root element.
 
@@ -167,8 +172,9 @@ import read from './captures/read.html?raw'
 `aria-current="location"`, a text-only marker. An item with `current: true` gets
 `aria-current="page"`, the selected fill and accent bar; `code: true` shows the
 label in the monospace font. The page grid places the rail, which stays in view
-on desktop. At 800px and below it is a native Menu disclosure until the page is
-interactive, then a drawer. The drawer closes on navigation and focuses the
+on desktop. At 800px and below it is a native disclosure until the page is
+interactive, then a drawer. The disclosure, the drawer button, and the drawer
+title all show `label`. The drawer closes on navigation and focuses the
 destination section, and focus follows the visible control across the
 breakpoint.
 
@@ -180,9 +186,11 @@ focus returns to the button on close. Phones show the button as an icon. `v-mode
 holds the active ID and defaults to the first item. Each capture has the ID
 `idPrefix` + `id` (`frame-` by default), so a deep link such as `#frame-read`
 selects its tab on load and on hash change. Without JavaScript every capture is
-listed under its own heading and scrolls at full size. The site owns terminal
-colors: set `--site-capture-bg` on `:root`, because the dialog renders outside
-the panel.
+listed under its own heading and scrolls at full size. Captures use a dark
+terminal palette for the `.term` root and the converter's ANSI classes (`.tf0`
+to `.tf15`, `.tb0` to `.tb15`, `.tf-dim`, `.tbold`, and the others). To change
+it, set `--site-capture-bg`, `--t-bg`, `--t-fg`, `--t-dim`, or `--t0` to `--t15`
+on `:root`, because the dialog renders outside the panel.
 
 `UiCommandList` renders a table of monospace commands and descriptions. Use the
 `command` slot to show a key as `<kbd>`, the `description` slot for `<kbd>` or
@@ -194,9 +202,59 @@ description and wraps.
 
 `site.css` also includes page helpers: `.fg-site-steps` for an ordered list with
 numbered circles, `.fg-site-facts` for an inline `dl` of short label and value
-pairs, `.fg-site-definitions` for a two-column `dl` of `dt` and `dd` that stacks
-on phones, `.fg-site-sr-only` for visually hidden text, and `.fg-site-skip` for
-a skip link that appears on focus.
+pairs whose links get a `--control-lg` hit area at 640px and below,
+`.fg-site-definitions` for a two-column `dl` of `dt` and `dd` that stacks on
+phones and keeps `code` such as `--all` on one line, `.fg-site-sr-only` for
+visually hidden text, and `.fg-site-skip` for a skip link that appears on focus.
+
+### Docs shell
+
+Add `fg-site-docs` to the element that wraps a project page's header, rail,
+main content, and footer. The shell then supplies:
+
+- the frame: the header across the top, the `--sidebar` rail beside `main`, and
+  the footer on the frame edges. At 800px and below the rail stacks above `main`.
+- element defaults inside the shell, plus the page background and font on
+  `body`: box sizing, heading sizes and margins, paragraph measure, links,
+  inline `code` at `--text-sm`, `kbd`, a 2px focus outline, and a `[hidden]`
+  rule that outranks the page's own `display` rules.
+- `.fg-site-footer` for the footer and `.fg-site-legend` for a `dl` that explains
+  what a capture shows. Legend columns are at least `--site-legend-column` wide,
+  `--sidebar` by default; set it on the legend to fit more entries in a row.
+
+```vue
+<template>
+  <div class="fg-site-docs">
+    <UiSiteHeader project="devps" />
+    <UiSiteNav label="On this page" :groups="navigation" />
+    <main id="main">
+      <section aria-labelledby="title">…</section>
+      <dl class="fg-site-legend">
+        <div><dt>PORTS</dt><dd>The ports the server listens on.</dd></div>
+      </dl>
+    </main>
+    <footer class="fg-site-footer">
+      <a href="https://github.com/filipgutica">Built by Filip Gutica</a>
+      <nav aria-label="Project links">
+        <a href="https://github.com/filipgutica/devps/releases">Releases</a>
+      </nav>
+    </footer>
+  </div>
+</template>
+```
+
+The header, rail, `main`, and footer must be direct children of the shell. The
+element defaults sit in the `base` cascade layer, so library components and the
+site's own rules win. That holds only when the site declares the layer order
+before importing `site.css`: `@import "tailwindcss"` does this, or start the
+stylesheet with `@layer base, components, utilities;`. To adopt the shell, delete
+the site's own frame, element base, `kbd`, footer, legend, and ANSI palette
+rules. Without `fg-site-docs`, the frame, element defaults, and phone header
+rules do not apply. These apply on every page: the `fg-site-footer` and
+`fg-site-legend` classes wherever a page uses them; the capture terminal palette
+for every `UiCapture`, in the `components` layer, so a site's own unlayered
+`.term` and ANSI rules and its `--t*` values still win; and `UiSiteNav`, whose
+phone toggle and drawer title now show its `label`.
 
 ## Development
 

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as e, i as t, n, o as r, r as i, t as a } from "./use-active-section-qEJQS1S9.js";
+import { a as e, i as t, n, o as r, r as i, t as a } from "./use-active-section-DCS_wyYq.js";
 import { Fragment as o, computed as s, createBlock as c, createCommentVNode as l, createElementBlock as u, createElementVNode as d, createTextVNode as f, createVNode as p, defineComponent as m, inject as h, mergeModels as g, mergeProps as _, normalizeStyle as v, openBlock as y, provide as b, ref as ee, renderList as x, renderSlot as S, resolveDynamicComponent as C, shallowRef as te, toDisplayString as w, unref as T, useId as E, useModel as ne, useSlots as D, watch as re, withCtx as O } from "vue";
 import { CheckboxIndicator as k, CheckboxRoot as A, Primitive as j, ProgressIndicator as M, ProgressRoot as N, RadioGroupItem as P, RadioGroupRoot as F, SliderRange as I, SliderRoot as L, SliderThumb as R, SliderTrack as z, Toggle as B } from "reka-ui";
 //#region src/components/UiCard.vue?vue&type=script&setup=true&lang.ts

package/dist/site.js

@@ -1,4 +1,4 @@
-import { a as e, i as t, n, o as r, r as i, t as a } from "./use-active-section-qEJQS1S9.js";
+import { a as e, i as t, n, o as r, r as i, t as a } from "./use-active-section-DCS_wyYq.js";
 import { Fragment as o, computed as s, createBlock as c, createCommentVNode as l, createElementBlock as u, createElementVNode as d, createTextVNode as f, createVNode as p, defineComponent as m, mergeModels as h, nextTick as g, normalizeClass as _, normalizeStyle as v, onBeforeUnmount as y, onMounted as b, onUnmounted as x, openBlock as S, ref as C, renderList as w, renderSlot as T, shallowRef as E, toDisplayString as D, unref as O, useId as k, useModel as ee, useSlots as A, useTemplateRef as te, watch as j, withCtx as M } from "vue";
 import { tryOnMounted as N, usePreferredDark as P, useStorage as F } from "@vueuse/core";
 //#region src/site/appearance.ts
@@ -250,7 +250,7 @@ var I = "tool-site-theme", L = (e) => e === "system" || e === "light" || e === "
 		}, [d("summary", {
 			class: "fg-site-rail__summary",
 			"aria-controls": O(t)
-		}, " Menu ", 8, pe), p(Z, {
+		}, D(e.label), 9, pe), p(Z, {
 			"content-id": O(t),
 			label: e.label,
 			groups: e.groups,
@@ -264,7 +264,7 @@ var I = "tool-site-theme", L = (e) => e === "system" || e === "light" || e === "
 			key: 1,
 			open: l.value,
 			"onUpdate:open": h[0] ||= (e) => l.value = e,
-			title: "Navigation",
+			title: e.label,
 			onCloseAutoFocus: E
 		}, {
 			trigger: M(() => [p(r, {
@@ -272,7 +272,7 @@ var I = "tool-site-theme", L = (e) => e === "system" || e === "light" || e === "
 				size: "lg",
 				class: "fg-site-rail__toggle"
 			}, {
-				default: M(() => [...h[1] ||= [f(" Menu ", -1)]]),
+				default: M(() => [f(D(e.label), 1)]),
 				_: 1
 			})]),
 			default: M(() => [p(Z, {
@@ -288,7 +288,7 @@ var I = "tool-site-theme", L = (e) => e === "system" || e === "light" || e === "
 				"active-id"
 			])]),
 			_: 1
-		}, 8, ["open"]))], 8, de));
+		}, 8, ["open", "title"]))], 8, de));
 	}
 }), ge = [
 	"aria-label",

package/dist/{use-active-section-qEJQS1S9.js → use-active-section-DCS_wyYq.js}

@@ -154,7 +154,7 @@ var N = /* @__PURE__ */ c({
 			_: 3
 		}, 8, ["open"]));
 	}
-}), H = { class: "fg-tabs" }, U = ["aria-label"], W = [
+}), H = { class: "fg-tabs" }, U = ["aria-label", "data-clipped"], W = [
 	"id",
 	"aria-controls",
 	"aria-selected",
@@ -180,16 +180,34 @@ var N = /* @__PURE__ */ c({
 		u(() => {
 			l.value = !0;
 		});
-		let C = b("list");
-		x([l, d], () => {
+		let C = b("list"), w = () => {
 			let e = C.value, t = e?.querySelector("[aria-selected=\"true\"]");
 			if (!e || !t) return;
-			let n = e.getBoundingClientRect(), { left: r, right: i } = t.getBoundingClientRect();
-			r < n.left ? e.scrollLeft -= n.left - r : i > n.right && (e.scrollLeft += i - n.right);
-		}, { flush: "post" });
-		let w = (e) => {
+			let n = e.getBoundingClientRect(), r = getComputedStyle(e), i = n.left + (Number.parseFloat(r.scrollPaddingLeft) || 0), a = n.right - (Number.parseFloat(r.scrollPaddingRight) || 0), { left: o, right: s } = t.getBoundingClientRect();
+			o < i ? e.scrollLeft -= i - o : s > a && (e.scrollLeft += s - a);
+		}, T = m(), E = () => {
+			let e = C.value;
+			if (!e) return;
+			let t = e.scrollWidth - e.clientWidth, n = getComputedStyle(e).direction === "rtl" ? e.scrollLeft + t : e.scrollLeft, r = n > 1, i = n < t - 1;
+			T.value = r && i ? "both" : r ? "left" : i ? "right" : void 0;
+		}, D = () => {
+			w(), E();
+		};
+		x([
+			l,
+			d,
+			() => n.items
+		], D, {
+			flush: "post",
+			deep: !0
+		}), x(C, (e, t, n) => {
+			if (!e || typeof ResizeObserver > "u") return;
+			let r = new ResizeObserver(D);
+			r.observe(e), n(() => r.disconnect());
+		});
+		let O = (e) => {
 			e !== d.value && s("update:modelValue", e);
-		}, T = (e) => {
+		}, k = (e) => {
 			if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey || ![
 				"ArrowLeft",
 				"ArrowRight",
@@ -213,7 +231,9 @@ var N = /* @__PURE__ */ c({
 			class: "fg-tabs__list",
 			role: "tablist",
 			"aria-label": n.label,
-			onKeydown: T
+			"data-clipped": T.value,
+			onKeydown: k,
+			onScrollPassive: E
 		}, [(f(!0), i(e, null, h(n.items, (e) => (f(), i("button", {
 			id: p(e.value),
 			key: e.value,
@@ -223,8 +243,8 @@ var N = /* @__PURE__ */ c({
 			"aria-controls": v(e.value),
 			"aria-selected": e.value === d.value,
 			tabindex: e.value === d.value ? 0 : -1,
-			onClick: (t) => w(e.value),
-			onFocus: (t) => w(e.value)
+			onClick: (t) => O(e.value),
+			onFocus: (t) => O(e.value)
 		}, _(e.label), 41, W))), 128))], 40, U)) : r("", !0), (f(!0), i(e, null, h(n.items, (e) => (f(), i("section", {
 			id: v(e.value),
 			key: e.value,
@@ -248,17 +268,35 @@ var N = /* @__PURE__ */ c({
 				id: e,
 				element: t
 			}] : [];
-		}), o = () => {
-			n = void 0;
-			let e = document.documentElement, r = Number.parseFloat(getComputedStyle(e).scrollPaddingTop) || 0, i = a[0]?.id;
-			for (let e of a) e.element.getBoundingClientRect().top <= r + 1 && (i = e.id);
-			window.scrollY > 0 && window.scrollY + window.innerHeight >= e.scrollHeight - 2 && (i = a.at(-1)?.id), t.value = i;
-		}, s = () => {
-			n === void 0 && (n = requestAnimationFrame(o));
+		}), o = document.documentElement, s = () => Number.parseFloat(getComputedStyle(o).scrollPaddingTop) || 0, c, l = () => {
+			if (n = void 0, c) {
+				let e = Math.abs(window.scrollY - c.landing);
+				e > c.closest + 2 ? c = void 0 : c.closest = Math.min(c.closest, e);
+			}
+			let e = s(), r = a[0]?.id;
+			for (let t of a) t.element.getBoundingClientRect().top <= e + 1 && (r = t.id);
+			window.scrollY > 0 && window.scrollY + window.innerHeight >= o.scrollHeight - 2 && (r = a.at(-1)?.id), t.value = c?.id ?? r;
+		}, u = () => {
+			n === void 0 && (n = requestAnimationFrame(l));
+		}, d = (e) => {
+			let t = a.find((t) => t.id === e);
+			if (c = void 0, t) {
+				let n = Math.max(0, o.scrollHeight - window.innerHeight), r = window.scrollY + t.element.getBoundingClientRect().top - s(), i = Math.min(Math.max(r, 0), n);
+				c = {
+					id: e,
+					landing: i,
+					closest: Math.abs(window.scrollY - i)
+				};
+			}
+			u();
+		}, f = () => d(location.hash.slice(1)), p = (e) => {
+			if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+			let t = e.target instanceof Element ? e.target.closest("a[href^=\"#\"]")?.getAttribute("href") : void 0;
+			t && d(t.slice(1));
 		};
-		window.addEventListener("scroll", s, { passive: !0 }), window.addEventListener("resize", s), window.addEventListener("pageshow", s), document.body.addEventListener("transitionend", s), typeof ResizeObserver < "u" && (r = new ResizeObserver(s), r.observe(document.body)), i = () => {
-			window.removeEventListener("scroll", s), window.removeEventListener("resize", s), window.removeEventListener("pageshow", s), document.body.removeEventListener("transitionend", s);
-		}, o();
+		window.addEventListener("scroll", u, { passive: !0 }), window.addEventListener("resize", u), window.addEventListener("pageshow", u), window.addEventListener("hashchange", f), document.addEventListener("click", p), document.body.addEventListener("transitionend", u), typeof ResizeObserver < "u" && (r = new ResizeObserver(u), r.observe(document.body)), i = () => {
+			window.removeEventListener("scroll", u), window.removeEventListener("resize", u), window.removeEventListener("pageshow", u), window.removeEventListener("hashchange", f), document.removeEventListener("click", p), document.body.removeEventListener("transitionend", u);
+		}, location.hash && f(), l();
 	}), d(() => {
 		i?.(), r?.disconnect(), n !== void 0 && cancelAnimationFrame(n);
 	}), p(t);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@filipgutica/ui",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "description": "A compact Vue design system with Tailwind CSS and VS Code theme support",
   "type": "module",
   "sideEffects": [

package/src/components/tabs.css

@@ -12,10 +12,19 @@
     width: max-content;
     max-width: 100%;
     overflow-x: auto;
+    scroll-padding-inline: var(--space-6);
     margin-block-end: var(--space-4);
     border-bottom: 1px solid var(--color-border-subtle);
   }
 
+  /* A strip that scrolls fades each clipped edge; the scroll padding keeps a revealed tab clear
+   * of the fade. Mask stops are alpha only: #000 keeps a pixel and transparent hides it. */
+  .fg-tabs__list[data-clipped="right"] { mask-image: linear-gradient(to right, #000 calc(100% - var(--space-6)), transparent); }
+  .fg-tabs__list[data-clipped="left"] { mask-image: linear-gradient(to left, #000 calc(100% - var(--space-6)), transparent); }
+  .fg-tabs__list[data-clipped="both"] {
+    mask-image: linear-gradient(to right, transparent, #000 var(--space-6), #000 calc(100% - var(--space-6)), transparent);
+  }
+
   .fg-tabs__tab {
     flex: none;
     min-height: var(--control-md);

package/src/components.css

@@ -24,16 +24,16 @@
   .fg-code-block__header {
     display: flex;
     align-items: center;
-    gap: 0.75rem;
+    gap: var(--space-3);
     min-height: 2.5rem;
-    padding: 0.35rem 0.75rem;
+    padding: 0.35rem var(--space-3);
     border-bottom: 1px solid color-mix(in srgb, var(--color-code-text) 16%, transparent);
     background: color-mix(in srgb, var(--color-code-text) 5%, var(--color-code));
-    font-size: 0.75rem;
+    font-size: var(--text-xs);
   }
   .fg-code-block__title { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-weight: 600; }
   .fg-code-block__language { opacity: 0.7; }
-  .fg-code-block__actions { display: flex; align-items: center; gap: 0.5rem; margin-left: auto; flex-shrink: 0; }
+  .fg-code-block__actions { display: flex; align-items: center; gap: var(--space-2); margin-left: auto; flex-shrink: 0; }
   .fg-code-block__copy {
     display: inline-flex;
     align-items: center;
@@ -41,9 +41,9 @@
     gap: 0.4rem;
     min-width: var(--control-lg);
     min-height: var(--control-lg);
-    padding: 0.25rem 0.4rem;
+    padding: var(--space-1) 0.4rem;
     border: 0;
-    border-radius: 0.25rem;
+    border-radius: var(--radius-inline);
     background: transparent;
     color: inherit;
     font: inherit;
@@ -54,15 +54,15 @@
   /* Inset: the code block clips its content. */
   .fg-code-block__copy:focus-visible, .fg-code-block__pre:focus-visible { outline: 2px solid var(--color-focus); outline-offset: -2px; }
   .fg-figure__plate:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 2px; }
-  .fg-code-block__pre { margin: 0; padding: 1rem; overflow: auto; max-height: 32rem; tab-size: 2; }
-  .fg-code-block__pre, .fg-code-block__pre code { font-family: var(--font-mono); font-size: 0.8125rem; line-height: 1.65; }
+  .fg-code-block__pre { margin: 0; padding: var(--space-4); overflow: auto; max-height: 32rem; tab-size: 2; }
+  .fg-code-block__pre, .fg-code-block__pre code { font-family: var(--font-mono); font-size: var(--text-sm); line-height: 1.65; }
   .fg-code-block__pre code { display: block; color: inherit; }
   .fg-code-block__line { display: flex; min-height: 1.65em; }
   .fg-code-block__text { white-space: pre; }
   .fg-code-block__number { min-width: 2.5em; padding-right: 1em; flex-shrink: 0; text-align: right; opacity: 0.5; user-select: none; }
   .fg-code-block[data-wrap="true"] .fg-code-block__text { min-width: 0; white-space: pre-wrap; overflow-wrap: anywhere; }
   .fg-code-block__status:empty { display: none; }
-  .fg-code-block__status:not(:empty) { display: block; padding: 0.5rem 0.75rem; font-size: 0.75rem; }
+  .fg-code-block__status:not(:empty) { display: block; padding: var(--space-2) var(--space-3); font-size: var(--text-xs); }
   .fg-code-block[data-variant="compact"] {
     position: relative;
     display: grid;
@@ -122,7 +122,7 @@
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    gap: 0.5rem;
+    gap: var(--space-2);
     color: var(--color-button-text);
     background: var(--color-button-bg);
     box-shadow: none;
@@ -167,19 +167,19 @@
   .fg-button[data-size="sm"],
   .fg-input[data-size="sm"],
   .fg-select[data-size="sm"] {
-    font-size: 0.8125rem;
+    font-size: var(--text-sm);
   }
 
   .fg-button[data-size="md"],
   .fg-input[data-size="md"],
   .fg-select[data-size="md"] {
-    font-size: 0.875rem;
+    font-size: var(--text-md);
   }
 
   .fg-button[data-size="lg"],
   .fg-input[data-size="lg"],
   .fg-select[data-size="lg"] {
-    font-size: 1rem;
+    font-size: var(--text-lg);
   }
 
   .fg-button[data-size="sm"] { min-height: var(--control-sm); }
@@ -193,20 +193,20 @@
   .fg-select[data-size="lg"] { height: var(--control-lg); }
 
   .fg-button[data-size="sm"] { padding: 0 0.6rem; }
-  .fg-button[data-size="md"] { padding: 0 0.75rem; }
-  .fg-button[data-size="lg"] { padding: 0 1rem; }
+  .fg-button[data-size="md"] { padding: 0 var(--space-3); }
+  .fg-button[data-size="lg"] { padding: 0 var(--space-4); }
 
   /* Deprecated UiButton aliases retained for existing consumers. */
   .fg-button[data-size="compact"] {
     min-height: var(--control-md);
     padding: 0 0.7rem;
-    font-size: 0.8125rem;
+    font-size: var(--text-sm);
   }
 
   .fg-button[data-size="default"] {
     min-height: var(--control-lg);
-    padding: 0 1rem;
-    font-size: 1rem;
+    padding: 0 var(--space-4);
+    font-size: var(--text-lg);
   }
 
   .fg-button[data-variant="secondary"] {
@@ -243,7 +243,7 @@
   .fg-button[data-variant="text"] {
     height: auto;
     min-height: auto;
-    padding: 0.25rem;
+    padding: var(--space-1);
     color: var(--color-link);
     background: transparent;
     text-decoration: underline;
@@ -339,7 +339,7 @@
   .fg-input[data-size="md"] { padding: 0 0.65rem; }
   .fg-input[data-size="lg"] { padding: 0 0.7rem; }
 
-  .fg-select[data-size="sm"] { padding: 0 1.6rem 0 0.5rem; }
+  .fg-select[data-size="sm"] { padding: 0 1.6rem 0 var(--space-2); }
   .fg-select[data-size="md"] { padding: 0 1.7rem 0 0.6rem; }
   .fg-select[data-size="lg"] { padding: 0 1.8rem 0 0.7rem; }
 
@@ -361,14 +361,14 @@
 
   .fg-field__label {
     color: var(--color-text);
-    font-size: 0.8125rem;
+    font-size: var(--text-sm);
     font-weight: 600;
   }
 
   .fg-field__description,
   .fg-field__error {
     margin: 0;
-    font-size: 0.8125rem;
+    font-size: var(--text-sm);
   }
 
   .fg-field__description { color: var(--color-muted); }
@@ -413,21 +413,21 @@
     min-height: var(--control-sm);
     align-items: center;
     gap: 0.45rem;
-    font-size: 0.8125rem;
+    font-size: var(--text-sm);
   }
 
   .fg-checkbox[data-size="md"] {
     min-height: var(--control-md);
     align-items: center;
     gap: 0.55rem;
-    font-size: 0.875rem;
+    font-size: var(--text-md);
   }
 
   .fg-checkbox[data-size="lg"] {
     min-height: var(--control-lg);
     align-items: center;
     gap: 0.65rem;
-    font-size: 1rem;
+    font-size: var(--text-lg);
   }
 
   .fg-checkbox[data-size] .fg-checkbox__control { margin-top: 0; }
@@ -435,7 +435,7 @@
   .fg-checkbox[data-size="sm"] .fg-checkbox__control {
     width: 1rem;
     height: 1rem;
-    border-radius: 0.25rem;
+    border-radius: var(--radius-inline);
   }
 
   .fg-checkbox[data-size="md"] .fg-checkbox__control {
@@ -455,14 +455,14 @@
   .fg-radio-card-group {
     display: grid;
     grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr));
-    gap: 0.75rem;
+    gap: var(--space-3);
   }
 
   .fg-radio-card {
     position: relative;
     display: block;
     min-width: 0;
-    padding: 0.75rem;
+    padding: var(--space-3);
     overflow: hidden;
     border: 1px solid var(--color-border-subtle);
     border-radius: var(--radius-panel);
@@ -493,15 +493,15 @@
   .fg-radio-card__content {
     display: grid;
     min-width: 0;
-    gap: 0.25rem;
+    gap: var(--space-1);
     padding-right: 1.75rem;
   }
 
   .fg-radio-card__indicator {
     position: absolute;
     z-index: 1;
-    top: 0.75rem;
-    right: 0.75rem;
+    top: var(--space-3);
+    right: var(--space-3);
     display: block;
     width: 1rem;
     height: 1rem;
@@ -523,7 +523,7 @@
     padding: 0.18rem 0.48rem;
     color: var(--color-muted);
     background: var(--color-surface-muted);
-    font-size: 0.75rem;
+    font-size: var(--text-xs);
     font-weight: 500;
     line-height: 1.25;
   }
@@ -537,8 +537,8 @@
   .fg-alert {
     display: flex;
     align-items: flex-start;
-    gap: 0.75rem;
-    padding: 0.75rem 1rem;
+    gap: var(--space-3);
+    padding: var(--space-3) var(--space-4);
     border: 1px solid var(--color-border-subtle);
     border-radius: var(--radius-control);
     color: var(--color-text);
@@ -562,8 +562,8 @@
     box-shadow: none;
   }
 
-  .fg-surface[data-padding="compact"] { padding: 0.75rem; }
-  .fg-surface[data-padding="default"] { padding: 1rem; }
+  .fg-surface[data-padding="compact"] { padding: var(--space-3); }
+  .fg-surface[data-padding="default"] { padding: var(--space-4); }
 
   .fg-card {
     min-width: 0;
@@ -805,8 +805,8 @@
     top: 50%;
     left: 50%;
     display: grid;
-    width: min(32rem, calc(100vw - 2rem));
-    max-height: min(42rem, calc(100vh - 2rem));
+    width: min(32rem, calc(100vw - var(--space-8)));
+    max-height: min(42rem, calc(100vh - var(--space-8)));
     overflow: hidden;
     transform: translate(-50%, -50%);
     border: 1px solid var(--color-border-subtle);
@@ -821,8 +821,8 @@
     display: flex;
     align-items: flex-start;
     justify-content: space-between;
-    gap: 1rem;
-    padding: 1rem;
+    gap: var(--space-4);
+    padding: var(--space-4);
   }
 
   .fg-dialog__header { border-bottom: 1px solid var(--color-border-subtle); }
@@ -836,21 +836,21 @@
   }
 
   .fg-dialog__description {
-    margin: 0.25rem 0 0;
+    margin: var(--space-1) 0 0;
     color: var(--color-muted);
-    font-size: 0.875rem;
+    font-size: var(--text-md);
   }
 
   .fg-dialog__body {
     min-height: 0;
     overflow: auto;
-    padding: 1rem;
+    padding: var(--space-4);
   }
 
   .fg-dialog__close {
     display: inline-grid;
     flex: none;
-    width: 2.75rem;
+    width: var(--control-lg);
     min-height: var(--control-lg);
     padding: 0;
     place-items: center;
@@ -900,7 +900,7 @@
       bottom: 0;
       left: 0;
       width: 100%;
-      max-height: calc(100vh - 1rem);
+      max-height: calc(100vh - var(--space-4));
       transform: none;
       border-radius: var(--radius-panel) var(--radius-panel) 0 0;
     }

package/src/site.css

@@ -1,7 +1,120 @@
 /* Shared chrome and page helpers for the project sites. Use with
  * @filipgutica/ui/themes/graphite-indigo.css, which supplies the type, space, and
  * page-measure roles this file reads. Nothing here targets site-specific markup. */
+/* Element defaults for a docs page inside .fg-site-docs. They sit in the base layer, so
+ * library components and the site's own rules win, as long as the site declares the layer
+ * order first (Tailwind's import does, or write @layer base, components, utilities;).
+ * Pages without .fg-site-docs get none of them. */
+@layer base {
+  html:has(.fg-site-docs) { scroll-padding-top: var(--space-6); }
+  body:has(.fg-site-docs) {
+    margin: 0;
+    background: var(--color-bg);
+    color: var(--color-text);
+    font: var(--text-md) / var(--leading) var(--font-ui);
+    -webkit-font-smoothing: antialiased;
+  }
+  .fg-site-docs,
+  .fg-site-docs *,
+  .fg-site-docs *::before,
+  .fg-site-docs *::after { box-sizing: border-box; }
+  .fg-site-docs :where(h1, h2, h3, p, dl, dd, figure) { margin: 0; }
+  .fg-site-docs :where(h1, h2, h3) {
+    font-weight: var(--weight-semibold);
+    line-height: var(--leading-tight);
+    text-wrap: balance;
+  }
+  .fg-site-docs :where(h1) { max-width: 22ch; font-size: var(--text-3xl); letter-spacing: var(--tracking-tight); }
+  .fg-site-docs :where(h2) { font-size: var(--text-xl); }
+  .fg-site-docs :where(p) { max-width: var(--measure); }
+  /* Tab panels and other enhanced markup use the hidden attribute, so it outranks the page's own
+   * display rules. until-found keeps the browser's find-in-page behavior. */
+  .fg-site-docs :where([hidden]:not([hidden="until-found"])) { display: none !important; }
+  .fg-site-docs :where(code, kbd, pre) { font-family: var(--font-mono); }
+  /* Monospace looks larger than the UI face, so inline code steps down: --text-sm in --text-md text.
+   * Code inside pre keeps the block's own size. */
+  .fg-site-docs :where(:not(pre) > code) { font-size: var(--text-sm); }
+  .fg-site-docs :where(a) { color: var(--color-link); text-underline-offset: 0.18em; }
+  .fg-site-docs :where(kbd) {
+    display: inline-block;
+    padding: 0 var(--space-1);
+    border: 1px solid var(--color-border);
+    border-bottom-width: 2px;
+    border-radius: var(--radius-inline);
+    background: var(--color-surface);
+    font-size: var(--text-xs);
+    white-space: nowrap;
+  }
+  .fg-site-docs :where(:focus-visible) { outline: 2px solid var(--color-focus); outline-offset: 2px; }
+}
+
 @layer components {
+  /* Docs shell: header across the top, the --sidebar rail beside main, and the footer
+   * on the frame edges. Header, rail, main, and footer are direct children. */
+  .fg-site-docs {
+    display: grid;
+    grid-template-columns: var(--sidebar) minmax(0, 1fr);
+    column-gap: var(--space-8);
+    max-width: calc(var(--page-max) + var(--sidebar) + var(--space-8) + var(--space-12));
+    margin-inline: auto;
+    padding-inline: var(--space-6);
+  }
+  .fg-site-docs > .fg-site-header {
+    --site-frame: 100%;
+    --site-gutter: 0px;
+    grid-column: 1 / -1;
+    min-width: 0;
+  }
+  .fg-site-docs > main {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: var(--space-12);
+    min-width: 0;
+    padding-block: var(--space-8) var(--space-16);
+  }
+  .fg-site-docs > .fg-site-footer { grid-column: 1 / -1; }
+
+  /* Footer: an attribution link at the start, project links in a nav at the end. */
+  .fg-site-footer {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0 var(--space-5);
+    padding-block: var(--space-6) var(--space-8);
+    border-top: 1px solid var(--color-border-subtle);
+    color: var(--color-muted);
+    font-size: var(--text-sm);
+  }
+  .fg-site-footer nav { display: flex; flex-wrap: wrap; gap: 0 var(--space-5); }
+  .fg-site-footer a {
+    display: inline-flex;
+    min-height: var(--control-lg);
+    align-items: center;
+    color: var(--color-muted);
+    text-decoration: none;
+  }
+  .fg-site-footer a:hover { color: var(--color-text); text-decoration: underline; }
+
+  /* Legend: a dl of what a capture shows, with one div per dt and dd pair. Columns are at
+   * least --site-legend-column wide (default --sidebar); a page can lower it to fit more. */
+  .fg-site-legend {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(min(var(--site-legend-column, var(--sidebar)), 100%), 1fr));
+    gap: 0 var(--space-6);
+    margin: 0;
+    font-size: var(--text-sm);
+  }
+  .fg-site-legend > div {
+    display: grid;
+    align-content: start;
+    gap: var(--space-1);
+    padding-block: var(--space-3);
+    border-top: 1px solid var(--color-border-subtle);
+  }
+  .fg-site-legend dt { font-family: var(--font-mono); font-weight: var(--weight-medium); }
+  .fg-site-legend dd { margin: 0; color: var(--color-muted); }
+
   /* A centered frame. The header uses the same edges as the page below it.
    * Set --site-frame on the header or a frame to change its width. */
   .fg-site-frame,
@@ -138,8 +251,8 @@
   .fg-site-nav a:focus-visible { outline: 2px solid var(--color-focus); outline-offset: -2px; }
 
   /* Section rail (UiSiteNav). The page grid places it; on desktop it stays in view
-   * beside the article. At 800px and below it becomes a Menu disclosure, replaced
-   * by a drawer once the page is interactive. */
+   * beside the article. At 800px and below it becomes a disclosure named by the
+   * label prop, replaced by a drawer once the page is interactive. */
   .fg-site-rail {
     position: sticky;
     top: var(--space-6);
@@ -168,9 +281,9 @@
   .fg-site-rail__group-label { margin-block-end: var(--space-1); }
 
   /* Capture panel (UiCapture): tabs in the header, the capture as the body, and the
-   * command and caption as the footer. The site owns terminal colors and sets the
-   * screen background with --site-capture-bg on :root, which also reaches the
-   * full-size viewer. Nothing clips the panel, so focus rings inside it stay whole. */
+   * command and caption as the footer. The screen uses a dark terminal palette by
+   * default. A site can set --site-capture-bg and --t* values on :root, which also
+   * reach the full-size viewer. Nothing clips the panel, so focus rings inside it stay whole. */
   .fg-capture {
     position: relative;
     min-width: 0;
@@ -220,7 +333,59 @@
     overflow-x: auto;
     background: var(--site-capture-bg, var(--color-code));
   }
+  /* Terminal markup gets the dark default; a plain <pre> keeps the code background its text expects. */
+  .fg-capture__screen:has(> .term) { background: var(--site-capture-bg, var(--t-bg, #131316)); }
   .fg-capture__screen > * { width: max-content; margin: 0; }
+  /* Terminal colors for checked-in capture markup: .term and the ANSI classes the capture
+   * converter emits. Each color reads the site's --t* value first, so a site palette on
+   * :root still wins, and these defaults apply only where a site sets none. */
+  .fg-capture__screen .term {
+    padding: var(--space-4);
+    color: var(--t-fg, #e6e6ea);
+    font: var(--weight-regular) var(--text-sm) / 1 var(--font-mono);
+    font-variant-ligatures: none;
+    tab-size: 8;
+  }
+  .fg-capture__screen .term i { display: inline-block; width: 1ch; overflow: visible; font-style: normal; }
+  .fg-capture__screen .tf0 { color: var(--t0, #2b2b31); }
+  .fg-capture__screen .tf1 { color: var(--t1, #f0776c); }
+  .fg-capture__screen .tf2 { color: var(--t2, #4cc38a); }
+  .fg-capture__screen .tf3 { color: var(--t3, #e2a54b); }
+  .fg-capture__screen .tf4 { color: var(--t4, #7d97ff); }
+  .fg-capture__screen .tf5 { color: var(--t5, #c792ea); }
+  .fg-capture__screen .tf6 { color: var(--t6, #5fd3d9); }
+  .fg-capture__screen .tf7 { color: var(--t7, #c8c8d0); }
+  .fg-capture__screen .tf8 { color: var(--t8, #a0a0ab); }
+  .fg-capture__screen .tf9 { color: var(--t9, #ff8f85); }
+  .fg-capture__screen .tf10 { color: var(--t10, #6fd3a0); }
+  .fg-capture__screen .tf11 { color: var(--t11, #e8b56a); }
+  .fg-capture__screen .tf12 { color: var(--t12, #7d97ff); }
+  .fg-capture__screen .tf13 { color: var(--t13, #d9a8f0); }
+  .fg-capture__screen .tf14 { color: var(--t14, #8ee3e8); }
+  .fg-capture__screen .tf15 { color: var(--t15, #ffffff); }
+  .fg-capture__screen .tb0 { background: var(--t0, #2b2b31); }
+  .fg-capture__screen .tb1 { background: var(--t1, #f0776c); }
+  .fg-capture__screen .tb2 { background: var(--t2, #4cc38a); }
+  .fg-capture__screen .tb3 { background: var(--t3, #e2a54b); }
+  .fg-capture__screen .tb4 { background: var(--t4, #7d97ff); }
+  .fg-capture__screen .tb5 { background: var(--t5, #c792ea); }
+  .fg-capture__screen .tb6 { background: var(--t6, #5fd3d9); }
+  .fg-capture__screen .tb7 { background: var(--t7, #c8c8d0); }
+  .fg-capture__screen .tb8 { background: var(--t8, #a0a0ab); }
+  .fg-capture__screen .tb9 { background: var(--t9, #ff8f85); }
+  .fg-capture__screen .tb10 { background: var(--t10, #6fd3a0); }
+  .fg-capture__screen .tb11 { background: var(--t11, #e8b56a); }
+  .fg-capture__screen .tb12 { background: var(--t12, #7d97ff); }
+  .fg-capture__screen .tb13 { background: var(--t13, #d9a8f0); }
+  .fg-capture__screen .tb14 { background: var(--t14, #8ee3e8); }
+  .fg-capture__screen .tb15 { background: var(--t15, #ffffff); }
+  .fg-capture__screen .tf-dim { color: var(--t-dim, #a0a0ab); }
+  .fg-capture__screen .tf-bg { color: var(--t-bg, #131316); }
+  .fg-capture__screen .tb-fg { background: var(--t-fg, #e6e6ea); }
+  .fg-capture__screen .tbold { font-weight: var(--weight-semibold); }
+  .fg-capture__screen .tital { font-style: italic; }
+  .fg-capture__screen .tul { text-decoration: underline; text-underline-offset: 0.18em; }
+
   .fg-capture__screen[data-fit] { overflow: hidden; }
   .fg-capture__screen[data-fit] > * { transform: scale(var(--capture-scale, 1)); transform-origin: top left; }
   .fg-capture__expand {
@@ -355,6 +520,8 @@
   }
   .fg-site-definitions dt { font-weight: var(--weight-medium); }
   .fg-site-definitions dd { margin: 0; color: var(--color-muted); }
+  /* Keep flags such as --all whole instead of breaking after a hyphen. */
+  .fg-site-definitions code { white-space: nowrap; }
 
   .fg-site-sr-only {
     position: absolute;
@@ -407,6 +574,8 @@
   }
   /* Keep in sync with MOBILE_QUERY in UiSiteNav.vue. */
   @media (max-width: 800px) {
+    .fg-site-docs { grid-template-columns: minmax(0, 1fr); }
+    .fg-site-docs > main { gap: var(--space-8); padding-top: var(--space-6); }
     .fg-site-rail {
       position: static;
       max-height: none;
@@ -432,8 +601,30 @@
     .fg-site-rail__menu .fg-site-rail__group { grid-template-columns: repeat(2, minmax(0, 1fr)); }
     .fg-site-rail__menu .fg-site-rail__group-label { grid-column: 1 / -1; }
     .fg-site-rail__nav a { min-height: var(--control-lg); }
+    /* The drawer title already shows the label; the heading still names the nav. */
+    .fg-drawer__content .fg-site-rail__label {
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      overflow: hidden;
+      clip-path: inset(50%);
+      white-space: nowrap;
+    }
   }
   @media (max-width: 640px) {
+    .fg-site-docs { padding-inline: var(--space-4); }
+    /* Docs-shell pages keep one header row on phones and repeat these links in their footer. */
+    .fg-site-docs .fg-site-header__links { display: none; }
+    /* Fact links, such as a Source link that stands in for the hidden header link, get a
+     * touch-sized hit area. The negative margin keeps each fact row one line tall, and the
+     * row gap of a list with links makes room for the part of the hit area past the line. */
+    .fg-site-facts:has(a) { row-gap: calc(var(--control-lg) - 1lh); }
+    .fg-site-facts a {
+      display: inline-flex;
+      min-height: var(--control-lg);
+      align-items: center;
+      margin-block: calc((1lh - var(--control-lg)) / 2);
+    }
     .fg-dialog__content.fg-capture-viewer { width: 100%; max-width: none; }
     /* Phones keep the icon; the accessible name still says Full size. */
     .fg-capture[data-enhanced="true"] .fg-tabs__list { margin-inline-end: calc(var(--space-2) + var(--control-lg)); }

package/src/theme.css

@@ -75,6 +75,7 @@
   --color-warning-surface: color-mix(in srgb, var(--color-warning) 13%, var(--color-surface));
   --color-success-surface: color-mix(in srgb, var(--color-success) 12%, var(--color-surface));
   --color-info-surface: color-mix(in srgb, var(--color-info) 12%, var(--color-surface));
+  --radius-inline: 0.25rem;
   --radius-control: 0.375rem;
   --radius-panel: 0.5rem;
   --radius-pill: 999px;
@@ -147,6 +148,7 @@
   --color-ui-warning: var(--color-warning);
   --color-ui-success: var(--color-success);
   --color-ui-info: var(--color-info);
+  --radius-ui-inline: var(--radius-inline);
   --radius-ui-control: var(--radius-control);
   --radius-ui-panel: var(--radius-panel);
 }

package/src/themes/graphite-indigo.css

@@ -41,7 +41,7 @@
   --color-syntax-attribute: var(--color-syntax-number);
   --color-error: #c7372d;
   --color-warning: #86532e;
-  --color-success: #1f8a5b;
+  --color-success: #157249;
   --color-info: #175cd3;
   --color-progress: var(--color-accent);
   --color-error-surface: color-mix(in srgb, var(--color-error) 10%, var(--color-bg));
@@ -64,7 +64,7 @@
 :root.dark {
   color-scheme: dark;
   --color-bg: #151619;
-  --color-surface: #191a1d;
+  --color-surface: #0e0f12;
   --color-surface-raised: #212226;
   --color-surface-muted: #303238;
   --color-text: #f4f5f8;
@@ -106,6 +106,6 @@
   --color-warning-surface: color-mix(in srgb, var(--color-warning) 12%, var(--color-bg));
   --color-success-surface: color-mix(in srgb, var(--color-success) 11%, var(--color-bg));
   --color-info-surface: color-mix(in srgb, var(--color-info) 10%, var(--color-bg));
-  --shadow-dialog: 0 8px 24px rgb(0 0 0 / 45%), 0 0 0 1px var(--color-border);
+  --shadow-dialog: 0 8px 24px rgb(0 0 0 / 45%), 0 0 0 1px var(--color-border-subtle);
   --color-status-text: var(--color-text);
 }