@gtivr4/a1-design-system-react 0.1.0 → 0.2.3

package/src/components/card/card.css

@@ -1,37 +1,201 @@
 .a1-card {
+  container: a1-card / inline-size;
   box-sizing: border-box;
   background: var(--semantic-color-surface-page);
-  border: var(--component-card-border-width) solid var(--semantic-color-border-strong);
+  border: var(--component-card-border-width) solid var(--semantic-color-border-subtle);
   border-radius: var(--component-card-border-radius);
   padding: var(--component-card-padding);
-  box-shadow: var(--a1-card-shadow);
+  box-shadow: var(--semantic-shadow-sm);
   color: var(--semantic-color-text-default);
 }
 
+/* ─── Navigation variant — the whole card is the link/button ─────────────── */
+
+.a1-card--navigation {
+  display: block;
+  inline-size: 100%;
+  text-align: start;
+  text-decoration: none;
+  border-color: var(--semantic-color-text-accent);
+  cursor: pointer;
+  transition:
+    background var(--semantic-motion-duration-fast) var(--semantic-motion-easing-standard),
+    border-color var(--semantic-motion-duration-fast) var(--semantic-motion-easing-standard),
+    box-shadow var(--semantic-motion-duration-fast) var(--semantic-motion-easing-standard);
+}
+
+button.a1-card--navigation {
+  appearance: none;
+  font: inherit;
+}
+
+.a1-card--navigation:hover {
+  background: var(--semantic-color-action-surface);
+  border-color: var(--semantic-color-action-background);
+}
+
+.a1-card--navigation:active {
+  background: var(--semantic-color-surface-panel);
+  border-color: var(--semantic-color-action-background);
+  box-shadow: var(--semantic-shadow-xs);
+}
+
+.a1-card--navigation:focus-visible {
+  outline: var(--component-button-focus-ring-width) solid var(--semantic-color-action-background);
+  outline-offset: var(--base-spacing-2);
+}
+
+/* ─── Bare variant — no chrome, no padding ─────────────────────────────────── */
+
+.a1-card--bare {
+  background: transparent;
+  border: none;
+  border-radius: 0;
+  box-shadow: none;
+  padding: 0;
+}
+
+/* ─── Content wrapper ─────────────────────────────────────────────────────── */
+
+.a1-card__content {
+  min-width: 0;
+}
+
+/* ─── Hero icon — full-bleed header area (or left strip at lg) ─────────────
+   Container query breakpoints: sm=320px, md=480px, lg=640px
+   base/sm/md : coloured band spanning the full card width at the top
+   lg ≥ 640px : coloured strip spanning the full card height on the left
+   ─────────────────────────────────────────────────────────────────────────── */
+
+.a1-card--has-hero {
+  overflow: hidden;
+}
+
+.a1-card--has-hero .a1-card__layout {
+  display: flex;
+  flex-direction: column;
+}
+
+.a1-card__hero {
+  /* Bleed out to the card edges on all four sides then add inner padding */
+  margin-top: calc(-1 * var(--component-card-padding));
+  margin-inline: calc(-1 * var(--component-card-padding));
+  margin-bottom: var(--component-card-padding);
+  padding: var(--base-spacing-32) 0;
+  background: var(--a1-card-hero-bg, var(--semantic-color-action-background));
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  --a1-icon-opsz: 48;
+}
+
+/* Higher specificity (0,2,0) beats .a1-icon (0,1,0) so font-size is not overridden by inherit */
+.a1-card__hero .a1-icon {
+  font-size: var(--base-spacing-64);
+  color: var(--semantic-color-text-inverse);
+}
+
+/* lg ≥ 640px — hero becomes a left strip, full card height; icon 3 steps larger (128px) */
+@container a1-card (min-width: 640px) {
+  .a1-card--has-hero > .a1-card__layout {
+    flex-direction: row;
+    align-items: stretch;
+  }
+
+  .a1-card__hero {
+    /* Reset top-strip margins; bleed left/top/bottom only */
+    margin-top: calc(-1 * var(--component-card-padding));
+    margin-bottom: calc(-1 * var(--component-card-padding));
+    margin-inline-start: calc(-1 * var(--component-card-padding));
+    margin-inline-end: 0;
+    margin-block: calc(-1 * var(--component-card-padding));
+    /* Vertical strip padding */
+    padding: var(--base-spacing-32) var(--base-spacing-40);
+    /* Round left corners only — right side butts flush against content */
+    border-start-start-radius: calc(var(--component-card-border-radius) - var(--component-card-border-width));
+    border-end-start-radius: calc(var(--component-card-border-radius) - var(--component-card-border-width));
+    border-start-end-radius: 0;
+    border-end-end-radius: 0;
+  }
+
+  .a1-card__hero .a1-icon {
+    font-size: var(--base-spacing-128);
+  }
+
+  .a1-card--has-hero .a1-card__content {
+    flex: 1 1 auto;
+    padding-inline-start: var(--component-card-padding);
+  }
+}
+
+/* ─── Default icon — small tokenised icon block ─────────────────────────────
+   Container query breakpoints (standard: sm=320px, md=480px, lg=640px):
+   base       : 40×40 box, 20px icon, icon above content (column)
+   sm ≥ 320px : 40×40 box, 24px icon
+   md ≥ 480px : 64×64 box, 32px icon
+   lg ≥ 640px : 96×96 box, 40px icon, shifted left (row layout)
+   ─────────────────────────────────────────────────────────────────────────── */
+
+.a1-card--has-icon .a1-card__layout {
+  display: flex;
+  flex-direction: column;
+}
+
 .a1-card__icon {
+  --a1-card-icon-box: var(--base-spacing-40);
+  --a1-card-icon-size: var(--component-card-icon-size);
+
   display: flex;
   align-items: center;
   justify-content: center;
-  width: var(--base-spacing-40);
-  height: var(--base-spacing-40);
+  width: var(--a1-card-icon-box);
+  height: var(--a1-card-icon-box);
   border-radius: var(--base-radius-control);
   background: var(--semantic-color-action-surface);
   color: var(--semantic-color-action-background);
   margin-bottom: var(--base-spacing-12);
   flex-shrink: 0;
-}
-
-.a1-card__icon {
   --a1-icon-opsz: var(--component-card-icon-optical-size);
 }
 
 .a1-card__icon .a1-icon {
-  font-size: var(--component-card-icon-size);
+  font-size: var(--a1-card-icon-size);
 }
 
-.a1-card--shadow-none { --a1-card-shadow: none; }
-.a1-card--shadow-xs   { --a1-card-shadow: var(--semantic-shadow-xs); }
-.a1-card--shadow-sm   { --a1-card-shadow: var(--semantic-shadow-sm); }
-.a1-card--shadow-md   { --a1-card-shadow: var(--semantic-shadow-md); }
-.a1-card--shadow-lg   { --a1-card-shadow: var(--semantic-shadow-lg); }
-.a1-card--shadow-xl   { --a1-card-shadow: var(--semantic-shadow-xl); }
+/* sm ≥ 320px — icon one step larger (24px), box unchanged */
+@container a1-card (min-width: 320px) {
+  .a1-card__icon {
+    --a1-card-icon-size: var(--base-spacing-24);
+    --a1-icon-opsz: 24;
+  }
+}
+
+/* md ≥ 480px — icon two steps larger (32px), box one step larger (64px) */
+@container a1-card (min-width: 480px) {
+  .a1-card__icon {
+    --a1-card-icon-box: var(--base-spacing-64);
+    --a1-card-icon-size: var(--base-spacing-32);
+    --a1-icon-opsz: 40;
+  }
+}
+
+/* lg ≥ 640px — icon three steps larger (40px), box two steps larger (96px), shifted left */
+@container a1-card (min-width: 640px) {
+  .a1-card--has-icon > .a1-card__layout {
+    flex-direction: row;
+    align-items: flex-start;
+    gap: var(--base-spacing-16);
+  }
+
+  .a1-card__icon {
+    --a1-card-icon-box: var(--base-spacing-96);
+    --a1-card-icon-size: var(--base-spacing-40);
+    --a1-icon-opsz: 48;
+    margin-bottom: 0;
+  }
+
+  .a1-card--has-icon .a1-card__content {
+    flex: 1 1 auto;
+  }
+}

package/src/components/checkbox-group/CheckboxGroup.jsx

@@ -0,0 +1,120 @@
+import { useId, useState, useContext } from "react";
+import { useLabel } from "../labels/Labels.jsx";
+import { MessageBadge } from "../message/Message.jsx";
+import { FieldsetContext } from "../fieldset/FieldsetContext.js";
+import "./checkbox-group.css";
+
+const SIZES = ["comfortable", "default", "compact"];
+
+export function CheckboxGroup({
+  label,
+  hint,
+  error,
+  size,
+  required     = false,
+  disabled     = false,
+  inline       = false,
+  name,
+  options      = [],
+  value,
+  defaultValue,
+  onChange,
+  id: providedId,
+  className    = "",
+  ...props
+}) {
+  const ctx    = useContext(FieldsetContext);
+  const autoId = useId();
+  const id     = providedId ?? autoId;
+  const hintId  = `${id}-hint`;
+  const errorId = `${id}-error`;
+
+  const resolvedSize = SIZES.includes(size) ? size : (ctx?.size ?? "default");
+
+  const [internalValue, setInternalValue] = useState(defaultValue ?? []);
+  const currentValue = value ?? internalValue;
+
+  function handleChange(optionValue, checked) {
+    const next = checked
+      ? [...currentValue, optionValue]
+      : currentValue.filter(v => v !== optionValue);
+    if (value == null) setInternalValue(next);
+    onChange?.(next);
+  }
+
+  const classes = [
+    "a1-checkbox-group",
+    `a1-checkbox-group--${resolvedSize}`,
+    inline   && "a1-checkbox-group--inline",
+    error    && "a1-checkbox-group--error",
+    required && "a1-checkbox-group--required",
+    disabled && "a1-checkbox-group--disabled",
+    className,
+  ].filter(Boolean).join(" ");
+
+  const describedBy = [error ? errorId : hint ? hintId : null]
+    .filter(Boolean).join(" ") || undefined;
+
+  const requiredText = useLabel("field.required", "Required");
+
+  return (
+    <fieldset className={classes} aria-describedby={describedBy} {...props}>
+      {label && (
+        <legend className="a1-checkbox-group__legend">
+          <span className="a1-checkbox-group__legend-inner">
+            {label}
+            {required && resolvedSize === "comfortable" ? (
+              <MessageBadge status="info" subtle>{requiredText}</MessageBadge>
+            ) : required ? (
+              <span className="a1-field__asterisk" aria-hidden="true"> *</span>
+            ) : null}
+          </span>
+        </legend>
+      )}
+      {hint && !error && (
+        <p className="a1-checkbox-group__message a1-checkbox-group__message--hint" id={hintId}>
+          {hint}
+        </p>
+      )}
+      <div className="a1-checkbox-group__items">
+        {options.map((option) => {
+          const isChecked  = currentValue.includes(option.value);
+          const isDisabled = disabled || option.disabled;
+          const itemId     = `${id}-${option.value}`;
+
+          return (
+            <label
+              key={option.value}
+              className={[
+                "a1-checkbox-item",
+                isDisabled && "a1-checkbox-item--disabled",
+              ].filter(Boolean).join(" ")}
+            >
+              <input
+                type="checkbox"
+                id={itemId}
+                className="a1-checkbox-item__input"
+                name={name}
+                value={option.value}
+                checked={isChecked}
+                disabled={isDisabled}
+                onChange={(e) => handleChange(option.value, e.target.checked)}
+              />
+              <span className="a1-checkbox-item__content">
+                <span className="a1-checkbox-item__label">{option.label}</span>
+                {option.hint && (
+                  <span className="a1-checkbox-item__hint">{option.hint}</span>
+                )}
+              </span>
+            </label>
+          );
+        })}
+      </div>
+      {error && (
+        <p className="a1-checkbox-group__message a1-checkbox-group__message--error" id={errorId} role="alert">
+          {error}
+        </p>
+      )}
+    </fieldset>
+  );
+}

package/src/components/checkbox-group/checkbox-group.css

@@ -0,0 +1,304 @@
+/* ─── CheckboxGroup ───────────────────────────────────────────────────────── */
+
+.a1-checkbox-group {
+  border: none;
+  margin: 0;
+  padding: 0;
+  min-width: 0;
+
+  /* Size tokens — default */
+  --a1-cb-size:          var(--component-checkbox-group-box-size);
+  --a1-cb-radius:        var(--base-radius-sm);
+  --a1-cb-gap:           var(--component-checkbox-group-gap);     /* horizontal gap: box ↔ text */
+  --a1-cb-item-gap:      var(--component-checkbox-group-item-gap);     /* gap between items (row padding provides visual breathing room) */
+  --a1-cb-group-gap:     var(--component-checkbox-group-group-gap);     /* vertical gap between legend/hint and message */
+  --a1-cb-items-top-gap: var(--component-checkbox-group-items-top-gap);    /* extra space between legend/hint and the items stack */
+  --a1-cb-input-nudge:   var(--component-checkbox-group-input-nudge);     /* top margin aligning box center with label cap-height */
+  --a1-cb-row-py:        var(--component-checkbox-group-row-padding-block);     /* vertical padding on each item row */
+  --a1-cb-row-px:        var(--component-checkbox-group-row-padding-inline);     /* horizontal padding on each item row */
+  --a1-cb-legend-size:  var(--semantic-font-size-body-sm);
+  --a1-cb-label-size:   var(--semantic-font-size-body-md);
+  --a1-cb-hint-size:    var(--semantic-font-size-body-xs);
+  --a1-cb-msg-size:     var(--semantic-font-size-body-xs);
+
+  display: flex;
+  flex-direction: column;
+  gap: var(--a1-cb-group-gap);
+}
+
+/* ─── Sizes ───────────────────────────────────────────────────────────────── */
+
+.a1-checkbox-group--comfortable {
+  --a1-cb-size:          var(--component-checkbox-group-comfortable-box-size);
+  --a1-cb-gap:           var(--component-checkbox-group-comfortable-gap);
+  --a1-cb-item-gap:      var(--component-checkbox-group-comfortable-item-gap);
+  --a1-cb-group-gap:     var(--component-checkbox-group-comfortable-group-gap);
+  --a1-cb-items-top-gap: var(--component-checkbox-group-comfortable-items-top-gap);
+  --a1-cb-input-nudge:   var(--component-checkbox-group-comfortable-input-nudge);
+  --a1-cb-row-py:        var(--component-checkbox-group-comfortable-row-padding-block);
+  --a1-cb-row-px:        var(--component-checkbox-group-comfortable-row-padding-inline);
+  --a1-cb-legend-size: var(--semantic-font-size-body-md);
+  --a1-cb-label-size:  var(--semantic-font-size-body-md);
+  --a1-cb-hint-size:   var(--semantic-font-size-body-sm);
+  --a1-cb-msg-size:    var(--semantic-font-size-body-sm);
+}
+
+.a1-checkbox-group--comfortable .a1-checkbox-item__label {
+  font-weight: var(--base-font-weight-medium);
+}
+
+@media (--bp-md-up) {
+  .a1-checkbox-group--comfortable {
+    --a1-cb-legend-size: var(--semantic-font-size-body-lg);
+    --a1-cb-label-size:  var(--semantic-font-size-body-lg);
+    --a1-cb-size:        var(--component-checkbox-group-comfortable-box-size-md);
+    --a1-cb-input-nudge: var(--component-checkbox-group-comfortable-input-nudge);
+  }
+}
+
+.a1-checkbox-group--compact {
+  --a1-cb-size:          var(--component-checkbox-group-compact-box-size);
+  --a1-cb-gap:           var(--component-checkbox-group-compact-gap);
+  --a1-cb-item-gap:      var(--component-checkbox-group-compact-item-gap);
+  --a1-cb-group-gap:     var(--component-checkbox-group-compact-group-gap);
+  --a1-cb-items-top-gap: var(--component-checkbox-group-compact-items-top-gap);
+  --a1-cb-input-nudge:   var(--component-checkbox-group-compact-input-nudge);
+  --a1-cb-row-py:        var(--component-checkbox-group-compact-row-padding-block);
+  --a1-cb-row-px:        var(--component-checkbox-group-compact-row-padding-inline);
+  --a1-cb-legend-size: var(--semantic-font-size-body-xs);
+  --a1-cb-label-size:  var(--semantic-font-size-body-sm);
+  --a1-cb-hint-size:   var(--semantic-font-size-body-xs);
+  --a1-cb-msg-size:    var(--semantic-font-size-body-xs);
+}
+
+/* ─── Legend ──────────────────────────────────────────────────────────────── */
+
+.a1-checkbox-group__legend {
+  display: block;
+  width: 100%;
+  padding: 0;
+  font-family: var(--component-paragraph-font-family);
+  font-size: var(--a1-cb-legend-size);
+  font-weight: var(--component-field-label-font-weight);
+  color: var(--semantic-color-text-default);
+  line-height: var(--semantic-font-line-height-body);
+}
+
+.a1-checkbox-group--disabled .a1-checkbox-group__legend {
+  color: var(--semantic-color-text-muted);
+}
+
+/* Inline-flex wrapper handles the gap between legend text and required badge/asterisk */
+.a1-checkbox-group__legend-inner {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--base-spacing-6);
+}
+
+/* ─── Group hint / error message ──────────────────────────────────────────── */
+
+.a1-checkbox-group__message {
+  margin: 0;
+  font-family: var(--component-paragraph-font-family);
+  font-size: var(--a1-cb-msg-size);
+  line-height: var(--semantic-font-line-height-body);
+}
+
+.a1-checkbox-group__message--hint  { color: var(--semantic-color-text-muted); }
+.a1-checkbox-group__message--error { color: var(--semantic-color-status-error-background); }
+
+/* ─── Items stack ─────────────────────────────────────────────────────────── */
+
+.a1-checkbox-group__items {
+  display: flex;
+  flex-direction: column;
+  gap: var(--a1-cb-item-gap);
+  margin-top: var(--a1-cb-items-top-gap);
+}
+
+/* ─── Individual item ─────────────────────────────────────────────────────── */
+
+.a1-checkbox-item {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--a1-cb-gap);
+  padding: var(--a1-cb-row-py) var(--a1-cb-row-px);
+  margin-inline: calc(-1 * var(--a1-cb-row-px));
+  border-radius: var(--base-radius-md);
+  cursor: pointer;
+  transition: background-color var(--semantic-motion-duration-fast);
+}
+
+.a1-checkbox-item--disabled {
+  cursor: not-allowed;
+}
+
+.a1-checkbox-item__content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--component-checkbox-group-content-gap);
+}
+
+.a1-checkbox-item__label {
+  font-family: var(--component-paragraph-font-family);
+  font-size: var(--a1-cb-label-size);
+  font-weight: var(--base-font-weight-regular);
+  color: var(--semantic-color-text-muted);
+  line-height: var(--semantic-font-line-height-body);
+}
+
+/* Restore default color when the item is checked */
+.a1-checkbox-item:has(.a1-checkbox-item__input:checked) .a1-checkbox-item__label {
+  color: var(--semantic-color-text-default);
+}
+
+/* Disabled always stays muted regardless of checked state */
+.a1-checkbox-item--disabled .a1-checkbox-item__label {
+  color: var(--semantic-color-text-muted);
+}
+
+.a1-checkbox-item__hint {
+  font-family: var(--component-paragraph-font-family);
+  font-size: var(--a1-cb-hint-size);
+  font-weight: var(--base-font-weight-regular);
+  color: var(--semantic-color-text-muted);
+  line-height: var(--semantic-font-line-height-body);
+}
+
+/* ─── Checkbox input ──────────────────────────────────────────────────────── */
+
+.a1-checkbox-item__input {
+  -webkit-appearance: none;
+  appearance: none;
+  flex-shrink: 0;
+  width: var(--a1-cb-size);
+  height: var(--a1-cb-size);
+  /* Nudge aligns the checkbox's visual center with the label's cap-height */
+  margin-top: var(--a1-cb-input-nudge);
+  border: var(--component-field-border-width) solid var(--semantic-color-border-strong);
+  border-radius: var(--a1-cb-radius);
+  background-color: var(--semantic-color-surface-page);
+  cursor: pointer;
+  transition:
+    border-color       var(--semantic-motion-duration-fast),
+    background-color   var(--semantic-motion-duration-fast);
+}
+
+/* Checked row — always show a tinted background */
+.a1-checkbox-item:not(.a1-checkbox-item--disabled):has(.a1-checkbox-item__input:checked) {
+  background-color: var(--a1-field-hover-background);
+}
+
+/* Hover — entire row background, triggered anywhere on the label */
+.a1-checkbox-item:not(.a1-checkbox-item--disabled):hover {
+  background-color: var(--a1-field-hover-background);
+}
+
+/* Checked row on hover — step one shade deeper/lighter */
+.a1-checkbox-item:not(.a1-checkbox-item--disabled):hover:has(.a1-checkbox-item__input:checked) {
+  background-color: var(--a1-field-active-background);
+}
+
+/* Also darken the input border on row hover (unchecked/non-indeterminate only) */
+.a1-checkbox-item:not(.a1-checkbox-item--disabled):hover
+  .a1-checkbox-item__input:not(:checked):not(:indeterminate) {
+  border-color: var(--a1-field-hover-border-color);
+}
+
+/* Focus */
+.a1-checkbox-item__input:focus-visible {
+  outline: var(--component-field-focus-ring-width) solid var(--component-field-focus-ring-color);
+  outline-offset: var(--component-field-focus-ring-offset);
+}
+
+/* Checked */
+.a1-checkbox-item__input:checked {
+  background-color: var(--semantic-color-status-info-background);
+  border-color: var(--semantic-color-status-info-background);
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'%3E%3Cpolyline points='2,6 5,9.5 10,3' fill='none' stroke='%23fafcff' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: center;
+  background-size: var(--component-checkbox-group-icon-size);
+}
+
+/* Indeterminate */
+.a1-checkbox-item__input:indeterminate {
+  background-color: var(--semantic-color-status-info-background);
+  border-color: var(--semantic-color-status-info-background);
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'%3E%3Cline x1='3' y1='6' x2='9' y2='6' stroke='%23fafcff' stroke-width='2' stroke-linecap='round'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: center;
+  background-size: var(--component-checkbox-group-icon-size);
+}
+
+/* Disabled (unchecked) */
+.a1-checkbox-item__input:disabled {
+  background-color: var(--semantic-color-surface-raised);
+  border-color: var(--semantic-color-border-subtle);
+  cursor: not-allowed;
+}
+
+/* Disabled + checked */
+.a1-checkbox-item__input:checked:disabled {
+  background-color: var(--semantic-color-border-default);
+  border-color: var(--semantic-color-border-default);
+}
+
+/* ─── Inline layout ───────────────────────────────────────────────────────── */
+
+.a1-checkbox-group--inline .a1-checkbox-group__items {
+  flex-direction: row;
+  flex-wrap: wrap;
+  gap: var(--a1-cb-gap);
+}
+
+/* Each inline item becomes a bordered pill — provides visual separation */
+.a1-checkbox-group--inline .a1-checkbox-item {
+  margin-inline: 0;
+  border: var(--component-field-border-width) solid var(--semantic-color-border-subtle);
+}
+
+/* Unchecked inline hover — darken border */
+.a1-checkbox-group--inline .a1-checkbox-item:not(.a1-checkbox-item--disabled):hover {
+  border-color: var(--a1-field-hover-border-color);
+}
+
+/* Checked inline item — accent border + background tint */
+.a1-checkbox-group--inline .a1-checkbox-item:not(.a1-checkbox-item--disabled):has(.a1-checkbox-item__input:checked) {
+  border-color: var(--semantic-color-status-info-background);
+}
+
+/* Checked inline hover — keep accent border, deepen background */
+.a1-checkbox-group--inline .a1-checkbox-item:not(.a1-checkbox-item--disabled):hover:has(.a1-checkbox-item__input:checked) {
+  border-color: var(--semantic-color-status-info-background);
+}
+
+/* Disabled inline item */
+.a1-checkbox-group--inline .a1-checkbox-item--disabled {
+  border-color: var(--semantic-color-border-subtle);
+  opacity: var(--component-checkbox-group-disabled-opacity);
+}
+
+/* Inline error — left accent doesn't suit a row layout; just use input borders */
+.a1-checkbox-group--inline.a1-checkbox-group--error .a1-checkbox-group__items {
+  border-left: none;
+  padding-left: 0;
+}
+
+/* ─── Error state ─────────────────────────────────────────────────────────── */
+
+/* Left accent border on the items block makes the error scope obvious at a glance */
+.a1-checkbox-group--error .a1-checkbox-group__items {
+  border-left: var(--component-checkbox-group-error-accent-width) solid var(--semantic-color-status-error-background);
+  padding-left: var(--base-spacing-12);
+}
+
+/* Unchecked items get a red border too */
+.a1-checkbox-group--error .a1-checkbox-item__input:not(:checked):not(:disabled) {
+  border-color: var(--semantic-color-status-error-border);
+}
+
+/* Bolder error message */
+.a1-checkbox-group__message--error {
+  font-weight: var(--component-checkbox-group-error-message-font-weight);
+}

package/src/components/cluster/Cluster.jsx

@@ -0,0 +1,52 @@
+import "./cluster.css";
+import { resolveSpacing } from "../structure-utils.js";
+
+const alignments = ["start", "center", "end", "stretch", "baseline"];
+const justifications = ["start", "center", "end", "between", "around", "evenly"];
+
+const alignMap = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  stretch: "stretch",
+  baseline: "baseline",
+};
+
+const justifyMap = {
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+  between: "space-between",
+  around: "space-around",
+  evenly: "space-evenly",
+};
+
+export function Cluster({
+  as: Component = "div",
+  gap = 8,
+  rowGap,
+  columnGap,
+  align = "center",
+  justify = "start",
+  className = "",
+  children,
+  ...props
+}) {
+  const resolvedAlign = alignments.includes(align) ? align : "center";
+  const resolvedJustify = justifications.includes(justify) ? justify : "start";
+  const gapValue = resolveSpacing(gap);
+
+  const style = {
+    "--a1-cluster-row-gap": resolveSpacing(rowGap) ?? gapValue,
+    "--a1-cluster-column-gap": resolveSpacing(columnGap) ?? gapValue,
+    "--a1-cluster-align": alignMap[resolvedAlign],
+    "--a1-cluster-justify": justifyMap[resolvedJustify],
+    ...props.style,
+  };
+
+  return (
+    <Component className={["a1-cluster", className].filter(Boolean).join(" ")} style={style} {...props}>
+      {children}
+    </Component>
+  );
+}