@boostdev/design-system-components 1.2.8 → 2.1.0

package/src/stories/DesignSystem/Borders.mdx

@@ -127,7 +127,7 @@ Override a component's border colour for a specific context by reassigning `--bd
 }
 
 /* Override globally via the token layer */
-@layer tokens.override {
+@layer boostdev.tokens.override {
   :root {
     --bdc_color: var(--bds-color_green);
   }
@@ -151,8 +151,8 @@ The `bdc` tokens are included automatically when you import the component styles
 
 ```css
 /* Included automatically with the full component CSS */
-@import '@boostdev/components/css';
+@import '@boostdev/design-system-components/css';
 
 /* Or load the token layer standalone */
-@import '@boostdev/components/css/bdc';
+@import '@boostdev/design-system-components/css/bdc';
 ```

package/src/stories/DesignSystem/Colors.mdx

@@ -184,7 +184,7 @@ These `--bds-BASE__color--*` tokens are the primitive values. **Do not use them
 Override `--bds-color_green` and `--bds-color_interactive` to change the primary action colour globally:
 
 ```css
-@layer tokens.override {
+@layer boostdev.tokens.override {
   :root {
     --bds-color_green:           var(--bds-BASE__color--blue);
     --bds-color_on-green:         var(--bds-BASE__color--white);

package/src/stories/DesignSystem/DarkMode.mdx

@@ -85,20 +85,20 @@ function ThemeToggle() {
 
 ## Customising tokens in dark mode
 
-Override any token in `@layer tokens.override` — the rule applies regardless of the active theme unless you scope it:
+Override any token in `@layer boostdev.tokens.override` — the rule applies regardless of the active theme unless you scope it:
 
 ```css
 @import "@boostdev/design-system-foundation/css";
 
 /* override for all themes */
-@layer tokens.override {
+@layer boostdev.tokens.override {
   :root {
     --bds-color_green: oklch(60% 0.15 145);
   }
 }
 
 /* override for dark mode only */
-@layer tokens.override {
+@layer boostdev.tokens.override {
   [data-theme="dark"],
   @media (prefers-color-scheme: dark) {
     :root:not([data-theme="light"]) {

package/src/stories/DesignSystem/Overview.mdx

@@ -49,14 +49,25 @@ import '@boostdev/design-system-foundation/css';
 
 ## Layer architecture
 
-All tokens live inside `@layer` declarations. The cascade order, from lowest to highest, is:
+All tokens live inside `@layer` declarations, all prefixed with `boostdev.` to prevent collisions
+with consumer layers of the same name. The cascade order, from lowest to highest, is:
 
 ```
-tokens.base → tokens.semantic → tokens.override → reset → base → utilities → component
+boostdev.tokens.base →
+boostdev.tokens.semantic →
+boostdev.tokens.deprecated →
+boostdev.tokens.override →
+boostdev.reset →
+boostdev.base →
+boostdev.utilities →
+boostdev.components →
+boostdev.component
 ```
 
-`@layer component` — used by every component in this library — sits above the token layers,
-so you can override any component from `@layer my-overrides` without specificity fights.
+`@layer boostdev.component` — used by every component in this library — sits above the token layers,
+so you can override any component from your own layer (e.g. `@layer my-overrides`) without
+specificity fights. Anything written outside of any `@layer` is treated as an unlayered declaration,
+which is the highest-priority in the cascade.
 
 ## Theming
 
@@ -78,7 +89,7 @@ Override any token in your own layer to retheme:
 ```css
 @import "@boostdev/design-system-foundation/css";
 
-@layer tokens.override {
+@layer boostdev.tokens.override {
   :root {
     --bds-cta:    var(--bds-BASE__color--blue);
     --bds-color_on-green: var(--bds-BASE__color--white);

package/src/stories/DesignSystem/Typography.mdx

@@ -49,7 +49,7 @@ export const TrackingSample = ({ token, label, value }) => (
 Override both tokens to apply a custom typeface globally:
 
 ```css
-@layer tokens.override {
+@layer boostdev.tokens.override {
   :root {
     --bds-font_family--heading: 'Inter', sans-serif;
     --bds-font_family--body:    'Inter', sans-serif;

package/src/stories/Introduction.mdx

@@ -30,20 +30,20 @@ import logo from '../static/logo.svg';
     ## Installation
 
     ```bash
-    pnpm add @boostdev/components @boostdev/design-system-foundation
+    pnpm add @boostdev/design-system-components @boostdev/design-system-foundation
     ```
 
     Import the CSS once at your app root:
 
     ```ts
     import '@boostdev/design-system-foundation/css';
-    import '@boostdev/components/css';
+    import '@boostdev/design-system-components/css';
     ```
 
     For **Next.js / RSC**, use the `/client` subpath:
 
     ```ts
-    import {Button, Card} from '@boostdev/components/client';
+    import {Button, Card} from '@boostdev/design-system-components/client';
     ```
 
     ---
@@ -92,7 +92,7 @@ import logo from '../static/logo.svg';
     everything at once:
 
     ```css
-    @layer tokens.override {
+    @layer boostdev.tokens.override {
         :root {
             --bds-cta:         var(--bds-BASE__color--orange);
             --bds-on-cta:      var(--bds-BASE__color--white);

package/src/stories/ReactNative.mdx

@@ -6,21 +6,21 @@ import { Meta } from '@storybook/blocks';
 
 > **Status: alpha** — components and APIs may change before stable release.
 
-`@boostdev/components` ships native implementations for 47 components — near-complete parity with the React web library. These use React Native primitives (`View`, `Text`, `Pressable`, `StyleSheet`, `Modal`, `Animated`) rather than HTML elements, and consume a dedicated token layer instead of CSS custom properties.
+`@boostdev/design-system-components` ships native implementations for 47 components — near-complete parity with the React web library. These use React Native primitives (`View`, `Text`, `Pressable`, `StyleSheet`, `Modal`, `Animated`) rather than HTML elements, and consume a dedicated token layer instead of CSS custom properties.
 
 ## Installation
 
 ```bash
-npm install @boostdev/components
+npm install @boostdev/design-system-components
 # or
-pnpm add @boostdev/components
+pnpm add @boostdev/design-system-components
 ```
 
 Metro automatically resolves the native entry point via the `"react-native"` export condition in `package.json` — no extra configuration needed.
 
 ```ts
 // Import is identical to the web version:
-import { Button, Alert, Badge, Avatar, Typography } from '@boostdev/components';
+import { Button, Alert, Badge, Avatar, Typography } from '@boostdev/design-system-components';
 ```
 
 ## Setup — ThemeProvider
@@ -28,7 +28,7 @@ import { Button, Alert, Badge, Avatar, Typography } from '@boostdev/components';
 Wrap your app (or the relevant subtree) in `ThemeProvider` to give native components access to the design token context:
 
 ```tsx
-import { ThemeProvider } from '@boostdev/components/native/ThemeContext';
+import { ThemeProvider } from '@boostdev/design-system-components/native/ThemeContext';
 
 export default function App() {
   return (
@@ -57,7 +57,7 @@ Native components consume tokens from `src/native/tokens.ts` — a JS object mir
 Tokens are accessed inside components via `useTheme()`:
 
 ```tsx
-import { useTheme } from '@boostdev/components/native/ThemeContext';
+import { useTheme } from '@boostdev/design-system-components/native/ThemeContext';
 
 function MyComponent() {
   const { tokens } = useTheme();

package/src/web-components/globals.ts

@@ -36,7 +36,7 @@ const bdcCss = `
     initial-value: 0 0 0 0 transparent;
   }
 
-  @layer component {
+  @layer boostdev.component {
     :root {
       --bdc-outline_border: none;
 

package/src/web-components/interaction/BdsAccordion.mdx

@@ -12,14 +12,14 @@ Framework-agnostic Accordion custom element. Coordinates open/closed state acros
 ## Installation
 
 ```js
-import '@boostdev/components/web-components';
+import '@boostdev/design-system-components/web-components';
 ```
 
 Or in HTML without a bundler:
 
 ```html
 <script type="module">
-  import '@boostdev/components/web-components';
+  import '@boostdev/design-system-components/web-components';
 </script>
 ```
 
@@ -85,7 +85,7 @@ Or in HTML without a bundler:
   </bds-accordion-item>
   <bds-accordion-item>
     <span slot="header">How do I install it?</span>
-    <p>Run npm install @boostdev/components.</p>
+    <p>Run npm install @boostdev/design-system-components.</p>
   </bds-accordion-item>
 </bds-accordion>
 

package/src/web-components/interaction/BdsAccordion.stories.tsx

@@ -49,7 +49,7 @@ function BdsAccordionStory({
         {React.createElement('p', { style: { margin: 0 } }, 'A framework-agnostic component library built on web standards.')}
       </BdsAccordionItem>
       <BdsAccordionItem header="How do I install it?">
-        {React.createElement('p', { style: { margin: 0 } }, 'Run npm install @boostdev/components and import the web components entry point.')}
+        {React.createElement('p', { style: { margin: 0 } }, 'Run npm install @boostdev/design-system-components and import the web components entry point.')}
       </BdsAccordionItem>
       <BdsAccordionItem header="Does it support dark mode?">
         {React.createElement('p', { style: { margin: 0 } }, 'Yes — all design tokens respond to [data-theme="dark"] and prefers-color-scheme: dark.')}

package/src/web-components/interaction/BdsButton.mdx

@@ -1,4 +1,4 @@
-import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import { Meta, Canvas, ArgTypes, Controls } from '@storybook/blocks';
 import * as Stories from './BdsButton.stories';
 
 <Meta of={Stories} />
@@ -13,37 +13,65 @@ Framework-agnostic button custom element. Renders as `<button>` or `<a>` dependi
 
 ```js
 // Register all web components at once
-import '@boostdev/components/web-components';
+import '@boostdev/design-system-components/web-components';
 ```
 
 Or in HTML without a bundler:
 
 ```html
 <script type="module">
-  import '@boostdev/components/web-components';
+  import '@boostdev/design-system-components/web-components';
 </script>
 ```
 
-## Examples
+## Playground
 
-### All variants & sizes
-<Canvas of={Stories.AllVariants} />
+<Canvas of={Stories.Playground} />
+<Controls of={Stories.Playground} />
+
+## Variants
 
-### Default
 <Canvas of={Stories.Default} />
+<Canvas of={Stories.Outline} />
 
-### Ghost
-<Canvas of={Stories.Ghost} />
+## Sizes
 
-### Sizes
 <Canvas of={Stories.Small} />
 <Canvas of={Stories.Medium} />
 <Canvas of={Stories.Large} />
 
-### Pulse (CTA emphasis)
+## Icons
+
+Slot an SVG (or any element) into `icon-start` or `icon-end`:
+
+```html
+<bds-button>
+  <svg slot="icon-start">…</svg>
+  Save
+</bds-button>
+```
+
+<Canvas of={Stories.WithIconStart} />
+<Canvas of={Stories.WithIconEnd} />
+
+### Icon-only (1:1 aspect ratio)
+
+Set the `is-icon-only` attribute to render a square button with equal `var(--bds-space_xs)` padding on both axes. Composable with any `variant`. Always pair with `aria-label` — there's no visible label text for assistive tech to read.
+
+<Canvas of={Stories.IconOnly} />
+<Canvas of={Stories.IconOnlyOutline} />
+<Canvas of={Stories.AllIconOnly} />
+
+## All variants & sizes
+
+<Canvas of={Stories.AllVariants} />
+
+## Pulse (CTA emphasis)
+
 <Canvas of={Stories.WithPulse} />
 
-### Disabled
+## Disabled
+
 <Canvas of={Stories.Disabled} />
 
 ## Props
@@ -54,14 +82,15 @@ Or in HTML without a bundler:
 
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `variant` | `"default" \| "ghost"` | `"default"` | Visual style — filled or transparent outlined |
-| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Height and padding scale |
+| `variant` | `"default" \| "outline"` | `"default"` | Visual style — filled or transparent outlined (`"ghost"` is a deprecated alias for `"outline"`) |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Height and horizontal padding |
 | `disabled` | boolean | `false` | Prevents interaction, sets `aria-disabled` |
 | `href` | string | — | Renders as `<a>` when set |
 | `target` | string | — | Forwarded to `<a>` when `href` is set |
 | `rel` | string | — | Forwarded to `<a>` when `href` is set |
 | `type` | `"button" \| "submit" \| "reset"` | `"button"` | Native button type |
 | `has-pulse` | boolean | `false` | Adds animated ring for CTA emphasis |
+| `is-icon-only` | boolean | `false` | 1:1 aspect ratio with equal `xs` padding on both axes. Requires `aria-label`. |
 | `aria-label` | string | — | Accessible label (required for icon-only buttons) |
 
 ## Slots
@@ -76,7 +105,7 @@ Or in HTML without a bundler:
 
 | Property | Description |
 |----------|-------------|
-| `--button_color` | Identity colour — fills the default variant, outlines the ghost variant |
+| `--button_color` | Identity colour — fills the default variant, outlines the outline variant |
 | `--button_on-color` | Text/icon colour on the button surface. Pair with `--button_color` |
 
 ## Invoker Commands API
@@ -94,8 +123,11 @@ Or in HTML without a bundler:
 
 ```html
 <bds-button variant="default" size="medium">Save</bds-button>
-<bds-button variant="ghost">Cancel</bds-button>
+<bds-button variant="outline">Cancel</bds-button>
 <bds-button href="/dashboard">Go to dashboard</bds-button>
+<bds-button is-icon-only aria-label="Confirm">
+  <svg viewBox="0 0 24 24">…</svg>
+</bds-button>
 ```
 
 ## Accessibility

package/src/web-components/interaction/BdsButton.stories.tsx

@@ -1,56 +1,188 @@
-import React from 'react';
+import React, { type ReactNode } from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import type { ButtonVariant, ButtonSize } from './bds-button';
 import '../index'; // auto-registers all custom elements
 
-// Thin React wrapper so Storybook controls work with the custom element's props
+const CheckIcon = (
+  <svg
+    slot="icon-start"
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 24 24"
+    width="1em"
+    height="1em"
+    aria-hidden
+    fill="currentColor"
+  >
+    <path d="M12 0a12 12 0 1 0 12 12A12 12 0 0 0 12 0Zm6.93 8.2-6.85 9.29a1 1 0 0 1-1.43.19l-4.89-3.91a1 1 0 0 1-.15-1.41A1 1 0 0 1 7 12.21l4.08 3.26L17.32 7a1 1 0 0 1 1.39-.21 1 1 0 0 1 .22 1.41Z" />
+  </svg>
+);
+
+const ArrowRightStart = <span slot="icon-start" aria-hidden>→</span>;
+const ArrowRightEnd = <span slot="icon-end" aria-hidden>→</span>;
+const ArrowLeftStart = <span slot="icon-start" aria-hidden>←</span>;
+
+// Icon for icon-only buttons — goes into the default slot (no slot attribute)
+const CheckIconDefault = (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 24 24"
+    width="1em"
+    height="1em"
+    aria-hidden
+    fill="currentColor"
+  >
+    <path d="M12 0a12 12 0 1 0 12 12A12 12 0 0 0 12 0Zm6.93 8.2-6.85 9.29a1 1 0 0 1-1.43.19l-4.89-3.91a1 1 0 0 1-.15-1.41A1 1 0 0 1 7 12.21l4.08 3.26L17.32 7a1 1 0 0 1 1.39-.21 1 1 0 0 1 .22 1.41Z" />
+  </svg>
+);
+
+const iconStartMap = {
+  none: undefined,
+  check: CheckIcon,
+  arrowRight: ArrowRightStart,
+  arrowLeft: ArrowLeftStart,
+};
+
+const iconEndMap = {
+  none: undefined,
+  arrowRight: ArrowRightEnd,
+};
+
+type IconStartKey = keyof typeof iconStartMap;
+type IconEndKey = keyof typeof iconEndMap;
+
+// React wrapper translating typed props into the custom element's attributes/slots
+interface BdsButtonProps {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  disabled?: boolean;
+  href?: string;
+  hasPulse?: boolean;
+  isIconOnly?: boolean;
+  'aria-label'?: string;
+  iconStart?: ReactNode;
+  iconEnd?: ReactNode;
+  children?: ReactNode;
+}
+
 function BdsButton({
   variant = 'default',
   size = 'medium',
   disabled,
   href,
   hasPulse,
+  isIconOnly,
+  'aria-label': ariaLabel,
+  iconStart,
+  iconEnd,
   children,
-}: {
-  variant?: ButtonVariant;
-  size?: ButtonSize;
-  disabled?: boolean;
-  href?: string;
-  hasPulse?: boolean;
-  children?: React.ReactNode;
-}) {
+}: BdsButtonProps) {
   return React.createElement(
     'bds-button',
-    { variant, size, disabled: disabled || undefined, href, 'has-pulse': hasPulse || undefined },
+    {
+      variant,
+      size,
+      disabled: disabled || undefined,
+      href,
+      'has-pulse': hasPulse || undefined,
+      'is-icon-only': isIconOnly || undefined,
+      'aria-label': ariaLabel,
+    },
+    iconStart,
     children,
+    iconEnd,
   );
 }
 
-const meta = {
+type BdsButtonStoryArgs = Omit<BdsButtonProps, 'iconStart' | 'iconEnd'> & {
+  iconStart?: IconStartKey;
+  iconEnd?: IconEndKey;
+};
+
+const meta: Meta<BdsButtonStoryArgs> = {
   title: 'Web Components/Interaction/Button',
   component: BdsButton,
   tags: ['!stable', 'experimental'],
   parameters: { layout: 'centered' },
   argTypes: {
-    variant: { control: 'select', options: ['default', 'ghost'] },
-    size: { control: 'select', options: ['small', 'medium', 'large'] },
+    variant: {
+      control: 'select',
+      options: ['default', 'outline'],
+      description: '`default` is filled; `outline` is transparent with a border.',
+      table: { defaultValue: { summary: 'default' } },
+    },
+    size: {
+      control: 'select',
+      options: ['small', 'medium', 'large'],
+      description: 'Height + horizontal padding.',
+      table: { defaultValue: { summary: 'medium' } },
+    },
+    iconStart: {
+      control: 'select',
+      options: Object.keys(iconStartMap) as IconStartKey[],
+      mapping: iconStartMap,
+      description: 'Icon rendered in the `icon-start` slot.',
+    },
+    iconEnd: {
+      control: 'select',
+      options: Object.keys(iconEndMap) as IconEndKey[],
+      mapping: iconEndMap,
+      description: 'Icon rendered in the `icon-end` slot.',
+    },
+    isIconOnly: {
+      control: 'boolean',
+      description: 'Forces 1:1 aspect ratio with minimal xs padding. Composable with any `variant`. Requires `aria-label`.',
+      table: { defaultValue: { summary: 'false' } },
+    },
+    hasPulse: {
+      control: 'boolean',
+      description: 'Adds a pulsing animation for CTA emphasis.',
+      table: { defaultValue: { summary: 'false' } },
+    },
+    disabled: { control: 'boolean' },
+    href: { control: 'text', description: 'When set, renders as `<a>` with button styling.' },
+    'aria-label': { control: 'text', description: 'Required for icon-only buttons.' },
   },
-} satisfies Meta<typeof BdsButton>;
+  args: { variant: 'default', size: 'medium' },
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<BdsButtonStoryArgs>;
 
-export const Default: Story = { args: { children: 'Default', variant: 'default' } };
-export const Ghost: Story = { args: { children: 'Ghost', variant: 'ghost' } };
+export const Playground: Story = {
+  args: { children: 'Button', iconStart: 'none', iconEnd: 'none' },
+};
+
+export const Default: Story = { args: { children: 'Default' } };
+export const Outline: Story = { args: { children: 'Outline', variant: 'outline' } };
 export const Small: Story = { args: { children: 'Small', size: 'small' } };
 export const Medium: Story = { args: { children: 'Medium', size: 'medium' } };
 export const Large: Story = { args: { children: 'Large', size: 'large' } };
 export const WithPulse: Story = { args: { children: 'Pulsing', hasPulse: true } };
 export const Disabled: Story = { args: { children: 'Disabled', disabled: true } };
+export const WithIconStart: Story = { args: { children: 'Confirm', iconStart: 'check' } };
+export const WithIconEnd: Story = { args: { children: 'Continue', iconEnd: 'arrowRight' } };
+
+export const IconOnly: Story = {
+  args: {
+    isIconOnly: true,
+    'aria-label': 'Confirm',
+    children: CheckIconDefault,
+  },
+};
+
+export const IconOnlyOutline: Story = {
+  args: {
+    variant: 'outline',
+    isIconOnly: true,
+    'aria-label': 'Confirm',
+    children: CheckIconDefault,
+  },
+};
+
 export const AllVariants: Story = {
   render: () => (
     <div style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
-      {(['default', 'ghost'] as const).flatMap(v =>
+      {(['default', 'outline'] as const).flatMap(v =>
         (['small', 'medium', 'large'] as const).map(s => (
           <BdsButton key={`${v}-${s}`} variant={v} size={s}>{v} {s}</BdsButton>
         )),
@@ -58,3 +190,23 @@ export const AllVariants: Story = {
     </div>
   ),
 };
+
+export const AllIconOnly: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '12px', flexWrap: 'wrap', alignItems: 'center' }}>
+      {(['default', 'outline'] as const).flatMap(v =>
+        (['small', 'medium', 'large'] as const).map(s => (
+          <BdsButton
+            key={`${v}-${s}`}
+            variant={v}
+            size={s}
+            isIconOnly
+            aria-label={`${v} ${s}`}
+          >
+            {CheckIconDefault}
+          </BdsButton>
+        )),
+      )}
+    </div>
+  ),
+};

package/src/web-components/interaction/BdsCollapsible.mdx

@@ -12,14 +12,14 @@ Framework-agnostic Collapsible custom element. Wraps a native `<details>`/`<summ
 ## Installation
 
 ```js
-import '@boostdev/components/web-components';
+import '@boostdev/design-system-components/web-components';
 ```
 
 Or in HTML without a bundler:
 
 ```html
 <script type="module">
-  import '@boostdev/components/web-components';
+  import '@boostdev/design-system-components/web-components';
 </script>
 ```
 

package/src/web-components/interaction/BdsDialog.mdx

@@ -12,14 +12,14 @@ Framework-agnostic Dialog custom element. Wraps a native `<dialog>` element with
 ## Installation
 
 ```js
-import '@boostdev/components/web-components';
+import '@boostdev/design-system-components/web-components';
 ```
 
 Or in HTML without a bundler:
 
 ```html
 <script type="module">
-  import '@boostdev/components/web-components';
+  import '@boostdev/design-system-components/web-components';
 </script>
 ```
 

package/src/web-components/interaction/BdsDrawer.mdx

@@ -12,14 +12,14 @@ Framework-agnostic Drawer (slide-in panel) custom element. Same modal infrastruc
 ## Installation
 
 ```js
-import '@boostdev/components/web-components';
+import '@boostdev/design-system-components/web-components';
 ```
 
 Or in HTML without a bundler:
 
 ```html
 <script type="module">
-  import '@boostdev/components/web-components';
+  import '@boostdev/design-system-components/web-components';
 </script>
 ```
 

package/src/web-components/interaction/BdsDropdownMenu.mdx

@@ -12,14 +12,14 @@ Framework-agnostic Dropdown Menu custom element. A trigger-anchored menu panel w
 ## Installation
 
 ```js
-import '@boostdev/components/web-components';
+import '@boostdev/design-system-components/web-components';
 ```
 
 Or in HTML without a bundler:
 
 ```html
 <script type="module">
-  import '@boostdev/components/web-components';
+  import '@boostdev/design-system-components/web-components';
 </script>
 ```
 

package/src/web-components/interaction/BdsPopover.mdx

@@ -12,7 +12,7 @@ Framework-agnostic popover custom element. A non-modal floating panel anchored t
 ## Installation
 
 ```js
-import '@boostdev/components/web-components';
+import '@boostdev/design-system-components/web-components';
 ```
 
 ## Examples