feat: W3C DTCG v2025.10 design tokens compliance - #67
Merged
Conversation
…export Refactor W3CTokensExporter to support v2025 and v1 (legacy) versions: - Color $value uses structured color objects (colorSpace, components, alpha, hex) - Multi-mode colors use $extensions.com.exfig.modes - Assets use $extensions.com.exfig.assetUrl instead of invented $type: "asset" - Typography decomposed into sub-tokens (fontFamily, fontSize, lineHeight, letterSpacing) - Add --w3c-version v1|v2025 flag (default: v2025) to all download commands - Add ColorTokenMetadata for Figma variableId/fileId in $extensions - V1 preserves all legacy behavior for backward compatibility Implements tasks 1.1-1.7, 2.1-2.5, 4.1-4.3, 6.1-6.7 from w3c-tokens-v2 change. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Extend ColorsVariablesLoader to propagate alias paths, descriptions,
and metadata. Implement "{Group.Token}" W3C alias syntax in color
export with stable mode ordering and per-mode alias resolution.
Refactor exportColorsV2025 to extract helper methods.
Tasks: 3.1-3.5
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ping Create NumberVariablesLoader to load FLOAT variables from Figma and classify them as dimension or number based on variable scopes. Add exportDimensions() and exportNumbers() to W3CTokensExporter. Add resolvedType and scopes fields to VariableValue model. Tasks: 5.1-5.6 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Create DownloadTokens command that exports colors, typography, dimensions, and numbers into a single W3C JSON file with deep-merge. Add integration test for unified token output. Tasks: 7.1-7.3 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
TokensFileSource parses W3C Design Token Community Group JSON files with nested group parsing, $type inheritance, alias resolution with circular reference detection, $root/$deprecated support, non-sRGB color space warnings, and model mapping to ExFigCore types. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…(tasks 9.1-9.6) Add Common.TokensFile PKL class with path and groupFilter fields. When tokensFile is set on a colors entry, the pipeline reads from a local .tokens.json file instead of Figma API. Includes codegen, bridging, validation, and integration tests. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Move completed change to archive, sync delta specs (design-tokens-export, tokens-file-source) to main specs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Update CLAUDE.md files, DocC (Usage, Configuration, ExFig), and README with new download tokens command, TokensFile source, W3C v2025 format, NumberToken type, and local .tokens.json import. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Summary of ChangesHello @alexey1312, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the design token export capabilities by aligning with the latest W3C DTCG v2025.10 specification. It introduces a more structured and compliant output format for colors, supports advanced token alias resolution, and expands token types to include dimensions and numbers. A new unified command simplifies the export process, and a local file parser allows for offline workflows, reducing reliance on the Figma API. These changes provide greater flexibility and adherence to modern design token standards. Highlights
Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This is an impressive and substantial feature addition that brings the tool's design token support up to the latest W3C standard. The changes are well-structured across multiple phases, including export compliance, token type expansion, and a new local file import capability. The introduction of the unified download tokens command and the TokensFileSource parser are great additions that significantly enhance the tool's flexibility and enable offline workflows.
The test coverage for the new functionality, especially for the token parser and the new exporter logic, is excellent and very thorough. The documentation updates across README.md, CLAUDE.md, and DocC are also clear and comprehensive.
I have one main piece of feedback regarding the implementation of the new .tokens.json parser, which deviates from the repository's established conventions for JSON processing. Please see the specific comment for details.
Addresses PR #67 review feedback: TokensFileSource now uses the project's JSONCodec/YYJSON for parsing instead of Foundation's JSONSerialization. - Add JSONValue/JSONObject/JSONArray typealiases and parseValue(from:) to JSONCodec for untyped DOM access without direct YYJSON imports - Refactor TokensFileSource to use JSONValue subscripts (.string, .number, .array, .object) instead of [String: Any] casts - Change ParsedToken.extensions from [String: Any]? to JSONValue? - Simplify ParsedTokenValue.unknown by removing unused Any payload Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Critical: guard `sortedModeColors.first` instead of force subscript [0], add summary warning for .unknown tokens after alias resolution with assert(isResolved) precondition on all mapping methods. Error handling: add depth limit (10) to ColorsVariablesLoader.handleColorMode to prevent stack overflow on circular aliases, warn about skipped sections in `download tokens` with error on empty output, distinguish depth-exceeded from unresolved in NumberVariablesLoader via ResolveResult enum, warn on non-string fontFamily entries and unexpected $deprecated types, warn when local tokens file ignores mode config. Type safety: make NumberToken.variableId/fileId optional (String?), conditionally emit $extensions in W3C exporter, make insertToken private. Docs: fix $extends claim (not implemented, now emits warning), fix colorToHex doc RGBA→RGB, remove 13 Task X.Y references, fix --output required→optional in DocC, fix NumberToken location in CLAUDE.md, fix MEMORY.md scope classification. Code quality: simplify scopesToTokenType, remove basePath alias, replace test deepMerge helper with production mergeTokens, add swiftlint:enable file_length to W3CTokensExporter.
Config-free CLI for working with W3C DTCG .tokens.json files directly, without PKL config or Figma token. Includes `info` (inspect) and `convert` (filter/re-export) subcommands. - Add `exfig tokens info` with human-readable and --json output - Add `exfig tokens convert` with --group, --type, --w3c-version, --compact - Add filtering/statistics methods to TokensFileSource - Move mergeTokens to W3CTokensExporter as shared static method - Update README with new tokens commands
- Replace JSONSerialization with JSONCodec via Codable TokensInfoReport - Use FileHandle.standardOutput instead of print() for data output - Rename resolvedAliasCount → aliasCount for accuracy - Extract W3CTokensExporter.exportAll(from:) to eliminate duplication - Add stable secondary sort by name in topLevelGroups() - Add combined group+type filter test
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
1 participant
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.
Description
colorSpace,components,alpha,hex) alongside legacy v1 hex strings"{Group.Token}"W3C reference syntax and circular reference detectiondownload tokenssubcommand that exports colors, typography, dimensions, and numbers into a single W3C JSON file.tokens.jsonparser (TokensFileSource) supporting nested groups,$typeinheritance,$root,$deprecated, and non-sRGB warningsCommon.TokensFileclass — bypasses Figma API whentokensFileis set on a colors entryAdditional notes
.tokens.jsonimport--w3c-versionflag selects v1 (legacy) or v2025 (default) formattokensFilesource enables use withoutFIGMA_PERSONAL_TOKENfor teams using Tokens Studio or similar tools