DS style barrel, Storybook style entry, and consumption docs

.storybook/preview.js

@@ -1,8 +1,7 @@
 import React from 'react';
 import { buildArgsParam } from 'storybook/internal/router';
 import { useArgs, useGlobals } from 'storybook/preview-api';
-import '@fontsource-variable/source-sans-3';
-import '../src/assets/styles/_shared.scss';
+import '../src/assets/styles/entry-styles';
 import themeCFPB from './themeCFPB';
 
 const responsivePreviewQueryParameter = 'responsivePreview';

README.md

@@ -12,16 +12,28 @@ Current components: https://cfpb.github.io/design-system-react
 
 The `@cfpb/design-system-react` library is released as an [NPM package](https://www.npmjs.com/package/@cfpb/design-system-react).
 
-To install the package and its peer dependencies:
+Install the library and its peer dependencies:
 
 ```
-yarn add @cfpb/design-system-react @cfpb/cfpb-design-system lit react react-dom react-router
+yarn add @cfpb/design-system-react @cfpb/cfpb-design-system lit react react-dom
 ```
 
-`lit` is required because `@cfpb/cfpb-design-system` web components (for example `<cfpb-tagline>` in `Banner`) are built with [Lit](https://lit.dev/).
+Add `react-router` if you use `Link` with `isRouterLink`:
+
+```
+yarn add react-router
+```
+
+| Peer                       | When you need it                                                                                                |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `@cfpb/cfpb-design-system` | Always install it. Required for DS web components and for importing DS styles directly (see [Styles](#styles)). |
+| `lit`                      | Components that render DS web components (for example `Banner` / `<cfpb-tagline>`).                             |
+| `react-router`             | `Link` with `isRouterLink` only.                                                                                |
 
 ## Usage
 
+Import components from the package:
+
 ```ts
 import { Alert, Button } from '@cfpb/design-system-react';
 import type { ReactElement } from 'react';
@@ -43,6 +55,172 @@ export default function SomePage(): ReactElement {
 }
 ```
 
+**You must also load styles** — see [Styles](#styles). Component imports alone do not apply CFPB styling.
+
+## Styles
+
+DSR components render the same CSS class names as `@cfpb/cfpb-design-system` (for example `.a-btn`, `.m-form-field`). **Styles must be loaded separately** — importing React components alone does not apply CFPB styling.
+
+There are **two supported patterns**. Pick one global CSS source for your app — **do not load both**.
+
+### Pattern A: DSR CSS only (new React apps)
+
+For Vite/CRA-style apps with no Sass pipeline. Import the library’s prebuilt stylesheet once:
+
+```ts
+// main.tsx or App.tsx
+import '@cfpb/design-system-react/index.css';
+```
+
+|                       |                                                                                                                                                                           |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **You get**           | DS styles for components listed in [`src/assets/styles/ds-components.ts`](src/assets/styles/ds-components.ts), plus Source Sans 3 (embedded), plus DSR-specific overrides |
+| **You still install** | `@cfpb/cfpb-design-system` (peer dependency — web components, version alignment)                                                                                          |
+| **You do not import** | `@cfpb/cfpb-design-system/dist/index.css` or `@use '…/src/index'` in your app                                                                                             |
+| **Best for**          | Greenfield React apps that mostly use DSR components (`dsr-test`, new internal tools)                                                                                     |
+
+The [`ds-components.ts`](src/assets/styles/ds-components.ts) barrel is the **library-maintained list** of DS SCSS files that feed `dist/index.css`. DSR contributors add to it when new React components need DS styles. App developers using Pattern A do not touch that file.
+
+### Pattern B: Full DS CSS + DSR components (existing CFPB apps)
+
+For apps that already load the full Design System — Sass-based properties, hand-rolled DS markup, cf.gov-style setups (for example apps that use `.o-expandable`, `.m-list`, `.m-btn-group` outside DSR components).
+
+Import **DSR components only**. Do **not** import `@cfpb/design-system-react/index.css`.
+
+**JavaScript / prebuilt CSS:**
+
+```ts
+// App entry — components from DSR, styles from DS
+import { Button, Heading } from '@cfpb/design-system-react';
+// No: import '@cfpb/design-system-react/index.css';
+```
+
+```scss
+// base.scss or global styles entry
+@use '@cfpb/cfpb-design-system/src/abstracts' as *;
+@use '@cfpb/cfpb-design-system/src/base' as *;
+@use '@cfpb/cfpb-design-system/dist/index.css' as *;
+```
+
+**Or Sass source (same coverage as `dist/index.css`):**
+
+```scss
+@use '@cfpb/cfpb-design-system/src/index' as *;
+```
+
+|                       |                                                                                                                                                     |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **You get**           | Full DS component CSS (expandables, lists, button groups, cards, …) and your existing Sass mixins/variables via `@use '…/abstracts'`                |
+| **You still install** | Both `@cfpb/design-system-react` and `@cfpb/cfpb-design-system`                                                                                     |
+| **You do not import** | `@cfpb/design-system-react/index.css` — it duplicates DS rules and embeds fonts a second time                                                       |
+| **Fonts**             | Load Source Sans yourself (for example `@fontsource-variable/source-sans-3` + DS `licensed-font` mixin). DS `dist/index.css` does not include fonts |
+| **Best for**          | Legacy apps mixing DSR React components with plain DS class names in JSX/SCSS                                                                       |
+
+Per-component `@use '@cfpb/cfpb-design-system/src/abstracts'` in your app SCSS is fine — that is Sass API (breakpoints, mixins), not duplicate component CSS.
+
+### Do not combine Pattern A and Pattern B
+
+| If you import…                        | Also import…                              | Result                                                |
+| ------------------------------------- | ----------------------------------------- | ----------------------------------------------------- |
+| `@cfpb/design-system-react/index.css` | `@cfpb/cfpb-design-system/dist/index.css` | Duplicate button/form/alert rules; fonts loaded twice |
+| `@cfpb/design-system-react/index.css` | `@use '…/src/index'` in Sass              | Same duplication                                      |
+
+DSR React components work with either pattern — they emit standard DS classes. Pattern B apps rely on the app’s global DS stylesheet; Pattern A apps rely on the library’s `index.css`.
+
+### Choosing a pattern
+
+| Your situation                                                            | Use                                                                                                                                                |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| New React app, Vite/CRA, mostly DSR components                            | **Pattern A**                                                                                                                                      |
+| Existing app with `dist/index.css` or `@use '…/src/index'` in global SCSS | **Pattern B**                                                                                                                                      |
+| App uses hand-rolled `.o-expandable`, `.m-list`, `.m-btn-group`, etc.     | **Pattern B** (DSR barrel does not include every DS module)                                                                                        |
+| Something looks unstyled on Pattern A                                     | Add the DS file to [`ds-components.ts`](src/assets/styles/ds-components.ts) in DSR, or temporarily switch to Pattern B until the barrel is updated |
+
+### What `ds-components.ts` covers today
+
+Styles bundled into `@cfpb/design-system-react/index.css` (Pattern A only):
+
+| React area                                   | DS stylesheet (under `@cfpb/cfpb-design-system/src/components/…`)                             |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `Button`                                     | `cfpb-buttons/button`, `cfpb-buttons/button-link`                                             |
+| `Heading` (`type="slug"`)                    | `cfpb-typography/slug-header`                                                                 |
+| `Pagination`                                 | `cfpb-pagination/pagination`                                                                  |
+| Forms (`TextInput`, `Checkbox`, `Select`, …) | `cfpb-forms/form`, `form-field`, `label`, `text-input`, `select`, `multiselect`, `form-alert` |
+| `Alert`                                      | `cfpb-notifications/notification` (+ DSR overrides in `alert.scss`)                           |
+| `Table`                                      | `cfpb-tables/table`                                                                           |
+| `Well`, `Divider`                            | `cfpb-layout/well`, `cfpb-layout/layout`                                                      |
+
+Not in the barrel (Pattern B or future DSR work): expandables, lists, button groups, link typography, hero, cards, and other DS modules. Pattern B apps get these from full DS CSS automatically.
+
+### Other options (advanced)
+
+**À la carte Sass** — if you only need buttons and links and already compile SCSS, import specific DS modules instead of full `dist/index.css`:
+
+```scss
+@use '@cfpb/cfpb-design-system/src/base' as base;
+@use '@cfpb/cfpb-design-system/src/components/cfpb-buttons/button';
+@use '@cfpb/cfpb-design-system/src/components/cfpb-buttons/button-link';
+@use '@cfpb/cfpb-design-system/src/components/cfpb-typography/link';
+```
+
+Load fonts yourself. This is a slimmer alternative to Pattern B when you control exactly which DS patterns you use. See [`ds-components.ts`](src/assets/styles/ds-components.ts) for the library’s curated equivalent on Pattern A.
+
+**Abstracts/base only** — `@use '…/src/abstracts'` and `@use '…/src/base'` give tokens and global typography, **not** component rules (no `.a-btn`). You still need Pattern A, Pattern B, or à la carte component imports.
+
+### Quick start (Pattern A — Vite + React)
+
+```ts
+// main.tsx
+import '@cfpb/design-system-react/index.css';
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App.tsx';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
+```
+
+Ensure `@cfpb/cfpb-design-system` and `lit` are installed even on Pattern A, so peer dependencies and web components resolve correctly.
+
+### Storybook (contributors)
+
+Storybook does **not** load prebuilt `dist/index.css`. It compiles the same source stack as Pattern A apps via [`src/assets/styles/entry-styles.ts`](src/assets/styles/entry-styles.ts), imported from [`.storybook/preview.js`](.storybook/preview.js):
+
+```js
+import '../src/assets/styles/entry-styles';
+```
+
+| Layer              | File                                 | Purpose                                                                                                                         |
+| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| Fonts              | `@fontsource-variable/source-sans-3` | Registers `@font-face` in the preview bundle — required for nested “All viewports” iframes (each iframe is a separate document) |
+| Tokens + overrides | `_shared.scss`                       | DS tokens/normalize plus DSR overrides (font stack, `.wrapper--match-content`, docs-tab prose in `#storybook-docs`)             |
+| Component rules    | `ds-components.ts`                   | DS styles bundled into `dist/index.css` for npm consumers                                                                       |
+
+When a component uses Design System class names (for example `.a-btn`, `.m-form-field`), add the matching DS SCSS import to [`ds-components.ts`](src/assets/styles/ds-components.ts). Do not import DS styles from individual component files — the barrel keeps the list in one place.
+
+**Stories** should import components from their source files (for example `./button`, `../Link/link`), not from `~/src/index`. ESLint enforces this on `*.stories.*` (`no-restricted-imports`). **MDX** overview pages should follow the same rule (not linted — our ESLint setup does not parse MDX reliably).
+
+Per-component `.scss` files (for example `banner.scss`, `link.scss`) still load when that component is imported. Storybook-only canvas tweaks live in [`.storybook/preview-head.html`](.storybook/preview-head.html).
+
+### Quick start (Pattern B — existing DS app)
+
+```js
+// App.js — global SCSS already loads DS via base.scss
+import './css/App.scss';
+import { Button, Heading } from '@cfpb/design-system-react';
+// Do not import '@cfpb/design-system-react/index.css'
+```
+
+```scss
+// base.scss
+@use '@cfpb/cfpb-design-system/src/abstracts' as *;
+@use '@cfpb/cfpb-design-system/src/base' as *;
+@use '@cfpb/cfpb-design-system/dist/index.css' as *;
+```
+
 ## Development
 
 To edit components or add new ones, install dependencies and run Storybook:

eslint.config.js

@@ -10,6 +10,29 @@ import unicorn from 'eslint-plugin-unicorn';
 import globals from 'globals';
 import tseslint from 'typescript-eslint';
 
+/** Stories must not import the library barrel — see README “Storybook styles”. */
+const noLibraryBarrelInStories = {
+  'no-restricted-imports': [
+    'error',
+    {
+      paths: [
+        {
+          name: '~/src/index',
+          message:
+            'Import the component from its source file (e.g. ./button). Global styles load via .storybook/preview.js → entry-styles.ts.',
+        },
+      ],
+      patterns: [
+        {
+          group: ['~/src/index', '~/src/index.ts'],
+          message:
+            'Import the component from its source file (e.g. ./button). Global styles load via .storybook/preview.js → entry-styles.ts.',
+        },
+      ],
+    },
+  ],
+};
+
 export default tseslint.config(
   {
     ignores: [
@@ -97,4 +120,9 @@ export default tseslint.config(
       '@typescript-eslint/no-explicit-any': 'off',
     },
   },
+  // Stories: import components from source, not the library barrel (MDX: same convention; see README).
+  {
+    files: ['**/*.stories.ts?(x)'],
+    rules: noLibraryBarrelInStories,
+  },
 );

src/assets/styles/_shared.scss

@@ -11,10 +11,10 @@
 */
 
 /**
- * Source Sans 3 is loaded via `@fontsource-variable/source-sans-3` in **`src/index.ts`** (apps)
- * and **`.storybook/preview.js`** (Storybook, including nested “All viewports” iframes) before
- * `_shared.scss` so `@font-face` is always registered.
- *
+ * Source Sans 3 and this file are loaded via **`entry-styles.ts`**, imported from
+ * **`src/index.ts`** and **`.storybook/preview.js`**, so `@font-face` is always registered
+ * (including nested “All viewports” Storybook iframes).
+ * DS component rules load from **`ds-components.ts`** via the same entry.
  * DS `custom-props` sets `--font-stack-branded: initial`, so `var(--font-stack)` falls back to
  * `system-ui`. Other DS chunks can repeat that `:root` block when code-split; in dev the last
  * chunk can win and wipe a non-`!important` override. Pin both tokens with `!important` so inputs,

src/assets/styles/ds-components.ts

@@ -0,0 +1,44 @@
+/**
+ * Curated Design System component styles bundled into `dist/index.css`.
+ *
+ * When adding a React component that uses DS class names, add the matching DS
+ * SCSS import here (once per file — duplicates are unnecessary). Component
+ * `.tsx` files should not import DS styles directly.
+ *
+ * Styles listed here are bundled into `dist/index.css` via `entry-styles.ts` and
+ * loaded in Storybook the same way.
+ */
+
+// Icons — Icon (and any component with .cf-icon-svg)
+import '@cfpb/cfpb-design-system/src/components/cfpb-icons/icon.scss';
+
+// Buttons — Button
+import '@cfpb/cfpb-design-system/src/components/cfpb-buttons/button.scss';
+import '@cfpb/cfpb-design-system/src/components/cfpb-buttons/button-link.scss';
+
+// Forms — Checkbox, RadioButton, Fieldset, Label, HelperText, TextInput,
+// TextArea, SelectSingle, SelectMulti, AlertFieldLevel
+import '@cfpb/cfpb-design-system/src/components/cfpb-forms/form.scss';
+import '@cfpb/cfpb-design-system/src/components/cfpb-forms/form-field.scss';
+import '@cfpb/cfpb-design-system/src/components/cfpb-forms/form-alert.scss';
+import '@cfpb/cfpb-design-system/src/components/cfpb-forms/label.scss';
+import '@cfpb/cfpb-design-system/src/components/cfpb-forms/text-input.scss';
+import '@cfpb/cfpb-design-system/src/components/cfpb-forms/select.scss';
+import '@cfpb/cfpb-design-system/src/components/cfpb-forms/multiselect.scss';
+
+// Typography — Heading (type="slug"), Link
+import '@cfpb/cfpb-design-system/src/components/cfpb-typography/slug-header.scss';
+import '@cfpb/cfpb-design-system/src/components/cfpb-typography/link.scss';
+
+// Layout — Divider (.content__line), Well
+import '@cfpb/cfpb-design-system/src/components/cfpb-layout/layout.scss';
+import '@cfpb/cfpb-design-system/src/components/cfpb-layout/well.scss';
+
+// Notifications — Alert (page-level)
+import '@cfpb/cfpb-design-system/src/components/cfpb-notifications/notification.scss';
+
+// Pagination — Pagination
+import '@cfpb/cfpb-design-system/src/components/cfpb-pagination/pagination.scss';
+
+// Tables — Table
+import '@cfpb/cfpb-design-system/src/components/cfpb-tables/table.scss';

src/assets/styles/entry-styles.ts

@@ -0,0 +1,8 @@
+/**
+ * Global style entry for library consumers and Storybook.
+ *
+ * Imported from `src/index.ts` and `.storybook/preview.js`. Keep both in sync.
+ */
+import '@fontsource-variable/source-sans-3';
+import './_shared.scss';
+import './ds-components';

src/components/Alert/alert.stories.tsx

@@ -1,6 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import type { ReactNode } from 'react';
-import { Alert, AlertFieldLevel, TextInput } from '~/src/index';
+import { Alert } from './alert';
+import { AlertFieldLevel } from './alert-field-level';
+import { TextInput } from '../TextInput/text-input';
 
 const meta: Meta<typeof Alert> = {
   title: 'Components (Draft)/Alerts',

src/components/Banner/banner.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import type { ReactNode, SyntheticEvent } from 'react';
-import { Banner } from '~/src/index';
+import { Banner } from './banner';
 import { AllLanguageCodes, LanguageLink } from './banner-language-link';
 
 const meta: Meta<typeof Banner> = {

src/components/Breadcrumb/breadcrumb.stories.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Breadcrumb } from '~/src/index';
+import { Breadcrumb } from './breadcrumb';
 
 const meta: Meta<typeof Breadcrumb> = {
   title: 'Components (Draft)/Breadcrumbs',

src/components/Buttons/buttons.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { expect, fn, userEvent, within } from 'storybook/test';
-import { Button, Link } from '~/src/index';
+import { Button } from './button';
+import Link from '../Link/link';
 import { ButtonGroup } from './button-group';
 
 /**