hlmnhkl-ui 0.25.1 → 0.29.0

package/README.md

@@ -1,6 +1,6 @@
 # hlmnhkl/ui
 
-React components, measured down to the part you never see: the 44px tap area, the 2px focus ring, the timing of every move. Black, white and grey, and copied into your app so the code is yours.
+React components, measured down to the part you never see: the 44px tap area, the 2px focus ring, the timing of every move. Black, white and grey with one blue accent, and copied into your app so the code is yours.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/hilmanhaikal/hlmnhkl-ui/main/.github/assets/home-dark.png">
@@ -65,7 +65,7 @@ Setup for other tools: [MCP server](https://ui.hlmnhkl.my/mcp).
 ## What you get
 
 - **The source, not a package.** The command copies plain files into your app. Change anything; there is no update to wait for.
-- **59 free components**, from Button, Dialog, Select and Table to Toast and Retime, one speed setting for every animation. See [COMPONENTS.md](COMPONENTS.md).
+- **63 free components**, from Button, Dialog, Select and Table to Toast and Retime, one speed setting for every animation. See [COMPONENTS.md](COMPONENTS.md).
 - **One look, set by tokens.** Every colour, size and timing comes from one file, `tokens.css`. Colour appears only to mean something: good, caution or bad.
 - **Light and dark.** Dark follows the system, or set `data-theme="dark"` on `<html>`.
 - **Accessible.** Keyboard support per the WAI-ARIA patterns, visible focus, screen reader labels, and reduced motion. On touch screens every control gives at least a 44px target, even the small sizes; only the six PIN boxes and the seven calendar days get narrower when the row has no room, about 36px wide on a 320px phone. CalendarHeatmap's days are small by design, since a year must fit on screen; its month table gives the same numbers at full size.
@@ -74,7 +74,7 @@ Setup for other tools: [MCP server](https://ui.hlmnhkl.my/mcp).
 
 ## Pro
 
-71 more components (such as DataGrid, Calendar, Chart, KanbanBoard and Combobox), page blocks, full templates and brand themes are coming as hlmnhkl/ui Pro. You can see them on the [docs site](https://ui.hlmnhkl.my).
+72 more components (such as DataGrid, Calendar, Chart, KanbanBoard and Combobox), page blocks, full templates and brand themes are coming as hlmnhkl/ui Pro. You can see them on the [docs site](https://ui.hlmnhkl.my).
 
 ## Licence
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hlmnhkl-ui",
-  "version": "0.25.1",
-  "description": "React components in a monochrome style. Copy them into your app with npx hlmnhkl-ui add <name>.",
+  "version": "0.29.0",
+  "description": "React components in black, white and grey with one blue accent. Copy them into your app with npx hlmnhkl-ui add <name>.",
   "license": "MIT",
   "homepage": "https://ui.hlmnhkl.my",
   "repository": {

package/scripts/pro-components.json

@@ -22,6 +22,7 @@
   "Drawer",
   "EmojiPicker",
   "FileUpload",
+  "GlassLens",
   "HoverCard",
   "IcInput",
   "Image",

package/src/components/Button/Button.module.css

@@ -74,7 +74,7 @@
   box-shadow: var(--hl-shadow-1);
 }
 @media (hover: hover) {
-  .primary:hover:not([aria-disabled="true"]) { background: var(--hl-color-inverse-hover); }
+  .primary:hover:not([aria-disabled="true"]) { background: var(--hl-color-accent-hover); }
 }
 
 .secondary {

package/src/components/Dialog/Dialog.module.css

@@ -27,9 +27,11 @@
   max-height: calc(100dvh - var(--hl-space-5) * 2);
   display: flex;
   flex-direction: column;
-  border: var(--hl-line) solid var(--hl-color-border);
+  border: var(--hl-line) solid var(--hl-glass-edge, var(--hl-color-border));
   border-radius: var(--hl-radius-panel);
-  background: var(--hl-color-surface);
+  background: var(--hl-glass-bg, var(--hl-color-surface));
+  -webkit-backdrop-filter: var(--hl-glass-filter, none);
+  backdrop-filter: var(--hl-glass-filter, none);
   box-shadow: var(--hl-shadow-4);
   outline: none;
   pointer-events: auto;

package/src/components/DropdownMenu/DropdownMenu.module.css

@@ -6,9 +6,11 @@
   max-height: calc(100dvh - 2 * var(--hl-space-5));
   overflow-y: auto;
   padding: var(--hl-space-2);
-  border: var(--hl-line) solid var(--hl-color-border);
+  border: var(--hl-line) solid var(--hl-glass-edge, var(--hl-color-border));
   border-radius: var(--hl-radius-md);
-  background: var(--hl-color-surface);
+  background: var(--hl-glass-bg, var(--hl-color-surface));
+  -webkit-backdrop-filter: var(--hl-glass-filter, none);
+  backdrop-filter: var(--hl-glass-filter, none);
   box-shadow: var(--hl-shadow-3);
   outline: none;
   transform-origin: top left;

package/src/components/Fab/Fab.module.css

@@ -0,0 +1,176 @@
+/* In the thumb zone: the bottom corner of the screen, clear of the home indicator and a notch. */
+.root {
+  position: fixed;
+  bottom: calc(env(safe-area-inset-bottom) + var(--hl-fab-gap));
+  z-index: var(--hl-z-sticky);
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: var(--hl-space-4);
+  pointer-events: none;
+}
+
+.end { right: calc(env(safe-area-inset-right) + var(--hl-fab-gap)); }
+
+.center {
+  left: 50%;
+  align-items: center;
+  translate: -50% 0;
+}
+
+.contained { position: absolute; }
+.contained.end { right: var(--hl-fab-gap); }
+.contained { bottom: var(--hl-fab-gap); }
+
+.fab {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  min-width: var(--hl-fab-size);
+  height: var(--hl-fab-size);
+  padding: 0 calc((var(--hl-fab-size) - var(--hl-icon-md)) / 2);
+  border: 0;
+  border-radius: var(--hl-radius-full);
+  background: var(--hl-color-accent);
+  color: var(--hl-color-accent-fg);
+  box-shadow: var(--hl-shadow-3);
+  font: inherit;
+  font-weight: var(--hl-weight-medium);
+  cursor: pointer;
+  pointer-events: auto;
+  -webkit-tap-highlight-color: transparent;
+  transition:
+    background-color var(--hl-motion-fast) var(--hl-ease-out),
+    scale var(--hl-motion-fast) var(--hl-ease-out);
+}
+
+@media (hover: hover) {
+  .fab:hover { background: var(--hl-color-accent-hover); }
+}
+
+.fab:active { scale: var(--hl-press-scale); }
+.fab:focus-visible { outline: none; box-shadow: var(--hl-shadow-3), var(--hl-focus-ring); }
+
+.icon {
+  display: grid;
+  place-items: center;
+  flex: none;
+  width: var(--hl-icon-md);
+  height: var(--hl-icon-md);
+  transition: rotate var(--hl-motion-slow) var(--hl-ease-spring);
+}
+
+.icon > svg { width: 100%; height: 100%; }
+
+/* Open: the icon turns a quarter, the way a plus becomes a cross. */
+.root[data-open] .icon { rotate: 45deg; }
+
+/* The label pours away into the icon: its column closes, so the pill shrinks to a circle around the icon. */
+.labelWrap {
+  display: grid;
+  grid-template-columns: 0fr;
+  transition: grid-template-columns var(--hl-motion-slower) var(--hl-ease-in-out);
+}
+
+.fab[data-extended] .labelWrap { grid-template-columns: 1fr; }
+
+.label {
+  min-width: 0;
+  overflow: hidden;
+  padding-inline-start: 0;
+  white-space: nowrap;
+  opacity: 0;
+  transition:
+    opacity var(--hl-motion-base) var(--hl-ease-out),
+    padding var(--hl-motion-slower) var(--hl-ease-in-out);
+}
+
+.fab[data-extended] .label {
+  padding-inline: var(--hl-space-3) var(--hl-space-2);
+  opacity: 1;
+  transition-delay: 0s, 0s;
+}
+
+/* The actions pour up out of the button, the nearest first, each a short step after the last. */
+.actions {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: var(--hl-space-3);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.center .actions { align-items: center; }
+
+.actions li {
+  opacity: 0;
+  translate: 0 var(--hl-shift-md);
+  scale: 0.6;
+  transform-origin: 100% 100%;
+  transition:
+    opacity var(--hl-motion-base) var(--hl-ease-out),
+    translate var(--hl-motion-slow) var(--hl-ease-spring),
+    scale var(--hl-motion-slow) var(--hl-ease-spring);
+}
+
+.center .actions li { transform-origin: 50% 100%; }
+
+.root[data-open] .actions li {
+  opacity: 1;
+  translate: none;
+  scale: 1;
+  transition-delay: calc(var(--i) * var(--hl-motion-stagger) * 2);
+}
+
+.action {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--hl-space-4);
+  min-height: var(--hl-hit-min);
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--hl-color-fg);
+  font: inherit;
+  cursor: pointer;
+  pointer-events: auto;
+  -webkit-tap-highlight-color: transparent;
+}
+
+.actionLabel {
+  padding: var(--hl-space-2) var(--hl-space-4);
+  border-radius: var(--hl-radius-full);
+  background: var(--hl-glass-bg, var(--hl-color-surface));
+  -webkit-backdrop-filter: var(--hl-glass-filter, none);
+  backdrop-filter: var(--hl-glass-filter, none);
+  box-shadow: var(--hl-shadow-2);
+  font-size: var(--hl-text-sm);
+  font-weight: var(--hl-weight-medium);
+  white-space: nowrap;
+}
+
+/* Lined up under the button's centre: a smaller circle in the same column. */
+.actionIcon {
+  display: grid;
+  place-items: center;
+  width: var(--hl-hit-min);
+  height: var(--hl-hit-min);
+  margin-inline-end: calc((var(--hl-fab-size) - var(--hl-hit-min)) / 2);
+  border-radius: var(--hl-radius-full);
+  background: var(--hl-glass-bg, var(--hl-color-surface));
+  -webkit-backdrop-filter: var(--hl-glass-filter, none);
+  backdrop-filter: var(--hl-glass-filter, none);
+  box-shadow: var(--hl-shadow-2);
+}
+
+.actionIcon > svg { width: var(--hl-icon-sm); height: var(--hl-icon-sm); }
+
+@media (hover: hover) {
+  .action:hover .actionIcon,
+  .action:hover .actionLabel { background: var(--hl-color-surface-hover); }
+}
+
+.action:focus-visible { outline: none; }
+.action:focus-visible .actionIcon { box-shadow: var(--hl-shadow-2), var(--hl-focus-ring); }

package/src/components/Fab/Fab.tsx

@@ -0,0 +1,117 @@
+'use client'
+
+import { useId, useRef, useState, type ReactNode } from 'react'
+import { cx } from '../../internal/cx'
+import { useDismiss } from '../../internal/layers'
+import { useScrollFrame } from '../../internal/scrollFrame'
+import styles from './Fab.module.css'
+
+export type FabAction = {
+  /** Shown beside the action's button and read as its name. */
+  label: string
+  icon: ReactNode
+  onSelect: () => void
+}
+
+export type FabProps = {
+  /** The button's name. Shown as text when extended, and always read by screen readers. */
+  label: string
+  /** The icon in the button, such as a plus. With actions it turns a quarter while they are open. */
+  icon: ReactNode
+  /** Called on tap. With actions, a tap opens them instead. */
+  onClick?: () => void
+  /** Shows the label beside the icon. It pours away into the icon as the page scrolls down, and back on the way up. */
+  extended?: boolean
+  /** A short stack of actions that pours up out of the button when it is tapped. */
+  actions?: FabAction[]
+  /** Where it sits along the bottom of the screen. */
+  position?: 'end' | 'center'
+  /** Sits at the bottom of its nearest positioned parent instead of the screen, for a demo or a panel. */
+  contained?: boolean
+  /** Extra class for the root element. */
+  className?: string
+}
+
+// One main action, floating in the thumb zone at the bottom of the screen.
+export function Fab({ label, icon, onClick, extended = false, actions, position = 'end', contained = false, className }: FabProps) {
+  const id = useId()
+  const rootRef = useRef<HTMLDivElement>(null)
+  const buttonRef = useRef<HTMLButtonElement>(null)
+  const firstRef = useRef<HTMLButtonElement>(null)
+  const [open, setOpen] = useState(false)
+  const [compact, setCompact] = useState(false)
+  const last = useRef<number | null>(null)
+
+  // Extended: down the page it folds to the icon, back up it opens again. It reads the scroll, never a timer.
+  useScrollFrame(
+    () => {
+      const y = window.scrollY
+      const prev = last.current
+      last.current = y
+      if (prev === null || Math.abs(y - prev) < 4) return
+      const next = y > prev && y > 80
+      return () => setCompact(next)
+    },
+    extended,
+  )
+
+  useDismiss(open, [rootRef], (reason) => {
+    setOpen(false)
+    if (reason === 'escape') buttonRef.current?.focus()
+  })
+
+  const hasActions = Boolean(actions?.length)
+  const toggle = () => {
+    if (!hasActions) return onClick?.()
+    const next = !open
+    setOpen(next)
+    if (next) requestAnimationFrame(() => firstRef.current?.focus())
+  }
+
+  return (
+    <div ref={rootRef} className={cx(styles.root, styles[position], contained && styles.contained, className)} data-open={open || undefined}>
+      {hasActions && (
+        <ul id={`${id}-actions`} className={styles.actions} inert={!open}>
+          {actions!.map((a, i) => (
+            <li key={a.label} style={{ ['--i' as string]: actions!.length - 1 - i }}>
+              <button
+                ref={i === 0 ? firstRef : undefined}
+                type="button"
+                className={styles.action}
+                onClick={() => {
+                  setOpen(false)
+                  buttonRef.current?.focus()
+                  a.onSelect()
+                }}
+              >
+                <span className={styles.actionLabel}>{a.label}</span>
+                <span className={styles.actionIcon} aria-hidden="true">
+                  {a.icon}
+                </span>
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+      <button
+        ref={buttonRef}
+        type="button"
+        className={styles.fab}
+        aria-label={extended ? undefined : label}
+        aria-expanded={hasActions ? open : undefined}
+        aria-controls={hasActions ? `${id}-actions` : undefined}
+        data-extended={(extended && !compact) || undefined}
+        onClick={toggle}
+      >
+        <span className={styles.icon} aria-hidden="true">
+          {icon}
+        </span>
+        {extended && (
+          <span className={styles.labelWrap}>
+            <span className={styles.label}>{label}</span>
+          </span>
+        )}
+      </button>
+    </div>
+  )
+}

package/src/components/Fab/index.ts

@@ -0,0 +1 @@
+export * from './Fab'

package/src/components/IconButton/IconButton.module.css

@@ -74,5 +74,5 @@
 }
 .primary { background: var(--hl-color-accent); color: var(--hl-color-accent-fg); }
 @media (hover: hover) {
-  .primary:hover:not(:disabled) { background: var(--hl-color-inverse-hover); }
+  .primary:hover:not(:disabled) { background: var(--hl-color-accent-hover); }
 }

package/src/components/Popover/Popover.module.css

@@ -4,9 +4,11 @@
   width: max-content;
   max-width: min(var(--hl-panel-w-sm), calc(100vw - var(--hl-space-5) * 2));
   padding: var(--hl-space-5);
-  border: var(--hl-line) solid var(--hl-color-border);
+  border: var(--hl-line) solid var(--hl-glass-edge, var(--hl-color-border));
   border-radius: var(--hl-radius-panel);
-  background: var(--hl-color-surface);
+  background: var(--hl-glass-bg, var(--hl-color-surface));
+  -webkit-backdrop-filter: var(--hl-glass-filter, none);
+  backdrop-filter: var(--hl-glass-filter, none);
   box-shadow: var(--hl-shadow-3);
   outline: none;
   transform-origin: top left;

package/src/components/Prose/Prose.module.css

@@ -0,0 +1,115 @@
+/* A line of about 68 characters, the length an eye can follow back to the next line without losing it.
+   :where keeps every rule at zero weight, so a class you add inside always wins. */
+.root {
+  max-width: var(--hl-prose-w);
+  color: var(--hl-color-fg);
+  font-size: var(--hl-text-md);
+  line-height: var(--hl-leading-normal);
+  overflow-wrap: break-word;
+}
+
+.root > :where(:first-child) { margin-top: 0; }
+.root > :where(:last-child) { margin-bottom: 0; }
+
+.root :where(p, ul, ol, blockquote, pre, figure, table, hr) { margin: 0 0 var(--hl-space-6); }
+
+/* A heading sits close to the text it opens and well clear of the text before it. */
+.root :where(h2, h3, h4) {
+  margin: var(--hl-space-10) 0 var(--hl-space-4);
+  font-weight: var(--hl-weight-semibold);
+  letter-spacing: var(--hl-tracking-tight);
+  line-height: var(--hl-leading-tight);
+  text-wrap: balance;
+}
+
+.root :where(h2) { font-size: var(--hl-text-2xl); }
+.root :where(h3) { font-size: var(--hl-text-xl); }
+.root :where(h4) { font-size: var(--hl-text-lg); }
+.root :where(h2, h3, h4) + :where(h3, h4) { margin-top: var(--hl-space-5); }
+
+.root :where(strong) { font-weight: var(--hl-weight-semibold); }
+
+.root :where(a) {
+  color: var(--hl-color-fg);
+  font-weight: var(--hl-weight-medium);
+  text-decoration: underline;
+  text-decoration-color: var(--hl-color-border-strong);
+  text-decoration-thickness: var(--hl-line);
+  text-underline-offset: 0.2em;
+  transition: text-decoration-color var(--hl-motion-fast) var(--hl-ease-out);
+}
+
+@media (hover: hover) {
+  .root :where(a):hover { text-decoration-color: currentColor; }
+}
+
+.root :where(a):focus-visible { outline: none; border-radius: var(--hl-radius-xs); box-shadow: var(--hl-focus-ring); }
+
+.root :where(ul, ol) { padding-left: var(--hl-space-6); }
+.root :where(li) { margin-bottom: var(--hl-space-2); padding-left: var(--hl-space-1); }
+.root :where(li) > :where(ul, ol) { margin: var(--hl-space-2) 0 0; }
+.root :where(li)::marker { color: var(--hl-color-fg-subtle); }
+
+/* A quote sits on a soft panel of its own, not behind a line down its side. */
+.root :where(blockquote) {
+  padding: var(--hl-space-5) var(--hl-space-6);
+  border-radius: var(--hl-radius-md);
+  background: var(--hl-color-surface-sunken);
+  color: var(--hl-color-fg-muted);
+}
+
+.root :where(blockquote) > :where(:last-child) { margin-bottom: 0; }
+
+.root :where(code) {
+  padding: 0.1em 0.35em;
+  border-radius: var(--hl-radius-xs);
+  background: var(--hl-color-surface-sunken);
+  font-family: var(--hl-font-mono);
+  font-size: 0.9em;
+}
+
+.root :where(pre) {
+  overflow-x: auto;
+  padding: var(--hl-space-5);
+  border-radius: var(--hl-radius-md);
+  background: var(--hl-code-bg);
+  color: var(--hl-code-fg);
+  font-size: var(--hl-text-sm);
+  line-height: var(--hl-leading-normal);
+}
+
+.root :where(pre) :where(code) { padding: 0; background: none; font-size: inherit; }
+
+.root :where(img, video) {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  border-radius: var(--hl-radius-md);
+}
+
+.root :where(figcaption) {
+  margin-top: var(--hl-space-3);
+  color: var(--hl-color-fg-muted);
+  font-size: var(--hl-text-sm);
+}
+
+.root :where(hr) {
+  height: 0;
+  border: 0;
+  border-top: var(--hl-line) solid var(--hl-color-border);
+}
+
+.root :where(table) {
+  display: block;
+  overflow-x: auto;
+  border-collapse: collapse;
+  font-size: var(--hl-text-sm);
+}
+
+.root :where(th, td) {
+  padding: var(--hl-space-3) var(--hl-space-4);
+  border-bottom: var(--hl-line) solid var(--hl-color-border);
+  text-align: left;
+}
+
+.root :where(th) { font-weight: var(--hl-weight-semibold); }

package/src/components/Prose/Prose.tsx

@@ -0,0 +1,14 @@
+import type { ComponentPropsWithRef, ElementType } from 'react'
+import { cx } from '../../internal/cx'
+import styles from './Prose.module.css'
+
+export type ProseProps = {
+  /** The element to render, such as article. */
+  as?: ElementType
+} & ComponentPropsWithRef<'div'>
+
+// Long text written elsewhere, such as Markdown or a CMS: headings, paragraphs, lists, quotes, code and
+// pictures, set for reading. It styles plain HTML inside it, so nothing needs a class.
+export function Prose({ as: Tag = 'div', className, ...rest }: ProseProps) {
+  return <Tag className={cx(styles.root, className)} {...rest} />
+}

package/src/components/Prose/index.ts

@@ -0,0 +1 @@
+export * from './Prose'

package/src/components/Sheet/Sheet.module.css

@@ -19,10 +19,12 @@
   display: flex;
   flex-direction: column;
   margin-left: calc(min(100%, var(--hl-panel-w-lg)) / -2);
-  border: var(--hl-line) solid var(--hl-color-border);
+  border: var(--hl-line) solid var(--hl-glass-edge, var(--hl-color-border));
   border-bottom: 0;
   border-radius: var(--hl-radius-sheet) var(--hl-radius-sheet) 0 0;
-  background: var(--hl-color-surface);
+  background: var(--hl-glass-bg, var(--hl-color-surface));
+  -webkit-backdrop-filter: var(--hl-glass-filter, none);
+  backdrop-filter: var(--hl-glass-filter, none);
   box-shadow: var(--hl-shadow-4);
   outline: none;
   padding-bottom: env(safe-area-inset-bottom);

package/src/components/TableOfContents/TableOfContents.module.css

@@ -0,0 +1,107 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--hl-space-3);
+}
+
+.title {
+  margin: 0 0 var(--hl-space-2);
+  font-size: var(--hl-text-sm);
+  font-weight: var(--hl-weight-semibold);
+  color: var(--hl-color-fg);
+}
+
+/* A strip of frames, one per section, threaded on a faint line through their middles. */
+.list {
+  position: relative;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.list::before {
+  content: "";
+  position: absolute;
+  top: var(--hl-space-6);
+  bottom: var(--hl-space-6);
+  left: calc(var(--hl-space-3) + var(--hl-space-2) - var(--hl-line) / 2);
+  border-left: var(--hl-line) solid var(--hl-color-border);
+}
+
+/* Looks compact but keeps a 44px hit area with an invisible layer. */
+.link {
+  position: relative;
+  display: flex;
+  align-items: baseline;
+  gap: var(--hl-space-4);
+  width: 100%;
+  min-height: var(--hl-control-h-sm);
+  padding: var(--hl-space-2) var(--hl-space-3);
+  border-radius: var(--hl-radius-sm);
+  color: var(--hl-color-fg-muted);
+  font-size: var(--hl-text-sm);
+  line-height: var(--hl-leading-snug);
+  text-decoration: none;
+  transition: color var(--hl-motion-fast) var(--hl-ease-out), background-color var(--hl-motion-fast) var(--hl-ease-out);
+}
+
+.link::after {
+  content: "";
+  position: absolute;
+  inset-inline: 0;
+  inset-block: min(0px, calc((100% - var(--hl-hit-min)) / 2));
+}
+
+@media (hover: hover) {
+  .link:hover { color: var(--hl-color-fg); background: var(--hl-color-surface-hover); }
+}
+
+.link:focus-visible { outline: none; box-shadow: var(--hl-focus-ring); }
+
+/* Each section's frame: open ahead, filled once read, ringed where the reader is. */
+.node {
+  position: relative;
+  z-index: 1;
+  flex: none;
+  width: var(--hl-space-4);
+  height: var(--hl-space-4);
+  translate: 0 calc(var(--hl-space-1) / 2);
+  border: var(--hl-line-thick) solid var(--hl-color-border-strong);
+  border-radius: var(--hl-radius-full);
+  background: var(--hl-color-bg);
+  transition:
+    background-color var(--hl-motion-base) var(--hl-ease-out),
+    border-color var(--hl-motion-base) var(--hl-ease-out),
+    box-shadow var(--hl-motion-base) var(--hl-ease-out);
+}
+
+[data-state="read"] .node { border-color: var(--hl-color-fg-subtle); background: var(--hl-color-fg-subtle); }
+
+[data-state="here"] .link { color: var(--hl-color-fg); font-weight: var(--hl-weight-medium); }
+
+[data-state="here"] .node {
+  border-color: var(--hl-color-fg);
+  background: var(--hl-color-fg);
+  box-shadow: 0 0 0 var(--hl-space-1) var(--hl-color-bg), 0 0 0 calc(var(--hl-space-1) + var(--hl-line-thick)) var(--hl-color-fg);
+}
+
+.toTop {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--hl-space-2);
+  align-self: flex-start;
+  min-height: var(--hl-hit-min);
+  padding-inline: var(--hl-space-3);
+  border-radius: var(--hl-radius-sm);
+  color: var(--hl-color-fg-muted);
+  font-size: var(--hl-text-sm);
+  text-decoration: none;
+}
+
+.toTop > svg { width: var(--hl-icon-sm); height: var(--hl-icon-sm); }
+
+@media (hover: hover) {
+  .toTop:hover { color: var(--hl-color-fg); background: var(--hl-color-surface-hover); }
+}
+
+.toTop:focus-visible { outline: none; box-shadow: var(--hl-focus-ring); }

package/src/components/TableOfContents/TableOfContents.tsx

@@ -0,0 +1,93 @@
+'use client'
+
+import { useEffect, useState, type MouseEvent } from 'react'
+import { cx } from '../../internal/cx'
+import { ArrowUpIcon } from '../../internal/icons'
+import { prefersReducedMotion } from '../../internal/motion'
+import styles from './TableOfContents.module.css'
+
+export type TocItem = {
+  /** The id of the heading on the page. */
+  id: string
+  label: string
+}
+
+export type TableOfContentsProps = {
+  /** The sections, in page order: each heading's id and the text to show for it. */
+  items: TocItem[]
+  /** Heading above the list, also the nav's name. */
+  title?: string
+  /** Adds a way back to the top once the reader has passed the first section. */
+  backToTop?: boolean
+  /** Extra class for the root element. */
+  className?: string
+}
+
+// The sections of a page as links to their headings. Each is a frame on a strip: filled once read, ringed
+// where the reader is, open ahead, so it shows how far through the page they are, not only where.
+export function TableOfContents({ items, title = 'On this page', backToTop = false, className }: TableOfContentsProps) {
+  const [active, setActive] = useState(items[0]?.id)
+
+  // The section being read is the last heading past the top third of the screen.
+  useEffect(() => {
+    const headings = items.map((t) => document.getElementById(t.id)).filter((h): h is HTMLElement => !!h)
+    const update = () => {
+      const line = window.innerHeight / 3
+      let current = headings[0]?.id
+      for (const h of headings) if (h.getBoundingClientRect().top <= line) current = h.id
+      // A short last section never reaches the line, so the bottom of the page selects it.
+      const atBottom = window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2
+      setActive(atBottom ? headings[headings.length - 1]?.id : current)
+    }
+    update()
+    window.addEventListener('scroll', update, { passive: true })
+    window.addEventListener('resize', update)
+    return () => {
+      window.removeEventListener('scroll', update)
+      window.removeEventListener('resize', update)
+    }
+  }, [items])
+
+  const plain = (e: MouseEvent) => e.button === 0 && !e.metaKey && !e.ctrlKey && !e.shiftKey && !e.altKey
+
+  // A plain click scrolls there and keeps one history entry; Cmd-click still opens a new tab.
+  const go = (e: MouseEvent<HTMLAnchorElement>, id: string) => {
+    const heading = document.getElementById(id)
+    if (!plain(e) || !heading) return
+    e.preventDefault()
+    heading.scrollIntoView({ behavior: prefersReducedMotion() ? 'auto' : 'smooth', block: 'start' })
+    if (!heading.hasAttribute('tabindex')) heading.setAttribute('tabindex', '-1')
+    heading.focus({ preventScroll: true })
+    window.history.replaceState(window.history.state, '', `#${id}`)
+  }
+
+  const toTop = (e: MouseEvent<HTMLAnchorElement>) => {
+    if (!plain(e)) return
+    e.preventDefault()
+    window.scrollTo({ top: 0, behavior: prefersReducedMotion() ? 'auto' : 'smooth' })
+    window.history.replaceState(window.history.state, '', window.location.pathname + window.location.search)
+  }
+
+  const at = Math.max(0, items.findIndex((t) => t.id === active))
+  return (
+    <nav className={cx(styles.root, className)} aria-label={title}>
+      <p className={styles.title}>{title}</p>
+      <ol className={styles.list}>
+        {items.map((t, n) => (
+          <li key={t.id} data-state={n < at ? 'read' : n === at ? 'here' : 'ahead'}>
+            <a href={`#${t.id}`} className={styles.link} aria-current={active === t.id ? 'location' : undefined} onClick={(e) => go(e, t.id)}>
+              <span className={styles.node} aria-hidden="true" />
+              {t.label}
+            </a>
+          </li>
+        ))}
+      </ol>
+      {backToTop && at > 0 && (
+        <a href="#" className={styles.toTop} onClick={toTop}>
+          <ArrowUpIcon aria-hidden="true" />
+          Back to top
+        </a>
+      )}
+    </nav>
+  )
+}

package/src/components/TableOfContents/index.ts

@@ -0,0 +1 @@
+export * from './TableOfContents'

package/src/components/ThemeToggle/ThemeToggle.module.css

@@ -0,0 +1,21 @@
+/* The sun and the moon share one spot: the one for the other theme turns away and shrinks as the
+   current one turns in. */
+.icon {
+  display: grid;
+  width: 1em;
+  height: 1em;
+}
+
+.sun,
+.moon {
+  grid-area: 1 / 1;
+  width: 100%;
+  height: 100%;
+  transition:
+    transform var(--hl-motion-slower) var(--hl-ease-spring),
+    opacity var(--hl-motion-base) var(--hl-ease-out);
+}
+
+/* Shows the theme the button switches to: the moon in light, the sun in dark. */
+.icon:not([data-theme-shown="dark"]) .sun { opacity: 0; transform: rotate(90deg) scale(0.4); }
+.icon[data-theme-shown="dark"] .moon { opacity: 0; transform: rotate(-90deg) scale(0.4); }

package/src/components/ThemeToggle/ThemeToggle.tsx

@@ -0,0 +1,69 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { MoonIcon, SunIcon } from '../../internal/icons'
+import { IconButton } from '../IconButton'
+import styles from './ThemeToggle.module.css'
+
+export type Theme = 'light' | 'dark'
+
+export type ThemeToggleProps = {
+  /** The theme, when your app keeps it. Leave it out and the toggle sets data-theme on <html> itself. */
+  theme?: Theme
+  /** Called with the new theme on every flip. */
+  onThemeChange?: (theme: Theme) => void
+  /** Where the choice is remembered when the toggle runs the page. Match it in themeScript. */
+  storageKey?: string
+  /** The button's size, the same as IconButton. */
+  size?: 'sm' | 'md' | 'lg'
+  /** Extra class for the button. */
+  className?: string
+}
+
+/** Put in <head>, before the page paints, so a saved dark theme never flashes light first. */
+export const themeScript = (storageKey = 'hl-theme') =>
+  `try{var t=localStorage.getItem(${JSON.stringify(storageKey)});if(t!=='light'&&t!=='dark')t=matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';document.documentElement.dataset.theme=t}catch(e){}`
+
+const pageTheme = (): Theme => (document.documentElement.dataset.theme === 'dark' ? 'dark' : 'light')
+
+// One button that flips between the light and dark theme. The sun turns into the moon and back.
+export function ThemeToggle({ theme: themeProp, onThemeChange, storageKey = 'hl-theme', size = 'sm', className }: ThemeToggleProps) {
+  const controlled = themeProp !== undefined
+  const [own, setOwn] = useState<Theme>('light')
+  const theme = controlled ? themeProp : own
+
+  // Read after mount: the server cannot know the page's theme, and themeScript has already set it.
+  useEffect(() => {
+    if (!controlled) setOwn(pageTheme())
+  }, [controlled])
+
+  const next: Theme = theme === 'dark' ? 'light' : 'dark'
+  const flip = () => {
+    if (!controlled) {
+      document.documentElement.dataset.theme = next
+      try {
+        localStorage.setItem(storageKey, next)
+      } catch {
+        // Not saved, so it lasts only this visit; the theme still changes.
+      }
+      setOwn(next)
+    }
+    onThemeChange?.(next)
+  }
+
+  return (
+    <IconButton
+      label={`Switch to ${next} theme`}
+      variant="secondary"
+      size={size}
+      className={className}
+      onClick={flip}
+      icon={
+        <span className={styles.icon} data-theme-shown={theme}>
+          <SunIcon className={styles.sun} />
+          <MoonIcon className={styles.moon} />
+        </span>
+      }
+    />
+  )
+}

package/src/components/ThemeToggle/index.ts

@@ -0,0 +1 @@
+export * from './ThemeToggle'

package/src/components/Toast/Toast.module.css

@@ -46,9 +46,11 @@
   align-items: flex-start;
   gap: var(--hl-space-4);
   padding: var(--hl-space-5) var(--hl-space-2) var(--hl-space-5) var(--hl-space-5);
-  border: var(--hl-line) solid var(--hl-color-border);
+  border: var(--hl-line) solid var(--hl-glass-edge, var(--hl-color-border));
   border-radius: var(--hl-radius-md);
-  background: var(--hl-color-surface);
+  background: var(--hl-glass-bg, var(--hl-color-surface));
+  -webkit-backdrop-filter: var(--hl-glass-filter, none);
+  backdrop-filter: var(--hl-glass-filter, none);
   box-shadow: var(--hl-shadow-3);
   pointer-events: auto;
   touch-action: pan-y;

package/src/components/Toggle/Toggle.module.css

@@ -59,7 +59,7 @@
 
 @media (hover: hover) {
   .root:hover:not(:disabled):not([data-on]) { background: var(--hl-color-surface-hover); }
-  .root[data-on]:hover:not(:disabled) { background: var(--hl-color-inverse-hover); }
+  .root[data-on]:hover:not(:disabled) { background: var(--hl-color-accent-hover); }
 }
 
 .root:focus-visible {

package/src/tokens.css

@@ -36,9 +36,13 @@
   --hl-color-inverse-fg: var(--hl-gray-0);
   --hl-color-inverse-hover: var(--hl-gray-700);
   --hl-color-shimmer: rgb(255 255 255 / 0.7);
-  /* Accent: the foreground by default, so the library stays monochrome */
-  --hl-color-accent: var(--hl-color-inverse);
-  --hl-color-accent-fg: var(--hl-color-inverse-fg);
+  /* Accent: marking blue, the layout dye a machinist wipes on a part to check its fit, for what is chosen
+     or on: primary buttons, checked and selected states, the current tab, progress. Blue because most
+     apps use it for the main action, so it reads at once. Everything else stays black, white and grey.
+     White on it is 6.8:1. */
+  --hl-color-accent: #1f5aa6;
+  --hl-color-accent-fg: #ffffff;
+  --hl-color-accent-hover: #194a8a;
 
   /* Status: always paired with an icon or word */
   --hl-color-success: #12733a;
@@ -72,6 +76,8 @@
   --hl-leading-tight: 1.2;
   --hl-leading-snug: 1.4;
   --hl-leading-normal: 1.6;
+  /* Prose: the longest line of reading text, about the most an eye follows back to the next line */
+  --hl-prose-w: 68ch;
   --hl-weight-regular: 400;
   --hl-weight-medium: 500;
   --hl-weight-semibold: 600;
@@ -166,6 +172,8 @@
   --hl-motion-base: calc(220ms * var(--hl-motion-scale));
   --hl-motion-slow: calc(360ms * var(--hl-motion-scale));
   --hl-motion-slower: calc(600ms * var(--hl-motion-scale));
+  /* Navbar dock: the trip to and from the bottom of the screen, long enough to read as liquid */
+  --hl-motion-pour: calc(760ms * var(--hl-motion-scale));
   --hl-motion-stagger: calc(30ms * var(--hl-motion-scale));
   --hl-motion-delay-tooltip: 400ms;
   --hl-motion-shimmer: 1400ms;
@@ -231,6 +239,9 @@
     --hl-color-inverse: #ececec;
     --hl-color-inverse-fg: #0a0a0a;
     --hl-color-inverse-hover: var(--hl-gray-300);
+    --hl-color-accent: #7fa8e6;
+    --hl-color-accent-fg: #0a0a0a;
+    --hl-color-accent-hover: #9bbcec;
     --hl-color-shimmer: rgb(255 255 255 / 0.06);
     --hl-color-success: #4cc97a;
     --hl-color-warning: #f2b33d;
@@ -269,6 +280,9 @@
   --hl-color-inverse: #ececec;
   --hl-color-inverse-fg: #0a0a0a;
   --hl-color-inverse-hover: var(--hl-gray-300);
+  --hl-color-accent: #7fa8e6;
+  --hl-color-accent-fg: #0a0a0a;
+  --hl-color-accent-hover: #9bbcec;
   --hl-color-shimmer: rgb(255 255 255 / 0.06);
   --hl-color-success: #4cc97a;
   --hl-color-warning: #f2b33d;
@@ -296,6 +310,7 @@
     --hl-motion-base: 0ms;
     --hl-motion-slow: 0ms;
     --hl-motion-slower: 0ms;
+    --hl-motion-pour: 0ms;
     --hl-motion-stagger: 0ms;
     --hl-motion-shimmer: 0ms;
     --hl-motion-spin: 1600ms;
@@ -378,6 +393,9 @@
   --hl-navbar-h: 64px;
   /* Navbar float: how far the page scrolls while the bar lifts into a floating card */
   --hl-navbar-float-run: 160px;
+  /* Fab: the round button's size, and its gap from the bottom and side of the screen */
+  --hl-fab-size: 56px;
+  --hl-fab-gap: 16px;
   --hl-sidebar-w: 248px;
   --hl-sidebar-w-collapsed: 64px;
   --hl-tabbar-h: 64px;
@@ -403,15 +421,18 @@
   /* A cell's widest, so long text wraps and a sideways-scrolling table stays readable. */
   --hl-table-cell-max: 320px;
 
-  /* Charts: series differ by shade, dash and marker, never colour alone */
+  /* Charts: series differ by colour, dash and marker, never colour alone. The colours are a survey map's
+     own code, in a fixed order: navy (the accent's family), contour brown, survey green, revision purple,
+     chart ochre. Checked for colour-blind separation (8.0 or more for adjacent pairs) and 3:1 against the surface, in both
+     themes. A sixth series folds into "Other" or a second chart; it never gets a made-up colour. */
   --hl-chart-h: 260px;
   --hl-chart-donut: 220px;
   --hl-chart-area-opacity: 0.14;
-  --hl-chart-1: var(--hl-gray-950);
-  --hl-chart-2: var(--hl-gray-600);
-  --hl-chart-3: #8a8a8a;
-  --hl-chart-4: var(--hl-gray-800);
-  --hl-chart-5: var(--hl-gray-500);
+  --hl-chart-1: #2f64b4;
+  --hl-chart-2: #b36324;
+  --hl-chart-3: #2f9a6e;
+  --hl-chart-4: #8a52c2;
+  --hl-chart-5: #a8861a;
   --hl-chart-dash-1: none;
   --hl-chart-dash-2: 6 4;
   --hl-chart-dash-3: 1.5 3.5;
@@ -426,22 +447,23 @@
   --hl-editor-min-h: 160px;
 }
 
+/* The same five colours, a step lighter for the dark surface, checked there on their own. */
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme="light"]) {
-    --hl-chart-1: var(--hl-gray-50);
-    --hl-chart-2: var(--hl-gray-400);
-    --hl-chart-3: #707070;
-    --hl-chart-4: var(--hl-gray-200);
-    --hl-chart-5: var(--hl-gray-500);
+    --hl-chart-1: #638fdb;
+    --hl-chart-2: #c97638;
+    --hl-chart-3: #3ea97a;
+    --hl-chart-4: #a873d6;
+    --hl-chart-5: #b0902a;
   }
 }
 
 [data-theme="dark"] {
-  --hl-chart-1: var(--hl-gray-50);
-  --hl-chart-2: var(--hl-gray-400);
-  --hl-chart-3: #707070;
-  --hl-chart-4: var(--hl-gray-200);
-  --hl-chart-5: var(--hl-gray-500);
+  --hl-chart-1: #638fdb;
+  --hl-chart-2: #c97638;
+  --hl-chart-3: #3ea97a;
+  --hl-chart-4: #a873d6;
+  --hl-chart-5: #b0902a;
 }
 
 @media (prefers-reduced-motion: reduce) {