# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
# Development (runs webpack + eleventy in parallel)
npm start

# Watch JS/SCSS only
npm run dev:scripts

# Eleventy dev server only (port 8080)
npm run dev:11ty

# Production build
npm run build

# Clean dist/
npm run clean
```

There are no lint or test commands configured in this project.

## Architecture

This is the **Test IO Design System** — a component library published as an npm package and documented via a static site.

**Two build pipelines run in parallel:**

1. **Webpack** (`webpack.config.js`) — bundles `src/assets/scripts/` (JS) and `src/assets/stylesheets/` (SCSS) into `dist/assets/`. Outputs `design-system.js` and `design-system.css` as the publishable library artifacts.

2. **Eleventy** (`.eleventy.js`) — takes `src/` as input, outputs to `dist/`. Pages live in `src/pages/` organized by component category. Templates use Nunjucks (primary), Pug, and HAML. Layouts in `src/_layouts/`, partials in `src/_includes/`.

**Key source locations:**
- `src/assets/scripts/` — jQuery-based component interactions, ECharts chart helpers, form component logic
- `src/assets/stylesheets/` — SCSS design tokens, component styles, vendored Bootstrap, plugin themes
- `src/pages/` — Documentation pages per component category (buttons, charts, components, forms, icons, navigation, typography, etc.)
- `src/static/` — Icon data (JSON), downloadable assets
- `utils/` — Eleventy helpers: `collections.js`, `filters.js`, `transforms.js`, `markdown.js`

**Frontend dependencies to be aware of:** jQuery 3.6, ECharts 5.6, Tom-Select, Select2, Trix, Dropzone, Flatpickr, Luxon. These are bundled via webpack entry points, not imported as ES modules.

**Publishing:** The npm package is published by CircleCI when `package.json` version is incremented. The documentation site is deployed as a Docker container to GCP (Kubernetes namespace `designsystems`). Netlify is also configured as an alternative deployment target.

**Adding a new component:** Create a page under `src/pages/<category>/`, add the SCSS to `src/assets/stylesheets/`, and any JS to `src/assets/scripts/`. The Eleventy build picks up new `.njk`/`.pug`/`.haml`/`.html` files automatically.

## Component Reference

See [`ai-reference.md`](./ai-reference.md) for the topic index. Load only the file you need:

| File | Covers |
|------|--------|
| [`ai-reference/setup.md`](./ai-reference/setup.md) | Install, CSS/JS import, directory structure, HAML conventions |
| [`ai-reference/design-tokens.md`](./ai-reference/design-tokens.md) | Colors, typography, spacing, breakpoints |
| [`ai-reference/buttons.md`](./ai-reference/buttons.md) | Button variants, sizes, icons, dropdowns |
| [`ai-reference/forms.md`](./ai-reference/forms.md) | Inputs, checkboxes, radios, toggles, selects, date pickers |
| [`ai-reference/cards.md`](./ai-reference/cards.md) | Card variants, sizes, layouts, collapsable |
| [`ai-reference/navigation.md`](./ai-reference/navigation.md) | Header, sidebar, tabs, portal variants |
| [`ai-reference/overlays.md`](./ai-reference/overlays.md) | Modals, drawers |
| [`ai-reference/feedback.md`](./ai-reference/feedback.md) | Alerts, notifications, progress, spinners, empty states |
| [`ai-reference/data-display.md`](./ai-reference/data-display.md) | Tables, lists, splitview |
| [`ai-reference/charts.md`](./ai-reference/charts.md) | ECharts setup and chart functions |
| [`ai-reference/utilities.md`](./ai-reference/utilities.md) | Tags, popovers, pagination, stepper, icons |
| [`ai-reference/layouts.md`](./ai-reference/layouts.md) | App/splitview/chat layouts, best practices, portal guidelines |