@gtivr4/a1-design-system-react 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtivr4/a1-design-system-react",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "React components for the A1 token-driven design system.",
   "type": "module",
   "main": "./src/index.js",

package/src/color-scheme.css

@@ -783,3 +783,41 @@ html.a1-theme-dark.a1-theme-accessible {
   --semantic-color-border-subtle:  var(--base-color-neutral-500);
   --semantic-color-border-default: var(--base-color-neutral-400);
 }
+
+/* ─── Fresh theme — gradient on body, surface tokens on html ─────────────────
+   Light mode: mint gradient. Dark mode: dark teal gradient.
+   CSS custom properties stay on html so they inherit throughout the document.
+   background-image targets body so it doesn't paint behind the html scroll area. */
+
+html.a1-theme-fresh body {
+  background-image: linear-gradient(207.43deg, #D7FFF8 0%, #CDF5EE 57.44%);
+  background-attachment: fixed;
+  background-color: var(--semantic-color-surface-page);
+}
+
+/* Dark mode surface tokens — stay on html for inheritance (0,2,1 beats html.a1-theme-dark 0,1,1) */
+html.a1-theme-fresh.a1-theme-dark,
+html.a1-theme-dark.a1-theme-fresh {
+  --semantic-color-surface-page:   #03453A;
+  --semantic-color-surface-panel:  #046756;
+  --semantic-color-surface-raised: #057868;
+}
+
+html.a1-theme-fresh.a1-theme-dark body,
+html.a1-theme-dark.a1-theme-fresh body {
+  background-image: linear-gradient(207.43deg, #046756 0%, #03453A 57.44%);
+  background-color: #03453A;
+}
+
+@media (prefers-color-scheme: dark) {
+  html.a1-theme-fresh {
+    --semantic-color-surface-page:   #03453A;
+    --semantic-color-surface-panel:  #046756;
+    --semantic-color-surface-raised: #057868;
+  }
+
+  html.a1-theme-fresh body {
+    background-image: linear-gradient(207.43deg, #046756 0%, #03453A 57.44%);
+    background-color: #03453A;
+  }
+}

package/src/components/button-container/ButtonContainer.d.ts

@@ -5,6 +5,8 @@ export interface ButtonContainerProps extends React.HTMLAttributes<HTMLDivElemen
   align?: "start" | "center" | "end";
   /** Default size passed to child Button elements that do not set their own size. */
   size?: "sm" | "md" | "lg";
+  /** When true, Button children stretch to fill remaining row space while IconButton children keep their natural square size. Always renders as a row — does not collapse to column on narrow containers. Default: false */
+  fillButtons?: boolean;
   children?: React.ReactNode;
 }
 

package/src/components/button-container/ButtonContainer.jsx

@@ -20,6 +20,7 @@ function applyButtonSize(children, size) {
 export function ButtonContainer({
   align = "start",
   size,
+  fillButtons = false,
   className = "",
   children,
   ...props
@@ -30,6 +31,7 @@ export function ButtonContainer({
     "a1-button-container",
     `a1-button-container--${resolvedAlign}`,
     resolvedSize && `a1-button-container--${resolvedSize}`,
+    fillButtons && "a1-button-container--fill-buttons",
     className
   ]
     .filter(Boolean)

package/src/components/button-container/button-container.css

@@ -54,3 +54,23 @@
 .a1-button-container--lg .a1-button-container__inner {
   gap: var(--base-spacing-16) var(--base-spacing-24);
 }
+
+/* ── Fill buttons ────────────────────────────────────────────────────────── */
+/* Buttons stretch to fill remaining space; icon buttons stay their natural
+   square size. Always row — does not collapse to column on narrow containers. */
+
+.a1-button-container--fill-buttons .a1-button-container__inner {
+  flex-direction: row;
+  flex-wrap: nowrap;
+  align-items: center;
+}
+
+.a1-button-container--fill-buttons .a1-button-container__inner > .a1-button {
+  flex: 1 1 0;
+  min-inline-size: 0;
+  width: auto;
+}
+
+.a1-button-container--fill-buttons .a1-button-container__inner > .a1-icon-button {
+  flex: 0 0 auto;
+}

package/src/components/data-table/DataTable.d.ts

@@ -78,6 +78,12 @@ export interface DataTableProps extends React.HTMLAttributes<HTMLDivElement> {
   emptyTitle?: string;
   emptyDescription?: string;
   emptyIcon?: string;
+  /**
+   * Custom full-width no-padding rows inserted into the table body.
+   * Each entry specifies `content` (ReactNode) and an optional `afterRow` index (0-based,
+   * default 0 = before all data rows). Multiple entries with the same `afterRow` stack in order.
+   */
+  notices?: Array<{ content: React.ReactNode; afterRow?: number }>;
 }
 
 export declare function DataTable(props: DataTableProps): React.ReactElement;

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

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from "react";
+import { Fragment, useEffect, useRef, useState } from "react";
 import { Button } from "../button/Button.jsx";
 import { SelectField } from "../field/SelectField.jsx";
 import { Icon } from "../icon/Icon.jsx";
@@ -197,6 +197,7 @@ export function DataTable({
   zebra = false,
   scrollable = false,
   caption,
+  notices = [],
   page,
   defaultPage = 1,
   pageSize,
@@ -661,39 +662,54 @@ export function DataTable({
               </tr>
             </thead>
             <tbody>
-              {visibleRowEntries.map(({ row, index: rowIndex, id: rowId, supportsRowClickSelection }) => {
-                const isSelected = selectedRowIdSet.has(rowId);
-                return (
-                  <tr
-                    key={rowId}
-                    data-selected={isSelected ? "true" : undefined}
-                    data-selectable-row={supportsRowClickSelection ? "true" : undefined}
-                    onClick={(event) => handleRowClick(rowId, supportsRowClickSelection, event)}
-                  >
-                    {selectable && (
-                      <td
-                        className="a1-data-table__select-cell"
-                        data-label="Select"
-                      >
-                        <SelectionCheckbox
-                          checked={isSelected}
-                          label={`Select row ${rowIndex + 1}`}
-                          onChange={(checked) => toggleRowSelected(rowId, checked)}
-                        />
-                      </td>
-                    )}
-                    {columns.map((col) => (
-                      <td
-                        key={col.key}
-                        data-label={col.label}
-                        data-align={getAlign(col)}
+              {(() => {
+                const noticeColSpan = selectable ? columns.length + 1 : columns.length;
+                const noticeMap = {};
+                notices.forEach(({ content, afterRow = 0 }) => {
+                  if (!noticeMap[afterRow]) noticeMap[afterRow] = [];
+                  noticeMap[afterRow].push(content);
+                });
+                return visibleRowEntries.map(({ row, index: rowIndex, id: rowId, supportsRowClickSelection }, i) => {
+                  const isSelected = selectedRowIdSet.has(rowId);
+                  const noticesHere = noticeMap[i] ?? [];
+                  return (
+                    <Fragment key={rowId}>
+                      {noticesHere.map((content, j) => (
+                        <tr key={j} className="a1-data-table__notice-row">
+                          <td className="a1-data-table__notice-cell" colSpan={noticeColSpan}>{content}</td>
+                        </tr>
+                      ))}
+                      <tr
+                        data-selected={isSelected ? "true" : undefined}
+                        data-selectable-row={supportsRowClickSelection ? "true" : undefined}
+                        onClick={(event) => handleRowClick(rowId, supportsRowClickSelection, event)}
                       >
-                        {renderCell(col, row[col.key])}
-                      </td>
-                    ))}
-                  </tr>
-                );
-              })}
+                        {selectable && (
+                          <td
+                            className="a1-data-table__select-cell"
+                            data-label="Select"
+                          >
+                            <SelectionCheckbox
+                              checked={isSelected}
+                              label={`Select row ${rowIndex + 1}`}
+                              onChange={(checked) => toggleRowSelected(rowId, checked)}
+                            />
+                          </td>
+                        )}
+                        {columns.map((col) => (
+                          <td
+                            key={col.key}
+                            data-label={col.label}
+                            data-align={getAlign(col)}
+                          >
+                            {renderCell(col, row[col.key])}
+                          </td>
+                        ))}
+                      </tr>
+                    </Fragment>
+                  );
+                });
+              })()}
             </tbody>
           </table>
         )}

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

@@ -201,6 +201,17 @@
   border-bottom: none;
 }
 
+/* ── Notice row (no-padding custom content spanning all columns) ─────────── */
+
+/* Double-class specificity (0-2-0) beats density td rules (0-1-1) */
+.a1-data-table .a1-data-table__notice-cell {
+  padding: 0;
+}
+
+.a1-data-table--zebra tbody .a1-data-table__notice-row td {
+  background: transparent;
+}
+
 /* ── Zebra striping ──────────────────────────────────────────────────────── */
 
 .a1-data-table--zebra tbody tr:nth-child(even) td {

package/src/components/field/NumberField.d.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+import { TextFieldProps } from "./TextField.d.ts";
+
+export interface NumberFieldProps extends Omit<TextFieldProps, "type"> {
+  /** Non-editable prefix rendered before the value at full input size and color (e.g. "$"). */
+  prefix?: string;
+  /** Non-editable unit label rendered after the value at smaller, muted size (e.g. "lbs", "km", "ft"). */
+  unit?: string;
+}
+
+export declare function NumberField(props: NumberFieldProps): React.ReactElement;

package/src/components/field/NumberField.jsx

@@ -1,11 +1,63 @@
+import { useRef, useCallback, useState, forwardRef } from "react";
 import { TextField } from "./TextField.jsx";
 
-export function NumberField({ className = "", ...props }) {
+export const NumberField = forwardRef(function NumberField(
+  { unit, prefix, className = "", onChange, value, defaultValue, style, ...props },
+  forwardedRef,
+) {
+  const localRef = useRef(null);
+
+  const mergedRef = useCallback((el) => {
+    localRef.current = el;
+    if (typeof forwardedRef === "function") forwardedRef(el);
+    else if (forwardedRef) forwardedRef.current = el;
+  }, [forwardedRef]);
+
+  const [uncontrolledLength, setUncontrolledLength] = useState(
+    () => Math.max(String(defaultValue ?? "").length, 1),
+  );
+
+  const inputLength = value !== undefined
+    ? Math.max(String(value).length || 1, 1)
+    : uncontrolledLength;
+
+  function handleChange(e) {
+    if (value === undefined) {
+      setUncontrolledLength(Math.max(e.target.value.length || 1, 1));
+    }
+    onChange?.(e);
+  }
+
+  const overlay = (prefix || unit) ? (
+    <>
+      {prefix && <span className="a1-field__prefix" aria-hidden="true">{prefix}</span>}
+      {unit && (
+        <span
+          className="a1-field__unit"
+          aria-hidden="true"
+          onClick={() => localRef.current?.focus()}
+        >
+          {unit}
+        </span>
+      )}
+    </>
+  ) : null;
+
   return (
     <TextField
+      ref={mergedRef}
       type="number"
-      className={className}
+      className={[
+        className,
+        prefix && "a1-field--has-prefix",
+        unit   && "a1-field--has-unit",
+      ].filter(Boolean).join(" ")}
+      inputOverlay={overlay}
+      onChange={unit ? handleChange : onChange}
+      value={value}
+      defaultValue={defaultValue}
+      style={unit ? { "--a1-field-number-width": `${inputLength}ch`, ...style } : style}
       {...props}
     />
   );
-}
+});

package/src/components/field/field.css

@@ -279,6 +279,137 @@
   width: auto;
 }
 
+/* ─── Number field prefix (e.g. "$") and unit (e.g. "lbs") ─────────────────── */
+/* The control container becomes the visual field; the input becomes borderless.
+   Prefix is reordered before the input via CSS order. Unit follows the input
+   as a compact flex child so it sits immediately beside the value. */
+
+.a1-field--has-prefix .a1-field__control,
+.a1-field--has-unit .a1-field__control {
+  display: flex;
+  align-items: center;
+  background: var(--a1-field-background);
+  border: var(--component-field-border-width) solid var(--a1-field-border-color);
+  border-radius: var(--a1-field-border-radius);
+  transition:
+    border-color var(--semantic-motion-duration-fast),
+    background var(--semantic-motion-duration-fast);
+  overflow: hidden;
+}
+
+/* Input loses its own border/background; container provides them */
+.a1-field--has-prefix .a1-field__input,
+.a1-field--has-unit .a1-field__input {
+  border: none;
+  background: transparent;
+  border-radius: 0;
+  outline: none;
+  /* suppress the native hover/active border — container handles it */
+  box-shadow: none;
+}
+
+.a1-field--has-prefix .a1-field__input:hover,
+.a1-field--has-unit .a1-field__input:hover,
+.a1-field--has-prefix .a1-field__input:active,
+.a1-field--has-unit .a1-field__input:active {
+  background: transparent;
+  border-color: transparent;
+}
+
+/* Focus ring moves to container */
+.a1-field--has-prefix .a1-field__control:focus-within,
+.a1-field--has-unit .a1-field__control:focus-within {
+  outline: var(--a1-field-focus-ring-width) solid var(--a1-field-focus-ring-color);
+  outline-offset: var(--a1-field-focus-ring-offset);
+  border-color: var(--semantic-color-action-background);
+}
+
+/* Hover on container */
+.a1-field--has-prefix .a1-field__control:hover:not(:focus-within),
+.a1-field--has-unit .a1-field__control:hover:not(:focus-within) {
+  background: var(--a1-field-hover-background);
+  border-color: var(--a1-field-hover-border-color);
+}
+
+/* Disabled: suppress hover on container */
+.a1-field--disabled.a1-field--has-prefix .a1-field__control,
+.a1-field--disabled.a1-field--has-unit .a1-field__control {
+  background: var(--semantic-color-surface-raised);
+  border-color: var(--semantic-color-border-subtle);
+  cursor: not-allowed;
+}
+
+/* Error: container */
+.a1-field--error.a1-field--has-prefix .a1-field__control,
+.a1-field--error.a1-field--has-unit .a1-field__control {
+  border-color: var(--semantic-color-status-error-border);
+  border-left-width: var(--a1-field-accent-border-width);
+  border-left-color: var(--semantic-color-status-error-background);
+}
+
+.a1-field--error.a1-field--has-prefix .a1-field__control:focus-within,
+.a1-field--error.a1-field--has-unit .a1-field__control:focus-within {
+  border-color: var(--semantic-color-status-error-background);
+  outline-color: var(--semantic-color-status-error-background);
+}
+
+/* Required: container */
+.a1-field--required.a1-field--has-prefix .a1-field__control,
+.a1-field--required.a1-field--has-unit .a1-field__control {
+  border-color: var(--semantic-color-status-info-border);
+  border-left-width: var(--a1-field-accent-border-width);
+  border-left-color: var(--semantic-color-status-info-background);
+}
+
+/* ─── Prefix: same size/color as value, visually before the input ────────── */
+
+.a1-field__prefix {
+  order: -1;  /* renders after input in DOM; flex order places it first */
+  flex-shrink: 0;
+  padding-inline-start: var(--a1-field-padding-inline);
+  padding-inline-end: var(--base-spacing-2);
+  font-family: var(--component-paragraph-font-family);
+  font-size: var(--a1-field-font-size);
+  font-weight: var(--base-font-weight-regular);
+  color: var(--semantic-color-text-default);
+  line-height: 1;
+  pointer-events: none;
+  user-select: none;
+}
+
+.a1-field--has-prefix .a1-field__input {
+  flex: 1;
+  min-width: 0;
+  padding-inline-start: 0;
+}
+
+/* ─── Unit: smaller/muted, immediately after the value ───────────────────── */
+/* Unit fills remaining space so clicks anywhere right of the value focus the input. */
+
+.a1-field__unit {
+  flex: 1;
+  padding-inline-start: var(--base-spacing-4);
+  padding-inline-end: var(--a1-field-padding-inline);
+  font-family: var(--component-paragraph-font-family);
+  font-size: var(--semantic-font-size-body-xs);
+  color: var(--semantic-color-text-muted);
+  line-height: 1;
+  pointer-events: auto;
+  user-select: none;
+  cursor: text;
+}
+
+/* Input shrinks to its value so the unit sits right beside it.
+   JS sets --a1-field-number-width per keystroke. field-sizing: content
+   auto-sizes in Chrome 123+ / Firefox 128+ regardless. */
+.a1-field--has-unit .a1-field__input {
+  flex: 0 0 auto;
+  width: calc(var(--a1-field-number-width, 4ch) + var(--a1-field-padding-inline));
+  min-width: 2ch;
+  padding-inline-end: 0;
+  field-sizing: content;
+}
+
 /* ─── Mask overlay (PhoneField, ZipField) ─────────────────────────────────── */
 
 .a1-field__mask-overlay {

package/src/components/icon-button/IconButton.d.ts

@@ -7,6 +7,8 @@ export interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonEl
   label: string;
   /** Visual style. Default: "tertiary" */
   variant?: "tertiary" | "secondary" | "destructive" | "success";
+  /** Button size. "lg" matches Button's large touch target (3.5rem) and icon size, suitable for pairing with large Buttons. Default: "md" */
+  size?: "md" | "lg";
   disabled?: boolean;
   onClick?: React.MouseEventHandler<HTMLButtonElement>;
 }

package/src/components/icon-button/IconButton.jsx

@@ -2,20 +2,24 @@ import "./icon-button.css";
 import { Icon } from "../icon/Icon.jsx";
 
 const variants = ["tertiary", "secondary", "destructive", "success"];
+const sizes = ["md", "lg"];
 
 export function IconButton({
   icon,
   label,
   variant = "tertiary",
+  size,
   disabled = false,
   onClick,
   className = "",
   ...props
 }) {
   const resolvedVariant = variants.includes(variant) ? variant : "tertiary";
+  const resolvedSize = sizes.includes(size) ? size : null;
   const classes = [
     "a1-icon-button",
     `a1-icon-button--${resolvedVariant}`,
+    resolvedSize === "lg" && "a1-icon-button--large",
     className,
   ].filter(Boolean).join(" ");
 

package/src/components/icon-button/icon-button.css

@@ -8,7 +8,7 @@
   align-items: center;
   justify-content: center;
   flex-shrink: 0;
-  height: var(--component-icon-button-size);
+  height: var(--a1-icon-button-size, var(--component-icon-button-size));
   aspect-ratio: 1;
   padding: 0;
   border-radius: var(--component-icon-button-border-radius);
@@ -33,8 +33,17 @@
 }
 
 .a1-icon-button .a1-icon {
-  font-size: var(--component-icon-button-icon-size);
-  --a1-icon-opsz: var(--component-icon-button-icon-optical-size);
+  font-size: var(--a1-icon-button-icon-size, var(--component-icon-button-icon-size));
+  --a1-icon-opsz: var(--a1-icon-button-icon-opsz, var(--component-icon-button-icon-optical-size));
+}
+
+/* ── Size: large ─────────────────────────────────────────────────────────── */
+/* Touch target matches Button lg (3.5rem); icon matches Button lg's icon. */
+
+.a1-icon-button--large {
+  --a1-icon-button-size:      var(--component-button-large-height);
+  --a1-icon-button-icon-size: var(--component-button-icon-size);
+  --a1-icon-button-icon-opsz: var(--component-button-icon-optical-size);
 }
 
 .a1-icon-button:focus-visible {

package/src/components/section/Section.d.ts

@@ -14,7 +14,7 @@ export interface SectionProps extends React.HTMLAttributes<HTMLElement> {
   /** Background surface treatment */
   surface?: "page" | "panel" | "raised";
   /** Gap between direct children */
-  gap?: "xs" | "sm" | "md" | "lg";
+  gap?: "xs" | "sm" | "md" | "lg" | "xl";
   /** Gradient overlay colour */
   gradient?: "accent" | "highlight" | "info" | "success" | "warn";
   /** Gradient origin. Default: "center" */

package/src/components/section/Section.jsx

@@ -4,7 +4,7 @@ import "./section.css";
 
 const VALID_PADDING = ["lg", "md", "sm", "xs", "none"];
 const VALID_SURFACES = ["page", "panel", "raised"];
-const VALID_GAPS = ["xs", "sm", "md", "lg"];
+const VALID_GAPS = ["xs", "sm", "md", "lg", "xl"];
 const VALID_GRADIENTS = ["accent", "highlight", "info", "success", "warn"];
 const VALID_GRADIENT_POSITIONS = [
   "top",

package/src/components/section/section.css

@@ -68,7 +68,8 @@
 .a1-section--gap-xs,
 .a1-section--gap-sm,
 .a1-section--gap-md,
-.a1-section--gap-lg {
+.a1-section--gap-lg,
+.a1-section--gap-xl {
   display: grid;
   justify-items: var(--a1-section-justify-items);
 }
@@ -77,6 +78,7 @@
 .a1-section--gap-sm { gap: var(--semantic-spacing-gap-sm); }
 .a1-section--gap-md { gap: var(--semantic-spacing-gap-md); }
 .a1-section--gap-lg { gap: var(--semantic-spacing-gap-lg); }
+.a1-section--gap-xl { gap: var(--semantic-spacing-gap-xl); }
 
 /* ── Height ────────────────────────────────────────────────────────────────── */
 

package/src/components/stack/Stack.d.ts

@@ -4,7 +4,7 @@ type Breakpoints = "xs" | "sm" | "md" | "lg" | "xl";
 type Direction = "column" | "column-reverse" | "row" | "row-reverse";
 type Justify = "start" | "center" | "end" | "between" | "around" | "evenly";
 type Align = "stretch" | "start" | "center" | "end" | "baseline";
-type SemanticGap = "xs" | "sm" | "md" | "lg";
+type SemanticGap = "xs" | "sm" | "md" | "lg" | "xl";
 type SpacingToken = 1 | 2 | 4 | 6 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 64 | 96 | 128;
 
 export interface StackProps extends React.HTMLAttributes<HTMLElement> {

package/src/components/stack/Stack.jsx

@@ -4,7 +4,7 @@ import { resolveSpacing } from "../structure-utils.js";
 const directions = ["column", "column-reverse", "row", "row-reverse"];
 const alignments = ["stretch", "start", "center", "end", "baseline"];
 const justifications = ["start", "center", "end", "between", "around", "evenly"];
-const semanticGaps = ["xs", "sm", "md", "lg"];
+const semanticGaps = ["xs", "sm", "md", "lg", "xl"];
 const breakpoints = ["xs", "sm", "md", "lg", "xl"];
 
 function resolveGap(gap) {

package/src/components/step-tracker/StepTracker.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+
+export interface StepTrackerProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Total number of steps. */
+  steps: number;
+  /** 1-indexed position of the current step. Default: 1. */
+  currentStep?: number;
+  /**
+   * Horizontal alignment of the tracker within its container.
+   * "left" | "center" | "right" — groups items together.
+   * "full" — active pill expands to fill remaining space.
+   * Default: "left".
+   */
+  align?: "left" | "center" | "right" | "full";
+}
+
+export declare function StepTracker(props: StepTrackerProps): React.ReactElement;

package/src/components/step-tracker/StepTracker.jsx

@@ -0,0 +1,41 @@
+import "./step-tracker.css";
+
+const ALIGNS = ["left", "center", "right", "full"];
+
+export function StepTracker({
+  steps,
+  currentStep = 1,
+  align = "left",
+  className = "",
+  ...props
+}) {
+  const resolvedAlign = ALIGNS.includes(align) ? align : "left";
+  const total = Math.max(1, steps);
+  const current = Math.min(total, Math.max(1, currentStep));
+
+  const classes = [
+    "a1-step-tracker",
+    resolvedAlign !== "left" && `a1-step-tracker--${resolvedAlign}`,
+    className,
+  ].filter(Boolean).join(" ");
+
+  return (
+    <div
+      className={classes}
+      role="img"
+      aria-label={`Step ${current} of ${total}`}
+      {...props}
+    >
+      {Array.from({ length: total }, (_, i) => (
+        <div
+          key={i}
+          className={[
+            "a1-step-tracker__step",
+            i + 1 === current && "a1-step-tracker__step--current",
+          ].filter(Boolean).join(" ")}
+          aria-hidden="true"
+        />
+      ))}
+    </div>
+  );
+}

package/src/components/step-tracker/step-tracker.css

@@ -0,0 +1,37 @@
+.a1-step-tracker {
+  --a1-st-dot-size:     var(--component-step-tracker-dot-size);
+  --a1-st-active-width: var(--component-step-tracker-active-width);
+  --a1-st-dot-color:    var(--semantic-color-border-strong);
+  --a1-st-active-color: var(--semantic-color-text-default);
+  --a1-st-gap:          var(--component-step-tracker-gap);
+
+  display: flex;
+  align-items: center;
+  gap: var(--a1-st-gap);
+}
+
+/* ─── Alignment ───────────────────────────────────────────────────────────── */
+
+.a1-step-tracker--center { justify-content: center; }
+.a1-step-tracker--right  { justify-content: flex-end; }
+
+/* full: dots stay fixed, active pill expands to fill remaining space */
+.a1-step-tracker--full .a1-step-tracker__step--current {
+  flex: 1;
+}
+
+/* ─── Step ────────────────────────────────────────────────────────────────── */
+
+.a1-step-tracker__step {
+  block-size: var(--a1-st-dot-size);
+  inline-size: var(--a1-st-dot-size);
+  border-radius: 9999px;
+  background: var(--a1-st-dot-color);
+  flex-shrink: 0;
+  transition: inline-size var(--semantic-motion-duration-fast, 150ms) var(--semantic-motion-easing-standard, ease);
+}
+
+.a1-step-tracker__step--current {
+  inline-size: var(--a1-st-active-width);
+  background: var(--a1-st-active-color);
+}

package/src/index.js

@@ -7,6 +7,7 @@ export { Notification } from "./components/notification/Notification.jsx";
 export { Snackbar } from "./components/snackbar/Snackbar.jsx";
 export { StatusBar } from "./components/status-bar/StatusBar.jsx";
 export { CircularProgress } from "./components/circular-progress/CircularProgress.jsx";
+export { StepTracker } from "./components/step-tracker/StepTracker.jsx";
 export { Bleed } from "./components/bleed/Bleed.jsx";
 export { IconButton } from "./components/icon-button/IconButton.jsx";
 export { Button } from "./components/button/Button.jsx";export { ButtonContainer } from "./components/button-container/ButtonContainer.jsx";

package/src/themes.css

@@ -295,10 +295,10 @@ html.a1-theme-catlympics.a1-theme-light, html.a1-theme-light.a1-theme-catlympics
 
 /* ────────────────────────────────────────────────────────────
    Fresh
-   A crisp, airy theme with sky-blue accents, Nunito body text (ExtraBold headings), Baskerville display typography, and a cool mint gradient background. Apply [data-theme='fresh'] to <html>.
+   A crisp, airy theme with sky-blue accents, Nunito body text (ExtraBold headings), Baskerville display typography, and a cool mint gradient background. Apply class="a1-theme-fresh" to <html>.
    ──────────────────────────────────────────────────────────── */
 
-[data-theme='fresh'] {
+html.a1-theme-fresh {
   --base-color-accent-0: #FAFCFF;
   --base-color-accent-50: #ECF3FE;
   --base-color-accent-100: #D8E8FD;
@@ -432,8 +432,6 @@ html.a1-theme-catlympics.a1-theme-light, html.a1-theme-light.a1-theme-catlympics
   --component-paragraph-font-weight: var(--theme-a1-fresh-font-weight-body);
   --component-heading-font-weight-heading: var(--theme-a1-fresh-font-weight-heading);
   --component-heading-font-weight-display: var(--theme-a1-fresh-font-weight-display);
-  background-image: linear-gradient(207.43deg, #D7FFF8 0%, #CDF5EE 57.44%);
-  background-attachment: fixed;
 }
 
 

package/src/tokens.css

@@ -234,6 +234,7 @@
   --semantic-spacing-gap-sm: 0.75rem;
   --semantic-spacing-gap-md: 1rem;
   --semantic-spacing-gap-lg: 1.5rem;
+  --semantic-spacing-gap-xl: 2.5rem;
   --semantic-font-size-body-xs: 0.75rem;
   --semantic-font-size-body-sm: 0.875rem;
   --semantic-font-size-body-md: 1rem;
@@ -679,6 +680,11 @@
   --component-status-bar-fill-background: #7c3aed;
   --component-status-bar-label-gap: 0.5rem;
   --component-status-bar-indeterminate-duration: 1400ms;
+  --component-step-tracker-dot-size: 0.5rem;
+  --component-step-tracker-dot-color: #64748b;
+  --component-step-tracker-active-width: 2rem;
+  --component-step-tracker-active-color: #060b14;
+  --component-step-tracker-gap: 0.375rem;
   --component-switch-track-width: 2.5rem;
   --component-switch-track-height: 1.375rem;
   --component-switch-thumb-size: 1rem;