npm package: @honeycluster/gds
Description: Global Design System: design tokens, theme CSS, and Tailwind integration for Honeycluster apps.
Author: honeycluster
Latest version: 0.1.0

# @honeycluster/gds

Global Design System: design tokens, theme CSS, and Tailwind integration for Honeycluster apps.

## What’s in this package

- **Design tokens** — Single source of truth (`tokens.json`) for colors, typography, spacing, etc.
- **Generated styles** — Platform outputs (web CSS/SCSS/JSON, iOS, Android, styleguide) from the design build.
- **Tailwind theme** — CSS layers and `@theme` definitions for use with Tailwind CSS (`styles/tailwind/`).
- **Build scripts** — Style Dictionary config and runners for design tokens and theme CSS.

## Build

From the package directory:

```bash
pnpm build
```

This will:

1. Compile the TypeScript build scripts.
2. Run the **design** build (web, iOS, Android, styleguide outputs from `tokens.json`).
3. Run the **Tailwind theme** build (Dark.css, Light.css, Globals.css, theme.css).
4. Format generated styles.

Outputs go under `styles/` (e.g. `styles/web/`, `styles/tailwind/`, `styles/ios/`, `styles/android/`, `styles/styleguide/`).

## Consuming the styles

### Tailwind (recommended for web apps)

In your app’s root CSS:

```css
@import '@honeycluster/gds/styles/tailwind/theme.css';
```

Then use `data-theme`, `data-variant`, and `data-mode` on your HTML to control theming. See **[styles/tailwind/README.md](./styles/tailwind/README.md)** for:

- What `data-theme`, `data-variant`, and `data-mode` do.
- How to use them with components (e.g. buttons).
- **Tailwind v4 theme namespaces** (e.g. `--spacing-*`, `--color-*`, `--radius-*`) and how GDS maps to them.
- Available CSS variables and Tailwind theme keys.

### Other platforms

- **Web (no Tailwind):** Import or copy the generated CSS from `styles/web/{mode}/` (e.g. `tokens.css`).
- **iOS/Android:** Use the generated token files under `styles/ios/` and `styles/android/`.

## Package exports

Published (or linked) artifacts include:

- `dist/` — Compiled build scripts (for programmatic use).
- `styles/` — All generated CSS, JSON, SCSS, plist, and Tailwind theme files.

Configure your app to resolve `@honeycluster/gds` to this package so that imports like `@honeycluster/gds/styles/tailwind/theme.css` work.

## Scripts

| Script            | Description |
|-------------------|-------------|
| `pnpm build`      | Full build: compile, design tokens, Tailwind theme, format styles. |
| `pnpm rebuild`    | Compile and run token/theme builds (no clean). |
| `pnpm format:styles` | Format generated files under `styles/` with Prettier. |
| `pnpm lint`       | Lint `src/`. |
| `pnpm format`     | Format `src/` with Prettier. |

## Configuration

Build behavior is driven by **`src/modules/config.ts`** (colors, dimensions, typography, paths). Apps can reuse the build with custom config via `getDefaultConfig()` and `mergeConfig()` and then call `runDesign()` and `runTwThemes()` from `src/run.ts`.

## Token source

- **Design tokens** are maintained in **`tokens.json`** (and optionally synced from Figma or other sources).
- The Tailwind theme generator reads `tokens.json` and emits Light/Dark/Globals CSS and `theme.css` with the correct `data-theme` / `data-variant` / `data-mode` structure.

For theme usage and examples, see **[styles/tailwind/README.md](./styles/tailwind/README.md)**.