@boostdev/design-system-components 0.1.12 → 0.1.14

package/src/components/interaction/Button/Button.mdx

@@ -0,0 +1,73 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Button.stories';
+
+<Meta of={Stories} />
+
+# Button
+
+Primary interactive element for triggering actions. Renders as `<button>` or `<a>` depending on whether `href` is provided.
+
+## When to use
+- The main action on a page or dialog (`primary`)
+- Secondary or destructive actions (`secondary`)
+- Navigation that should look like an action (`href` → renders as `<a>`)
+
+## When not to use
+- Navigation to another page when it reads naturally as a link — use `Link` instead
+- When the action is purely icon-based without a label — ensure `aria-label` is set
+
+## Examples
+
+### All variants & sizes
+<Canvas of={Stories.AllVariants} />
+
+### Primary
+<Canvas of={Stories.Primary} />
+
+### Secondary
+<Canvas of={Stories.Secondary} />
+
+### Sizes
+<Canvas of={Stories.Small} />
+<Canvas of={Stories.Medium} />
+<Canvas of={Stories.Large} />
+
+### As a link
+<Canvas of={Stories.AsLink} />
+
+### With icons
+<Canvas of={Stories.WithIcons} />
+
+### Pulse (CTA emphasis)
+<Canvas of={Stories.WithPulse} />
+
+### Disabled
+<Canvas of={Stories.Disabled} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--button_bg`</td><td>Background colour</td></tr>
+<tr><td>`--button_color`</td><td>Text colour</td></tr>
+<tr><td>`--button_border-color`</td><td>Border colour</td></tr>
+<tr><td>`--button_bg--hover`</td><td>Background on hover</td></tr>
+<tr><td>`--button_color--hover`</td><td>Text colour on hover</td></tr>
+</tbody>
+</table>
+
+
+## Accessibility
+
+- Always provide children or `aria-label` for icon-only buttons
+- Disabled state sets `aria-disabled="true"` and removes the element from the tab order
+- When rendered as `<a>`, `href` must point to a valid destination
+- `hasPulse` animation respects `prefers-reduced-motion`

package/src/components/interaction/Button/Button.module.css

@@ -1,55 +1,45 @@
 @keyframes pulse {
   0% {
     transform: scale(1);
-    box-shadow: 0 0 0 0 rgb(from var(--button_pulse-color) r g b / 50%);
+    box-shadow: 0 0 0 0 rgb(from var(--button_pulse-color, var(--color_cta)) r g b / 50%);
   }
 
   70% {
     transform: scale(1.01);
-    box-shadow: 0 0 0 var(--space_m) rgb(from var(--button_pulse-color) r g b / 0%);
+    box-shadow: 0 0 0 var(--space_m) rgb(from var(--button_pulse-color, var(--color_cta)) r g b / 0%);
   }
 
   100% {
     transform: scale(1);
-    box-shadow: 0 0 0 0 rgb(from var(--button_pulse-color) r g b / 0%);
+    box-shadow: 0 0 0 0 rgb(from var(--button_pulse-color, var(--color_cta)) r g b / 0%);
   }
 }
 
 @layer component {
   .button,
   .button[href] {
-    /* Component tokens — override from a parent context or inline style */
-    --button_height:       3em;
-    --button_font-size:    inherit;
-    --button_bg:           var(--color_cta);
-    --button_text:         var(--color_on-cta);
-    --button_border-color: var(--color_cta);
-    --button_pulse-color:  var(--button_bg);
-
     all: unset;
     position: relative;
     font: inherit;
     padding-inline: var(--space_l);
     display: inline-flex;
     gap: var(--space_xs);
-    border-radius: var(--border_radius--s);
+    border-radius: var(--button_border_radius--s, var(--border_radius--s));
     align-items: center;
     cursor: pointer;
     scroll-padding-block-end: var(--space_l);
     justify-content: center;
-    height: var(--button_height);
-    font-size: var(--button_font-size);
+    height: var(--button_height, 3em);
+    font-size: var(--button_font-size, inherit);
     white-space: nowrap;
     line-height: 1;
-    background-color: var(--button_bg);
-    color: var(--button_text);
-    border: 2px solid var(--button_border-color);
+    background-color: var(--button_bg, var(--color_cta));
+    color: var(--button_text, var(--color_on-cta));
+    border: 2px solid var(--button_border-color, var(--color_cta));
     transition: var(--animation_transition);
   }
 
   .button.--primary {
-    --button_bg:           var(--color_cta);
-    --button_text:         var(--color_on-cta);
     --button_border-color: transparent;
   }
 
@@ -62,6 +52,7 @@
   .button.--size_small {
     --button_height:    2.25em;
     --button_font-size: var(--font_size--body--s);
+    --button_border_radius--s: var(--border_radius--xs);
 
     padding-inline: var(--space_m);
   }
@@ -73,10 +64,11 @@
   }
 
   .button.--size_large {
-    --button_height:    3.75em;
     --button_font-size: var(--font_size--heading-3);
 
     padding-inline: var(--space_xl);
+    --button_border_radius--s: var(--border_radius--m);
+
   }
 
   .button.--hasPulse {

package/src/components/interaction/Button/Button.stories.tsx

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

package/src/components/interaction/Command/Command.mdx

@@ -0,0 +1,28 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Command.stories';
+
+<Meta of={Stories} />
+
+# Command
+
+Keyboard-first command palette for searching and executing actions. Commonly triggered by `⌘K`.
+
+## When to use
+- Applications with many actions that power users access via keyboard
+- Global search combining navigation, actions, and settings
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Input has `role="combobox"` with `aria-controls` pointing to the results list
+- Results list uses `role="listbox"` with `role="option"` items
+- `aria-activedescendant` tracks the highlighted option
+- Keyboard: `↑`/`↓` to navigate, `Enter` to execute, `Escape` to dismiss

package/src/components/interaction/Command/Command.module.css

@@ -11,7 +11,8 @@
   }
 
   .dialog::backdrop {
-    background: rgb(0 0 0 / 50%);
+    background-color: var(--command_backdrop-color, rgb(0 0 0 / 50%));
+    backdrop-filter: blur(3px);
   }
 
   .palette {

package/src/components/interaction/Command/Command.stories.tsx

@@ -2,11 +2,11 @@ import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import { Command } from './Command';
 import type { CommandItem } from './Command';
+import { Button } from '../Button/Button';
 
 const meta = {
   title: 'Interaction/Command',
   component: Command,
-  tags: ['autodocs'],
 } satisfies Meta<typeof Command>;
 
 export default meta;
@@ -25,9 +25,9 @@ export const Default: Story = {
     const [open, setOpen] = useState(false);
     return (
       <>
-        <button type="button" onClick={() => setOpen(true)}>
+        <Button onClick={() => setOpen(true)}>
           Open Command Palette <kbd>⌘K</kbd>
-        </button>
+        </Button>
         <Command isOpen={open} items={items} onClose={() => setOpen(false)} />
       </>
     );

package/src/components/interaction/Dialog/Dialog.mdx

@@ -0,0 +1,57 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Dialog.stories';
+
+<Meta of={Stories} />
+
+# Dialog
+
+Modal overlay using the native `<dialog>` element. Traps focus inside the dialog while open and renders a dimmed, blurred backdrop.
+
+## When to use
+- Confirmations, alerts, and short focused tasks that need the user's attention before continuing
+- Forms that are secondary to the main page flow
+
+## When not to use
+- Complex workflows with many steps — consider a dedicated page or a `Drawer`
+- Non-critical information — use a `Popover` or inline content instead
+
+## Examples
+
+### Default (open)
+<Canvas of={Stories.Default} />
+
+### Interactive (controlled)
+<Canvas of={Stories.Interactive} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## CSS variables
+
+
+<table>
+<thead>
+<tr><th>Variable</th><th>Default</th><th>Description</th></tr>
+</thead>
+<tbody>
+<tr><td>`--dialog_color`</td><td>`var(--color_grey--subtle)`</td><td>Dialog background</td></tr>
+<tr><td>`--dialog_on-color`</td><td>`var(--color_on-grey--subtle)`</td><td>Dialog text colour</td></tr>
+<tr><td>`--dialog_backdrop-color`</td><td>`rgb(0 0 0 / 50%)`</td><td>Backdrop overlay colour</td></tr>
+</tbody>
+</table>
+
+
+## Behaviour
+
+- Opens via `showModal()` — provides native focus trapping and `Escape` key to close
+- Backdrop click calls `onClose`
+- Body scroll is locked while open (`overflow: hidden`)
+- `onClose` is also called on `Escape` via the native `cancel` event
+
+## Accessibility
+
+- Native `<dialog>` provides `role="dialog"` and `aria-modal="true"` automatically
+- Focus is moved to the first focusable element inside on open
+- `Escape` key closes the dialog
+- Add `aria-labelledby` pointing to the dialog title for screen readers

package/src/components/interaction/Dialog/Dialog.module.css

@@ -8,6 +8,7 @@
     padding: var(--space_l);
     max-width: 90svw;
     max-height: 90svh;
+    overflow: visible;
   }
 
   .dialogContent {
@@ -42,4 +43,9 @@
     width: 1.25em;
     height: 1.25em;
   }
+
+  .dialog::backdrop {
+    background-color: var(--dialog_backdrop-color, rgb(0 0 0 / 50%));
+    backdrop-filter: blur(3px);
+  }
 }

package/src/components/interaction/Dialog/Dialog.stories.tsx

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

package/src/components/interaction/Drawer/Drawer.mdx

@@ -0,0 +1,35 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Drawer.stories';
+
+<Meta of={Stories} />
+
+# Drawer
+
+Slide-in panel from the left or right edge of the viewport. Use for navigation, filters, or secondary task flows that should not interrupt the main content.
+
+## When to use
+- Mobile navigation panels
+- Filter sidebars in data-heavy views
+- Multi-step flows that are secondary to the main page
+
+## When not to use
+- Simple confirmations or short prompts — use `Dialog`
+- Content that always needs to be visible — use a sidebar layout instead
+
+## Examples
+
+### Left
+<Canvas of={Stories.Left} />
+
+### Right
+<Canvas of={Stories.Right} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Uses `<dialog>` internally — provides native focus trapping and `Escape` to close
+- `aria-label` on the dialog describes the drawer's purpose
+- Body scroll locked while open

package/src/components/interaction/Drawer/Drawer.module.css

@@ -14,7 +14,8 @@
   }
 
   .drawer::backdrop {
-    background: rgb(0 0 0 / 50%);
+    background-color: var(--drawer_backdrop-color, rgb(0 0 0 / 50%));
+    backdrop-filter: blur(3px);
   }
 
   .panel {
@@ -28,7 +29,7 @@
     color: var(--drawer_on-color, var(--color_on-bg));
     box-shadow: var(--shadow_xl);
     overflow: hidden;
-    transition: transform var(--animation_transition-duration) var(--animation_easing);
+    transition: var(--animation_transition);
   }
 
   .--side_right .panel {
@@ -48,13 +49,6 @@
     flex-shrink: 0;
   }
 
-  .title {
-    margin: 0;
-    font-size: var(--font_size--heading--s);
-    font-weight: var(--font_weight--semibold);
-    line-height: var(--font_line-height--heading);
-  }
-
   .closeButton {
     all: unset;
     display: flex;

package/src/components/interaction/Drawer/Drawer.stories.tsx

@@ -1,11 +1,11 @@
 import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import { Drawer } from './Drawer';
+import { Button } from '../Button/Button';
 
 const meta = {
   title: 'Interaction/Drawer',
   component: Drawer,
-  tags: ['autodocs'],
 } satisfies Meta<typeof Drawer>;
 
 export default meta;
@@ -16,7 +16,7 @@ export const Right: Story = {
     const [open, setOpen] = useState(false);
     return (
       <>
-        <button type="button" onClick={() => setOpen(true)}>Open right drawer</button>
+        <Button onClick={() => setOpen(true)}>Open right drawer</Button>
         <Drawer isOpen={open} onClose={() => setOpen(false)} title="Settings" side="right">
           <p>Drawer content goes here. You can put any React content inside.</p>
         </Drawer>
@@ -30,7 +30,7 @@ export const Left: Story = {
     const [open, setOpen] = useState(false);
     return (
       <>
-        <button type="button" onClick={() => setOpen(true)}>Open left drawer</button>
+        <Button onClick={() => setOpen(true)}>Open left drawer</Button>
         <Drawer isOpen={open} onClose={() => setOpen(false)} title="Navigation" side="left">
           <nav>
             <ul>

package/src/components/interaction/Drawer/Drawer.tsx

@@ -5,10 +5,11 @@ import { cn } from '@boostdev/design-system-foundation';
 interface DrawerProps {
   isOpen: boolean;
   onClose: () => void;
-  title: string;
+  title: ReactNode;
   children: ReactNode;
   side?: 'left' | 'right';
   className?: string;
+  arialLabel?: string;
 }
 
 export function Drawer({
@@ -17,6 +18,7 @@ export function Drawer({
   title,
   children,
   side = 'right',
+  arialLabel = '',
   className,
 }: Readonly<DrawerProps>) {
   const dialogRef = useRef<HTMLDialogElement>(null);
@@ -46,13 +48,13 @@ export function Drawer({
     <dialog
       ref={dialogRef}
       className={cn(css.drawer, css[`--side_${side}`], className)}
-      aria-label={title}
+      aria-label={arialLabel}
       onClick={handleClick}
       onCancel={handleCancel}
     >
       <div className={css.panel}>
         <div className={css.header}>
-          <h2 className={css.title}>{title}</h2>
+          {!!title && title}
           <button
             type="button"
             className={css.closeButton}

package/src/components/interaction/DropdownMenu/DropdownMenu.mdx

@@ -0,0 +1,40 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './DropdownMenu.stories';
+
+<Meta of={Stories} />
+
+# DropdownMenu
+
+Floating menu with a list of selectable actions, triggered by a button. Supports disabled items and separators.
+
+## When to use
+- Overflow actions in a toolbar or table row
+- Context menus on cards or list items
+
+## When not to use
+- Navigation — use a `<nav>` with links
+- More than ~8 items — consider a `Command` palette or a `Select`
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With separator
+<Canvas of={Stories.WithSeparator} />
+
+### With disabled item
+<Canvas of={Stories.WithDisabledItem} />
+
+### Aligned end
+<Canvas of={Stories.AlignedEnd} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Implements ARIA menu pattern: `role="menu"`, `role="menuitem"`
+- Arrow keys navigate items; `Enter`/`Space` activate; `Escape` closes
+- Disabled items have `aria-disabled="true"` and are skipped during keyboard navigation

package/src/components/interaction/DropdownMenu/DropdownMenu.stories.tsx

@@ -1,10 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { DropdownMenu } from './DropdownMenu';
+import {Button} from "../Button";
 
 const meta = {
   title: 'Interaction/DropdownMenu',
   component: DropdownMenu,
-  tags: ['autodocs'],
   decorators: [
     Story => (
       <div style={{ display: 'flex', alignItems: 'flex-start', justifyContent: 'center', padding: '2rem' }}>
@@ -26,14 +26,14 @@ export const Default: Story = {
     ],
   },
   render: args => (
-    <DropdownMenu {...args} trigger={<button type="button">Actions ▾</button>} />
+    <DropdownMenu {...args} trigger={<Button variant="secondary">Actions ▾</Button>} />
   ),
 };
 
 export const WithDisabledItem: Story = {
   render: () => (
     <DropdownMenu
-      trigger={<button type="button">Options ▾</button>}
+      trigger={<Button variant="secondary">Options ▾</Button>}
       items={[
         { id: 'view', label: 'View' },
         { id: 'edit', label: 'Edit' },
@@ -46,7 +46,7 @@ export const WithDisabledItem: Story = {
 export const WithSeparator: Story = {
   render: () => (
     <DropdownMenu
-      trigger={<button type="button">File ▾</button>}
+      trigger={<Button variant="secondary">File ▾</Button>}
       items={[
         { id: 'new', label: 'New' },
         { id: 'open', label: 'Open' },
@@ -60,7 +60,7 @@ export const WithSeparator: Story = {
 export const AlignedEnd: Story = {
   render: () => (
     <DropdownMenu
-      trigger={<button type="button">⋮</button>}
+      trigger={<Button variant="secondary">⋮</Button>}
       items={[{ id: 'copy', label: 'Copy link' }, { id: 'report', label: 'Report' }]}
       placement="bottom-end"
     />

package/src/components/interaction/Popover/Popover.mdx

@@ -0,0 +1,34 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Popover.stories';
+
+<Meta of={Stories} />
+
+# Popover
+
+Floating panel anchored to a trigger element. Unlike `Tooltip`, popovers can contain interactive content (forms, links, buttons).
+
+## When to use
+- Filter panels, date pickers, or mini-forms attached to a trigger
+- Rich contextual details that require user interaction
+
+## When not to use
+- Non-interactive supplementary text — use `Tooltip` instead
+- Full-screen overlays — use `Dialog`
+
+## Examples
+
+### Default
+<Canvas of={Stories.Default} />
+
+### With form
+<Canvas of={Stories.WithForm} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Trigger element gets `aria-haspopup="true"` and `aria-expanded` toggled on open/close
+- Popover panel is linked via `aria-controls`
+- Focus moves into the panel on open; `Escape` closes and returns focus to trigger

package/src/components/interaction/Popover/Popover.stories.tsx

@@ -1,10 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { Popover } from './Popover';
+import { Button } from '../Button/Button';
 
 const meta = {
   title: 'Interaction/Popover',
   component: Popover,
-  tags: ['autodocs'],
   argTypes: {
     placement: { control: 'radio', options: ['top', 'bottom', 'left', 'right'] },
   },
@@ -24,7 +24,7 @@ export const Default: Story = {
   args: { placement: 'bottom', content: <p style={{ margin: 0 }}>This is a popover with rich content.</p> },
   render: args => (
     <Popover {...args}>
-      <button type="button">Open popover</button>
+      <Button>Open popover</Button>
     </Popover>
   ),
 };
@@ -41,7 +41,7 @@ export const WithForm: Story = {
         </div>
       }
     >
-      <button type="button">Filters</button>
+      <Button variant="secondary">Filters</Button>
     </Popover>
   ),
 };

package/src/components/interaction/Rating/Rating.mdx

@@ -0,0 +1,38 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './Rating.stories';
+
+<Meta of={Stories} />
+
+# Rating
+
+Read-only star rating display. Use to show an existing score; for user input, combine with a form input or interactive stars.
+
+## When to use
+- Displaying product or review scores
+- Showing ratings in cards or lists
+
+## Examples
+
+### Three stars (default)
+<Canvas of={Stories.ThreeStars} />
+
+### Full stars
+<Canvas of={Stories.FullStars} />
+
+### Empty
+<Canvas of={Stories.Empty} />
+
+### Custom max (out of 10)
+<Canvas of={Stories.CustomMax} />
+
+### All ratings
+<Canvas of={Stories.AllRatings} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Accessibility
+
+- Renders as a `<span>` with `role="img"` and `aria-label="X out of Y stars"`
+- Stars are `aria-hidden` — the label carries the full meaning

package/src/components/interaction/Rating/Rating.stories.tsx

@@ -4,7 +4,6 @@ import { Rating } from './Rating';
 const meta = {
   title: 'Interaction/Rating',
   component: Rating,
-  tags: ['autodocs'],
   argTypes: {
     value: { control: { type: 'range', min: 0, max: 5, step: 1 } },
     max: { control: { type: 'number' } },