@thatch-health/slab-tokens 0.0.4 → 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