Merged
Conversation
🦋 Changeset detectedLatest commit: 00fefa2 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
Contributor
Design Token Diff (CSS)
|
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the generated LLM/design-token documentation output to include richer metadata and a more compact, “spec-like” markdown format, and wires a new build step to produce that spec file.
Changes:
- Refactors
markdownLlmGuidelinesoutput structure (Semantic Key section, category metadata, typography tables, pattern compression, shorthand fields). - Introduces a dedicated
build:llmscript to generateDESIGN_TOKENS_SPEC.mdand updates packaging/gitignore accordingly. - Adds a CSS header referencing the spec file to
primitives.cssand theme CSS outputs.
Reviewed changes
Copilot reviewed 5 out of 6 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src/formats/markdownLlmGuidelines.ts | Major rewrite of the markdown generator (semantic metadata tables, compression/grouping logic, new output format). |
| src/formats/markdownLlmGuidelines.test.ts | Updates/adds unit tests for the new output shape and shorthands. |
| scripts/buildTokens.ts | Removes combined LLM build and adds spec header injection into CSS outputs. |
| scripts/buildLlm.ts | New script to generate DESIGN_TOKENS_SPEC.md via Style Dictionary platform. |
| package.json | Adds build:llm step to build and includes DESIGN_TOKENS_SPEC.md in published files. |
| .gitignore | Ignores generated DESIGN_TOKENS_SPEC.md. |
Comments suppressed due to low confidence (7)
src/formats/markdownLlmGuidelines.ts:631
createCrossCategyBracketNotationis unused and will fail lint under@typescript-eslint/no-unused-vars. Also, the name appears to have a typo ("Categy" -> "Category"), which will be confusing if/when it is used. Either remove it or rename+use it for the wildcard semantic pattern output.
function createCrossCategyBracketNotation(
entries: {subcategory: string; variant: string; guideline: LlmGuideline}[],
): {name: string; guideline: LlmGuideline}[] {
// Group by subcategory + description + rules (normalized)
const groups: Map<string, {subcategory: string; variants: string[]; guideline: LlmGuideline}> = new Map()
src/formats/markdownLlmGuidelines.ts:678
- The formatter now always emits the full document header/Legend/Semantic Key even when
guidelinesis empty (no tokens withorg.primer.llm). Existing unit tests in this repo expect an early return with only the header in that case. Either reintroduce an early return whenguidelines.length === 0, or update the tests to match the new intended behavior.
export const markdownLlmGuidelines: FormatFn = async ({dictionary}: FormatFnArguments) => {
const tokens = dictionary.allTokens.sort(sortByName)
const guidelines: LlmGuideline[] = []
src/formats/markdownLlmGuidelines.ts:431
guideline.usage?.sort()mutates theusagearray in-place. Sinceusageis later rendered, this can silently reorder usage items and also couples key creation with output ordering. Use a non-mutating sort (e.g. sort a copy) when building grouping keys.
function createGuidelineKey(guideline: LlmGuideline): string {
return JSON.stringify({
category: guideline.category,
description: guideline.description || '',
usage: guideline.usage?.sort() || [],
src/formats/markdownLlmGuidelines.test.ts:248
CATEGORY_INFO.fgColor.nameisForeground Colors, but this assertion expects## Text. Update the expected heading (or adjustCATEGORY_INFO.fgColor.nameifTextis the intended label).
expect(result).toContain('## Text')
src/formats/markdownLlmGuidelines.ts:387
getTypographyRoleis declared but never used in this file. With@typescript-eslint/no-unused-varsenabled, this will failnpm run lint. Either use it in the typography output logic or remove it.
function getTypographyRole(tokenName: string): string | null {
for (const {role, patterns} of TYPOGRAPHY_ROLES) {
if (patterns.some(pattern => tokenName.startsWith(pattern))) {
return role
}
src/formats/markdownLlmGuidelines.ts:581
createBracketNotationis declared but never used. With@typescript-eslint/no-unused-varsenabled, this will fail lint. Either wire it into the semantic token rendering (which also aligns with the bracket-notation expectations in tests) or remove it.
function createBracketNotation(tokens: LlmGuideline[]): {name: string; guideline: LlmGuideline}[] {
// Group by category + subcategory + description + rules
const groups: Map<string, LlmGuideline[]> = new Map()
for (const token of tokens) {
src/formats/markdownLlmGuidelines.test.ts:31
- These expectations appear out of sync with the formatter output after this PR: the formatter now emits
# Primer Design Token Guidelinesand category headings like## Border Width(with a space) rather than# Token Guidelines/## BorderWidth. Update the assertions to match the new output so the unit test reflects the intended format.
expect(result).toContain('# Token Guidelines')
expect(result).toContain('## BorderWidth')
expect(result).toContain('### borderWidth-thick')
expect(result).toContain('Thick 2px border for emphasis')
expect(result).toContain('**U:** focus-indicator, selected-state')
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Merged
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
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.
Add more meta data and update how it is compiled to an md file.