# Nucleus CSS

> A polished, accessible, zero-build CSS framework. Prefix: `n-`. 697 classes, 76 tokens. No runtime JS, no build step required.

Every class begins with the `n-` prefix. Only classes listed in the
manifest exist — do NOT invent classes, and do NOT mix in Tailwind or Bootstrap
class names (no `flex`, `mt-4`, `btn-primary`, `col-md-6`; use `n-flex`,
`n-mt-4`, `n-btn n-btn-primary`, `n-col-md-6`).

## Install

```bash
npm install @navitallabs/nucleus-css
```

```js
import "@navitallabs/nucleus-css";               // full framework
```

```css
@import "@navitallabs/nucleus-css";              /* or a module below */
```

CDN: `https://cdn.jsdelivr.net/npm/@navitallabs/nucleus-css@2.0.0/dist/nucleus.min.css`

## Configure an AI coding assistant

`npx @navitallabs/nucleus-css ai-setup <tool>` writes this context plus the tool's
native project rule. Supported tools: `claude`, `codex`, `cursor`, and
`antigravity`.

## Modular imports

- `@navitallabs/nucleus-css/reset` — tokens, reset, global a11y
- `@navitallabs/nucleus-css/utilities` — layout + utility classes
- `@navitallabs/nucleus-css/components` — buttons, cards, forms, etc.
- `@navitallabs/nucleus-css/themes` — themes + dark mode
(Import `reset` first, or just import the full bundle.)

## Naming conventions

- Component: `n-<name>` (e.g. `n-btn`, `n-card`, `n-alert`).
- Variant: `n-<name>-<variant>` (e.g. `n-btn-primary`, `n-alert-success`).
- Size: `n-<name>-sm` / `n-<name>-lg`.
- Responsive utility: `n-<util>-<bp>-*` where bp ∈ {sm, md, lg, xl, xxl} (e.g. `n-col-md-6`, `n-d-lg-flex`).
- Prefer canonical classes. Deprecated aliases remain valid but the validator reports their replacement.

## State convention

1. Use native state and accurate ARIA first (`disabled`, `aria-current="page"`, `aria-selected="true"`, `aria-expanded="true"`).
2. Use `data-state` for framework-specific state when ARIA would be inaccurate.
3. Use namespaced visual hooks such as `n-is-active`, `n-is-loading`, and `n-is-disabled`.
Do not add unprefixed `.active` to new markup.

## Breakpoints (min-width, mobile-first)

- sm: 576px
- md: 768px
- lg: 992px
- xl: 1200px
- xxl: 1600px

## Core layout

- `n-container` / `n-container-fluid`
- `n-row` + `n-col-1..12` (and `n-col-{sm,md,lg,xl}-1..12`)
- `n-auto-grid`, `n-grid-auto-fit`, `n-sidebar-layout`, `n-cluster`, `n-split`, `n-stack`, `n-switcher`, `n-cover`, `n-reel`, `n-frame`, `n-section`, `n-content`

## Core utilities

- spacing: n-m-{0..5}, n-mt/mb/ml/mr/mx/my-{0..5}, n-p-{0..5}, n-pt/pb/pl/pr/px/py-{0..5}
- flex: n-flex, n-flex-col, n-items-center, n-justify-between, n-gap-{0..5}
- text: n-text-{xs..4xl}, n-text-center, n-font-{light..bold}, n-text-{primary,muted,...}
- color bg: n-bg-{primary,secondary,success,danger,warning,info,light,dark,white,muted}
- sizing: n-w-full, n-max-w-{sm..2xl}, n-h-screen, n-min-h-screen
- border/radius: n-border, n-rounded, n-rounded-{sm,lg,xl,full}, n-shadow-{sm..xl}
- display: n-d-{none,block,grid,...} and responsive n-d-{sm,md,lg}-*; use canonical n-flex for flex containers

## Spacing scale (not Tailwind-compatible)

- 0: 0
- 1: 0.25rem
- 2: 0.5rem
- 3: 1rem
- 4: 1.5rem
- 5: 3rem
Never infer Nucleus spacing values from Tailwind. For example, `n-p-4` is 1.5rem.

## Components

n-container, n-row, n-auto-grid, n-sidebar-layout, n-cluster, n-split, n-stack, n-btn, n-button-group, n-card, n-input, n-select, n-textarea, n-checkbox, n-switch, n-input-group, n-fieldset, n-navbar, n-breadcrumb, n-pagination, n-tabs, n-alert, n-badge, n-callout, n-toast, n-progress, n-spinner, n-skeleton, n-dialog, n-drawer, n-accordion, n-dropdown, n-tooltip, n-table, n-list-group, n-stat, n-avatar, n-chip, n-empty-state, n-prose, n-code-block, n-blockquote, n-surface, n-icon-tile, n-status, n-meter, n-gauge, n-segmented, n-stat-grid, n-banner, n-dock, n-cookie-bar, n-combobox, n-timeline, n-plan, n-checklist, n-table-stack, n-search-field, n-footer, n-signal-list

## Themes & modes

- Themes (on any element via `data-theme`): ocean, forest, rose, amber, mono
- Density (`data-density`): compact, spacious
- Dark mode: automatic (`@media (prefers-color-scheme: dark)`) or manual class `n-dark-mode`
- Customize via CSS custom properties (`--n-*`), e.g. `--n-primary`, `--n-radius`, `--n-font-sans`.

## Common mistakes to avoid

- Inventing classes not in the manifest (validate with `npx @navitallabs/nucleus-css validate ./src`).
- Using deprecated aliases when a canonical class is available (the validator warns and suggests a replacement).
- Using Tailwind/Bootstrap names instead of the `n-` equivalents.
- Using the `open` attribute on `n-dialog` — open it with `dialog.showModal()`.
- Forgetting a `<label>` for `n-input`/`n-select`/`n-textarea`.

## More detail (local files)

- CLASS_REFERENCE.md — every class with a description
- COMPONENT_REFERENCE.md — components with HTML examples
- llms-full.txt — complete plain-text reference
- dist/nucleus.manifest.json — machine-readable manifest
- AI_USAGE.md — how to prompt AI tools to use Nucleus
- MANIFEST.md — manifest schema and structured CLI commands