astryx-dracula 0.2.0 → 0.3.0

package/tokens.css

@@ -3,6 +3,24 @@
  * This file is the pre-theme paint fallback. Values follow the Dracula spec UI
  * palette (Background Light #343746 surfaces, Selection #44475A quiet edges,
  * Current Line #6272A4 visible edges). Do not add new hexes here.
+ * Deliberate spec deviations, mirrored in astryx-theme.ts: spec Comment
+ * #6272A4 fails the 4.5:1 WCAG floor for body text, so secondary #9AA1BC,
+ * paragraph #B0B3C4 and base-muted #8288A6 are same-hue lifts, #4C5067
+ * (subdue) is chrome only and never text, and theme.css adds #FFD5CC as the
+ * pale inverted error surface. Do not revert any of them to spec hexes.
+ * Two categorical data hues are deliberately ABSENT from the list below, do not
+ * re-add them: `brown` (was byte-identical to orange, and a categorical series
+ * set is a palette where distinctness IS the contract) and `purple` (purple
+ * means tappable, never data). The purple ban is a MODULE rule —
+ * `shared/chart-hues.ts` is purple-free by construction — so the SEQUENTIAL
+ * `--color-data-purple-1..5` ramp below SURVIVES and is sanctioned; only the
+ * categorical half is revoked. Rationale lives in astryx-theme.ts.
+ * `--color-data-teal-1..5` derives off `--color-data-categorical-teal` (#A4FFFF,
+ * an ANSI bright, not a spec token) rather than spec Cyan #8BE9FD; provenance
+ * fix only, nothing renders the ramp today (HeatScale is shamrock).
+ * `--color-on-dark` is the spec Foreground #F8F8F2, NOT pure white — Dracula has
+ * no #FFFFFF, and the dark media scope repins text/icon-primary onto it. It
+ * must stay a 6-digit hex literal: core's Spinner concatenates an alpha onto it.
  * Fonts: copy `fonts/` to your app's served static dir (Vite: `public/fonts/`). */
 
 @font-face {
@@ -10,7 +28,7 @@
   font-style: normal;
   font-weight: 400;
   font-display: swap;
-  src: url('/fonts/JetBrainsMono-Regular.woff2') format('woff2');
+  src: url('/astryx-dracula/fonts/JetBrainsMono-Regular.woff2') format('woff2');
 }
 
 @font-face {
@@ -18,11 +36,24 @@
   font-style: normal;
   font-weight: 600;
   font-display: swap;
-  src: url('/fonts/JetBrainsMono-SemiBold.woff2') format('woff2');
+  src: url('/astryx-dracula/fonts/JetBrainsMono-SemiBold.woff2') format('woff2');
 }
 
+/* Canvas: the document scroller's track is transparent, so the unpainted
+ * canvas (black in dark color-scheme) shows through as a gutter behind the
+ * thumb in Chrome and Safari. Paint html/body the brand bg so track and
+ * page read as one surface. */
+html,
+body {
+  background-color: #282A36;
+}
+
+/* Full plain-CSS mirror of astryx-theme.ts (frozen dark slots). Edit the theme,
+ * not this file, then re-mirror. Unlayered by design so it beats core layers;
+ * zero !important anywhere. */
 :root {
   color-scheme: dark;
+  background-color: #282A36;
 
   --dracula-bg: #282A36;
   --dracula-current-line: #6272A4;
@@ -53,34 +84,255 @@
   --tile-row: 96px;
   --border-radius: 5px;
   --radius-element: 5px;
+  --radius-inner: 4px;
+  --radius-container: 5px;
+  --radius-page: 5px;
+  --radius-chat: 5px;
   --font-family-mono: 'JetBrains Mono', ui-monospace, monospace;
+  --font-family-body: 'JetBrains Mono', monospace;
+  --font-family-heading: 'JetBrains Mono', monospace;
+  --font-family-code: 'JetBrains Mono', monospace;
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+  --font-size-4xs: 0.375rem;
+  --font-size-3xs: 0.4375rem;
+  --font-size-2xs: 0.5rem;
+  --font-size-xs: 0.625rem;
+  --font-size-sm: 0.75rem;
+  --font-size-base: 14px;
+  --font-size-lg: 1.0625rem;
+  --font-size-xl: 1.25rem;
+  --font-size-2xl: 1.5rem;
+  --font-size-3xl: 1.8125rem;
+  --font-size-4xl: 2.1875rem;
+  --font-size-5xl: 2.625rem;
+  --font-size-h1: 24px;
+  --font-size-h2: 20px;
+  --font-size-h3: 16px;
+  --font-size-h4: 14px;
+  --font-size-h5: 13px;
+  --font-size-h6: 12px;
+  --text-heading-1-size: var(--font-size-2xl);
+  --text-heading-1-weight: var(--font-weight-normal);
+  --text-heading-1-leading: 1.3333;
+  --text-heading-2-size: var(--font-size-xl);
+  --text-heading-2-weight: var(--font-weight-normal);
+  --text-heading-2-leading: 1.4;
+  --text-heading-3-size: var(--font-size-lg);
+  --text-heading-3-weight: var(--font-weight-normal);
+  --text-heading-3-leading: 1.4118;
+  --text-heading-4-size: var(--font-size-base);
+  --text-heading-4-weight: var(--font-weight-normal);
+  --text-heading-4-leading: 1.4286;
+  --text-heading-5-size: var(--font-size-sm);
+  --text-heading-5-weight: var(--font-weight-normal);
+  --text-heading-5-leading: 1.6667;
+  --text-heading-6-size: var(--font-size-xs);
+  --text-heading-6-weight: var(--font-weight-normal);
+  --text-heading-6-leading: 1.6;
+  --text-body-size: var(--font-size-base);
+  --text-body-weight: var(--font-weight-normal);
+  --text-body-leading: 1.4286;
+  --text-large-size: var(--font-size-lg);
+  --text-large-weight: var(--font-weight-semibold);
+  --text-large-leading: 1.4118;
+  --text-label-size: var(--font-size-base);
+  --text-label-weight: var(--font-weight-semibold);
+  --text-label-leading: 1.4286;
+  --text-code-size: var(--font-size-base);
+  --text-code-weight: var(--font-weight-normal);
+  --text-code-leading: 1.4286;
+  --text-supporting-size: var(--font-size-sm);
+  --text-supporting-weight: var(--font-weight-normal);
+  --text-supporting-leading: 1.6667;
+  --text-display-1-size: var(--font-size-5xl);
+  --text-display-1-weight: var(--font-weight-normal);
+  --text-display-1-leading: 1.2381;
+  --text-display-2-size: var(--font-size-4xl);
+  --text-display-2-weight: var(--font-weight-normal);
+  --text-display-2-leading: 1.2571;
+  --text-display-3-size: var(--font-size-3xl);
+  --text-display-3-weight: var(--font-weight-normal);
+  --text-display-3-leading: 1.3793;
+  --duration-fast-min: 130ms;
+  --duration-fast: 175ms;
+  --duration-fast-max: 235ms;
+  --duration-medium-min: 310ms;
+  --duration-medium: 410ms;
+  --duration-medium-max: 545ms;
+  --duration-slow-min: 730ms;
+  --duration-slow: 975ms;
+  --duration-slow-max: 1300ms;
+  --ease-standard: cubic-bezier(0.24, 1, 0.4, 1);
+  --shadow-low: 0 2px 4px #191A210D, 0 4px 8px #191A211A;
+  --shadow-med: 0 2px 4px #191A210D, 0 4px 12px #191A211A;
+  --shadow-high: 0 4px 6px #191A211A, 0 12px 24px #191A2126;
+  --shadow-inset-hover: inset 0px 0px 0px 2px #6272A430;
+  --shadow-inset-selected: inset 0px 0px 0px 2px #BD93F930;
+  --shadow-inset-success: inset 0px 0px 0px 2px #50FA7B30;
+  --shadow-inset-warning: inset 0px 0px 0px 2px #F1FA8C30;
+  --shadow-inset-error: inset 0px 0px 0px 2px #FF555530;
 
-  --color-background: #282A36;
+  --color-background-body: #282A36;
+  --color-background: var(--color-background-body);
+  --color-background-surface: #343746;
+  --color-background-card: #343746;
+  --color-background-popover: #424450;
+  --color-background-muted: #44475A;
+  --color-background-inverted: #F8F8F2;
+  --color-background-error-inverted: #FFD5CC;
+  --color-overlay: #191A21CC;
+  --color-overlay-hover: #0000001F;
+  --color-overlay-pressed: #00000033;
+  --color-border: #6272A4;
+  --color-border-emphasized: #9AA1BC;
+  --color-neutral: #F8F8F21A;
+  --color-tint-hover: #FFFFFF;
+  --color-on-dark: #F8F8F2;
+  --color-on-light: #000000;
+  --color-shadow: #21222C;
+  --color-track: #6272A4;
+  --color-skeleton: #6272A4;
   --color-accent: #BD93F9;
   --color-success: #50FA7B;
   --color-error: #FF5555;
   --color-warning: #F1FA8C;
   --color-info: #8BE9FD;
+  --color-accent-muted: var(--color-background-purple);
+  --color-success-muted: var(--color-background-green);
+  --color-warning-muted: var(--color-background-yellow);
+  --color-error-muted: var(--color-background-red);
+  --color-info-muted: var(--color-background-cyan);
   --color-text-primary: #F8F8F2;
   --color-text-secondary: #9AA1BC;
   --color-text-disabled: #6272A4;
   --color-text-accent: #BD93F9;
-  --color-border: #6272A4;
+  --color-text-highlight: #F8F8F2;
+  --color-text-paragraph: #B0B3C4;
+  --color-text-base: #9AA1BC;
+  --color-text-base-muted: #8288A6;
+  --color-text-subdue: #4C5067;
+  --color-icon-primary: #F8F8F2;
+  --color-icon-secondary: #9AA1BC;
+  --color-icon-disabled: #6272A4;
+  --color-icon-accent: #BD93F9;
+  --color-on-accent: #21222C;
+  --color-on-success: #21222C;
+  --color-on-warning: #21222C;
+  --color-on-error: #21222C;
+  --color-on-info: #21222C;
+  --color-functional-red: #DE5735;
+  --color-functional-orange: #A39514;
+  --color-functional-green: #089108;
+  --color-functional-cyan: #0081D6;
+  --color-functional-purple: #815CD6;
+  --color-background-blue: #6272A41A;
+  --color-border-blue: #6272A44D;
+  --color-icon-blue: #6272A4;
+  --color-text-blue: #6272A4;
+  --color-background-cyan: #8BE9FD1A;
+  --color-border-cyan: #8BE9FD4D;
+  --color-icon-cyan: #8BE9FD;
+  --color-text-cyan: #8BE9FD;
+  --color-background-gray: #9AA1BC1A;
+  --color-border-gray: #9AA1BC4D;
+  --color-icon-gray: #9AA1BC;
+  --color-text-gray: #9AA1BC;
+  --color-background-green: #50FA7B1A;
+  --color-border-green: #50FA7B4D;
+  --color-icon-green: #50FA7B;
+  --color-text-green: #50FA7B;
+  --color-background-orange: #FFB86C1A;
+  --color-border-orange: #FFB86C4D;
+  --color-icon-orange: #FFB86C;
+  --color-text-orange: #FFB86C;
+  --color-background-pink: #FF79C61A;
+  --color-border-pink: #FF79C64D;
+  --color-icon-pink: #FF79C6;
+  --color-text-pink: #FF79C6;
+  --color-background-purple: #BD93F91A;
+  --color-border-purple: #BD93F94D;
+  --color-icon-purple: #BD93F9;
+  --color-text-purple: #BD93F9;
+  --color-background-red: #FF55551A;
+  --color-border-red: #FF55554D;
+  --color-icon-red: #FF5555;
+  --color-text-red: #FF5555;
+  --color-background-teal: #A4FFFF1A;
+  --color-border-teal: #A4FFFF4D;
+  --color-icon-teal: #A4FFFF;
+  --color-text-teal: #A4FFFF;
+  --color-background-yellow: #F1FA8C1A;
+  --color-border-yellow: #F1FA8C4D;
+  --color-icon-yellow: #F1FA8C;
+  --color-text-yellow: #F1FA8C;
+  --color-data-categorical-blue: #6272A4;
+  --color-data-categorical-orange: #FFB86C;
+  --color-data-categorical-green: #50FA7B;
+  --color-data-categorical-pink: #FF79C6;
+  --color-data-categorical-cyan: #8BE9FD;
+  --color-data-categorical-red: #FF5555;
+  --color-data-categorical-teal: #A4FFFF;
+  --color-data-categorical-indigo: #D6ACFF;
+  --color-data-neutral: #8C939B;
+  --color-data-purple-5: hsl(264.71 89.47% 28%);
+  --color-data-purple-4: hsl(264.71 89.47% 44%);
+  --color-data-purple-3: hsl(264.71 89.47% 60%);
+  --color-data-purple-2: hsl(264.71 89.47% 74%);
+  --color-data-purple-1: hsl(264.71 89.47% 88%);
+  --color-data-pink-5: hsl(325.52 100% 28%);
+  --color-data-pink-4: hsl(325.52 100% 44%);
+  --color-data-pink-3: hsl(325.52 100% 60%);
+  --color-data-pink-2: hsl(325.52 100% 74%);
+  --color-data-pink-1: hsl(325.52 100% 88%);
+  --color-data-red-5: hsl(0 100% 28%);
+  --color-data-red-4: hsl(0 100% 44%);
+  --color-data-red-3: hsl(0 100% 60%);
+  --color-data-red-2: hsl(0 100% 74%);
+  --color-data-red-1: hsl(0 100% 88%);
+  --color-data-orange-5: hsl(31.02 100% 28%);
+  --color-data-orange-4: hsl(31.02 100% 44%);
+  --color-data-orange-3: hsl(31.02 100% 60%);
+  --color-data-orange-2: hsl(31.02 100% 74%);
+  --color-data-orange-1: hsl(31.02 100% 88%);
+  --color-data-yellow-5: hsl(64.91 91.67% 28%);
+  --color-data-yellow-4: hsl(64.91 91.67% 44%);
+  --color-data-yellow-3: hsl(64.91 91.67% 60%);
+  --color-data-yellow-2: hsl(64.91 91.67% 74%);
+  --color-data-yellow-1: hsl(64.91 91.67% 88%);
+  --color-data-teal-5: hsl(180 100% 28%);
+  --color-data-teal-4: hsl(180 100% 44%);
+  --color-data-teal-3: hsl(180 100% 60%);
+  --color-data-teal-2: hsl(180 100% 74%);
+  --color-data-teal-1: hsl(180 100% 88%);
+  --color-data-blue-5: hsl(225.45 26.61% 28%);
+  --color-data-blue-4: hsl(225.45 26.61% 44%);
+  --color-data-blue-3: hsl(225.45 26.61% 60%);
+  --color-data-blue-2: hsl(225.45 26.61% 74%);
+  --color-data-blue-1: hsl(225.45 26.61% 88%);
+  --color-data-shamrock-5: hsl(135.18 94.44% 28%);
+  --color-data-shamrock-4: hsl(135.18 94.44% 44%);
+  --color-data-shamrock-3: hsl(135.18 94.44% 60%);
+  --color-data-shamrock-2: hsl(135.18 94.44% 74%);
+  --color-data-shamrock-1: hsl(135.18 94.44% 88%);
+  --color-data-gray-5: hsl(231.43 14.89% 28%);
+  --color-data-gray-4: hsl(231.43 14.89% 44%);
+  --color-data-gray-3: hsl(231.43 14.89% 60%);
+  --color-data-gray-2: hsl(231.43 14.89% 74%);
+  --color-data-gray-1: hsl(231.43 14.89% 88%);
   --color-widget-background: #343746;
   --color-widget-content-border: #6272A4;
   --color-widget-background-highlight: #44475A;
   --color-separator: #44475A;
   --color-popover-background: #424450;
   --color-popover-border: #6272A4;
-  --color-graph-gridlines: #44475A;
   --color-progress-border: #44475A;
   --color-progress-value: #6272A4;
+  --color-vertical-progress-value: #6272A4;
+  --color-graph-gridlines: #44475A;
   --color-widget-shadow: #21222C;
-  --color-text-highlight: #F8F8F2;
-  --color-text-paragraph: #B0B3C4;
-  --color-text-base: #9AA1BC;
-  --color-text-base-muted: #8288A6;
-  --color-text-subdue: #4C5067;
   --color-current-line: #6272A4;
   --color-selection: #44475A;
   --color-primary: #BD93F9;
@@ -88,34 +340,177 @@
   --color-negative: #FF5555;
   --color-tag-orange: #FFB86C;
   --color-tag-pink: #FF79C6;
+  --color-tag-cyan: #8BE9FD;
+  --color-tag-yellow: #F1FA8C;
+  --color-tag-green: #50FA7B;
+  --color-tag-purple: #BD93F9;
+  /* The token was named `tag-blue` and held purple. Dracula has no blue; the
+   * closest is Comment/Comment-dim, and Purple is what the rest of the kit
+   * already uses for a fourth accent -- so the VALUE was right and the NAME
+   * was the lie. Renamed, not repinned: a `blue` tag that paints purple is
+   * wrong in a way no contrast number catches, and a future author adding a
+   * real blue tag would have found the slot occupied. Verify no consumer
+   * returned with `grep -rn "tag-blue"` before shipping a rename. */
 }
 
-/* Dracula scrollbars: Selection thumb on transparent track, Current Line on
- * hover. Firefox uses the two properties; Chromium uses the pseudo-elements. */
-:root {
-  scrollbar-width: thin;
-  scrollbar-color: var(--dracula-selection) transparent;
+/* Dracula scrollbars. The spec defines no scrollbar token, so these follow its
+ * UI Design Guidelines instead: the track is transparent, so the bar reads as
+ * a thumb only and picks up whatever tier it sits on — the document scroller
+ * shows the html/body paint, surface and card scrollers show their own
+ * surface instead of a page-background gutter inside the card. The
+ * resting thumb uses Current Line, which the spec designates for
+ * subtle borders and separators, and the hovered thumb promotes to Purple, the
+ * brand accent for anything interactive. Selection (#44475A) was the resting
+ * thumb before, at 1.5:1 against the background, which made the scrollbar
+ * effectively invisible.
+ *
+ * Engine split (verified 2026-09: Safari ignores `scrollbar-color` when
+ * `scrollbar-width: thin` is set, and `scrollbar-width` makes WebKit ignore
+ * the `::-webkit-scrollbar-*` rules — the two systems are mutually exclusive
+ * in Safari). So: no `scrollbar-width` anywhere (Safari falls back to overlay
+ * scrollbars that never take space; Chrome/Firefox size via the rules below),
+ * Firefox-only `scrollbar-color` guarded by `@supports`, WebKit-only sizing
+ * and hover, also guarded so Firefox never sees a pseudo-element.
+ * Safari overlay scrollbars ignore thumb width/border (system-drawn while
+ * scrolling); resting color still applies when the bar is persistent.
+ *
+ * Environment note: the shared headless browser paints overlay scrollbars
+ * (scrollbarWidth 0 even with content overflowing), so themed scrollbar
+ * rules cannot be verified there. Check them in a real Chrome against
+ * /templates and /bento: resting thumb Current Line, hover Purple. */
+@supports (scrollbar-color: auto) and (not (-webkit-hyphens: none)) {
+  :root {
+    scrollbar-color: var(--dracula-current-line) transparent;
+  }
+}
+
+@supports selector(::-webkit-scrollbar) {
+  *::-webkit-scrollbar {
+    width: 10px;
+    height: 10px;
+    background: transparent;
+  }
+
+  *::-webkit-scrollbar-track,
+  *::-webkit-scrollbar-corner {
+    background: transparent;
+  }
+
+  *::-webkit-scrollbar-thumb {
+    background-color: var(--dracula-current-line);
+    border-radius: 5px;
+    border: 2px solid transparent;
+    background-clip: content-box;
+  }
+
+  *::-webkit-scrollbar-thumb:hover {
+    background-color: var(--dracula-purple);
+    border: 2px solid transparent;
+    background-clip: content-box;
+  }
 }
 
-*::-webkit-scrollbar {
-  width: 10px;
-  height: 10px;
+/* A resizable SideNav reports exactly 1px of horizontal overflow: the resize
+ * handle renders 1px wider than its own box, and the side-nav panel scrolls
+ * both axes, so a permanent horizontal scrollbar paints under the rail even
+ * though nothing overflows visually. Clip the offending pixel on the handle
+ * itself rather than on the panel: a collapsed rail renders its child popovers
+ * as descendants of that panel, and they only escape the clip because their
+ * root happens to be position:fixed. Clipping the panel would break them the
+ * day an ancestor gains a transform. The handle contains nothing but its pill,
+ * which sits inside its box, so clipping it costs nothing. Needed until the
+ * resize handle stops reporting the extra pixel. Re-verified against
+ * @astryxdesign/core 0.3.0: without the clip the hit area's half-pixel inline
+ * shift leaves content at 300.5px in a 300px rail, and the LayoutPanel
+ * (overflow:auto on both axes) reports scrollWidth 301 > 300 — the permanent
+ * bar is back. Keep. */
+.astryx-app-shell-sidenav .astryx-resize-handle {
+  overflow: hidden;
 }
 
-*::-webkit-scrollbar-track,
-*::-webkit-scrollbar-corner {
-  background: transparent;
+/* Astryx leaves the resize handle's drag surface translated -50% along the
+ * block axis without ever positioning it at top:50%, so it spans only the TOP
+ * HALF of the rail: the pointer reads col-resize and dragging works above the
+ * midpoint, and nothing at all happens below it, even though the pill is drawn
+ * straddling that boundary. The pill sibling carries a correct top:50%, which
+ * is exactly what the drag surface is missing. Re-verified against
+ * @astryxdesign/core 0.3.0: hitAreaHorizontal is still top:0/bottom:0 while
+ * hitAreaOffsetX translates Y by -50%, so without this the drag surface spans
+ * [-50%,+50%] of the rail and the bottom half is dead (elementFromPoint hits
+ * the handle, which has no pointer handler). Upstream workaround; drop it if
+ * the component starts positioning its own hit area. */
+.astryx-app-shell-sidenav
+  .astryx-resize-handle
+  > :not(.astryx-resize-handle-pill) {
+  top: 50%;
+  bottom: auto;
+  height: 100%;
 }
 
-*::-webkit-scrollbar-thumb {
-  background: var(--dracula-selection);
-  border-radius: 5px;
-  border: 2px solid transparent;
-  background-clip: content-box;
+/* Everything below this line is UNLAYERED on purpose, and that is load-bearing,
+ * not a style choice. Unlayered author rules beat every core LAYER regardless of
+ * specificity — verified in Chromium against the declared order
+ * (`@layer reset, astryx-base, astryx-theme`, vite.config.ts) where an
+ * unlayered (0,1,0) rule outranked core's (0,4,0) `:not(#):not(#):not(#)` rule
+ * inside `@layer astryx-base`. scripts/check.ts asserts `@layer` count is 0 in
+ * this file, so the next agent cannot "tidy" these rules into a layer and
+ * silently break all of them at once.
+ *
+ * BOUNDARY, because the sentence above is true of layers and stops being true
+ * one step out: unlayered does NOT beat an INLINE style. But that is
+ * PER-PROPERTY, not per-element, and the difference decides real work:
+ *   - Core never assigns `box-shadow` inline — 0 occurrences across core. A
+ *     stylesheet RING therefore paints normally, over whatever background core
+ *     set. `--shadow-inset-selected` is reachable with no !important, no core
+ *     change and no version bump.
+ *   - Core DOES assign `el.style.backgroundColor` on selected table rows
+ *     (dist/Table/plugins/selection/useTableSelection.js:79). So a kit WASH on
+ *     that state is unreachable: the exits are `!important` (banned by the gate
+ *     below) or a core change (deferred by the 0.3.0 version ruling).
+ * Stated here so the next agent does not discover it the hard way, and so nobody
+ * reads the inline-style note as a blanket blocker and avoids box-shadow too.
+
+/* Reduced motion. Core gates its per-component motion on
+ * `@media (prefers-reduced-motion: reduce)`, but each rule is inside
+ * `@layer astryx-base`, so an unlayered blanket here wins on layer order alone —
+ * no !important, no specificity arms race. Deliberately narrow: it touches only
+ * duration and iteration count, and NEVER `scrollbar-width`, because core's
+ * carousel relies on a layered `scrollbar-width: none` to hide its bar and a
+ * universal rule here would un-hide it (the one scrollbar-width in the stack). */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms;
+    animation-iteration-count: 1;
+    transition-duration: 0.01ms;
+  }
+
+  html {
+    scroll-behavior: auto;
+  }
 }
 
-*::-webkit-scrollbar-thumb:hover {
-  background: var(--dracula-current-line);
-  border: 2px solid transparent;
-  background-clip: content-box;
+/* Sticky-header focus and in-page anchor offset. AppShell in `auto` mode pins
+ * the header with `position: sticky` (dist/AppShell/AppShell.js:398, 630-632),
+ * so anything scrolled to `block: 'start'` lands underneath it — the focus ring
+ * renders perfectly and is simply off-screen. Two paths hit this: keyboard focus
+ * on a long `height="auto"` documentation page, and the four in-page outline
+ * navigations that call `scrollIntoView({ block: 'start' })`
+ * (shared/chaptered-doc.tsx, documentation-design.tsx, documentation-technical.tsx,
+ * product-gallery.tsx).
+ *
+ * Declared on the TARGET, not the scroller, and that is the deliberate choice.
+ * `scroll-padding-top` on `:root` cannot work here: a document scroller's
+ * scroll-padding must be declared on the root, but core measures the header and
+ * publishes it as `--appshell-header-height` on the SHELL element
+ * (AppShell.js:276-291, via ResizeObserver), and a custom property set on a
+ * descendant never reaches the root. A static number at `:root` would be exactly
+ * the unmeasured guess this repo refuses to ship. `scroll-margin-block` on the
+ * target resolves at a DESCENDANT, so it reads core's real measured height —
+ * correct at every viewport width and in both AppShell modes — with
+ * `--spacing-8` only as the fallback for pages that have no sticky header at all. */
+:where(:focus-visible, h1, h2, h3, h4, [id]) {
+  scroll-margin-block: var(--appshell-header-height, var(--spacing-8))
+    var(--space-viewport);
 }