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

package/package.json

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

package/src/components/accordion/Accordion.d.ts

@@ -3,6 +3,12 @@ import * as React from "react";
 export interface AccordionProps {
   /** Trigger label text */
   label: string;
+  /**
+   * Secondary information shown in the trigger, **below** the label. It only
+   * shows while the accordion is collapsed (a glanceable summary, e.g. the
+   * applied settings) and is hidden when open. Truncates with an ellipsis.
+   */
+  subtext?: React.ReactNode;
   /** Controlled open state */
   open?: boolean;
   /** Initial open state (uncontrolled). Default: false */
@@ -11,6 +17,8 @@ export interface AccordionProps {
   onChange?: (open: boolean) => void;
   /** Size — affects trigger text size and padding. Default: "md" */
   size?: "sm" | "md" | "lg";
+  /** Show a divider under the trigger/header (it stays attached to the header, not the bottom of the open panel). Default: false */
+  divider?: boolean;
   /** Prevent the accordion from being toggled. Default: false */
   disabled?: boolean;
   className?: string;

package/src/components/accordion/Accordion.jsx

@@ -6,11 +6,13 @@ const SIZES = ["sm", "md", "lg"];
 
 export function Accordion({
   label,
+  subtext,
   children,
   open: controlledOpen,
   defaultOpen = false,
   onChange,
   size = "md",
+  divider = false,
   disabled = false,
   className = "",
   ...rest
@@ -46,6 +48,7 @@ export function Accordion({
         "a1-accordion",
         `a1-accordion--${resolvedSize}`,
         open && "a1-accordion--open",
+        divider && "a1-accordion--divider",
         disabled && "a1-accordion--disabled",
         className,
       ].filter(Boolean).join(" ")}
@@ -63,7 +66,12 @@ export function Accordion({
         <span className="a1-accordion__chevron" aria-hidden="true">
           <Icon name="expand_more" />
         </span>
-        <span className="a1-accordion__label">{label}</span>
+        <span className="a1-accordion__text">
+          <span className="a1-accordion__label">{label}</span>
+          {subtext != null && subtext !== "" && (
+            <span className="a1-accordion__subtext">{subtext}</span>
+          )}
+        </span>
       </button>
 
       <div

package/src/components/accordion/accordion.css

@@ -3,31 +3,34 @@
 .a1-accordion {
   /* Size tokens — default (md) */
   --a1-ac-height:      var(--component-accordion-trigger-height-md);
-  --a1-ac-px:          var(--component-accordion-padding-inline-md);
+  --a1-ac-px:          var(--base-spacing-8);
   --a1-ac-py:          var(--base-spacing-8);
   --a1-ac-icon-size:   var(--component-accordion-icon-size-md);
   --a1-ac-font-size:   var(--semantic-font-size-body-md);
   --a1-ac-font-weight: var(--base-font-weight-medium);
+  --a1-ac-subtext-size: var(--semantic-font-size-body-sm);
 }
 
 /* ─── Sizes ─────────────────────────────────────────────────────────────────── */
 
 .a1-accordion--sm {
   --a1-ac-height:      var(--component-accordion-trigger-height-sm);
-  --a1-ac-px:          var(--component-accordion-padding-inline-sm);
+  --a1-ac-px:          var(--base-spacing-4);
   --a1-ac-py:          var(--base-spacing-6);
   --a1-ac-icon-size:   var(--component-accordion-icon-size-sm);
   --a1-ac-font-size:   var(--semantic-font-size-body-sm);
   --a1-ac-font-weight: var(--base-font-weight-medium);
+  --a1-ac-subtext-size: var(--semantic-font-size-body-xs);
 }
 
 .a1-accordion--lg {
   --a1-ac-height:      var(--component-accordion-trigger-height-lg);
-  --a1-ac-px:          var(--component-accordion-padding-inline-lg);
+  --a1-ac-px:          var(--base-spacing-12);
   --a1-ac-py:          var(--base-spacing-12);
   --a1-ac-icon-size:   var(--component-accordion-icon-size-lg);
   --a1-ac-font-size:   var(--semantic-font-size-body-lg);
   --a1-ac-font-weight: var(--base-font-weight-bold);
+  --a1-ac-subtext-size: var(--semantic-font-size-body-md);
 }
 
 /* ─── Trigger ───────────────────────────────────────────────────────────────── */
@@ -41,7 +44,6 @@
   padding-inline: var(--a1-ac-px);
   padding-block: var(--a1-ac-py);
   border: none;
-  border-radius: var(--component-accordion-border-radius);
   background: transparent;
   cursor: pointer;
   color: var(--semantic-color-text-default);
@@ -85,13 +87,36 @@
   transform: rotate(0deg);
 }
 
-/* ─── Label ─────────────────────────────────────────────────────────────────── */
+/* ─── Label + subtext ───────────────────────────────────────────────────────── */
+
+/* Label and subtext stack vertically (subtext below the title). */
+.a1-accordion__text {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-width: 0;
+}
 
 .a1-accordion__label {
-  flex: 1;
   min-width: 0;
 }
 
+/* Secondary info below the title, shown only while collapsed (e.g. a summary of
+   applied settings). Truncates with an ellipsis. */
+.a1-accordion__subtext {
+  min-width: 0;
+  color: var(--semantic-color-text-muted);
+  font-size: var(--a1-ac-subtext-size);
+  font-weight: var(--semantic-font-weight-body);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.a1-accordion--open .a1-accordion__subtext {
+  display: none;
+}
+
 /* ─── Body — CSS grid height animation ──────────────────────────────────────── */
 
 .a1-accordion__body {
@@ -109,6 +134,15 @@
   min-height: 0;
 }
 
+/* ─── Divider (optional) ────────────────────────────────────────────────────── */
+/* Attached to the trigger (the expanding header), so it stays put under the
+   header whether collapsed or expanded — never drops to the bottom of the open
+   panel. */
+
+.a1-accordion--divider .a1-accordion__trigger {
+  border-block-end: var(--component-divider-size-xs) solid var(--semantic-color-border-subtle);
+}
+
 /* ─── Disabled ──────────────────────────────────────────────────────────────── */
 
 .a1-accordion--disabled .a1-accordion__trigger {

package/src/components/button/button.css

@@ -1,8 +1,8 @@
 .a1-button {
   box-sizing: border-box;
-  height: var(--a1-button-height, var(--component-button-min-height));
+  /* min-height keeps the standard target size for a single line; the button
+     grows taller when a long label wraps to multiple lines. */
   min-height: var(--a1-button-height, var(--component-button-min-height));
-  max-height: var(--a1-button-height, var(--component-button-min-height));
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -18,7 +18,11 @@
   --a1-icon-weight: 700;
   line-height: var(--component-button-font-line-height);
   text-decoration: none;
-  white-space: nowrap;
+  /* Allow long labels to wrap onto multiple lines (centered), breaking an
+     over-long word if needed, instead of overflowing a fixed-height pill. */
+  white-space: normal;
+  text-align: center;
+  overflow-wrap: anywhere;
   overflow: clip;
   cursor: pointer;
   background: var(--a1-button-background);

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

@@ -13,12 +13,38 @@ export interface FigureProps extends React.HTMLAttributes<HTMLElement> {
   captionSrOnly?: boolean;
   /** Caption alignment. Default: "start" */
   captionPosition?: "start" | "center";
-  /** Border radius on the image. */
+  /** Border radius on the image. Default (no prop) is square, same as "none". */
   radius?: "none" | "sm" | "md" | "lg";
   /** Constrain figure width. */
-  size?: "xs" | "sm" | "md" | "lg";
-  /** Horizontal alignment of the figure. Default: "start" */
-  align?: "start" | "center" | "end";
+  size?: "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "xxl";
+  /** Horizontal alignment of the figure. Default: "none" (normal flow). */
+  align?: "none" | "start" | "center" | "end";
+  /**
+   * Fix the image to a set aspect ratio, cropping to fill via `object-fit: cover`.
+   * Omit for the image's natural ratio.
+   */
+  aspectRatio?: "16:9" | "4:3" | "3:2" | "1:1" | "2:3" | "3:4" | "9:16" | "21:9";
+  /**
+   * Crop focal point used when the image is cropped (i.e. when `aspectRatio` or a
+   * fixed height applies). Maps to `object-position`. Default: "center"
+   */
+  crop?:
+    | "center"
+    | "top"
+    | "bottom"
+    | "left"
+    | "right"
+    | "top-left"
+    | "top-right"
+    | "bottom-left"
+    | "bottom-right";
+  /**
+   * Freeform crop: a sub-rectangle of the image to show, expressed as fractions
+   * (0–1) of the natural image — `{ x, y, width, height }` where x/y is the
+   * top-left corner. Applied non-destructively (CSS only); the image is never
+   * modified. Takes precedence over `aspectRatio` / `crop` when set.
+   */
+  cropRect?: { x: number; y: number; width: number; height: number };
   /** Top margin. */
   marginTop?: "sm" | "md" | "lg";
   /** Bottom margin. */

package/src/components/figure/Figure.jsx

@@ -1,11 +1,24 @@
 import "./figure.css";
+import { useState } from "react";
 import { Bleed } from "../bleed/Bleed.jsx";
 
+function isCropRect(rect) {
+  return (
+    rect != null &&
+    typeof rect === "object" &&
+    ["x", "y", "width", "height"].every((k) => typeof rect[k] === "number") &&
+    rect.width > 0 &&
+    rect.height > 0
+  );
+}
+
 const rounded = ["none", "sm", "md", "lg"];
 const captionPositions = ["start", "center"];
 const spacings = ["sm", "md", "lg"];
-const sizes = ["xs", "sm", "md", "lg"];
-const alignments = ["start", "center", "end"];
+const sizes = ["3xs", "2xs", "xs", "sm", "md", "lg", "xl", "xxl"];
+const alignments = ["none", "start", "center", "end"];
+const aspectRatios = ["16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16", "21:9"];
+const crops = ["center", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"];
 
 export function Figure({
   src,
@@ -16,6 +29,9 @@ export function Figure({
   radius,
   size,
   align,
+  aspectRatio,
+  crop,
+  cropRect,
   marginTop,
   marginBottom,
   bleed,
@@ -25,12 +41,20 @@ export function Figure({
   imgStyle,
   ...props
 }) {
+  // Freeform crop: a sub-rectangle of the image (fractions 0–1) shown
+  // non-destructively. We measure the natural ratio to size the crop box.
+  const cropped = isCropRect(cropRect);
+  const [naturalRatio, setNaturalRatio] = useState(null);
+
   const classes = [
     "a1-figure",
     radius != null && rounded.includes(radius) && `a1-figure--rounded-${radius}`,
     captionPositions.includes(captionPosition) && captionPosition !== "start" && `a1-figure--caption-${captionPosition}`,
     sizes.includes(size) && `a1-figure--${size}`,
-    alignments.includes(align) && align !== "start" && `a1-figure--align-${align}`,
+    alignments.includes(align) && align !== "none" && `a1-figure--align-${align}`,
+    !cropped && aspectRatios.includes(aspectRatio) && `a1-figure--ratio-${aspectRatio.replace(":", "-")}`,
+    !cropped && crops.includes(crop) && crop !== "center" && `a1-figure--crop-${crop}`,
+    cropped && "a1-figure--cropped",
     spacings.includes(marginTop) && `a1-figure--mt-${marginTop}`,
     spacings.includes(marginBottom) && `a1-figure--mb-${marginBottom}`,
     className,
@@ -40,14 +64,38 @@ export function Figure({
     captionSrOnly ? "a1-sr-only" : "a1-figure__caption",
   ].join(" ");
 
+  const img = (
+    <img
+      src={src}
+      alt={alt}
+      className={["a1-figure__img", imgClassName].filter(Boolean).join(" ")}
+      style={imgStyle}
+      onLoad={cropped ? (e) => {
+        const { naturalWidth, naturalHeight } = e.currentTarget;
+        if (naturalWidth && naturalHeight) setNaturalRatio(naturalWidth / naturalHeight);
+      } : undefined}
+    />
+  );
+
+  const media = cropped ? (
+    <div
+      className="a1-figure__crop"
+      style={{
+        "--a1-figure-crop-x": cropRect.x,
+        "--a1-figure-crop-y": cropRect.y,
+        "--a1-figure-crop-w": cropRect.width,
+        "--a1-figure-crop-h": cropRect.height,
+        // Box aspect ratio = (cropW · imgW) / (cropH · imgH).
+        ...(naturalRatio ? { aspectRatio: `${(cropRect.width / cropRect.height) * naturalRatio}` } : {}),
+      }}
+    >
+      {img}
+    </div>
+  ) : img;
+
   const figure = (
     <figure className={classes} style={style} {...props}>
-      <img
-        src={src}
-        alt={alt}
-        className={["a1-figure__img", imgClassName].filter(Boolean).join(" ")}
-        style={imgStyle}
-      />
+      {media}
       {caption && (
         <figcaption className={captionClasses}>{caption}</figcaption>
       )}

package/src/components/figure/figure.css

@@ -15,7 +15,13 @@
   display: block;
   width: 100%;
   height: auto;
-  border-radius: var(--base-radius-container);
+  /* Square by default — this is the same as radius="none". Use the `radius`
+     prop to round the corners. */
+  border-radius: 0;
+  /* Crop point. Harmless on natural-ratio images (the box already matches the
+     intrinsic ratio); takes effect once a fixed aspect-ratio or height crops. */
+  object-fit: cover;
+  object-position: var(--a1-figure-crop, center);
 }
 
 .a1-figure__caption {
@@ -27,25 +33,47 @@
   font-style: italic;
 }
 
-/* ── Rounded modifier ──────────────────────────────────────────────────────── */
+/* ── Freeform crop (cropRect) ────────────────────────────────────────────────
+   The crop box clips a sub-rectangle of the image. The image is scaled so the
+   crop region fills the box width and shifted so the region's top-left aligns. */
+.a1-figure__crop {
+  position: relative;
+  inline-size: 100%;
+  overflow: hidden;
+}
 
-.a1-figure--rounded .a1-figure__img {
-  border-radius: var(--base-radius-container);
+.a1-figure--cropped .a1-figure__crop .a1-figure__img {
+  position: absolute;
+  inline-size: calc(100% / var(--a1-figure-crop-w));
+  max-inline-size: none;
+  block-size: auto;
+  inset-inline-start: calc(var(--a1-figure-crop-x) / var(--a1-figure-crop-w) * -100%);
+  inset-block-start: calc(var(--a1-figure-crop-y) / var(--a1-figure-crop-h) * -100%);
+  border-radius: 0;
 }
 
-.a1-figure--rounded-none .a1-figure__img {
+/* ── Rounded modifier ──────────────────────────────────────────────────────── */
+
+/* radius="none" matches the default (square) — kept so a figure can be reset to
+   square when a wrapping context sets a radius. The crop box, when present, is
+   the clipping element so it carries the radius. */
+.a1-figure--rounded-none .a1-figure__img,
+.a1-figure--rounded-none .a1-figure__crop {
   border-radius: 0;
 }
 
-.a1-figure--rounded-sm .a1-figure__img {
+.a1-figure--rounded-sm .a1-figure__img,
+.a1-figure--rounded-sm .a1-figure__crop {
   border-radius: var(--base-radius-sm);
 }
 
-.a1-figure--rounded-md .a1-figure__img {
+.a1-figure--rounded-md .a1-figure__img,
+.a1-figure--rounded-md .a1-figure__crop {
   border-radius: var(--base-radius-md);
 }
 
-.a1-figure--rounded-lg .a1-figure__img {
+.a1-figure--rounded-lg .a1-figure__img,
+.a1-figure--rounded-lg .a1-figure__crop {
   border-radius: var(--base-radius-lg);
 }
 
@@ -60,8 +88,11 @@
 .a1-figure--mb-lg { margin-bottom: var(--base-spacing-24); }
 
 /* ── Alignment ───────────────────────────────────────────────────────────── */
+/* Default (align="none"): no alignment — the figure flows at the inline-start in
+   normal document flow. start/center/end are explicit alignments. */
 
 /* start/end: constrain the figure itself and shift via margin */
+.a1-figure--align-start { margin-inline-end: auto; }
 .a1-figure--align-end { margin-inline-start: auto; }
 
 /* center: figure stays full-width; size constrains img + caption */
@@ -70,14 +101,24 @@
 /* ── Size ────────────────────────────────────────────────────────────────── */
 
 /* Default: constrain the figure element */
+.a1-figure--3xs { max-width: 5rem; }
+.a1-figure--2xs { max-width: 8rem; }
 .a1-figure--xs { max-width: 12rem; }
 .a1-figure--sm { max-width: 20rem; }
 .a1-figure--md { max-width: 30rem; }
 .a1-figure--lg { max-width: 40rem; }
+.a1-figure--xl { max-width: 50rem; }
+.a1-figure--xxl { max-width: 60rem; }
 
 /* Center override: transfer the constraint to img + caption instead */
 .a1-figure--align-center { max-width: none; }
 
+.a1-figure--align-center.a1-figure--3xs .a1-figure__img,
+.a1-figure--align-center.a1-figure--3xs .a1-figure__caption { max-width: 5rem; }
+
+.a1-figure--align-center.a1-figure--2xs .a1-figure__img,
+.a1-figure--align-center.a1-figure--2xs .a1-figure__caption { max-width: 8rem; }
+
 .a1-figure--align-center.a1-figure--xs .a1-figure__img,
 .a1-figure--align-center.a1-figure--xs .a1-figure__caption { max-width: 12rem; }
 
@@ -90,6 +131,37 @@
 .a1-figure--align-center.a1-figure--lg .a1-figure__img,
 .a1-figure--align-center.a1-figure--lg .a1-figure__caption { max-width: 40rem; }
 
+.a1-figure--align-center.a1-figure--xl .a1-figure__img,
+.a1-figure--align-center.a1-figure--xl .a1-figure__caption { max-width: 50rem; }
+
+.a1-figure--align-center.a1-figure--xxl .a1-figure__img,
+.a1-figure--align-center.a1-figure--xxl .a1-figure__caption { max-width: 60rem; }
+
+/* ── Aspect ratio ────────────────────────────────────────────────────────── */
+
+/* A fixed aspect-ratio box; the image fills it via object-fit: cover, cropping
+   to the `crop` point. width:100% + height:auto lets aspect-ratio size the box. */
+.a1-figure--ratio-16-9 .a1-figure__img { aspect-ratio: 16 / 9; }
+.a1-figure--ratio-4-3 .a1-figure__img { aspect-ratio: 4 / 3; }
+.a1-figure--ratio-3-2 .a1-figure__img { aspect-ratio: 3 / 2; }
+.a1-figure--ratio-1-1 .a1-figure__img { aspect-ratio: 1 / 1; }
+.a1-figure--ratio-2-3 .a1-figure__img { aspect-ratio: 2 / 3; }
+.a1-figure--ratio-3-4 .a1-figure__img { aspect-ratio: 3 / 4; }
+.a1-figure--ratio-9-16 .a1-figure__img { aspect-ratio: 9 / 16; }
+.a1-figure--ratio-21-9 .a1-figure__img { aspect-ratio: 21 / 9; }
+
+/* ── Crop (object-position) ──────────────────────────────────────────────────
+   Each modifier sets --a1-figure-crop, read by .a1-figure__img's
+   object-position. Default (center) needs no class. */
+.a1-figure--crop-top { --a1-figure-crop: center top; }
+.a1-figure--crop-bottom { --a1-figure-crop: center bottom; }
+.a1-figure--crop-left { --a1-figure-crop: left center; }
+.a1-figure--crop-right { --a1-figure-crop: right center; }
+.a1-figure--crop-top-left { --a1-figure-crop: left top; }
+.a1-figure--crop-top-right { --a1-figure-crop: right top; }
+.a1-figure--crop-bottom-left { --a1-figure-crop: left bottom; }
+.a1-figure--crop-bottom-right { --a1-figure-crop: right bottom; }
+
 /* ── Caption position ──────────────────────────────────────────────────────── */
 
 .a1-figure--caption-center .a1-figure__caption {

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

@@ -13,8 +13,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";
+  /** Button size. "sm" is a 24×24px target (the WCAG 2.2 AA minimum) for dense toolbars; "lg" matches Button's large touch target (3.5rem) and icon size. Default: "md" */
+  size?: "sm" | "md" | "lg";
   /** Link target when rendered with `as="a"`. */
   href?: string;
   disabled?: boolean;

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

@@ -2,7 +2,8 @@ import "./icon-button.css";
 import { Icon } from "../icon/Icon.jsx";
 
 const variants = ["tertiary", "secondary", "destructive", "success"];
-const sizes = ["md", "lg"];
+const sizes = ["sm", "md", "lg"];
+const sizeClass = { sm: "a1-icon-button--small", lg: "a1-icon-button--large" };
 
 export function IconButton({
   as: Component = "button",
@@ -23,7 +24,7 @@ export function IconButton({
   const classes = [
     "a1-icon-button",
     `a1-icon-button--${resolvedVariant}`,
-    resolvedSize === "lg" && "a1-icon-button--large",
+    resolvedSize && sizeClass[resolvedSize],
     className,
   ].filter(Boolean).join(" ");
 

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

@@ -37,12 +37,22 @@
   --a1-icon-opsz: var(--a1-icon-button-icon-opsz, var(--component-icon-button-icon-optical-size));
 }
 
+/* ── Size: small ─────────────────────────────────────────────────────────── */
+/* 24×24px total — the WCAG 2.2 target-size (AA) minimum; for dense toolbars. */
+
+.a1-icon-button--small {
+  --a1-icon-button-size:      var(--base-spacing-24);
+  --a1-icon-button-icon-size: var(--base-spacing-16);
+}
+
 /* ── 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);
+  /* Icon is two steps up the icon scale (20 → 24 → 32px) so it reads at the
+     larger touch target. */
+  --a1-icon-button-icon-size: var(--base-spacing-32);
   --a1-icon-button-icon-opsz: var(--component-button-icon-optical-size);
 }
 

package/src/components/menu/Menu.jsx

@@ -81,6 +81,18 @@ export function Menu({
     el.style.setProperty("--a1-menu-top", `${Math.round(top)}px`);
     el.style.setProperty("--a1-menu-left", `${Math.round(left)}px`);
     el.style.setProperty("--a1-menu-max-height", `${Math.floor(maxHeight)}px`);
+
+    // `position: fixed` resolves against the nearest transformed/filtered
+    // ancestor's box, not the viewport — e.g. an `overlay` Toolbar positioned
+    // with a CSS transform. Measure where the menu actually landed and correct
+    // by the containing-block offset so it stays anchored to the viewport.
+    const placed = el.getBoundingClientRect();
+    const dx = left - placed.left;
+    const dy = top - placed.top;
+    if (Math.abs(dx) > 0.5 || Math.abs(dy) > 0.5) {
+      el.style.setProperty("--a1-menu-left", `${Math.round(left + dx)}px`);
+      el.style.setProperty("--a1-menu-top", `${Math.round(top + dy)}px`);
+    }
   }, [anchorRef]);
 
   const openDialog = useCallback(() => {

package/src/components/menu/menu.css

@@ -104,16 +104,27 @@
   background: transparent;
 }
 
-/* Active / current-page indicator */
+/* Active / current-page indicator — matches the TreeMenu selected pattern:
+   a solid action-background fill for a clear, unambiguous highlight. */
 .a1-menu-item--active {
-  color: var(--semantic-color-text-default);
-  background: var(--semantic-color-action-surface);
-  border-inline-start: 2px solid var(--semantic-color-action-background);
-  padding-inline-start: calc(var(--base-spacing-8) - 2px);
+  color: var(--semantic-color-action-foreground);
+  background: var(--semantic-color-action-background);
+}
+
+.a1-menu-item--active:hover {
+  background: var(--semantic-color-action-background-hover);
+}
+
+.a1-menu-item--active:active {
+  background: var(--semantic-color-action-background-pressed);
+}
+
+.a1-menu-item--active:focus-visible {
+  outline-color: var(--semantic-color-action-foreground);
 }
 
 .a1-menu-item--active .a1-menu-item__icon {
-  color: var(--semantic-color-action-background);
+  color: var(--semantic-color-action-foreground);
 }
 
 /* Destructive variant */

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

@@ -33,6 +33,12 @@ export interface SectionProps extends React.HTMLAttributes<HTMLElement> {
   borderStyle?: "solid" | "dashed" | "dotted";
   /** Border color tone. Uses the same variants as Divider. Default: "subtle" */
   borderVariant?: "subtle" | "strong" | "accent";
+  /**
+   * Which sides the border is drawn on (requires `borderSize`). `"all"` (default)
+   * draws all four sides; pass an array to draw only those sides, e.g.
+   * `["top", "bottom"]`. An empty array draws no border.
+   */
+  borderSides?: "all" | ("top" | "right" | "bottom" | "left")[];
   /** Border radius scale. */
   radius?: "none" | "sm" | "md" | "lg" | "xl";
   children?: React.ReactNode;

package/src/components/section/Section.jsx

@@ -23,8 +23,19 @@ const VALID_ALIGNMENTS = ["left", "center", "right"];
 const VALID_BORDER_SIZES = ["xs", "sm", "md", "lg"];
 const VALID_BORDER_STYLES = ["solid", "dashed", "dotted"];
 const VALID_BORDER_VARIANTS = ["subtle", "strong", "accent"];
+const VALID_BORDER_SIDES = ["top", "right", "bottom", "left"];
 const VALID_RADII = ["none", "sm", "md", "lg", "xl"];
 
+// Resolve which sides get the border. `null` means all sides (the default);
+// an array means only those sides (an empty array means no border).
+function resolveBorderSides(borderSides) {
+  if (borderSides == null || borderSides === "all") return null;
+  const arr = Array.isArray(borderSides) ? borderSides : [borderSides];
+  const sides = VALID_BORDER_SIDES.filter((side) => arr.includes(side));
+  if (sides.length === VALID_BORDER_SIDES.length) return null; // all four = all
+  return sides;
+}
+
 export function Section({
   as: Component = "section",
   padding = "md",
@@ -39,6 +50,7 @@ export function Section({
   borderSize,
   borderStyle = "solid",
   borderVariant = "subtle",
+  borderSides,
   radius,
   className = "",
   children,
@@ -98,6 +110,13 @@ export function Section({
 
   if (borderSize && VALID_BORDER_SIZES.includes(borderSize)) {
     classes.push(`a1-section--border-${borderSize}`);
+
+    // Per-side borders. Omitted / "all" draws all four sides (default).
+    const sides = resolveBorderSides(borderSides);
+    if (sides) {
+      classes.push("a1-section--border-sided");
+      sides.forEach((side) => classes.push(`a1-section--border-side-${side}`));
+    }
   }
 
   if (borderStyle && VALID_BORDER_STYLES.includes(borderStyle)) {