@gtivr4/a1-design-system-react 0.4.0 → 0.5.0

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

@@ -0,0 +1,85 @@
+import "./circular-progress.css";
+
+const SIZES = ["xs", "sm", "md", "lg"];
+
+// SVG uses a 100×100 viewBox with a 10-unit stroke so the ring scales
+// proportionally when the container size changes via CSS.
+const VIEWBOX = 100;
+const STROKE  = 10;
+const R       = (VIEWBOX - STROKE) / 2;       // 45
+const CIRC    = 2 * Math.PI * R;              // ≈ 282.74
+const ARC     = CIRC * 0.25;                  // 25% arc for indeterminate
+
+export function CircularProgress({
+  value         = 0,
+  max           = 100,
+  size          = "md",
+  indeterminate = false,
+  children,
+  className     = "",
+  ...props
+}) {
+  const resolvedSize = SIZES.includes(size) ? size : "md";
+  const hasInner     = resolvedSize !== "xs";
+
+  const pct        = Math.min(1, Math.max(0, max > 0 ? value / max : 0));
+  const dashArray  = indeterminate ? `${ARC} ${CIRC - ARC}` : CIRC;
+  const dashOffset = indeterminate ? 0 : CIRC * (1 - pct);
+
+  const classes = [
+    "a1-circular-progress",
+    resolvedSize !== "md" && `a1-circular-progress--${resolvedSize}`,
+    indeterminate && "a1-circular-progress--indeterminate",
+    className,
+  ].filter(Boolean).join(" ");
+
+  return (
+    <div
+      className={classes}
+      role="progressbar"
+      aria-valuenow={indeterminate ? undefined : value}
+      aria-valuemin={0}
+      aria-valuemax={max}
+      {...props}
+    >
+      <div className="a1-circular-progress__ring">
+        <svg
+          className="a1-circular-progress__svg"
+          viewBox={`0 0 ${VIEWBOX} ${VIEWBOX}`}
+          aria-hidden="true"
+        >
+          <circle
+            className="a1-circular-progress__track"
+            cx={VIEWBOX / 2}
+            cy={VIEWBOX / 2}
+            r={R}
+            fill="none"
+            strokeWidth={STROKE}
+          />
+          <circle
+            className="a1-circular-progress__fill"
+            cx={VIEWBOX / 2}
+            cy={VIEWBOX / 2}
+            r={R}
+            fill="none"
+            strokeWidth={STROKE}
+            strokeDasharray={dashArray}
+            strokeDashoffset={dashOffset}
+            strokeLinecap="round"
+            transform={`rotate(-90 ${VIEWBOX / 2} ${VIEWBOX / 2})`}
+          />
+        </svg>
+        {hasInner && children && (
+          <div className="a1-circular-progress__inner" aria-hidden="true">
+            {children}
+          </div>
+        )}
+      </div>
+      {!hasInner && children && (
+        <div className="a1-circular-progress__after">
+          {children}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,104 @@
+/* ─── CircularProgress ───────────────────────────────────────────────────────── */
+
+.a1-circular-progress {
+  --a1-cp-size:    var(--component-circular-progress-md-size);
+  --a1-cp-track:   var(--component-circular-progress-track-color);
+  --a1-cp-fill:    var(--component-circular-progress-fill-color);
+  --a1-cp-gap:     var(--component-circular-progress-gap);
+
+  display: inline-flex;
+  align-items: center;
+  gap: var(--a1-cp-gap);
+}
+
+/* ─── Sizes ──────────────────────────────────────────────────────────────────── */
+
+.a1-circular-progress--xs { --a1-cp-size: var(--component-circular-progress-xs-size); }
+.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); }
+
+/* ─── Ring (SVG + optional inner content) ────────────────────────────────────── */
+
+.a1-circular-progress__ring {
+  flex-shrink: 0;
+  position: relative;
+  width:  var(--a1-cp-size);
+  height: var(--a1-cp-size);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* ─── SVG ────────────────────────────────────────────────────────────────────── */
+
+.a1-circular-progress__svg {
+  position: absolute;
+  inset: 0;
+  width:  100%;
+  height: 100%;
+  overflow: visible;
+}
+
+/* ─── Track ──────────────────────────────────────────────────────────────────── */
+
+.a1-circular-progress__track {
+  stroke: var(--a1-cp-track);
+}
+
+/* ─── Fill ───────────────────────────────────────────────────────────────────── */
+
+.a1-circular-progress__fill {
+  stroke: var(--a1-cp-fill);
+  transition: stroke-dashoffset var(--semantic-motion-duration-normal) var(--semantic-motion-easing-standard);
+}
+
+/* ─── Inner content (sm / md / lg) ──────────────────────────────────────────── */
+
+/* position: relative sits above the absolute SVG inside the flex __ring */
+.a1-circular-progress__inner {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  /* 80% keeps content within the inner edge of the 10 %-wide viewBox stroke */
+  max-width: 80%;
+  overflow: hidden;
+}
+
+/* ─── After content (xs only, rendered after the ring in DOM order) ─────────── */
+
+.a1-circular-progress__after {
+  font-family: var(--component-paragraph-font-family);
+  font-size: var(--semantic-font-size-body-sm);
+  color: var(--semantic-color-text-default);
+  line-height: var(--semantic-font-line-height-body);
+}
+
+/* ─── Indeterminate (spin) ───────────────────────────────────────────────────── */
+
+.a1-circular-progress--indeterminate .a1-circular-progress__svg {
+  animation: a1-cp-spin var(--component-circular-progress-indeterminate-duration) linear infinite;
+  transform-origin: center;
+}
+
+.a1-circular-progress--indeterminate .a1-circular-progress__fill {
+  transition: none;
+}
+
+@keyframes a1-cp-spin {
+  to { transform: rotate(360deg); }
+}
+
+/* ─── Reduced motion ─────────────────────────────────────────────────────────── */
+
+@media (prefers-reduced-motion: reduce) {
+  .a1-circular-progress--indeterminate .a1-circular-progress__svg {
+    animation: none;
+  }
+  .a1-circular-progress__fill {
+    transition: none;
+  }
+}

package/src/components/cluster/Cluster.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+type SpacingToken = 1 | 2 | 4 | 6 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 64 | 96 | 128;
+
+export interface ClusterProps extends React.HTMLAttributes<HTMLElement> {
+  /** Underlying element. Default: "div" */
+  as?: React.ElementType;
+  /** Gap applied to both row and column. Default: 8 */
+  gap?: SpacingToken;
+  /** Row gap override */
+  rowGap?: SpacingToken;
+  /** Column gap override */
+  columnGap?: SpacingToken;
+  /** Align-items. Default: "center" */
+  align?: "start" | "center" | "end" | "stretch" | "baseline";
+  /** Justify-content. Default: "start" */
+  justify?: "start" | "center" | "end" | "between" | "around" | "evenly";
+  children?: React.ReactNode;
+}
+
+export declare function Cluster(props: ClusterProps): React.ReactElement;

package/src/components/code/Code.d.ts

@@ -0,0 +1,15 @@
+import * as React from "react";
+
+export interface CodeProps extends React.HTMLAttributes<HTMLElement> {
+  /** Code presentation. Inline keeps minimal padding for prose; block renders a preformatted block. Default: "inline" */
+  variant?: "inline" | "block";
+  /** Allow long inline snippets or block code to wrap. Default: false */
+  wrapping?: boolean;
+  /** Show a small tertiary copy button at the bottom-left of the code block. Default: false */
+  copyCode?: boolean;
+  /** Text copied to the clipboard. Defaults to the rendered text children. */
+  copyText?: string;
+  children?: React.ReactNode;
+}
+
+export declare function Code(props: CodeProps): React.ReactElement;

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

@@ -0,0 +1,83 @@
+import * as React from "react";
+
+export interface DataTableColumn {
+  key: string;
+  label: string;
+  type?: "text" | "number" | "currency" | "date" | "badge" | "avatar" | "link" | "actions";
+  align?: "start" | "center" | "end";
+  width?: string;
+  sortable?: boolean;
+  sortAccessor?: (row: Record<string, unknown>) => unknown;
+  searchAccessor?: (row: Record<string, unknown>) => unknown;
+  statusMap?: Record<string, "neutral" | "info" | "success" | "warn" | "error">;
+  currencySymbol?: string;
+}
+
+export interface DataTableSortState {
+  key: string;
+  direction: "asc" | "desc";
+}
+
+export interface DataTableFilter {
+  key: string;
+  label: string;
+  type?: "single" | "multi";
+  options: Array<{ value: string; label: string }>;
+}
+
+export interface DataTableProps extends React.HTMLAttributes<HTMLDivElement> {
+  columns?: DataTableColumn[];
+  rows?: Record<string, unknown>[];
+  /**
+   * Cell spacing density.
+   * Omit (default) to auto-select density based on the available container width.
+   */
+  size?: "comfortable" | "default" | "compact";
+  /** Alternate row shading. Default: false */
+  zebra?: boolean;
+  /** Enable horizontal scroll on the table. Default: false */
+  scrollable?: boolean;
+  /** Accessible caption for the table */
+  caption?: string;
+  /** Controlled current page (1-based) */
+  page?: number;
+  /** Uncontrolled initial page. Default: 1 */
+  defaultPage?: number;
+  /** Number of rows per page for built-in pagination */
+  pageSize?: number;
+  /** Total page count for server-side pagination */
+  totalPages?: number;
+  /** Total row count for server-side row counter */
+  totalRows?: number;
+  /** Called when the active page changes */
+  onPageChange?: (page: number) => void;
+  /** Controlled sort state */
+  sort?: DataTableSortState | null;
+  /** Uncontrolled initial sort state */
+  defaultSort?: DataTableSortState;
+  /** Called when sort changes */
+  onSortChange?: (sort: DataTableSortState | null) => void;
+  filters?: DataTableFilter[];
+  filterValue?: Record<string, unknown>;
+  defaultFilterValue?: Record<string, unknown>;
+  onFilterChange?: (value: Record<string, unknown>) => void;
+  searchValue?: string;
+  defaultSearchValue?: string;
+  onSearchChange?: (value: string) => void;
+  searchColumn?: string;
+  defaultSearchColumn?: string;
+  onSearchColumnChange?: (column: string) => void;
+  searchableColumns?: Array<{ key: string; label: string }>;
+  /** Enable row selection. Default: false */
+  selectable?: boolean;
+  selectedRowIds?: (string | number)[];
+  defaultSelectedRowIds?: (string | number)[];
+  onSelectedRowIdsChange?: (ids: string[]) => void;
+  onDeleteSelected?: (rows: Record<string, unknown>[], ids: string[]) => void;
+  getRowId?: (row: Record<string, unknown>, index: number) => string | number;
+  emptyTitle?: string;
+  emptyDescription?: string;
+  emptyIcon?: string;
+}
+
+export declare function DataTable(props: DataTableProps): React.ReactElement;

package/src/components/dialog/Dialog.d.ts

@@ -0,0 +1,15 @@
+import * as React from "react";
+
+export interface DialogProps extends React.DialogHTMLAttributes<HTMLDialogElement> {
+  /** Whether the dialog is visible. Default: false */
+  open?: boolean;
+  /** Called when the user closes the dialog (Escape, close button, or backdrop click) */
+  onClose?: () => void;
+  /** Dialog title shown in the header */
+  title?: string;
+  /** Footer content — wrapped in a right-aligned `ButtonContainer` */
+  footer?: React.ReactNode;
+  children?: React.ReactNode;
+}
+
+export declare function Dialog(props: DialogProps): React.ReactElement;

package/src/components/dialog/dialog.css

@@ -12,8 +12,12 @@
 }
 
 .a1-dialog[open] {
-  display: flex;
-  flex-direction: column;
+  /* CSS Grid instead of Flex: Safari collapses flex: 1 children when the
+     container has only max-height but no explicit height. Grid resolves
+     track sizes against the constrained container first, so 1fr works. */
+  display: grid;
+  grid-template-rows: auto minmax(0, 1fr);
+  grid-auto-rows: auto;
   gap: var(--base-spacing-16);
 }
 
@@ -45,8 +49,8 @@
 }
 
 .a1-dialog__body {
-  flex: 1;
   overflow-y: auto;
+  min-height: 0;
 }
 
 .a1-dialog__footer {

package/src/components/divider/Divider.d.ts

@@ -0,0 +1,22 @@
+import * as React from "react";
+
+type Breakpoints = "xs" | "sm" | "md" | "lg" | "xl";
+type Orientation = "horizontal" | "vertical";
+
+export interface DividerProps extends React.HTMLAttributes<HTMLHRElement> {
+  /**
+   * Line orientation. Responsive object syntax supported. Default: "horizontal"
+   * @example orientation={{ xs: "horizontal", md: "vertical" }}
+   */
+  orientation?: Orientation | Partial<Record<Breakpoints, Orientation>>;
+  /** Visual style. Default: "subtle" */
+  variant?: "subtle" | "strong" | "accent" | "dashed" | "dotted";
+  /** Line thickness. Default: "xs" */
+  size?: "xs" | "sm" | "md" | "lg";
+  /** Block-axis margin (space above and below for horizontal, left/right for vertical). Default: "sm" */
+  space?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "xxl";
+  /** Whether this divider is purely decorative (no semantic role). Default: true */
+  decorative?: boolean;
+}
+
+export declare function Divider(props: DividerProps): React.ReactElement;

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

@@ -0,0 +1,22 @@
+import * as React from "react";
+
+export interface SelectFieldProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, "size"> {
+  /** Visible label text */
+  label?: string;
+  /** Helper text shown below the field */
+  hint?: string;
+  /** Error message — replaces hint and marks the field invalid */
+  error?: string;
+  /** Size density. Inherits from parent `Fieldset` when omitted. Default: "default" */
+  size?: "comfortable" | "default" | "compact";
+  /** Label position. Inherits from parent `Fieldset` when omitted. Default: "above" */
+  labelPosition?: "above" | "before";
+  required?: boolean;
+  disabled?: boolean;
+  /** Element rendered inside the field control */
+  inputOverlay?: React.ReactNode;
+  /** `<option>` elements */
+  children?: React.ReactNode;
+}
+
+export declare const SelectField: React.ForwardRefExoticComponent<SelectFieldProps & React.RefAttributes<HTMLSelectElement>>;

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

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+export interface TextFieldProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "placeholder"> {
+  /** Visible label text */
+  label?: string;
+  /** Helper text shown below the field */
+  hint?: string;
+  /** Error message — replaces hint and marks the field invalid */
+  error?: string;
+  /** Size density. Inherits from parent `Fieldset` when omitted. Default: "default" */
+  size?: "comfortable" | "default" | "compact";
+  /** Label position. Inherits from parent `Fieldset` when omitted. Default: "above" */
+  labelPosition?: "above" | "before";
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  /** Element rendered inside the field control (e.g. a unit suffix) */
+  inputOverlay?: React.ReactNode;
+}
+
+export declare const TextField: React.ForwardRefExoticComponent<TextFieldProps & React.RefAttributes<HTMLInputElement>>;

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

@@ -0,0 +1,28 @@
+import * as React from "react";
+
+export interface TextareaFieldProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "size" | "rows"> {
+  /** Visible label text */
+  label?: string;
+  /** Helper text shown below the field */
+  hint?: string;
+  /** Error message — replaces hint and marks the field invalid */
+  error?: string;
+  /** Size density. Inherits from parent `Fieldset` when omitted. Default: "default" */
+  size?: "comfortable" | "default" | "compact";
+  /** Label position. Inherits from parent `Fieldset` when omitted. Default: "above" */
+  labelPosition?: "above" | "before";
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  /**
+   * Initial visible row height. Pass a number for exact rows or a size token.
+   * sm=2 · md=4 · lg=8 · xl=12. Default: "md"
+   */
+  rows?: "sm" | "md" | "lg" | "xl" | number;
+  /** Maximum character count */
+  maxLength?: number;
+  /** Show a character counter. Auto-enabled when `maxLength` is set. Default: false */
+  showCount?: boolean;
+}
+
+export declare const TextareaField: React.ForwardRefExoticComponent<TextareaFieldProps & React.RefAttributes<HTMLTextAreaElement>>;

package/src/components/field-row/FieldRow.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+
+export interface FieldRowProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Lays out multiple field components side by side in a single row. */
+  children?: React.ReactNode;
+}
+
+export declare function FieldRow(props: FieldRowProps): React.ReactElement;

package/src/components/fieldset/Fieldset.d.ts

@@ -0,0 +1,27 @@
+import * as React from "react";
+
+export interface FieldsetProps extends React.FieldsetHTMLAttributes<HTMLFieldSetElement> {
+  /** `<legend>` text for the field group */
+  legend?: string;
+  /**
+   * Size density applied to all child fields via context.
+   * Individual fields can override this.
+   */
+  size?: "comfortable" | "default" | "compact";
+  /**
+   * Label position applied to all child fields via context.
+   * Individual fields can override this.
+   */
+  labelPosition?: "above" | "before";
+  /**
+   * Show a "* Required field" note below the legend.
+   * Only shown for "default" and "compact" sizes (comfortable fields show inline badges).
+   * Default: false
+   */
+  markRequired?: boolean;
+  /** Add a subtle surface background to the fieldset. Default: false */
+  surface?: boolean;
+  children?: React.ReactNode;
+}
+
+export declare function Fieldset(props: FieldsetProps): React.ReactElement;

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

@@ -0,0 +1,39 @@
+import * as React from "react";
+
+type SpacingToken = 1 | 2 | 4 | 6 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 64 | 96 | 128;
+
+export interface FigureProps extends React.HTMLAttributes<HTMLElement> {
+  /** Image source URL */
+  src: string;
+  /** Image alt text. Pass "" for decorative images. */
+  alt?: string;
+  /** Caption text or React node rendered as `<figcaption>` */
+  caption?: React.ReactNode;
+  /** Render caption visually hidden (screen-reader only). Default: false */
+  captionSrOnly?: boolean;
+  /** Caption alignment. Default: "start" */
+  captionPosition?: "start" | "center";
+  /** Border radius on the image. */
+  radius?: "none" | "sm" | "md" | "lg";
+  /** Constrain figure width. */
+  size?: "xs" | "sm" | "md" | "lg";
+  /** Horizontal alignment of the figure. Default: "start" */
+  align?: "start" | "center" | "end";
+  /** Top margin. */
+  marginTop?: "sm" | "md" | "lg";
+  /** Bottom margin. */
+  marginBottom?: "sm" | "md" | "lg";
+  /**
+   * Pull the figure outside its container padding using `Bleed`.
+   * Pass `true` for symmetric bleed or a numeric spacing token for inline-only.
+   */
+  bleed?: boolean | SpacingToken;
+  /** Extra class names on the `<figure>` element */
+  className?: string;
+  /** Extra class names on the `<img>` element */
+  imgClassName?: string;
+  /** Inline styles for the `<img>` element */
+  imgStyle?: React.CSSProperties;
+}
+
+export declare function Figure(props: FigureProps): React.ReactElement;

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

@@ -0,0 +1,38 @@
+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 ColSpan = number | "full";
+
+export interface GridProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Number of columns. Pass a number for a fixed count, or a responsive object.
+   * @example columns={{ xs: 1, md: 2, lg: 3 }}
+   */
+  columns?: number | Partial<Record<Breakpoints, number>>;
+  /** Gap applied to both row and column. Semantic token ("sm"–"xxl") or numeric spacing value. */
+  gap?: GapKey;
+  /** Row gap override. Falls back to `gap`. */
+  rowGap?: GapKey;
+  /** Column gap override. Falls back to `gap`. */
+  columnGap?: GapKey;
+  /** Grid layout preset. Default: "default" */
+  layout?: "default" | "bento";
+  /** CSS value for `grid-auto-rows` */
+  autoRows?: string;
+  children?: React.ReactNode;
+}
+
+export interface GridItemProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Column span. Pass a number, "full", or a responsive object.
+   * @example span={{ xs: "full", md: 2 }}
+   */
+  span?: ColSpan | Partial<Record<Breakpoints, ColSpan>>;
+  /** Row span. Pass a number or a responsive object. */
+  rowSpan?: number | Partial<Record<Breakpoints, number>>;
+  children?: React.ReactNode;
+}
+
+export declare function Grid(props: GridProps): React.ReactElement;
+export declare function GridItem(props: GridItemProps): React.ReactElement;

package/src/components/heading/Heading.d.ts

@@ -0,0 +1,43 @@
+import * as React from "react";
+
+type Breakpoints = "xs" | "sm" | "md" | "lg" | "xl";
+type HeadingSize = "xxl" | "xl" | "lg" | "md" | "sm" | "xs";
+type DisplaySize = "sm" | "md" | "lg" | "xl" | "xxl" | "jumbo" | "xJumbo";
+
+export interface HeadingProps extends React.HTMLAttributes<HTMLHeadingElement> {
+  /** HTML heading level. Default: "h2" */
+  as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span";
+  /**
+   * Typography type — drives the available size scale.
+   * "heading" uses the text hierarchy scale; "display" uses the larger editorial scale.
+   * Default: "heading"
+   */
+  type?: "heading" | "display";
+  /**
+   * Size within the active type scale. Responsive object syntax supported.
+   * Heading sizes: xs | sm | md | lg | xl | xxl
+   * Display sizes: sm | md | lg | xl | xxl | jumbo | xJumbo
+   * @example size={{ xs: "lg", md: "xl" }}
+   */
+  size?: HeadingSize | DisplaySize | Partial<Record<Breakpoints, HeadingSize | DisplaySize>>;
+  /** Text colour. Default: "default" */
+  color?: "default" | "muted" | "accent";
+  /** Add bottom margin. Useful when followed by body text. */
+  margin?: "sm" | "md" | "lg";
+  /** Apply text-wrap. "balance" distributes line lengths evenly — best for short headings. */
+  textWrap?: "balance";
+  /** Horizontal text alignment. "start"/"end" are logical aliases for LTR/RTL-safe alignment. */
+  align?: "left" | "center" | "right" | "start" | "end";
+  children?: React.ReactNode;
+}
+
+export interface HeadingMarkProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Visual decoration style. Default: "highlight" */
+  variant?: "highlight" | "underline";
+  /** Underline style (only applies when variant="underline"). Default: "swoop" */
+  underlineStyle?: "swoop" | "wave" | "sketch";
+  children?: React.ReactNode;
+}
+
+export declare function Heading(props: HeadingProps): React.ReactElement;
+export declare function HeadingMark(props: HeadingMarkProps): React.ReactElement;

package/src/components/heading/Heading.jsx

@@ -4,7 +4,7 @@ const headingSizes = ["xxl", "xl", "lg", "md", "sm", "xs"];
 const displaySizes = ["sm", "md", "lg", "xl", "xxl", "jumbo", "xJumbo"];
 const colors = ["default", "muted", "accent"];
 const margins = ["sm", "md", "lg"];
-const levels = ["h1", "h2", "h3", "h4", "h5", "h6"];
+const elements = ["h1", "h2", "h3", "h4", "h5", "h6", "p", "span"];
 const breakpoints = ["xs", "sm", "md", "lg", "xl"];
 const textWraps = ["balance"];
 const aligns = ["left", "center", "right", "start", "end"];
@@ -50,7 +50,7 @@ export function Heading({
   style,
   ...props
 }) {
-  const resolvedAs = levels.includes(Component) ? Component : "h2";
+  const resolvedAs = elements.includes(Component) ? Component : "h2";
   const isDisplay = type === "display";
   const validSizes = isDisplay ? displaySizes : headingSizes;
   const defaultSize = isDisplay ? "md" : (levelDefaults[resolvedAs] ?? "md");

package/src/components/icon/Icon.d.ts

@@ -0,0 +1,25 @@
+import * as React from "react";
+
+export interface IconProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Material Symbols icon name (e.g. "check_circle", "home", "arrow_back") */
+  name: string;
+  /**
+   * Variable font weight axis (100–700).
+   * Default is set via CSS token `--a1-icon-weight`.
+   */
+  weight?: number;
+  /**
+   * Grade axis — adjusts visual weight without changing size (-25–200).
+   * Default is set via CSS token `--a1-icon-grade`.
+   */
+  grade?: number;
+  /**
+   * Optical size axis — adjusts detail level (20, 24, 40, 48).
+   * Default is set via CSS token `--a1-icon-opsz`.
+   */
+  opticalSize?: 20 | 24 | 40 | 48;
+  /** Fill the icon shape. Default: false */
+  fill?: boolean;
+}
+
+export declare function Icon(props: IconProps): React.ReactElement;