npm - @estebanruano/design-tokens - Versions diffs - 1.0.3 → 1.0.32 - Mend

@estebanruano/design-tokens 1.0.3 → 1.0.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -1,78 +1,53 @@
 # Design System Tokens
-Single source of truth for all design tokens. One `pnpm run build` generates platform-specific outputs for Web, Android, iOS, Flutter, and Compose Multiplatform.
+Single source of truth for all design tokens — **`figma/tokens.json`** (Tokens Studio / Figma Variables export) is the **absolute source of truth** on every branch, generated into `tokens/` and platform `dist/` outputs. Markdown-based syncing was removed; `design-system-foundations.md` is documentation only.
+## Documentation
+| Guide | Audience |
+|-------|----------|
+| **[Figma SSOT](docs/figma-ssot.md)** | Figma JSON as source — `pnpm run sync:figma` |
+| [Workflow & production](docs/workflow-and-production.md) | Releases (markdown-sync sections are historical) |
+| [General next steps](docs/general-next-steps.md) | Platform leads — adopting tokens across web, mobile, Flutter |
+| [Android + Material 3](docs/android-material3-next-steps.md) | Android / Compose — theme mapping |
+| [design-system-foundations.md](design-system-foundations.md) | Designers — token values and naming (documentation) |
 ## Quick Start
 ```bash
 pnpm install
-# Full pipeline: markdown → token JSONs → all platform outputs
-pnpm run sync
-# Or run each step separately:
-pnpm run parse    # markdown → token JSONs only
-pnpm run build    # token JSONs → platform outputs only
-```
-Outputs land in `dist/` (Gradle uses `./build/`, so token outputs use `dist/` to avoid clashes):
-```
-dist/
-├── web/
-│   ├── tokens.css          # CSS custom properties
-│   └── tokens.js           # ES6 JavaScript constants
-├── android/
-│   ├── colors.xml          # Android color resources
-│   ├── dimens.xml          # Android dimension resources
-│   └── font_dimens.xml     # Android font dimensions
-├── ios/
-│   └── DesignTokens.swift  # Swift constants (UIColor)
-├── flutter/
-│   └── design_tokens.dart  # Dart constants (Color)
-├── compose/
-│   └── DesignTokens.kt     # Kotlin object (Compose Color/Dp)
-└── json/
-    └── tokens.json         # Flat JSON (debugging / other tools)
+# From Figma JSON (Tokens Studio export — the SSOT):
+pnpm run sync:figma
 ```
-## How It Works
-The pipeline has two stages:
+| Command | Source | Generates |
+|---------|--------|-----------|
+| **`pnpm run sync:figma`** | `figma/tokens.json` | `tokens/`, `dist/**`, `package.json` ← `$metadata.version` |
-**Stage 1 — `pnpm run parse`** runs `md-to-tokens.mjs`, which reads `design-system-foundations.md`, copies the `**Version:**` semver into `package.json`, extracts every JSON code block, converts to DTCG format (`$value` / `$type`), and writes each token category to its own file under `tokens/`.
+`pnpm run sync` is an alias for **`sync:figma`**.
-**Stage 2 — `pnpm run build`** runs Style Dictionary, which reads all `tokens/**/*.json` files and generates platform-specific outputs in `dist/`.
+### Pipeline
-**`pnpm run sync`** runs both stages in sequence — this is the single command the design team needs.
-### Workflow
+**Figma → everything**
 ```
-design-system-foundations.md    ← Designers edit this (the human-readable source)
-         │
-         ▼  pnpm run parse
-    tokens/**/*.json            ← DTCG-format JSON (auto-generated)
-         │
-         ▼  pnpm run build
-    dist/                       ← Platform outputs (auto-generated; commit with PR)
-    ├── web/tokens.css
-    ├── web/tokens.js
-    ├── android/colors.xml
-    ├── android/dimens.xml
-    ├── ios/DesignTokens.swift
-    ├── flutter/design_tokens.dart
-    ├── compose/DesignTokens.kt
-    └── json/tokens.json
+figma/tokens.json  →  pnpm run sync:figma  →  tokens/ + dist/
 ```
 ### Versioning (releases)
-Release numbers for **npm** (`@estebanruano/design-tokens`), **Android Maven** (`tokensVersion`), and the `version` field in `package.json` all come from the `**Version:** x.y.z` line at the top of `design-system-foundations.md`. **`pnpm run parse`** and **`pnpm run sync`** write that value into `package.json`; Gradle uses `package.json` when `-PtokensVersion` / `TOKENS_VERSION` are unset. Bump `**Version:**` for each release (npm and GitHub Packages reject duplicate versions).
+Release numbers for **npm** (`@estebanruano/design-tokens`), **Android Maven** (`tokensVersion`), and the `version` field in `package.json` all come from the **`VERSION`** file at the repo root (single line, semver). `pnpm run version:set -- --version x.y.z` writes it (and mirrors it into the foundations md and `package.json`); **`pnpm run sync`** copies `VERSION` into `package.json`; Gradle reads `VERSION` when `-PtokensVersion` / `TOKENS_VERSION` are unset. Bump it for each release (npm and GitHub Packages reject duplicate versions).
+**Further reading:** [Workflow & production](docs/workflow-and-production.md) · [General next steps](docs/general-next-steps.md) · [Android + Material 3](docs/android-material3-next-steps.md)
 ## Using tokens on the web
-Web artifacts are **`dist/web/tokens.css`** (CSS custom properties on `:root`) and **`dist/web/tokens.js`** (named ES module exports, e.g. `ColorPrimary500`). **`dist/json/tokens.json`** is a flat JSON dump for scripts or design tooling.
+Web artifacts are **`dist/web/tokens.css`** (CSS custom properties on `:root`) and **`dist/web/tokens.js`** (named ES module exports). **`dist/figma/tokens.json`** is for Figma Variables / Tokens Studio import. **`dist/json/tokens.json`** is a flat Style Dictionary dump for scripts.
+### Figma
+After `pnpm run figma` or `pnpm run sync`, import **`dist/figma/tokens.json`** in [Tokens Studio for Figma](https://tokens.studio/) (or your Variables sync plugin). Token names match Oter CSS variables (`primary-color`, `text-primary`, `type-h1`, …). Override the collection name with `FIGMA_COLLECTION="My Set"` if needed.
 ### In this monorepo / locally
@@ -95,7 +70,7 @@ import { ColorPrimary500, Spacing4 } from '@estebanruano/design-tokens';
 @import '@estebanruano/design-tokens/css';
 .my-button {
-  background: var(--color-primary-500);
+  background: var(--color-brand-primary);
   padding: var(--spacing-4);
 }
 ```
@@ -113,10 +88,9 @@ Use the same **`import '@estebanruano/design-tokens/css'`** and **`import { …
 #### npm release checklist (maintainers)
-1. Bump **`**Version:**`** in **`design-system-foundations.md`** (and merge so **`main`** has the release).
-2. Run **`pnpm run sync`** locally or rely on CI / **Sync tokens from markdown** so **`package.json`**, **`tokens/`**, and **`dist/`** match the doc; commit any changes.
-3. **First time only:** bootstrap the package with **`npm publish --access public`** from a machine logged into npm (see **[First publish on npm (bootstrap)](#first-publish-on-npm-bootstrap)**), then configure **Trusted publishing** on npm for workflow **`publish-web.yml`**.
-4. **Ongoing:** GitHub → **Actions** → **Publish web tokens (npm)** → **Run workflow** on **`main`** (OIDC; no **`NPM_TOKEN`**).
+1. Bump the version locally: `pnpm run version:set -- --version 1.0.10` (writes **`VERSION`** and mirrors it into the foundations md + `package.json`), run `pnpm run sync:figma`, commit, push.
+2. GitHub → **Actions** → **Publish web tokens (npm)** or **Publish Android library** → **Run workflow** on the branch to release (no inputs — the version is read from the **`VERSION`** file). Both sync from **`figma/tokens.json`** and build `dist/android/*.xml` for the AAR.
+3. **First time only (npm):** bootstrap with **`npm publish --access public`**, then configure **Trusted publishing** for **`publish-web.yml`** (see **[First publish on npm (bootstrap)](#first-publish-on-npm-bootstrap)**).
 ### Fetching without a package manager (CDN)
@@ -132,29 +106,34 @@ Pin the version in the URL for reproducible builds. For production SPAs, prefer
 ```
 tokens/
 ├── color/
-│   ├── primary.json        # Brand primary scale (00–800)
-│   ├── secondary.json      # Brand secondary scale (00–800)
-│   ├── neutral.json        # Gray scale (0–1000)
-│   └── semantic.json       # Success, warning, error, info
+│   ├── brand.json          # Indigo brand (primary, hover, tints)
+│   ├── surface.json        # Slate surfaces + borders
+│   ├── text.json           # Text ramp
+│   ├── semantic.json       # Success, warning, danger, info
+│   ├── eisenhower.json     # Tasks matrix accents
+│   └── gradient.json       # Auth hero gradient
 ├── typography/
-│   └── scale.json          # Font families, weights, sizes, line heights
+│   ├── family.json         # Geist, Geist Mono, Lexend
+│   ├── weight.json
+│   └── scale.json          # Semantic type scale (h1–mono)
 ├── spacing/
-│   └── spacing.json        # 4px base unit scale (0–40)
+│   └── spacing.json        # xs → xxl (4px base)
 ├── radius/
-│   └── radius.json         # Border radii (none–full)
+│   └── radius.json         # sm → full
 ├── shadow/
-│   └── shadow.json         # Elevation levels (sm–xl)
+│   └── shadow.json         # sm → xl
 ├── motion/
-│   └── motion.json         # Duration + easing curves
-└── opacity/
-    └── opacity.json        # Disabled, hover, pressed, focus, scrim
+│   ├── duration.json
+│   └── easing.json
+└── z-index/
+    └── z-index.json        # Stacking ladder
 ```
 ## How to Update Tokens
 ### For engineers (Claude Code)
 ```bash
-claude "Update primary-500 to #EA580C in tokens/color/primary.json, rebuild, commit and push"
+claude "Update primary-color to #4F46E5 in figma/tokens.json, run pnpm run sync, commit and push"
 ```
 ### For designers (GitHub Web UI)
@@ -168,78 +147,31 @@ claude "Update primary-500 to #EA580C in tokens/color/primary.json, rebuild, com
 ## Adding a New Token
-1. Add the token to the appropriate JSON file under `tokens/`
-2. Follow the DTCG-compatible format:
+1. Add the token to **`figma/tokens.json`** (flat Tokens Studio name) and map it in
+   `token-name-map.mjs` (`FIGMA_TO_TOKEN_PATH`) if the generic naming rules do not cover it:
    ```json
    {
      "token-name": {
        "$value": "#F97316",
-       "$type": "color",
-       "$description": "Optional description"
+       "$type": "color"
      }
    }
    ```
-3. Run `pnpm run sync` to verify all platforms generate correctly
-4. Commit and push — CI validates; merge to `main`, then run **Publish Android library** and/or **Publish web tokens (npm)** manually when you want a Maven or npm release (see below)
+2. Run `pnpm run sync` to verify all platforms generate correctly (never edit `tokens/` by hand)
+3. Commit and push — CI validates; merge to `main`, then run **Publish Android library** and/or **Publish web tokens (npm)** manually when you want a Maven or npm release (see below)
 ## Automation (GitHub Actions)
-This repo can run the full “edit markdown → tokens → PR → registries” loop on GitHub:
+Full setup, branch flows, Figma in prod, release checklists, and troubleshooting: **[docs/workflow-and-production.md](docs/workflow-and-production.md)**.
 | Workflow | When | What it does |
 |----------|------|----------------|
-| **Sync tokens from markdown** | Push that changes `design-system-foundations.md` | Runs `pnpm run sync`, commits `tokens/`, `dist/`, and `package.json` (when changed) to the same branch, then opens a PR into `main` if the branch is not `main` and no open PR exists. On `main`, it pushes the sync commit directly. |
-| **CI** | Pull requests to `main` | `pnpm run sync` then fails if anything drifts from the commit; builds `:design-tokens-android` with Gradle. |
-| **Publish Android library** | Manual only: Actions → workflow → **Run workflow** (typically from `main`) | `pnpm run sync`, then `./gradlew :design-tokens-android:publish` to **GitHub Packages**. Maven **groupId**, **artifactId**, and Android **namespace** are set in **`gradle.properties`**. **Version** = `**Version:**` in `design-system-foundations.md` (via `package.json` after sync; override with `-PtokensVersion` / `TOKENS_VERSION` if needed). |
-| **Publish web tokens (npm)** | Manual only: Actions → workflow → **Run workflow** (typically from `main`) | `pnpm run sync`, then **`npm publish`** (npm ≥ 11.5.1) to **registry.npmjs.org** using **[Trusted Publishing](https://docs.npmjs.com/trusted-publishers/)** (OIDC). Requires **`id-token: write`** in the workflow (already set) and a one-time **Trusted Publisher** config on npm for workflow file **`publish-web.yml`**. **Version** comes from the foundations markdown (see **Versioning** above). |
-### Deployment workflow
-Deployments are **manual** for Android (Maven) and web (npm). Nothing publishes automatically when you merge to `main`. Use this sequence when you want consumers to pick up a new release.
-**Workflow files** (under `.github/workflows/`):
-| File | Role |
-|------|------|
-| `sync-tokens-from-md.yml` | Regenerates artifacts after markdown edits (automatic on push). |
-| `ci.yml` | Validates PRs: regenerated tree must match the commit. |
-| `publish-android.yml` | Publishes the Android AAR to **GitHub Packages** (Maven). |
-| `publish-web.yml` | Publishes **`@estebanruano/design-tokens`** to **npm** via **OIDC** ([Trusted publishing](https://docs.npmjs.com/trusted-publishers/)). |
-**Recommended release path**
-1. **Change tokens or version** in `design-system-foundations.md` (including `**Version:**` when you intend a new Maven/npm release — see **Versioning (releases)** above).
-2. **Push** your branch. **Sync tokens from markdown** runs: it executes `pnpm run sync`, commits generated files, and either **opens a PR to `main`** (feature branches) or **pushes to `main`** (if you edited on `main` directly).
-3. **Review and merge** the PR when CI is green (or confirm the direct push on `main` if you used that path).
-4. **Publish** — only after `main` contains the version and artifacts you want live:
-   - **Android:** GitHub → **Actions** → **Publish Android library** → **Run workflow**, select **`main`** (or a release branch if you use one). Uses `GITHUB_TOKEN`; no extra secret.
-   - **Web:** GitHub → **Actions** → **Publish web tokens (npm)** → **Run workflow**, select **`main`**. Uses **OIDC trusted publishing** (no `NPM_TOKEN`); complete the [one-time npm setup](#npm-trusted-publishing-setup) below.
-Both publish workflows run **`pnpm run sync`** first, so the published bits always match the checked-out commit (including `**Version:**` → `package.json`). The npm job then runs **`npm publish`** so the npm CLI can use OIDC (see [Trusted publishing](https://docs.npmjs.com/trusted-publishers/)).
-**If publish fails with 409 / duplicate version**
-The Maven or npm coordinate for that version already exists. Bump `**Version:**` in the foundations doc, merge a sync commit, then run the publish workflow again.
-```mermaid
-flowchart TD
-  A[Edit design-system-foundations.md] --> B[Push]
-  B --> C[Sync tokens from markdown]
-  C --> D{Branch is main?}
-  D -->|No| E[Bot commits + opens PR to main]
-  D -->|Yes| F[Bot commits to main]
-  E --> G[Merge PR after CI]
-  F --> H[main up to date]
-  G --> H
-  H --> I[Run publish workflows from main when ready]
-  I --> J[Publish Android library → GitHub Packages Maven]
-  I --> K[Publish web tokens npm → registry.npmjs.org]
-```
-**Repo settings you need**
+| **Sync tokens from Figma JSON** | Push to `figma/tokens.json` (or manual) | `pnpm run sync:figma` → commit `tokens/`, `dist/`, `package.json` |
+| **CI** | PR to `main` / `belcorp` | `sync:figma` → fail on drift → assemble Android |
+| **Publish web tokens (npm)** | Manual | `sync:figma` → `npm publish` |
+| **Publish Android library** | Manual | `sync:figma` → Gradle publish |
-1. **Actions → General → Workflow permissions**: allow **Read and write** so the sync job can push commits and open PRs.
-2. **Android publishing**: GitHub Packages Maven uses `GITHUB_TOKEN` from Actions (`packages: write` on the Android publish workflow). Bump `**Version:**` in `design-system-foundations.md` for every new Maven release — **the same version cannot be published twice** (Gradle will fail with **HTTP 409 Conflict** if you try).
+Merging to `main` does **not** publish npm or Maven — run publish workflows when consumers need a new version.
 #### npm: Trusted publishing setup
@@ -302,11 +234,28 @@ gpr.key=YOUR_PAT_WITH_read:packages
 In **CI** for the consuming app, inject the same values (e.g. repository secrets mapped to env vars or `ORG_GRADLE_PROJECT_gpr.*` so Gradle picks them up).
+**Material 3 and multi-project structure:** see [docs/android-material3-next-steps.md](docs/android-material3-next-steps.md) for mapping tokens to M3 (Compose + Views), shared theme libraries vs apps, and flavors / multiple products.
 ### Using tokens in Android app code
-The **`tokens-android`** artifact is a normal **`com.android.library`**: it ships **resource XML** only (colors, dimens, font dimens, etc.). After `implementation(...)`, those resources are **merged** into your app module, so you reference them like any other library resource.
+The **`tokens-android`** artifact is a normal **`com.android.library`**: it ships **resource XML** only. After `implementation(...)`, those resources are **merged** into your app module, so you reference them like any other library resource.
+**Local repo vs published AAR:** this repo keeps **four** files under `dist/android/` (`colors.xml`, `dimens.xml`, `integers.xml`, `strings.xml`). Android Studio often shows them as **one combined `<resources>` block** when you inspect the library dependency — that is normal. If colors or `font_size_*` differ from your local `dist/android/`, the app is almost certainly on an **older Maven version**; bump the dependency and re-run **Publish Android library** with a new version after `pnpm run sync`.
+**Resource names** match the generated files in **`dist/android/`**: `colors.xml`, `dimens.xml` (spacing, radius, **and font sizes in `sp`**), `integers.xml`, `strings.xml`. There is no `R.font_dimens` type — font sizes are normal **`R.dimen`** entries (e.g. `R.dimen.font_size_h1`, `@dimen/font_size_h1` in XML).
-**Resource names** match the generated files in this repo under **`dist/android/`** (e.g. `colors.xml`, `dimens.xml`). Typical names look like `color_primary_500`, `color_neutral_500`, `spacing_4`, `radius_md` — always confirm the exact `name="…"` in those files when you add or rename tokens.
+**Font sizes in Compose:** `dimensionResource()` returns `Dp`, but `Text.fontSize` needs `TextUnit` (`sp`). Use:
+```kotlin
+import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.res.dimensionResource
+Text(
+    fontSize = with(LocalDensity.current) {
+        dimensionResource(R.dimen.font_size_h1).toSp()
+    },
+)
+```
 **XML layouts**
@@ -314,8 +263,9 @@ The **`tokens-android`** artifact is a normal **`com.android.library`**: it ship
 <TextView
     android:layout_width="wrap_content"
     android:layout_height="wrap_content"
-    android:textColor="@color/color_primary_500"
-    android:padding="@dimen/spacing_4" />
+    android:textColor="@color/color_brand_primary"
+    android:textSize="@dimen/font_size_body"
+    android:padding="@dimen/spacing_md" />
 ```
 **`styles.xml` / Material theme**

package/VERSION ADDED Viewed

	@@ -0,0 +1 @@
1	+ 1.0.32