# nShift Design System

> A Vue 3 component library for nShift products. All components are built with Vue 3 (Composition API, `<script setup>`), PrimeVue 4, and Tailwind CSS 4. Design tokens are compiled from `design-tokens.json` into CSS custom properties and Tailwind utilities. Use this file as the entry point when building UI with nShift components.

## Stack

- **Framework:** Vue 3, `<script setup>`, TypeScript
- **Styling:** Tailwind CSS 4 (no config file — all inline via `@theme`), nShift design tokens
- **UI Library:** PrimeVue 4 with Aura theme preset
- **Router:** Vue Router 4 (web history)
- **Path alias:** `@` → `src/`
- **Dark mode:** toggled via `.dark` class on root

## Design Tokens

Token source: `design-tokens.json` (W3C format). Compiled to `src/tokens.css` on `npm run dev`. Never edit `tokens.css` directly.

**Naming convention:** Token path → CSS variable → Tailwind utility

| Token path | CSS variable | Tailwind example |
|---|---|---|
| `foundational.surface.container.low` | `--color-surface-container-low` | `bg-surface-container-low` |
| `foundational.onSurface.standard` | `--color-on-surface-standard` | `text-on-surface-standard` |
| `foundational.outline` | `--color-outline` | `border-outline` |
| `semantic.success.primary` | `--color-success-primary` | `bg-success-primary` |
| `semantic.error.primary` | `--color-error-primary` | `bg-error-primary` |
| `foundational.scrim.standard` | `--color-scrim-standard` | `bg-scrim-standard` |

**Rule:** Always prefer semantic tokens (e.g. `--color-success-primary`) over foundational primitives.

**Key token values:**
- Primary text: `--color-on-surface-standard` #191919
- Secondary text: `--color-on-surface-variant` #666465
- Default border: `--color-outline` #C2C2C2
- Subtle dividers: `--color-outline-lowest` #E9E9E9
- Page background: `--color-surface-standard` #FFFFFF
- Neutral action (buttons): `--color-neutral-core-primary` #2B2B2B
- Modal scrim: `--color-scrim-standard` rgba(0,0,0,0.32)

---

## Components

Components live in `src/components/`. Import them directly:

```vue
import NsButton from '@/components/NsButton.vue'
```

---

### NsButton

The primary action component. Use for any user-initiated action.

**Props:**
- `label` string — Button text (default: `'Label'`). Overridden by default slot.
- `variant` `'filled' | 'outlined' | 'ghost' | 'secret'` — Visual emphasis (default: `'filled'`). Use filled for primary, outlined for secondary, ghost for low-emphasis, secret for revealed-on-hover.
- `size` `'sm' | 'md'` — sm = 28px height, md = 32px height (default: `'md'`)
- `severity` `'neutral' | 'neutral-light' | 'information' | 'error'` — Color intent (default: `'neutral'`)
- `disabled` boolean (default: `false`)
- `loading` boolean — Shows spinner, disables interaction (default: `false`)

**Slots:** `default` (label), `left-icon`, `right-icon`

**Rules:**
- One filled button per section maximum
- Never use secret for critical or destructive actions

```vue
<NsButton label="Save" variant="filled" severity="neutral" />
<NsButton label="Cancel" variant="outlined" />
<NsButton variant="ghost" size="sm">
  <template #left-icon><img :src="icon" /></template>
  Delete
</NsButton>
```

---

### NsIconButton

Icon-only square button. Identical to NsButton in behaviour but renders no label.

**Props:**
- `variant` `'filled' | 'outlined' | 'ghost'` (default: `'filled'`)
- `size` `'xs' | 'standard'` — xs = 24×24px, standard = 32×32px (default: `'standard'`)
- `severity` `'neutral' | 'information' | 'error'` (default: `'neutral'`)
- `disabled` boolean (default: `false`)
- `active` boolean — Active/selected state for toolbar toggles (default: `false`)
- `ariaLabel` string — **Required** for accessibility

**Slots:** `default` — SVG icon (should be 20×20px)

```vue
<NsIconButton variant="ghost" ariaLabel="Delete row">
  <svg viewBox="0 0 24 24" fill="currentColor">...</svg>
</NsIconButton>
```

---

### NsCheckbox

Allows users to select one or multiple independent options.

**Props:**
- `modelValue` boolean (v-model, default: `false`)
- `variant` `'standard' | 'error' | 'disabled'` (default: `'standard'`)
- `size` `'standard' | 'small'` — standard = 24×24px, small = 20×20px (default: `'standard'`)
- `indeterminate` boolean — Shows dash for partially-selected groups (default: `false`)
- `label` string — Label beside checkbox (default: `''`)

```vue
<NsCheckbox v-model="checked" label="Accept terms" />
<NsCheckbox v-model="allSelected" :indeterminate="someSelected" />
```

---

### NsToggle

Binary on/off switch. Use when a setting applies immediately without a form submit.

**Props:**
- `modelValue` boolean (v-model, default: `false`)
- `label` string — Optional label to the right (default: `''`)
- `disabled` boolean (default: `false`)

```vue
<NsToggle v-model="enabled" label="Enable notifications" />
```

---

### NsInputField

Text input with floating label and optional helper text.

**Props:**
- `modelValue` string (v-model, default: `''`)
- `label` string — Floating label (doubles as placeholder when empty)
- `helperText` string — Helper or error message below the field
- `variant` `'standard' | 'error' | 'disabled'` (default: `'standard'`)
- `iconLeft` boolean — Show left icon slot (default: `false`)
- `iconRight` boolean — Show right icon slot (default: `false`)
- `rightButton` boolean — Attach button to right edge (default: `false`)

**Slots:** `icon-left`, `icon-right`, `right-button`

```vue
<NsInputField v-model="query" label="Search" helper-text="Enter at least 3 characters" />
```

---

### NsSelect

Floating-label dropdown. Supports single and multi-select with checkboxes.

**Props:**
- `label` string — Floating label text
- `options` `(string | { label: string; value: string|number })[]` — Options list (default: `[]`)
- `modelValue` `Array<string|number>` (v-model, default: `[]`)
- `variant` `'default' | 'error' | 'disabled'` (default: `'default'`)
- `checkboxes` boolean — Show checkboxes in dropdown for multi-select (default: `true`)
- `divider` boolean — Show divider line between label and dropdown (default: `true`)
- `helperText` string — Helper or error text below field

```vue
<NsSelect v-model="selected" label="Carrier" :options="['DHL', 'UPS', 'FedEx']" />
<NsSelect v-model="filters" label="Status" :options="statusOptions" :checkboxes="true" />
```

---

### NsRadioButton

Radio button for mutually exclusive single-option selection within a group.

**Props:**
- `modelValue` `string | number | boolean | null` (v-model, default: `null`)
- `value` `string | number | boolean` — **Required.** The value this radio represents
- `label` string — Label text (default: `''`)
- `size` `'standard' | 'small'` — standard = 24px circle, small = 20px circle (default: `'standard'`)
- `variant` `'default' | 'error' | 'disabled'` (default: `'default'`)
- `name` string — Groups radios for keyboard navigation (default: `'radio'`)

```vue
<NsRadioButton v-model="carrier" value="dhl" label="DHL" name="carrier" />
<NsRadioButton v-model="carrier" value="ups" label="UPS" name="carrier" />
```

---

### NsTab

Tab bar for switching between views or content sections.

**Props:**
- `items` `string[] | { label: string; icon?: string }[]` — Tab labels or objects (default: `['Tab 1','Tab 2','Tab 3']`)
- `modelValue` string (v-model) — Active tab label (defaults to first tab)
- `size` `'standard' | 'small'` (default: `'standard'`)
- `variant` `'tabs' | 'icons'` — Text tabs or icon-only tabs (default: `'tabs'`)

**Events:** `update:modelValue`

```vue
<NsTab v-model="activeTab" :items="['Overview', 'Details', 'History']" size="small" />
<div v-if="activeTab === 'Overview'">...</div>
```

---

### NsPagination

Standalone paginator — a sliding window of page numbers with first/last/prev/next arrows.

**Props:**
- `total` number — **Required.** Total number of pages
- `siblings` number — Pages shown on each side of current (default: `2`)
- `modelValue` number (v-model) — Current page (default: `1`)

```vue
<NsPagination v-model="page" :total="totalPages" />
```

---

### NsTag

Removable label chip for filters, applied tags, and multi-select values.

**Props:**
- `label` string — **Required.** Primary text
- `label2` string — Optional secondary label after a separator
- `variant` `'neutral' | 'inverse' | 'ghost' | 'disabled'` (default: `'neutral'`)

**Events:** `remove` — User clicks the × button

```vue
<NsTag label="Amsterdam" variant="neutral" @remove="removeTag('Amsterdam')" />
<NsTag label="Status" label2="In transit" variant="neutral" @remove="clearFilter('status')" />
```

---

### NsBadge

Compact status label. Use to convey status or category — not for interaction.

**Props:**
- `label` string — Badge text (default: `'Label'`)
- `severity` `'neutral' | 'success' | 'information' | 'attention' | 'warning' | 'inactive' | 'error' | 'flare'` (default: `'neutral'`)
- `filled` boolean — `true` = solid background, `false` = tinted container (default: `true`)

**Slots:** `#icon` (16×16 icon), `default` (overrides label)

```vue
<NsBadge label="Delivered" severity="success" />
<NsBadge label="Delayed" severity="warning" :filled="false" />
```

---

### NsCallout

Inline contextual banner with a left accent border. Use for persistent in-page feedback or important notices.

**Props:**
- `variant` `'neutral' | 'success' | 'information' | 'attention' | 'warning' | 'error' | 'flare' | 'inverse'` (default: `'neutral'`)
- `title` boolean — Show title line (default: `true`)
- `titleText` string — Bold title text (default: `'General update'`)
- `bodyText` string — Body text (default: placeholder)
- `icon` boolean — Show leading icon (default: `true`)

```vue
<NsCallout variant="error" title-text="Upload failed" body-text="The file exceeds the 10MB limit." />
<NsCallout variant="information" :title="false" body-text="Changes are saved automatically." />
```

---

### NsToast

Transient notification that auto-dismisses after 4 seconds. Use for confirmations and alerts — not for persistent messages (use NsCallout instead).

**Props:**
- `message` string — **Required.** The notification text
- `variant` `'neutral' | 'success' | 'information' | 'flare' | 'attention' | 'warning' | 'error' | 'inverse'` (default: `'neutral'`)
- `dismissable` boolean — Show × button (default: `true`)
- `reappear` boolean — Reappear after 5s for demo purposes (default: `true`)

**Events:** `dismiss`

```vue
<NsToast message="Changes saved successfully." variant="success" />
```

---

### NsAccordion

Collapsible section with a clickable header. Use to progressively disclose secondary content.

**Props:**
- `title` string — **Required.** Header label
- `modelValue` boolean (v-model) — Open/closed state (default: `false`)
- `size` `'default' | 'small'` (default: `'default'`)
- `disabled` boolean (default: `false`)

**Slots:** `default` (revealed content), `icon` (20×20 icon left of header)

```vue
<NsAccordion title="Shipping details" v-model="open">
  <div class="px-4 py-3">Content here</div>
</NsAccordion>
```

---

### NsTooltip

Small hover label for supplementary information. Use for icon buttons and truncated text — not for content the user must act on.

**Props:**
- `text` string — **Required.** Tooltip copy
- `position` `'top' | 'bottom'` (default: `'top'`)
- `alignment` `'left' | 'center' | 'right'` (default: `'center'`)
- `delay` number — ms before showing (default: `200`)

**Slots:** `default` — Trigger element

```vue
<NsTooltip text="Download CSV">
  <NsIconButton variant="ghost" ariaLabel="Download CSV">...</NsIconButton>
</NsTooltip>
```

---

### NsSpinner

Animated loading arc. Use while data is loading.

**Props:**
- `size` `'standard' | 'small'` — standard = 40×40px, small = 32×32px (default: `'standard'`)

```vue
<NsSpinner />
<NsSpinner size="small" />
```

---

### NsDropzone

File upload dropzone with drag-and-drop, uploading/success/error states, and file grid.

**Props:**
- `maxFileSize` number — Bytes (default: `10485760` = 10MB)
- `accept` string — MIME types or extensions (default: `'*'`)
- `multiple` boolean — Allow multiple files (default: `true`)
- `autoResolve` `'success' | 'error'` — Auto-resolve uploads to this state after 3s (default: `'success'`)
- `autoReset` boolean — Clear files after success (default: `true`)

**Events:**
- `upload` — `(files: File[], ids: string[])` — Fires when files are added. Call `setStatus(id, 'success'|'error')` on the component ref to resolve each file.
- `retry` — `({ id, file })` — User retries a failed file

```vue
<NsDropzone accept=".csv,.xlsx" @upload="handleUpload" />
```

---

### NsBreadcrumb

Navigation trail showing the user's location in the app hierarchy.

**Props:**
- `items` `BreadcrumbItem[]` — **Required.** Ordered array, root first. Last item = current page (plain text, no link).

**BreadcrumbItem:**
```ts
{ label?: string; icon?: string; ariaLabel?: string; to?: string; href?: string }
```

**Rules:**
- Last item never has `to` or `href`
- Items beyond 4 auto-collapse to `[first] › ··· › [n-1] › [current]`
- Icon-only home item must use `ariaLabel`

```vue
<NsBreadcrumb :items="[
  { icon: homeIcon, ariaLabel: 'Home', to: '/' },
  { label: 'Shipments', to: '/shipments' },
  { label: 'SHP-1042' },
]" />
```

---

### NsModal

Dialog modal with header, scrollable body slot, and cancel/confirm footer.

**Props:**
- `title` string — **Required.**
- `subtitle` string (default: `''`)
- `dismiss` boolean — Show × button (default: `true`)
- `cancelLabel` string (default: `'Cancel'`)
- `confirmLabel` string (default: `'Confirm'`)

**Model:** `v-model:visible` boolean

**Slots:** `#icon` (20×20), `default` (body), `#footer` (override entire footer)

**Events:** `cancel`, `confirm`

```vue
<NsModal v-model:visible="showModal" title="Delete shipment?" confirm-label="Delete">
  <p>This action cannot be undone.</p>
</NsModal>
```

---

### NsTable

Full-featured data table with search, filters, pagination, density, zebra, and bulk selection.

**Props:**
- `columns` `{ key: string; label: string }[]` — **Required.**
- `rows` `Record<string, unknown>[]` — **Required.**
- `topBarSearch` boolean — Search input above table (default: `true`)
- `searchPlaceholder` string (default: `'Search…'`)
- `filterBar` boolean — Filters button + panel (default: `false`)
- `filterDefinitions` `{ key, label, options: {value, label}[] }[]` — Column filter definitions (default: `[]`)
- `bulkActionBar` boolean — Checkbox column + selection bar (default: `false`)
- `tableFooter` boolean — Pagination footer (default: `true`)
- `pageSize` number (default: `10`)
- `pageSizeOptions` number[] — Shows rows-per-page selector when provided
- `zebra` boolean — Alternating row backgrounds (default: `false`)
- `density` `'compact' | 'regular' | 'relaxed'` — Row height 32/44/56px (default: `'regular'`)
- `loading` boolean — Shimmer skeleton rows (default: `false`)

**Slots:**
- `#cell-{columnKey}` (scope: `{ row, value }`) — Custom cell rendering
- `#bulk-actions` (scope: `{ selectedIndices, selectedRows }`) — Actions in bulk bar
- `#empty-action` — CTA inside the no-data empty state

```vue
<NsTable
  :columns="[{ key: 'id', label: 'ID' }, { key: 'status', label: 'Status' }]"
  :rows="shipments"
  :filter-bar="true"
  :filter-definitions="filterDefs"
  :bulk-action-bar="true"
  density="compact"
>
  <template #cell-status="{ value }">
    <NsBadge :label="value" severity="success" />
  </template>
  <template #bulk-actions="{ selectedRows }">
    <NsButton label="Export" variant="outlined" size="sm" />
  </template>
</NsTable>
```

---

### NsSidemenu

Fixed-width side panel with optional title bar and selectable items. Use for navigation or filter panels.

**Props:**
- `items` `SideMenuItem[]` — **Required.** `{ label, value, icon?, additionalText?, children? }`
- `modelValue` `string | number | null` (v-model) — Selected item value (default: `null`)
- `title` string — Title bar text (default: `'Title'`)
- `showTitleBar` boolean (default: `true`)
- `initialExpanded` `(string|number)[]` — Values of initially expanded parent items (default: `[]`)

**Slots:** `title-extra` (right of title text), `default` (below item list)

**Events:** `update:modelValue`, `close`

**Rules:**
- Top-level icons: all-or-nothing (if any item has icon, all must)
- Children never have icons
- Width is always 296px

```vue
<NsSidemenu
  v-model="activeFilter"
  title="Filter shipments"
  :items="filterItems"
  :initial-expanded="['by-status']"
  @close="sidebarOpen = false"
/>
```

---

### NsTopBar

Primary nShift product navigation bar. Fixed at top, 56px tall.

**Props:**
- `productName` string (default: `'Product'`)
- `productIcon` string — Path to product SVG (rendered in dark badge)
- `userName` string — Shown in utility bar
- `userEmail` string — Triggers utility bar rendering when provided
- `items` `{ label: string; to?: string; href?: string }[]` — Nav links
- `activeItem` string — Label of active nav link
- `hideNav` boolean — Hide the nav links row
- `hideActions` boolean — Hide action icons (help, notifications, user)
- `showActionBar` boolean — Render action bar below nav (default: `false`)
- `pageTitle` string — Page title in action bar
- `breadcrumbs` `{ label, to?, href?, active? }[]` — Breadcrumb trail in action bar

**Slots:** `#right` (injected into topbar right side)

```vue
<NsTopBar
  product-name="Deliver"
  :product-icon="deliverIcon"
  :items="navItems"
  active-item="Shipments"
  user-name="Emil Larsén"
  user-email="emil@nshift.com"
/>
```

---

### NsPageFooter

nShift product page footer. Use at the bottom of every product page.

**Props:**
- `variant` `'light' | 'dark'` (default: `'light'`)
- `size` `'large' | 'x-small'` — x-small for app pages, large for landing/marketing (default: `'x-small'`)
- `copyright` string (default: `'Copyright © 2021-2026, nShift'`)
- `links` `{ label: string; href: string }[]` — Legal nav links (defaults to 4 standard nShift links)
- `showWebsiteLink` boolean — Show nShift website link in large variant (default: `false`)

```vue
<NsPageFooter />
<NsPageFooter variant="dark" size="large" :show-website-link="true" />
```

---

## Storybook routes

| Route | Component |
|---|---|
| `/storybook/atoms/button` | NsButton |
| `/storybook/atoms/icon-button` | NsIconButton |
| `/storybook/atoms/checkbox` | NsCheckbox |
| `/storybook/atoms/toggle` | NsToggle |
| `/storybook/atoms/input-field` | NsInputField |
| `/storybook/atoms/select` | NsSelect |
| `/storybook/atoms/radio-button` | NsRadioButton |
| `/storybook/atoms/tab` | NsTab |
| `/storybook/atoms/pagination` | NsPagination |
| `/storybook/atoms/tag` | NsTag |
| `/storybook/atoms/badge` | NsBadge |
| `/storybook/atoms/callout` | NsCallout |
| `/storybook/atoms/toast` | NsToast |
| `/storybook/atoms/accordion` | NsAccordion |
| `/storybook/atoms/tooltip` | NsTooltip |
| `/storybook/atoms/spinner` | NsSpinner |
| `/storybook/atoms/dropzone` | NsDropzone |
| `/storybook/atoms/breadcrumb` | NsBreadcrumb |
| `/storybook/molecules/modal` | NsModal |
| `/storybook/organisms/table` | NsTable |
| `/storybook/organisms/sidemenu` | NsSidemenu |
| `/storybook/organisms/topbar` | NsTopBar |
| `/storybook/organisms/page-footer` | NsPageFooter |
| `/storybook/fundamentals/colors` | Design tokens / color palette |
| `/storybook/fundamentals/logos` | nShift logo assets |