feat(pie-token-map): CACT-4721 add pie-token-map package

[matthewhardern]

Summary

Adds a new @justeattakeaway/pie-token-map package under packages/tools/ that provides programmatic lookup of PIE design tokens by name, returning CSS variable references (var(--dt-*)).

Why this package?

Currently, consumers who need to reference design tokens programmatically (e.g. in JS/TS logic, SSR, or cross-platform tooling) have no typed, structured way to do so. They must hard-code CSS variable strings. This package:

• Returns CSS variable references, not resolved values - preserving runtime theme reactivity (tokens respond to theme switching via CSS custom properties)
• Provides TypeScript-safe token lookups - as const arrays with extracted union types for every token category, giving compile-time autocomplete and validation
• Enables cross-platform parity - token names are aligned with the Android PIE token map, allowing shared tooling to reference the same token names across platforms
• Auto-generates from source - a build-time script reads @justeat/pie-design-tokens/dist/tokens.json and generates typed maps, ensuring the package stays in sync with upstream token changes

Intended use case

Its purpose is solely to allow the use of styling text in marketing content on the JET+ hub. It enables marketing to say, for example, "underline this word", and have it applied across all 3 platforms identically — without them having to write content for 3 platforms separately. It has no other intended use case beyond this.

The way styles are applied obviously differs per platform, so we needed a cross-platform way of doing it. Android went first as they already had a library; web is copying their approach.

What's included

• 9 token categories: color, typography, radius, spacing, elevation, gradient, motion, breakpoint, z-index
• Per-category getter functions: getColor(), getTypography(), getRadius(), etc.
• hasToken(category, name) - validation helper for checking token existence
• tokenMap convenience object - aggregates all getters and raw maps
• tokensVersion - tracks the upstream @justeat/pie-design-tokens version
• Platform-agnostic color aliases - maps container-base, container-neutral, etc. to their web-container-* CSS vars for Android parity
• Composite typography tokens - returns structured objects with family, weight, size/sizeWide/sizeNarrow, lineHeight, fontStyle, textDecoration, and paragraph properties where applicable

Design decisions

• Zero runtime dependencies - generated maps are static TypeScript objects; @justeat/pie-design-tokens is a devDependency used only at build/generate time
• Code generation over manual maintenance - scripts/generate-token-map.ts reads tokens.json directly, so adding new tokens upstream requires only a regenerate, not manual code changes
• Z-index tokens are hand-written - these come from pie-css/css/input.css rather than tokens.json, so the list is maintained explicitly in the generator
• ESM-only output - follows the repo standard ("type": "module", Vite library build with formats: ['es'])

Package structure

packages/tools/pie-token-map/
├── scripts/generate-token-map.ts   # Reads tokens.json, generates src/generated/*
├── src/
│   ├── index.ts                    # Public API (getters, exports, tokenMap object)
│   ├── types.ts                    # Shared types (CssVarRef, TokenCategory, TypographyTokenValue)
│   └── generated/                  # Auto-generated token maps (one per category + version)
├── test/unit/token-map.spec.ts     # Comprehensive unit tests
├── vite.config.ts                  # Library build config
└── package.json                    # v0.1.0, alpha status

Test plan

• Unit tests cover all 9 token categories (getters return correct var(--dt-*) refs)
• Completeness tests verify every token in tokens.json is present in the generated maps
• Platform-agnostic color aliases map correctly to web-* prefixed CSS vars
• Typography structure tests validate responsive vs non-responsive tokens, italic/link/paragraph properties
• hasToken() tested across all categories for known and unknown names
• tokenMap convenience object exposes all getters, raw maps, and version
• tokensVersion matches @justeat/pie-design-tokens package version
• CI lint and build pass
• README documentation for the package
• Integration examples showing usage with pie-css and web components

Follow-up work

• Consider adding a CI check that verifies generated output matches what the script would produce (drift detection)

[changeset-bot]

🦋 Changeset detected

Latest commit: 54b5093

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@justeattakeaway/pie-token-map	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[jamieomaguire]

Please can you deliver the follow-up work as a part of this ticket?

The readme content should be mandatory for this change at a minimum

[matthewhardern]

Please can you deliver the follow-up work as a part of this ticket?

The readme content should be mandatory for this change at a minimum

Yep will do 👍

[ashleynolan]

Couple of comments from me.

Would be interested to see the use case for this too (in terms of the application once it's published). I'm guessing it's for enabling better styling in JS hooks (CSS-inJS style), but I'd be wary of overusing it where CSS classes can be used to apply the styles instead, as it'll be less performant due to using JS.

[matthewhardern]

Couple of comments from me.

Would be interested to see the use case for this too (in terms of the application once it's published). I'm guessing it's for enabling better styling in JS hooks (CSS-inJS style), but I'd be wary of overusing it where CSS classes can be used to apply the styles instead, as it'll be less performant due to using JS.

It's purpose is solely to allow the use of styling text in marketing content on the JET+ hub, it enables marketing to say for example do underline on this word, and it then be applied across all 3 platforms identically without them having to write content for 3 platforms separately. It has no other intended use case beyond this.

The way styles are applied obviously differ per platform and therefore we needed a cross platform way of doing it, android went first as they already had a library, web is copying their approach.