@boostdev/design-system-components 2.8.0 → 2.11.0

package/src/components/ui/Collapsible/Collapsible.tsx

@@ -12,7 +12,11 @@ export interface CollapsibleProps extends WithClassName, Omit<HTMLAttributes<HTM
   open?: boolean;
   /** Uncontrolled initial open state */
   defaultOpen?: boolean;
-  /** Called after each toggle with the new open state */
+  /**
+   * Called on toggle with the new open state. When `open` is controlled,
+   * this reports the requested next state instead of applying it — update
+   * `open` in response to actually expand or collapse the panel.
+   */
   onToggle?: (open: boolean) => void;
   /**
    * Groups multiple Collapsible elements so only one is open at a time
@@ -31,10 +35,23 @@ export function Collapsible({
   className,
   ...rest
 }: Readonly<CollapsibleProps>) {
+  const isControlled = open !== undefined;
+
   const handleToggle = (e: SyntheticEvent<HTMLDetailsElement>) => {
+    // Controlled instances report state changes via handleSummaryClick
+    // instead, so the native toggle is prevented before this ever fires.
+    if (isControlled) return;
     onToggle?.(e.currentTarget.open);
   };
 
+  const handleSummaryClick = (e: SyntheticEvent<HTMLElement>) => {
+    if (!isControlled) return;
+    // Own the toggle: cancel the native open/close and let the consumer
+    // decide the next state by updating the `open` prop in response.
+    e.preventDefault();
+    onToggle?.(!open);
+  };
+
   return (
     <details
       className={cn(css.collapsible, className)}
@@ -43,7 +60,7 @@ export function Collapsible({
       onToggle={handleToggle}
       {...rest}
     >
-      <summary className={css.summary}>
+      <summary className={css.summary} onClick={handleSummaryClick}>
         <span className={css.summaryContent}>{summary}</span>
         <span className={css.icon} aria-hidden="true" />
       </summary>

package/src/components/ui/DescriptionList/DescriptionList.mdx

@@ -21,6 +21,8 @@ Key-value pairs rendered as a semantic `<dl>` element. Supports stacked and inli
 
 ## Props
 
+> **HTML attributes** — all standard HTML attributes for the root element are forwarded via `{...rest}` (`id`, `className`, `style`, `data-*`, `aria-*`, event handlers, etc.). Component-controlled attributes take precedence.
+
 <ArgTypes of={Stories} />
 
 ## Accessibility

package/src/components/ui/Link/Link.mdx

@@ -5,7 +5,7 @@ import * as Stories from './Link.stories';
 
 # Link
 
-Styled anchor element with three visual variants. Renders as `<a>` by default, but can be rendered as a `<button>` or any other element via the `component` prop.
+Styled anchor element with three visual variants. Renders as `<a>` by default, but can be rendered as a `<button>` or any other element via the `as` prop.
 
 ## When to use
 - Navigation to another page or route
@@ -36,6 +36,8 @@ Styled anchor element with three visual variants. Renders as `<a>` by default, b
 
 ## Props
 
+> **HTML attributes** — all standard HTML attributes for the root element are forwarded via `{...rest}` (`id`, `className`, `style`, `data-*`, `aria-*`, event handlers, etc.). Component-controlled attributes take precedence.
+
 <ArgTypes of={Stories} />
 
 ## CSS variables
@@ -73,4 +75,4 @@ Defaults: `default` and `standalone` resolve to `--bds-color_interactive_on-bg`
 ## Accessibility
 
 - External links add `target="_blank"` with `rel="noopener noreferrer"` and a visually-hidden "(opens in new tab)" label
-- The `as` prop allows any element while maintaining link semantics via `role`
+- The `as` prop lets you render any element (e.g. `button`, `span`), but it does not add a `role` or `href` for you — when rendering as a non-`<a>` element, pass `role` and/or `href`/`onClick` yourself so the element keeps the correct semantics

package/src/components/ui/Loading/Loading.mdx

@@ -31,6 +31,8 @@ Animated spinner that communicates an in-progress operation.
 
 ## Props
 
+> **HTML attributes** — all standard HTML attributes for the root element are forwarded via `{...rest}` (`id`, `className`, `style`, `data-*`, `aria-*`, event handlers, etc.). Component-controlled attributes take precedence.
+
 <ArgTypes of={Stories} />
 
 ## CSS variables
@@ -41,12 +43,13 @@ Animated spinner that communicates an in-progress operation.
 <tr><th>Variable</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--loading_color`</td><td>Spinner stroke colour (defaults to `currentcolor`)</td></tr>
+<tr><td>`--loading_color`</td><td>Spinner stroke colour (defaults to `var(--bds-color_interactive)`)</td></tr>
+<tr><td>`--loading_radius`</td><td>Spinner border radius (defaults to `var(--bds-border_radius--circle)`)</td></tr>
 </tbody>
 </table>
 
 
 ## Accessibility
 
-- Renders with `role="status"` and a visually-hidden "Loading…" label
-- Animation respects `prefers-reduced-motion` — the spinner fades instead of spinning
+- Renders with `role="status"` and an accessible name of `aria-label="Loading"` on the root element — pass your own `aria-label` to override it
+- Animation respects `prefers-reduced-motion` — the spin animation is disabled entirely instead of spinning

package/src/components/ui/Loading/Loading.module.css

@@ -9,7 +9,7 @@
     inline-size: 2.5em;
     block-size: 2.5em;
     border: 4px solid var(--bds-color_bg);
-    border-block-start: 4px solid var(--bds-color_interactive);
+    border-block-start: 4px solid var(--loading_color, var(--bds-color_interactive));
     border-radius: var(--loading_radius, var(--bds-border_radius--circle));
     animation: spin 1s linear infinite;
   }
@@ -25,15 +25,15 @@
     block-size: 4em;
     border-width: 6px;
   }
+
+  @media (prefers-reduced-motion: reduce) {
+    .spinner {
+      animation: none;
+    }
+  }
 }
 
 @keyframes spin {
   0% { transform: rotate(0deg); }
   100% { transform: rotate(360deg); }
 }
-
-@media (prefers-reduced-motion: reduce) {
-  .spinner {
-    animation: none;
-  }
-}

package/src/components/ui/Loading/Loading.spec.tsx

@@ -16,4 +16,16 @@ describe('Loading', () => {
     const { container } = render(<Loading className="custom" />);
     expect(container.firstChild).toHaveClass('custom');
   });
+
+  it('puts the status role and accessible name on the root element receiving forwarded attributes', () => {
+    const { container } = render(<Loading data-testid="spinner" />);
+    const status = screen.getByRole('status');
+    expect(status).toBe(container.firstChild);
+    expect(status).toHaveAttribute('data-testid', 'spinner');
+  });
+
+  it('allows a consumer aria-label to override the default accessible name', () => {
+    render(<Loading aria-label="Fetching results" />);
+    expect(screen.getByRole('status', { name: 'Fetching results' })).toBeInTheDocument();
+  });
 });

package/src/components/ui/Loading/Loading.tsx

@@ -7,10 +7,15 @@ interface LoadingProps extends WithClassName, HTMLAttributes<HTMLDivElement> {
   size?: 'small' | 'medium' | 'large';
 }
 
-export function Loading({ size = 'medium', className, ...rest }: LoadingProps) {
+export function Loading({ size = 'medium', className, 'aria-label': ariaLabel, ...rest }: LoadingProps) {
   return (
-    <div {...rest} className={cn(css.loading, css[`--size_${size}`], className)}>
-      <div className={css.spinner} role="status" aria-label="Loading" />
+    <div
+      role="status"
+      aria-label={ariaLabel ?? 'Loading'}
+      {...rest}
+      className={cn(css.loading, css[`--size_${size}`], className)}
+    >
+      <div className={css.spinner} />
     </div>
   );
 }

package/src/components/ui/NotificationBanner/NotificationBanner.mdx

@@ -37,6 +37,8 @@ Full-width banner for page-level system messages. Sits at the top of the page or
 
 ## Props
 
+> **HTML attributes** — all standard HTML attributes for the root element are forwarded via `{...rest}` (`id`, `className`, `style`, `data-*`, `aria-*`, event handlers, etc.). Component-controlled attributes take precedence.
+
 <ArgTypes of={Stories} />
 
 ## CSS variables
@@ -56,6 +58,7 @@ The override surface is **layered**. Setting a public token on the banner (or an
 <tr><td>`--banner_dismiss-radius`</td><td>`var(--bds-border_radius--circle)`</td><td>Dismiss button border radius.</td></tr>
 <tr><td>`--banner_dismiss-border`</td><td>`none`</td><td>Dismiss button border.</td></tr>
 <tr><td>`--banner_dismiss-opacity--hover`</td><td>`0.7`</td><td>Dismiss button opacity on hover.</td></tr>
+<tr><td>`--banner_dismiss-size`</td><td>`2.75rem`</td><td>Dismiss button minimum hit area (44x44px, WCAG 2.5.5). The 1rem icon stays centered inside it.</td></tr>
 </tbody>
 </table>
 
@@ -80,3 +83,4 @@ Defaults resolve to the corresponding foundation tokens.
 
 - Uses `role="alert"` for error/warning variants and `role="status"` for info/success
 - Dismiss button has `aria-label="Dismiss notification"`
+- Dismiss button has a minimum 44x44px hit area (WCAG 2.5.5) even though its icon renders at 1rem

package/src/components/ui/NotificationBanner/NotificationBanner.module.css

@@ -55,6 +55,11 @@
     flex-shrink: 0;
     cursor: pointer;
     color: currentcolor;
+
+    /* WCAG 2.5.5: minimum 44x44px interactive area — the visible icon stays
+       1rem; the hit area grows around it via min-inline-size/min-block-size. */
+    min-inline-size: var(--banner_dismiss-size, 2.75rem);
+    min-block-size: var(--banner_dismiss-size, 2.75rem);
     border-radius: var(--banner_dismiss-radius, var(--bds-border_radius--circle));
     border: var(--banner_dismiss-border, none);
     transition: var(--bds-animation_transition);

package/src/components/ui/NotificationBanner/NotificationBanner.spec.tsx

@@ -1,7 +1,14 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { NotificationBanner } from './NotificationBanner';
 
+const cssSource = readFileSync(
+  resolve(process.cwd(), 'src/components/ui/NotificationBanner/NotificationBanner.module.css'),
+  'utf8',
+);
+
 describe('NotificationBanner', () => {
   it('renders children', () => {
     render(<NotificationBanner>System maintenance scheduled</NotificationBanner>);
@@ -39,4 +46,17 @@ describe('NotificationBanner', () => {
     render(<NotificationBanner action={<button>View details</button>}>Msg</NotificationBanner>);
     expect(screen.getByRole('button', { name: 'View details' })).toBeInTheDocument();
   });
+
+  it('gives the dismiss button a 44x44px minimum hit area (WCAG 2.5.5)', () => {
+    // jsdom has no layout engine, so this can't be asserted via
+    // getBoundingClientRect(); pin the contract in the CSS source instead
+    // (same approach as FieldGroup.spec.tsx). The visible icon (1rem) can
+    // stay small — only the interactive hit area must reach 44px (2.75rem).
+    const dismissRuleMatch = cssSource.match(/\.dismiss\s*{[^}]*}/);
+    expect(dismissRuleMatch).not.toBeNull();
+    const dismissRule = dismissRuleMatch?.[0] ?? '';
+
+    expect(dismissRule).toMatch(/min-inline-size:\s*var\(--banner_dismiss-size,\s*2\.75rem\)/);
+    expect(dismissRule).toMatch(/min-block-size:\s*var\(--banner_dismiss-size,\s*2\.75rem\)/);
+  });
 });

package/src/components/ui/Pagination/Pagination.mdx

@@ -30,11 +30,13 @@ Navigation control for paged data sets. Renders prev/next buttons plus numbered
 
 ## Props
 
+> **HTML attributes** — all standard HTML attributes for the root element are forwarded via `{...rest}` (`id`, `className`, `style`, `data-*`, `aria-*`, event handlers, etc.). Component-controlled attributes take precedence.
+
 <ArgTypes of={Stories} />
 
 ## CSS variables
 
-The override surface is **layered**. Setting `--btn_bg` / `--btn_color` / `--btn_border` on the pagination (or any ancestor) wins in every state — resting, hover, and active. Setting per-state tokens targets only that one state.
+The override surface is **layered**. Setting `--pagination_item-bg` / `--pagination_item-color` / `--pagination_item-border` on the pagination (or any ancestor) wins in every state — resting, hover, and active. Setting per-state tokens targets only that one state.
 
 ### Public override tokens (win over per-state defaults)
 
@@ -44,9 +46,9 @@ The override surface is **layered**. Setting `--btn_bg` / `--btn_color` / `--btn
 </thead>
 <tbody>
 <tr><td>`--pagination_radius`</td><td>`var(--bds-border_radius--full)`</td><td>Page button border radius.</td></tr>
-<tr><td>`--btn_bg`</td><td>`transparent` (per state)</td><td>Button background. Set to theme every state at once.</td></tr>
-<tr><td>`--btn_color`</td><td>per state</td><td>Button text colour.</td></tr>
-<tr><td>`--btn_border`</td><td>per state</td><td>Button border colour.</td></tr>
+<tr><td>`--pagination_item-bg`</td><td>`transparent` (per state)</td><td>Button background. Set to theme every state at once.</td></tr>
+<tr><td>`--pagination_item-color`</td><td>per state</td><td>Button text colour.</td></tr>
+<tr><td>`--pagination_item-border`</td><td>per state</td><td>Button border colour.</td></tr>
 </tbody>
 </table>
 
@@ -58,16 +60,36 @@ The override surface is **layered**. Setting `--btn_bg` / `--btn_color` / `--btn
 </thead>
 <tbody>
 <tr><td>resting</td><td>(`transparent`)</td><td>(`var(--bds-color_on-bg)`)</td><td>(`var(--bds-color_bg--subtle)`)</td></tr>
-<tr><td>hover</td><td>`--btn_bg--hover`</td><td>`--btn_color--hover`</td><td>—</td></tr>
-<tr><td>active (current page)</td><td>`--btn_bg--active`</td><td>`--btn_color--active`</td><td>`--btn_border--active`</td></tr>
+<tr><td>hover</td><td>`--pagination_item-bg--hover`</td><td>`--pagination_item-color--hover`</td><td>—</td></tr>
+<tr><td>active (current page)</td><td>`--pagination_item-bg--active`</td><td>`--pagination_item-color--active`</td><td>`--pagination_item-border--active`</td></tr>
 </tbody>
 </table>
 
-Defaults: hover resolves to `--bds-color_bg--subtle` / `--bds-color_interactive_on-bg`; active resolves to `--bds-color_interactive` / `--bds-color_on-interactive`.
+Defaults: hover resolves to `--bds-color_bg--subtle` / `--bds-color_interactive_on-bg`; active resolves through the shared `--bdc-color_active` / `--bdc-color_on-active` hooks (`--bds-color_interactive` / `--bds-color_on-interactive` by default), so a global active-state theme override also re-colours the current page.
+
+### Deprecated aliases
+
+The original `--btn_*` token names are still read as a fallback layer beneath the `--pagination_item-*` names above, so existing overrides keep working. Prefer the new names for new code.
 
+<table>
+<thead>
+<tr><th>Deprecated</th><th>Use instead</th></tr>
+</thead>
+<tbody>
+<tr><td>`--btn_bg`</td><td>`--pagination_item-bg`</td></tr>
+<tr><td>`--btn_color`</td><td>`--pagination_item-color`</td></tr>
+<tr><td>`--btn_border`</td><td>`--pagination_item-border`</td></tr>
+<tr><td>`--btn_bg--hover`</td><td>`--pagination_item-bg--hover`</td></tr>
+<tr><td>`--btn_color--hover`</td><td>`--pagination_item-color--hover`</td></tr>
+<tr><td>`--btn_bg--active`</td><td>`--pagination_item-bg--active`</td></tr>
+<tr><td>`--btn_color--active`</td><td>`--pagination_item-color--active`</td></tr>
+<tr><td>`--btn_border--active`</td><td>`--pagination_item-border--active`</td></tr>
+</tbody>
+</table>
 
 ## Accessibility
 
 - Wraps in `<nav aria-label="Pagination">`
 - Current page button has `aria-current="page"`
 - Prev/next buttons are disabled (not just hidden) when at the boundary
+- Page buttons meet the 44×44px (2.75rem) WCAG 2.5.5 minimum touch target

package/src/components/ui/Pagination/Pagination.module.css

@@ -22,16 +22,17 @@
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    min-inline-size: 2.25rem;
-    block-size: 2.25rem;
+    min-inline-size: 2.75rem;
+    block-size: 2.75rem;
     padding-inline: var(--bds-space_xs);
     border-radius: var(--pagination_radius, var(--bds-border_radius--full));
 
-    /* Layered cascade: public overrides (--btn_bg, --btn_color, --btn_border) win
-       over per-state defaults. Hover/active write to the inner --btn_*--state slot. */
-    background-color: var(--btn_bg, var(--btn_bg--state, transparent));
-    color:            var(--btn_color, var(--btn_color--state, var(--bds-color_on-bg)));
-    --bdc_color:      var(--btn_border, var(--btn_border--state, var(--bds-color_bg--subtle)));
+    /* Layered cascade: public overrides (--pagination_item-bg, --pagination_item-color,
+       --pagination_item-border) win over per-state defaults. The old --btn_* names are
+       kept as deprecated aliases. Hover/active write to the inner --btn_*--state slot. */
+    background-color: var(--pagination_item-bg, var(--btn_bg, var(--btn_bg--state, transparent)));
+    color:            var(--pagination_item-color, var(--btn_color, var(--btn_color--state, var(--bds-color_on-bg))));
+    --bdc_color:      var(--pagination_item-border, var(--btn_border, var(--btn_border--state, var(--bds-color_bg--subtle))));
 
     border: none;
     box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
@@ -55,15 +56,15 @@
 
   @media (hover: hover) and (pointer: fine) {
     .button:not(:disabled, .--active):hover {
-      --btn_bg--state:    var(--btn_bg--hover, var(--bds-color_bg--subtle));
-      --btn_color--state: var(--btn_color--hover, var(--bds-color_interactive_on-bg));
+      --btn_bg--state:    var(--pagination_item-bg--hover, var(--btn_bg--hover, var(--bds-color_bg--subtle)));
+      --btn_color--state: var(--pagination_item-color--hover, var(--btn_color--hover, var(--bds-color_interactive_on-bg)));
     }
   }
 
   .button.--active {
-    --btn_bg--state:     var(--btn_bg--active, var(--bds-color_interactive));
-    --btn_color--state:  var(--btn_color--active, var(--bds-color_on-interactive));
-    --btn_border--state: var(--btn_border--active, var(--bds-color_interactive));
+    --btn_bg--state:     var(--pagination_item-bg--active, var(--btn_bg--active, var(--bdc-color_active)));
+    --btn_color--state:  var(--pagination_item-color--active, var(--btn_color--active, var(--bdc-color_on-active)));
+    --btn_border--state: var(--pagination_item-border--active, var(--btn_border--active, var(--bdc-color_active)));
   }
 
   .button.--nav svg {
@@ -75,8 +76,8 @@
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    min-inline-size: 2.25rem;
-    block-size: 2.25rem;
+    min-inline-size: 2.75rem;
+    block-size: 2.75rem;
     color: var(--bds-color_on-bg--subtle);
     font-size: var(--bds-font_size--body);
     user-select: none;

package/src/components/ui/Progress/Progress.mdx

@@ -30,6 +30,8 @@ Horizontal progress bar communicating completion towards a goal.
 
 ## Props
 
+> **HTML attributes** — all standard HTML attributes for the root element are forwarded via `{...rest}` (`id`, `className`, `style`, `data-*`, `aria-*`, event handlers, etc.). Component-controlled attributes take precedence.
+
 <ArgTypes of={Stories} />
 
 ## CSS variables
@@ -41,12 +43,14 @@ Horizontal progress bar communicating completion towards a goal.
 </thead>
 <tbody>
 <tr><td>`--progress_color-active`</td><td>Filled track colour (defaults to `var(--bdc-color_active)`)</td></tr>
-<tr><td>`--progress_color-track`</td><td>Empty track colour</td></tr>
+<tr><td>`--progress_color-track`</td><td>Empty track colour (defaults to `var(--bds-color_bg--subtle)`)</td></tr>
+<tr><td>`--progress_radius`</td><td>Track and fill corner radius (defaults to `var(--bds-border_radius--full)`)</td></tr>
+<tr><td>`--progress_height`</td><td>Track block-size (defaults per `size`: `--bds-space_xxs`/`--bds-space_xs`/`--bds-space_s`)</td></tr>
 </tbody>
 </table>
 
 
 ## Accessibility
 
-- Uses `<progress>` element with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
+- Uses `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
 - `label` prop sets `aria-label` — always provide a meaningful label

package/src/components/ui/Progress/Progress.module.css

@@ -21,7 +21,7 @@
   .track {
     inline-size: 100%;
     block-size: var(--progress_height, var(--bds-space_xs));
-    background-color: var(--bds-color_bg--subtle);
+    background-color: var(--progress_color-track, var(--bds-color_bg--subtle));
     border-radius: var(--progress_radius, var(--bds-border_radius--full));
     overflow: hidden;
   }

package/src/components/ui/Progress/Progress.spec.tsx

@@ -52,4 +52,21 @@ describe('Progress', () => {
     render(<Progress value={-10} label="Empty" showLabel />);
     expect(screen.getByText('0%')).toBeInTheDocument();
   });
+
+  it('clamps aria-valuenow to max when value exceeds max', () => {
+    render(<Progress value={150} label="Overloaded" />);
+    expect(screen.getByRole('progressbar')).toHaveAttribute('aria-valuenow', '100');
+  });
+
+  it('clamps aria-valuenow to 0 when value is negative', () => {
+    render(<Progress value={-10} label="Empty" />);
+    expect(screen.getByRole('progressbar')).toHaveAttribute('aria-valuenow', '0');
+  });
+
+  it('sets fill inline-size via the logical inlineSize style property', () => {
+    const { container } = render(<Progress value={40} label="Loading" />);
+    const fill = container.querySelector('.fill') as HTMLElement;
+    expect(fill.style.inlineSize).toBe('40%');
+    expect(fill.style.width).toBe('');
+  });
 });

package/src/components/ui/Progress/Progress.tsx

@@ -33,12 +33,12 @@ export function Progress({
       <div
         role="progressbar"
         aria-label={label}
-        aria-valuenow={value}
+        aria-valuenow={Math.min(max, Math.max(0, value))}
         aria-valuemin={0}
         aria-valuemax={max}
         className={cn(css.track, css[`--size_${size}`])}
       >
-        <div className={css.fill} style={{ width: `${percentage}%` }} />
+        <div className={css.fill} style={{ inlineSize: `${percentage}%` }} />
       </div>
     </div>
   );

package/src/components/ui/ProgressCircle/ProgressCircle.mdx

@@ -24,6 +24,8 @@ Circular progress indicator. Use when a compact representation fits better than
 
 ## Props
 
+> **HTML attributes** — all standard HTML attributes for the root element are forwarded via `{...rest}` (`id`, `className`, `style`, `data-*`, `aria-*`, event handlers, etc.). Component-controlled attributes take precedence.
+
 <ArgTypes of={Stories} />
 
 ## CSS variables
@@ -34,13 +36,15 @@ Circular progress indicator. Use when a compact representation fits better than
 <tr><th>Variable</th><th>Description</th></tr>
 </thead>
 <tbody>
-<tr><td>`--progress-circle_color-active`</td><td>Arc stroke colour</td></tr>
-<tr><td>`--progress-circle_color-track`</td><td>Background circle colour</td></tr>
+<tr><td>`--progressCircle_color-active`</td><td>Arc stroke colour</td></tr>
+<tr><td>`--progressCircle_color-track`</td><td>Background circle colour</td></tr>
+<tr><td>`--progressCircle_font-size--small`</td><td>Value label font size at `size="small"`</td></tr>
 </tbody>
 </table>
 
 
 ## Accessibility
 
-- SVG uses `role="img"` with an `aria-label` derived from `label` and current value
-- Numeric value is visually rendered when `showValue` is true; screen readers announce via `aria-valuenow`
+- The root `<div>` uses `role="progressbar"` with `aria-label={label}` plus `aria-valuenow`/`aria-valuemin`/`aria-valuemax`
+- The SVG arc is decorative and hidden from assistive technology via `aria-hidden`
+- Numeric value is visually rendered when `showValue` is true; screen readers announce progress via the `aria-valuenow` on the root element

package/src/components/ui/ProgressCircle/ProgressCircle.module.css

@@ -11,7 +11,7 @@
   }
 
   .track {
-    stroke: var(--bds-color_bg--subtle);
+    stroke: var(--progressCircle_color-track, var(--bds-color_bg--subtle));
   }
 
   .fill {
@@ -28,7 +28,7 @@
     line-height: 1;
   }
 
-  .--size_small .value  { font-size: 0.5rem; }
+  .--size_small .value  { font-size: var(--progressCircle_font-size--small, var(--bds-font_size--body--s)); }
   .--size_medium .value { font-size: var(--bds-font_size--body--s); }
   .--size_large .value  { font-size: var(--bds-font_size--body); }
 

package/src/components/ui/ProgressCircle/ProgressCircle.spec.tsx

@@ -19,7 +19,17 @@ describe('ProgressCircle', () => {
 
   it('clamps values above max', () => {
     render(<ProgressCircle value={150} label="Progress" />);
-    expect(screen.getByRole('progressbar')).toHaveAttribute('aria-valuenow', '150');
+    expect(screen.getByRole('progressbar')).toHaveAttribute('aria-valuenow', '100');
+  });
+
+  it('clamps aria-valuenow below min', () => {
+    render(<ProgressCircle value={-20} label="Progress" />);
+    expect(screen.getByRole('progressbar')).toHaveAttribute('aria-valuenow', '0');
+  });
+
+  it('clamps aria-valuenow to a custom max', () => {
+    render(<ProgressCircle value={999} max={200} label="Progress" />);
+    expect(screen.getByRole('progressbar')).toHaveAttribute('aria-valuenow', '200');
   });
 
   it('shows percentage value when showValue is true', () => {

package/src/components/ui/ProgressCircle/ProgressCircle.tsx

@@ -35,7 +35,7 @@ export function ProgressCircle({
       {...rest}
       role="progressbar"
       aria-label={label}
-      aria-valuenow={value}
+      aria-valuenow={Math.min(max, Math.max(0, value))}
       aria-valuemin={0}
       aria-valuemax={max}
       className={cn(css.wrapper, css[`--size_${size}`], className)}

package/src/components/ui/Separator/Separator.mdx

@@ -21,6 +21,8 @@ Visual divider between content sections. Renders a semantic `<hr>` (horizontal)
 
 ## Props
 
+> **HTML attributes** — all standard HTML attributes for the root element are forwarded via `{...rest}` (`id`, `className`, `style`, `data-*`, `aria-*`, event handlers, etc.). Component-controlled attributes take precedence.
+
 <ArgTypes of={Stories} />
 
 ## CSS variables
@@ -33,6 +35,7 @@ Visual divider between content sections. Renders a semantic `<hr>` (horizontal)
 <tbody>
 <tr><td>`--separator_color`</td><td>`var(--bds-color_on-bg)`</td><td>Line colour</td></tr>
 <tr><td>`--separator_thickness`</td><td>`1px`</td><td>Line thickness (height for horizontal, width for vertical)</td></tr>
+<tr><td>`--separator_length`</td><td>`1em`</td><td>Minimum height of the vertical separator when rendered outside a flex/grid container. Inside a flex or grid container the separator still stretches to fill the cross axis (`align-self: stretch`) — this token only sets a floor for standalone usage.</td></tr>
 </tbody>
 </table>
 
@@ -41,3 +44,7 @@ Visual divider between content sections. Renders a semantic `<hr>` (horizontal)
 
 - Horizontal variant uses `<hr>` — natively announces a thematic break to screen readers
 - Vertical variant uses `role="separator"` with `aria-orientation="vertical"`
+
+## Layout notes
+
+- The vertical separator relies on `align-self: stretch` to fill the height of a flex or grid parent. Outside such a container it falls back to `min-block-size: var(--separator_length, 1em)` so it never collapses to zero height.

package/src/components/ui/Separator/Separator.module.css

@@ -13,6 +13,7 @@
   .separator.--vertical {
     display: inline-block;
     inline-size: var(--separator_thickness, 1px);
+    min-block-size: var(--separator_length, 1em);
     align-self: stretch;
   }
 }

package/src/components/ui/Skeleton/Skeleton.mdx

@@ -28,9 +28,26 @@ Layout-preserving placeholder shown while content is loading. Renders a shimmer
 
 ## Props
 
+> **HTML attributes** — all standard HTML attributes for the root element are forwarded via `{...rest}` (`id`, `className`, `style`, `data-*`, `aria-*`, event handlers, etc.). Component-controlled attributes take precedence.
+
 <ArgTypes of={Stories} />
 
+## CSS variables
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--skeleton_color-base`</td><td>Gradient base colour (defaults to `var(--bds-color_grey--subtle)`)</td></tr>
+<tr><td>`--skeleton_color-highlight`</td><td>Gradient highlight colour that sweeps across the base (defaults to `var(--bds-color_bg)`)</td></tr>
+<tr><td>`--skeleton_radius`</td><td>Corner radius (defaults to `var(--bds-border_radius--xs)`)</td></tr>
+<tr><td>`--skeleton_min-block-size`</td><td>Minimum block-size when no height is set via `className`/inline style (defaults to `var(--bds-space_m)`)</td></tr>
+</tbody>
+</table>
+
 ## Accessibility
 
 - Renders `aria-hidden="true"` — skeleton blocks are invisible to screen readers
 - The containing region should use `aria-busy="true"` while loading, then `aria-live="polite"` when content arrives
+- The shimmer animation respects `prefers-reduced-motion: reduce` — it is disabled and replaced with a static base colour

package/src/components/ui/Skeleton/Skeleton.module.css

@@ -2,14 +2,21 @@
   .skeleton {
     background: linear-gradient(
       90deg,
-      var(--bds-color_grey--subtle) 25%,
-      var(--bds-color_bg) 50%,
-      var(--bds-color_grey--subtle) 75%
+      var(--skeleton_color-base, var(--bds-color_grey--subtle)) 25%,
+      var(--skeleton_color-highlight, var(--bds-color_bg)) 50%,
+      var(--skeleton_color-base, var(--bds-color_grey--subtle)) 75%
     );
     background-size: 200% 100%;
     animation: shimmer 1.5s infinite;
-    border-radius: var(--bds-border_radius--xs);
-    min-block-size: var(--bds-space_m);
+    border-radius: var(--skeleton_radius, var(--bds-border_radius--xs));
+    min-block-size: var(--skeleton_min-block-size, var(--bds-space_m));
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .skeleton {
+      animation: none;
+      background: var(--skeleton_color-base, var(--bds-color_grey--subtle));
+    }
   }
 }