@boostdev/design-system-components 1.2.7 → 2.0.0

package/AGENTS.md

@@ -13,7 +13,7 @@ A component library with three targets:
 ```css
 @import '@boostdev/design-system-foundation/css';
 ```
-All component styles live inside `@layer component`.
+All component styles live inside `@layer boostdev.component`.
 
 **Web Components:** import the bundle to register all custom elements:
 ```js
@@ -28,7 +28,7 @@ import '@boostdev/design-system-components/web-components';
 - **ui/**: Accordion, Alert, Avatar, Badge, Breadcrumb, Calendar, Carousel, Collapsible, DescriptionList, Link, Loading, NotificationBanner, Pagination, Progress, ProgressCircle, Separator, Skeleton, SkipLink, Table, Tabs, Tooltip, Typography
 - **interaction/**: Button, Command, Dialog, Drawer, DropdownMenu, Popover, Rating, Toast (ToastProvider + useToast hook)
 - **interaction/form/**: Checkbox, CheckboxGroup, Combobox, FileInput, FormInput, NumberInput, Radio, RadioGroup, SegmentedControl, Select, Slider, Switch, Textarea (+ atom primitives: Label, Message, InputContainer)
-- **layout/**: ButtonGroup, Card, IconWrapper, SectionHeader
+- **layout/**: ButtonContainer (formerly ButtonGroup — deprecated alias still available), Card, IconWrapper, SectionHeader
 
 ### Web Components (experimental) — `src/web-components/`
 Custom elements built with Lit. Entry: `src/web-components/index.ts`. Bundled with Lit (no peer dep required).
@@ -77,7 +77,7 @@ React Native overview: `src/stories/ReactNative.mdx`.
 ## 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
+- All rules placed inside `@layer boostdev.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
@@ -212,6 +212,8 @@ import '@boostdev/design-system-components/css';
 
 > **`cn()` in Server Components**: For `cn` only, prefer `@boostdev/design-system-components/utils` — the root entry includes a CSS side-effect import.
 
+> **Next.js styles not applying?** Import the pre-built CSS once at the root: `import '@boostdev/design-system-components/css'` (exposed via the `./css` subpath in the package's `exports` map). `transpilePackages` is **not** required — class names are renamed to `bds{version}{Component}-*` at build time by `scripts/patch-css-modules.mjs`, and the JS bundle contains no runtime CSS Module imports. Forgetting the CSS import is the most common cause of unstyled components.
+
 ## Accessibility requirements (WCAG 2.1 AA)
 
 Every component must meet WCAG 2.1 Level AA:
@@ -233,7 +235,7 @@ References: https://developer.mozilla.org/en-US/docs/Web/Accessibility | https:/
 
 ## Usage guidelines
 
-- **Form buttons must be wrapped in `ButtonGroup`**: Whenever buttons are used inside a form (submit, reset, cancel, navigation), wrap them in a `ButtonGroup` component. Use `variant="flow"` for multi-step form navigation (Back / Next) and `variant="card"` for single-form submissions. This ensures consistent spacing, alignment, and responsive behaviour.
+- **Form buttons must be wrapped in `ButtonContainer`**: Whenever buttons are used inside a form (submit, reset, cancel, navigation), wrap them in a `ButtonContainer` component. Use `variant="flow"` for multi-step form navigation (Back / Next) and `variant="card"` for single-form submissions. This ensures consistent spacing, alignment, and responsive behaviour. (`ButtonGroup` is a deprecated alias — use `ButtonContainer` for new code.)
 
 ## Key decisions
 
@@ -271,7 +273,7 @@ Key patterns:
 
 1. Create `src/components/{category}/{ComponentName}/`
 2. Add `ComponentName.tsx`, `ComponentName.module.css`, `index.ts`
-3. Wrap all CSS rules in `@layer component { ... }`
+3. Wrap all CSS rules in `@layer boostdev.component { ... }`
 4. Use only design token custom properties for colours, spacing, typography
 5. Export the props interface (`export interface ComponentNameProps`) from the component file
 6. Re-export component and props type from the local `index.ts` and from `src/index.ts`

package/README.md

@@ -1,4 +1,4 @@
-# @boostdev/components
+# @boostdev/design-system-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.
@@ -6,9 +6,9 @@ Zero extra runtime — bring your own CSS reset and token layer, then import the
 ## 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
+pnpm add @boostdev/design-system-components @boostdev/design-system-foundation
+npm install @boostdev/design-system-components @boostdev/design-system-foundation
+yarn add @boostdev/design-system-components @boostdev/design-system-foundation
 ```
 
 `@boostdev/design-system-foundation` is a required peer dependency. The components rely on its
@@ -21,7 +21,7 @@ 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";
+@import "@boostdev/design-system-components/css";
 ```
 
 Or with a JS bundler (Vite, Next.js, etc.):
@@ -29,17 +29,17 @@ Or with a JS bundler (Vite, Next.js, etc.):
 ```ts
 // main.ts / layout.tsx
 import '@boostdev/design-system-foundation/css';
-import '@boostdev/components/css';
+import '@boostdev/design-system-components/css';
 ```
 
-All component styles live inside `@layer component`, which sits above the token layers in the
+All component styles live inside `@layer boostdev.component`, which sits above the token layers in the
 cascade. You can override any component from outside without specificity fights.
 
 ---
 
 ## Next.js / React Server Components
 
-The main `@boostdev/components` entry has no `'use client'` directive. When Next.js evaluates the
+The main `@boostdev/design-system-components` entry has no `'use client'` directive. When Next.js evaluates the
 bundle in a React Server Component context, components that call `createContext` (e.g. `Toast`) will
 crash at module evaluation time.
 
@@ -48,15 +48,33 @@ bundle, which tells Next.js to treat it as client-only code:
 
 ```ts
 // Plain React / Vite — unchanged
-import { Button, Card } from '@boostdev/components';
+import { Button, Card } from '@boostdev/design-system-components';
 
 // Next.js / RSC — use the /client subpath
-import { Button, Card } from '@boostdev/components/client';
+import { Button, Card } from '@boostdev/design-system-components/client';
 
 // Server-safe utilities (cn, WithClassName) — works in Server Components, layouts, middleware
-import { cn } from '@boostdev/components/utils';
+import { cn } from '@boostdev/design-system-components/utils';
 ```
 
+### Styles won't apply? Import the CSS file
+
+The most common cause of unstyled components in a Next.js app is forgetting to import the CSS
+bundle. This package ships pre-built, already-scoped CSS (class names are renamed at build time
+to `bds{version}{Component}-*`), so Next.js does **not** need to process it — you just need to
+load it once at the root:
+
+```ts
+// app/layout.tsx (App Router)  or  pages/_app.tsx (Pages Router)
+import '@boostdev/design-system-foundation/css';
+import '@boostdev/design-system-components/css';
+```
+
+The `./css` subpath is exposed in the package's `exports` map and points at the pre-built
+`dist/index.css`. You do **not** need `transpilePackages` for this library — classes are already
+scoped at publish time and the JS bundle contains no runtime CSS Module imports. Add
+`transpilePackages` only if another dependency in your tree genuinely requires it.
+
 ---
 
 ## Usage
@@ -66,7 +84,7 @@ import { cn } from '@boostdev/components/utils';
 #### Badge
 
 ```tsx
-import { Badge } from '@boostdev/components';
+import { Badge } from '@boostdev/design-system-components';
 
 <Badge>New</Badge>
 <Badge variant="success">Active</Badge>
@@ -82,7 +100,7 @@ Variants: `primary` (default) · `secondary` · `success` · `error` · `warning
 #### Collapsible
 
 ```tsx
-import { Collapsible } from '@boostdev/components';
+import { Collapsible } from '@boostdev/design-system-components';
 
 <Collapsible summary="What is the return policy?" defaultOpen>
   You can return any item within 30 days of purchase.
@@ -100,7 +118,7 @@ Built on native `<details>`/`<summary>`. Use `name` to group multiple Collapsibl
 #### Typography
 
 ```tsx
-import { Typography } from '@boostdev/components';
+import { Typography } from '@boostdev/design-system-components';
 
 <Typography variant="h1">Page title</Typography>
 <Typography variant="h2">Section title</Typography>
@@ -121,7 +139,7 @@ Variants: `h1` · `h2` · `h3` · `body` (default) · `body_s`
 #### Loading
 
 ```tsx
-import { Loading } from '@boostdev/components';
+import { Loading } from '@boostdev/design-system-components';
 
 <Loading />
 <Loading size="small" />
@@ -135,7 +153,7 @@ Sizes: `small` · `medium` (default) · `large`
 #### Skeleton
 
 ```tsx
-import { Skeleton } from '@boostdev/components';
+import { Skeleton } from '@boostdev/design-system-components';
 
 <Skeleton className="w-48 h-4" />
 ```
@@ -149,7 +167,7 @@ Renders an `aria-hidden` shimmer block. Size it with a `className` or inline sty
 #### Button
 
 ```tsx
-import { Button } from '@boostdev/components';
+import { Button } from '@boostdev/design-system-components';
 
 <Button>Click me</Button>
 <Button variant="outline">Cancel</Button>
@@ -187,7 +205,7 @@ import { Button } from '@boostdev/components';
 #### Dialog
 
 ```tsx
-import { Dialog } from '@boostdev/components';
+import { Dialog } from '@boostdev/design-system-components';
 
 <Dialog isOpen={open} onClose={() => setOpen(false)}>
   <h2>Confirm</h2>
@@ -206,7 +224,7 @@ Override the backdrop colour via `--color_backdrop` (default: `rgb(0 0 0 / 50%)`
 #### Rating
 
 ```tsx
-import { Rating } from '@boostdev/components';
+import { Rating } from '@boostdev/design-system-components';
 
 <Rating value={3} />
 <Rating value={4} max={10} />
@@ -220,7 +238,7 @@ background colour.
 #### Toast
 
 ```tsx
-import { ToastProvider, useToast } from '@boostdev/components';
+import { ToastProvider, useToast } from '@boostdev/design-system-components';
 
 // Wrap your app (or layout) once:
 <ToastProvider>
@@ -251,7 +269,7 @@ All components accept native HTML attributes for their root element via `...rest
 #### FormInput
 
 ```tsx
-import { FormInput } from '@boostdev/components';
+import { FormInput } from '@boostdev/design-system-components';
 
 <FormInput
   label="Email"
@@ -265,7 +283,7 @@ import { FormInput } from '@boostdev/components';
 #### Checkbox
 
 ```tsx
-import { Checkbox, CheckboxGroup } from '@boostdev/components';
+import { Checkbox, CheckboxGroup } from '@boostdev/design-system-components';
 
 <Checkbox
   label="I agree to the terms"
@@ -287,7 +305,7 @@ Group multiple checkboxes with a shared label using `CheckboxGroup`:
 #### Radio
 
 ```tsx
-import { Radio, RadioGroup } from '@boostdev/components';
+import { Radio, RadioGroup } from '@boostdev/design-system-components';
 
 <RadioGroup legend="Preferred contact" required>
   <Radio label="Option A" name="choice" value="a" description="Optional supporting text." />
@@ -298,7 +316,7 @@ import { Radio, RadioGroup } from '@boostdev/components';
 #### Switch
 
 ```tsx
-import { Switch } from '@boostdev/components';
+import { Switch } from '@boostdev/design-system-components';
 
 <Switch label="Enable notifications" name="notifications" />
 <Switch label="Dark mode" name="dark-mode" defaultChecked />
@@ -310,7 +328,7 @@ Sizes: `small` · `medium` (default) · `large`
 #### SegmentedControl
 
 ```tsx
-import { SegmentedControl } from '@boostdev/components';
+import { SegmentedControl } from '@boostdev/design-system-components';
 
 <SegmentedControl aria-label="Calendar view" selectedIndex={1}>
   <button>Day</button>
@@ -334,7 +352,7 @@ Children-based API — pass `<button>`, `<a>`, or router `<Link>` elements direc
 #### ButtonGroup
 
 ```tsx
-import { ButtonGroup, Button } from '@boostdev/components';
+import { ButtonGroup, Button } from '@boostdev/design-system-components';
 
 <ButtonGroup variant="flow" aria-label="Page navigation">
   <Button>Back</Button>
@@ -352,7 +370,7 @@ import { ButtonGroup, Button } from '@boostdev/components';
 #### Card
 
 ```tsx
-import { Card } from '@boostdev/components';
+import { Card } from '@boostdev/design-system-components';
 
 <Card>Basic card</Card>
 <Card variant="elevated" padding="large">Elevated</Card>
@@ -372,7 +390,7 @@ import { Card } from '@boostdev/components';
 #### SectionHeader
 
 ```tsx
-import { SectionHeader } from '@boostdev/components';
+import { SectionHeader } from '@boostdev/design-system-components';
 
 <SectionHeader title="Our services" />
 <SectionHeader
@@ -395,7 +413,7 @@ import { SectionHeader } from '@boostdev/components';
 #### IconWrapper
 
 ```tsx
-import { IconWrapper } from '@boostdev/components';
+import { IconWrapper } from '@boostdev/design-system-components';
 
 <IconWrapper>
   <svg>...</svg>
@@ -420,10 +438,10 @@ Composes class name strings, filtering out falsy values:
 
 ```ts
 // Server-safe — works in Server Components, layouts, middleware
-import { cn } from '@boostdev/components/utils';
+import { cn } from '@boostdev/design-system-components/utils';
 
 // Also available from root or /client (but these are client-only in Next.js)
-import { cn } from '@boostdev/components';
+import { cn } from '@boostdev/design-system-components';
 
 cn('card', isActive && 'card--active', [extraClass])
 // → "card card--active extraClass"
@@ -444,7 +462,7 @@ Every component exposes CSS custom properties as a styling API. Set them on a pa
 }
 ```
 
-All component styles sit in `@layer component`. You can also write rules in a higher layer:
+All component styles sit in `@layer boostdev.component`. You can also write rules in a higher layer:
 
 ```css
 @layer my-overrides {
@@ -500,7 +518,7 @@ retheme all components at once:
 
 ```css
 /* tokens.config.css — import after the design system CSS */
-@layer tokens.override {
+@layer boostdev.tokens.override {
   :root {
     --bds-cta:        var(--bds-BASE__color--orange);
     --bds-on-cta:     var(--bds-BASE__color--white);
@@ -516,7 +534,7 @@ and progress indicators. Override it once to retheme checkboxes, radio buttons,
 bars, and the switch thumb simultaneously:
 
 ```css
-@layer tokens.override {
+@layer boostdev.tokens.override {
   :root {
     --bds-active:            var(--bds-BASE__color--blue);
     --bds-on-active:         var(--bds-BASE__color--white);
@@ -548,7 +566,7 @@ pnpm storybook    # Storybook dev server on port 6006
 
 1. Create `src/components/{category}/{Name}/`
 2. Add `Name.tsx`, `Name.module.css`, `index.ts`
-3. Wrap all CSS in `@layer component { ... }`
+3. Wrap all CSS in `@layer boostdev.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`
@@ -587,13 +605,13 @@ pnpm mcp:start   # listens on http://localhost:3001/api/mcp
 47 components are available for React Native — near-complete parity with the web library. Metro auto-resolves the native entry via the `"react-native"` export condition.
 
 ```tsx
-import { Button, FormInput, Dialog, Tabs } from '@boostdev/components';
+import { Button, FormInput, Dialog, Tabs } from '@boostdev/design-system-components';
 ```
 
 Wrap your app in `ThemeProvider`:
 
 ```tsx
-import { ThemeProvider } from '@boostdev/components/native/ThemeContext';
+import { ThemeProvider } from '@boostdev/design-system-components/native/ThemeContext';
 
 export default function App() {
   return (