carbon-design-system
diff --git a/‎CLAUDE.md‎
Lines changed: 301 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 301 additions & 0 deletions
@@ -0,0 +1,301 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a **Carbon Design System** React starter template with server-side rendering (SSR). The project uses Vite, React 19, React Router 7, and Express to provide a full-stack SSR application scaffold. It's designed to be a starting point for teams building applications with IBM's Carbon Design System.
+
+**Key requirement:** Node 24 is required for development.
+
+## Common Commands
+
+### Development
+```bash
+npm run dev           # Start development server with hot reload (runs src/server.js)
+npm run preview       # Preview production build locally (NODE_ENV=local)
+npm run preview:prod  # Preview production build (NODE_ENV=production)
+```
+
+### Building
+```bash
+npm run build         # Build both client and server for production
+npm run build:client  # Build client-side bundle only
+npm run build:server  # Build server-side bundle only
+```
+
+### Testing
+```bash
+npm run test          # Run all tests with coverage (Vitest)
+npm run test:watch    # Run tests in watch mode
+```
+
+### Linting
+```bash
+npm run lint          # Run all linters (ESLint, Stylelint, Prettier, CSpell)
+npm run lint-fix      # Auto-fix ESLint, Stylelint, and Prettier issues
+npm run lint:es       # ESLint only
+npm run lint:style    # Stylelint only (for SCSS files)
+npm run lint:format   # Prettier only
+npm run lint:spell    # CSpell (spell checker) only
+```
+
+## Architecture
+
+### Server-Side Rendering (SSR)
+
+The application is split into **client-side** and **server-side** code:
+
+- **Entry points:**
+  - `src/entry-client.jsx` - Client-side hydration entry point (uses `hydrateRoot` with `BrowserRouter`)
+  - `src/entry-server.jsx` - Server-side rendering entry point (uses `renderToPipeableStream` with `StaticRouter`)
+  - `src/server.js` - Express server that handles SSR and serves the application
+
+- **Server flow:**
+  - In development: Vite dev server with middleware mode handles HMR and SSR
+  - In production: Express serves static assets from `dist/client` and renders HTML via `dist/server`
+  - The server splits `index.html` at `<!--app-html-->` marker and streams React output in between
+
+### Routing Architecture
+
+Routes are defined in a **flat configuration** (`src/routes/config.js`) and then organized hierarchically:
+
+- Each route has a `path` and optional `element` (React component)
+- Routes include a `carbon` property with metadata for Carbon UI components:
+  - `label` - Display name in navigation
+  - `inHeader` - Show in header navigation
+  - `inSideNav` - Show in side navigation
+  - `icon` - Carbon icon component
+  - `href` - External links (for routes without elements)
+  - `virtualPath` - Path for routes without actual pages (like external links)
+  - `subMenu` - Auto-generated from child routes matching parent path pattern
+
+- **Route processing:**
+  - Flat routes are processed to create a hierarchy for Carbon header/sidenav
+  - `routesInHeader` and `routesInSideNav` are exported for nav components
+  - Parent-child relationships are detected via path patterns (`/parent/child`)
+
+- **Status codes:**
+  - Routes can have a `status` property (e.g., 404 for NotFound)
+  - `src/routes/utils.js` exports `getStatusCodeForPath()` for SSR
+
+### API Routes
+
+API routes are registered via `src/routes/routes.js`:
+- Uses `getRoutes(app, handlers)` pattern for testability
+- Handlers can be swapped for mocks in tests
+- Example: `app.get('/api/message', handlers.getMessage)`
+- Service layer is in `src/service/`, API layer in `src/api/`
+
+### Theme Management
+
+The app uses a sophisticated theme system via `ThemeContext`:
+
+- **Theme settings:**
+  - `themeSetting`: 'system' | 'light' | 'dark'
+  - `themeMenuCompliment`: boolean (inverts header/menu theme)
+  - Persisted to localStorage via `src/utils/local-storage.js`
+
+- **Theme values:**
+  - `theme`: 'g10' (light) or 'g100' (dark) - main page theme
+  - `themeMenu`: 'g10' or 'g100' - header/menu theme (can differ if compliment enabled)
+  - Uses Carbon's `usePrefersDarkScheme()` for system preference detection
+
+- **Implementation:**
+  - `ThemeProvider` wraps the app in `entry-client.jsx` (client-only, not server)
+  - `ThemeLayout` wraps routes and applies `GlobalTheme` and `Theme` components
+  - Updates `document.documentElement` with `cs--theme` attribute
+
+### CSS/SCSS
+
+- **Carbon Design System** styles are imported via SCSS
+- Styles are loaded from `index.html` (not React components) to avoid FOUC and layout shifts
+- Uses `sass-embedded` for SCSS compilation
+- Stylelint enforces:
+  - Carbon tokens/mixins/functions usage (`stylelint-plugin-carbon-tokens`)
+  - Logical properties (e.g., `block-size` instead of `height`)
+  - Accessibility rules (`@double-great/stylelint-a11y`)
+
+### Testing
+
+Testing uses **Vitest**, **React Testing Library**, and **MSW** (Mock Service Worker):
+
+- **Setup:** `src/test/setup.js` configures mocks for JSDOM (matchMedia, ResizeObserver, etc.)
+- **MSW integration:**
+  - `src/test/server.js` wraps MSW's setupServer with networking utils
+  - `src/test/networking.js` tracks outgoing requests for debugging
+  - `src/test/router.js` provides router for registering mock handlers
+  - API routes are registered using the same `getRoutes()` function as production
+- **Test files:** Place tests in `src/__tests__/*.test.jsx` or `src/__tests__/*.test.js`
+- **Coverage:** Vitest automatically generates coverage reports using V8 provider
+
+## Project Structure
+
+```
+src/
+├── entry-client.jsx          # Client hydration entry
+├── entry-server.jsx          # SSR render entry
+├── server.js                 # Express server
+├── context/                  # React contexts (ThemeContext)
+├── routes/
+│   ├── config.js            # Route definitions with Carbon metadata
+│   ├── index.jsx            # Router component
+│   ├── routes.js            # API route registration
+│   └── utils.js             # Route utilities (status codes, etc.)
+├── layouts/                  # Layout wrappers (theme-layout, page-layout)
+├── pages/                    # Page components
+├── components/               # Shared components (Nav, Footer, etc.)
+├── test/                     # Test setup and utilities
+│   ├── setup.js             # Vitest setup, JSDOM mocks
+│   ├── server.js            # MSW server wrapper
+│   ├── networking.js        # Network request tracking
+│   └── test-utils.jsx       # Custom render utilities
+├── __tests__/               # Test files
+├── api/                      # API layer (data fetching)
+├── service/                  # Service layer (business logic)
+└── utils/                    # Utility functions
+
+dist/
+├── client/                   # Client build output
+└── server/                   # Server build output
+```
+
+## Important Development Notes
+
+### Adding New Routes
+
+1. Add route config to `src/routes/config.js`
+2. Include `carbon` metadata for navigation (`label`, `inHeader`, `inSideNav`, etc.)
+3. The route will automatically be organized into parent/child hierarchy
+4. For external links, use `href` and `virtualPath` instead of `path` and `element`
+
+### Stylelint Rules
+
+When disabling Stylelint rules, ALWAYS provide a description:
+```scss
+/* stylelint-disable-next-line rule-name -- Reason for disabling */
+```
+Never disable rules for entire files. See `docs/Stylelint.md` for details.
+
+### Server-Side Rendering Considerations
+
+- `ThemeProvider` is only in `entry-client.jsx` (not server-side) because it depends on `window.localStorage`
+- Server uses `StaticRouter`, client uses `BrowserRouter`
+- Template has `<!--app-html-->` placeholder where React output is injected
+- Server aborts rendering after 10 seconds (`ABORT_DELAY`)
+
+### Testing API Routes
+
+Tests can use the same `getRoutes()` function as production by passing mock handlers:
+```javascript
+import { getRoutes } from '../routes/routes';
+import { getRouter } from './router';
+
+const mockHandlers = { getMessage: vi.fn() };
+getRoutes(getRouter(mocks, networking), mockHandlers);
+```
+
+## Internationalization (i18n)
+
+This project uses **i18next** with **react-i18next** for internationalization, fully integrated with SSR.
+
+### Translation Pattern
+
+English text stays **inline** with components using the `defaultValue` pattern. Other languages are stored in separate JSON files:
+
+```jsx
+import { useTranslation } from 'react-i18next';
+
+const MyComponent = () => {
+  const { t } = useTranslation();
+
+  return (
+    <div>
+      <h1>{t('myComponent.title', 'Default English Title')}</h1>
+      <p>{t('myComponent.description', 'Default English description text.')}</p>
+    </div>
+  );
+};
+```
+
+- **First parameter**: Translation key (e.g., `'myComponent.title'`)
+- **Second parameter**: English text (default value)
+- Only non-English translations need to be added to language files
+
+### File Structure
+
+```
+src/
+├── i18n.client.js           # Client-side i18n config
+├── i18n.server.js           # Server-side i18n config
+└── locales/
+    ├── de.json              # German translations
+    └── [lang].json          # Add more languages here
+```
+
+### Adding New Languages
+
+1. Create a new JSON file in `src/locales/` (e.g., `fr.json` for French)
+2. Add the language to `supportedLngs` in both `i18n.client.js` and `i18n.server.js`:
+   ```js
+   supportedLngs: ['en', 'de', 'fr'],
+   ```
+3. Add translations matching the keys used in components:
+   ```json
+   {
+     "myComponent": {
+       "title": "Titre en français",
+       "description": "Description en français."
+     }
+   }
+   ```
+
+### Translation File Format
+
+Organize translations by component/page using nested objects:
+
+```json
+{
+  "welcome": {
+    "title": "Willkommen",
+    "description": "Beschreibung",
+    "features": {
+      "title": "Funktionen",
+      "subtitle": "Untertitel"
+    }
+  },
+  "dashboard": {
+    "title": "Dashboard"
+  }
+}
+```
+
+### Language Detection
+
+The app automatically detects the user's preferred language from:
+1. Browser settings (`navigator.language`)
+2. HTML `lang` attribute
+3. Falls back to English if language not supported
+
+### SSR Considerations
+
+- Server-side config (`i18n.server.js`) uses filesystem backend to load translations
+- Client-side config (`i18n.client.js`) uses dynamic imports with browser language detection
+- Translations are serialized on server and hydrated on client to prevent language flicker
+- Both configs have `useSuspense: false` for SSR compatibility
+
+### Packages Used
+
+- `i18next` - Core i18n engine
+- `react-i18next` - React bindings (provides `useTranslation` hook)
+- `i18next-http-middleware` - Express middleware for SSR language detection
+- `i18next-fs-backend` - Server-side filesystem loader
+- `i18next-browser-languagedetector` - Client-side language detection
+- `i18next-resources-to-backend` - Client-side dynamic translation loading
+- `vite-plugin-i18next-loader` - Vite plugin for HMR support
+
+## Husky Pre-commit Hooks
+
+The project uses Husky with lint-staged to run linters on staged files before commit. Specifically:
+- ESLint runs on staged JS/TS/JSX/TSX files
+- Special check prevents accidental commit of `.npmrc`