anentrypoint-design 0.0.401 → 0.0.403

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anentrypoint-design",
-  "version": "0.0.401",
+  "version": "0.0.403",
   "description": "247420 design system SDK — webjsx + modified ripple-ui, single-file ESM bundle for reproducible use of the AnEntrypoint design.",
   "type": "module",
   "main": "./dist/247420.js",
@@ -116,7 +116,8 @@
     "a11y": "node scripts/a11y-audit.mjs",
     "a11y:baseline": "node scripts/a11y-audit.mjs --write-baseline",
     "visual": "node scripts/visual-baseline.mjs check",
-    "visual:update": "node scripts/visual-baseline.mjs update"
+    "visual:update": "node scripts/visual-baseline.mjs update",
+    "lint:dead-controls": "node scripts/lint-dead-controls.mjs"
   },
   "repository": {
     "type": "git",

package/scripts/lint-css.mjs

@@ -27,6 +27,7 @@ import { lintInlineStylesOrThrow } from './lint-inline-styles.mjs';
 import { lintDuplicateSelectorsOrThrow } from './lint-duplicate-selectors.mjs';
 import { lintSwallowCommentsOrThrow } from './lint-swallow-comments.mjs';
 import { lintInlineCssOrThrow } from './lint-inline-css.mjs';
+import { lintDeadControlsOrThrow } from './lint-dead-controls.mjs';
 
 // Each entry: a human label for the report, and the check function to run.
 // EVERY check here throws on violation and is counted in the pass/fail tally.
@@ -60,6 +61,12 @@ const CHECKS = [
     ['inline-styles', lintInlineStylesOrThrow],
     ['duplicate-selectors', lintDuplicateSelectorsOrThrow],
     ['swallow-comments', lintSwallowCommentsOrThrow],
+    // A rendered control that cannot act — an empty handler body, or an
+    // href="#" that goes nowhere. Both shipped in quantity (6 no-op handlers
+    // across three kits, 24 placeholder links across blog and docs) precisely
+    // because nothing checked: the affordance renders either way, so the defect
+    // is invisible until someone clicks.
+    ['dead-controls', lintDeadControlsOrThrow],
 ];
 
 // Runs every rule module's check, prints one aggregated report, and returns

package/src/community-app.js

@@ -202,6 +202,10 @@ export function mountCommunityApp(root, adapter = {}) {
             : chatView(s);
         const showVoiceBanner = s.voiceConnected && s.voiceChannelName && !(inVoiceChannel && s.voiceChannelName === ch.name);
         return h('div', { class: 'ca-app' },
+            // Same skip-link contract AppShell() provides. This app builds its
+            // own chrome, so without this a keyboard user had to tab through
+            // the whole topbar nav and channel rail to reach the messages.
+            h('a', { href: '#app-main', class: 'skip-link' }, 'skip to main content'),
             // top bar (sole app chrome above the chat-head)
             h('header', { class: 'app-topbar' },
                 h('span', { class: 'brand' }, 'zellous', h('span', { class: 'slash' }, ' / '), h('span', {}, ch.name || 'general')),
@@ -217,7 +221,15 @@ export function mountCommunityApp(root, adapter = {}) {
             Banner({ tone: 'success', visible: !!showVoiceBanner, message: showVoiceBanner ? ('In voice: ' + (s.voiceChannelName || '') + ' — click to return') : '', actionLabel: 'Leave', onAction: (e) => { if (e && e.stopPropagation) e.stopPropagation(); A.leaveVoice && A.leaveVoice(); }, onClick: () => A.returnToVoice && A.returnToVoice() }),
             h('div', { class: 'app-body' + (s.mobileMenuOpen ? ' ca-rail-open' : '') },
                 h('aside', { class: 'app-side ca-rail' + (s.mobileMenuOpen ? ' open' : '') }, railView(s)),
-                h('main', { class: 'app-main', onclick: () => { if (s.mobileMenuOpen && A.closeMobileMenu) A.closeMobileMenu(); } },
+                // id + tabindex match AppShell()'s contract so the skip link
+                // above actually lands somewhere; this app builds its own shell
+                // and so inherited neither.
+                h('main', { class: 'app-main', id: 'app-main', tabindex: '0', onclick: () => { if (s.mobileMenuOpen && A.closeMobileMenu) A.closeMobileMenu(); } },
+                    // The channel name is the page title, but it lived only in
+                    // the topbar brand span, leaving the document with no
+                    // heading at all. sr-only because the topbar and chat-head
+                    // already show it — this adds the semantics, not a visual.
+                    h('h1', { class: 'sr-only' }, ch.name || 'general'),
                     !inVoiceChannel && s.voiceConnected ? VoiceStrip({ channelName: s.voiceChannelName, status: s.voiceConnectionState || 'connected', muted: !!s.micMuted, deafened: !!s.voiceDeafened, onMute: () => A.toggleMic && A.toggleMic(), onDeafen: () => A.toggleDeafen && A.toggleDeafen(), onLeave: () => A.leaveVoice && A.leaveVoice(), open: true }) : null,
                     UserPanel({ name: (s.currentUser && (s.currentUser.displayName || s.currentUser.username || s.currentUser.name)) || 'You', tag: s.currentUser && s.currentUser.tag, color: avatarColor(s.userId), muted: !!s.micMuted, deafened: !!s.voiceDeafened, onMute: () => A.toggleMic && A.toggleMic(), onDeafen: () => A.toggleDeafen && A.toggleDeafen(), onSettings: () => A.openSettings && A.openSettings() }),
                     bodyMain,

package/src/components/community/chrome.js

@@ -10,7 +10,14 @@ const h = webjsx.createElement;
 export function ChatHeader({ icon = '#', name, topic, toolbar = [] } = {}) {
     return h('div', { class: 'cm-chat-header' },
         h('span', { class: 'cm-chat-header-icon' }, icon),
-        h('span', { class: 'cm-chat-header-name' }, name),
+        // h1, not span: this is already the visible title of the content column
+        // — the channel you are reading. It carried no heading semantics, so
+        // both community kits rendered a document with zero headings. An h1
+        // here reuses the element that was always the page title rather than
+        // adding a second, hidden one. .cm-chat-header-name pins weight/size/
+        // colour and now also zeroes the UA h1 margin, so this is a semantic
+        // change with no visual change.
+        h('h1', { class: 'cm-chat-header-name' }, name),
         topic ? h('span', { class: 'cm-chat-header-topic' }, topic) : null,
         h('div', { class: 'cm-chat-header-toolbar' }, ...toolbar)
     );

package/src/components/community/shell.js

@@ -8,9 +8,18 @@ const h = webjsx.createElement;
 
 export function CommunityShell({ serverRailProps, sidebarProps, children, memberListProps, voiceStripProps } = {}) {
     return h('div', { class: 'cm-shell' },
+        // Same skip-link + <main id="app-main"> contract AppShell() provides.
+        // This shell is the AppShell alternative for the community layout, so
+        // the kits built on it were the only ones in the repo with no main
+        // landmark and no way for a keyboard user to get past the server rail
+        // and channel sidebar — two full columns of links before any content.
+        h('a', { href: '#app-main', class: 'skip-link' }, 'skip to main content'),
         serverRailProps ? ServerRail(serverRailProps) : null,
         sidebarProps ? ChannelSidebar(sidebarProps) : null,
-        h('div', { class: 'cm-main' }, ...(Array.isArray(children) ? children : [children])),
+        // <main>, not <div>: this is the content column. tabindex=0 for the
+        // same reason AppShell uses it — the column scrolls, so it must be
+        // reachable by Tab for a keyboard-only user to scroll it at all.
+        h('main', { class: 'cm-main', id: 'app-main', tabindex: '0' }, ...(Array.isArray(children) ? children : [children])),
         memberListProps ? MemberList(memberListProps) : null,
         voiceStripProps ? VoiceStrip(voiceStripProps) : null
     );

package/src/components/content/fields.js

@@ -100,14 +100,22 @@ export function Select({ label, value = '', options = [], onChange, name, key, p
         const lab = typeof o === 'string' ? o : (o.label != null ? o.label : (o.id || o.value));
         opts.push(h('option', { key: 'o-' + id, value: id, selected: id === value }, lab));
     }
+    // When this select is returned bare (the no-label/no-hint/md branch below),
+    // it is the node the caller keys, so it must carry the caller's key. The
+    // internal 'i' only has to be unique among THIS component's own children,
+    // which is why the wrapped branches can keep it. Previously 'i' was
+    // hardcoded here and the bare branch dropped `key` on the floor, so two
+    // sibling label-less Selects both keyed as 'i' and webjsx's keyed diff
+    // collapsed them into one on the next re-render.
+    const bare = label == null && hint == null && size === 'md';
     const select = h('select', {
-        key: 'i', name, class: 'ds-select',
+        key: bare && key != null ? key : 'i', name, class: 'ds-select',
         // Guarantee an accessible name even when rendered without a visible label.
         'aria-label': ariaLabel || (label == null ? (title || placeholder || name) : null),
         title,
         onchange: onChange ? (e) => onChange(e.target.value, e) : null
     }, ...opts);
-    if (label == null && hint == null && size === 'md') return select;
+    if (bare) return select;
     if (label == null && hint == null) return h('label', { key, class: 'ds-field' + sizeCls }, select);
     return h('label', { key, class: 'ds-field' + sizeCls },
         label != null ? h('span', { key: 'l', class: 'ds-field-label' }, label) : null,

package/src/components/content/hero.js

@@ -129,7 +129,7 @@ export function PageHeader({ title, lede, eyebrow, right, compact, dense, id })
     // of a display H1 over a paragraph. App surfaces (files, dashboards,
     // settings) should not spend 150px of fold on an intro.
     if (dense) {
-        return h('section', { class: 'ds-section ds-section-compact ds-page-header-dense', id: id || null },
+        return h('section', { class: 'ds-section ds-section-compact ds-page-header-dense', ...(id ? { id } : {}) },
             h('div', { class: 'ds-page-header-dense-row' },
                 ...[
                     title != null ? h('h1', { key: 'dh' }, title) : null,
@@ -137,7 +137,7 @@ export function PageHeader({ title, lede, eyebrow, right, compact, dense, id })
                     right != null ? h('div', { key: 'dr', class: 'ds-page-header-right' }, ...(Array.isArray(right) ? right : [right])) : null,
                 ].filter(Boolean)));
     }
-    return h('section', { class: 'ds-section' + (compact ? ' ds-section-compact' : ''), id: id || null },
+    return h('section', { class: 'ds-section' + (compact ? ' ds-section-compact' : ''), ...(id ? { id } : {}) },
         eyebrow ? h('span', { class: 'eyebrow' }, eyebrow) : null,
         title != null ? h('h1', {}, title) : null,
         lede != null ? h('p', { class: 'lede' }, lede) : null,

package/src/components/content/panel.js

@@ -9,7 +9,7 @@ const h = webjsx.createElement;
 
 export function Panel({ title, count, right, style = '', class: className = '', children, kind, id }) {
     const cls = 'panel' + (kind ? ' panel-' + kind : '') + (className ? ' ' + className : '');
-    return h('div', { class: cls, style, id: id || null },
+    return h('div', { class: cls, style, ...(id ? { id } : {}) },
         title != null ? h('div', { class: 'panel-head' },
             h('span', {}, title),
             right != null ? right : (count != null ? h('span', {}, String(count)) : null)
@@ -48,7 +48,7 @@ export function PanelFromItems({ heading, items = [], keyPrefix = 'i', count, st
 }
 
 export function Section({ title, eyebrow, children, id }) {
-    return h('section', { class: 'ds-section', id: id || null },
+    return h('section', { class: 'ds-section', ...(id ? { id } : {}) },
         eyebrow ? h('span', { class: 'eyebrow' }, eyebrow) : null,
         title ? h('h3', {}, title) : null,
         ...(Array.isArray(children) ? children : [children])

package/src/components/shell/app-shell.js

@@ -93,16 +93,34 @@ export function Side({ sections = [] } = {}) {
         return h('div', { class: 'app-side-group', key: sec.group, role: 'group', 'aria-labelledby': groupId },
             h('h2', { class: 'group', id: groupId }, sec.group),
             ...sec.items.map((item, i) => {
-                const { glyph, label, href = '#', active, count, color, onClick } = item;
+                const { glyph, label, href, active, count, color, onClick } = item;
                 const countLabel = (count != null && count !== 0 && count !== '0') ? ` (${count})` : '';
+                // An item with neither href nor onClick is not a control, and
+                // must not look like one. href used to default to '#', so a
+                // forgotten destination silently produced a pointer-cursor,
+                // tab-stoppable anchor that navigated nowhere — which is why
+                // dead sidebar rows kept reappearing in new kits: the dead
+                // affordance was the DEFAULT. Such an item keeps the <a> (every
+                // .app-side row rule is anchor-scoped, so a different element
+                // would lose the whole grid layout) but drops href entirely: an
+                // anchor with no href is not a link, takes no tab stop, and is
+                // styled inert by .app-side a:not([href]) in topbar.css.
+                // An onClick with no href IS a real control and still gets
+                // href='#' so it stays keyboard-activatable.
+                const isControl = href != null || onClick != null;
+                // href is spread in only when this row is a control. Setting it
+                // to null instead would NOT omit the attribute — webjsx passes a
+                // null straight to updatePropOrAttr, which stringifies it, and
+                // the row renders href="null": still a link, still tab-stopped,
+                // still pointer-cursored. The key has to be absent.
                 return h('a', {
                     key: sec.group + i,
-                    href,
+                    ...(isControl ? { href: href != null ? href : '#' } : {}),
                     class: active ? 'active' : '',
                     'aria-current': active ? 'page' : null,
                     'aria-label': label + countLabel,
                     onclick: onClick,
-                    onkeydown: onSideLinkKeyDown
+                    onkeydown: isControl ? onSideLinkKeyDown : null
                 },
                     glyph != null ? Glyph({ children: glyph, color }) : h('span', { class: 'glyph', 'aria-hidden': 'true' }),
                     h('span', {}, label),

package/src/components/theme-toggle.js

@@ -19,52 +19,90 @@ const MODES = [
     ['ink',   'dark'],
 ];
 
-// Track instances so an OS-theme change while in 'auto' re-renders the
-// glyph in the compact variant (the segmented variant doesn't need it).
-const refresh = new Set();
-let _bound = false;
-function bindOnce() {
-    if (_bound) return;
-    _bound = true;
-    onThemeChange(() => { for (const cb of refresh) cb(); });
+// Both variants render from `getTheme()` at the moment their vnode is built,
+// but nothing re-renders this control when the theme changes: a host kit's view
+// is not subscribed to the theme, and applyTheme() only touches <html> and the
+// theme listeners. So each instance repaints itself from the live theme through
+// a ref — once on mount, then on every theme change. `el._dsThemeBound` makes
+// that idempotent, since a ref callback runs again on each re-render of the
+// host. (This replaces a `refresh` Set that nothing ever added to, so the
+// onThemeChange subscription it fed always iterated an empty set.)
+function bindThemePaint(el, paint) {
+    if (!el || el._dsThemeBound) return;
+    el._dsThemeBound = true;
+    paint();
+    onThemeChange(paint);
 }
 
 export function ThemeToggle({ compact = false, onChange } = {}) {
-    bindOnce();
     const current = getTheme();
 
     if (compact) {
         // Plain words only - 'ink'/'paper' are internal theme codenames a user
         // never chose; the resolved scheme rides in the title, not the label.
-        const resolvedWord = resolvedTheme() === 'ink' ? 'dark' : 'light';
-        const word = current === 'auto' ? 'auto' : (current === 'ink' ? 'dark' : 'light');
-        const label = 'theme: ' + word;
+        const wordFor = (t) => (t === 'auto' ? 'auto' : (t === 'ink' ? 'dark' : 'light'));
+        const labelFor = (t) => 'theme: ' + wordFor(t);
+        const titleFor = (t) => labelFor(t)
+            + (t === 'auto' ? ' (currently ' + (resolvedTheme() === 'ink' ? 'dark' : 'light') + ')' : '')
+            + ' — click to cycle';
         return h('button', {
             class: 'btn ds-theme-toggle',
             type: 'button',
-            'aria-label': label,
-            title: label + (current === 'auto' ? ' (currently ' + resolvedWord + ')' : '') + ' — click to cycle',
+            'aria-label': labelFor(current),
+            title: titleFor(current),
+            // getTheme() at click time, not the `current` captured when this
+            // vnode was built. Nothing re-renders this button on a theme
+            // change, so a captured value goes stale after the first click and
+            // the cycle sticks: auto -> paper, then every later click computes
+            // from a stale 'auto' and lands on paper again.
             onclick: () => {
-                const next = current === 'auto' ? 'paper' : (current === 'paper' ? 'ink' : 'auto');
+                const now = getTheme();
+                const next = now === 'auto' ? 'paper' : (now === 'paper' ? 'ink' : 'auto');
                 applyTheme(next);
                 if (onChange) try { onChange(next); } catch { /* swallow: consumer onChange callback must not break the toggle */ }
-            }
+            },
+            ref: (el) => bindThemePaint(el, () => {
+                const now = getTheme();
+                el.setAttribute('aria-label', labelFor(now));
+                el.setAttribute('title', titleFor(now));
+                const lab = el.querySelector('.ds-theme-toggle-label');
+                if (lab) lab.textContent = labelFor(now);
+            })
         },
         // CSS-drawn half-disc so the control still reads as the theme switch
         // when the label is hidden (icon-only rail strip).
         h('span', { class: 'ds-theme-disc', 'aria-hidden': 'true' }),
-        h('span', { class: 'ds-theme-toggle-label' }, label));
+        h('span', { class: 'ds-theme-toggle-label' }, labelFor(current)));
     }
 
     return h('div', {
         class: 'ds-theme-toggle ds-segmented',
         role: 'radiogroup',
-        'aria-label': 'theme'
+        'aria-label': 'theme',
+        // Paint the selected segment from the live theme rather than only from
+        // `current` (captured when this vnode was built). Nothing re-renders
+        // this control when it is clicked: the host kit's view is not
+        // subscribed to the theme, so applyTheme() correctly flipped
+        // <html data-theme> while the segment kept `is-on` on whatever was
+        // selected at mount — clicking "light" changed the theme but left
+        // "auto" looking selected, which reads as a control that did nothing.
+        // Doing it in a ref keeps this correct for BOTH triggers: a click here,
+        // and an external change (another toggle, or the OS scheme flipping
+        // while in auto) via the onThemeChange subscription.
+        ref: (el) => bindThemePaint(el, () => {
+            const now = getTheme();
+            for (const btn of el.querySelectorAll('.ds-seg-btn')) {
+                const on = btn.dataset.mode === now;
+                btn.classList.toggle('is-on', on);
+                btn.setAttribute('aria-checked', on ? 'true' : 'false');
+            }
+        })
     }, ...MODES.map(([mode, label]) =>
         h('button', {
             key: mode,
             type: 'button',
             role: 'radio',
+            'data-mode': mode,
             'aria-checked': current === mode ? 'true' : 'false',
             class: 'ds-seg-btn' + (current === mode ? ' is-on' : ''),
             onclick: () => {

package/src/css/app-shell/panel-row.css

@@ -155,10 +155,19 @@ a.row:hover .meta, .row[role="button"]:hover .meta { color: var(--accent-ink); t
    takes the full width instead of wrapping in the narrow code gutter. */
 .row.row-nocode { grid-template-columns: minmax(0, 1fr) auto; }
 
-.row .code  { font-family: var(--ff-mono); font-size: var(--fs-xs); color: var(--fg-3); font-variant-numeric: tabular-nums; letter-spacing: 0.01em; }
+/* `.row-code` / `.row-title` / `.row-meta` are the BEM-ish spelling of the same
+   three cells as `.code` / `.title` / `.meta`. Both spellings are live in the
+   wild (preview/index-row.html uses the hyphenated one), and a cell that
+   matches no rule falls back to browser defaults — 16px body text in all three
+   tracks, which is precisely the undifferentiated render the specimen page was
+   shipping. Aliased rather than renamed so neither spelling can silently go
+   unstyled again. */
+.row .code,
+.row .row-code  { font-family: var(--ff-mono); font-size: var(--fs-xs); color: var(--fg-3); font-variant-numeric: tabular-nums; letter-spacing: 0.01em; }
 /* Title defaults to the quiet app voice (fs-sm/500) — the 18px/600 marketing
    voice is now opt-in via .row--lede. */
-.row .title { font-family: var(--ff-body); font-weight: 500; font-size: var(--fs-sm); line-height: var(--lh-snug); display: flex; align-items: baseline; gap: var(--space-2-5); flex-wrap: wrap; min-width: 0; }
+.row .title,
+.row .row-title { font-family: var(--ff-body); font-weight: 500; font-size: var(--fs-sm); line-height: var(--lh-snug); display: flex; align-items: baseline; gap: var(--space-2-5); flex-wrap: wrap; min-width: 0; }
 .row .title .sub { font-family: var(--ff-body); font-weight: 400; font-size: var(--fs-sm); color: var(--fg-3); }
 /* Marketing/editorial index row — restores the roomier padding + larger title
    the default carried before app-scale became the base. */
@@ -174,7 +183,20 @@ a.row:hover .meta, .row[role="button"]:hover .meta { color: var(--accent-ink); t
 /* Context-pane cwd fact reads as a path (like .ds-dash-cwd/.ds-session-agent/
    .ds-dash-model) -- scoped to that one row so no other Row .sub is affected. */
 .ds-context-cwd-row .row .sub { font-family: var(--ff-mono); }
-.row .meta  { font-family: var(--ff-mono); font-size: var(--fs-xs); color: var(--fg-3); text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; align-self: center; }
+.row .meta,
+.row .row-meta  { font-family: var(--ff-mono); font-size: var(--fs-xs); color: var(--fg-3); text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; align-self: center; }
+/* `.row-meta` carries free prose ("state machine · 3k · shipping"), unlike
+   `.meta`'s short tabular counts — so it wraps instead of forcing the row's
+   third track wide enough to overflow a phone viewport. */
+.row .row-meta { white-space: normal; }
+/* Hairline-divided index list. `.row` is deliberately hairline-FREE (the rail
+   is the affordance), but an editorial index reads as a printed table of
+   contents: the divider IS the structure, which is what
+   preview/index-row.html's caption claims. Opt-in on the container so no
+   existing rail-based list changes. */
+.row-list > .row + .row { margin-top: 0; border-top: 1px solid var(--rule); border-radius: 0; }
+.row-list > .row:first-child { border-radius: var(--r-1) var(--r-1) 0 0; }
+.row-list > .row:last-child { border-radius: 0 0 var(--r-1) var(--r-1); }
 /* WorksList meta pairs a label with a disclosure chevron, inline-aligned. */
 .ds-works-meta { display: inline-flex; align-items: center; gap: .4em; }
 

package/src/css/app-shell/primitives.css

@@ -165,6 +165,15 @@
 .chip.tone-wip, .chip.tone-neutral {
   background: var(--bg-3); color: var(--fg-2);
 }
+/* `.chip.accent` is the bare-adjective spelling of tone-accent (ui_kits/blog
+   uses it for a "draft" chip). It had no rule anywhere, so an accented chip
+   rendered byte-identical to a plain one. Folded into the alias grouping rather
+   than given its own block, so the two spellings cannot drift apart. --accent
+   is the FILL and --accent-ink the readable text tone (AGENTS.md) — the bare
+   lead is ~1.07:1 on paper and unreadable as text. */
+.chip.accent, .chip.tone-accent {
+  background: var(--accent-tint); color: var(--accent-ink);
+}
 /* tone-dim was applied by five kits (aicat, project_page, signin, system_primer,
    terminal) with no rule anywhere, so a "dim" chip rendered byte-identical to a
    plain one — measured at rgb(234,230,218) on rgb(31,31,38), same opacity. It is
@@ -222,4 +231,17 @@
   font-family: var(--ff-mono); font-size: var(--fs-tiny);
   opacity: 0.8;
 }
+/* Glyph() (src/components/shell/atoms.js) emits `glyph glyph-{size}` and an
+   inline `font-size: var(--glyph-size-{size}, <literal>)`. The custom property
+   is the documented theming hook — it is what lets a theme retune glyph scale
+   without touching the component — but nothing declared it, so every glyph fell
+   through to the hard-coded inline literal and the hook was inert. Declaring
+   the three rungs on the scale makes the hook real; the sm/lg classes also give
+   the box a matching footprint instead of the one-size 18px square. */
+/* Values mirror Glyph()'s own inline fallbacks exactly (11 / 13 / 16px), so
+   declaring the hook changes nothing visually — it only makes the property
+   themeable, which is what it always claimed to be. */
+.glyph { --glyph-size-sm: var(--fs-nano); --glyph-size-base: var(--fs-tiny); --glyph-size-lg: var(--fs-body); }
+.glyph-sm { width: 14px; height: 14px; }
+.glyph-lg { width: 22px; height: 22px; }
 

package/src/css/app-shell/topbar.css

@@ -164,6 +164,14 @@ body.canvas-host { background: transparent !important; }
   padding: var(--space-5) var(--space-3);
   font-size: var(--fs-sm);
 }
+/* Sidebar section wrapper emitted by Side() (src/components/shell/app-shell.js).
+   It is the `role="group"` that owns the heading + its links, so it must be the
+   thing that groups them visually too: without a rule it was a bare block, and
+   the only separation between sections came from .app-side's own flex gap —
+   which meant the heading floated equidistant between the group it labels and
+   the one above it. Stacking the group's own children tightly re-attaches the
+   heading to its links. */
+.app-side-group { display: flex; flex-direction: column; gap: var(--space-hair); }
 .app-side .group {
   font-size: var(--fs-xs); font-weight: 600;
   color: var(--fg-3); padding: 0 var(--space-3);
@@ -184,7 +192,20 @@ body.canvas-host { background: transparent !important; }
 @media (pointer: coarse) {
   .app-side a { min-height: 44px; padding: var(--space-2-75) var(--space-3); }
 }
-.app-side a:hover { background: var(--bg-2); color: var(--fg); }
+/* A sidebar row with no href and no handler is a static label, not a control:
+   Side() emits it as an <a> only so it keeps the grid layout above. It must not
+   claim to be pressable — no pointer, no hover highlight. (An anchor without
+   href is already skipped by the tab order and exposed as generic, not link.) */
+.app-side a:not([href]) { cursor: default; }
+/* An entry naming a section/tag that does not exist yet — in the sidebar tree
+   or the topbar nav. It stays visible so the intended shape of the docs is
+   legible, but it is not a link and must not read as one: dimmed, and inert
+   like any other href-less anchor. Both selectors are needed because the two
+   navs style their anchors separately. */
+.app-side a.is-unwritten,
+.app-topbar nav a.is-unwritten { color: var(--fg-3); cursor: default; }
+.app-topbar nav a.is-unwritten:hover { background: none; color: var(--fg-3); }
+.app-side a[href]:hover { background: var(--bg-2); color: var(--fg); }
 .app-side a:focus-visible {
   outline: var(--focus-w) solid var(--focus-color);
   outline-offset: var(--focus-offset);