@gtivr4/a1-design-system-react 0.15.0 → 0.18.0

package/src/components/bottom-sheet/bottom-sheet.css

@@ -0,0 +1,113 @@
+/* BottomSheet — fixed bottom panel, no scrim, separation via shadow. Drag handle
+   resizes between detents; content scrolls internally. xs + sm only. */
+
+.a1-bottom-sheet {
+  position: fixed;
+  inset-inline: 0;
+  inset-block-end: 0;
+  z-index: var(--component-bottom-sheet-z-index, 200);
+
+  display: flex;
+  flex-direction: column;
+  block-size: var(--a1-bottom-sheet-height, var(--component-bottom-sheet-header-height, 3.5rem));
+  max-block-size: 96dvh;
+  min-block-size: var(--component-bottom-sheet-header-height, 3.5rem);
+
+  background: var(--component-bottom-sheet-background, var(--semantic-color-surface-card));
+  border-start-start-radius: var(--component-bottom-sheet-border-radius, var(--base-radius-lg));
+  border-start-end-radius: var(--component-bottom-sheet-border-radius, var(--base-radius-lg));
+  /* Strong 1px hairline along the top edge (and up the rounded corners). */
+  border-block-start: var(--component-divider-size-sm) solid var(--semantic-color-border-strong);
+  border-inline: var(--component-divider-size-sm) solid var(--semantic-color-border-strong);
+  /* Upward shadow only — separates the sheet from page content without a scrim. */
+  box-shadow:
+    0 calc(-1 * var(--base-spacing-2)) var(--base-spacing-8)
+      color-mix(in srgb, var(--semantic-color-text-default) 12%, transparent),
+    var(--semantic-shadow-xl);
+
+  padding-block-end: env(safe-area-inset-bottom, 0px);
+  transition: block-size var(--semantic-motion-duration-fast) var(--semantic-motion-easing-standard);
+}
+
+.a1-bottom-sheet--dragging {
+  transition: none;
+}
+
+/* ── Header (drag handle + title) ──────────────────────────────────────────── */
+
+.a1-bottom-sheet__header {
+  flex: none;
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: var(--base-spacing-8);
+  padding: var(--base-spacing-8) var(--component-bottom-sheet-padding, var(--base-spacing-16));
+  min-block-size: var(--component-bottom-sheet-header-height, 3.5rem);
+  cursor: grab;
+  touch-action: none;
+  user-select: none;
+}
+
+.a1-bottom-sheet--dragging .a1-bottom-sheet__header {
+  cursor: grabbing;
+}
+
+.a1-bottom-sheet__handle {
+  align-self: center;
+  flex: none;
+  inline-size: var(--component-bottom-sheet-handle-width, var(--base-spacing-40));
+  block-size: var(--component-bottom-sheet-handle-height, var(--base-spacing-4));
+  padding: 0;
+  border: none;
+  border-radius: 999px;
+  background: var(--semantic-color-border-strong);
+  cursor: grab;
+}
+
+.a1-bottom-sheet__handle:focus-visible {
+  outline: var(--component-button-focus-ring-width, 2px) solid var(--semantic-color-text-accent);
+  outline-offset: var(--base-spacing-4);
+}
+
+.a1-bottom-sheet__title {
+  font-size: var(--semantic-font-size-body-md);
+  font-weight: var(--semantic-font-weight-heading);
+  color: var(--semantic-color-text-default);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* ── Scrollable content ────────────────────────────────────────────────────── */
+
+.a1-bottom-sheet__content {
+  flex: 1 1 auto;
+  min-block-size: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  -webkit-overflow-scrolling: touch;
+  padding:
+    0
+    var(--component-bottom-sheet-padding, var(--base-spacing-16))
+    var(--base-spacing-16);
+}
+
+/* When collapsed the content area has no height — it's clipped to the header. */
+.a1-bottom-sheet--collapsed .a1-bottom-sheet__content {
+  overflow: hidden;
+}
+
+/* ── Spacer: reserves the collapsed footprint in document flow ─────────────── */
+
+.a1-bottom-sheet__spacer {
+  block-size: var(--component-bottom-sheet-header-height, 3.5rem);
+}
+
+/* ── xs + sm only ──────────────────────────────────────────────────────────── */
+
+@media (--bp-md-up) {
+  .a1-bottom-sheet,
+  .a1-bottom-sheet__spacer {
+    display: none;
+  }
+}

package/src/components/code/Code.jsx

@@ -77,6 +77,7 @@ export function Code({
 
   const copyLabel = useLabel("code.copyCode", "Copy code");
   const copiedLabel = useLabel("code.copied", "Copied");
+  const editLabel = useLabel("code.editCode", "Edit code");
   const textToCopy = useMemo(
     () => copyText || (editable ? editableValue : textFromChildren(Children.toArray(children))),
     [children, copyText, editable, editableValue],
@@ -113,6 +114,10 @@ export function Code({
   ]
     .filter(Boolean)
     .join(" ");
+  const editableProps = {
+    ...props,
+    ...(!props["aria-label"] && !props["aria-labelledby"] ? { "aria-label": editLabel } : null),
+  };
 
   if (!shouldRenderBlock) {
     return (
@@ -145,7 +150,7 @@ export function Code({
           value={editableValue}
           onChange={handleTextareaChange}
           spellCheck={false}
-          {...props}
+          {...editableProps}
         />
       ) : (
         <pre className="a1-code-block__pre">

package/src/components/data-table/DataTable.jsx

@@ -12,7 +12,7 @@ import "./data-table.css";
  * columns: Array<{
  *   key: string,
  *   label: string,
- *   type?: "text" | "number" | "currency" | "date" | "badge" | "avatar" | "link" | "actions",
+ *   type?: "text" | "number" | "currency" | "date" | "badge" | "avatar" | "image" | "link" | "actions",
  *   align?: "start" | "center" | "end",
  *   width?: string,
  *   sortable?: boolean,
@@ -29,6 +29,7 @@ import "./data-table.css";
 // Estimated minimum content width per column type at a "neutral" padding level
 const COL_BASE_WIDTH = {
   avatar:   160,  // avatar circle + name text
+  image:     72,  // small thumbnail
   date:     110,  // "Jan 12, 2026"
   actions:  120,  // one or two compact buttons
   link:     120,  // linked text
@@ -455,6 +456,15 @@ export function DataTable({
         );
       }
 
+      case "image": {
+        // value is an image URL, or `{ src, alt }`.
+        const src = value && typeof value === "object" ? value.src : value;
+        const alt = value && typeof value === "object" ? (value.alt ?? "") : "";
+        return src
+          ? <img className="a1-data-table__thumb" src={src} alt={alt} loading="lazy" />
+          : <span className="a1-data-table__thumb a1-data-table__thumb--empty" aria-hidden="true" />;
+      }
+
       case "badge": {
         const status = col.statusMap?.[value] ?? "neutral";
         const compact = activeDensity === "compact";

package/src/components/data-table/data-table.css

@@ -286,6 +286,25 @@
   font-size: var(--component-notification-font-size);
 }
 
+/* Image (thumbnail) cell type. */
+.a1-data-table__thumb {
+  display: block;
+  inline-size: 2.5rem;
+  block-size: 2.5rem;
+  object-fit: cover;
+  border-radius: var(--base-radius-sm);
+  background: var(--semantic-color-surface-raised);
+}
+
+.a1-data-table--compact .a1-data-table__thumb {
+  inline-size: 2rem;
+  block-size: 2rem;
+}
+
+.a1-data-table__thumb--empty {
+  border: var(--component-divider-size-sm) dashed var(--semantic-color-border-subtle);
+}
+
 .a1-data-table__actions {
   display: inline-flex;
   align-items: center;

package/src/components/figure/Figure.d.ts

@@ -54,6 +54,13 @@ export interface FigureProps extends React.HTMLAttributes<HTMLElement> {
    * Pass `true` for symmetric bleed or a numeric spacing token for inline-only.
    */
   bleed?: boolean | SpacingToken;
+  /**
+   * Show a tokenized placeholder pattern when `src` is missing or fails to load
+   * (e.g. a deleted image). Default: true. Set false to render the bare `<img>`.
+   */
+  placeholder?: boolean;
+  /** Material Symbols icon shown in the placeholder. Default: "image" */
+  placeholderIcon?: string;
   /** Extra class names on the `<figure>` element */
   className?: string;
   /** Extra class names on the `<img>` element */

package/src/components/figure/Figure.jsx

@@ -1,6 +1,7 @@
 import "./figure.css";
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { Bleed } from "../bleed/Bleed.jsx";
+import { Icon } from "../icon/Icon.jsx";
 
 function isCropRect(rect) {
   return (
@@ -35,6 +36,8 @@ export function Figure({
   marginTop,
   marginBottom,
   bleed,
+  placeholder = true,
+  placeholderIcon = "image",
   className = "",
   imgClassName = "",
   style,
@@ -46,6 +49,12 @@ export function Figure({
   const cropped = isCropRect(cropRect);
   const [naturalRatio, setNaturalRatio] = useState(null);
 
+  // Show a tokenized placeholder pattern when there's no source or it fails to
+  // load (e.g. a deleted library image). Reset the error flag when src changes.
+  const [errored, setErrored] = useState(false);
+  useEffect(() => { setErrored(false); }, [src]);
+  const showPlaceholder = placeholder && (!src || errored);
+
   const classes = [
     "a1-figure",
     radius != null && rounded.includes(radius) && `a1-figure--rounded-${radius}`,
@@ -70,6 +79,7 @@ export function Figure({
       alt={alt}
       className={["a1-figure__img", imgClassName].filter(Boolean).join(" ")}
       style={imgStyle}
+      onError={() => setErrored(true)}
       onLoad={cropped ? (e) => {
         const { naturalWidth, naturalHeight } = e.currentTarget;
         if (naturalWidth && naturalHeight) setNaturalRatio(naturalWidth / naturalHeight);
@@ -77,7 +87,18 @@ export function Figure({
     />
   );
 
-  const media = cropped ? (
+  const placeholderEl = (
+    <div
+      className={["a1-figure__img", "a1-figure__placeholder", imgClassName].filter(Boolean).join(" ")}
+      style={imgStyle}
+      role="img"
+      aria-label={alt || undefined}
+    >
+      <Icon name={placeholderIcon} className="a1-figure__placeholder-icon" aria-hidden="true" />
+    </div>
+  );
+
+  const media = showPlaceholder ? placeholderEl : cropped ? (
     <div
       className="a1-figure__crop"
       style={{

package/src/components/figure/figure.css

@@ -167,3 +167,28 @@
 .a1-figure--caption-center .a1-figure__caption {
   text-align: center;
 }
+
+/* ─── Placeholder ─────────────────────────────────────────────────────────────
+   Shown when the image is missing or fails to load: a tokenized diagonal-stripe
+   pattern with a centered icon. Shares .a1-figure__img sizing, so aspect-ratio
+   and size variants apply; a 4/3 fallback box is used when no ratio is set. */
+.a1-figure__placeholder {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  aspect-ratio: 4 / 3;
+  background-color: var(--semantic-color-surface-raised);
+  background-image: repeating-linear-gradient(
+    45deg,
+    var(--semantic-color-border-subtle) 0,
+    var(--semantic-color-border-subtle) 1px,
+    transparent 1px,
+    transparent 10px
+  );
+  color: var(--semantic-color-text-muted);
+}
+
+.a1-figure__placeholder-icon {
+  font-size: var(--base-spacing-48);
+  opacity: 0.6;
+}

package/src/components/grid/Grid.d.ts

@@ -1,7 +1,7 @@
 import * as React from "react";
 
 type Breakpoints = "xs" | "sm" | "md" | "lg" | "xl";
-type GapKey = "xs" | "sm" | "md" | "lg" | "xl" | "xxl" | 1 | 2 | 4 | 6 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 64 | 96 | 128;
+type GapKey = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "xxl" | 1 | 2 | 4 | 6 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 64 | 96 | 128;
 type ColSpan = number | "full";
 
 export interface GridProps extends React.HTMLAttributes<HTMLDivElement> {

package/src/components/grid/Grid.jsx

@@ -14,6 +14,8 @@ const breakpoints = ["xs", "sm", "md", "lg", "xl"];
 
 function resolveGap(key) {
   if (key == null) return undefined;
+  // "none" removes the gap (matches the shared resolveSpacing convention).
+  if (key === "none") return "0";
   if (gapSizes[key]) return gapSizes[key];
 
   const n = Number(key);

package/src/components/grid/grid.css

@@ -34,6 +34,7 @@
 .a1-grid--xs-3  { --a1-grid-cols: 3; }
 .a1-grid--xs-4  { --a1-grid-cols: 4; }
 .a1-grid--xs-6  { --a1-grid-cols: 6; }
+.a1-grid--xs-8  { --a1-grid-cols: 8; }
 .a1-grid--xs-12 { --a1-grid-cols: 12; }
 
 @media (--bp-sm-up) {
@@ -42,6 +43,7 @@
   .a1-grid--sm-3  { --a1-grid-cols: 3; }
   .a1-grid--sm-4  { --a1-grid-cols: 4; }
   .a1-grid--sm-6  { --a1-grid-cols: 6; }
+  .a1-grid--sm-8  { --a1-grid-cols: 8; }
   .a1-grid--sm-12 { --a1-grid-cols: 12; }
 }
 
@@ -51,6 +53,7 @@
   .a1-grid--md-3  { --a1-grid-cols: 3; }
   .a1-grid--md-4  { --a1-grid-cols: 4; }
   .a1-grid--md-6  { --a1-grid-cols: 6; }
+  .a1-grid--md-8  { --a1-grid-cols: 8; }
   .a1-grid--md-12 { --a1-grid-cols: 12; }
 }
 
@@ -60,6 +63,7 @@
   .a1-grid--lg-3  { --a1-grid-cols: 3; }
   .a1-grid--lg-4  { --a1-grid-cols: 4; }
   .a1-grid--lg-6  { --a1-grid-cols: 6; }
+  .a1-grid--lg-8  { --a1-grid-cols: 8; }
   .a1-grid--lg-12 { --a1-grid-cols: 12; }
 }
 
@@ -69,6 +73,7 @@
   .a1-grid--xl-3  { --a1-grid-cols: 3; }
   .a1-grid--xl-4  { --a1-grid-cols: 4; }
   .a1-grid--xl-6  { --a1-grid-cols: 6; }
+  .a1-grid--xl-8  { --a1-grid-cols: 8; }
   .a1-grid--xl-12 { --a1-grid-cols: 12; }
 }
 

package/src/components/page-layout/page-layout.css

@@ -117,10 +117,16 @@
   overflow-y: hidden;
 }
 
-.a1-page-layout--viewport-height .a1-page-layout__sidebar .a1-side-nav {
-  position: relative;
-  top: auto;
-  height: 100%;
+/* Only at lg+ is the sidebar persistent and in flow; pin the SideNav to fill the
+   sidebar height so its footer stays anchored. At md and below the SideNav must
+   keep its fixed-overlay behaviour (see side-nav.css) so the sidebar slot
+   collapses and the main column expands to fill the freed space. */
+@media (--bp-lg-up) {
+  .a1-page-layout--viewport-height .a1-page-layout__sidebar .a1-side-nav {
+    position: relative;
+    top: auto;
+    height: 100%;
+  }
 }
 
 .a1-page-layout--viewport-height .a1-page-layout__content {

package/src/components/page-nav/PageNav.jsx

@@ -2,6 +2,22 @@ import { useEffect, useRef, useState } from "react";
 import { Card } from "../card/Card.jsx";
 import "./page-nav.css";
 
+// Find the nearest scrollable ancestor of a node, or null when the page scrolls
+// on the document/window itself. Needed because the host may scroll a nested
+// container (e.g. a viewport-height PageLayout) rather than the window — in which
+// case window scroll never fires and the progress/active state would freeze.
+function getScrollParent(node) {
+  let el = node?.parentElement;
+  while (el && el !== document.body && el !== document.documentElement) {
+    const overflowY = getComputedStyle(el).overflowY;
+    if ((overflowY === "auto" || overflowY === "scroll") && el.scrollHeight > el.clientHeight) {
+      return el;
+    }
+    el = el.parentElement;
+  }
+  return null;
+}
+
 export function PageNav({
   sections = [],
   label = "On this page",
@@ -12,22 +28,27 @@ export function PageNav({
   const [progress, setProgress] = useState(0);
   const intersectingIds = useRef(new Set());
 
-  // Reading progress: track document scroll position
+  // Reading progress: track the scroll position of the actual scroll container
+  // (the window, or a nested scrollable ancestor like a viewport-height layout).
   useEffect(() => {
+    const scroller = getScrollParent(sections.length ? document.getElementById(sections[0].id) : null);
+    const target = scroller ?? window;
     function update() {
-      const el = document.documentElement;
+      const el = scroller ?? document.documentElement;
       const total = el.scrollHeight - el.clientHeight;
       setProgress(total > 0 ? (el.scrollTop / total) * 100 : 0);
     }
-    window.addEventListener("scroll", update, { passive: true });
+    target.addEventListener("scroll", update, { passive: true });
     update();
-    return () => window.removeEventListener("scroll", update);
-  }, []);
+    return () => target.removeEventListener("scroll", update);
+  }, [sections]);
 
-  // Active section: observe each section element entering/leaving the viewport
+  // Active section: observe each section element entering/leaving the scroll
+  // container (root = the nested scroller, or the viewport when null).
   useEffect(() => {
     if (!sections.length) return;
 
+    const scroller = getScrollParent(document.getElementById(sections[0].id));
     const observer = new IntersectionObserver(
       (entries) => {
         entries.forEach((entry) => {
@@ -43,9 +64,9 @@ export function PageNav({
         if (first) setActiveId(first.id);
       },
       // -8% top offset keeps the active section stable once it clears the
-      // header; -88% bottom offset means only the top 12% of the viewport
+      // header; -88% bottom offset means only the top 12% of the scroll area
       // is treated as "current".
-      { rootMargin: "-8% 0px -88% 0px", threshold: 0 }
+      { root: scroller ?? null, rootMargin: "-8% 0px -88% 0px", threshold: 0 }
     );
 
     sections.forEach(({ id }) => {

package/src/components/page-nav/page-nav.css

@@ -163,3 +163,16 @@
     border-color: var(--semantic-color-action-background);
   }
 }
+
+/* ── Desktop: stick within its column as the reader scrolls ────────────────── */
+/* `--a1-page-nav-top` lets a consumer offset for a sticky header (default 16px);
+   a long nav scrolls internally rather than running past the viewport. */
+@media (min-width: 769px) {
+  .a1-page-nav.a1-card {
+    position: sticky;
+    top: var(--a1-page-nav-top, var(--base-spacing-16));
+    align-self: start;
+    max-block-size: calc(100vh - var(--a1-page-nav-top, var(--base-spacing-16)) - var(--base-spacing-16));
+    overflow: hidden auto;
+  }
+}

package/src/components/paragraph/Paragraph.d.ts

@@ -17,6 +17,8 @@ export interface ParagraphProps extends React.HTMLAttributes<HTMLParagraphElemen
   textWrap?: "balance";
   /** Horizontal text alignment. "start"/"end" are logical aliases for LTR/RTL-safe alignment. */
   align?: "left" | "center" | "right" | "start" | "end";
+  /** Font weight. Omit to inherit the body default. */
+  weight?: "regular" | "medium" | "semibold" | "bold";
   children?: React.ReactNode;
 }
 

package/src/components/paragraph/Paragraph.jsx

@@ -5,6 +5,7 @@ const colors = ["default", "muted"];
 const breakpoints = ["xs", "sm", "md", "lg", "xl"];
 const textWraps = ["balance"];
 const aligns = ["left", "center", "right", "start", "end"];
+const weights = ["regular", "medium", "semibold", "bold"];
 
 function isResponsiveSize(size) {
   return size && typeof size === "object" && !Array.isArray(size);
@@ -31,6 +32,7 @@ export function Paragraph({
   color = "default",
   textWrap,
   align,
+  weight,
   className = "",
   style,
   ...props
@@ -39,6 +41,7 @@ export function Paragraph({
   const resolvedColor = colors.includes(color) ? color : "default";
   const resolvedTextWrap = textWraps.includes(textWrap) ? textWrap : null;
   const resolvedAlign = aligns.includes(align) ? align : null;
+  const resolvedWeight = weights.includes(weight) ? weight : null;
   const responsiveStyle = getResponsiveSizeStyle(size);
   const resolvedStyle = Object.keys(responsiveStyle).length
     ? { ...responsiveStyle, ...style }
@@ -50,6 +53,7 @@ export function Paragraph({
     resolvedColor !== "default" && `a1-paragraph--${resolvedColor}`,
     resolvedTextWrap && `a1-paragraph--wrap-${resolvedTextWrap}`,
     resolvedAlign && `a1-paragraph--align-${resolvedAlign}`,
+    resolvedWeight && `a1-paragraph--weight-${resolvedWeight}`,
     className
   ]
     .filter(Boolean)

package/src/components/paragraph/paragraph.css

@@ -2,7 +2,7 @@
   margin: 0;
   font-family: var(--component-paragraph-font-family);
   font-size: var(--a1-paragraph-responsive-size, var(--a1-paragraph-size));
-  font-weight: var(--component-paragraph-font-weight);
+  font-weight: var(--a1-paragraph-weight, var(--component-paragraph-font-weight));
   line-height: var(--component-paragraph-font-line-height);
   color: var(--a1-paragraph-color, var(--semantic-color-text-default));
 }
@@ -39,6 +39,11 @@
 
 .a1-paragraph--muted { --a1-paragraph-color: var(--semantic-color-text-muted); }
 
+.a1-paragraph--weight-regular  { --a1-paragraph-weight: var(--base-font-weight-regular); }
+.a1-paragraph--weight-medium   { --a1-paragraph-weight: var(--base-font-weight-medium); }
+.a1-paragraph--weight-semibold { --a1-paragraph-weight: var(--base-font-weight-semibold); }
+.a1-paragraph--weight-bold     { --a1-paragraph-weight: var(--base-font-weight-bold); }
+
 /* Text wrap */
 .a1-paragraph--wrap-balance { text-wrap: balance; }
 
@@ -48,8 +53,3 @@
 .a1-paragraph--align-right  { text-align: end;    }
 .a1-paragraph--align-start  { text-align: start;  }
 .a1-paragraph--align-end    { text-align: end;    }
-
-.a1-paragraph + .a1-paragraph,
-.a1-paragraph + .a1-heading {
-  margin-top: 1.5em;
-}

package/src/components/segmented-control/SegmentedControl.d.ts

@@ -18,6 +18,14 @@ export interface SegmentedControlProps extends React.HTMLAttributes<HTMLDivEleme
   fullWidth?: boolean;
   /** Height scale. Default: "md" */
   size?: "sm" | "md" | "lg";
+  /**
+   * Label display. `"all"` (default) shows every option's label. `"selected"`
+   * shows the label only on the selected option; the rest render icon-only
+   * (using each option's `ariaLabel`/`label` for its accessible name). Options
+   * without an icon always show their label so they never render blank.
+   * "none" hides every label (fully icon-only).
+   */
+  labelMode?: "all" | "selected" | "none";
 }
 
 export declare function SegmentedControl(props: SegmentedControlProps): React.ReactElement;

package/src/components/segmented-control/SegmentedControl.jsx

@@ -11,6 +11,7 @@ export function SegmentedControl({
   onChange,
   fullWidth = false,
   size,
+  labelMode = "all",
   ...props
 }) {
   const items = options.map(normalize);
@@ -52,8 +53,20 @@ export function SegmentedControl({
       onKeyDown={handleKeyDown}
     >
       {items.map((opt) => {
-        const iconOnly = Boolean(opt.icon) && !opt.label;
         const isSelected = value === opt.value;
+        // labelMode controls which segments show their text label:
+        //   "all" (default) — every segment.
+        //   "selected"      — only the selected segment.
+        //   "none"          — none of them (fully icon-only).
+        // An option with no icon always shows its label so it never goes blank.
+        const wantsLabel =
+          Boolean(opt.label) &&
+          (labelMode === "none"
+            ? !opt.icon
+            : labelMode === "selected"
+              ? (isSelected || !opt.icon)
+              : true);
+        const iconOnly = Boolean(opt.icon) && !wantsLabel;
 
         return (
           <button
@@ -61,7 +74,7 @@ export function SegmentedControl({
             role="radio"
             type="button"
             aria-checked={isSelected}
-            aria-label={iconOnly ? (opt.ariaLabel ?? opt.value) : undefined}
+            aria-label={iconOnly ? (opt.ariaLabel ?? opt.label ?? opt.value) : undefined}
             tabIndex={isSelected ? 0 : -1}
             className={[
               "a1-segment",
@@ -72,7 +85,7 @@ export function SegmentedControl({
             onClick={() => onChange?.(opt.value)}
           >
             {opt.icon && <Icon name={opt.icon} className="a1-segment__icon" />}
-            {opt.label}
+            {wantsLabel ? opt.label : null}
           </button>
         );
       })}

package/src/components/segmented-control/segmented.css

@@ -13,6 +13,9 @@
 
 .a1-segmented--full-width {
   display: flex;
+  /* Fill the container so the equal-width segments actually stretch — `display:
+     flex` alone leaves it content-width inside a centering flex/grid parent. */
+  inline-size: 100%;
 }
 
 /* ─── Segment button ──────────────────────────────────────────────────────── */
@@ -58,10 +61,27 @@
   font-size: var(--semantic-font-size-body-sm);
 }
 
+/* Small: tighter padding and a font size one step down from the default. */
+.a1-segmented--sm .a1-segment {
+  padding: var(--component-segmented-segment-padding-block-sm)
+           var(--component-segmented-segment-padding-inline-sm);
+  font-size: var(--semantic-font-size-body-xs);
+  /* Tighter icon↔label gap at sm. */
+  gap: var(--base-spacing-4);
+}
+
+/* Large: roomier padding and a font size one step up. */
+.a1-segmented--lg .a1-segment {
+  padding: var(--component-segmented-segment-padding-block-lg)
+           var(--component-segmented-segment-padding-inline-lg);
+  font-size: var(--semantic-font-size-body-md);
+}
+
 /* ─── Icon ────────────────────────────────────────────────────────────────── */
 
 .a1-segment__icon {
-  font-size: 1em;
+  /* One step larger than the label so the glyph reads clearly at the md/lg sizes. */
+  font-size: 1.25em;
 }
 
 /* Icon-only: match inline padding to block padding so the segment is square */
@@ -69,6 +89,16 @@
   padding-inline: var(--component-segmented-segment-padding-block);
 }
 
+/* Small: a larger icon and tighter horizontal padding per segment (so an
+   icon-only sm strip stays compact). */
+.a1-segmented--sm .a1-segment__icon {
+  font-size: 1.5em;
+}
+
+.a1-segmented--sm .a1-segment--icon-only {
+  padding-inline: var(--component-segmented-segment-padding-block-sm);
+}
+
 /* ─── Dark mode ───────────────────────────────────────────────────────────── */
 
 .a1-theme-dark .a1-segment:not([aria-checked="true"]),