@inversestudio/design-tokens

v1.2.1

Published

3 months ago

IDS Design System tokens - compiled from Tokens Studio format

0High
0Medium
0Low

michael-inv

vedran-inverse

nogaenbar

design-tokens design-system style-dictionary tokens-studio css-variables scss storybook

IDS Design Tokens

Design tokens for the IDS (Inverse Design System), built with Style Dictionary and compatible with Tokens Studio.

Installation

npm install @ids/design-tokens

Usage

CSS Custom Properties

/* 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';

.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

// 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

// 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

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

// 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

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

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

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

React Theme Provider Example

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

# 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

npm install @storybook/addon-styling -D

Configure `.storybook/preview.js`

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

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

Edit token JSON files in /core/, /styles/, or /theme/
Run npm run build to regenerate outputs
Run npm test to validate
Commit changes

License

MIT