@boostdev/design-system-components 1.1.2 → 1.2.0

package/src/web-components/ui/BdsSeparator.mdx

@@ -0,0 +1,63 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsSeparator.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-separator&gt;
+
+Framework-agnostic Separator custom element. Renders a horizontal or vertical visual divider.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Horizontal
+<Canvas of={Stories.Horizontal} />
+
+### Vertical
+<Canvas of={Stories.Vertical} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Direction of the separator line |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--separator_color` | Line colour (defaults to `--bds-color_on-bg`) |
+| `--separator_thickness` | Line thickness (default: `1px`) |
+
+## Usage in plain HTML
+
+```html
+<!-- Horizontal (default) -->
+<bds-separator></bds-separator>
+
+<!-- Vertical — needs a height context -->
+<div style="display: flex; align-items: center; height: 40px; gap: 16px;">
+  <span>Left</span>
+  <bds-separator orientation="vertical"></bds-separator>
+  <span>Right</span>
+</div>
+```
+
+## Accessibility
+
+- Renders as `role="separator"` with `aria-orientation` set automatically
+- Purely decorative — screen readers announce it as a separator landmark

package/src/web-components/ui/BdsSeparator.stories.tsx

@@ -0,0 +1,47 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index';
+
+function BdsSeparator({ orientation }: { orientation?: 'horizontal' | 'vertical' }) {
+  return React.createElement('bds-separator', { orientation });
+}
+
+const meta = {
+  title: 'Web Components/UI/Separator',
+  component: BdsSeparator,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+  argTypes: {
+    orientation: { control: 'select', options: ['horizontal', 'vertical'] },
+  },
+} satisfies Meta<typeof BdsSeparator>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Horizontal: Story = { args: { orientation: 'horizontal' } };
+
+export const Vertical: Story = {
+  render: () => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '16px', height: '40px' }}>
+      <span>Left</span>
+      <BdsSeparator orientation="vertical" />
+      <span>Right</span>
+    </div>
+  ),
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>
+      <p style={{ margin: 0 }}>Content above horizontal separator</p>
+      <BdsSeparator orientation="horizontal" />
+      <p style={{ margin: 0 }}>Content below</p>
+      <div style={{ display: 'flex', alignItems: 'center', gap: '16px', height: '40px' }}>
+        <span>Left</span>
+        <BdsSeparator orientation="vertical" />
+        <span>Right</span>
+      </div>
+    </div>
+  ),
+};

package/src/web-components/ui/BdsSkeleton.mdx

@@ -0,0 +1,67 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsSkeleton.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-skeleton&gt;
+
+Framework-agnostic Skeleton loading placeholder. Shows a shimmer animation while content is loading. Size is set via inline `style` or container CSS — the element inherits its dimensions from the surrounding layout.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### Card layout skeleton
+<Canvas of={Stories.AllVariants} />
+
+### Text line
+<Canvas of={Stories.TextLine} />
+
+### Avatar placeholder
+<Canvas of={Stories.Avatar} />
+
+### Card placeholder
+<Canvas of={Stories.Card} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+This element has no attributes. Control dimensions via `style` or a CSS class on the host.
+
+## CSS Custom Properties
+
+The shimmer animation uses design tokens directly:
+
+| Token | Description |
+|-------|-------------|
+| `--bds-color_grey--subtle` | Shimmer base colour |
+| `--bds-color_bg` | Shimmer highlight colour |
+| `--bds-border_radius--xs` | Default corner radius |
+
+## Usage in plain HTML
+
+```html
+<!-- Text line -->
+<bds-skeleton style="width: 200px; height: 1rem;"></bds-skeleton>
+
+<!-- Avatar -->
+<bds-skeleton style="width: 3rem; height: 3rem; border-radius: 50%;"></bds-skeleton>
+
+<!-- Card block -->
+<bds-skeleton style="width: 280px; height: 160px;"></bds-skeleton>
+```
+
+## Accessibility
+
+- Hidden from assistive technology via `aria-hidden="true"` — it is a purely visual placeholder
+- Pair with a live region or announce loading state through other means if necessary
+- Respects `prefers-reduced-motion`: shimmer animation is disabled for users who prefer reduced motion

package/src/web-components/ui/BdsSkeleton.stories.tsx

@@ -0,0 +1,50 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '../index';
+
+function BdsSkeleton({ style }: { style?: React.CSSProperties }) {
+  return React.createElement('bds-skeleton', { style });
+}
+
+const meta = {
+  title: 'Web Components/UI/Skeleton',
+  component: BdsSkeleton,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'centered' },
+} satisfies Meta<typeof BdsSkeleton>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const TextLine: Story = {
+  render: () => <BdsSkeleton style={{ width: '200px', height: '1rem' }} />,
+};
+
+export const Heading: Story = {
+  render: () => <BdsSkeleton style={{ width: '300px', height: '1.75rem' }} />,
+};
+
+export const Avatar: Story = {
+  render: () => <BdsSkeleton style={{ width: '3rem', height: '3rem', borderRadius: '50%' }} />,
+};
+
+export const Card: Story = {
+  render: () => <BdsSkeleton style={{ width: '280px', height: '160px' }} />,
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', width: '280px' }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
+        <BdsSkeleton style={{ width: '3rem', height: '3rem', borderRadius: '50%', flexShrink: 0 }} />
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px', flex: 1 }}>
+          <BdsSkeleton style={{ width: '100%', height: '1rem' }} />
+          <BdsSkeleton style={{ width: '60%', height: '0.75rem' }} />
+        </div>
+      </div>
+      <BdsSkeleton style={{ width: '100%', height: '120px' }} />
+      <BdsSkeleton style={{ width: '80%', height: '0.875rem' }} />
+      <BdsSkeleton style={{ width: '60%', height: '0.875rem' }} />
+    </div>
+  ),
+};

package/src/web-components/ui/BdsTypography.mdx

@@ -0,0 +1,83 @@
+import { Meta, Canvas, ArgTypes } from '@storybook/blocks';
+import * as Stories from './BdsTypography.stories';
+
+<Meta of={Stories} />
+
+# &lt;bds-typography&gt;
+
+Framework-agnostic Typography custom element. Renders slotted content inside the appropriate semantic HTML element with the correct typographic styles.
+
+> **Status: experimental** — API may change before stable release.
+
+## Installation
+
+```js
+import '@boostdev/components/web-components';
+```
+
+## Examples
+
+### All variants
+<Canvas of={Stories.AllVariants} />
+
+### Heading 1
+<Canvas of={Stories.H1} />
+
+### Body
+<Canvas of={Stories.Body} />
+
+### Body small
+<Canvas of={Stories.BodySmall} />
+
+## Props
+
+<ArgTypes of={Stories} />
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `variant` | `"h1" \| "h2" \| "h3" \| "body" \| "body_s"` | `"body"` | Typographic style and semantic element |
+| `component` | string | — | Override the rendered HTML tag (e.g. `"span"`, `"label"`) |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `(default)` | Text content |
+
+## Default tag mapping
+
+| Variant | Rendered tag |
+|---------|-------------|
+| `h1` | `<h1>` |
+| `h2` | `<h2>` |
+| `h3` | `<h3>` |
+| `body` | `<p>` |
+| `body_s` | `<p>` |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--typography_color` | Text colour (defaults to `--bds-color_on-bg`) |
+
+## Usage in plain HTML
+
+```html
+<bds-typography variant="h1">Page title</bds-typography>
+
+<bds-typography variant="body">
+  A paragraph of body text.
+</bds-typography>
+
+<!-- Override tag while keeping style -->
+<bds-typography variant="body_s" component="span">
+  Inline small text
+</bds-typography>
+```
+
+## Accessibility
+
+- Uses the correct semantic HTML element by default — always prefer semantic variants over overriding `component`
+- Use `component` only when the semantic element must differ from the visual style (e.g. a `<span>` styled as `body_s` inside a heading)

package/src/web-components/ui/BdsTypography.stories.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { TypographyVariant } from './bds-typography';
+import '../index';
+
+function BdsTypography({
+  variant,
+  component,
+  children,
+}: {
+  variant?: TypographyVariant;
+  component?: string;
+  children?: React.ReactNode;
+}) {
+  return React.createElement('bds-typography', { variant, component }, children);
+}
+
+const meta = {
+  title: 'Web Components/UI/Typography',
+  component: BdsTypography,
+  tags: ['!stable', 'experimental'],
+  parameters: { layout: 'padded' },
+  argTypes: {
+    variant: { control: 'select', options: ['h1', 'h2', 'h3', 'body', 'body_s'] },
+  },
+} satisfies Meta<typeof BdsTypography>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const H1: Story = { args: { variant: 'h1', children: 'Heading level 1' } };
+export const H2: Story = { args: { variant: 'h2', children: 'Heading level 2' } };
+export const H3: Story = { args: { variant: 'h3', children: 'Heading level 3' } };
+export const Body: Story = { args: { variant: 'body', children: 'Body text — the default paragraph style for reading comfort.' } };
+export const BodySmall: Story = { args: { variant: 'body_s', children: 'Small body text — useful for captions and helper text.' } };
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      {(['h1', 'h2', 'h3', 'body', 'body_s'] as const).map(v => (
+        <BdsTypography key={v} variant={v}>
+          {v === 'h1' && 'Heading level 1'}
+          {v === 'h2' && 'Heading level 2'}
+          {v === 'h3' && 'Heading level 3'}
+          {v === 'body' && 'Body text — comfortable reading size for paragraphs.'}
+          {v === 'body_s' && 'Small body — captions, labels, and secondary text.'}
+        </BdsTypography>
+      ))}
+    </div>
+  ),
+};

package/src/web-components/ui/bds-alert.ts

@@ -110,8 +110,7 @@ export class BdsAlert extends LitElement {
       transition: var(--bds-animation_transition);
       border-radius: 50%;
       --bdc_color: currentcolor;
-      outline: var(--bdc-outline_width) solid var(--bdc_color);
-      outline-offset: var(--bdc-outline_offset);
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
     }
 
     .dismiss svg {

package/src/web-components/ui/bds-card.ts

@@ -53,9 +53,7 @@ export class BdsCard extends LitElement {
 
     .card.--outlined {
       --bdc_color: currentcolor;
-      outline: var(--bdc-outline_width) solid var(--bdc_color);
-      outline-offset: var(--bdc-outline_offset);
-      box-shadow: var(--bds-shadow_s);
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color), var(--bds-shadow_s);
     }
 
     .card.--padding-none   { padding: 0; }

package/src/web-components/ui/bds-notification-banner.ts

@@ -91,8 +91,7 @@ export class BdsNotificationBanner extends LitElement {
       border-radius: 50%;
       transition: var(--bds-animation_transition);
       --bdc_color: currentcolor;
-      outline: var(--bdc-outline_width) solid var(--bdc_color);
-      outline-offset: var(--bdc-outline_offset);
+      box-shadow: inset 0 0 0 var(--bdc-outline_width) var(--bdc_color);
     }
 
     .dismiss svg {