@boostdev/design-system-components 0.1.13 → 0.1.15

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;

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

@@ -0,0 +1,52 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Progress.stories';
+
+<Meta of={Stories} />
+
+# Progress
+
+Horizontal progress bar communicating completion towards a goal.
+
+## When to use
+- File uploads, form step completion, onboarding flows
+- Any process with a known total and measurable progress
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With label
+<Canvas of={Stories.WithLabel} />
+
+### All sizes
+<Canvas of={Stories.AllSizes} />
+
+### Complete
+<Canvas of={Stories.Complete} />
+
+### Empty
+<Canvas of={Stories.Empty} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--progress_color-active`</td><td>Filled track colour (defaults to `var(--color_active)`)</td></tr>
+<tr><td>`--progress_color-track`</td><td>Empty track colour</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Uses `<progress>` element 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

@@ -23,10 +23,8 @@
   }
 
   .track {
-    --progress_height: var(--space_xs);
-
     width: 100%;
-    height: var(--progress_height);
+    height: var(--progress_height, var(--space_xs));
     background-color: var(--color_bg--subtle);
     border-radius: 999px;
     overflow: hidden;

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

@@ -4,7 +4,6 @@ import { Progress } from './Progress';
 const meta = {
   title: 'UI/Progress',
   component: Progress,
-  tags: ['autodocs'],
   argTypes: {
     size: { control: 'radio', options: ['small', 'medium', 'large'] },
     value: { control: { type: 'range', min: 0, max: 100 } },

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

@@ -0,0 +1,46 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './ProgressCircle.stories';
+
+<Meta of={Stories} />
+
+# ProgressCircle
+
+Circular progress indicator. Use when a compact representation fits better than a horizontal bar.
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With value
+<Canvas of={Stories.WithValue} />
+
+### Sizes
+<Canvas of={Stories.Small} />
+<Canvas of={Stories.Large} />
+
+### Complete
+<Canvas of={Stories.Complete} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<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>
+</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`

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

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

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

@@ -0,0 +1,29 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Separator.stories';
+
+<Meta of={Stories} />
+
+# Separator
+
+Visual divider between content sections. Renders a semantic `<hr>` (horizontal) or a `<div role="separator">` (vertical).
+
+## When to use
+- Between logically distinct content blocks in a layout
+- To separate items in a menu or list
+
+## Examples
+
+### Horizontal
+<Canvas of={Stories.Horizontal} />
+
+### Vertical
+<Canvas of={Stories.Vertical} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Horizontal variant uses `<hr>` — natively announces a thematic break to screen readers
+- Vertical variant uses `role="separator"` with `aria-orientation="vertical"`

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

@@ -4,7 +4,6 @@ import { Separator } from './Separator';
 const meta = {
   title: 'UI/Separator',
   component: Separator,
-  tags: ['autodocs'],
   argTypes: {
     orientation: { control: 'radio', options: ['horizontal', 'vertical'] },
   },

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

@@ -0,0 +1,36 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Skeleton.stories';
+
+<Meta of={Stories} />
+
+# Skeleton
+
+Layout-preserving placeholder shown while content is loading. Renders a shimmer block sized by `className` or inline style.
+
+## When to use
+- Replace individual content areas (text lines, images, cards) during async data fetching
+- Preserve perceived layout stability during initial page load
+
+## When not to use
+- For very short loads (< 300 ms) — consider a spinner instead to avoid layout shift
+- When you cannot predict content dimensions — use a `Loading` spinner
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Text line
+<Canvas of={Stories.TextLine} />
+
+### Card layout
+<Canvas of={Stories.Card} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## 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

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

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

package/src/components/ui/SkipLink/SkipLink.mdx

@@ -0,0 +1,34 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './SkipLink.stories';
+
+<Meta of={Stories} />
+
+# SkipLink
+
+Visually hidden link that becomes visible on keyboard focus, allowing keyboard users to skip repetitive navigation and jump directly to the main content.
+
+## When to use
+- At the very top of every page, before any navigation
+- Required for WCAG 2.4.1 compliance (Bypass Blocks)
+
+## Notes
+
+The link is visually hidden until focused. Press **Tab** on the preview below to reveal it.
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Custom target
+<Canvas of={Stories.CustomTarget} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Renders as a standard `<a>` — no special ARIA needed
+- The `href` must match a valid `id` on the target element (e.g. `<main id="main-content">`)
+- Visible focus style is required — the component applies a high-contrast outline on `:focus-visible`

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

@@ -4,7 +4,6 @@ import { SkipLink } from './SkipLink';
 const meta = {
   title: 'UI/SkipLink',
   component: SkipLink,
-  tags: ['autodocs'],
   decorators: [
     Story => (
       <div style={{ minHeight: '4rem', position: 'relative' }}>

package/src/components/ui/Table/Table.mdx

@@ -0,0 +1,38 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Table.stories';
+
+<Meta of={Stories} />
+
+# Table
+
+Data table with optional sortable columns and caption.
+
+## When to use
+- Structured data with relationships across rows and columns
+- When users need to compare values across multiple attributes
+
+## When not to use
+- Layout purposes — use CSS Grid or Flexbox
+- Simple key-value data — use `DescriptionList` instead
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Sortable columns
+<Canvas of={Stories.Sortable} />
+
+### With caption
+<Canvas of={Stories.WithCaption} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Wraps in `<table>` with `<thead>` and `<tbody>`
+- Column headers use `<th scope="col">`
+- Sortable columns set `aria-sort="ascending"` / `"descending"` / `"none"`
+- `caption` renders as `<caption>` — the accessible name of the table

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

@@ -7,7 +7,6 @@ type User = { name: string; role: string; status: string; joined: string };
 const meta = {
   title: 'UI/Table',
   component: Table,
-  tags: ['autodocs'],
 } satisfies Meta<typeof Table<User>>;
 
 export default meta;

package/src/components/ui/Tabs/Tabs.mdx

@@ -0,0 +1,40 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Tabs.stories';
+
+<Meta of={Stories} />
+
+# Tabs
+
+Organises content into discrete panels accessible via a horizontal tab list.
+
+## When to use
+- Switching between related views without a page navigation
+- When all tab panels share the same context (e.g. product details: Overview, Specs, Reviews)
+
+## When not to use
+- More than 5–6 tabs — consider a `Select` or sidebar navigation instead
+- When panels are only loosely related — use separate pages or sections
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With default open tab
+<Canvas of={Stories.WithDefaultTab} />
+
+### With disabled tab
+<Canvas of={Stories.WithDisabledTab} />
+
+### Rich content
+<Canvas of={Stories.RichContent} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Implements ARIA tabs pattern: `role="tablist"`, `role="tab"`, `role="tabpanel"`
+- Arrow keys navigate between tabs; `Enter`/`Space` activate
+- Active tab uses `aria-selected="true"`; panel linked via `aria-labelledby`

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

@@ -11,9 +11,6 @@
   }
 
   .tab {
-    --tab_color:        var(--color_on-bg);
-    --tab_border-color: transparent;
-
     all: unset;
     display: inline-flex;
     align-items: center;
@@ -21,8 +18,8 @@
     font-family: var(--font_family--body);
     font-size: var(--font_size--body);
     font-weight: var(--font_weight--semibold);
-    color: var(--tab_color);
-    border-bottom: 2px solid var(--tab_border-color);
+    color: var(--tab_color, var(--color_on-bg));
+    border-bottom: 2px solid var(--tab_border-color, transparent);
     margin-bottom: -1px;
     cursor: pointer;
     transition: var(--animation_transition);