@boostdev/design-system-components 0.1.1

package/AGENTS.md

@@ -0,0 +1,72 @@
+# @boostdev/components - Agent Guide
+
+## What this package provides
+
+A framework-agnostic React component library built on top of `@boostdev/design-system-foundation`.
+All components use CSS Modules and consume design tokens from `@boostdev/design-system-foundation`.
+Zero extra runtime — bring your own CSS reset and token layer.
+
+## Prerequisites
+
+Consumers must load the design system CSS before using these components:
+```css
+@import '@boostdev/design-system-foundation/css';
+```
+Or individual token layers. All component styles live inside `@layer component`.
+
+## Component categories
+
+- **ui/**: Pure display — Badge, Typography, Loading, Skeleton
+- **interaction/**: Interactive — Button, Dialog, Toast (with Provider + hook), Rating
+- **interaction/form/**: Form fields — FormInput, Checkbox, Radio (+ atom primitives Label, Message, InputContainer)
+- **layout/**: Layout helpers — ButtonGroup, Card, SectionHeader, IconWrapper
+
+## Styling conventions
+
+- CSS Modules (`.module.css`) for all components — styles are scoped, no global leakage
+- All rules placed inside `@layer component` to sit above token layers in the cascade
+- Variant classes follow the pattern `--{variant}` or `--{group}_{variant}` matching the source
+- Component-level CSS custom properties (e.g. `--button_bg`) can be overridden from a parent
+- Never hardcode colours, spacing, or typography values — always use design tokens
+
+## Token usage rules (from @boostdev/design-system-foundation)
+
+- Colour surfaces always pair with their `on-` content token
+- Space: use named scale tokens (`--space_xs`, `--space_m`, etc.), never raw px/rem
+- Shadow: use elevation scale (`--shadow_s` … `--shadow_2xl`)
+- Z-index: use named role tokens, never raw integers
+
+## Import paths
+
+```ts
+// Named exports from the main barrel
+import { Button, Badge, Typography } from '@boostdev/components';
+
+// CSS (import once, at the app root)
+import '@boostdev/components/css';
+```
+
+## Accessibility requirements (WCAG 2.1 AA)
+
+Every component must meet WCAG 2.1 Level AA:
+
+- **Semantic HTML** — use the correct element (`<button>`, `<a>`, `<nav>`, `<dialog>`, etc.)
+- **Keyboard navigable** — all interactive elements reachable and operable via keyboard
+- **Focus visible** — visible focus indicator on every interactive element (WCAG 2.4.7)
+- **ARIA** — add `aria-label` / `aria-labelledby` / `role` where native semantics are insufficient; no redundant ARIA
+- **Colour contrast** — minimum 4.5:1 for text, 3:1 for large text and UI components (WCAG 1.4.3 / 1.4.11)
+- **Touch targets** — minimum 44×44px interactive area (WCAG 2.5.5)
+- **State communication** — disabled, loading, error, and expanded states communicated via ARIA attributes
+- **No motion harm** — respect `prefers-reduced-motion` for animations/transitions
+
+References: https://developer.mozilla.org/en-US/docs/Web/Accessibility | https://www.w3.org/WAI/WCAG21/quickref/
+
+## Adding new components
+
+1. Create `src/components/{category}/{ComponentName}/`
+2. Add `ComponentName.tsx`, `ComponentName.module.css`, `index.ts`
+3. Wrap all CSS rules in `@layer component { ... }`
+4. Use only design token custom properties for colours, spacing, typography
+5. Re-export from the category barrel and from `src/index.ts`
+6. Meet all accessibility requirements listed above
+7. After changes: `pnpm build`, `pnpm typecheck`, `pnpm lint`, `pnpm lint:css`

package/README.md

@@ -0,0 +1,396 @@
+# @boostdev/components
+
+Accessible, token-driven React components built on [`@boostdev/design-system-foundation`](https://www.npmjs.com/package/@boostdev/design-system-foundation).
+Zero extra runtime — bring your own CSS reset and token layer, then import the components.
+
+## Installation
+
+```bash
+pnpm add @boostdev/components @boostdev/design-system-foundation
+npm install @boostdev/components @boostdev/design-system-foundation
+yarn add @boostdev/components @boostdev/design-system-foundation
+```
+
+`@boostdev/design-system-foundation` is a required peer dependency. The components rely on its
+CSS custom properties for all colour, spacing, and typography values.
+
+## Setup
+
+Import the design system tokens and the component styles once at your app root:
+
+```css
+/* app.css */
+@import "@boostdev/design-system-foundation/css";
+@import "@boostdev/components/css";
+```
+
+Or with a JS bundler (Vite, Next.js, etc.):
+
+```ts
+// main.ts / layout.tsx
+import '@boostdev/design-system-foundation/css';
+import '@boostdev/components/css';
+```
+
+All component styles live inside `@layer component`, which sits above the token layers in the
+cascade. You can override any component from outside without specificity fights.
+
+---
+
+## Usage
+
+### UI components
+
+#### Badge
+
+```tsx
+import { Badge } from '@boostdev/components';
+
+<Badge>New</Badge>
+<Badge variant="success">Active</Badge>
+<Badge variant="error">Failed</Badge>
+<Badge variant="warning">Pending</Badge>
+<Badge variant="secondary">Draft</Badge>
+```
+
+Variants: `primary` (default) · `secondary` · `success` · `error` · `warning`
+
+---
+
+#### Typography
+
+```tsx
+import { Typography } from '@boostdev/components';
+
+<Typography variant="h1">Page title</Typography>
+<Typography variant="h2">Section title</Typography>
+<Typography variant="body">Paragraph text</Typography>
+<Typography variant="body_s">Small print</Typography>
+```
+
+Pass `component` to override the rendered element without changing the visual style:
+
+```tsx
+<Typography variant="h2" component="h3">Visually h2, semantically h3</Typography>
+```
+
+Variants: `h1` · `h2` · `h3` · `body` (default) · `body_s`
+
+---
+
+#### Loading
+
+```tsx
+import { Loading } from '@boostdev/components';
+
+<Loading />
+<Loading size="small" />
+<Loading size="large" />
+```
+
+Sizes: `small` · `medium` (default) · `large`
+
+---
+
+#### Skeleton
+
+```tsx
+import { Skeleton } from '@boostdev/components';
+
+<Skeleton className="w-48 h-4" />
+```
+
+Renders an `aria-hidden` shimmer block. Size it with a `className` or inline style.
+
+---
+
+### Interaction components
+
+#### Button
+
+```tsx
+import { Button } from '@boostdev/components';
+
+<Button>Click me</Button>
+<Button variant="secondary">Cancel</Button>
+<Button size="small">Small</Button>
+<Button href="/dashboard">Link button</Button>
+<Button iconStart={<Icon />} aria-label="Delete" />
+<Button hasPulse>Call to action</Button>
+```
+
+| Prop | Type | Default |
+|---|---|---|
+| `variant` | `'primary' \| 'secondary'` | `'primary'` |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` |
+| `href` | `string` | — renders an `<a>` |
+| `iconStart` | `ReactNode` | — |
+| `iconEnd` | `ReactNode` | — |
+| `hasPulse` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+
+---
+
+#### Dialog
+
+```tsx
+import { Dialog } from '@boostdev/components';
+
+<Dialog isVisible={open} handleClose={() => setOpen(false)}>
+  <h2>Confirm</h2>
+  <p>Are you sure?</p>
+</Dialog>
+```
+
+Renders a native `<dialog>` element. `isVisible` controls open/close; `handleClose` is called
+when the close button is pressed.
+
+---
+
+#### Rating
+
+```tsx
+import { Rating } from '@boostdev/components';
+
+<Rating value={3} />
+<Rating value={4} max={10} />
+```
+
+`max` defaults to `5`. Stars are rendered as SVG icons; unfilled stars use the current
+background colour.
+
+---
+
+#### Toast
+
+```tsx
+import { ToastProvider, useToast } from '@boostdev/components';
+
+// Wrap your app (or layout) once:
+<ToastProvider>
+  <App />
+</ToastProvider>
+
+// Inside any component:
+function SaveButton() {
+  const { showToast } = useToast();
+  return (
+    <button onClick={() => showToast('Saved!', 'success')}>
+      Save
+    </button>
+  );
+}
+```
+
+`showToast(message, variant)` — variant: `'success'` · `'error'` · `'info'`
+
+Toasts auto-dismiss after 5 seconds.
+
+---
+
+### Form components
+
+All form components accept standard HTML input attributes via spread in addition to their own props.
+
+#### FormInput
+
+```tsx
+import { FormInput } from '@boostdev/components';
+
+<FormInput
+  label="Email"
+  name="email"
+  type="email"
+  hint="We'll never share your email"
+  error={errors.email}
+/>
+```
+
+#### Checkbox
+
+```tsx
+import { Checkbox } from '@boostdev/components';
+
+<Checkbox
+  label="I agree to the terms"
+  name="agree"
+  error={errors.agree}
+/>
+```
+
+#### Radio
+
+```tsx
+import { Radio } from '@boostdev/components';
+
+<Radio label="Option A" name="choice" value="a" />
+<Radio label="Option B" name="choice" value="b" />
+```
+
+---
+
+### Layout components
+
+#### ButtonGroup
+
+```tsx
+import { ButtonGroup, Button } from '@boostdev/components';
+
+<ButtonGroup variant="flow">
+  <Button>Back</Button>
+  <Button>Next</Button>
+</ButtonGroup>
+```
+
+Variants: `flow` · `card` · `modal` · `content`
+
+---
+
+#### Card
+
+```tsx
+import { Card } from '@boostdev/components';
+
+<Card>Basic card</Card>
+<Card variant="elevated" padding="large">Elevated</Card>
+<Card variant="outlined" textAlign="center">Outlined</Card>
+<Card onClick={() => navigate('/detail')}>Clickable card</Card>
+```
+
+| Prop | Type | Default |
+|---|---|---|
+| `variant` | `'default' \| 'elevated' \| 'outlined'` | `'default'` |
+| `padding` | `'none' \| 'small' \| 'medium' \| 'large'` | `'medium'` |
+| `textAlign` | `'start' \| 'center' \| 'end'` | `'start'` |
+| `onClick` | `() => void` | — renders a `<button>` |
+
+---
+
+#### SectionHeader
+
+```tsx
+import { SectionHeader } from '@boostdev/components';
+
+<SectionHeader title="Our services" />
+<SectionHeader
+  title="Welcome"
+  subtitle="Everything you need in one place"
+  size="large"
+  alignment="center"
+/>
+```
+
+| Prop | Type | Default |
+|---|---|---|
+| `title` | `string` | required |
+| `subtitle` | `string` | — |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` |
+| `alignment` | `'start' \| 'center' \| 'end'` | `'start'` |
+
+---
+
+#### IconWrapper
+
+```tsx
+import { IconWrapper } from '@boostdev/components';
+
+<IconWrapper>
+  <svg>...</svg>
+</IconWrapper>
+```
+
+Renders a circular container sized to its own `font-size`. Override the background colour via the
+`--icon-wrapper-color` CSS custom property.
+
+---
+
+### Utilities
+
+#### cn
+
+Composes class name strings, filtering out falsy values:
+
+```ts
+import { cn } from '@boostdev/components';
+
+cn('card', isActive && 'card--active', [extraClass])
+// → "card card--active extraClass"
+```
+
+---
+
+## Overriding component styles
+
+Every component exposes CSS custom properties as a styling API. Set them on a parent or via
+`style` to adjust the component without writing extra CSS:
+
+```css
+/* Override the button background for a specific context */
+.hero .button {
+  --button_bg: var(--color_brand);
+  --button_text: var(--color_on-brand);
+}
+```
+
+All component styles sit in `@layer component`. You can also write rules in a higher layer:
+
+```css
+@layer my-overrides {
+  .my-button {
+    border-radius: 0;
+  }
+}
+```
+
+---
+
+## Theming
+
+Components inherit from `@boostdev/design-system-foundation` tokens. Override semantic tokens to
+retheme all components at once:
+
+```css
+/* tokens.config.css — import after the design system CSS */
+@layer tokens.override {
+  :root {
+    --color_cta:        var(--BASE__color--orange);
+    --color_on-cta:     var(--BASE__color--white);
+    --color_interactive: var(--BASE__color--orange);
+  }
+}
+```
+
+Dark mode is handled automatically via `[data-theme="dark"]` or `prefers-color-scheme`.
+
+---
+
+## Development
+
+```bash
+pnpm build        # compile to dist/
+pnpm typecheck    # TypeScript check (library code only)
+pnpm lint         # ESLint
+pnpm lint:css     # Stylelint
+pnpm test         # Vitest — 71 tests
+pnpm storybook    # Storybook dev server on port 6006
+```
+
+### Adding a new component
+
+1. Create `src/components/{category}/{Name}/`
+2. Add `Name.tsx`, `Name.module.css`, `index.ts`
+3. Wrap all CSS in `@layer component { ... }`
+4. Use only design token custom properties — no hard-coded colours, spacing, or font sizes
+5. Re-export from `src/index.ts`
+6. Run `pnpm build && pnpm typecheck && pnpm lint && pnpm lint:css && pnpm test`
+
+---
+
+## Publishing a new version
+
+```bash
+npm version patch   # or minor / major
+git push --follow-tags
+```
+
+GitLab CI will build and publish to npm automatically on version tags.