@boostdev/design-system-components 0.1.12 → 0.1.14

package/src/components/interaction/form/Slider/Slider.mdx

@@ -0,0 +1,58 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Slider.stories';
+
+<Meta of={Stories} />
+
+# Slider
+
+Range input for selecting a numeric value within a bounded range.
+
+## When to use
+- Volume, brightness, price range — any continuously variable numeric value
+- When approximate values are acceptable and a visual range is helpful
+
+## When not to use
+- Precise numeric entry — use `NumberInput` instead
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With value display
+<Canvas of={Stories.WithValue} />
+
+### Custom range
+<Canvas of={Stories.CustomRange} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--slider_color-active`</td><td>`var(--color_active)`</td><td>Filled track and thumb colour</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Native `<input type="range">` with `aria-valuemin`, `aria-valuemax`, `aria-valuenow`
+- Label linked via `id`/`htmlFor`
+- Arrow keys adjust value by `step`; `Home`/`End` jump to min/max

package/src/components/interaction/form/Slider/Slider.stories.tsx

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

package/src/components/interaction/form/Switch/Switch.mdx

@@ -0,0 +1,61 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Switch.stories';
+
+<Meta of={Stories} />
+
+# Switch
+
+Toggle control for binary settings that take immediate effect — without requiring a form submit.
+
+## When to use
+- Enabling/disabling a feature or preference that applies instantly (dark mode, notifications)
+
+## When not to use
+- Choices that require a form submit to apply — use `Checkbox`
+- Choices within a multi-select group — use `Checkbox`
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Checked (on)
+<Canvas of={Stories.Checked} />
+
+### All sizes
+<Canvas of={Stories.AllSizes} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+### Disabled + checked
+<Canvas of={Stories.DisabledChecked} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--switch_color-active`</td><td>`var(--color_active--subtle)`</td><td>Track colour when on</td></tr>
+<tr><td>`--switch_color-thumb`</td><td>`var(--color_active--strong)`</td><td>Thumb colour when on</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Renders `<input type="checkbox">` with `role="switch"` and `aria-checked`
+- Label is always associated; state is communicated via the accessible name

package/src/components/interaction/form/Switch/Switch.module.css

@@ -4,10 +4,6 @@
     --switch_track-pad:    var(--space_xxxs);
     --switch_track-height: calc(var(--switch_thumb-size) + var(--switch_track-pad) * 2);
     --switch_track-width:  calc(var(--switch_thumb-size) * 2 + var(--switch_track-pad) * 2);
-    --track_bg:            var(--color_grey--subtle);
-    --track_active:        var(--color_active--subtle);
-    --thumb_bg:            var(--color_grey);
-    --thumb_bg--active:    var(--color_active--strong);
 
     color: var(--switch_color, var(--color_on-bg));
     display: flex;
@@ -57,11 +53,11 @@
     width: var(--switch_track-width);
     height: var(--switch_track-height);
     border-radius: 999px;
-    background-color: var(--track_bg);
+    background-color: var(--track_bg, var(--color_grey--subtle));
     padding-inline: var(--switch_track-pad);
     pointer-events: none;
     transition: var(--animation_transition);
-    outline: 1px solid var(--thumb_bg);
+    outline: 1px solid var(--thumb_bg, var(--color_grey));
     outline-offset: var(--outline_offset);
   }
 
@@ -71,7 +67,7 @@
     width: var(--switch_thumb-size);
     height: var(--switch_thumb-size);
     border-radius: 50%;
-    background-color: var(--thumb_bg);
+    background-color: var(--thumb_bg, var(--color_grey));
     box-shadow: var(--shadow_s);
     transition: var(--animation_transition);
     transform: translateX(0);
@@ -84,12 +80,12 @@
 
   /* Checked state via CSS sibling combinator */
   .switch:checked + .track {
-    background-color: var(--track_active);
-    outline-color: var(--thumb_bg--active);
+    background-color: var(--track_active, var(--color_active--subtle));
+    outline-color: var(--thumb_bg--active, var(--color_active--strong));
   }
 
   .switch:checked + .track .thumb {
-    background-color: var(--thumb_bg--active);
+    background-color: var(--thumb_bg--active, var(--color_active--strong));
     transform: translateX(var(--switch_thumb-size));
   }
 

package/src/components/interaction/form/Switch/Switch.stories.tsx

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

package/src/components/interaction/form/Textarea/Textarea.mdx

@@ -0,0 +1,41 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Textarea.stories';
+
+<Meta of={Stories} />
+
+# Textarea
+
+Multi-line text input with label, hint, and error support.
+
+## When to use
+- Free-form text input where content is expected to span multiple lines (comments, descriptions, notes)
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With value
+<Canvas of={Stories.WithValue} />
+
+### With hint
+<Canvas of={Stories.WithHint} />
+
+### With error
+<Canvas of={Stories.WithError} />
+
+### Tall (8 rows)
+<Canvas of={Stories.Tall} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Native `<textarea>` with label linked via `id`/`htmlFor`
+- Error message linked via `aria-describedby`
+- `rows` controls the visible height — does not limit character count

package/src/components/interaction/form/Textarea/Textarea.stories.tsx

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

package/src/components/layout/ButtonGroup/ButtonGroup.mdx

@@ -0,0 +1,47 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './ButtonGroup.stories';
+
+<Meta of={Stories} />
+
+# ButtonGroup
+
+Layout wrapper that arranges `Button` children according to a contextual variant. Handles spacing, alignment, and direction.
+
+## Variants
+
+
+<table>
+<thead>
+<tr><th>Variant</th><th>Layout</th><th>Use case</th></tr>
+</thead>
+<tbody>
+<tr><td>`flow`</td><td>Horizontal, space-between</td><td>Form step navigation (Back / Next)</td></tr>
+<tr><td>`card`</td><td>Horizontal, end-aligned</td><td>Card footer actions</td></tr>
+<tr><td>`modal`</td><td>Horizontal, end-aligned, compact</td><td>Dialog footer</td></tr>
+<tr><td>`content`</td><td>Horizontal, start-aligned</td><td>Inline action groups</td></tr>
+</tbody>
+</table>
+
+
+## Examples
+
+### Flow
+<Canvas of={Stories.Flow} />
+
+### Card
+<Canvas of={Stories.Card} />
+
+### Modal
+<Canvas of={Stories.Modal} />
+
+### Content
+<Canvas of={Stories.Content} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Renders as `<div role="group">` — no additional ARIA needed for the wrapper
+- Individual buttons inside retain their own accessible names

package/src/components/layout/ButtonGroup/ButtonGroup.module.css

@@ -13,16 +13,16 @@
     align-items: center;
   }
 
-  .buttonGroup.--variant__card .container {
+  .buttonGroup.--variant_card .container {
     align-items: stretch;
   }
 
-  .buttonGroup.--variant__flow .container,
-  .buttonGroup.--variant__modal .container {
+  .buttonGroup.--variant_flow .container,
+  .buttonGroup.--variant_modal .container {
     align-items: center;
   }
 
-  .buttonGroup.--variant__content .container {
+  .buttonGroup.--variant_content .container {
     align-items: flex-start;
   }
 
@@ -33,25 +33,25 @@
         justify-content: space-between;
       }
 
-      .buttonGroup.--variant__modal .container > :first-child:last-child,
-      .buttonGroup.--variant__flow .container > :first-child:last-child {
+      .buttonGroup.--variant_modal .container > :first-child:last-child,
+      .buttonGroup.--variant_flow .container > :first-child:last-child {
         margin-inline-start: auto;
       }
 
-      .buttonGroup.--variant__card .container {
+      .buttonGroup.--variant_card .container {
         justify-content: center;
       }
 
-      .buttonGroup.--variant__modal .container {
+      .buttonGroup.--variant_modal .container {
         justify-content: flex-end;
       }
 
-      .buttonGroup.--variant__content .container {
+      .buttonGroup.--variant_content .container {
         justify-content: flex-start;
         align-items: center;
       }
 
-      .buttonGroup.--variant__grid .container {
+      .buttonGroup.--variant_grid .container {
         justify-content: center;
       }
     }

package/src/components/layout/ButtonGroup/ButtonGroup.stories.tsx

@@ -1,11 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { ButtonGroup } from './ButtonGroup';
-import { Button } from '../../interaction/Button/Button';
+import { Button } from '../../interaction/Button';
 
 const meta = {
   title: 'Layout/ButtonGroup',
   component: ButtonGroup,
-  tags: ['autodocs'],
   argTypes: {
     variant: { control: 'select', options: ['flow', 'card', 'modal', 'content', undefined] },
   },

package/src/components/layout/Card/Card.mdx

@@ -0,0 +1,58 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Card.stories';
+
+<Meta of={Stories} />
+
+# Card
+
+Contained surface for grouping related content. Three visual variants provide different levels of elevation. When `onClick` is supplied, renders as a `<button>`.
+
+## When to use
+- Group content that belongs together (product listing, profile summary, dashboard widget)
+- Clickable card navigating to a detail view
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Elevated
+<Canvas of={Stories.Elevated} />
+
+### Outlined
+<Canvas of={Stories.Outlined} />
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Centered text
+<Canvas of={Stories.Centered} />
+
+### Clickable
+<Canvas of={Stories.Clickable} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--card_bg`</td><td>Card background colour</td></tr>
+<tr><td>`--card_on-bg`</td><td>Card text colour</td></tr>
+<tr><td>`--card_border-color`</td><td>Border colour (outlined variant)</td></tr>
+<tr><td>`--card_shadow`</td><td>Box shadow (elevated variant)</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Static card renders as `<div>` — no interactive role
+- Clickable card renders as `<button>` — keyboard and screen reader accessible
+- Ensure clickable cards have a meaningful accessible name (via visible text content)

package/src/components/layout/Card/Card.stories.tsx

@@ -4,7 +4,6 @@ import { Card } from './Card';
 const meta = {
   title: 'Layout/Card',
   component: Card,
-  tags: ['autodocs'],
   argTypes: {
     variant: { control: 'select', options: ['default', 'elevated', 'outlined'] },
     padding: { control: 'select', options: ['none', 'small', 'medium', 'large'] },

package/src/components/layout/IconWrapper/IconWrapper.mdx

@@ -0,0 +1,39 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './IconWrapper.stories';
+
+<Meta of={Stories} />
+
+# IconWrapper
+
+Circular container that sizes to its own `font-size`. Use to give an SVG icon a consistent background pill in lists, cards, and badges.
+
+## When to use
+- Icon + background in feature lists or empty states
+- Avatar-like icon representations
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--icon-wrapper_color`</td><td>`var(--color_cta--subtle)`</td><td>Background colour</td></tr>
+<tr><td>`--icon-wrapper_on-color`</td><td>`var(--color_on-cta--subtle)`</td><td>Icon colour</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Purely decorative wrapper — the icon inside should carry its own `aria-label` or be `aria-hidden` with a sibling visible label

package/src/components/layout/IconWrapper/IconWrapper.stories.tsx

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

package/src/components/layout/SectionHeader/SectionHeader.mdx

@@ -0,0 +1,38 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './SectionHeader.stories';
+
+<Meta of={Stories} />
+
+# SectionHeader
+
+Heading block with optional subtitle for introducing a content section.
+
+## When to use
+- Above a grid of cards, a data table, or any content region that needs a title
+- Marketing and landing page sections
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### Without subtitle
+<Canvas of={Stories.WithoutSubtitle} />
+
+### Large
+<Canvas of={Stories.Large} />
+
+### Small
+<Canvas of={Stories.Small} />
+
+### Centered
+<Canvas of={Stories.Centered} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Title renders as `<h2>` by default — override with `titleAs` to fit document outline
+- Subtitle is a `<p>` following the heading — no additional ARIA needed

package/src/components/layout/SectionHeader/SectionHeader.stories.tsx

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

package/src/components/ui/Accordion/Accordion.mdx

@@ -0,0 +1,40 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Accordion.stories';
+
+<Meta of={Stories} />
+
+# Accordion
+
+Vertically stacked sections that can be expanded and collapsed independently.
+
+## When to use
+- FAQs, glossaries, and settings panels with many optional details
+- Reducing vertical space when most users need only a few items
+
+## When not to use
+- When users need to compare multiple sections simultaneously — show them all by default
+- When there are fewer than 3 items — just show the content
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With default open item
+<Canvas of={Stories.WithDefaultOpen} />
+
+### Allow multiple open
+<Canvas of={Stories.AllowMultiple} />
+
+### With disabled item
+<Canvas of={Stories.WithDisabledItem} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Implements ARIA disclosure pattern: trigger buttons use `aria-expanded` and `aria-controls`
+- Content panels use `role="region"` with `aria-labelledby`
+- Disabled items have `aria-disabled="true"` and are excluded from keyboard focus

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

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

package/src/components/ui/Alert/Alert.mdx

@@ -0,0 +1,63 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Alert.stories';
+
+<Meta of={Stories} />
+
+# Alert
+
+Inline contextual feedback message. Use for confirmations, warnings, errors, and informational notices inline within page content.
+
+## When to use
+- Feedback that is directly related to an action on the current page
+- Persistent notices that must remain visible while the user takes action
+
+## When not to use
+- Transient feedback after an action — use `Toast` instead
+- Page-level banners that span the full width — use `NotificationBanner`
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Success
+<Canvas of={Stories.Success} />
+
+### Error
+<Canvas of={Stories.Error} />
+
+### Warning
+<Canvas of={Stories.Warning} />
+
+### Info
+<Canvas of={Stories.Info} />
+
+### With title
+<Canvas of={Stories.WithTitle} />
+
+### Dismissible
+<Canvas of={Stories.Dismissible} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--alert_color`</td><td>Background colour (defaults to variant semantic token)</td></tr>
+<tr><td>`--alert_on-color`</td><td>Text and icon colour</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Uses `role="alert"` to announce content to screen readers immediately on mount
+- `onDismiss` close button has `aria-label="Dismiss"` — ensure the label is meaningful in context
+- Colour alone is not used to convey meaning: each variant includes an icon

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

@@ -1,17 +1,13 @@
 @layer component {
     .alert {
-        --alert_bg: var(--color_blue--subtle);
-        --alert_text: var(--color_on-blue--subtle);
-        --alert_border: var(--color_blue);
-
         display: flex;
         align-items: flex-start;
         gap: var(--space_s);
         padding: var(--space_m);
         border-radius: var(--border_radius--s);
-        border-inline-start: var(--space_s) solid var(--alert_border);
-        background-color: var(--alert_bg);
-        color: var(--alert_text);
+        border-inline-start: var(--space_s) solid var(--alert_border, var(--color_blue));
+        background-color: var(--alert_bg, var(--color_blue--subtle));
+        color: var(--alert_text, var(--color_on-blue--subtle));
         font-size: var(--font_size--body);
         line-height: var(--font_line-height--body);
     }

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

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