feat(web): generate literal-union TS types for token paths#27
Open
Gr1dlock wants to merge 2 commits into
Open
Conversation
The published web package shipped `index.d.ts` as
`declare const tokens: Record<string, string>`, so consumers got no
compile-time safety when referencing token paths.
Generate `index.d.ts` from the token definitions instead, emitting:
- `ColorToken` — every canonical color path (`semantic.color.text.primary`,
`primitive.color.grey.950`, …)
- `TypographyToken` — grouped `typography.{category}.{id}` paths, with the
category derived from the font-token id prefix (UI Kit 5 grouping)
The default `tokens: Record<string, string>` export is kept for back-compat.
`index.d.ts` is now produced by the build (build/types.ts + formats/types-web.ts)
rather than copied from a static template.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jun 2, 2026
UI Kit 4.0 names the category 'Number' and has no 'caption'. Emit typography.number.* (not numeric) and drop the unused caption mapping. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
jaidensiu
approved these changes
Jun 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The published web package shipped
index.d.tsasdeclare const tokens: Record<string, string>, so consumers (e.g. the app-backend SDUI V4 library, which references tokens by their canonical path) got no compile-time safety — any string passed.This generates
index.d.tsfrom the token definitions, emitting literal-union types:ColorToken— every canonical color path:semantic.color.text.primary,semantic.color.border.translucent,primitive.color.grey.950, …TypographyToken— groupedtypography.{category}.{id}paths (typography.headline.h1,typography.body.b2, …). The category (display/numeric/headline/subtitle/label/body/caption) is derived from the font-token id prefix, matching the UI Kit 5 grouping.The default
tokens: Record<string, string>export is preserved for backward compatibility.Changes
tokens/formats/types-web.ts— new generator (path → literal-union types)tokens/build/types.ts—buildWebTypes()loads color + font definitions, writesbuild/web/index.d.tstokens/build/index.ts— runsbuildWebTypes()in the buildtokens/build/web-package.ts— stop copying the staticindex.d.ts(now generated)tokens/templates/web/index.d.tsNotes
index.d.tslands inbuild/web(the published artifact), same as the other web outputs — no committed generated file.import type { ColorToken, TypographyToken } from '@worldcoin/nucleus'andsatisfiestheir token maps against them.npm run build,typecheck,lint,format:checkall pass.Part of adopting Nucleus tokens in app-backend SDUI V4.
🤖 Generated with Claude Code