`)\n 382→3. Include tokens.css first, then components\n 383→4. Test in both light and dark modes\n 384→5. Use the living documentation (index.html) for visual reference\n 385→6. Keep spacing consistent using the spacing scale\n 386→7. Use utility classes for quick layouts\n 387→8. Card component is perfect for grouping content\n 388→9. Stack class handles vertical rhythm automatically\n 389→10. Container class centers and constrains content width\n 390→"}]},"uuid":"f15df57c-ec55-4fe5-900e-39b20f8cdb6c","timestamp":"2026-02-26T08:34:46.940Z","sourceToolAssistantUUID":"11e7b3d9-bcfe-4efc-88ae-db578f10b93a"}
{"parentUuid":"f15df57c-ec55-4fe5-900e-39b20f8cdb6c","isSidechain":true,"userType":"external","cwd":"/home/josie/development/personal/josiedot","sessionId":"c514f1c3-0c37-43cf-8aa4-6f853eaddd4f","version":"2.1.58","gitBranch":"main","agentId":"aa4e93909597934a4","slug":"serene-munching-planet","message":{"model":"claude-haiku-4-5-20251001","id":"msg_019eH5xKihjV1VQP5VegvW5h","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01TAykDnF4Tni3CzGY7LMi2G","name":"Read","input":{"file_path":"/home/josie/development/personal/josiedot/design/docs/integration-guide.md"},"caller":{"type":"direct"}}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":6,"cache_creation_input_tokens":5446,"cache_read_input_tokens":56791,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":5446},"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"}},"requestId":"req_011CYWNc78hjVwsmpgX84uDo","type":"assistant","uuid":"7a8ec1d4-ce85-4666-87f6-470c6f4e24c6","timestamp":"2026-02-26T08:34:47.009Z"}
{"parentUuid":"7a8ec1d4-ce85-4666-87f6-470c6f4e24c6","isSidechain":true,"userType":"external","cwd":"/home/josie/development/personal/josiedot","sessionId":"c514f1c3-0c37-43cf-8aa4-6f853eaddd4f","version":"2.1.58","gitBranch":"main","agentId":"aa4e93909597934a4","slug":"serene-munching-planet","type":"progress","data":{"type":"hook_progress","hookEvent":"PreToolUse","hookName":"PreToolUse:Read","command":"python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.py"},"toolUseID":"toolu_01TAykDnF4Tni3CzGY7LMi2G","parentToolUseID":"toolu_01TAykDnF4Tni3CzGY7LMi2G","uuid":"73a6932f-5533-4b59-a422-e2f5aa04c62d","timestamp":"2026-02-26T08:34:47.010Z"}
{"parentUuid":"73a6932f-5533-4b59-a422-e2f5aa04c62d","isSidechain":true,"userType":"external","cwd":"/home/josie/development/personal/josiedot","sessionId":"c514f1c3-0c37-43cf-8aa4-6f853eaddd4f","version":"2.1.58","gitBranch":"main","agentId":"aa4e93909597934a4","slug":"serene-munching-planet","type":"progress","data":{"type":"hook_progress","hookEvent":"PostToolUse","hookName":"PostToolUse:Read","command":"python3 ${CLAUDE_PLUGIN_ROOT}/hooks/posttooluse.py"},"parentToolUseID":"toolu_01TAykDnF4Tni3CzGY7LMi2G","toolUseID":"toolu_01TAykDnF4Tni3CzGY7LMi2G","timestamp":"2026-02-26T08:34:47.070Z","uuid":"e3cd07d1-0e08-4a36-b61d-378e19d69f0e"}
{"parentUuid":"e3cd07d1-0e08-4a36-b61d-378e19d69f0e","isSidechain":true,"userType":"external","cwd":"/home/josie/development/personal/josiedot","sessionId":"c514f1c3-0c37-43cf-8aa4-6f853eaddd4f","version":"2.1.58","gitBranch":"main","agentId":"aa4e93909597934a4","slug":"serene-munching-planet","type":"progress","data":{"type":"hook_progress","hookEvent":"PostToolUse","hookName":"PostToolUse:Read","command":"callback"},"parentToolUseID":"toolu_01TAykDnF4Tni3CzGY7LMi2G","toolUseID":"toolu_01TAykDnF4Tni3CzGY7LMi2G","timestamp":"2026-02-26T08:34:47.070Z","uuid":"ba646bac-0717-44f0-afd4-8b1f78328675"}
{"parentUuid":"7a8ec1d4-ce85-4666-87f6-470c6f4e24c6","isSidechain":true,"userType":"external","cwd":"/home/josie/development/personal/josiedot","sessionId":"c514f1c3-0c37-43cf-8aa4-6f853eaddd4f","version":"2.1.58","gitBranch":"main","agentId":"aa4e93909597934a4","slug":"serene-munching-planet","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01TAykDnF4Tni3CzGY7LMi2G","type":"tool_result","content":" 1→# Integration Guide\n 2→\n 3→How to adopt the josie.* design system in a new or existing project.\n 4→\n 5→## Prerequisites\n 6→\n 7→The design system is plain CSS with no build step. It expects to live as a sibling directory to your project inside the josiedot monorepo:\n 8→\n 9→```\n 10→josiedot/\n 11→ design/ <-- this repo\n 12→ josiedothealth/\n 13→ josiedotlol/\n 14→ josiedotplace/\n 15→ josiedottown/\n 16→```\n 17→\n 18→All import paths in this guide assume that layout. Adjust the relative paths if your project structure differs.\n 19→\n 20→## Step 1: Import the Tokens\n 21→\n 22→Every project starts with `tokens.css`. This gives you the full set of CSS custom properties (colors, typography, spacing, shadows, z-index, transitions) and a baseline reset (box-sizing, body font, background color). Dark mode support is included automatically.\n 23→\n 24→```html\n 25→
\n 26→```\n 27→\n 28→After this single import, you can use design tokens anywhere in your own CSS:\n 29→\n 30→```css\n 31→.my-element {\n 32→ color: var(--text-primary);\n 33→ background: var(--bg-secondary);\n 34→ padding: var(--space-4);\n 35→ border: var(--border-thin) solid var(--border-color);\n 36→ border-radius: var(--radius-base);\n 37→ font-size: var(--text-sm);\n 38→ transition: background var(--transition-base);\n 39→}\n 40→```\n 41→\n 42→This is the minimum viable integration. If your project has its own component library, you can stop here and build on top of the tokens.\n 43→\n 44→## Step 2: Add Component Stylesheets\n 45→\n 46→Import only the component stylesheets you need. Each one is independent; they depend on `tokens.css` but not on each other.\n 47→\n 48→```html\n 49→\n 50→
\n 51→\n 52→\n 53→
\n 54→
\n 55→
\n 56→
\n 57→```\n 58→\n 59→### What Each Stylesheet Provides\n 60→\n 61→**buttons.css** -- `.button` with variants `.secondary`, `.ghost`, `.danger` and size modifiers `.small`, `.large`, `.full-width`.\n 62→\n 63→**cards.css** -- `.card` with variants `.flat`, `.elevated`, `.outlined` and structure classes `.card-header`, `.card-title`, `.card-subtitle`, `.card-body`, `.card-footer`. Also `.card-grid` for responsive auto-fill layouts.\n 64→\n 65→**forms.css** -- `.input` with states `.error`, `.success` and sizes `.small`, `.large`. Toggle switches (`.toggle-switch`, `.toggle-group`), checkboxes (`.checkbox`), radios (`.radio`), and validation messages (`.form-helper`, `.form-error`, `.form-success`).\n 66→\n 67→**layout.css** -- `.container` (with `.narrow`, `.wide`, `.full`), flex utilities (`.flex`, `.flex-col`, `.items-center`, `.justify-between`, etc.), grid utilities (`.grid`, `.grid-cols-2`, `.grid-cols-3`, `.grid-cols-4`), gap utilities (`.gap-1` through `.gap-8`), margin/padding utilities, `.section`, and `.stack`.\n 68→\n 69→## Step 3: Set Up Your HTML Boilerplate\n 70→\n 71→Minimal starting point:\n 72→\n 73→```html\n 74→\n 75→\n 76→\n 77→
\n 78→
\n 79→
\n 80→
project name\n 81→\n 82→
\n 83→
\n 84→
\n 85→
\n 86→
\n 87→\n 88→
\n 89→\n 90→\n 91→
\n 92→ \n 93→
\n 94→\n 95→\n 96→```\n 97→\n 98→Your project stylesheet loads last so it can extend or override design system styles when needed.\n 99→\n 100→## Migrating an Existing Project\n 101→\n 102→If you are adding the design system to a project that already has its own CSS, adopt it incrementally rather than rewriting everything at once.\n 103→\n 104→### Phase 1: Tokens Only\n 105→\n 106→Import `tokens.css` and start replacing hardcoded values in your existing stylesheets with design token references. Target these categories in order:\n 107→\n 108→1. **Colors** -- Replace hex values with `var(--text-primary)`, `var(--bg-secondary)`, `var(--border-color)`, etc. This gets you automatic dark mode for free.\n 109→2. **Spacing** -- Replace pixel values with `var(--space-N)`. The scale uses 4px increments: `--space-1` is 4px, `--space-2` is 8px, `--space-4` is 16px, and so on.\n 110→3. **Typography** -- Replace font-size declarations with `var(--text-sm)`, `var(--text-base)`, `var(--text-lg)`, etc.\n 111→4. **Borders and radii** -- Use `var(--border-thin)`, `var(--radius-base)`, etc.\n 112→\n 113→### Phase 2: Replace Custom Components\n 114→\n 115→Once your tokens are in place, start swapping your custom button, card, form, and layout styles for the design system components. Work through one component type at a time:\n 116→\n 117→1. Swap button styles for `.button` classes\n 118→2. Swap card/panel styles for `.card` classes\n 119→3. Swap form input styles for `.input` and `.form-group` classes\n 120→4. Replace layout scaffolding with `.container`, `.flex`, `.grid` utilities\n 121→\n 122→### Phase 3: Remove Dead CSS\n 123→\n 124→After migration, audit your project stylesheet and delete any rules that are now handled by the design system. The goal is to have your project CSS contain only project-specific styles that extend the system.\n 125→\n 126→## Writing Project-Specific Styles\n 127→\n 128→When you need styles beyond what the design system provides, always build on top of the tokens:\n 129→\n 130→```css\n 131→/* Good -- uses tokens */\n 132→.project-sidebar {\n 133→ width: 250px;\n 134→ background: var(--bg-secondary);\n 135→ border-right: var(--border-thin) solid var(--border-color);\n 136→ padding: var(--space-6);\n 137→}\n 138→\n 139→.project-sidebar a {\n 140→ display: block;\n 141→ padding: var(--space-3);\n 142→ color: var(--text-secondary);\n 143→ text-decoration: none;\n 144→ border-radius: var(--radius-base);\n 145→ transition: background var(--transition-fast);\n 146→}\n 147→\n 148→.project-sidebar a:hover {\n 149→ background: var(--bg-tertiary);\n 150→ color: var(--text-primary);\n 151→}\n 152→```\n 153→\n 154→```css\n 155→/* Bad -- hardcoded values bypass the system */\n 156→.project-sidebar {\n 157→ width: 250px;\n 158→ background: #2a2a2a;\n 159→ border-right: 1px solid #404040;\n 160→ padding: 24px;\n 161→}\n 162→```\n 163→\n 164→Using tokens means your project-specific styles will adapt to dark/light mode automatically and stay visually consistent with every other josie.* project.\n 165→\n 166→## Dark Mode\n 167→\n 168→Dark mode is handled entirely by `tokens.css` via `@media (prefers-color-scheme: dark)`. If all your styles reference design tokens, dark mode works without any additional effort.\n 169→\n 170→Things to watch for:\n 171→\n 172→- **Hardcoded colors will not adapt.** Any `color: #333` or `background: white` in your project CSS will ignore the user's color scheme preference. Always use token variables.\n 173→- **Images and media** may need separate treatment. Consider providing dark variants or using `filter: invert()` / `opacity` adjustments where appropriate.\n 174→- **Third-party widgets** (maps, embeds, iframes) will not respect the token system. Style their containers and accept that their internals are outside your control.\n 175→\n 176→### Testing Dark Mode\n 177→\n 178→In Firefox or Chrome DevTools, use the color scheme emulation to toggle between light and dark without changing your OS settings.\n 179→\n 180→## Using JSON Tokens in Build Tools\n 181→\n 182→The `tokens/` directory includes JSON files (`colors.json`, `typography.json`, `spacing.json`) for programmatic access. Use these when you need token values in JavaScript, build scripts, or templating:\n 183→\n 184→```javascript\n 185→import colors from '../design/tokens/colors.json';\n 186→import typography from '../design/tokens/typography.json';\n 187→import spacing from '../design/tokens/spacing.json';\n 188→\n 189→const primaryBg = colors.colors.background.light.primary;\n 190→const baseFontSize = typography.typography.fontSizes.base;\n 191→```\n 192→\n 193→This is useful for generating styles in JS frameworks, populating config objects, or feeding tokens into tools like PostCSS.\n 194→\n 195→## Presentations\n 196→\n 197→The design system includes a LaTeX Beamer theme for slide decks. If your project involves presentations:\n 198→\n 199→```bash\n 200→cd design/beamer\n 201→pandoc slides.md -d josie.yaml -o slides.pdf\n 202→```\n 203→\n 204→Write your slides in Markdown, and the josie Beamer theme handles fonts (IBM Plex Sans/Mono), colors, and layout to match the rest of the identity.\n 205→\n 206→## Responsive Behavior\n 207→\n 208→The component stylesheets use three breakpoints:\n 209→\n 210→| Breakpoint | Width | Behavior |\n 211→|------------|-----------|------------------------------------|\n 212→| Mobile | < 640px | Grids collapse to single column |\n 213→| Tablet | < 1024px | 3- and 4-column grids become 2-col |\n 214→| Desktop | >= 1024px | Full grid layouts |\n 215→\n 216→The `.container` class centers content at 1200px max-width with `--container-padding` gutters. Use `.container.narrow` (800px) for text-heavy pages and `.container.wide` (1400px) for dashboards.\n 217→\n 218→## Checklist\n 219→\n 220→Use this when integrating a new project:\n 221→\n 222→- [ ] `tokens.css` imported before all other stylesheets\n 223→- [ ] Component stylesheets imported selectively (only what the project uses)\n 224→- [ ] Project stylesheet loaded after design system imports\n 225→- [ ] No hardcoded color hex values in project CSS (use `--text-*`, `--bg-*`, `--border-color`, `--color-*` tokens)\n 226→- [ ] No hardcoded pixel spacing in project CSS (use `--space-*` tokens)\n 227→- [ ] No hardcoded font sizes in project CSS (use `--text-*` tokens)\n 228→- [ ] Buttons use `.button` classes instead of custom styles\n 229→- [ ] Form inputs use `.input` classes instead of custom styles\n 230→- [ ] Layout uses `.container`, `.flex`, `.grid` utilities where appropriate\n 231→- [ ] Page tested in both light and dark mode\n 232→- [ ] Page tested at mobile, tablet, and desktop widths\n 233→- [ ] Semantic HTML used (`