@boostdev/design-system-components 2.7.1 → 2.11.0

package/src/web-components/ui/BdsCalendarRange.mdx

@@ -0,0 +1,71 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsCalendarRange.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-calendar-range&gt;
+
+Form-associated range date picker custom element. Two-click selection with
+hover/focus preview; value is an ISO range `"YYYY-MM-DD/YYYY-MM-DD"`.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/design-system-components/web-components';
+```
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With a preselected range
+<Canvas of={Stories.WithValue} />
+
+### Two months
+<Canvas of={Stories.TwoMonths} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | string | — | Form field name |
+| `value` | string | — | Selected range, `"YYYY-MM-DD/YYYY-MM-DD"` |
+| `disabled` | boolean | `false` | Disables all interaction |
+| `min` / `max` | string | — | Selectable bounds (ISO 8601) |
+| `months` | number | `1` | Number of months shown side by side |
+| `page-by` | `"months"` \| `"single"` | `"months"` | Pagination step |
+| `first-day-of-week` | number (0–6) | `1` | First weekday column (Monday) |
+| `locale` | string | runtime default | `Intl` locale for date text |
+| `previous-label` / `next-label` | string | English | Nav button aria-labels |
+
+## Properties (JS only)
+
+`isDateDisallowed(date) => boolean`, `formatWeekday(date)`, `formatMonth(date)`,
+`formatDay(date)` — set on the element instance to override defaults.
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `bds-range-select` | `{ start: string, end: string }` | Fired when both ends are chosen (sorted) |
+| `bds-range-start` | `{ start: string }` | Fired on the first click |
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| Arrow keys | Move focus between days |
+| Home / End | Start / end of week |
+| Page Up / Down | Previous / next month |
+| Shift + Page Up / Down | Previous / next year |
+| Enter / Space | Pick start, then end |
+| Escape | Cancel an in-progress range |
+
+## Accessibility
+
+- Full ARIA grid pattern with roving tabindex, matching `<bds-calendar>`
+- Range start and end carry `aria-selected="true"` on their gridcell
+- Respects `disabled`, `formDisabledCallback`, and `prefers-reduced-motion`

package/src/web-components/ui/BdsCalendarRange.stories.tsx

@@ -0,0 +1,31 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsCalendarRange({
+  name, value, min, max, months,
+}: {
+  name?: string; value?: string; min?: string; max?: string; months?: number;
+}) {
+  return React.createElement('bds-calendar-range', { name, value, min, max, months });
+}
+
+const meta = {
+  title: 'Web Components/UI/CalendarRange',
+  component: BdsCalendarRange,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    value:  { control: 'text' },
+    min:    { control: 'text' },
+    max:    { control: 'text' },
+    months: { control: 'number' },
+  },
+} satisfies Meta<typeof BdsCalendarRange>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { args: {} };
+export const WithValue: Story = { args: { value: '2026-04-10/2026-04-16' } };
+export const TwoMonths: Story = { args: { value: '2026-04-10/2026-04-16', months: 2 } };

package/src/web-components/ui/BdsCard.mdx

@@ -5,7 +5,7 @@ import * as Stories from './BdsCard.stories';
 
 # <bds-card>
 
-Framework-agnostic Card layout custom element. A versatile container with three visual variants, text alignment, and an optional clickable mode. Padding is controlled via the `--card_padding` CSS custom property.
+Framework-agnostic Card layout custom element. A versatile container with three visual variants, five padding variants, text alignment, and an optional clickable mode. Each padding variant's resolved value can be overridden via the `--card_padding` CSS custom property.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -25,6 +25,9 @@ import '@boostdev/design-system-components/web-components';
 ### All variants
 <Canvas of={Stories.AllVariants} />
 
+### All padding variants
+<Canvas of={Stories.AllPaddingVariants} />
+
 ### Default
 <Canvas of={Stories.Default} />
 
@@ -46,6 +49,7 @@ import '@boostdev/design-system-components/web-components';
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `variant` | `"default" \| "elevated" \| "outlined"` | `"default"` | Shadow and border style |
+| `padding` | `"none" \| "small" \| "medium" \| "large" \| "extra-large"` | `"medium"` | Inner padding scale |
 | `text-align` | `"start" \| "center" \| "end"` | `"start"` | Text alignment |
 | `clickable` | boolean | `false` | Renders the card as a `<button>` with hover/active effects |
 | `aria-label` | string | — | Accessible label (recommended when `clickable` is set) |
@@ -66,7 +70,7 @@ import '@boostdev/design-system-components/web-components';
 
 | Property | Description |
 |----------|-------------|
-| `--card_padding` | Inner padding (default: `var(--bds-space_m)`) |
+| `--card_padding` | Overrides the resolved padding value for the active `padding` variant (default: the variant's scale token — `0`, `--bds-space_s`, `--bds-space_m`, `--bds-space_l`, or `--bds-space_xl`) |
 | `--card_color` | Card background colour |
 | `--card_on-color` | Card text/foreground colour |
 | `--card_border` | Border on outlined variant (default: `none`) |
@@ -74,7 +78,7 @@ import '@boostdev/design-system-components/web-components';
 ## Usage in plain HTML
 
 ```html
-<bds-card variant="elevated" style="--card_padding: var(--bds-space_l)">
+<bds-card variant="elevated" padding="large">
   <p>Card content</p>
 </bds-card>
 

package/src/web-components/ui/BdsCard.stories.tsx

@@ -1,16 +1,18 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import type { CardVariant, CardTextAlign } from './bds-card';
+import type { CardVariant, CardPadding, CardTextAlign } from './bds-card';
 import '../index'; // auto-registers all custom elements
 
 function BdsCard({
   variant = 'default',
+  padding = 'medium',
   textAlign = 'start',
   clickable,
   ariaLabel,
   children,
 }: {
   variant?: CardVariant;
+  padding?: CardPadding;
   textAlign?: CardTextAlign;
   clickable?: boolean;
   ariaLabel?: string;
@@ -20,6 +22,7 @@ function BdsCard({
     'bds-card',
     {
       variant,
+      padding,
       'text-align': textAlign,
       clickable: clickable || undefined,
       'aria-label': ariaLabel,
@@ -35,6 +38,7 @@ const meta = {
   parameters: { layout: 'centered' },
   argTypes: {
     variant:   { control: 'select', options: ['default', 'elevated', 'outlined'] },
+    padding:   { control: 'select', options: ['none', 'small', 'medium', 'large', 'extra-large'] },
     textAlign: { control: 'select', options: ['start', 'center', 'end'] },
     clickable: { control: 'boolean' },
   },
@@ -61,3 +65,15 @@ export const AllVariants: Story = {
     </div>
   ),
 };
+
+export const AllPaddingVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 16, flexWrap: 'wrap', maxWidth: 700 }}>
+      {(['none', 'small', 'medium', 'large', 'extra-large'] as const).map(p =>
+        React.createElement('bds-card', { key: p, variant: 'outlined', padding: p, style: { width: 160 } },
+          React.createElement('p', { style: { margin: 0 } }, p),
+        ),
+      )}
+    </div>
+  ),
+};

package/src/web-components/ui/BdsCarousel.mdx

@@ -40,23 +40,34 @@ import '@boostdev/design-system-components/web-components';
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `current-index` | number | `0` | Active slide index (0-based) |
+| `current-index` | number | `0` | Active slide index (0-based). Setting this attribute/property scrolls the track to that slide. |
 | `indicators` | boolean | `false` | Shows dot indicator buttons below the slides |
 | `loop` | boolean | `false` | Wraps from last slide to first and vice versa |
+| `label` | string | `"Carousel"` | Accessible name for the slide region |
+| `prev-label` | string | `"Previous slide"` | Accessible name for the built-in previous button |
+| `next-label` | string | `"Next slide"` | Accessible name for the built-in next button |
 
 ## Slots
 
 | Slot | Description |
 |------|-------------|
-| `(default)` | Slide content — each direct child is one slide |
-| `prev` | Custom previous button (replaces the built-in button) |
-| `next` | Custom next button (replaces the built-in button) |
+| `(default)` | Slide content — each direct child with no `slot` attribute is one slide |
+| `prev` | Custom previous button (replaces the built-in button). Clicks anywhere inside this slot navigate to the previous slide. |
+| `next` | Custom next button (replaces the built-in button). Clicks anywhere inside this slot navigate to the next slide. |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `goTo(index: number)` | Navigate to a specific slide (clamped, or wrapped when `loop` is set) |
+| `next()` | Navigate to the next slide |
+| `prev()` | Navigate to the previous slide |
 
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `bds-slide-change` | `{ index: number }` | Fired when the active slide changes |
+| `bds-slide-change` | `{ index: number }` | Fired when the active slide changes, via navigation (`goTo`/`next`/`prev`, the nav buttons, or a dot) or via manual scroll/swipe |
 
 ## Usage in plain HTML
 
@@ -68,16 +79,33 @@ import '@boostdev/design-system-components/web-components';
 </bds-carousel>
 
 <script>
-  document.querySelector('bds-carousel')
-    .addEventListener('bds-slide-change', e => {
-      console.log('Active slide:', e.detail.index);
-    });
+  const carousel = document.querySelector('bds-carousel');
+  carousel.addEventListener('bds-slide-change', e => {
+    console.log('Active slide:', e.detail.index);
+  });
+
+  // Public navigation API
+  carousel.next();
+  carousel.prev();
+  carousel.goTo(2);
 </script>
 ```
 
+### Custom prev/next buttons
+
+```html
+<bds-carousel>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+  <button slot="prev">◀</button>
+  <button slot="next">▶</button>
+</bds-carousel>
+```
+
 ## Accessibility
 
-- The slide track has `role="region"` with `aria-label="Carousel"`
-- Dot indicators carry `role="tab"` and `aria-selected`; the indicator list has `role="tablist"`
-- Navigation buttons have descriptive `aria-label` values and are disabled at boundaries (unless `loop` is set)
+- The slide track has `role="region"` with a consumer-supplied `aria-label` (via the `label` attribute, defaulting to "Carousel")
+- Dot indicators are plain buttons with `aria-current="true"` on the active slide (no incomplete ARIA tabs pattern); the indicator group has `role="group"`
+- Dot indicators keep an 8px visual size but expose a larger invisible hit area (~24px) to meet the WCAG 2.5.8 minimum touch-target size
+- Navigation buttons have descriptive, overridable `aria-label` values (`prev-label`/`next-label`) and are disabled at boundaries (unless `loop` is set)
 - Smooth scroll is suppressed when `prefers-reduced-motion: reduce` is set

package/src/web-components/ui/BdsDescriptionList.mdx

@@ -18,7 +18,12 @@ import '@boostdev/design-system-components/web-components';
 ## When to use
 
 - Displaying key–value data such as user profiles, settings summaries, or metadata panels
-- Use `layout="inline"` to place term and value side-by-side on wider screens
+- Use `layout="inline"` to place term and value side-by-side in a two-column grid (term column: `minmax(8rem, 1fr)`, value column: `2fr`)
+
+## Layout behaviour
+
+- **Stacked** (default): each `<dt>` sits directly above its `<dd>` with a tight gap (`--bds-space_xxs`); a looser gap (`--bds-space_s`) separates one term/detail pair from the next.
+- **Inline**: `<dt>`/`<dd>` pairs are laid out side by side as grid rows — the term in a `minmax(8rem, 1fr)` column, the detail in a `2fr` column, `align-items: baseline`.
 
 ## Examples
 

package/src/web-components/ui/BdsIconWrapper.mdx

@@ -51,8 +51,9 @@ import '@boostdev/design-system-components/web-components';
 
 | Property | Description |
 |----------|-------------|
-| `--icon-wrapper-color` | Background fill of the circular container |
-| `--bds-on-icon-wrapper-color` | Icon/foreground colour inside the wrapper |
+| `--icon-wrapper_radius` | Border radius of the circular container (default `var(--bds-border_radius--circle)`); `--icon-wrapper-radius` (hyphen-delimited) is a deprecated alias |
+| `--icon-wrapper_color` | Background fill of the circular container (default `var(--bds-color_bg)`); `--icon-wrapper-color` (hyphen-delimited) is a deprecated alias |
+| `--icon-wrapper_on-color` | Icon/foreground colour inside the wrapper (default `var(--bds-color_on-bg)`) |
 
 ## Usage in plain HTML
 

package/src/web-components/ui/BdsLink.mdx

@@ -60,10 +60,22 @@ import '@boostdev/design-system-components/web-components';
 
 ## CSS Custom Properties
 
+Resting and hover colours are independent, layered overrides: a top-level
+override (e.g. `--link_color`) wins over the per-variant default for that
+same state (e.g. `--link_color--default`), which falls back to the design
+token. Setting `--link_color` on an ancestor themes only the resting state
+across all variants; setting `--link_color-hover` themes only hover.
+
 | Property | Description |
 |----------|-------------|
-| `--link_color` | Link colour |
-| `--link_color-hover` | Link hover colour |
+| `--link_color` | Link colour override (all variants, resting state) |
+| `--link_color-hover` | Link hover colour override (all variants) |
+| `--link_color--default` | Resting colour override for `variant="default"` |
+| `--link_color-hover--default` | Hover colour override for `variant="default"` |
+| `--link_color--subtle` | Resting colour override for `variant="subtle"` |
+| `--link_color-hover--subtle` | Hover colour override for `variant="subtle"` |
+| `--link_color--standalone` | Resting colour override for `variant="standalone"` |
+| `--link_color-hover--standalone` | Hover colour override for `variant="standalone"` |
 
 ## Usage in plain HTML
 

package/src/web-components/ui/BdsNotificationBanner.mdx

@@ -63,6 +63,23 @@ import '@boostdev/design-system-components/web-components';
 | `(default)` | Banner body text or HTML |
 | `action` | Optional action area (e.g. a `<button>` or `<a>`) |
 
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--banner_bg` | Banner background colour (all variants) |
+| `--banner_text` | Banner text colour (all variants) |
+| `--banner_border` | Banner bottom border colour (all variants) |
+| `--banner_bg--info` / `--banner_text--info` / `--banner_border--info` | Info variant colours |
+| `--banner_bg--success` / `--banner_text--success` / `--banner_border--success` | Success variant colours |
+| `--banner_bg--warning` / `--banner_text--warning` / `--banner_border--warning` | Warning variant colours |
+| `--banner_bg--error` / `--banner_text--error` / `--banner_border--error` | Error variant colours |
+| `--banner_dismiss-size` | Dismiss button minimum touch target (default `2.75rem`, WCAG 2.5.5); the visible icon stays 1rem |
+| `--banner_dismiss-radius` | Dismiss button border radius |
+| `--banner_dismiss-border` | Dismiss button border |
+| `--banner_dismiss-border-color` | Dismiss button inset-border colour (default `currentcolor`). `--notification-banner_dismiss-border-color` is a deprecated alias for the same hook. |
+| `--banner_dismiss-opacity--hover` | Dismiss button opacity on hover |
+
 ## Events
 
 | Event | Detail | Description |
@@ -83,3 +100,4 @@ import '@boostdev/design-system-components/web-components';
 - `error` and `warning` variants render `role="alert"` with `aria-live="assertive"`
 - `info` and `success` variants render `role="status"` with `aria-live="polite"`
 - The dismiss button has a configurable `aria-label` via `dismiss-label`
+- The dismiss button's interactive hit area meets the WCAG 2.5.5 44×44px minimum (`--banner_dismiss-size`), even though the visible icon stays 1rem

package/src/web-components/ui/BdsPagination.mdx

@@ -54,6 +54,44 @@ import '@boostdev/design-system-components/web-components';
 |-------|--------|-------------|
 | `bds-page-change` | `{ page: number }` | Fired when the user navigates to a different page |
 
+## CSS variables
+
+The override surface is **layered**. Setting `--pagination_item-bg` / `--pagination_item-color` / `--pagination_item-border` on the element (or any ancestor) wins in every state — resting, hover, and active. Setting a per-state token targets only that one state.
+
+### Public override tokens (win over per-state defaults)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--pagination_radius` | `var(--bds-border_radius--full)` | Page button border radius |
+| `--pagination_item-bg` | `transparent` (per state) | Button background — themes every state at once |
+| `--pagination_item-color` | per state | Button text colour |
+| `--pagination_item-border` | per state | Button border colour (bdc inset border) |
+
+### Per-state overrides
+
+| State | Background | Text | Border |
+|-------|-----------|------|--------|
+| resting | (`transparent`) | (`var(--bds-color_on-bg)`) | (`var(--bds-color_bg--subtle)`) |
+| hover | `--pagination_item-bg--hover` | `--pagination_item-color--hover` | — |
+| active (current page) | `--pagination_item-bg--active` | `--pagination_item-color--active` | `--pagination_item-border--active` |
+
+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.
+
+| Deprecated | Use instead |
+|------------|-------------|
+| `--btn_bg` | `--pagination_item-bg` |
+| `--btn_color` | `--pagination_item-color` |
+| `--btn_border` | `--pagination_item-border` |
+| `--btn_bg--hover` | `--pagination_item-bg--hover` |
+| `--btn_color--hover` | `--pagination_item-color--hover` |
+| `--btn_bg--active` | `--pagination_item-bg--active` |
+| `--btn_color--active` | `--pagination_item-color--active` |
+| `--btn_border--active` | `--pagination_item-border--active` |
+
 ## Usage in plain HTML
 
 ```html
@@ -70,5 +108,6 @@ import '@boostdev/design-system-components/web-components';
 ## Accessibility
 
 - Wrapped in `<nav aria-label="Pagination">` with an `<ul>` list structure
-- Active page button carries `aria-current="page"`
+- Numbered page buttons carry `aria-label="Page N"`; the active page button additionally carries `aria-current="page"` (non-active buttons omit `aria-current` entirely rather than emitting `aria-current="false"`)
 - Previous/Next buttons have descriptive `aria-label` values and are `disabled` at the boundaries
+- Page buttons meet the 44×44px (2.75rem) WCAG 2.5.5 minimum touch target

package/src/web-components/ui/BdsProgress.mdx

@@ -55,7 +55,10 @@ import '@boostdev/design-system-components/web-components';
 
 | Property | Description |
 |----------|-------------|
-| `--progress_color-active` | Fill colour of the progress bar |
+| `--progress_color-active` | Fill colour of the progress bar (defaults to `var(--bdc-color_active)`) |
+| `--progress_color-track` | Empty track colour (defaults to `var(--bds-color_bg--subtle)`) |
+| `--progress_radius` | Track and fill corner radius (defaults to `var(--bds-border_radius--full)`) |
+| `--progress_height` | Track block-size (defaults per `size`: `--bds-space_xxs`/`--bds-space_xs`/`--bds-space_s`) |
 
 ## Usage in plain HTML
 
@@ -67,4 +70,7 @@ import '@boostdev/design-system-components/web-components';
 ## Accessibility
 
 - Renders with `role="progressbar"`, `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
-- Always provide a `label` to give the bar a meaningful accessible name
+- Always provide a `label` to give the bar a meaningful accessible name — when `label` is
+  unset, `aria-label` is omitted entirely (not rendered as an empty string), so the
+  progressbar falls back to having **no** accessible name
+- `aria-valuenow` is clamped to the `0`–`max` range, matching the visual fill

package/src/web-components/ui/BdsProgressCircle.mdx

@@ -47,7 +47,7 @@ import '@boostdev/design-system-components/web-components';
 |-----------|------|---------|-------------|
 | `value` | number | `0` | Current progress value |
 | `max` | number | `100` | Maximum value |
-| `label` | string | — | Accessible label for the progress bar |
+| `label` | string | — | Accessible label for the progress bar (required — see Accessibility) |
 | `show-value` | boolean | `false` | Displays the rounded percentage in the centre of the ring |
 | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Diameter (`40px` / `64px` / `96px`) |
 
@@ -56,6 +56,8 @@ import '@boostdev/design-system-components/web-components';
 | Property | Description |
 |----------|-------------|
 | `--progressCircle_color-active` | Stroke colour of the filled arc |
+| `--progressCircle_color-track` | Stroke colour of the background track (default: `--bds-color_bg--subtle`) |
+| `--progressCircle_font-size--small` | Font size of the centred value label at `size="small"` (default: `--bds-font_size--body--s`) |
 
 ## Usage in plain HTML
 
@@ -67,4 +69,5 @@ import '@boostdev/design-system-components/web-components';
 ## Accessibility
 
 - Renders with `role="progressbar"`, `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
-- Always provide a `label` to give the indicator a meaningful accessible name
+- `label` is required — without it the host renders `role="progressbar"` with no accessible name. When `label` is unset, `aria-label` is omitted entirely (never rendered empty) so assistive technology falls back correctly instead of announcing a nameless control.
+- `aria-valuenow` is clamped to the `0`–`max` range, matching the visual fill, even if `value` is passed out of range

package/src/web-components/ui/BdsRating.mdx

@@ -55,6 +55,13 @@ import '@boostdev/design-system-components/web-components';
 <bds-rating value="4" max="10"></bds-rating>
 ```
 
+## CSS Custom Properties
+
+| Variable | Default | Description |
+|----------|---------|--------------|
+| `--rating_color` | `var(--bds-color_bg)` | Colour of unfilled stars |
+| `--rating_color--filled` | `var(--bds-color_warning)` | Colour of filled stars |
+
 ## Accessibility
 
 - Renders `role="img"` with `aria-label` set to `"{value} out of {max} stars"`

package/src/web-components/ui/BdsSectionHeader.mdx

@@ -29,6 +29,9 @@ import '@boostdev/design-system-components/web-components';
 ### Default
 <Canvas of={Stories.Default} />
 
+### Extra small
+<Canvas of={Stories.ExtraSmall} />
+
 ### Small
 <Canvas of={Stories.Small} />
 
@@ -49,17 +52,18 @@ import '@boostdev/design-system-components/web-components';
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `title` | string | — | Heading text (required) |
+| `heading` | string | — | Heading text (required) |
+| `title` | string | — | **Deprecated** — alias for `heading`. Sharing the name with the global HTML `title` attribute triggers a native browser tooltip on hover; kept working as a fallback when `heading` is unset, will be removed in a later major. Use `heading` instead. |
 | `subtitle` | string | — | Optional subheading text |
 | `alignment` | `"start" \| "center" \| "end"` | `"start"` | Text and flex alignment |
-| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Font size scale for title and subtitle |
+| `size` | `"xs" \| "small" \| "medium" \| "large"` | `"medium"` | Font size scale for title and subtitle |
 | `title-as` | string | `"h2"` | Override the HTML element rendered for the title |
 
 ## Usage in plain HTML
 
 ```html
 <bds-section-header
-  title="Our Products"
+  heading="Our Products"
   subtitle="Browse the full range"
   size="large"
   alignment="center">
@@ -70,3 +74,18 @@ import '@boostdev/design-system-components/web-components';
 
 - The title renders as `h2` by default; use `title-as` to match the page heading hierarchy
 - Avoid skipping heading levels when changing `title-as`
+
+## CSS custom properties
+
+| Token | Default | Description |
+|-------|---------|--------------|
+| `--sectionHeader_gap` | `--bds-space_m` | Gap between title and subtitle |
+| `--sectionHeader_title-color` | `--bds-color_on-bg` | Title text color (`--sectionHeader-title-color`, kebab-delimited, is a deprecated alias) |
+| `--sectionHeader_subtitle-color` | `--bds-color_grey--strong` | Subtitle text color |
+| `--sectionHeader_title-size` | Size-variant font-size token (e.g. `--bds-font_size--display` for medium/large) | Title font size |
+| `--sectionHeader_title-line-height` | Size-variant line-height token | Title line height |
+| `--sectionHeader_title-weight` | `--bds-font_weight--bold` | Title font weight |
+| `--sectionHeader_subtitle-size` | Size-variant font-size token | Subtitle font size |
+| `--sectionHeader_subtitle-line-height` | `1.3` (medium/large) or `1.4` (xs/small) | Subtitle line height |
+
+The host also sets `grid-column: var(--bds-grid_span-100)` so the header spans the full row when placed inside `<bds-grid>`.

package/src/web-components/ui/BdsSectionHeader.stories.tsx

@@ -3,19 +3,19 @@ import type { Meta, StoryObj } from '@storybook/react';
 import '../index'; // auto-registers all custom elements
 
 function BdsSectionHeader({
-  title = '',
+  heading = '',
   subtitle,
   alignment = 'start',
   size = 'medium',
   titleAs,
 }: {
-  title?: string;
+  heading?: string;
   subtitle?: string;
   alignment?: 'start' | 'center' | 'end';
-  size?: 'small' | 'medium' | 'large';
+  size?: 'xs' | 'small' | 'medium' | 'large';
   titleAs?: string;
 }) {
-  return React.createElement('bds-section-header', { title, subtitle, alignment, size, 'title-as': titleAs });
+  return React.createElement('bds-section-header', { heading, subtitle, alignment, size, 'title-as': titleAs });
 }
 
 const meta = {
@@ -25,7 +25,7 @@ const meta = {
   parameters: { layout: 'padded' },
   argTypes: {
     alignment: { control: 'select', options: ['start', 'center', 'end'] },
-    size:      { control: 'select', options: ['small', 'medium', 'large'] },
+    size:      { control: 'select', options: ['xs', 'small', 'medium', 'large'] },
     titleAs:   { control: 'text' },
   },
 } satisfies Meta<typeof BdsSectionHeader>;
@@ -34,21 +34,23 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
-  args: { title: 'Our Products', subtitle: 'Browse the full range', size: 'medium', alignment: 'start' },
+  args: { heading: 'Our Products', subtitle: 'Browse the full range', size: 'medium', alignment: 'start' },
 };
-export const Small: Story = { args: { title: 'Recent Activity', subtitle: 'Last 30 days', size: 'small' } };
-export const Large: Story = { args: { title: 'Welcome Back', subtitle: 'Here is what happened today', size: 'large' } };
+export const ExtraSmall: Story = { args: { heading: 'Filters', subtitle: 'Refine the results', size: 'xs' } };
+export const Small: Story = { args: { heading: 'Recent Activity', subtitle: 'Last 30 days', size: 'small' } };
+export const Large: Story = { args: { heading: 'Welcome Back', subtitle: 'Here is what happened today', size: 'large' } };
 export const Centered: Story = {
-  args: { title: 'Our Mission', subtitle: 'We are building something great', alignment: 'center' },
+  args: { heading: 'Our Mission', subtitle: 'We are building something great', alignment: 'center' },
 };
-export const TitleOnly: Story = { args: { title: 'Settings', size: 'small' } };
+export const TitleOnly: Story = { args: { heading: 'Settings', size: 'small' } };
 
 export const AllSizes: Story = {
   render: () => (
     <div style={{ display: 'flex', flexDirection: 'column', gap: 32 }}>
-      {React.createElement('bds-section-header', { title: 'Small Heading', subtitle: 'Subtitle text', size: 'small' })}
-      {React.createElement('bds-section-header', { title: 'Medium Heading', subtitle: 'Subtitle text', size: 'medium' })}
-      {React.createElement('bds-section-header', { title: 'Large Heading', subtitle: 'Subtitle text', size: 'large' })}
+      {React.createElement('bds-section-header', { heading: 'Extra Small Heading', subtitle: 'Subtitle text', size: 'xs' })}
+      {React.createElement('bds-section-header', { heading: 'Small Heading', subtitle: 'Subtitle text', size: 'small' })}
+      {React.createElement('bds-section-header', { heading: 'Medium Heading', subtitle: 'Subtitle text', size: 'medium' })}
+      {React.createElement('bds-section-header', { heading: 'Large Heading', subtitle: 'Subtitle text', size: 'large' })}
     </div>
   ),
 };

package/src/web-components/ui/BdsTable.mdx

@@ -9,6 +9,13 @@ Framework-agnostic scrollable Table wrapper custom element. Apply design-system
 
 > **Status: experimental** — API may change before stable release.
 
+> **Light-DOM styling contract:** `::slotted()` can only match the node placed directly into
+> the slot (the `<table>` itself), never its descendants. `<thead>`/`<th>`/`<td>` styling is
+> therefore shipped as a document-level stylesheet scoped to the `bds-table > table …` selector
+> (adopted once, the first time any `<bds-table>` module is imported). This means the slotted
+> `<table>` must be a **direct child** of `<bds-table>` for cell styling and `sticky-header` to
+> apply — don't wrap it in an intermediate element.
+
 ## Installation
 
 ```js
@@ -37,12 +44,21 @@ import '@boostdev/design-system-components/web-components';
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `sticky-header` | boolean | `false` | Freezes `<thead>` at the top when the table overflows vertically |
+| `aria-label` | string | — | Accessible name for the scrollable region; also enables `role="region"` on the wrapper |
 
 ## Slots
 
 | Slot | Description |
 |------|-------------|
-| `(default)` | A standard `<table>` element with `<thead>` and `<tbody>` |
+| `(default)` | A standard `<table>` element (must be a direct child — see the light-DOM styling contract above) |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--table_border` | Wrapper border (default: `none`) |
+| `--table_radius` | Wrapper corner radius (default: `var(--bdc-outline_radius)`, itself set to `var(--bds-border_radius--s)` on the wrapper) |
+| `--table_row-bg--hover` | Row background on hover, pointer devices only (default: `var(--bds-color_bg--subtle)`) |
 
 ## Usage in plain HTML
 
@@ -78,4 +94,9 @@ import '@boostdev/design-system-components/web-components';
 
 - Use a standard `<table>` with proper `<thead>` / `<tbody>` structure
 - Column headers (`<th>`) are automatically styled; add `scope="col"` for complex tables
-- The wrapper is horizontally scrollable (`overflow-inline: auto`) on small viewports
+- The wrapper is horizontally scrollable (`overflow-inline: auto`) on small viewports and is
+  keyboard-focusable (`tabindex="0"`) with a `:focus-visible` outline, so it can be scrolled
+  without a mouse in browsers that don't auto-focus scroll containers
+- Set `aria-label` on `<bds-table>` to give the scrollable region an accessible name — this also
+  adds `role="region"` on the wrapper; without it, the wrapper stays unlabelled and roleless to
+  avoid a nameless landmark