# @moderne/neo-design

**Internal Moderne package** - Design system build tools for processing design tokens into multiple output formats (CSS, JavaScript, JSON).

## 🚀 Quick Start

```bash
npm install @moderneinc/neo-design
```

## 📦 What's Included

- **Design Tokens**: W3C DTCG format token files in `src/tokens/`
  - `primitive/` — color, spacing, border-radius, shadow, typography, breakpoints
  - `semantic/` — semantic colors, semantic typography (aliases into primitives)
- **Internal Plugin System**: CSS Variables, JS Export, and DTS Export plugins (build-time only)
- **DTCG Reader**: Reads W3C Design Tokens Community Group format into plugin-compatible structures
- **Pure JavaScript**: Simplified architecture, no TypeScript complexity
- **Multiple Output Formats**: CSS custom properties, JavaScript exports, and TypeScript declarations

## 🎨 Generated Outputs

The build process generates design token files:

```bash
# After running npm run build, generated files include:
dist/
├── colors.css              # Primitive color CSS custom properties
├── colors.json             # Primitive color tokens (JSON)
├── colors.js               # Primitive color tokens (JS)
├── semantic-colors.css     # Semantic/theme color CSS custom properties
├── semantic-colors.json    # Semantic color tokens (JSON)
├── semantic-colors.js      # Semantic color tokens (JS)
├── typography.css          # Typography CSS custom properties
├── typography.json         # Typography tokens (JSON)
├── typography.js           # Typography tokens (JS)
├── breakpoints.js          # Breakpoint tokens (JS)
├── index.js                # Main CommonJS bundle
└── index.esm.js            # Main ESM bundle
```

## 🔧 Internal Build System

The package includes an internal plugin system used during the build process:

**Build-time Plugins:**

- **CSS Variables Plugin**: Generates CSS custom properties from design tokens
- **JS Export Plugin**: Creates JavaScript module exports from processed tokens
- **JSON Export Plugin**: Generates JSON files with processed design tokens

These plugins are configured in `neo.config.js` and executed by `scripts/build-production.js` during `npm run build`. They read W3C DTCG format token files via the DTCG reader and are not exposed as public exports.

## 🏗️ Architecture & Build Process

```mermaid
graph TB
    F[Figma API] --> S[fetch-figma-variables.js]
    S --> A[DTCG Token Files<br/>src/tokens/*.tokens.json]

    A --> B[npm run build<br/>scripts/build-production.js]

    B --> C[Rollup Bundle Build<br/>rollup -c]
    C --> D[Generated Bundles<br/>dist/]
    D --> E[index.js<br/>CommonJS Bundle]
    D --> Esm[index.esm.js<br/>ES Module Bundle]

    B --> G[Token Contract Processing<br/>neo.config.js]
    G --> R[DTCG Reader<br/>dtcg-reader.js]
    R --> G1[Colors]
    R --> G2[Semantic Colors]
    R --> G3[Typography]
    R --> G4[Shadows + Spacing + ...]

    G1 --> H[CSS Variables Plugin]
    G1 --> I[JS Export Plugin]
    G1 --> J[DTS Export Plugin]

    H --> K[Generated Artifacts<br/>dist/]
    I --> K
    J --> K
    G2 --> K
    G3 --> K
    G4 --> K

    K --> L[Ready for npm publish]

    style F fill:#fff3e0
    style A fill:#e1f5fe
    style K fill:#f3e5f5
    style L fill:#e8f5e8
```

## 🔧 Development

### Scripts

- `npm run build` - Complete build pipeline with plugin execution
- `npm run dev` - Watch mode development build with Rollup
- `npm run clean` - Remove dist directory
- `npm run storybook` - Preview tokens in Storybook (port 6006)
- `npm run test` - Run Vitest test suite
- `npm run lint` - Lint source code with Biome
- `npm run format` - Format code with Biome
- `npm run knip` - Check for unused dependencies and exports

## 📖 Documentation

- View token documentation in Storybook: `npm run storybook`
- See `stories/` for color and typography showcases
- Check `dist/` for built artifacts after running `npm run build`

---

**Package**: `@moderne/neo-design` (Private - Internal Moderne use only)
**Source**: Figma file `fQTkGSFbYyE7LiHuQJsENC`
**Architecture**: Pure JavaScript ES6 modules