@thatch-health/slab-tokens 0.0.5 → 0.0.6

package/README.md

@@ -2,9 +2,85 @@
 
 This package is the pipeline for importing Figma tokens defined in [Token Foundations](https://www.figma.com/design/AMVtHovyyMCo78skFvePV4/Token-Foundations?node-id=32-93&p=f&t=fLz0IYz5irefoKsl-11) and then outputing in appropriate formats for web, the marketing website, and slab design system itself. This package uses [Terrazzo](https://terrazzo.app/) to manage the conversion from the [Design Token Community Group](https://www.designtokens.org/) specification which is a universal token specification. The package itself exports a few endpoints for consumers to use:
 
+- `@thatch-health/slab-tokens` - The `getToken` and `mergeToken` JavaScript API for querying token metadata
 - `@thatch-health/slab-tokens/tokens-raw` - The raw JSON values of the DTCG specification downloaded from Figma
-- `@thatch-health/slab-tokens/css` - The output from terrazzo using the css plugin
-- `@thatch-health/slab-tokens/tailwind-v3-plugin` - A plugin for tailwind v3 that maps css variables
+- `@thatch-health/slab-tokens/css/app` - CSS custom properties output from Terrazzo (import in a root CSS file)
+- `@thatch-health/slab-tokens/tailwind-v3-plugin` - A plugin for Tailwind v3 that maps CSS variables to utility classes
+- `@thatch-health/slab-tokens/tailwind-v4-plugin` - A CSS plugin for Tailwind v4 that maps CSS variables to utility classes
+
+## Installation
+
+Install the package:
+
+```bash
+npm i @thatch-health/slab-tokens
+```
+
+### Import CSS
+
+In a root `.css` file, import the token styles:
+
+```css
+@import "@thatch-health/slab-tokens/css/app";
+```
+
+### Tailwind v3
+
+In your `tailwind.config.js`, import the plugin and add it to your plugins array:
+
+```ts
+import slabPlugin from "@thatch-health/slab-tokens/tailwind-v3-plugin";
+
+const config = {
+  plugins: [slabPlugin],
+};
+
+export default config;
+```
+
+### Tailwind v4
+
+In the CSS file where you import Tailwind, add both the CSS tokens and the v4 plugin:
+
+```css
+@import "tailwindcss";
+@import "@thatch-health/slab-tokens/css/app";
+@import "@thatch-health/slab-tokens/tailwind-v4-plugin";
+```
+
+## `getToken` API
+
+The package exposes a `getToken` function for querying token metadata programmatically. This is useful for MCP servers, documentation tooling, or any code that needs to discover which tokens apply to a given design intent.
+
+```ts
+import { getToken } from "@thatch-health/slab-tokens";
+```
+
+`getToken` accepts an options object where **at least one field is required**. Multiple fields are ANDed together to narrow results.
+
+| Option     | Type            | Description                                                                                                                             |
+| ---------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `category` | `TokenCategory` | Filter by design intent: `"surface"`, `"action"`, `"form"`, `"typography"`, `"dimension"`, `"radius"`, `"gap"`, `"spacing"`, `"stroke"` |
+| `scope`    | `Scope`         | Filter by broad token kind: `"color"`, `"spacing"`, or `"typography"`                                                                   |
+| `property` | `CSSProperty`   | Filter by the CSS property the token applies to (e.g. `"background"`, `"padding"`, `"font-size"`)                                       |
+| `name`     | `string`        | Fuzzy-match on token name (e.g. `"action primary bg"` matches `"action.default.primary.bg"`)                                            |
+
+Each result is a `MergedToken` which includes the DTCG token fields plus a `$extensions["thatch.slab"]` entry describing the CSS variable, Tailwind class(es), and applicable CSS properties.
+
+### Examples
+
+```ts
+// All action color tokens
+getToken({ category: "action", scope: "color" });
+
+// Tokens that set the background property on action components, filtered by name
+getToken({ property: "background", category: "action", name: "default" });
+// → ["action.default.ghost.bg", "action.default.primary.bg", ...]
+
+// Fuzzy search by name
+getToken({ name: "action.default.primary.bg" });
+// → includes "action.default.primary.bg", "action.default.primary.bg-end", etc.
+```
 
 ## Development
 

package/dist/index.d.mts

@@ -1754,8 +1754,9 @@ interface FigmaToken {
   $description?: string;
   $extensions?: FigmaExtensions;
 }
+type RequireAtLeastOne<T> = { [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>> }[keyof T];
 //#endregion
-//#region src/index.d.ts
+//#region src/merge-token.d.ts
 declare const COLOR_MODES: readonly ["neutral", "danger", "info", "neutral-inverted", "success", "warning"];
 type ColorMode = (typeof COLOR_MODES)[number];
 type SlabEntry = {
@@ -1772,6 +1773,7 @@ type SlabEntry = {
   note?: string;
 };
 type MergedToken = FigmaToken & {
+  $name: string;
   $extensions: {
     "com.figma.variableId"?: string;
     "thatch.slab": SlabEntry;
@@ -1780,5 +1782,43 @@ type MergedToken = FigmaToken & {
 };
 declare function mergeToken(key: keyof typeof tokenMap): MergedToken | null;
 //#endregion
-export { ColorMode, MergedToken, SlabEntry, mergeToken };
+//#region src/get-token.d.ts
+/**
+ * A semantic grouping of tokens by their design intent.
+ * Use `category` to narrow results to a specific part of the design system.
+ */
+type TokenCategory = /** Page backgrounds, cards, banners, and other non-interactive containers. */"surface" /** Base page background. Primary surfaces sit at the bottom of the visual stack. */ | "surface-primary" /** Elevated containers such as sidebars, panels, or cards placed on a primary surface. */ | "surface-secondary" /** Badges, nav bars, or chips that sit on top of primary or secondary surfaces. */ | "surface-tertiary" /** Buttons, links, dropdowns, and other interactive controls. */ | "action" /** The most prominent interactive element on a view. Use sparingly — one per view. Includes default, hover, and disabled states. */ | "action-primary" /** Supporting interactive elements like secondary buttons or sidebar nav rows. Includes default, hover, and disabled states. */ | "action-secondary" /** Interactive elements that appear as plain text until engaged, like cancel buttons. Includes default, hover, and disabled states. */ | "action-ghost" /** Link-style interactive elements that use color to signal interactivity. Includes default, hover, and disabled states. */ | "action-tertiary" /** Text fields, selects, checkboxes, radio buttons, and other form inputs. */ | "form" /** Primary form control surfaces — input backgrounds, borders, and text. Includes default, disabled, and active states. */ | "form-primary" /** Secondary form text — helper text and supplemental labels. Includes default, disabled, and active states. */ | "form-secondary" /** All typography tokens. Use sub-categories below for narrower results. */ | "typography" /** Display/heading type tokens — large expressive text. */ | "display" /** Header tokens — section headings. */ | "header" /** Body tokens — default reading text. */ | "body" /** Control tokens — labels, buttons, and UI chrome. */ | "control" /** Mono tokens — code and tabular data. */ | "mono" /** Fixed-size tokens for elements like buttons or badges (width / height). */ | "dimension" /** Border-radius tokens. */ | "radius" /** Gap tokens for flex and grid layouts (inline and stack). */ | "gap" /** Inset tokens for padding and margin. */ | "spacing" /** Border-width tokens. */ | "stroke";
+/**
+ * The broad kind of a token.
+ * - `"color"` — fills, text colors, border colors, and gradients.
+ * - `"spacing"` — padding, margin, gap, size, border-radius, and border-width.
+ * - `"typography"` — font-family, font-size, font-weight, line-height, letter-spacing.
+ */
+type Scope = "color" | "spacing" | "typography";
+/**
+ * The CSS property a token directly applies to.
+ * Scoped to properties that are actually present in the shipped token set.
+ */
+type CSSProperty = "background" | "color" | "border-color" | "outline-color" | "--tw-gradient-from" | "--tw-gradient-to" | "font-family" | "font-size" | "font-weight" | "line-height" | "letter-spacing" | "padding" | "padding-top" | "padding-right" | "padding-bottom" | "padding-left" | "margin" | "margin-top" | "margin-right" | "margin-bottom" | "margin-left" | "border-width" | "border-top-width" | "border-right-width" | "border-bottom-width" | "border-left-width" | "gap" | "column-gap" | "row-gap" | "width" | "height" | "min-width" | "min-height" | "border-radius";
+/**
+ * Options for {@link getToken}. At least one field must be provided.
+ * Multiple fields are ANDed — each one further narrows the result set.
+ */
+type GetTokenOptions = RequireAtLeastOne<{
+  /** Narrow by design intent (e.g. `"action"` returns button/link tokens). */category: TokenCategory; /** Narrow by broad token kind: color, spacing, or typography. */
+  scope: Scope; /** Narrow by the CSS property the token sets. */
+  property: CSSProperty;
+  /**
+   * Fuzzy-match on the token name using fuse.js.
+   * e.g. `"action primary bg"` will match `"action.default.primary.bg"`.
+   */
+  name: string;
+}>;
+/**
+ * Search for design tokens matching the given options.
+ * At least one option must be provided. Multiple options are ANDed together.
+ */
+declare function getToken(options: GetTokenOptions): MergedToken[];
+//#endregion
+export { type CSSProperty, type ColorMode, type GetTokenOptions, type MergedToken, type Scope, type SlabEntry, type TokenCategory, getToken, mergeToken };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/token-map.ts","../src/utils/types.ts","../src/index.ts"],"mappings":";cASa,QAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAb;;;;;;UCDiB,cAAA;EACf,gBAAA;EACA,kBAAA;EACA,qBAAA;AAAA;;;;;KAOU,aAAA;AAAA,UAyBK,eAAA;EACf,sBAAA;EACA,kBAAA,GAAqB,aAAA;EACrB,sBAAA;IACE,GAAA;EAAA;EAEF,gCAAA;EACA,sBAAA;EACA,oBAAA;EACA,gBAAA;EACA,qBAAA,GAAwB,cAAA;AAAA;AAAA,UAGT,eAAA;EACf,UAAA;EACA,UAAA;EACA,KAAA;EACA,GAAA;AAAA;AAAA,UAGe,UAAA;EACf,KAAA;EACA,MAAA,oBAA0B,eAAA;EAC1B,YAAA;EACA,WAAA,GAAc,eAAA;AAAA;;;cCvDV,WAAA;AAAA,KAQM,SAAA,WAAoB,WAAA;AAAA,KAEpB,SAAA;EACV,WAAA;EACA,IAAA;EACA,QAAA;iFAEE,WAAA;IAEA,aAAA;EAAA;;;;;EAMF,IAAA;AAAA;AAAA,KAGU,WAAA,GAAc,UAAA;EACxB,WAAA;IACE,sBAAA;IACA,aAAA,EAAe,SAAA;IACf,cAAA,GAAiB,MAAA,CAAO,SAAA;EAAA;AAAA;AAAA,iBA8EZ,UAAA,CAAW,GAAA,eAAkB,QAAA,GAAW,WAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/token-map.ts","../src/utils/types.ts","../src/merge-token.ts","../src/get-token.ts"],"mappings":";cASa,QAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAb;;;;;;UCDiB,cAAA;EACf,gBAAA;EACA,kBAAA;EACA,qBAAA;AAAA;;;;;KAOU,aAAA;AAAA,UAyBK,eAAA;EACf,sBAAA;EACA,kBAAA,GAAqB,aAAA;EACrB,sBAAA;IACE,GAAA;EAAA;EAEF,gCAAA;EACA,sBAAA;EACA,oBAAA;EACA,gBAAA;EACA,qBAAA,GAAwB,cAAA;AAAA;AAAA,UAGT,eAAA;EACf,UAAA;EACA,UAAA;EACA,KAAA;EACA,GAAA;AAAA;AAAA,UAGe,UAAA;EACf,KAAA;EACA,MAAA,oBAA0B,eAAA;EAC1B,YAAA;EACA,WAAA,GAAc,eAAA;AAAA;AAAA,KAyCJ,iBAAA,oBACE,CAAA,KAAM,QAAA,CAAS,IAAA,CAAK,CAAA,EAAG,CAAA,KAAM,OAAA,CAAQ,IAAA,CAAK,CAAA,EAAG,OAAA,OAAc,CAAA,EAAG,CAAA,YACpE,CAAA;;;cCxGF,WAAA;AAAA,KASM,SAAA,WAAoB,WAAA;AAAA,KAEpB,SAAA;EACV,WAAA;EACA,IAAA;EACA,QAAA;iFAEE,WAAA;IAEA,aAAA;EAAA;;;;;EAMF,IAAA;AAAA;AAAA,KAGU,WAAA,GAAc,UAAA;EACxB,KAAA;EACA,WAAA;IACE,sBAAA;IACA,aAAA,EAAe,SAAA;IACf,cAAA,GAAiB,MAAA,CAAO,SAAA;EAAA;AAAA;AAAA,iBAwEZ,UAAA,CAAW,GAAA,eAAkB,QAAA,GAAW,WAAA;;;;;;;KClG5C,aAAA;;;;;;;KAsDA,KAAA;;;;;KAMA,WAAA;;;;;KAgDA,eAAA,GAAkB,iBAAA;8EAE5B,QAAA,EAAU,aAAA;EAEV,KAAA,EAAO,KAAA;EAEP,QAAA,EAAU,WAAA;;;;;EAKV,IAAA;AAAA;;;;;iBAwDc,QAAA,CAAS,OAAA,EAAS,eAAA,GAAkB,WAAA"}