npm package: @michael-inverse/design-tokens
Description: IDS Design System tokens - compiled from Tokens Studio format
Author: Inverse Studio
Latest version: 1.0.0

# IDS Design Tokens

Design tokens for the IDS (Inverse Design System), built with [Style Dictionary](https://amzn.github.io/style-dictionary/) and compatible with [Tokens Studio](https://tokens.studio/).

## Installation

```bash
npm install @ids/design-tokens
```

## Usage

### CSS Custom Properties

```css
/* Import all tokens (light theme default) */
@import '@ids/design-tokens/css';

/* Or import specific theme */
@import '@ids/design-tokens/css/tokens.light.css';
@import '@ids/design-tokens/css/tokens.dark.css';
```

```css
.button {
  background-color: var(--ids-color-element-primary-default);
  color: var(--ids-color-element-primary-on-primary);
  padding: var(--ids-spacing-0-75x) var(--ids-spacing-1x);
  border-radius: var(--ids-border-radius-0-25x);
}

.button:hover {
  background-color: var(--ids-color-element-primary-hover);
}
```

### SCSS

```scss
// Import variables and mixins
@import '@ids/design-tokens/scss';

// Or import individual files
@import '@ids/design-tokens/scss/tokens';
@import '@ids/design-tokens/scss/mixins';

// Use variables directly
.button {
  background-color: $ids-color-element-primary-default;
  padding: $ids-spacing-0-75x $ids-spacing-1x;
}

// Or use utility mixins
.button {
  @include ids-color(background-color, 'element-primary-default');
  @include ids-spacing(padding, '1x');
  @include ids-radius('0-25x');
}

// Typography composite
.label {
  @include ids-typography('label-1x');
}
```

### JavaScript / TypeScript

```javascript
// ES Modules
import tokens from '@ids/design-tokens';
import { idsColorElementPrimaryDefault } from '@ids/design-tokens';

// CommonJS
const tokens = require('@ids/design-tokens');

// Access nested tokens
console.log(tokens.ids.color.element.primary.default);
// Output: '#4d5057'

// Or use flat exports
console.log(idsColorElementPrimaryDefault);
// Output: '#4d5057'
```

### TypeScript with Full Type Safety

```typescript
import tokens, { IDSTokens } from '@ids/design-tokens';

// Full autocomplete and type checking
const primaryColor: string = tokens.ids.color.element.primary.default;

// Theme-specific imports
import * as lightTokens from '@ids/design-tokens/dist/types/tokens.light';
```

### JSON

```javascript
// Flat structure
import tokens from '@ids/design-tokens/json';
// { "ids-color-element-primary-default": "#4d5057", ... }

// Nested structure
import tokens from '@ids/design-tokens/json/tokens.nested.json';
// { ids: { color: { element: { primary: { default: "#4d5057" } } } } }
```

## Theming

### CSS Theme Switching

```html
<!-- Light theme (default) -->
<body>
  <!-- Uses :root tokens -->
</body>

<!-- Dark theme -->
<body data-theme="dark">
  <!-- Uses [data-theme="dark"] tokens -->
</body>
```

```javascript
// Toggle theme
document.body.setAttribute('data-theme', 'dark');
```

### React Theme Provider Example

```tsx
import { createContext, useContext, useState } from 'react';

const ThemeContext = createContext({ theme: 'light', setTheme: () => {} });

export function ThemeProvider({ children }) {
  const [theme, setTheme] = useState('light');

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      <div data-theme={theme}>{children}</div>
    </ThemeContext.Provider>
  );
}

export const useTheme = () => useContext(ThemeContext);
```

## Token Structure

### Primitive Tokens (Core)

Located in `/core/` - Base values that should NOT be used directly in components.

- `ids.core.color.*` - Color palette (neutral, blue, red, green)
- `ids.core.sizing.*` - Base sizing unit (16px REM)
- `ids.core.font.*` - Font families, sizes, line heights
- `ids.core.borderRadius.*` - Base border radius
- `ids.core.borderWidth.*` - Border widths

### Semantic Tokens

Located in `/styles/` and `/theme/` - Meaningful tokens for component usage.

- `ids.color.element.*` - Interactive element colors (primary, secondary, disabled)
- `ids.color.border.*` - Border colors
- `ids.spacing.*` - Spacing scale (0.13x to 2.5x)
- `ids.dimension.*` - Element and icon dimensions
- `ids.borderRadius.*` - Semantic border radius
- `ids.border.*` - Composite border tokens
- `ids.typography.*` - Typography composites

## Development

### Build Tokens

```bash
# Install dependencies
npm install

# Build all outputs
npm run build

# Watch for changes
npm run build:watch

# Run tests
npm test
```

### Output Structure

```
dist/
├── css/
│   ├── tokens.css          # Default (light theme)
│   ├── tokens.light.css    # Light theme
│   ├── tokens.dark.css     # Dark theme
│   └── index.css           # All themes
├── scss/
│   ├── _tokens.scss        # Default variables
│   ├── _tokens.light.scss  # Light theme variables
│   ├── _mixins.scss        # Utility mixins
│   └── index.scss          # All imports
├── js/
│   ├── tokens.js           # CommonJS default
│   ├── tokens.light.js     # Light theme
│   └── index.js            # All exports
├── esm/
│   ├── tokens.js           # ES Modules default
│   ├── tokens.light.js     # Light theme
│   └── index.js            # All exports
├── json/
│   ├── tokens.json         # Flat structure
│   ├── tokens.nested.json  # Nested structure
│   └── tokens.light.json   # Light theme
└── types/
    ├── tokens.d.ts         # TypeScript definitions
    ├── tokens.light.d.ts   # Light theme types
    └── index.d.ts          # All exports
```

## Storybook Integration

### Install Addon

```bash
npm install @storybook/addon-styling -D
```

### Configure `.storybook/preview.js`

```javascript
import '@ids/design-tokens/css';

export const parameters = {
  backgrounds: {
    default: 'light',
    values: [
      { name: 'light', value: '#ffffff' },
      { name: 'dark', value: '#101114' },
    ],
  },
};

// Theme decorator
export const decorators = [
  (Story, context) => {
    const theme = context.globals.theme || 'light';
    return (
      <div data-theme={theme}>
        <Story />
      </div>
    );
  },
];

export const globalTypes = {
  theme: {
    name: 'Theme',
    description: 'Global theme for components',
    defaultValue: 'light',
    toolbar: {
      icon: 'circlehollow',
      items: ['light', 'dark'],
      showName: true,
    },
  },
};
```

## CI/CD Pipeline Integration

### GitHub Actions Example

```yaml
name: Build and Publish Tokens

on:
  push:
    branches: [main]
    paths:
      - 'core/**'
      - 'styles/**'
      - 'theme/**'
      - '$themes.json'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: npm ci

      - name: Build tokens
        run: npm run build

      - name: Run tests
        run: npm test

      - name: Publish to npm
        run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

## Token Naming Convention

Tokens follow a hierarchical naming pattern:

```
ids-{category}-{subcategory}-{variant}-{state}
```

Examples:
- `--ids-color-element-primary-default`
- `--ids-color-element-primary-hover`
- `--ids-spacing-1x`
- `--ids-border-radius-full`

## Contributing

1. Edit token JSON files in `/core/`, `/styles/`, or `/theme/`
2. Run `npm run build` to regenerate outputs
3. Run `npm test` to validate
4. Commit changes

## License

MIT