llms.txt

# CodeSignal Design System - LLM Reference

## Quick Start

Include these CSS files in order:
1. colors/colors.css
2. spacing/spacing.css  
3. typography/typography.css
4. components/[component]/[component].css

Also include Work Sans font from Google Fonts.

## Design Tokens

### Colors
- Base scales: `--Colors-Base-[Family]-[Step]` (e.g., `--Colors-Base-Primary-700`)
- Semantic: `--Colors-[Category]-[Context]` (e.g., `--Colors-Text-Body-Default`)
- Prefer semantic tokens over base scales for theming support

### Spacing
- Pattern: `--UI-Spacing-spacing-[size]` (none, min, xxs, xs, s, mxs, ms, m, ml, mxl, l, xl, xxl, xxxl, 4xl, max)
- Radius: `--UI-Radius-radius-[size]` (none, min, xxs, xs, s, m, ml, mxl, l, xl)
- Input heights: `--UI-Input-[size]` (min: 26px, xs: 32px, sm: 40px, md: 48px, lg: 60px)

### Typography
- Classes: `.body-[size]`, `.heading-[size]`, `.label-[size]`
- Fonts: Work Sans (body), Founders Grotesk (headings), JetBrains Mono (code)

## Components

### Button
- Base: `.button`
- Variants: `.button-primary`, `.button-secondary`, `.button-tertiary`, `.button-danger`, `.button-success`, `.button-text`, `.button-text-primary`
- Sizes: `.button-xsmall`, `.button-small`, `.button-large` (default: medium/48px)
- Example: `<button class="button button-primary">Click</button>`

### Box
- Base: `.box`
- Variants: `.box.selected`, `.box.emphasized`, `.box.shadowed`, `.box.card`, `.box.non-interactive`
- `.box.non-interactive`: Disables hover/focus/active state changes (useful for non-clickable containers)
- Example: `<div class="box">Content</div>` or `<div class="box card non-interactive">Non-interactive card</div>`

### Input
- Base: `.input`
- Types: `type="text"` or `type="number"`
- States: `.hover`, `.focus`, `:disabled`
- Example: `<input type="text" class="input" placeholder="...">`

### Checkbox
- Base: `.input-checkbox` wrapper with `input[type="checkbox"]`
- Structure: `<label class="input-checkbox"><input type="checkbox"><span class="input-checkbox-box"><span class="input-checkbox-checkmark"></span></span><span class="input-checkbox-label">Label</span></label>`
- Sizes: `.input-checkbox-small`, `.input-checkbox-xsmall` (default: 32px)
- States: Default, Hover (blue border), Checked (blue background + white checkmark), Disabled
- Example: `<label class="input-checkbox"><input type="checkbox" checked><span class="input-checkbox-box"><span class="input-checkbox-checkmark"></span></span><span class="input-checkbox-label">Checkbox Label</span></label>`

### Radio
- Base: `.input-radio` wrapper with `input[type="radio"]`
- Structure: `<label class="input-radio"><input type="radio" name="group"><span class="input-radio-circle"><span class="input-radio-dot"></span></span><span class="input-radio-label">Label</span></label>`
- Sizes: `.input-radio-small`, `.input-radio-xsmall` (default: 32px)
- States: Default, Hover (blue border), Checked (blue filled circle + white inner dot), Disabled
- Example: `<label class="input-radio"><input type="radio" name="option" checked><span class="input-radio-circle"><span class="input-radio-dot"></span></span><span class="input-radio-label">Radio Label</span></label>`

### Tag
- Base: `.tag` or `.tag.default`
- Variants: `.tag.secondary`, `.tag.outline`, `.tag.success`, `.tag.error`, `.tag.warning`, `.tag.info`
- States: `.hover`, `.focus`, `.active`
- Example: `<div class="tag success">Completed</div>`

### Table
- Structure: Wrap `<table class="table">` in `<div class="table-scroll">` for horizontal scrolling on narrow viewports
- Classes: `.table-scroll` (border, radius, overflow-x), `.table` (cell typography, row borders, editorial styling)
- Example: `<div class="table-scroll"><table class="table"><thead><tr><th>…</th></tr></thead><tbody><tr><td>…</td></tr></tbody></table></div>`
- CSS-only (no JS)

### Icon
- Base: `.icon`
- Icon names: `.icon-[name]` (e.g., `.icon-jobs`, `.icon-academy`)
- Sizes: `.icon-small` (16px), `.icon-medium` (24px, default), `.icon-large` (32px), `.icon-xlarge` (48px)
- Colors: `.icon-primary`, `.icon-secondary`, `.icon-success`, `.icon-danger`, `.icon-warning`
- Example: `<span class="icon icon-jobs icon-large icon-primary"></span>`

### Dropdown (JS Component)
- Import: `import Dropdown from '/design-system/components/dropdown/dropdown.js'`
- Initialize: `new Dropdown(selector, { items, placeholder, onSelect, ... })`
- Methods: `getValue()`, `setValue(value)`, `open()`, `close()`, `toggleOpen()`, `destroy()`

### Horizontal Cards (JS Component)
- Import: `import HorizontalCards from '/design-system/components/horizontal-cards/horizontal-cards.js'`
- Initialize: `new HorizontalCards(selector, { cards, showNavigation, onCardChange, ... })`
- Cards: Array of objects with `title` (HTML), `description` (HTML), `actionHtml`, or `actionPlaceholder`
- Methods: `getCurrentIndex()`, `getCurrentCard()`, `scrollToNext()`, `scrollToPrevious()`, `scrollToIndex(index)`, `destroy()`
- Features: Horizontal scrolling, card centering, navigation buttons, keyboard/touch support

### Numeric Slider (JS Component)
- Import: `import NumericSlider from '/design-system/components/numeric-slider/numeric-slider.js'`
- Initialize: `new NumericSlider(selector, { type, min, max, value, showInputs, theme, ... })`
- Types: `'single'` (one handle) or `'range'` (two handles)
- Methods: `getValue()`, `setValue(value)`, `setDisabled(disabled)`, `destroy()`
- Themes: `'default'` (neutral track, primary filled/handles) or `'primary'` (all primary)
- Can override individual parts: `trackTheme`, `filledTheme`, `handleTheme`

### Split Panel (JS Component)
- Import: `import SplitPanel from '/design-system/components/split-panel/split-panel.js'`
- Initialize: `new SplitPanel(selector, { orientation, initialSplit, minLeft, minRight, disabled, onChange })`
- Orientation: `'horizontal'` (left/right) or `'vertical'` (top/bottom)
- Methods: `getSplit()`, `setSplit(percent)`, `getLeftPanel()`, `getRightPanel()`, `setDisabled(disabled)`, `destroy()`
- Features: Resizable panels with draggable divider, mouse/touch/keyboard support, visual feedback on focus/drag

### Modal (JS Component)
- Import: `import Modal from '/design-system/components/modal/modal.js'`
- Initialize: `new Modal({ size, title, content, footerButtons, ... })`
- Sizes: `'small'` (400px), `'medium'` (600px), `'large'` (900px), `'xlarge'` (1200px)
- Content: HTML string, DOM element, CSS selector (e.g., `'#my-content'`), or template content
- Methods: `open()`, `close()`, `updateContent(content)`, `updateTitle(title)`, `destroy()`
- Footer buttons: Array of `{label, type, onClick}` configs
- Help Modal: `Modal.createHelpModal({ title, content, ... })` - Convenience method for help/documentation modals (xlarge size, footer with close button, styled for help content)

## Best Practices

1. Always use semantic color tokens (e.g., `--Colors-Text-Body-Default`) over base scales
2. Components support dark mode automatically via `prefers-color-scheme`
3. Use spacing tokens for consistent padding/margins
4. Include component CSS files after foundation CSS files
5. Icons use `mask-image` with `background-color` for color control

## File Structure

```
design-system/
├── colors/colors.css
├── spacing/spacing.css
├── typography/typography.css
└── components/
    ├── button/button.css
    ├── boxes/boxes.css
    ├── dropdown/dropdown.css + dropdown.js
    ├── horizontal-cards/horizontal-cards.css + horizontal-cards.js
    ├── icons/icons.css
    ├── input/input.css
    ├── modal/modal.css + modal.js
    ├── numeric-slider/numeric-slider.css + numeric-slider.js
    ├── split-panel/split-panel.css + split-panel.js
    ├── table/table.css
    └── tags/tags.css
```