npm package: @lightberryltd/croma-tokens
Description: Croma design tokens for web
Author: David Kososhvili
Latest version: 0.1.1

# @lightberryltd/croma-tokens

Design tokens for the Croma design system, exported from Figma and packaged for JS, CSS and SCSS.

This README explains how a frontend developer should use the package.

---

## 1. Installation

```bash
npm install @lightberryltd/croma-tokens
```

You don’t need to build anything inside your app – the compiled assets live in `dist/`.

---

## 2. JS / TS usage

### Import tokens

```ts
import tokens from '@lightberryltd/croma-tokens';
// or
import { tokens } from '@lightberryltd/croma-tokens';
```

The shape is:

- `tokens.variables` – all tokens
  - key: Figma token name (e.g. `primaryPrimary500`)
  - value:
    - `type`: `"COLOR" | "FLOAT" | "STRING" | ...`
    - `values`: `{ Default?: string | number; Light?: string; Dark?: string; ... }`

Example:

```ts
const primary500 = tokens.variables.primaryPrimary500.values.Default; // "#0066ff"
// In CSS/SCSS this same token is exposed as `primary500`.
```

You also get a TypeScript type:

```ts
import type { Tokens } from '@lightberryltd/croma-tokens';

const themeFromTokens = (t: Tokens) => ({
  primary: t.variables.primaryPrimary500.values.Default,
});
```

Use JS/TS when you want to:

- Build theme objects for your UI library.
- Map these tokens into Tailwind, MUI, Chakra, etc.

---

## 3. CSS custom properties (light / dark)

File: `dist/tokens.css`

This file exposes CSS custom properties that work in any web stack.

### How the theme works

- `:root { ... }` → **light/default** values.
- `.dark { ... }` → overrides for tokens that have a **Dark** variant.

### Adding to your app

Global CSS import:

```css
@import '@lightberryltd/croma-tokens/dist/tokens.css';
```

Use variables in components:

```css
body {
  background-color: var(--background-default);
  color: var(--text-default);
}

.button-primary {
  background-color: var(--components-button-variant-primary-default);
  color: var(--components-button-variant-primary-text);
}
```

Enable dark mode by toggling the `dark` class:

```tsx
// React / Next.js example
<body className={isDark ? 'dark' : ''}>
  {children}
</body>
```

Any element inside `.dark` will automatically pick up the dark overrides.

---

## 4. SCSS usage

File: `dist/_design-tokens.scss`

This gives you SCSS variables that mirror the Figma tokens.

### Import in SCSS

```scss
@use '@lightberryltd/croma-tokens/dist/_design-tokens' as tokens;
```

### Naming convention

For each COLOR token:

- Base: Figma name in kebab-case  
  `primaryPrimary500` → `primary-primary500`
- Suffix:
  - `-light` → `Default`/`Light`
  - `-dark` → `Dark`

Examples:

- `tokens.$primary500-light`
- `tokens.$primary500-dark`
- `tokens.$background-default-light`
- `tokens.$background-default-dark`

### Example usage

```scss
@use '@lightberryltd/croma-tokens/dist/_design-tokens' as tokens;

.button-primary {
  background-color: tokens.$components-button-variant-primary-default-light;
  color: tokens.$components-button-variant-primary-text-light;
}

.app-dark {
  background-color: tokens.$background-default-dark;
}
```

Use SCSS when you want values resolved at build time and are compiling a CSS bundle.

---

## 5. What is exposed by the package

You can rely on these entry points:

- `@lightberryltd/croma-tokens`
  - default export: token JSON object
  - named export: `tokens`
- `@lightberryltd/croma-tokens/dist/tokens.css`
  - CSS custom properties (`:root` + `.dark`)
- `@lightberryltd/croma-tokens/dist/_design-tokens.scss`
  - SCSS variables
- `@lightberryltd/croma-tokens/dist/tokens.json`
  - raw JSON, if you prefer to load it yourself

In a typical app you will use **either** the JS export **or** the CSS/SCSS entry points.

---

## 6. For package maintainers

Consumers of the package don’t need this section; this is only for publishing new versions.

```bash
npm install
npm run build
```

This will generate:

- `dist/index.js` + `dist/index.d.ts`
- `dist/tokens.css`
- `dist/_design-tokens.scss`
- `dist/tokens.json`

To publish a new version:

```bash
npm publish
```