@moderne/neo-design

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

🚀 Quick Start

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:

# 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

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