@boostdev/design-system-components 0.1.13 → 0.1.14

package/src/components/ui/Avatar/Avatar.mdx

@@ -0,0 +1,53 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Avatar.stories';
+
+<Meta of={Stories} />
+
+# Avatar
+
+Circular user representation. Displays a profile image when available, falling back to initials derived from `name`, then a generic placeholder.
+
+## When to use
+- User identity in comments, messages, or list items
+- Profile headers
+
+## Examples
+
+### With image
+<Canvas of={Stories.WithImage} />
+
+### With initials
+<Canvas of={Stories.WithInitials} />
+
+### All sizes
+<Canvas of={Stories.AllSizes} />
+
+### Single name (one initial)
+<Canvas of={Stories.SingleName} />
+
+### No name fallback
+<Canvas of={Stories.NoName} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--avatar_color`</td><td>Background colour for initials fallback</td></tr>
+<tr><td>`--avatar_on-color`</td><td>Text colour for initials</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Always provide a meaningful `alt` when passing `src`
+- When no image is shown, `aria-label` is derived from `name` to describe the avatar to screen readers
+- Touch target meets 44×44px minimum at `medium` size and above

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

@@ -1,22 +1,18 @@
 @layer component {
   .avatar {
-    --avatar_size:   3em;
-    --avatar_bg:     var(--color_blue);
-    --avatar_text:   var(--color_on-blue);
-
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    width: var(--avatar_size);
-    height: var(--avatar_size);
+    width: var(--avatar_size, 3em);
+    height: var(--avatar_size, 3em);
     border-radius: 50%;
     overflow: hidden;
     flex-shrink: 0;
   }
 
   .avatar.--fallback {
-    background-color: var(--avatar_bg);
-    color: var(--avatar_text);
+    background-color: var(--avatar_bg, var(--color_blue));
+    color: var(--avatar_text, var(--color_on-blue));
     font-weight: var(--font_weight--semibold);
   }
 

package/src/components/ui/Avatar/Avatar.stories.tsx

@@ -4,7 +4,6 @@ import { Avatar } from './Avatar';
 const meta = {
   title: 'UI/Avatar',
   component: Avatar,
-  tags: ['autodocs'],
   argTypes: {
     size: { control: 'radio', options: ['small', 'medium', 'large'] },
   },

package/src/components/ui/Badge/Badge.mdx

@@ -0,0 +1,62 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Badge.stories';
+
+<Meta of={Stories} />
+
+# Badge
+
+Compact inline label for status, category, or count. Renders a `<span>` with a semantic variant colour.
+
+## When to use
+- Highlight status on a record (active, error, draft)
+- Show a count alongside a navigation item
+- Label items in a list by category
+
+## When not to use
+- As a call-to-action — use `Button` instead
+- For long text — badges are single words or short phrases
+
+## Examples
+
+### Variants
+<Canvas of={Stories.AllVariants} />
+
+### Primary
+<Canvas of={Stories.Primary} />
+
+### Secondary
+<Canvas of={Stories.Secondary} />
+
+### Success
+<Canvas of={Stories.Success} />
+
+### Error
+<Canvas of={Stories.Error} />
+
+### Warning
+<Canvas of={Stories.Warning} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+Override these on a parent element to customise the badge without touching global tokens:
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--badge_color`</td><td>`var(--color_cta--subtle)`</td><td>Background colour</td></tr>
+<tr><td>`--badge_on-color`</td><td>`var(--color_on-cta--subtle)`</td><td>Text colour</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Renders as `<span>` — purely decorative/informational, no interactive role
+- Ensure the badge text is meaningful without surrounding context, or supplement it with a visually-hidden description for screen readers

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

@@ -1,22 +1,16 @@
 @layer component {
   .badge {
-    /* Component tokens — override from a parent context or inline style */
-    --badge_bg:        var(--color_blue);
-    --badge_text:      var(--color_on-blue);
-    --badge_radius:    2em;
-    --badge_font-size: var(--font_size--body--s);
-
     display: inline-flex;
     align-items: center;
     justify-content: center;
     padding: var(--space_xxs) var(--space_xs);
-    border-radius: var(--badge_radius);
-    font-size: var(--badge_font-size);
+    border-radius: var(--badge_radius, 2em);
+    font-size: var(--badge_font-size, var(--font_size--body--s));
     font-weight: var(--font_weight--semibold);
     line-height: 1;
     white-space: nowrap;
-    background-color: var(--badge_bg);
-    color: var(--badge_text);
+    background-color: var(--badge_bg, var(--color_blue));
+    color: var(--badge_text, var(--color_on-blue));
   }
 
   .--variant_primary {

package/src/components/ui/Badge/Badge.stories.tsx

@@ -4,7 +4,6 @@ import { Badge } from './Badge';
 const meta = {
   title: 'UI/Badge',
   component: Badge,
-  tags: ['autodocs'],
   argTypes: {
     variant: { control: 'select', options: ['primary', 'secondary', 'success', 'error', 'warning'] },
   },

package/src/components/ui/Breadcrumb/Breadcrumb.mdx

@@ -0,0 +1,36 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Breadcrumb.stories';
+
+<Meta of={Stories} />
+
+# Breadcrumb
+
+Hierarchical navigation trail showing the user's location within the site structure.
+
+## When to use
+- Multi-level site structures (3+ levels deep)
+- Pages where users may arrive directly and benefit from context
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Single level
+<Canvas of={Stories.SingleLevel} />
+
+### Two levels
+<Canvas of={Stories.TwoLevels} />
+
+### Deep nested
+<Canvas of={Stories.DeepNested} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Wraps in `<nav aria-label="Breadcrumb">`
+- The current page item has `aria-current="page"`
+- Separator glyphs are `aria-hidden="true"`

package/src/components/ui/Breadcrumb/Breadcrumb.stories.tsx

@@ -4,7 +4,6 @@ import { Breadcrumb } from './Breadcrumb';
 const meta = {
   title: 'UI/Breadcrumb',
   component: Breadcrumb,
-  tags: ['autodocs'],
 } satisfies Meta<typeof Breadcrumb>;
 
 export default meta;

package/src/components/ui/Calendar/Calendar.mdx

@@ -0,0 +1,34 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Calendar.stories';
+
+<Meta of={Stories} />
+
+# Calendar
+
+Date picker calendar grid. Use standalone or as the popover content inside a date input.
+
+## When to use
+- Date selection in forms where a visual calendar improves comprehension
+- Booking flows, scheduling tools, date range pickers
+
+## Examples
+
+### Default (uncontrolled)
+<Canvas of={Stories.Default} />
+
+### With default value
+<Canvas of={Stories.WithDefaultValue} />
+
+### With min/max constraints
+<Canvas of={Stories.WithMinMax} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Grid uses `role="grid"` with `role="gridcell"` for each day
+- Selected date has `aria-selected="true"`; disabled dates have `aria-disabled="true"`
+- Month navigation buttons have descriptive `aria-label` values
+- Arrow keys move focus within the grid; `Enter`/`Space` select a date

package/src/components/ui/Calendar/Calendar.stories.tsx

@@ -5,7 +5,6 @@ import { Calendar } from './Calendar';
 const meta = {
   title: 'UI/Calendar',
   component: Calendar,
-  tags: ['autodocs'],
   decorators: [
     Story => (
       <div style={{ display: 'flex', justifyContent: 'center', padding: '2rem' }}>

package/src/components/ui/Carousel/Carousel.mdx

@@ -0,0 +1,31 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Carousel.stories';
+
+<Meta of={Stories} />
+
+# Carousel
+
+Horizontally scrollable slide container with previous/next navigation.
+
+## When to use
+- Image galleries, featured content, or step-by-step flows where all items share equal priority
+- When screen space is limited and items benefit from a browse interaction
+
+## When not to use
+- Critical content — most users do not interact with carousels; place key content outside
+- More than 5–6 slides — consider a grid or tabbed layout
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Prev/next buttons have `aria-label="Previous"` / `"Next"`
+- The slide container has `aria-live="polite"` to announce slide changes
+- Fully keyboard navigable: buttons receive focus, slides are accessible via arrow keys

package/src/components/ui/Carousel/Carousel.stories.tsx

@@ -4,7 +4,6 @@ import { Carousel } from './Carousel';
 const meta = {
   title: 'UI/Carousel',
   component: Carousel,
-  tags: ['autodocs'],
 } satisfies Meta<typeof Carousel>;
 
 export default meta;

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

@@ -0,0 +1,28 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './DescriptionList.stories';
+
+<Meta of={Stories} />
+
+# DescriptionList
+
+Key-value pairs rendered as a semantic `<dl>` element. Supports stacked and inline layouts.
+
+## When to use
+- Product details, order summaries, profile information
+- Any list of labelled values where semantic key-value association matters
+
+## Examples
+
+### Stacked (default)
+<Canvas of={Stories.Stacked} />
+
+### Inline
+<Canvas of={Stories.Inline} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Uses native `<dl>`, `<dt>`, `<dd>` — correct semantics without extra ARIA

package/src/components/ui/DescriptionList/DescriptionList.stories.tsx

@@ -4,7 +4,6 @@ import { DescriptionList } from './DescriptionList';
 const meta = {
   title: 'UI/DescriptionList',
   component: DescriptionList,
-  tags: ['autodocs'],
 } satisfies Meta<typeof DescriptionList>;
 
 export default meta;

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

@@ -0,0 +1,44 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Link.stories';
+
+<Meta of={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.
+
+## When to use
+- Navigation to another page or route
+- Inline text links within paragraphs
+
+## When not to use
+- An action that does not navigate — use `Button` instead
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Subtle
+<Canvas of={Stories.Subtle} />
+
+### Standalone
+<Canvas of={Stories.Standalone} />
+
+### External
+<Canvas of={Stories.External} />
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Inline usage
+<Canvas of={Stories.InlineUsage} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## 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`

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

@@ -1,9 +1,6 @@
 @layer component {
   .link {
-    --link_color:       var(--color_interactive);
-    --link_color-hover: var(--color_blue--strong);
-
-    color: var(--link_color);
+    color: var(--link_color, var(--color_interactive));
     text-decoration: underline;
     text-underline-offset: 0.2em;
     transition: var(--animation_transition);
@@ -18,7 +15,7 @@
 
   @media (hover: hover) and (pointer: fine) {
     .link:hover {
-      --link_color: var(--link_color-hover);
+      --link_color: var(--link_color-hover, var(--color_blue--strong));
     }
   }
 

package/src/components/ui/Link/Link.stories.tsx

@@ -4,7 +4,6 @@ import { Link } from './Link';
 const meta = {
   title: 'UI/Link',
   component: Link,
-  tags: ['autodocs'],
   argTypes: {
     variant: { control: 'radio', options: ['default', 'subtle', 'standalone'] },
   },

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

@@ -0,0 +1,52 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Loading.stories';
+
+<Meta of={Stories} />
+
+# Loading
+
+Animated spinner that communicates an in-progress operation.
+
+## When to use
+- Inline within a button, card, or container while content is being fetched
+- As a full-section overlay during page transitions
+
+## When not to use
+- When the loading duration exceeds ~10 seconds — consider a progress bar instead
+- As a skeleton replacement — use `Skeleton` for layout-preserving placeholders
+
+## Examples
+
+### Sizes
+<Canvas of={Stories.AllSizes} />
+
+### Small
+<Canvas of={Stories.Small} />
+
+### Medium
+<Canvas of={Stories.Medium} />
+
+### Large
+<Canvas of={Stories.Large} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--loading_color`</td><td>Spinner stroke colour (defaults to `currentcolor`)</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

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

@@ -4,7 +4,6 @@ import { Loading } from './Loading';
 const meta = {
   title: 'UI/Loading',
   component: Loading,
-  tags: ['autodocs'],
   argTypes: {
     size: { control: 'select', options: ['small', 'medium', 'large'] },
   },

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

@@ -0,0 +1,45 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './NotificationBanner.stories';
+
+<Meta of={Stories} />
+
+# NotificationBanner
+
+Full-width banner for page-level system messages. Sits at the top of the page or a major section.
+
+## When to use
+- Maintenance windows, feature announcements, or system-wide errors
+- When the message applies to the entire page rather than a specific component
+
+## When not to use
+- Inline content feedback — use `Alert` instead
+- Transient feedback after a user action — use `Toast`
+
+## Examples
+
+### Info
+<Canvas of={Stories.Info} />
+
+### Success
+<Canvas of={Stories.Success} />
+
+### Warning
+<Canvas of={Stories.Warning} />
+
+### Error
+<Canvas of={Stories.Error} />
+
+### With action
+<Canvas of={Stories.WithAction} />
+
+### Dismissible
+<Canvas of={Stories.Dismissible} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Uses `role="alert"` for error/warning variants and `role="status"` for info/success
+- Dismiss button has `aria-label="Dismiss notification"`

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

@@ -1,16 +1,12 @@
 @layer component {
   .banner {
-    --banner_bg: var(--color_blue--subtle);
-    --banner_text: var(--color_on-blue--subtle);
-    --banner_border: var(--color_blue);
-
     display: flex;
     align-items: center;
     gap: var(--space_m);
     padding: var(--space_s) var(--space_m);
-    background-color: var(--banner_bg);
-    color: var(--banner_text);
-    border-block-end: 3px solid var(--banner_border);
+    background-color: var(--banner_bg, var(--color_blue--subtle));
+    color: var(--banner_text, var(--color_on-blue--subtle));
+    border-block-end: 3px solid var(--banner_border, var(--color_blue));
     font-size: var(--font_size--body);
     line-height: var(--font_line-height--body);
     width: 100%;

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

@@ -1,10 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { NotificationBanner } from './NotificationBanner';
+import { Button } from '../../interaction/Button/Button';
 
 const meta = {
   title: 'UI/NotificationBanner',
   component: NotificationBanner,
-  tags: ['autodocs'],
 } satisfies Meta<typeof NotificationBanner>;
 
 export default meta;
@@ -18,7 +18,7 @@ export const WithAction: Story = {
   args: {
     variant: 'info',
     children: 'A new version is available.',
-    action: <button type="button">Update now</button>,
+    action: <Button size="small">Update now</Button>,
   },
 };
 export const Dismissible: Story = {

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

@@ -0,0 +1,39 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Pagination.stories';
+
+<Meta of={Stories} />
+
+# Pagination
+
+Navigation control for paged data sets. Renders prev/next buttons plus numbered page links.
+
+## When to use
+- Tables, lists, and search results with more items than fit on one screen
+- When infinite scroll is not appropriate (e.g. users need to return to a specific page)
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### First page
+<Canvas of={Stories.FirstPage} />
+
+### Last page
+<Canvas of={Stories.LastPage} />
+
+### Many pages
+<Canvas of={Stories.ManyPages} />
+
+### Interactive
+<Canvas of={Stories.Interactive} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## 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

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

@@ -14,10 +14,6 @@
   }
 
   .button {
-    --btn_bg:         transparent;
-    --btn_color:      var(--color_on-bg);
-    --btn_border:     var(--color_bg--subtle);
-
     all: unset;
     display: inline-flex;
     align-items: center;
@@ -26,9 +22,9 @@
     height: 2.25rem;
     padding-inline: var(--space_xs);
     border-radius: var(--border_radius--xs);
-    border: 1px solid var(--btn_border);
-    background-color: var(--btn_bg);
-    color: var(--btn_color);
+    border: 1px solid var(--btn_border, var(--color_bg--subtle));
+    background-color: var(--btn_bg, transparent);
+    color: var(--btn_color, var(--color_on-bg));
     font-family: var(--font_family--body);
     font-size: var(--font_size--body);
     font-variant-numeric: tabular-nums;

package/src/components/ui/Pagination/Pagination.stories.tsx

@@ -5,7 +5,6 @@ import { Pagination } from './Pagination';
 const meta = {
   title: 'UI/Pagination',
   component: Pagination,
-  tags: ['autodocs'],
 } satisfies Meta<typeof Pagination>;
 
 export default meta;