@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:

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:

@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 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.