@boostdev/design-system-components 1.2.0 → 1.2.1

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

@@ -0,0 +1,83 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsCarousel.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-carousel&gt;
+
+Framework-agnostic Carousel custom element. A scroll-snap based slider where each direct child becomes a slide. Supports dot indicators, looping, and custom previous/next buttons via named slots.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## When to use
+
+- Cycling through a set of related content cards, images, or feature highlights
+- Use `indicators` to help users understand how many slides exist and which one is active
+- Use `loop` for continuous navigation without boundaries
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With indicators
+<Canvas of={Stories.WithIndicators} />
+
+### Loop
+<Canvas of={Stories.Loop} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `current-index` | number | `0` | Active slide index (0-based) |
+| `indicators` | boolean | `false` | Shows dot indicator buttons below the slides |
+| `loop` | boolean | `false` | Wraps from last slide to first and vice versa |
+
+## 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) |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `bds-slide-change` | `{ index: number }` | Fired when the active slide changes |
+
+## Usage in plain HTML
+
+```html
+<bds-carousel indicators loop>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+  <div>Slide 3</div>
+</bds-carousel>
+
+<script>
+  document.querySelector('bds-carousel')
+    .addEventListener('bds-slide-change', e => {
+      console.log('Active slide:', e.detail.index);
+    });
+</script>
+```
+
+## 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)
+- Smooth scroll is suppressed when `prefers-reduced-motion: reduce` is set

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

@@ -0,0 +1,96 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index'; // auto-registers all custom elements
+
+function BdsCarousel({
+  currentIndex = 0,
+  indicators,
+  loop,
+  children,
+}: {
+  currentIndex?: number;
+  indicators?: boolean;
+  loop?: boolean;
+  children?: React.ReactNode;
+}) {
+  return React.createElement(
+    'bds-carousel',
+    {
+      'current-index': currentIndex,
+      indicators: indicators || undefined,
+      loop: loop || undefined,
+    },
+    children,
+  );
+}
+
+const slides = ['Slide 1', 'Slide 2', 'Slide 3'].map(label =>
+  React.createElement(
+    'div',
+    {
+      key: label,
+      style: {
+        background: 'var(--bds-color_bg--subtle, #f3f4f6)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        height: 160,
+        fontSize: '1.25rem',
+        fontWeight: 600,
+        borderRadius: 8,
+      },
+    },
+    label,
+  ),
+);
+
+const meta = {
+  title: 'Web Components/UI/Carousel',
+  component: BdsCarousel,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    currentIndex: { control: 'number' },
+    indicators:   { control: 'boolean' },
+    loop:         { control: 'boolean' },
+  },
+} satisfies Meta<typeof BdsCarousel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <div style={{ width: 400 }}>
+      {React.createElement(
+        'bds-carousel',
+        {},
+        ...slides,
+      )}
+    </div>
+  ),
+};
+
+export const WithIndicators: Story = {
+  render: () => (
+    <div style={{ width: 400 }}>
+      {React.createElement(
+        'bds-carousel',
+        { indicators: true },
+        ...slides,
+      )}
+    </div>
+  ),
+};
+
+export const Loop: Story = {
+  render: () => (
+    <div style={{ width: 400 }}>
+      {React.createElement(
+        'bds-carousel',
+        { indicators: true, loop: true },
+        ...slides,
+      )}
+    </div>
+  ),
+};

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

@@ -5,7 +5,7 @@ import * as Stories from './BdsDescriptionList.stories';
 
 # <bds-description-list>
 
-Framework-agnostic Description List custom element. Wraps a semantic `<dl>` element for rendering key–value pairs. Consumers provide `<dt>` and `<dd>` elements as slotted children.
+Framework-agnostic Description List custom element. Wraps slotted `<dt>`/`<dd>` pairs in a styled `<dl>` with stacked or inline layout.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -15,10 +15,15 @@ Framework-agnostic Description List custom element. Wraps a semantic `<dl>` elem
 import '@boostdev/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
+
 ## Examples
 
-### All layouts
-<Canvas of={Stories.AllVariants} />
+### Default (stacked)
+<Canvas of={Stories.Default} />
 
 ### Stacked
 <Canvas of={Stories.Stacked} />
@@ -34,34 +39,26 @@ import '@boostdev/components/web-components';
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `layout` | `"stacked" \| "inline"` | `"stacked"` | Arrangement of terms and details |
+| `layout` | `"stacked" \| "inline"` | `"stacked"` | Display mode — stacked places term above value; inline places them side-by-side |
 
 ## Slots
 
 | Slot | Description |
 |------|-------------|
-| `(default)` | `<dt>` and `<dd>` element pairs |
+| `(default)` | `<dt>` and `<dd>` pairs |
 
 ## Usage in plain HTML
 
 ```html
-<bds-description-list>
+<bds-description-list layout="inline">
   <dt>Name</dt>
   <dd>Jane Doe</dd>
   <dt>Email</dt>
   <dd>jane@example.com</dd>
 </bds-description-list>
-
-<bds-description-list layout="inline">
-  <dt>Status</dt>
-  <dd>Active</dd>
-  <dt>Role</dt>
-  <dd>Designer</dd>
-</bds-description-list>
 ```
 
 ## Accessibility
 
-- Renders a semantic `<dl>` element — screen readers announce it as a description list
-- Ensure `<dt>` and `<dd>` elements are properly paired
-- The `::slotted(dt)` and `::slotted(dd)` CSS selectors apply the visual styling
+- Renders a native `<dl>` element — screen readers announce it as a description list
+- Ensure every `<dt>` has a corresponding `<dd>`

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

@@ -1,9 +1,9 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
 function BdsDescriptionList({
-  layout,
+  layout = 'stacked',
   children,
 }: {
   layout?: 'stacked' | 'inline';
@@ -18,62 +18,47 @@ const meta = {
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'centered' },
   argTypes: {
-    layout: { control: 'select', options: ['stacked', 'inline'] },
+    layout: { control: 'radio', options: ['stacked', 'inline'] },
   },
 } satisfies Meta<typeof BdsDescriptionList>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-const items = [
-  { term: 'Name', detail: 'Jane Doe' },
-  { term: 'Email', detail: 'jane@example.com' },
-  { term: 'Role', detail: 'Designer' },
-];
+export const Default: Story = {
+  render: () =>
+    React.createElement(
+      'bds-description-list',
+      { layout: 'stacked' },
+      React.createElement('dt', null, 'Name'),
+      React.createElement('dd', null, 'Jane Doe'),
+      React.createElement('dt', null, 'Email'),
+      React.createElement('dd', null, 'jane@example.com'),
+      React.createElement('dt', null, 'Role'),
+      React.createElement('dd', null, 'Administrator'),
+    ),
+};
 
 export const Stacked: Story = {
-  render: () => (
-    <BdsDescriptionList layout="stacked">
-      {items.flatMap(({ term, detail }) => [
-        React.createElement('dt', { key: `dt-${term}` }, term),
-        React.createElement('dd', { key: `dd-${term}` }, detail),
-      ])}
-    </BdsDescriptionList>
-  ),
+  render: () =>
+    React.createElement(
+      'bds-description-list',
+      { layout: 'stacked' },
+      React.createElement('dt', null, 'Framework'),
+      React.createElement('dd', null, 'Lit'),
+      React.createElement('dt', null, 'Language'),
+      React.createElement('dd', null, 'TypeScript'),
+    ),
 };
 
 export const Inline: Story = {
-  render: () => (
-    <BdsDescriptionList layout="inline">
-      {items.flatMap(({ term, detail }) => [
-        React.createElement('dt', { key: `dt-${term}` }, term),
-        React.createElement('dd', { key: `dd-${term}` }, detail),
-      ])}
-    </BdsDescriptionList>
-  ),
-};
-
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', gap: '48px', flexWrap: 'wrap', alignItems: 'flex-start' }}>
-      <div>
-        <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888', fontWeight: 600 }}>Stacked</p>
-        <BdsDescriptionList layout="stacked">
-          {items.flatMap(({ term, detail }) => [
-            React.createElement('dt', { key: `dt-${term}` }, term),
-            React.createElement('dd', { key: `dd-${term}` }, detail),
-          ])}
-        </BdsDescriptionList>
-      </div>
-      <div>
-        <p style={{ margin: '0 0 8px', fontSize: '0.75rem', color: '#888', fontWeight: 600 }}>Inline</p>
-        <BdsDescriptionList layout="inline">
-          {items.flatMap(({ term, detail }) => [
-            React.createElement('dt', { key: `dt-${term}` }, term),
-            React.createElement('dd', { key: `dd-${term}` }, detail),
-          ])}
-        </BdsDescriptionList>
-      </div>
-    </div>
-  ),
+  render: () =>
+    React.createElement(
+      'bds-description-list',
+      { layout: 'inline' },
+      React.createElement('dt', null, 'Status'),
+      React.createElement('dd', null, 'Active'),
+      React.createElement('dt', null, 'Plan'),
+      React.createElement('dd', null, 'Professional'),
+    ),
 };

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

@@ -5,7 +5,7 @@ import * as Stories from './BdsIconWrapper.stories';
 
 # <bds-icon-wrapper>
 
-Framework-agnostic Icon Wrapper custom element. Displays an icon inside a circular container with background and foreground theming.
+Framework-agnostic Icon Wrapper custom element. Displays a slotted icon inside a circular container with design-system background and foreground colour theming.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -15,13 +15,21 @@ Framework-agnostic Icon Wrapper custom element. Displays an icon inside a circul
 import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+- To visually highlight a feature icon in a card, empty state, or marketing section
+- Use `aria-hidden="true"` when the icon is purely decorative and adjacent text provides the label
+
 ## Examples
 
-### All variants
-<Canvas of={Stories.AllVariants} />
+### Default
+<Canvas of={Stories.Default} />
+
+### With label
+<Canvas of={Stories.WithLabel} />
 
-### With star icon
-<Canvas of={Stories.WithStar} />
+### Multiple
+<Canvas of={Stories.Multiple} />
 
 ## Props
 
@@ -31,7 +39,7 @@ import '@boostdev/components/web-components';
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `aria-hidden` | string | — | Set to `"true"` for purely decorative icons |
+| `aria-hidden` | string | — | Set to `"true"` for decorative icons |
 
 ## Slots
 
@@ -43,28 +51,20 @@ import '@boostdev/components/web-components';
 
 | Property | Description |
 |----------|-------------|
-| `--icon-wrapper-color` | Circle background colour |
-| `--bds-on-icon-wrapper-color` | Icon fill/stroke colour |
+| `--icon-wrapper-color` | Background fill of the circular container |
+| `--bds-on-icon-wrapper-color` | Icon/foreground colour inside the wrapper |
 
 ## Usage in plain HTML
 
 ```html
-<!-- Decorative icon -->
 <bds-icon-wrapper aria-hidden="true">
-  <svg viewBox="0 0 24 24" fill="currentColor">
-    <path d="M12 17.27L18.18 21..."/>
-  </svg>
-</bds-icon-wrapper>
-
-<!-- Meaningful icon — add aria-label to the wrapper -->
-<bds-icon-wrapper aria-label="Favourite">
-  <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
-    <path d="M12 21.593c..."/>
+  <svg viewBox="0 0 24 24" fill="currentColor" width="24" height="24">
+    <path d="M12 2l3.09 6.26L22 9.27l-5 4.87L18.18 21 12 17.77 5.82 21 7 14.14 2 9.27l6.91-1.01z"/>
   </svg>
 </bds-icon-wrapper>
 ```
 
 ## Accessibility
 
-- When the icon is decorative, set `aria-hidden="true"` on the host
-- When the icon conveys meaning, set `aria-label` on the host and `aria-hidden="true"` on the SVG itself
+- Use `aria-hidden="true"` when the icon is decorative and the surrounding content provides context
+- When the icon is standalone and meaningful, omit `aria-hidden` and provide a label via adjacent text or `aria-label` on the wrapper

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

@@ -1,34 +1,25 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
-import '../index';
+import '../index'; // auto-registers all custom elements
 
+// Simple star SVG for demonstration
 const StarIcon = () =>
   React.createElement(
     'svg',
-    { viewBox: '0 0 24 24', fill: 'currentColor', width: '1.25em', height: '1.25em', 'aria-hidden': 'true' },
+    { xmlns: 'http://www.w3.org/2000/svg', viewBox: '0 0 24 24', fill: 'currentColor', width: 24, height: 24 },
     React.createElement('path', {
       d: 'M12 17.27L18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z',
     }),
   );
 
-const CheckIcon = () =>
-  React.createElement(
-    'svg',
-    { viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: '2.5', width: '1.25em', height: '1.25em', 'aria-hidden': 'true' },
-    React.createElement('path', { strokeLinecap: 'round', strokeLinejoin: 'round', d: 'M5 13l4 4L19 7' }),
-  );
-
-const HeartIcon = () =>
-  React.createElement(
-    'svg',
-    { viewBox: '0 0 24 24', fill: 'currentColor', width: '1.25em', height: '1.25em', 'aria-hidden': 'true' },
-    React.createElement('path', {
-      d: 'M12 21.593c-.425-.052-8.092-5.65-8.092-10.82C3.908 6.64 7.084 4 10.408 4c1.75 0 3.192.806 4.175 2.016A5.355 5.355 0 0 1 18.175 4c3.324 0 6.5 2.64 6.5 6.773 0 5.17-7.667 10.768-8.092 10.82z',
-    }),
-  );
-
-function BdsIconWrapper({ children }: { children?: React.ReactNode }) {
-  return React.createElement('bds-icon-wrapper', null, children);
+function BdsIconWrapper({
+  ariaHidden,
+  children,
+}: {
+  ariaHidden?: string;
+  children?: React.ReactNode;
+}) {
+  return React.createElement('bds-icon-wrapper', { 'aria-hidden': ariaHidden }, children);
 }
 
 const meta = {
@@ -36,41 +27,55 @@ const meta = {
   component: BdsIconWrapper,
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'centered' },
+  argTypes: {
+    ariaHidden: { control: 'text' },
+  },
 } satisfies Meta<typeof BdsIconWrapper>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const WithStar: Story = {
-  render: () => (
-    <BdsIconWrapper>
-      <StarIcon />
-    </BdsIconWrapper>
-  ),
+export const Default: Story = {
+  render: () =>
+    React.createElement(
+      'bds-icon-wrapper',
+      { 'aria-hidden': 'true' },
+      React.createElement(StarIcon),
+    ),
 };
 
-export const WithCheck: Story = {
-  render: () => (
-    <BdsIconWrapper>
-      <CheckIcon />
-    </BdsIconWrapper>
-  ),
+export const Decorative: Story = {
+  render: () =>
+    React.createElement(
+      'bds-icon-wrapper',
+      { 'aria-hidden': 'true' },
+      React.createElement(StarIcon),
+    ),
 };
 
-export const WithHeart: Story = {
+export const WithLabel: Story = {
   render: () => (
-    <BdsIconWrapper>
-      <HeartIcon />
-    </BdsIconWrapper>
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 8 }}>
+      {React.createElement(
+        'bds-icon-wrapper',
+        {},
+        React.createElement(StarIcon),
+      )}
+      <span>Favourites</span>
+    </div>
   ),
 };
 
-export const AllVariants: Story = {
+export const Multiple: Story = {
   render: () => (
-    <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
-      <BdsIconWrapper><StarIcon /></BdsIconWrapper>
-      <BdsIconWrapper><CheckIcon /></BdsIconWrapper>
-      <BdsIconWrapper><HeartIcon /></BdsIconWrapper>
+    <div style={{ display: 'flex', gap: 16 }}>
+      {[1, 2, 3].map(i =>
+        React.createElement(
+          'bds-icon-wrapper',
+          { key: i, 'aria-hidden': 'true' },
+          React.createElement(StarIcon),
+        ),
+      )}
     </div>
   ),
 };

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

@@ -5,7 +5,7 @@ import * as Stories from './BdsLink.stories';
 
 # <bds-link>
 
-Framework-agnostic Link custom element. Renders a semantic `<a>` element with three visual styles and built-in external link handling.
+Framework-agnostic Link custom element. Renders a styled `<a>` tag with three visual variants, automatic external link handling, and design-token colours.
 
 > **Status: experimental** — API may change before stable release.
 
@@ -15,6 +15,12 @@ Framework-agnostic Link custom element. Renders a semantic `<a>` element with th
 import '@boostdev/components/web-components';
 ```
 
+## When to use
+
+- Inline hyperlinks within body text (default or subtle)
+- Standalone call-to-action links that should look more prominent (standalone)
+- External links that automatically get `rel="noreferrer noopener"` and a screen reader suffix
+
 ## Examples
 
 ### All variants
@@ -23,6 +29,9 @@ import '@boostdev/components/web-components';
 ### Default
 <Canvas of={Stories.Default} />
 
+### Subtle
+<Canvas of={Stories.Subtle} />
+
 ### Standalone
 <Canvas of={Stories.Standalone} />
 
@@ -37,39 +46,34 @@ import '@boostdev/components/web-components';
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `href` | string | — | Link destination |
-| `target` | string | — | Native anchor target |
+| `href` | string | — | Link destination URL |
+| `target` | string | — | Standard `<a>` target attribute |
 | `variant` | `"default" \| "subtle" \| "standalone"` | `"default"` | Visual style |
-| `external` | boolean | `false` | Adds `rel="noreferrer noopener"`, opens in new tab, appends screen-reader text |
-| `external-label` | string | `"(opens in new tab)"` | Visually-hidden text appended for external links |
+| `external` | boolean | `false` | Adds `rel="noreferrer noopener"`, forces `target="_blank"`, and appends a visually-hidden screen reader label |
+| `external-label` | string | `"(opens in new tab)"` | Screen reader text appended when `external` is set |
 
 ## Slots
 
 | Slot | Description |
 |------|-------------|
-| `(default)` | Link text content |
+| `(default)` | Link text or content |
 
 ## CSS Custom Properties
 
 | Property | Description |
 |----------|-------------|
-| `--link_color` | Link text colour |
-| `--link_color-hover` | Link colour on hover |
+| `--link_color` | Link colour |
+| `--link_color-hover` | Link hover colour |
 
 ## Usage in plain HTML
 
 ```html
-<bds-link href="/docs">Read the docs</bds-link>
-
-<bds-link href="/about" variant="subtle">About us</bds-link>
-
-<bds-link href="/get-started" variant="standalone">Get started →</bds-link>
-
 <bds-link href="https://example.com" external>Visit site</bds-link>
+<p>Read our <bds-link href="/privacy">privacy policy</bds-link>.</p>
+<bds-link href="/docs" variant="standalone">View documentation</bds-link>
 ```
 
 ## Accessibility
 
-- Renders a native `<a>` — fully keyboard accessible
-- `external` adds a visually-hidden `(opens in new tab)` label for screen reader users and sets `rel="noreferrer noopener"` for security
-- Always provide meaningful link text — avoid "click here" or "read more"
+- When `external` is set, a visually-hidden `<span>` with configurable text is appended for screen readers
+- Ensure `href` always points to a valid destination