@gainsight-hub/design-tokens 0.1.0

package/README.md

@@ -0,0 +1,305 @@
+# @gainsight-hub/design-tokens
+
+Design tokens for the Gainsight Community Hub — CSS custom properties, TypeScript constants, JSON, and a Tailwind v3 preset.
+
+## Install
+
+```bash
+npm install @gainsight-hub/design-tokens
+```
+
+---
+
+## Quick start
+
+Import `styles.css` once at your app entry point. That's it for most apps.
+
+```js
+// main.js / main.ts
+import "@gainsight-hub/design-tokens/styles.css";
+```
+
+Then use tokens anywhere via CSS custom properties:
+
+```css
+.button {
+  background: var(--color-action-primary-default);
+  color: var(--color-content-inverse);
+  border-radius: var(--button-radius);
+}
+```
+
+---
+
+## CSS custom properties
+
+### Base (light theme)
+
+Defines all tokens as CSS custom properties on `:root`. This is the default light theme.
+
+```js
+import "@gainsight-hub/design-tokens/styles.css";
+```
+
+### All themes bundled
+
+Includes the base tokens plus all theme overrides in a single file. Use this if you want to switch themes at runtime without loading additional stylesheets.
+
+```js
+import "@gainsight-hub/design-tokens/themes.css";
+```
+
+### Individual themes
+
+Load only the theme you need on top of `styles.css`:
+
+```js
+import "@gainsight-hub/design-tokens/styles.css";
+import "@gainsight-hub/design-tokens/themes/dark.css";
+```
+
+Available themes:
+
+| Import path | Description |
+|---|---|
+| `@gainsight-hub/design-tokens/themes/dark.css` | Gainsight dark mode |
+| `@gainsight-hub/design-tokens/themes/legacy.css` | Legacy variable aliases |
+| `@gainsight-hub/design-tokens/themes/mui.css` | Material UI overrides |
+| `@gainsight-hub/design-tokens/themes/antd.css` | Ant Design overrides |
+| `@gainsight-hub/design-tokens/themes/spectrum.css` | Adobe Spectrum overrides |
+
+### Theme switching at runtime
+
+All CSS custom properties can be scoped and overridden at any level:
+
+```css
+/* Scope to a data attribute */
+[data-theme="dark"] {
+  --color-surface-page: #161618;
+  --color-content-default: #f4f5f7;
+}
+
+/* Scope to a tenant / white-label */
+[data-tenant="acme"] {
+  --color-action-primary-default: #e63946;
+  --button-primary-background-default: #e63946;
+}
+```
+
+---
+
+## TypeScript / JavaScript
+
+Import typed token constants directly. All exports are fully typed via the bundled `tokens.d.ts`.
+
+```ts
+import {
+  ColorActionPrimaryDefault,
+  ColorSurfacePage,
+  RadiusFull,
+} from "@gainsight-hub/design-tokens";
+
+// Use in JS logic — e.g. canvas drawing, charting libs
+ctx.fillStyle = ColorActionPrimaryDefault; // "#0C66E4"
+```
+
+---
+
+## Tailwind v3
+
+### Step 1 — Import the CSS variables
+
+The Tailwind preset generates utility classes that reference CSS custom properties. Import `styles.css` so those variables are defined on the page.
+
+```js
+// main.js / main.ts
+import "@gainsight-hub/design-tokens/styles.css";
+```
+
+### Step 2 — Add the preset to your Tailwind config
+
+**ESM** (Vite, Next.js, modern setups):
+
+```js
+// tailwind.config.js
+import preset from "@gainsight-hub/design-tokens/tailwind";
+
+export default {
+  content: ["./src/**/*.{html,js,ts,jsx,tsx}"],
+  presets: [preset],
+};
+```
+
+**CJS** (older Tailwind v3 configs):
+
+```js
+// tailwind.config.cjs
+const preset = require("@gainsight-hub/design-tokens/tailwind");
+
+module.exports = {
+  content: ["./src/**/*.{html,js,ts,jsx,tsx}"],
+  presets: [preset],
+};
+```
+
+### Step 3 — Use token-based utility classes
+
+```html
+<!-- Colors -->
+<div class="bg-action-primary text-content-inverse">Primary button</div>
+<div class="bg-surface-default text-content-default">Card</div>
+<div class="bg-status-success-bold text-content-inverse">Success badge</div>
+
+<!-- Spacing -->
+<div class="p-spacing-200 gap-spacing-100">Layout</div>
+
+<!-- Border radius -->
+<div class="rounded-radius-100">Small</div>
+<div class="rounded-radius-full">Pill / avatar</div>
+
+<!-- Typography -->
+<p class="text-sm leading-normal font-medium">Body text</p>
+
+<!-- Shadows -->
+<div class="shadow-elevation-1">Raised card</div>
+```
+
+Color token naming — the `-default` suffix collapses into the base class:
+
+| Tailwind class | CSS variable |
+|---|---|
+| `bg-action-primary` | `var(--color-action-primary-default)` |
+| `bg-action-primary-hover` | `var(--color-action-primary-hover)` |
+| `bg-surface-page` | `var(--color-surface-page)` |
+| `text-content-subtle` | `var(--color-content-subtle)` |
+| `border-line-default` | `var(--color-line-default)` |
+
+> **Why import both `styles.css` and the preset?**
+> `styles.css` defines the CSS custom property values. The preset generates utility classes that reference those variables with `var(--token-name)`. The preset alone produces no colors — it needs the variables defined on the page. This separation enables runtime theming: change a CSS variable at any scope and every Tailwind class using that token updates automatically, with no rebuild.
+
+---
+
+## Component tokens (CSS Modules)
+
+For component internals, use CSS Modules with `var()` directly:
+
+```css
+/* Button.module.css */
+.root {
+  background: var(--button-primary-background-default);
+  color: var(--button-primary-label-default);
+  border-radius: var(--button-radius);
+  padding: var(--space-100) var(--space-200);
+}
+
+.root:hover {
+  background: var(--button-primary-background-hover);
+}
+```
+
+```tsx
+// Button.tsx
+import styles from "./Button.module.css";
+
+export function Button({ children }: { children: React.ReactNode }) {
+  return <button className={styles.root}>{children}</button>;
+}
+```
+
+---
+
+## JSON
+
+Raw token values as nested JSON. Useful for tooling, build scripts, or non-web targets (e.g. React Native, Figma plugins).
+
+```js
+import tokens from "@gainsight-hub/design-tokens/tokens.json" with { type: "json" };
+
+const primary = tokens.color.action.primary.default.value; // "#0C66E4"
+const gutter = tokens.space.layout.gutter.value;            // "12px"
+```
+
+## Token catalog
+
+Structured catalog with resolved values, descriptions, alias chains, and legacy mappings. Used by the design portal and design tooling.
+
+```js
+import catalog from "@gainsight-hub/design-tokens/token-catalog.json" with { type: "json" };
+
+// 224 tokens with cssVar, path, type, value, description, references, legacyMapping
+catalog.all.forEach(token => console.log(token.cssVar, token.value));
+```
+
+## Runtime theme switching
+
+Switch the active theme at runtime — no page reload required. `applyThemeConfig` lazy-loads the theme CSS on first use via `import.meta.url`, so only the themes you actually activate are fetched.
+
+```js
+import "@gainsight-hub/design-tokens/styles.css"; // load base tokens first
+import { applyThemeConfig } from "@gainsight-hub/design-tokens";
+
+// Switch to dark mode
+await applyThemeConfig("gainsight-dark");
+
+// Dark mode + custom brand color override
+await applyThemeConfig("gainsight-dark", { "--theme-brand-700": "#FF6600" });
+
+// Restore default light theme
+await applyThemeConfig("gainsight-light");
+```
+
+Available theme IDs: `gainsight-light` (default), `dark`, `legacy`, `mui`, `antd`, `spectrum`.
+
+---
+
+## Available exports
+
+| Import | Description |
+|---|---|
+| `@gainsight-hub/design-tokens` | `applyThemeConfig` + TypeScript/JS named constants |
+| `@gainsight-hub/design-tokens/styles.css` | CSS custom properties — base light theme |
+| `@gainsight-hub/design-tokens/themes.css` | CSS custom properties — all themes bundled |
+| `@gainsight-hub/design-tokens/themes/*` | Individual theme overrides (load on top of `styles.css`) |
+| `@gainsight-hub/design-tokens/tailwind` | Tailwind v3 preset (ESM + CJS) |
+| `@gainsight-hub/design-tokens/tokens.json` | Nested JSON — raw token values |
+| `@gainsight-hub/design-tokens/token-catalog.json` | Full catalog with resolved values, descriptions, alias chains |
+
+---
+
+## Package structure
+
+```
+packages/design-tokens/
+├── src/                   Token source files (Style Dictionary format)
+│   ├── primitive/         Raw scales — color, space, radius, font, shadow
+│   ├── semantic/          Semantic roles — action, surface, content, line, status
+│   └── component/         Component tokens — button, card, feed, navigation, widget
+├── config/                Style Dictionary config and custom formats
+│   └── themes/            Theme override definitions
+├── migration/             Legacy variable mapping tools
+├── build.js               Build entry point
+└── dist/                  Published output (generated, do not edit)
+    ├── index.js            Root entry — applyThemeConfig + token constants
+    ├── index.d.ts          TypeScript declarations for root entry
+    ├── applyTheme.js       Runtime theme switcher (lazy CSS loading)
+    ├── applyTheme.d.ts     TypeScript declarations for applyThemeConfig
+    ├── tokens.js           JS named constants
+    ├── tokens.d.ts         TypeScript declarations for token constants
+    ├── styles.css          CSS custom properties (base light theme)
+    ├── themes.css          All themes combined (styles.css + all theme overrides)
+    ├── tokens.json         Nested JSON
+    ├── token-catalog.json  Full token catalog
+    ├── tailwind.preset.mjs Tailwind preset (ESM)
+    ├── tailwind.preset.cjs Tailwind preset (CJS)
+    └── themes/             Individual theme CSS files
+```
+
+## Building and publishing
+
+```bash
+# Build from the monorepo root
+turbo run build --filter=@gainsight-hub/design-tokens
+
+# Publish
+npm publish --access public -w packages/design-tokens
+```

package/dist/applyTheme.d.ts

@@ -0,0 +1,14 @@
+// Auto-generated — do not edit manually.
+
+/**
+ * Switches the active theme at runtime. Lazy-loads the theme CSS on first use.
+ * Import styles.css first to establish the default light theme.
+ *
+ * @param themeId   Theme to activate ("gainsight-dark", "legacy", "theme-mui", …).
+ *                  Pass "gainsight-light" to restore the default.
+ * @param overrides Optional CSS variable overrides applied on top of the base theme.
+ */
+export declare function applyThemeConfig(
+  themeId: string,
+  overrides?: Record<string, string>,
+): Promise<void>;

package/dist/applyTheme.js

@@ -0,0 +1,66 @@
+// Auto-generated — do not edit manually.
+const THEME_CSS_URLS = {
+  "dark": new URL("./themes/dark.css", import.meta.url).href,
+  "legacy": new URL("./themes/legacy.css", import.meta.url).href,
+  "mui": new URL("./themes/mui.css", import.meta.url).href,
+  "antd": new URL("./themes/antd.css", import.meta.url).href,
+  "spectrum": new URL("./themes/spectrum.css", import.meta.url).href,
+};
+
+const STYLE_ID = "__gs-theme-overrides";
+const _loaded = new Set();
+
+function loadCss(url) {
+  if (_loaded.has(url)) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const link = document.createElement("link");
+    link.rel = "stylesheet";
+    link.href = url;
+    link.onload = () => { _loaded.add(url); resolve(); };
+    link.onerror = () => reject(new Error("Failed to load theme CSS: " + url));
+    document.head.appendChild(link);
+  });
+}
+
+function injectOverrides(overrides) {
+  const css = Object.entries(overrides).map(([k, v]) => "  " + k + ": " + v + ";").join("\n");
+  let el = document.getElementById(STYLE_ID);
+  if (!el) { el = document.createElement("style"); el.id = STYLE_ID; document.head.appendChild(el); }
+  el.textContent = ":root {\n" + css + "\n}";
+}
+
+function removeOverrides() {
+  document.getElementById(STYLE_ID)?.remove();
+}
+
+/**
+ * Switches the active theme at runtime.
+ *
+ * @param {string} themeId   - Theme to activate. Use "gainsight-light" to restore the default.
+ * @param {Record<string,string>} [overrides] - Optional CSS variable overrides applied on top.
+ * @returns {Promise<void>}
+ *
+ * @example
+ * import { applyThemeConfig } from "@gainsight-hub/design-tokens";
+ *
+ * await applyThemeConfig("gainsight-dark");
+ * await applyThemeConfig("gainsight-dark", { "--theme-brand-700": "#FF6600" });
+ * await applyThemeConfig("gainsight-light"); // restore default
+ */
+export async function applyThemeConfig(themeId, overrides = {}) {
+  const cssUrl = THEME_CSS_URLS[themeId];
+
+  if (!cssUrl) {
+    // Default / light theme — remove any active theme attribute
+    document.documentElement.removeAttribute("data-theme");
+  } else {
+    await loadCss(cssUrl);
+    document.documentElement.setAttribute("data-theme", themeId);
+  }
+
+  if (Object.keys(overrides).length === 0) {
+    removeOverrides();
+  } else {
+    injectOverrides(overrides);
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+// Auto-generated — do not edit manually.
+export * from "./tokens.js";
+export { applyThemeConfig } from "./applyTheme.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+// Auto-generated — do not edit manually.
+export * from "./tokens.js";
+export { applyThemeConfig } from "./applyTheme.js";