@helloimjolopez-pathway/pathway-components 0.0.0-stage → 0.1.0

package/components/icon/action-icon.jsx

@@ -0,0 +1,155 @@
+/**
+ * ActionIcon: the icon-only control Pathway puts in a header or a toolbar.
+ *
+ * SOURCE OF TRUTH: Figma set `Action Icon` 40006794:19891, on the
+ * `↳ ❇️ Action Icon` page. Nine variants on two axes, read and MEASURED
+ * 2026-10-07. Used 30 times inside the Widget set and twice inside KPI Tiles,
+ * which makes it the most-nested component in this part of the system and the
+ * one whose absence from Code Connect mattered most.
+ *
+ * MEASURED, per Size. The box is the target, `Container.Icon` is the state
+ * layer, and the glyph is the frame size an `<Icon>` takes:
+ *
+ *   Size    box     Container.Icon   glyph
+ *   Small   36x36        24x24 r=8     12
+ *   Base    44x44        28x28 r=8     14
+ *   Large   48x48        32x32 r=8     16
+ *
+ * STATE TOKENS, read off all six state variants 2026-10-08.
+ *
+ * The state layer's fill:
+ *   Default    none
+ *   Hover      `Fill/Action/Primary/Subtle/Hover`
+ *   Pressed    `Fill/Action/Primary/Subtle/Pressed`
+ *
+ * The glyph's colour:
+ *   Default    `Foreground/Action/Secondary/Rest`
+ *   Hover      `Foreground/Action/Secondary/Hover`
+ *   Pressed    `Foreground/Action/Secondary/Pressed`
+ *
+ * `State` is Default / Hover / Pressed and is runtime, never a prop.
+ * `Icon` is an INSTANCE_SWAP, which in code is the `name` prop: any Material
+ * Symbols ligature.
+ *
+ * THE COMPONENT ITSELF BINDS NO FILL, in any of the nine variants, and the
+ * glyph's fill is unbound too so it inherits. That is why this takes its
+ * resting colour from `color` on the button and lets the glyph inherit it: the
+ * design expresses "whatever the surrounding context is" rather than a fixed
+ * icon colour, and a hard-coded one would break the Widget header, the KPI
+ * tile and a dark toolbar all differently.
+ *
+ * WHY IT LIVES HERE rather than in widget.jsx, where it used to. It was a
+ * private helper inside the Widget, so the Figma component had nothing
+ * importable to point at and the KPI Tile could not reuse it. The Widget now
+ * imports it.
+ */
+import React, { useState } from "react";
+import { Icon } from "./icon.jsx";
+import { useReducedMotion } from "../_shared/use-reduced-motion.jsx";
+
+const C = (n) => `var(--semantic-color-${n})`;
+const U = (n) => `var(--semantic-layout-units-${n})`;
+const M = (n) => `var(--motion-${n})`;
+
+/* Read off the Action Icon set, every variant, 2026-10-12. `box` is the button,
+   `layer` is the state-layer frame the hover and pressed fills go on, `glyph` is
+   the nested Material Symbols instance.
+
+   THE GLYPHS WERE EVERY ONE 2px TOO SMALL. This read 12 / 14 / 16, which is the
+   sequence one step down from the real one, so every action icon in the system
+   rendered small inside a correctly sized target: the Widget header's 16px
+   ellipsis drew at 14. The three state-layer sizes were right, which is why it
+   survived a measurement pass that compared targets and layers and never looked
+   at the glyph. Figma's nested instance is 14 at Small, 16 at Base, 18 at Large. */
+export const ACTION_ICON_SIZES = {
+  Small: { box: 36, layer: 24, glyph: 14 },
+  Base:  { box: 44, layer: 28, glyph: 16 },
+  Large: { box: 48, layer: 32, glyph: 18 },
+};
+
+export const T = {
+  rest:       C("foreground-action-secondary-rest"),
+  hover:      C("foreground-action-secondary-hover"),
+  pressed:    C("foreground-action-secondary-pressed"),
+  /* THE STATE LAYER IS ACTION/PRIMARY/SUBTLE, NOT ACTION/SECONDARY.
+     Read off the set's six state variants on 2026-10-08: Hover binds
+     Fill/Action/Primary/Subtle/Hover and Pressed binds /Pressed. This file used
+     the SECONDARY family, which is a neutral grey, where the design is a light
+     blue. That is the single most visible token error in the component, because
+     the hover state is the only thing the layer is for. */
+  layerHover: C("fill-action-primary-subtle-hover"),
+  layerPress: C("fill-action-primary-subtle-pressed"),
+};
+
+/**
+ * @param {string} name   Material Symbols ligature, Figma's `Icon` swap.
+ * @param {"Small"|"Base"|"Large"} size  Figma's Size axis.
+ * @param {string} label  Required: an icon-only control with no accessible
+ *                        name is unusable, so this is not optional.
+ * @param {0|1} fill      FILL axis. The Widget header is FILL 0.
+ * @param {string} color  Override the resting colour. Omit on a light surface;
+ *                        pass one on a dark or on-brand surface, where Ghost
+ *                        is the right family.
+ */
+export function ActionIcon({
+  name,
+  size = "Small",
+  label,
+  fill = 0,
+  color,
+  onClick,
+  disabled,
+  className = "",
+  style,
+  ...rest
+}) {
+  const noMotion = useReducedMotion();
+  const [hov, setHov] = useState(false);
+  const [press, setPress] = useState(false);
+  const s = ACTION_ICON_SIZES[size] || ACTION_ICON_SIZES.Small;
+  const fg = disabled ? T.rest : press ? T.pressed : hov ? T.hover : (color || T.rest);
+
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={label}
+      disabled={disabled}
+      onClick={onClick}
+      onMouseEnter={() => setHov(true)}
+      onMouseLeave={() => { setHov(false); setPress(false); }}
+      onMouseDown={() => setPress(true)}
+      onMouseUp={() => setPress(false)}
+      onBlur={() => setPress(false)}
+      className={`pw-action-icon ${className}`}
+      data-size={size}
+      style={{
+        display: "inline-flex", alignItems: "center", justifyContent: "center",
+        width: s.box, height: s.box, flexShrink: 0, boxSizing: "border-box",
+        background: "transparent", border: "none", padding: 0,
+        cursor: disabled ? "default" : "pointer",
+        opacity: disabled ? 0.5 : 1,
+        color: fg,
+        ...style,
+      }}
+      {...rest}
+    >
+      {/* Container.Icon is the state layer, and it is SMALLER than the target.
+          The fill belongs on this box, not on the button: painting the target
+          gives a hover area visibly larger than the one in the design, which
+          is the bug the Widget header shipped with once. */}
+      <span style={{
+        display: "inline-flex", alignItems: "center", justifyContent: "center",
+        width: s.layer, height: s.layer, borderRadius: U("cornerradius-base"),
+        background: press ? T.layerPress : hov ? T.layerHover : "transparent",
+        transition: noMotion ? "none" : `background ${M("duration-2")} ${M("easing-standard")}`,
+      }}>
+        <Icon name={name} size={s.glyph} fill={fill} style={{
+          transition: noMotion ? "none" : `color ${M("duration-2")} ${M("easing-standard")}`,
+        }} />
+      </span>
+    </button>
+  );
+}
+
+export default ActionIcon;

package/components/icon/display-icon.jsx

@@ -0,0 +1,137 @@
+/**
+ * DisplayIcon: a decorative icon in a tinted circle, used by alerts, empty
+ * states and the KPI tile's featured icon slot.
+ *
+ * SOURCE OF TRUTH: Figma set `DisplayIcon` 40006522:26547 on the
+ * `↳ ❇️ Display Icon` page. 21 variants on Size x Color, plus an
+ * INSTANCE_SWAP for the glyph, read and MEASURED 2026-10-07.
+ *
+ * MEASURED
+ *   Size      box       glyph
+ *   Small    24x24       12
+ *   Medium   32x32       16
+ *   Large    40x40       20
+ *
+ *   Color    Accent | Positive | Negative | Danger | Neutral | Info | Alert
+ *
+ * THE COLOUR AXIS MAPS ONTO THE MEANING-NAMED TONE GROUPS, not onto hue names,
+ * which is what CLAUDE.md §2.0 requires. `Danger` and `Negative` are both in
+ * the Figma axis and are different tones in the token set: Negative is Red and
+ * Severe is Orange, so Danger takes Severe. `Accent` has no single meaning, so
+ * it takes Brand rather than one of the four decorative accents, because a
+ * display icon on an alert is not decoration.
+ *
+ * Each tone draws its SUBTLE fill with its ON SUBTLE foreground, which is the
+ * pairing the token set guarantees and `check-fill-foreground-pairs` asserts.
+ * Reaching for a Strong fill here would put tone text on a tone block.
+ *
+ * THE TOKENS BELOW ARE READ BACK FROM FIGMA, not derived from the names.
+ *
+ * What was there before, and what it took to find it: the variant itself has no
+ * fill and the nested glyph instance has no fill, so a reader checking those two
+ * nodes concludes the Color axis is unbound. It is not: the bindings live on the
+ * `Container` frame and on the `_shape` vector INSIDE the glyph instance. A
+ * first pass reported "no tokens at all", which was wrong.
+ *
+ * The real defects, found by reading all 21 variants on 2026-10-08 and fixed in
+ * the file the same day:
+ *
+ *   - Only 4 of 21 glyphs were bound. The other 17 were raw fills.
+ *   - Two of those 4 used HUE-NAMED tokens, `Foreground/Static/Amethyst/Bold`
+ *     and `Foreground/Static/Green/Bold`, which the semantic tier forbids and
+ *     which are not even in the local variable set any more.
+ *   - `Neutral` drew `Fill/Action/Secondary/Hover`: an ACTION token on a
+ *     decorative element that has no states.
+ *   - `Info` drew `Fill/Static/Brand/Faint`, and Faint has no paired On Subtle
+ *     foreground, so the pairing the token set guarantees did not exist for it.
+ *   - Every Container carried a paint STYLE as well as a variable, which is two
+ *     sources of truth for one colour. The styles were cleared.
+ */
+import React from "react";
+import { Icon } from "./icon.jsx";
+
+const C = (n) => `var(--semantic-color-${n})`;
+
+const U = (n) => `var(--semantic-layout-units-${n})`;
+
+export const L = {
+  // Figma: Container cornerRadius 8 on all 21 variants.
+  radius: U("cornerradius-base"),
+};
+
+export const DISPLAY_ICON_SIZES = {
+  Small:  { box: 24, glyph: 12 },
+  Medium: { box: 32, glyph: 16 },
+  Large:  { box: 40, glyph: 20 },
+};
+
+/**
+ * Figma's Color axis, read back from the file after binding on 2026-10-08.
+ *
+ * EACH VALUE KEEPS THE HUE IT ALREADY RENDERED. The names are not a clean map
+ * onto the tone groups and that is the file's own history, not something to
+ * tidy here: `Accent` resolves to INFO (amethyst) and `Info` resolves to BRAND.
+ * Repointing either would repaint a variant rather than fix a mapping, so the
+ * binding kept the hue and fixed only the tier and the pairing.
+ *
+ * An earlier version of this file guessed Accent to Brand and Info to Info,
+ * which is those two swapped, so a consumer asking for Accent got blue where
+ * the design is amethyst.
+ */
+export const DISPLAY_ICON_COLORS = {
+  // Accent is amethyst, which is the Info tone in the token set.
+  Accent:   { fill: C("fill-static-info-subtle"),      fg: C("foreground-static-info-on-subtle") },
+  Positive: { fill: C("fill-static-positive-subtle"),  fg: C("foreground-static-positive-on-subtle") },
+  Negative: { fill: C("fill-static-negative-subtle"),  fg: C("foreground-static-negative-on-subtle") },
+  // Danger is Severe (orange), a different tone from Negative (red). Both are
+  // in the Figma axis, so they must stay different here too.
+  Danger:   { fill: C("fill-static-severe-subtle"),    fg: C("foreground-static-severe-on-subtle") },
+  Alert:    { fill: C("fill-static-attention-subtle"), fg: C("foreground-static-attention-on-subtle") },
+  // Neutral has no On Subtle rung, so its foreground is Base.
+  Neutral:  { fill: C("fill-static-neutral-subtle"),   fg: C("foreground-static-neutral-base") },
+  // Info is the BRAND blue in this component, not the Info tone.
+  Info:     { fill: C("fill-static-brand-subtle"),     fg: C("foreground-static-brand-on-subtle") },
+};
+
+/**
+ * @param {string} name  Material Symbols ligature, Figma's `IconInstance` swap.
+ * @param {"Small"|"Medium"|"Large"} size
+ * @param {keyof DISPLAY_ICON_COLORS} color  Figma's Color axis.
+ * @param {string} label  Omit for a decorative icon, which is the common case:
+ *                        a display icon almost always sits beside a heading
+ *                        that already says what it means.
+ */
+export function DisplayIcon({
+  name,
+  size = "Small",
+  color = "Accent",
+  fill = 1,
+  label,
+  className = "",
+  style,
+  ...rest
+}) {
+  const s = DISPLAY_ICON_SIZES[size] || DISPLAY_ICON_SIZES.Small;
+  const tone = DISPLAY_ICON_COLORS[color] || DISPLAY_ICON_COLORS.Accent;
+  return (
+    <span
+      className={`pw-display-icon ${className}`}
+      data-size={size}
+      data-color={color}
+      style={{
+        display: "inline-flex", alignItems: "center", justifyContent: "center",
+        width: s.box, height: s.box, flexShrink: 0,
+        /* r=8 ON EVERY VARIANT, a rounded square. This drew a full circle, which
+           is a different shape: Figma's Container corner radius is 8 at all
+           three sizes, and only the Featured icon's Light outline type is round. */
+        borderRadius: L.radius,
+        background: tone.fill, color: tone.fg, ...style,
+      }}
+      {...rest}
+    >
+      <Icon name={name} size={s.glyph} fill={fill} label={label} />
+    </span>
+  );
+}
+
+export default DisplayIcon;

package/components/icon/featured-icon.jsx

@@ -0,0 +1,162 @@
+/**
+ * FeaturedIcon: the large icon badge a KPI tile puts above its number.
+ *
+ * WHY THIS EXISTS. The KPI Tiles set nests a FOREIGN component here: `Featured
+ * icon` 40003806:3550, a remote library component from Untitled UI, the same
+ * source as the `↳ Select` page in CLAUDE.md §8.1. Eighty-four variants of it,
+ * ten instances inside a Pathway component, none of them ours and none of them
+ * mappable from this repo because a Code Connect mapping publishes into the
+ * file that owns the component.
+ *
+ * THE FOREIGN COMPONENT WAS ALREADY USING PATHWAY'S COLOURS, just not bound to
+ * them. Every one of the seven raw hexes in the four variants the KPI Tile uses
+ * matches an existing Pathway semantic token EXACTLY, distance 0 in RGB:
+ *
+ *   #dff6e2  Fill/Static/Positive/Subtle
+ *   #dcd9ef  Fill/Static/Info/Subtle
+ *   #353063  Foreground/Static/Info/On Subtle
+ *   #ffffff  Fill/Surface/Elevated
+ *   #e6e2dc  Stroke/Static/Neutral/Base
+ *   #313131  Foreground/Static/Neutral/Base
+ *   #001f00  Foreground/Static/Positive/On Strong
+ *
+ * So nothing here is a redesign. It is the same drawing on the tokens it was
+ * already the colour of.
+ *
+ * MEASURED, from the four variants the KPI Tile actually nests:
+ *
+ *   Type=Light outline   r=28, so a circle
+ *     lg  48x48, glyph 24
+ *     fill and stroke are THE SAME HEX at sw=8, so the ring is invisible and
+ *     the shape is a flat tinted circle. Reproduced as a solid circle, because
+ *     an 8px stroke in the fill's own colour is decoration that draws nothing.
+ *
+ *   Type=Modern          r=8, a rounded square. NOT tone-coloured:
+ *     lg  48x48, glyph 24
+ *     md  40x40, glyph 20
+ *     Fill/Surface/Elevated, 1px Stroke/Static/Neutral/Base, inside align,
+ *     plus a shadow. Its glyph is Foreground/Static/Neutral/Base.
+ *
+ * ONE DEPARTURE AND ONE GAP, both deliberate:
+ *
+ *   - The Positive glyph takes `On Subtle` (#0d351b) rather than the `On
+ *     Strong` (#001f00) the foreign component used. On Strong is the
+ *     foreground for a SOLID fill and this glyph sits on a Subtle one, so the
+ *     exact-hex match would have been a pairing violation. On Subtle measures
+ *     11.94:1 on that tint against On Strong's 15.4:1, so both clear AAA and
+ *     the difference is invisible at 24px. This also makes Positive consistent
+ *     with the Info variant, which was already an exact match AND the correct
+ *     pairing.
+ *
+ *   - Figma's Modern shadow is `0 1 2 rgba(10,13,18,0.05)` plus two inner
+ *     shadows. Pathway's smallest elevation token is `--elevation-widget`,
+ *     `0 2px 8px -2px`, so there is no exact match and the inner shadows have
+ *     no token at all. Rather than invent one, this uses the nearest existing
+ *     token and the gap is recorded in the spec. The inner shadows are dropped:
+ *     they are an Untitled UI flourish, not a Pathway treatment.
+ */
+import React from "react";
+import { Icon } from "./icon.jsx";
+
+const C = (n) => `var(--semantic-color-${n})`;
+const U = (n) => `var(--semantic-layout-units-${n})`;
+
+export const FEATURED_ICON_SIZES = {
+  md: { box: 40, glyph: 20 },
+  lg: { box: 48, glyph: 24 },
+};
+
+/**
+ * The tones, on the same pairing every Pathway tone group guarantees: a Subtle
+ * fill with its On Subtle foreground. Matched to DisplayIcon's table so the two
+ * cannot disagree, including that `Accent` is amethyst (Info) and `Info` is
+ * brand, which is the file's own history.
+ */
+export const FEATURED_ICON_COLORS = {
+  Accent:   { fill: C("fill-static-info-subtle"),      fg: C("foreground-static-info-on-subtle") },
+  Positive: { fill: C("fill-static-positive-subtle"),  fg: C("foreground-static-positive-on-subtle") },
+  Negative: { fill: C("fill-static-negative-subtle"),  fg: C("foreground-static-negative-on-subtle") },
+  Danger:   { fill: C("fill-static-severe-subtle"),    fg: C("foreground-static-severe-on-subtle") },
+  Alert:    { fill: C("fill-static-attention-subtle"), fg: C("foreground-static-attention-on-subtle") },
+  Neutral:  { fill: C("fill-static-neutral-subtle"),   fg: C("foreground-static-neutral-base") },
+  Info:     { fill: C("fill-static-brand-subtle"),     fg: C("foreground-static-brand-on-subtle") },
+};
+
+export const FEATURED_ICON_TYPES = ["outline", "modern"];
+
+export const T = {
+  chipFill:   C("fill-surface-elevated"),
+  chipBorder: C("stroke-static-neutral-base"),
+  chipGlyph:  C("foreground-static-neutral-base"),
+};
+
+export const L = {
+  // Light outline is r=28 on a 48 box, which is past half the width, so it is a
+  // circle rather than a specific radius. CornerRadius/Full says that.
+  circle: U("cornerradius-full"),
+  // Modern is r=8 at both sizes.
+  chip:   U("cornerradius-base"),
+  border: "var(--semantic-layout-units-borderwidth-base)",
+};
+
+/**
+ * @param {string} name  Material Symbols ligature.
+ * @param {"md"|"lg"} size  Figma's Size axis, the two values the design uses.
+ * @param {"outline"|"modern"} type  Figma's Type axis. `outline` is the tinted
+ *                       circle and takes `color`; `modern` is the white chip
+ *                       and ignores it, because it is not tone-coloured.
+ * @param {keyof FEATURED_ICON_COLORS} color  Only meaningful for `outline`.
+ * @param {string} glyphColor  Override the glyph colour with a semantic token's
+ *                       var(). Needed because Figma is NOT consistent here: the
+ *                       KPI Tile's Icon 01 binds its glyph to
+ *                       Foreground/Static/Positive/On STRONG while Icon 02 binds
+ *                       Info/On Subtle, for the same Light outline type. Rather
+ *                       than silently normalise one of them, the component
+ *                       defaults to the correct On Subtle pairing and the call
+ *                       site can say when the file differs.
+ * @param {string} label  Omit for a decorative badge, which is the common case:
+ *                       a featured icon sits above a heading that already says
+ *                       what it means.
+ */
+export function FeaturedIcon({
+  name = "trending_up",
+  size = "lg",
+  type = "outline",
+  color = "Positive",
+  glyphColor,
+  fill = 1,
+  label,
+  className = "",
+  style,
+  ...rest
+}) {
+  const s = FEATURED_ICON_SIZES[size] || FEATURED_ICON_SIZES.lg;
+  const modern = type === "modern";
+  const tone = FEATURED_ICON_COLORS[color] || FEATURED_ICON_COLORS.Positive;
+
+  return (
+    <span
+      className={`pw-featured-icon ${className}`}
+      data-size={size}
+      data-type={type}
+      data-color={modern ? "Neutral" : color}
+      style={{
+        display: "inline-flex", alignItems: "center", justifyContent: "center",
+        width: s.box, height: s.box, flexShrink: 0, boxSizing: "border-box",
+        borderRadius: modern ? L.chip : L.circle,
+        background: modern ? T.chipFill : tone.fill,
+        color: glyphColor || (modern ? T.chipGlyph : tone.fg),
+        // Modern's 1px border is INSIDE-aligned in Figma, which border-box
+        // reproduces: the chip stays 48, the border eats into it.
+        border: modern ? `${L.border} solid ${T.chipBorder}` : "none",
+        boxShadow: modern ? "var(--elevation-widget)" : "none",
+        ...style,
+      }}
+      {...rest}
+    >
+      <Icon name={name} size={s.glyph} fill={fill} label={label} />
+    </span>
+  );
+}
+
+export default FeaturedIcon;

package/components/icon/icon.jsx

@@ -0,0 +1,154 @@
+/**
+ * Icon: the one place Pathway renders an icon.
+ *
+ * WHY THIS FILE EXISTS. Every Figma icon component in this system had NO code
+ * to point at. Code Connect listed them with no path and no link, so a
+ * developer opening an icon in Figma was told nothing about how to render one.
+ * The repo was part of the reason: six components each carried their OWN
+ * private `Icon` or `Glyph` helper (top-nav, search, org-switcher, dashboard,
+ * kpi-tile, plus the sidenav's inline spans), all doing the same thing
+ * slightly differently, and none of them importable. There was nothing to
+ * link BECAUSE there was no shared module.
+ *
+ * WHAT A PATHWAY ICON ACTUALLY IS, since this is the question that keeps
+ * coming up. It is not an SVG file and there is no per-icon asset to fetch.
+ * It is one variable font, Material Symbols Rounded, and an icon is its NAME
+ * written as text inside an element that has the font applied. The browser's
+ * ligature substitution turns the text `arrow_forward` into the arrow glyph.
+ * So:
+ *
+ *   the font       Material Symbols Rounded, from Google Fonts
+ *   the stylesheet https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded
+ *                    :opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200
+ *   the catalogue  https://fonts.google.com/icons  (set Style = Rounded)
+ *   the source     https://github.com/google/material-design-icons
+ *   one icon       <span class="material-symbols-rounded">arrow_forward</span>
+ *
+ * The name you write is the folder name in that repo and the name shown in
+ * that catalogue. Nothing is imported per icon, which is the whole appeal: the
+ * font carries every glyph, so adding an icon costs nothing.
+ *
+ * THE FOUR AXES are variable-font axes, not separate fonts:
+ *
+ *   FILL  0 outlined, 1 solid. READ IT FROM FIGMA PER COMPONENT, never assume.
+ *         SideNav is FILL 1 throughout; the Widget header is FILL 0.
+ *   wght  400 everywhere in Pathway.
+ *   GRAD  0 everywhere in Pathway.
+ *   opsz  matched to the font size, which is what keeps the stroke weight even
+ *         across sizes. A 16px icon at opsz 20 is visibly lighter than it
+ *         should be, and that defect shipped once in the SideNav rail.
+ *
+ * SIZE IS THE FRAME, NEVER THE VECTOR. Figma nests a wrapper (24), an icon
+ * frame (16) and the drawn vector (~12), because the Material grid has about
+ * 2px of built-in padding. `size` here is the FRAME, so `size={16}` reproduces
+ * Figma's 16 and lands the visible glyph near 12. Passing the vector's 12
+ * ships an icon a third too small. See docs/design-system-spec.md §7.2.
+ */
+import React from "react";
+
+/** The stylesheet every surface that renders an icon must load. */
+export const MATERIAL_SYMBOLS_HREF =
+  "https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded" +
+  ":opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200";
+
+/** Where the names come from, for anyone looking for one. */
+export const ICON_SOURCES = {
+  catalogue: "https://fonts.google.com/icons",
+  repo: "https://github.com/google/material-design-icons",
+  webSymbols: "https://github.com/google/material-design-icons/tree/master/symbols/web",
+};
+
+/** Pathway's fixed axis values. Only FILL and opsz ever vary. */
+export const AXES = { wght: 400, GRAD: 0 };
+
+/**
+ * The per-size table from docs/design-system-spec.md §7.2. `wrapper` is the
+ * container Figma draws around the frame, and is the touch or alignment box
+ * rather than anything the glyph itself occupies.
+ */
+export const SIZES = {
+  L: { frame: 18, wrapper: 26 },
+  M: { frame: 16, wrapper: 24 },
+  S: { frame: 14, wrapper: 20 },
+};
+
+/**
+ * @param {string} name   The Material Symbols ligature, e.g. "arrow_forward".
+ *                        Same string as the folder name in Google's repo.
+ * @param {number|"L"|"M"|"S"} size  The FRAME size. A letter resolves through
+ *                        SIZES; a number is used as-is. Default M, 16.
+ * @param {0|1} fill      FILL axis. Read it from Figma; never assume.
+ * @param {string} color  Any CSS colour. Pass a semantic token's var(), never
+ *                        a hex. Omit to inherit, which is usually right: an
+ *                        icon beside a label should take the label's colour.
+ * @param {string} label  An accessible name. Omit for a decorative icon and it
+ *                        is hidden from assistive tech, which is the default
+ *                        because most icons sit beside their own text.
+ */
+export function Icon({
+  name,
+  size = "M",
+  fill = 0,
+  color,
+  label,
+  className = "",
+  style,
+  ...rest
+}) {
+  const frame = typeof size === "number" ? size : (SIZES[size] || SIZES.M).frame;
+  return (
+    <span
+      className={`material-symbols-rounded ${className}`}
+      // Decorative by default. A label makes it an image with a name.
+      role={label ? "img" : undefined}
+      aria-label={label || undefined}
+      aria-hidden={label ? undefined : true}
+      style={{
+        fontSize: frame,
+        lineHeight: 1,
+        display: "block",
+        flexShrink: 0,
+        color,
+        // opsz TRACKS THE FONT SIZE. Pinning it to 20 while the glyph renders
+        // at 16 makes the stroke too light, which is what went wrong in the
+        // collapsed SideNav rail.
+        fontVariationSettings: `'FILL' ${fill}, 'wght' ${AXES.wght}, 'GRAD' ${AXES.GRAD}, 'opsz' ${frame}`,
+        ...style,
+      }}
+      {...rest}
+    >
+      {name}
+    </span>
+  );
+}
+
+/**
+ * The icon in its Figma wrapper: the alignment box, not the glyph.
+ *
+ * Use it when you are reproducing a Figma frame that nests
+ * `Container.LeadingIcon` around `Icon.Leading`. A bare `<Icon>` is the frame
+ * alone and is what most layouts want.
+ */
+export function IconBox({ name, size = "M", fill = 0, color, label, style, ...rest }) {
+  const s = typeof size === "string" ? (SIZES[size] || SIZES.M) : { frame: size, wrapper: size + 8 };
+  return (
+    <span style={{
+      display: "inline-flex", alignItems: "center", justifyContent: "center",
+      width: s.wrapper, height: s.wrapper, flexShrink: 0, ...style,
+    }} {...rest}>
+      <Icon name={name} size={s.frame} fill={fill} color={color} label={label} />
+    </span>
+  );
+}
+
+/**
+ * Drop the stylesheet in. Storybook and the HTML demos load it in their own
+ * head; this is for a consumer who renders an Icon without having done that,
+ * because a missing font shows the LIGATURE NAME as text rather than failing,
+ * and "arrow_forward" in the middle of a button is a confusing bug to chase.
+ */
+export const IconFont = () => (
+  <link rel="stylesheet" href={MATERIAL_SYMBOLS_HREF} />
+);
+
+export default Icon;