@gtivr4/a1-design-system-react 0.6.2 → 0.8.0

package/guidelines/Guidelines.md

@@ -158,7 +158,6 @@ Every named export from `@gtivr4/a1-design-system-react` — verified against `s
 | `MessageEmptyState` | Empty state block; `scale="page\|section\|card"`, `icon`, `title`, `description`, `action` |
 | `Notification` | Badge wrapper; `count`, `label`, `dot`, `variant`, `position`, `max` |
 | `Snackbar` | Toast notification; `open`, `onClose`, `message`, `action` |
-| `SystemBanner` | Full-width system alert; `status`, `title`, `message`, `onDismiss` |
 
 ### Overlay
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtivr4/a1-design-system-react",
-  "version": "0.6.2",
+  "version": "0.8.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/circular-progress/CircularProgress.d.ts

@@ -14,7 +14,7 @@ export interface CircularProgressProps {
    * Circle diameter. xs renders the smallest ring (no inner content — children
    * are placed inline after the ring instead). Default: "md"
    */
-  size?: "xs" | "sm" | "md" | "lg";
+  size?: "xs" | "sm" | "md" | "lg" | "xl";
   /**
    * Shows a continuously rotating arc instead of a value-based fill.
    * Removes aria-valuenow so assistive technology announces an indeterminate

package/src/components/circular-progress/CircularProgress.jsx

@@ -1,6 +1,6 @@
 import "./circular-progress.css";
 
-const SIZES = ["xs", "sm", "md", "lg"];
+const SIZES = ["xs", "sm", "md", "lg", "xl"];
 
 // SVG uses a 100×100 viewBox with a 10-unit stroke so the ring scales
 // proportionally when the container size changes via CSS.

package/src/components/circular-progress/circular-progress.css

@@ -17,6 +17,7 @@
 .a1-circular-progress--sm { --a1-cp-size: var(--component-circular-progress-sm-size); }
 /* md is the default — no modifier needed */
 .a1-circular-progress--lg { --a1-cp-size: var(--component-circular-progress-lg-size); }
+.a1-circular-progress--xl { --a1-cp-size: var(--component-circular-progress-xl-size); }
 
 /* ─── Ring (SVG + optional inner content) ────────────────────────────────────── */
 

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(--a1-field-font-size);
+  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/components/top-header/TopHeader.jsx

@@ -8,6 +8,28 @@ import "./top-header.css";
 
 // ── Helpers ────────────────────────────────────────────────────────────────────
 
+// Breakpoint min-widths that match the system breakpoint tokens.
+const BP_QUERIES = {
+  sm: "(min-width: 481px)",
+  md: "(min-width: 641px)",
+  lg: "(min-width: 1025px)",
+  xl: "(min-width: 1441px)",
+};
+
+// Resolve a scalar or responsive { xs?, sm?, md?, lg?, xl? } navIconPosition
+// value to a boolean indicating whether icon-above mode is active right now.
+function resolveIconAbove(prop) {
+  if (!prop || typeof prop === "string") return prop === "above";
+  // Cascade xs → sm → md → lg → xl, carrying forward the last explicit value.
+  let resolved = prop.xs ?? "start";
+  for (const [bp, query] of Object.entries(BP_QUERIES)) {
+    if (typeof window !== "undefined" && window.matchMedia(query).matches) {
+      resolved = prop[bp] ?? resolved;
+    }
+  }
+  return resolved === "above";
+}
+
 // Split a flat items array into sections separated by { divider: true } markers.
 function splitIntoSections(items) {
   const sections = [];
@@ -211,7 +233,7 @@ function NavMenuItem({ item, onClose }) {
 
 // ── NavItem (desktop) ──────────────────────────────────────────────────────────
 
-function NavItem({ item, openId, onOpen }) {
+function NavItem({ item, openId, onOpen, iconAbove }) {
   const triggerRef = useRef(null);
   const hasSubmenu = item.items?.length > 0;
   const hasRoute = !!item.href;
@@ -234,7 +256,32 @@ function NavItem({ item, openId, onOpen }) {
     .filter(Boolean)
     .join(" ");
 
-  const linkContent = (
+  // In icon-above mode the chevron is nested inside the label span so it sits
+  // inline with the text in the column layout, rather than appearing as a
+  // third stacked row below the icon and label.
+  const linkContent = iconAbove ? (
+    <>
+      {item.icon && (
+        <Icon
+          name={item.icon}
+          className="a1-top-header__nav-link-icon"
+          aria-hidden="true"
+        />
+      )}
+      {!isIconOnly && (
+        <span className="a1-top-header__nav-link-label">
+          {item.label}
+          {hasSubmenu && (
+            <Icon
+              name="expand_more"
+              className="a1-top-header__nav-chevron"
+              aria-hidden="true"
+            />
+          )}
+        </span>
+      )}
+    </>
+  ) : (
     <>
       {item.icon && (
         <Icon
@@ -247,14 +294,13 @@ function NavItem({ item, openId, onOpen }) {
     </>
   );
 
-  const submenuChevron = (
-    hasSubmenu && (
-      <Icon
-        name="expand_more"
-        className="a1-top-header__nav-chevron"
-        aria-hidden="true"
-      />
-    )
+  // In icon-above mode the chevron lives inside linkContent (see above).
+  const submenuChevron = !iconAbove && hasSubmenu && (
+    <Icon
+      name="expand_more"
+      className="a1-top-header__nav-chevron"
+      aria-hidden="true"
+    />
   );
 
   const submenuButtonContent = (
@@ -540,8 +586,10 @@ export function TopHeader({
   navItems = [],
   actions = [],
   loginButton,
+  navIconPosition = "start",
   className = "",
 }) {
+  const [iconAbove, setIconAbove] = useState(() => resolveIconAbove(navIconPosition));
   const [openSubmenu, setOpenSubmenu] = useState(null);
   const [openAction, setOpenAction] = useState(null);
   const [mobileNavOpen, setMobileNavOpen] = useState(false);
@@ -569,10 +617,29 @@ export function TopHeader({
     return () => desktopQuery.removeListener(closeAtDesktop);
   }, [mobileNavOpen]);
 
+  // Re-resolve iconAbove whenever navIconPosition or the viewport changes.
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return undefined;
+
+    const update = () => setIconAbove(resolveIconAbove(navIconPosition));
+    const listeners = Object.values(BP_QUERIES).map((q) => {
+      const mq = window.matchMedia(q);
+      mq.addEventListener("change", update);
+      return [mq, update];
+    });
+    update();
+    return () => listeners.forEach(([mq, fn]) => mq.removeEventListener("change", fn));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [JSON.stringify(navIconPosition)]);
+
   return (
     <>
       <header
-        className={["a1-top-header", className].filter(Boolean).join(" ")}
+        className={[
+          "a1-top-header",
+          iconAbove && "a1-top-header--nav-icon-above",
+          className,
+        ].filter(Boolean).join(" ")}
       >
         <button
           type="button"
@@ -599,6 +666,7 @@ export function TopHeader({
                   item={item}
                   openId={openSubmenu}
                   onOpen={setOpenSubmenu}
+                  iconAbove={iconAbove}
                 />
               ))}
             </ul>

package/src/components/top-header/top-header.css

@@ -320,6 +320,38 @@
   margin-inline-start: var(--base-spacing-4);
 }
 
+/* ── Icon-above nav layout ────────────────────────────────────────────────── */
+
+/* Nav links become a column: icon above, label (+ optional chevron) below. */
+.a1-top-header--nav-icon-above .a1-top-header__nav-link {
+  flex-direction: column;
+  align-items: center;
+  gap: var(--base-spacing-2);
+  padding-block: var(--base-spacing-8);
+  padding-inline: var(--base-spacing-8);
+  font-size: var(--semantic-font-size-body-xs);
+}
+
+/* Icon slightly larger so it reads clearly at the top of each item. */
+.a1-top-header--nav-icon-above .a1-top-header__nav-link-icon {
+  font-size: var(--semantic-font-size-heading-sm);
+}
+
+/* Label row: inline-flex so the small chevron sits beside the text. */
+.a1-top-header--nav-icon-above .a1-top-header__nav-link-label {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--base-spacing-2);
+  line-height: 1;
+}
+
+/* Chevron in this context is a small inline decoration next to the label. */
+.a1-top-header--nav-icon-above .a1-top-header__nav-link-label .a1-top-header__nav-chevron {
+  font-size: var(--semantic-font-size-body-sm);
+  margin-inline-start: 0;
+  transition: transform var(--semantic-motion-duration-fast) var(--semantic-motion-easing-standard);
+}
+
 /* ── Responsive ──────────────────────────────────────────────────────────── */
 
 @media (max-width: 768px) {
@@ -334,4 +366,23 @@
   .a1-top-header__nav {
     display: none;
   }
+
+  /* Icon-above mode: nav is always visible; hamburger is not needed. */
+  .a1-top-header--nav-icon-above .a1-top-header__hamburger {
+    display: none;
+  }
+
+  .a1-top-header--nav-icon-above .a1-top-header__nav {
+    display: flex;
+  }
+
+  /* Allow horizontal scrolling if items overflow on very small screens. */
+  .a1-top-header--nav-icon-above .a1-top-header__nav-list {
+    overflow-x: auto;
+    scrollbar-width: none;
+  }
+
+  .a1-top-header--nav-icon-above .a1-top-header__nav-list::-webkit-scrollbar {
+    display: none;
+  }
 }

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

@@ -130,6 +130,7 @@
   --base-spacing-64: 4rem;
   --base-spacing-96: 6rem;
   --base-spacing-128: 8rem;
+  --base-spacing-192: 12rem;
   --base-spacing-neg-4: -0.25rem;
   --base-spacing-neg-8: -0.5rem;
   --base-spacing-neg-12: -0.75rem;
@@ -234,6 +235,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;
@@ -413,6 +415,7 @@
   --component-circular-progress-sm-size: 4rem;
   --component-circular-progress-md-size: 6rem;
   --component-circular-progress-lg-size: 8rem;
+  --component-circular-progress-xl-size: 12rem;
   --component-circular-progress-track-color: #e1e8f3;
   --component-circular-progress-fill-color: #7c3aed;
   --component-circular-progress-gap: 0.5rem;
@@ -679,6 +682,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;

package/src/components/system-banner/SystemBanner.d.ts

@@ -1,17 +0,0 @@
-import * as React from "react";
-
-export interface SystemBannerProps {
-  /** Semantic status colour. Default: "neutral" */
-  status?: "neutral" | "info" | "success" | "warn" | "error";
-  /** Bold title text */
-  title?: string;
-  /** Override the default status icon with any Material Symbols name */
-  icon?: string;
-  /** Action element rendered at the trailing end */
-  action?: React.ReactNode;
-  /** Called when the dismiss button is clicked. Omit to hide the dismiss button. */
-  onDismiss?: () => void;
-  children?: React.ReactNode;
-}
-
-export declare function SystemBanner(props: SystemBannerProps): React.ReactElement;

package/src/components/system-banner/SystemBanner.jsx

@@ -1,57 +0,0 @@
-import "./system-banner.css";
-import { Icon } from "../icon/Icon.jsx";
-import { IconButton } from "../icon-button/IconButton.jsx";
-
-const STATUS_ICONS = {
-  neutral: "campaign",
-  info:    "info",
-  success: "check_circle",
-  warn:    "warning",
-  error:   "error",
-};
-
-const STATUSES = ["neutral", "info", "success", "warn", "error"];
-
-export function SystemBanner({
-  status = "neutral",
-  title,
-  icon,
-  action,
-  onDismiss,
-  children,
-}) {
-  const resolvedStatus = STATUSES.includes(status) ? status : "neutral";
-  const resolvedIcon = icon ?? STATUS_ICONS[resolvedStatus];
-
-  return (
-    <div
-      className={`a1-system-banner a1-system-banner--${resolvedStatus}`}
-      role="alert"
-      aria-live="polite"
-    >
-      <div className="a1-system-banner__inner">
-        <span className="a1-system-banner__icon" aria-hidden="true">
-          <Icon name={resolvedIcon} />
-        </span>
-
-        <div className="a1-system-banner__content">
-          {title    && <span className="a1-system-banner__title">{title}</span>}
-          {children && <span className="a1-system-banner__body">{children}</span>}
-        </div>
-
-        {action && (
-          <div className="a1-system-banner__action">{action}</div>
-        )}
-
-        {onDismiss && (
-          <IconButton
-            icon="close"
-            label="Dismiss"
-            onClick={onDismiss}
-            className="a1-system-banner__dismiss"
-          />
-        )}
-      </div>
-    </div>
-  );
-}

package/src/components/system-banner/system-banner.css

@@ -1,118 +0,0 @@
-/* ─── System Banner ────────────────────────────────────────────────────────── */
-
-.a1-system-banner {
-  --a1-sysbanner-bg: var(--semantic-color-surface-inverse);
-  --a1-sysbanner-fg: var(--semantic-color-text-inverse);
-
-  background: var(--a1-sysbanner-bg);
-  color: var(--a1-sysbanner-fg);
-  width: 100%;
-}
-
-.a1-system-banner--info    { --a1-sysbanner-bg: var(--semantic-color-status-info-background); }
-.a1-system-banner--success { --a1-sysbanner-bg: var(--semantic-color-status-success-background); }
-.a1-system-banner--warn    { --a1-sysbanner-bg: var(--semantic-color-status-warn-background); }
-.a1-system-banner--error   { --a1-sysbanner-bg: var(--semantic-color-status-error-background); }
-
-/* ─── Inner layout ─────────────────────────────────────────────────────────── */
-
-.a1-system-banner__inner {
-  display: flex;
-  align-items: center;
-  flex-wrap: wrap;
-  gap: var(--base-spacing-8) var(--base-spacing-12);
-  max-width: var(--component-message-banner-system-max-width);
-  margin-inline: auto;
-  padding-block: var(--base-spacing-12);
-  padding-inline: var(--base-spacing-24);
-}
-
-/* ─── Icon ─────────────────────────────────────────────────────────────────── */
-
-.a1-system-banner__icon {
-  flex-shrink: 0;
-  display: flex;
-  font-size: var(--component-message-banner-icon-size);
-  line-height: 1;
-  --a1-icon-opsz: var(--component-message-banner-icon-optical-size);
-}
-
-/* ─── Content (title + body inline) ───────────────────────────────────────── */
-
-.a1-system-banner__content {
-  flex: 1;
-  min-width: 0;
-  display: flex;
-  flex-wrap: wrap;
-  align-items: baseline;
-  gap: 0 var(--base-spacing-8);
-  font-family: var(--component-paragraph-font-family);
-  font-size: var(--semantic-font-size-body-sm);
-  line-height: var(--semantic-font-line-height-body);
-}
-
-.a1-system-banner__title {
-  font-weight: var(--component-message-banner-title-font-weight);
-  color: var(--a1-sysbanner-fg);
-}
-
-.a1-system-banner__body {
-  font-weight: var(--semantic-font-weight-body);
-  color: var(--a1-sysbanner-fg);
-  opacity: 0.85;
-}
-
-/* ─── Action ───────────────────────────────────────────────────────────────── */
-
-.a1-system-banner__action {
-  flex-shrink: 0;
-}
-
-/* ─── Dismiss ──────────────────────────────────────────────────────────────── */
-
-.a1-system-banner__dismiss {
-  flex-shrink: 0;
-  margin-inline-start: var(--base-spacing-4);
-}
-
-/* ─── Link override on solid bg ────────────────────────────────────────────── */
-
-.a1-system-banner .a1-link {
-  color: var(--a1-sysbanner-fg);
-}
-
-.a1-system-banner .a1-link:hover {
-  color: color-mix(in srgb, var(--a1-sysbanner-fg) 80%, transparent);
-}
-
-.a1-system-banner .a1-link:active {
-  color: color-mix(in srgb, var(--a1-sysbanner-fg) 65%, transparent);
-}
-
-/* ─── Tertiary button override on solid bg ─────────────────────────────────── */
-
-.a1-system-banner .a1-button--tertiary {
-  --a1-button-foreground:         var(--a1-sysbanner-fg);
-  --a1-button-foreground-hover:   var(--a1-sysbanner-fg);
-  --a1-button-foreground-pressed: var(--a1-sysbanner-fg);
-  --a1-button-background:         transparent;
-  --a1-button-background-hover:   color-mix(in srgb, var(--a1-sysbanner-fg) 12%, transparent);
-  --a1-button-background-pressed: color-mix(in srgb, var(--a1-sysbanner-fg) 20%, transparent);
-  --a1-button-border:             color-mix(in srgb, var(--a1-sysbanner-fg) 40%, transparent);
-  --a1-button-border-hover:       color-mix(in srgb, var(--a1-sysbanner-fg) 60%, transparent);
-  --a1-button-border-pressed:     color-mix(in srgb, var(--a1-sysbanner-fg) 75%, transparent);
-}
-
-/* ─── Icon button (dismiss) override on solid bg ───────────────────────────── */
-
-.a1-system-banner .a1-icon-button {
-  --a1-icon-button-foreground:         var(--a1-sysbanner-fg);
-  --a1-icon-button-foreground-hover:   var(--a1-sysbanner-fg);
-  --a1-icon-button-foreground-pressed: var(--a1-sysbanner-fg);
-  --a1-icon-button-background:         transparent;
-  --a1-icon-button-background-hover:   color-mix(in srgb, var(--a1-sysbanner-fg) 12%, transparent);
-  --a1-icon-button-background-pressed: color-mix(in srgb, var(--a1-sysbanner-fg) 20%, transparent);
-  --a1-icon-button-border:             transparent;
-  --a1-icon-button-border-hover:       transparent;
-  --a1-icon-button-border-pressed:     transparent;
-}