newtone-api

Core engine, component library, and configurator widget for the newtone color system ecosystem.

What is newtone-api?

newtone-api is the foundational repository containing:

1. Core Engine (newtone npm package) — Pure TypeScript color science engine

   • Color space conversions (sRGB, OKLAB, OKLCH)
   • WCAG contrast calculations
   • Gamut mapping
   • Dynamic range and desaturation curves
   • Hue grading

2. Component Library (@newtonedev/components npm package) — Cross-platform UI components

   • Button, Card, TextInput, Select, Toggle, Slider, HueSlider
   • Theme provider with light/dark modes
   • Design token generation

3. Configurator (@newtonedev/configurator npm package) — Visual palette builder widget

   • Embeddable color system editor
   • Real-time preview
   • Export to JSON, CSS, or NewtoneThemeConfig

Tech Stack

• Language: TypeScript (zero external dependencies in core engine)
• UI Framework: React + react-native-web (cross-platform components)
• Package Manager: npm workspaces
• Testing: Vitest + React Testing Library

Getting Started

# Install dependencies
npm install

# Run tests
npm test

# Build all packages
npm run build

Project Structure

src/
├── color-spaces/        # Color conversions (sRGB, OKLAB, OKLCH)
├── luminance/           # WCAG contrast calculations
├── gamut/               # Gamut mapping algorithms
├── engine/              # Core color generation pipeline
└── mcp/                 # Model Context Protocol server (planned)

packages/
├── components/          # @newtonedev/components
│   ├── src/
│   │   ├── theme/      # NewtoneProvider, theme context
│   │   ├── tokens/     # Design token computation
│   │   ├── Button/     # Component implementations
│   │   ├── Card/
│   │   └── ...
│   └── package.json
└── configurator/        # @newtonedev/configurator
    ├── src/
    │   ├── Configurator.tsx
    │   ├── panels/     # Global, palettes, canvas, preview, export
    │   └── state/      # useReducer state management
    └── package.json

Published Packages

All packages published to npm under the newtonedev organization:

npm install newtone                      # Core engine
npm install @newtonedev/components       # Component library
npm install @newtonedev/configurator     # Configurator widget

Current Version: 0.1.0

Documentation

• Feature Catalog — Complete feature inventory (18 features, 16 complete)
• Active Sprint — Current sprint tasks and priorities
• Product Spec — Original product specification

Related Projects

• newtone-web — Public-facing SaaS app (newtone.dev)
• newtone-admin — Admin backoffice for site theme control

Key Patterns

Zero Dependencies in Core Engine

The newtone package has zero external dependencies. All color space math is implemented from scratch in pure TypeScript.

Cross-Platform Components

Components use react-native-web for cross-platform compatibility:

• Button uses onPress (not onClick)
• TextInput uses onChangeText (not onChange)
• All components work on web and React Native

Self-Affecting Pattern

When the configurator is wrapped in a NewtoneProvider whose config is controlled by the configurator itself, the configurator's own UI updates in real-time as palettes change. Used in newtone-web editor and newtone-admin theme editor.

Building & Testing

# Run all tests
npm test

# Build all packages
npm run build

# Publish to npm (requires npm login as joshuaallenmx)
cd packages/components && npm publish
cd packages/configurator && npm publish
cd ../.. && npm publish

License

Private — All rights reserved