@boostdev/design-system-components 0.1.18 → 1.0.1

package/src/stories/DesignSystem/Motion.mdx

@@ -0,0 +1,96 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Design System/Motion" />
+
+export const AnimDemo = ({ label, token, animationStyle }) => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem', alignItems: 'center' }}>
+    <div style={{
+      width: '3rem',
+      height: '3rem',
+      background: 'var(--bds-interactive)',
+      borderRadius: '0.5rem',
+      animation: animationStyle,
+      opacity: 0.9,
+    }} />
+    <div style={{ textAlign: 'center' }}>
+      <div style={{ fontSize: '0.8rem', fontWeight: 600 }}>{label}</div>
+      {token && <div style={{ fontSize: '0.7rem', fontFamily: 'monospace', opacity: 0.6 }}>{token}</div>}
+    </div>
+  </div>
+);
+
+# Motion
+
+## Timing tokens
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--bds-animation_easing` | `ease-out` | Default easing for transitions |
+| `--bds-animation_duration--fast` | `150ms` | Micro-interactions, hover states |
+| `--bds-animation_duration--normal` | `350ms` | Panel opens, page transitions |
+| `--bds-animation_transition-duration` | `150ms` | Shorthand duration alias |
+| `--bds-animation_transition` | `all 150ms ease-out` | Single-line transition shorthand |
+
+```css
+.button {
+  transition: var(--bds-animation_transition);
+}
+
+.panel {
+  transition: transform var(--bds-animation_duration--normal) var(--bds-animation_easing);
+}
+```
+
+---
+
+## Keyframe animations
+
+The foundation ships six named keyframes.
+
+<div style={{ display: 'flex', gap: '3rem', flexWrap: 'wrap', padding: '2rem', background: 'var(--bds-bg--subtle)', borderRadius: '0.75rem', marginBottom: '2rem' }}>
+  <AnimDemo label="bounce" animationStyle="bounce 1s ease-out infinite" />
+  <AnimDemo label="rotate" animationStyle="rotate 2s linear infinite" />
+  <AnimDemo label="fade-zoom" animationStyle="fade-zoom 2s ease-in-out infinite" />
+  <AnimDemo label="slide-to-start" animationStyle="slide-to-start 1.5s ease-in-out infinite alternate" />
+  <AnimDemo label="slide-to-end" animationStyle="slide-to-end 1.5s ease-in-out infinite alternate" />
+</div>
+
+| Keyframe | Description |
+|----------|-------------|
+| `bounce` | Scale 1 → 0.75 → 1 — attention pulse |
+| `rotate` | 0 → 360deg — continuous spin |
+| `fade-zoom` | Opacity + scale pulse (1,1) → (0.4,1.25) → (1,1) |
+| `slide-to-start` | translateX 0 → -20% |
+| `slide-to-end` | translateX 0 → 20% |
+
+---
+
+## Reduced motion
+
+All animations in the library respect `prefers-reduced-motion`. When building custom animations, always add this override:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .my-animated-element {
+    animation: none;
+    transition: none;
+  }
+}
+```
+
+---
+
+## Chevron rotation
+
+`--bds-animation_chevron-rotate--end: x 180deg`
+
+Convenience token for animating a chevron/caret icon into its open/closed state:
+
+```css
+.chevron {
+  transition: rotate var(--bds-animation_transition);
+}
+.chevron[data-open="true"] {
+  rotate: var(--bds-animation_chevron-rotate--end);
+}
+```

package/src/stories/DesignSystem/Overview.mdx

@@ -0,0 +1,99 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Design System/Overview" />
+
+# Design System Foundation
+
+`@boostdev/design-system-foundation` is the token layer that every component in this library is built on.
+It provides a complete set of CSS custom properties for colour, spacing, typography, grid, elevation, and motion —
+all responsive and theme-aware out of the box.
+
+## Installation
+
+```bash
+pnpm add @boostdev/design-system-foundation
+```
+
+## Setup
+
+Import the CSS once at your app root. Components rely on these custom properties being present in the document.
+
+```css
+/* app.css */
+@import "@boostdev/design-system-foundation/css";
+```
+
+Or via a JS bundler (Vite, Next.js, etc.):
+
+```ts
+// main.ts / layout.tsx
+import '@boostdev/design-system-foundation/css';
+```
+
+## What's included
+
+| Import | Contents |
+|--------|----------|
+| `/css` | Everything below, bundled |
+| `/css/tokens/color` | Colour palette + semantic colour tokens |
+| `/css/tokens/space` | Spacing scale + container tokens |
+| `/css/tokens/font` | Typography — family, size, weight, line-height, tracking |
+| `/css/tokens/grid` | Responsive grid columns + span helpers |
+| `/css/tokens/border` | Border radius + outline tokens |
+| `/css/tokens/shadow` | Elevation scale (s → 2xl) |
+| `/css/tokens/animations` | Easing, duration, transition shorthand, keyframes |
+| `/css/tokens/z-index` | Z-index scale + named role aliases |
+| `/css/reset` | Minimal CSS reset |
+| `/css/base` | Base element styles (headings, links, body) |
+| `/css/utilities` | Utility classes (grid layout, visually-hidden, etc.) |
+
+## Layer architecture
+
+All tokens live inside `@layer` declarations. The cascade order, from lowest to highest, is:
+
+```
+tokens.base → tokens.semantic → tokens.override → reset → base → utilities → 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.
+
+## Theming
+
+Tokens adapt automatically to light and dark mode via `data-theme` attribute or `prefers-color-scheme`:
+
+```html
+<!-- explicit themes -->
+<html data-theme="light">
+<html data-theme="dark">
+```
+
+```css
+/* or CSS-only, no attribute needed */
+@media (prefers-color-scheme: dark) { … }
+```
+
+Override any token in your own layer to retheme:
+
+```css
+@import "@boostdev/design-system-foundation/css";
+
+@layer tokens.override {
+  :root {
+    --bds-cta:    var(--bds-BASE__color--blue);
+    --bds-on-cta: var(--bds-BASE__color--white);
+  }
+}
+```
+
+## Naming convention
+
+```
+--bds-{group}_{name}--{variant}
+```
+
+- `bds-` prefix = all foundation tokens
+- `_` separates group from name
+- `--` separates name from scale variant
+- `BASE__` prefix = primitive palette (never use directly in component CSS)
+- All semantic tokens are prefixed with `bds-` (e.g. `--bds-bg`, `--bds-interactive`)

package/src/stories/DesignSystem/Spacing.mdx

@@ -0,0 +1,74 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Design System/Spacing" />
+
+export const SpaceStep = ({ token, mobile, tablet, desktop }) => (
+  <div style={{ display: 'grid', gridTemplateColumns: '10rem auto 1fr', gap: '0 1.5rem', alignItems: 'center', padding: '0.625rem 0', borderBottom: '1px solid var(--bds-grey--subtle)' }}>
+    <code style={{ fontSize: '0.75rem' }}>{token}</code>
+    <div style={{ width: `var(${token})`, height: '1.25rem', background: 'var(--bds-interactive)', borderRadius: '0.125rem', minWidth: '2px' }} />
+    <div style={{ fontSize: '0.75rem', color: 'var(--bds-grey)', fontFamily: 'monospace' }}>
+      {mobile}{tablet !== mobile ? ` → ${tablet}` : ''}{desktop !== tablet ? ` → ${desktop}` : ''}
+    </div>
+  </div>
+);
+
+# Spacing
+
+All spacing values use a named scale — `xxxs` through `xxxxl`. Larger values are responsive and grow at `40rem`, `48rem`, and `64rem` breakpoints. Use these tokens for margins, paddings, and gaps everywhere.
+
+**Never use raw `px` or `rem` values in component CSS.** Use the scale tokens.
+
+## Scale
+
+<SpaceStep token="--bds-space_xxxs" mobile="2px" tablet="2px" desktop="2px" />
+<SpaceStep token="--bds-space_xxs"  mobile="4px" tablet="4px" desktop="4px" />
+<SpaceStep token="--bds-space_xs"   mobile="8px" tablet="8px" desktop="8px" />
+<SpaceStep token="--bds-space_s"    mobile="12px" tablet="12px" desktop="12px" />
+<SpaceStep token="--bds-space_m"    mobile="16px" tablet="16px" desktop="16px" />
+<SpaceStep token="--bds-space_l"    mobile="16px" tablet="24px" desktop="24px" />
+<SpaceStep token="--bds-space_xl"   mobile="16px" tablet="24px" desktop="32px" />
+<SpaceStep token="--bds-space_xxl"  mobile="24px" tablet="32px" desktop="48px" />
+<SpaceStep token="--bds-space_xxxl" mobile="32px" tablet="40px" desktop="64px" />
+<SpaceStep token="--bds-space_xxxxl" mobile="40px" tablet="48px" desktop="96px" />
+
+## Responsive values
+
+| Token | Mobile | 40rem+ | 48rem+ |
+|-------|--------|--------|--------|
+| `--bds-space_xxxs` | 0.125rem | 0.125rem | 0.125rem |
+| `--bds-space_xxs` | 0.25rem | 0.25rem | 0.25rem |
+| `--bds-space_xs` | 0.5rem | 0.5rem | 0.5rem |
+| `--bds-space_s` | 0.75rem | 0.75rem | 0.75rem |
+| `--bds-space_m` | 1rem | 1rem | 1rem |
+| `--bds-space_l` | 1rem | 1.5rem | 1.5rem |
+| `--bds-space_xl` | 1rem | 1.5rem | 2rem |
+| `--bds-space_xxl` | 1.5rem | 2rem | 3rem |
+| `--bds-space_xxxl` | 2rem | 2.5rem | 4rem |
+| `--bds-space_xxxxl` | 2.5rem | 3rem | 6rem |
+
+---
+
+## Container tokens
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--bds-container_max-width` | Responsive | Page-level container width |
+| `--bds-container_max-width--narrow` | 48rem (fixed) | Narrow content like forms, articles |
+| `--bds-container_min-width` | min-content | Prevents overflow |
+| `--bds-container_spacing` | Responsive | Outer page margin |
+| `--bds-container_spacing-inline` | Responsive | Horizontal gutter padding |
+
+---
+
+## Usage
+
+```css
+.card {
+  padding: var(--bds-space_m);
+  gap: var(--bds-space_s);
+}
+
+.section {
+  padding-block: var(--bds-space_xxxl);
+}
+```

package/src/stories/DesignSystem/Typography.mdx

@@ -0,0 +1,110 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Design System/Typography" />
+
+export const TypeScale = ({ token, label, style = {} }) => (
+  <div style={{ display: 'grid', gridTemplateColumns: '10rem 1fr', gap: '0.5rem 1.5rem', alignItems: 'baseline', padding: '0.75rem 0', borderBottom: '1px solid var(--bds-grey--subtle)' }}>
+    <div style={{ fontSize: '0.75rem', fontFamily: 'monospace', color: 'var(--bds-on-bg--muted, var(--bds-grey))', lineHeight: 1.4 }}>
+      {token}
+    </div>
+    <div style={{ fontFamily: 'var(--bds-font_family--body)', fontSize: `var(${token})`, ...style }}>
+      {label}
+    </div>
+  </div>
+);
+
+export const WeightSample = ({ weight, token, label }) => (
+  <div style={{ display: 'grid', gridTemplateColumns: '12rem 1fr', gap: '0.5rem 1.5rem', alignItems: 'baseline', padding: '0.75rem 0', borderBottom: '1px solid var(--bds-grey--subtle)' }}>
+    <div style={{ fontSize: '0.75rem', fontFamily: 'monospace', color: 'var(--bds-grey)' }}>
+      <div>{token}</div>
+      <div style={{ opacity: 0.7 }}>{weight}</div>
+    </div>
+    <div style={{ fontFamily: 'var(--bds-font_family--body)', fontWeight: `var(${token})`, fontSize: '1.25rem' }}>
+      {label} — The quick brown fox
+    </div>
+  </div>
+);
+
+export const TrackingSample = ({ token, label, value }) => (
+  <div style={{ display: 'grid', gridTemplateColumns: '12rem 1fr', gap: '0.5rem 1.5rem', alignItems: 'baseline', padding: '0.75rem 0', borderBottom: '1px solid var(--bds-grey--subtle)' }}>
+    <div style={{ fontSize: '0.75rem', fontFamily: 'monospace', color: 'var(--bds-grey)' }}>
+      <div>{token}</div>
+      <div style={{ opacity: 0.7 }}>{value}</div>
+    </div>
+    <div style={{ fontFamily: 'var(--bds-font_family--body)', letterSpacing: `var(${token})`, fontSize: '1rem' }}>
+      {label}
+    </div>
+  </div>
+);
+
+# Typography
+
+## Font families
+
+| Token | Value |
+|-------|-------|
+| `--bds-font_family--heading` | Arial, Helvetica, sans-serif |
+| `--bds-font_family--body` | Arial, Helvetica, sans-serif |
+
+Override both tokens to apply a custom typeface globally:
+
+```css
+@layer tokens.override {
+  :root {
+    --bds-font_family--heading: 'Inter', sans-serif;
+    --bds-font_family--body:    'Inter', sans-serif;
+  }
+}
+```
+
+---
+
+## Font size scale
+
+Font sizes are responsive — they grow at `48rem` and `64rem` breakpoints.
+The values shown reflect the **desktop** (64rem+) scale.
+
+<TypeScale token="--bds-font_size--display" label="Display — Hero headlines" style={{ fontWeight: 700, lineHeight: 1.05 }} />
+<TypeScale token="--bds-font_size--heading-1" label="Heading 1 — Page titles" style={{ fontWeight: 700, lineHeight: 1.2 }} />
+<TypeScale token="--bds-font_size--heading-2" label="Heading 2 — Section titles" style={{ fontWeight: 700, lineHeight: 1.2 }} />
+<TypeScale token="--bds-font_size--heading-3" label="Heading 3 — Sub-sections" style={{ fontWeight: 600, lineHeight: 1.2 }} />
+<TypeScale token="--bds-font_size--body" label="Body — Default paragraph text" />
+<TypeScale token="--bds-font_size--body--s" label="Body small — Captions, hints, meta" />
+
+### Responsive values
+
+| Token | Mobile | Tablet (48rem) | Desktop (64rem) |
+|-------|--------|----------------|-----------------|
+| `--bds-font_size--display` | 3.5rem | 4.5rem | 6rem |
+| `--bds-font_size--heading-1` | 2rem | 2.5rem | 3rem |
+| `--bds-font_size--heading-2` | 1.5rem | 1.75rem | 2rem |
+| `--bds-font_size--heading-3` | 1.25rem | 1.375rem | 1.5rem |
+| `--bds-font_size--body` | 1em | 1em | 1em |
+| `--bds-font_size--body--s` | 0.875em | 0.875em | 0.875em |
+
+---
+
+## Font weight
+
+<WeightSample token="--bds-font_weight--light" weight="300" label="Light" />
+<WeightSample token="--bds-font_weight--medium" weight="400" label="Medium / Body" />
+<WeightSample token="--bds-font_weight--semibold" weight="600" label="Semibold / Subheading" />
+<WeightSample token="--bds-font_weight--bold" weight="700" label="Bold / Heading" />
+
+---
+
+## Line height
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--bds-font_line-height--display` | 1.05 | Display headings — very tight |
+| `--bds-font_line-height--heading` | 1.2 | Section headings |
+| `--bds-font_line-height--body` | 1.6 | Body text — comfortable reading |
+
+---
+
+## Letter spacing (tracking)
+
+<TrackingSample token="--bds-font_tracking--tight" label="Display headlines use tight tracking" value="-0.02em" />
+<TrackingSample token="--bds-font_tracking--normal" label="Body text uses normal tracking" value="0" />
+<TrackingSample token="--bds-font_tracking--wide" label="SMALL CAPS, BADGES USE WIDE TRACKING" value="0.06em" />

package/src/stories/Introduction.css

@@ -9,9 +9,9 @@
 }
 
 .card {
-    grid-column: var(--grid_span-25)
+    grid-column: var(--bds-grid_span-25)
 }
 
 .cardContent {
-    font-size: var(--font_size--body--s);
+    font-size: var(--bds-font_size--body--s);
 }

package/src/stories/Introduction.mdx

@@ -20,8 +20,8 @@ import {Card} from "../components/layout/Card/index.ts";
             Accessible, token-driven React components. Zero extra runtime.
         </p>
         <ButtonGroup variant="content">
-            <Button variant="secondary" href="https://www.npmjs.com/package/@boostdev/design-system-foundation">DS Foundation</Button>
-            <Button variant="secondary" href="https://www.npmjs.com/package/@boostdev/design-system-components">DS Components</Button>
+            <Button variant="ghost" href="https://www.npmjs.com/package/@boostdev/design-system-foundation">DS Foundation</Button>
+            <Button variant="ghost" href="https://www.npmjs.com/package/@boostdev/design-system-components">DS Components</Button>
         </ButtonGroup>
     </div>
     ---
@@ -93,11 +93,11 @@ import {Card} from "../components/layout/Card/index.ts";
     ```css
     @layer tokens.override {
         :root {
-            --color_cta:         var(--BASE__color--orange);
-            --color_on-cta:      var(--BASE__color--white);
-            --color_interactive: var(--BASE__color--orange);
-            --color_active:      var(--BASE__color--orange);
-            --color_on-active:   var(--BASE__color--white);
+            --bds-cta:         var(--bds-BASE__color--orange);
+            --bds-on-cta:      var(--bds-BASE__color--white);
+            --bds-interactive: var(--bds-BASE__color--orange);
+            --bds-active:      var(--bds-BASE__color--orange);
+            --bds-on-active:   var(--bds-BASE__color--white);
         }
     }
     ```