npm package: @nxtg/design-tokens
Description: NXTG.AI Design System — canonical theme tokens for all web properties
Author: NXTG.AI
Latest version: 1.0.0

# @nxtg/design-tokens

Canonical design system tokens for all NXTG.AI web properties. One import, brand-correct by default.

## The Problem

Every NXTG.AI property (nxtg.ai, faultline.nxtg.ai, Forge UI) maintains its own theme CSS. They drift. Colors don't match. Light mode looks different everywhere. Dark mode contrast varies. Teams interpret "use brand orange" differently.

## The Solution

```css
/* Your globals.css — one line */
@import "@nxtg/design-tokens/globals.css";
```

Done. Both themes work. Brand orange is correct. Typography scale is consistent. Spacing is on the 4px grid.

## What's Included

| File | What It Does |
|------|-------------|
| `globals.css` | One-import theme (colors + typography + spacing + base resets) |
| `tokens/colors.css` | Light mode ("Polished Steel") + Dark mode ("Industrial Void") |
| `tokens/typography.css` | Inter + JetBrains Mono, 1.25 Major Third scale |
| `tokens/spacing.css` | 4px grid system, container breakpoints |
| `tailwind.preset.ts` | Tailwind CSS v4 preset mapping all tokens to utilities |

## Quick Start

### Install

```bash
npm install github:nxtg-ai/nxtg-design-tokens
```

### CSS Import (simplest)

```css
/* In your app's globals.css */
@import "@nxtg/design-tokens/globals.css";

/* Your project-specific variables go here (don't duplicate token values) */
:root {
  --sidebar-width: 280px;
}
```

### Tailwind Preset (if using Tailwind)

```ts
// tailwind.config.ts
import nxtgPreset from '@nxtg/design-tokens/tailwind.preset'

export default {
  presets: [nxtgPreset],
  // your project config...
}
```

### Using Tokens in Components

```tsx
// Correct — uses semantic tokens
<div className="bg-background text-foreground border-border" />
<button className="bg-accent text-accent-foreground" />

// Wrong — raw primitives that won't respect theme switching
<div className="bg-black text-white border-gray-700" />
```

## Theme Personalities

### Light Mode: "Polished Steel"

Cool metallic grays with subtle blue undertone. Think brushed aluminum MacBooks, Bang & Olufsen speakers. Background: `#ebeef1`. Brand orange as a glowing indicator light on premium hardware.

### Dark Mode: "Industrial Void"

True black (`#000000`), not dark gray. Content emerges from darkness with clear hierarchy. Brand orange as a beacon of interaction. Designed for focus and late-night sessions.

## Brand Accent

**Orange** — `hsl(24, 100%, 50%)` in light, `hsl(25, 95%, 53%)` in dark. This is non-negotiable across all NXTG.AI properties.

## Rules

1. Do NOT override token values in consuming projects
2. If you need a project-specific variable, use a different name
3. The token package is the source of truth — your globals.css consumes it
4. Both themes must work — never build dark-only or light-only

## Architecture

This package is `AWP.Dev.DesignGovernance.Web` — the first ActionWorkflow Pack in the NXTG.AI portfolio. It enforces the Design Constitution (`standards/design-constitution.md`) at the code level.

**Litmus test**: Precision Industrial Calm — engineered intelligence, earned trust, zero visual noise.

## License

MIT