nice-styles

A type-safe design system with CSS custom properties and TypeScript tokens.

Installation

npm install nice-styles

Quick Start

CSS

Import all CSS variables:

@import 'nice-styles/variables.css';

.card {
  padding: var(--gap-base);
  border-radius: var(--border-radius-base);
  color: var(--foreground-color-base);
}

Or import individual token groups:

@import 'nice-styles/css/fontSize.css';
@import 'nice-styles/css/gap.css';

For backward compatibility with deprecated variables:

@import 'nice-styles/deprecated.css';

TypeScript/JavaScript

Option 1: Import from main package (recommended)

import { fontSize, foregroundColor, gap } from 'nice-styles'

console.log(fontSize.base)           // "16px"
console.log(foregroundColor.link)    // "hsla(202, 100%, 50%, 1)"
console.log(gap.large)                // "32px"

Option 2: Import from specific files

// Import tokens
import { fontSize } from 'nice-styles/tokens.js'

// Import constants
import { FONT_SIZE_BASE } from 'nice-styles/constants.js'

Architecture

Data Structures

nice-styles provides design tokens in three complementary formats:

1. Constants (SCREAMING_SNAKE_CASE)

Raw constant values exported individually:

import { FONT_SIZE_BASE, FOREGROUND_COLOR_LINK } from 'nice-styles'

console.log(FONT_SIZE_BASE)         // "16px"
console.log(FOREGROUND_COLOR_LINK)  // "hsla(202, 100%, 50%, 1)"

Use when: You need direct access to individual constant values.

2. Tokens (camelCase objects)

Organized token objects with semantic keys:

import { fontSize, foregroundColor } from 'nice-styles'

console.log(fontSize.base)          // "16px"
console.log(fontSize.large)         // "20px"
console.log(foregroundColor.link)   // "hsla(202, 100%, 50%, 1)"
console.log(foregroundColor.error)  // "hsla(10, 92%, 63%, 1)"

Use when: You want semantic organization and better autocomplete.

3. CSS Custom Properties (kebab-case)

CSS variables for runtime styling:

:root {
  --font-size-base: "16px";
  --font-size-large: "20px";
  --foreground-color-link: "hsla(202, 100%, 50%, 1)";
  --foreground-color-error: "hsla(10, 92%, 63%, 1)";
}

Use when: You need runtime CSS theming and custom properties.

How It Works

┌─────────────────────┐
│  src/tokens.json    │  ← Central token definitions
│  (Source of truth)  │
└──────────┬──────────┘
           │
           ├────────────────────────┬──────────────────────┐
           ↓                        ↓                      ↓
┌──────────────────────┐  ┌──────────────────┐  ┌─────────────────┐
│ scripts/generateCss  │  │scripts/generate  │  │ src/services/   │
│                      │  │     Types        │  │ *.ts files      │
└──────────┬───────────┘  └──────────┬───────┘  └────────┬────────┘
           │                         │                   │
           ↓                         ↓                   │
    ┌──────────────┐         ┌──────────────┐           │
    │variables.css │         │dist/types.d.ts│           │
    │dist/css/*.css│         └──────────────┘           │
    └──────────────┘                ↑                    │
                             (bypasses tsc)              ↓
                                                  ┌─────────────┐
                                                  │ TypeScript  │
                                                  │  Compiler   │
                                                  │ (excludes   │
                                                  │ utilities)  │
                                                  └──────┬──────┘
                                                         │
                                                         ↓
                                                  ┌─────────────┐
                                                  │  dist/      │
                                                  │ services/   │
                                                  │  *.js       │
                                                  │  *.d.ts     │
                                                  └─────────────┘

Package Exports

The dist/ directory contains all compiled outputs consumed by users:

JavaScript/TypeScript Files

• dist/index.js + dist/index.d.ts

  • Main entry point
  • Exports all constants, tokens, and types
  • Used when: import { fontSize } from 'nice-styles'

• dist/constants.js + dist/constants.d.ts

  • All constant values (SCREAMING_SNAKE_CASE)
  • Compiled from src/constants.ts

• dist/tokens.js + dist/tokens.d.ts

  • All token objects (camelCase)
  • Generated from constants.ts, compiled by TypeScript

• dist/types.d.ts

  • TypeScript type definitions for token keys
  • Auto-generated from tokens.json (bypasses TypeScript compiler)
  • Exports: AnimationDurationType, FontSizeType, ForegroundColorType, etc.
  • Each type is a union of valid keys for that token group

CSS Files

• variables.css (root level)

  • All CSS custom properties in one file
  • Used when: @import 'nice-styles/variables.css'

• dist/css/*.css (individual token files)

  • animationDuration.css
  • fontSize.css
  • foregroundColor.css
  • gap.css
  • ...and 11 more
  • Used when: @import 'nice-styles/dist/css/fontSize.css'

Available Tokens

| Token | Keys | Example | |-------|------|---------| | animationDuration | base, slow | "300ms", "600ms" | | animationEasing | base | "ease-in-out" | | backgroundColor | base, alternate | "hsla(0, 100%, 100%, 1)" | | borderColor | base, dark, darker | "hsla(240, 9%, 91%, 1)" | | borderRadius | smaller, small, base, large, larger | "2px" to "32px" | | borderWidth | base, large | "1.5px", "2px" | | boxShadow | downBase, downLarge, upBase, upLarge | Shadow values | | cellHeight | smaller, small, base, large, larger | "24px" to "72px" | | foregroundColor | lighter, light, medium, dark, base, link, success, warning, error | Color values | | fontFamily | base, code, heading | Font stacks | | fontSize | smaller, small, base, large, larger | "12px" to "24px" | | fontWeight | light, base, medium, semibold, bold, extrabold, black | "300" to "900" | | gap | smaller, small, base, large, larger | "4px" to "48px" | | iconStrokeWidth | base, large | "1.5px", "2px" | | lineHeight | condensed, base, expanded | "1.25" to "1.75" |

Usage Examples

TypeScript Component

import { fontSize, foregroundColor, gap } from 'nice-styles'

const styles = {
  fontSize: fontSize.base,
  color: foregroundColor.base,
  padding: gap.base,
  linkColor: foregroundColor.link,
  errorColor: foregroundColor.error,
}

CSS Styling

.button {
  font-size: var(--font-size-base);
  padding: var(--gap-small) var(--gap-base);
  border-radius: var(--border-radius-base);
  background: var(--background-color-base);
  color: var(--foreground-color-base);
  font-weight: var(--font-weight-medium);
}

.button-primary {
  background: var(--foreground-color-link);
  color: var(--background-color-base);
}

.alert-error {
  color: var(--foreground-color-error);
  border: var(--border-width-base) solid var(--foreground-color-error);
  border-radius: var(--border-radius-small);
  padding: var(--gap-small);
}

Dynamic Token Function

import { getToken } from 'nice-styles'

// Get token with CSS variable and raw value
const fontSize = getToken('fontSize')
console.log(fontSize.key)   // "--font-size-base"
console.log(fontSize.var)   // "var(--font-size-base)"
console.log(fontSize.value) // "16px"

// Get specific token item
const large = getToken('fontSize', 'large')
console.log(large.value) // "24px"

TypeScript Types

Each token group has a corresponding type that represents all valid keys:

import type { FontSizeType, ForegroundColorType, GapType } from 'nice-styles'

// Type-safe token key usage
function setFontSize(size: FontSizeType) {
  return fontSize[size]
}

setFontSize('base')    // ✓ Valid
setFontSize('large')   // ✓ Valid
setFontSize('huge')    // ✗ Type error

// Use in component props
interface ButtonProps {
  size?: FontSizeType
  color?: ForegroundColorType
  spacing?: GapType
}

const Button = ({ size = 'base', color = 'base', spacing = 'base' }: ButtonProps) => ({
  fontSize: fontSize[size],
  color: foregroundColor[color],
  padding: gap[spacing],
})

Available types:

• AnimationDurationType - "base" | "slow"
• AnimationEasingType - "base"
• BackgroundColorType - "base" | "alternate"
• BorderColorType - "base" | "heavy" | "heavier"
• BorderRadiusType - "smaller" | "small" | "base" | "large" | "larger"
• BorderWidthType - "base" | "large"
• BoxShadowType - "downBase" | "downLarge" | "upBase" | "upLarge"
• CellHeightType - "smaller" | "small" | "base" | "large" | "larger"
• ForegroundColorType - "lighter" | "light" | "medium" | "heavy" | "base" | "disabled" | "link" | "success" | "warning" | "error"
• FontFamilyType - "base" | "code" | "heading"
• FontSizeType - "smaller" | "small" | "base" | "large" | "larger"
• FontWeightType - "light" | "base" | "medium" | "semibold" | "bold" | "extrabold" | "black"
• GapType - "smaller" | "small" | "base" | "large" | "larger"
• LineHeightType - "condensed" | "base" | "expanded"

Development

Adding New Tokens

1. Edit src/constants.ts and add your constants with a // Token: comment:

// Token: BUTTON_SIZE
export const BUTTON_SIZE_SMALL = "32px"
export const BUTTON_SIZE_MEDIUM = "40px"
export const BUTTON_SIZE_LARGE = "48px"

2. Run the token generator:

npm run build:tokens

This automatically generates:

• src/tokens.ts with buttonSize token object
• src/types.ts with ButtonSizeType = "small" | "medium" | "large"
• CSS variables in variables.css
• Individual dist/css/buttonSize.css file

3. Compile TypeScript:

npm run build:ts

Or run both with:

npm run build

Build Process

# Generate tokens from constants
npm run build:tokens

# Compile TypeScript
npm run build:ts

# Run both
npm run build

# Watch mode
npm run watch

Migration from v3.x

Version 4.0.0 removes all deprecated numbered token variants (e.g., FONT_SIZE_1, BORDER_RADIUS_2).

Before (v3.x):

import { FONT_SIZE_1, borderRadius1 } from 'nice-styles'

After (v4.x):

import { FONT_SIZE_BASE, borderRadius } from 'nice-styles'
console.log(borderRadius.base)

All numbered variants have been removed. Use semantic names instead:

• _1 → .base or .small
• _2 → .large or .alternate
• etc.

License

MIT © Mohammed Ibrahim