npm package: @ibis-design/css
Description: Design tokens, CSS variables, and Tailwind preset for the IBIS design system.
Latest version: 0.4.0

# @ibis-design/css

Design tokens as CSS custom properties, optional base CSS, and a Tailwind v4–compatible preset for the IBIS design system. Framework-agnostic; usable from any stack.

## Installation

```bash
npm install @ibis-design/css
```

## Usage

### Brands / style sets

The package ships two style sets. The default entry is **ibis**; use explicit paths for **alchemy**:

| Import | Description |
|--------|-------------|
| `@ibis-design/css` or `@ibis-design/css/ibis-design.css` | IBIS design tokens (default) |
| `@ibis-design/css/alchemy-design.css` | Alchemy design tokens |
| `@ibis-design/css/ibis-design.scss` / `alchemy-design.scss` | SCSS variables for each brand |

**Tailwind presets** — Use the preset that matches the token CSS you load:

| Import | Description |
|--------|-------------|
| `@ibis-design/css/tailwind.preset` or `@ibis-design/css/preset` | IBIS preset (default) |
| `@ibis-design/css/ibis/tailwind.preset` | IBIS preset (explicit) |
| `@ibis-design/css/alchemy/tailwind.preset` | Alchemy preset |

### CSS variables

Import the generated tokens in your CSS (or entry point) so that `:root` is populated with design tokens:

```css
@import "@ibis-design/css";
/* or */
@import "@ibis-design/css/ibis-design.css";
```

All tokens are exposed as custom properties, for example:

- `--color-primary-500`, `--color-success-text`, …
- `--spacing-1`, `--spacing-4`, …
- `--font-sans`, `--font-size-base`, …
- `--radius-sm`, `--radius-lg`, …

Use them in your own CSS:

```css
.card {
  background: var(--color-primary-50);
  padding: var(--spacing-4);
  border-radius: var(--radius-md);
  font-family: var(--font-sans);
}
```

### Tailwind preset

Use the preset so Tailwind utilities (e.g. `bg-primary-500`, `p-4`, `rounded-md`) map to the same token values. Load the preset that matches the token CSS you use.

**Ibis:**

```js
/** @type {import('tailwindcss').Config} */
module.exports = {
  presets: [require("@ibis-design/css/tailwind.preset")],
  content: ["./src/**/*.{html,js,ts,jsx,tsx,svelte,vue}"],
};
```

**Alchemy:**

```js
presets: [require("@ibis-design/css/alchemy/tailwind.preset")],
```

Ensure the matching token CSS is loaded in your app (e.g. `@import "@ibis-design/css/ibis-design.css"` for ibis or `@import "@ibis-design/css/alchemy-design.css"` for alchemy) so that the `var(--...)` references resolve.

Tailwind v4 may use a different config or CSS-based theme; the preset shape is compatible with Tailwind v3. For v4, use the same preset via `@config` if supported, or import the tokens CSS and extend your theme with the same variable names.

## Build

From the package directory (or from the repo root with `npm run build:css`):

```bash
npm run build
```

This runs Style Dictionary for each token set in `src/tokens/` (e.g. `ibis.json`, `alchemy.json`) and writes per brand under `dist/<brand>/`:

- `dist/<brand>/<brand>-design.css` — `:root` block with all CSS custom properties
- `dist/<brand>/<brand>-design.scss` — SCSS variables
- `dist/<brand>/tailwind.preset.js` — Tailwind theme extend object that references those variables

Do not edit the files in `dist/`; they are generated. To change tokens, edit the JSON files in `src/tokens/` and run `npm run build` again.

## Token source

Tokens are defined in DTCG format in `src/tokens/` (e.g. `ibis.json`, `alchemy.json`). The build is driven by `src/scripts/build.ts` and `src/config/style-dictionary.config.ts`. Style Dictionary reads the token JSON and emits CSS, SCSS, and the Tailwind preset. Other packages (e.g. Svelte, React Native) can consume the generated CSS or preset for consistent values.

## Fonts

The tokens reference font families (e.g. Inter, Metrisch, Beyond Infinity). This package does not bundle or load font files. To get the intended typography, load the fonts in your app (e.g. via Google Fonts, a CDN, or self-hosted assets) and ensure the font names match the token values.