Guidelines #1295
Open
Guidelines #1295
Conversation
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
|
Contributor
Design Token Diff (CSS)The message is too long to be displayed here. For more details, please check the job summary. |
Contributor
Design Token Diff (StyleLint)The message is too long to be displayed here. For more details, please check the job summary. |
Contributor
Design Token Diff (Figma)
|
Contributor
Design Token Diff (Fallbacks)
|
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request adds LLM (Large Language Model) guidelines functionality to design tokens, enabling AI assistants to understand proper token usage through structured metadata. The implementation creates a new extension namespace (org.primer.llm) in design tokens and generates a dedicated JSON file with usage guidelines.
Changes:
- Added
org.primer.llmextension schema and integration across token types - Created new filter, format, and platform for generating LLM guidelines output
- Added LLM usage metadata to typography, sizing, color, shadow, and motion tokens
- Moved font stack definitions to a separate file and added LLM guidelines
- Created human-readable markdown guideline documents for typography, spacing, motion, and color
Reviewed changes
Copilot reviewed 49 out of 52 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
src/schemas/llmExtension.ts |
New Zod schema defining LLM extension structure (usage array, rules string) |
src/filters/hasLlmExtensions.ts |
Filter to identify tokens with LLM extensions |
src/formats/jsonLlmGuidelines.ts |
Formatter outputting flat JSON with token guidelines |
src/platforms/llmGuidelines.ts |
Platform configuration for LLM guidelines output |
src/tokens/functional/typography/typography.json5 |
Added LLM extensions to typography tokens; has critical syntax errors |
src/tokens/functional/typography/font-stack.json5 |
New file extracting font stacks with LLM guidelines |
src/tokens/functional/size/radius.json5 |
New file for border radius tokens with LLM guidelines; has documentation conflicts |
src/tokens/functional/size/border.json5 |
Added descriptions and LLM extensions to border tokens |
src/tokens/functional/shadow/shadow.json5 |
Added LLM extensions to shadow tokens |
src/tokens/functional/color/bgColor.json5 |
Added LLM extensions to background color tokens |
src/tokens/base/motion/easing.json5 |
Added LLM extensions to easing curve tokens |
src/schemas/*Token.ts |
Added optional LLM extension support to multiple token schemas |
scripts/buildTokens.ts |
Added LLM guidelines build step |
scripts/buildFigma.ts |
Updated to include new font-stack file |
contributor-docs/llm-token-guidelines.md |
Documentation using incorrect namespace (org.primer.ai vs org.primer.llm) |
guidelines/*.llm.md |
Human-readable guideline documents for various design areas |
.gitignore |
Has critical syntax error preventing proper file exclusion |
package.json |
Added output files to package distribution |
package-lock.json |
Unrelated peer dependency flag removals |
Comments suppressed due to low confidence (1)
src/tokens/functional/typography/typography.json5:458
- Missing line break between the closing brace of $extensions and the closing brace of the shorthand object. Line 458 has two closing braces that should be on separate lines for proper JSON5 formatting.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+41
to
+54
| $description: 'Large border radius (12px). Use for larger containers, dialogs, or when more visual softness is desired. Always use this for buttons.', | ||
| $type: 'dimension', | ||
| $extensions: { | ||
| 'org.primer.figma': { | ||
| collection: 'functional/size', | ||
| scopes: ['radius'], | ||
| codeSyntax: { | ||
| web: 'var(--borderRadius-large) /* utility class: .rounded-3 */', | ||
| }, | ||
| }, | ||
| 'org.primer.llm': { | ||
| usage: ['dialog', 'card', 'modal'], | ||
| rules: 'Recommended for dialogs and modals.', | ||
| }, |
There was a problem hiding this comment.
Conflicting guidance for button border radius. The description on line 41 states "Always use this for buttons" but the llm usage array on line 52 doesn't include 'button', and line 34 shows 'button' is listed under medium radius. Additionally, line 17 explicitly says "Do NOT use for buttons or cards" for small radius, but line 52 includes 'card' in the usage for large radius. This creates inconsistent guidance across the three radius sizes.
Comment on lines
+1
to
+147
| # AI Token Guidelines | ||
|
|
||
| This document describes how to add AI-specific usage guidelines to design tokens for consumption by AI assistants like GitHub Copilot. | ||
|
|
||
| ## Overview | ||
|
|
||
| AI Token Guidelines is a feature that outputs a dedicated JSON file (`dist/ai/ai-token-guidelines.json`) containing usage guidelines for AI assistants. This file helps AI tools understand how and when to use specific design tokens. | ||
|
|
||
| ## Source Format | ||
|
|
||
| Add AI guidelines to tokens using the `$extensions['org.primer.ai']` namespace, following the existing pattern for Figma extensions: | ||
|
|
||
| ```json5 | ||
| { | ||
| borderRadius: { | ||
| large: { | ||
| $value: '12px', | ||
| $type: 'dimension', | ||
| $description: 'Large border radius (12px). Use for larger containers, dialogs, or when more visual softness is desired.', | ||
| $extensions: { | ||
| 'org.primer.figma': { /* existing Figma extensions */ }, | ||
| 'org.primer.ai': { | ||
| usage: ['button', 'dialog', 'card', 'modal'], | ||
| rules: 'MUST use for all buttons. Recommended for dialogs and modals.', | ||
| }, | ||
| }, | ||
| }, | ||
| }, | ||
| } | ||
| ``` | ||
|
|
||
| ### Extension Properties | ||
|
|
||
| | Property | Type | Description | | ||
| |----------|------|-------------| | ||
| | `usage` | `string[]` | Array of use cases where this token applies | | ||
| | `rules` | `string` | Prescriptive guidance using RFC 2119 keywords (MUST, SHOULD, etc.) | | ||
|
|
||
| The `$description` field from the token itself is also included in the output. | ||
|
|
||
| ## Output Format | ||
|
|
||
| The build process generates `dist/ai/ai-token-guidelines.json` with a flat structure: | ||
|
|
||
| ```json | ||
| { | ||
| "borderRadius-large": { | ||
| "description": "Large border radius (12px). Use for larger containers, dialogs, or when more visual softness is desired.", | ||
| "usage": ["button", "dialog", "card", "modal"], | ||
| "rules": "MUST use for all buttons. Recommended for dialogs and modals." | ||
| }, | ||
| "borderWidth-thick": { | ||
| "description": "Thick 2px border for emphasis...", | ||
| "usage": ["focus-indicator", "selected-state"], | ||
| "rules": "MUST use for focus rings on interactive elements." | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Adding AI Guidelines to Tokens | ||
|
|
||
| ### Step 1: Identify High-Priority Tokens | ||
|
|
||
| Focus on tokens where AI assistants commonly make mistakes or need explicit guidance: | ||
| - Focus indicators and accessibility-related tokens | ||
| - Semantic color tokens (danger, success, accent) | ||
| - Border radius for specific component types | ||
| - Shadow tokens for elevation hierarchy | ||
|
|
||
| ### Step 2: Add the Extension | ||
|
|
||
| Add `org.primer.ai` to the token's `$extensions`: | ||
|
|
||
| ```json5 | ||
| { | ||
| bgColor: { | ||
| danger: { | ||
| emphasis: { | ||
| $value: '{base.color.red.5}', | ||
| $type: 'color', | ||
| $description: 'Emphasized danger background for critical errors', | ||
| $extensions: { | ||
| 'org.primer.figma': { /* ... */ }, | ||
| 'org.primer.ai': { | ||
| usage: ['delete-button', 'critical-alert'], | ||
| rules: 'MUST use for destructive action buttons. Use fgColor.onEmphasis for text.', | ||
| }, | ||
| }, | ||
| }, | ||
| }, | ||
| }, | ||
| } | ||
| ``` | ||
|
|
||
| ### Step 3: Build and Verify | ||
|
|
||
| ```bash | ||
| npm run build:tokens | ||
| ``` | ||
|
|
||
| Check that your token appears in `dist/ai/ai-token-guidelines.json`. | ||
|
|
||
| ## Best Practices | ||
|
|
||
| ### Writing Good Usage Arrays | ||
|
|
||
| - Use lowercase, hyphenated terms: `focus-indicator`, `delete-button` | ||
| - Be specific about component types: `modal` instead of `overlay` | ||
| - Include common synonyms if helpful | ||
|
|
||
| ### Writing Effective Rules | ||
|
|
||
| Use RFC 2119 keywords for clarity: | ||
| - **MUST** - Absolute requirement | ||
| - **MUST NOT** - Absolute prohibition | ||
| - **SHOULD** - Recommended but not required | ||
| - **SHOULD NOT** - Discouraged but not prohibited | ||
| - **MAY** - Optional | ||
|
|
||
| Example rules: | ||
| - ✅ "MUST use for focus rings on interactive elements" | ||
| - ✅ "Do NOT use for subtle dividers" | ||
| - ✅ "SHOULD pair with fgColor.onEmphasis for text" | ||
| - ❌ "Use this for buttons" (too vague, no clear directive) | ||
|
|
||
| ## Architecture | ||
|
|
||
| ### Files | ||
|
|
||
| | File | Purpose | | ||
| |------|---------| | ||
| | `src/filters/hasAiExtensions.ts` | Filter for tokens with `org.primer.ai` | | ||
| | `src/formats/jsonAiGuidelines.ts` | Format outputting flat AI-optimized JSON | | ||
| | `src/platforms/aiGuidelines.ts` | Platform configuration | | ||
|
|
||
| ### Build Integration | ||
|
|
||
| The AI guidelines build step in `scripts/buildTokens.ts` processes all functional tokens and outputs only those with AI extensions. | ||
|
|
||
| ## Testing | ||
|
|
||
| Run the tests to verify your changes: | ||
|
|
||
| ```bash | ||
| npm test -- src/filters/hasAiExtensions.test.ts | ||
| npm test -- src/formats/jsonAiGuidelines.test.ts | ||
| ``` |
There was a problem hiding this comment.
Documentation references 'org.primer.ai' but the actual implementation uses 'org.primer.llm'. The documentation consistently refers to the extension namespace as 'org.primer.ai' throughout, but all code files (schemas, filters, formats) use 'org.primer.llm'. This creates confusion and will mislead contributors.
Comment on lines
+1
to
+50
| { | ||
| "base": { | ||
| "color": { | ||
| "aquaBlue": { | ||
| "500": { | ||
| "key": "{base.color.aquaBlue.500}", | ||
| "$value": "#2C29FF", | ||
| "$type": "color", | ||
| "$description": "The primary color for interactive elements.", | ||
| "filePath": "integration/tokens/base.json5", | ||
| "isSource": true, | ||
| "original": { | ||
| "$value": "#2C29FF", | ||
| "$type": "color", | ||
| "$description": "The primary color for interactive elements.", | ||
| "key": "{base.color.aquaBlue.500}" | ||
| }, | ||
| "name": "500", | ||
| "attributes": {}, | ||
| "path": [ | ||
| "base", | ||
| "color", | ||
| "aquaBlue", | ||
| "500" | ||
| ] | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "fgColor": { | ||
| "link-rest-01": { | ||
| "key": "{fgColor.link-rest-01}", | ||
| "$value": "#2C29FF", | ||
| "$type": "color", | ||
| "filePath": "integration/tokens/functional.json5", | ||
| "isSource": true, | ||
| "original": { | ||
| "$value": "{base.color.aquaBlue.500}", | ||
| "$type": "color", | ||
| "key": "{fgColor.link-rest-01}" | ||
| }, | ||
| "name": "link-rest-01", | ||
| "attributes": {}, | ||
| "path": [ | ||
| "fgColor", | ||
| "link-rest-01" | ||
| ] | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
These integration build files appear to be generated test artifacts that should be excluded by .gitignore. The .gitignore file has a syntax error on line 10 that prevents "integration/build" from being properly ignored. Once the .gitignore syntax is fixed, these files should not be tracked in version control.
| $type: 'typography', | ||
| $description: 'Compact small font with a smaller line height of 16px. Use it for single-line scenarios, as the small sizing doesn’t pass accessibility requirements.', | ||
| }, | ||
| $description: 'Compact small font with a smaller line height of 16px. Use it for single-line scenarios, as the small sizing doesn’t pass accessibility requirements.', $extensions: { |
There was a problem hiding this comment.
Missing line break between the closing brace of $description and the $extensions property. The $description string on line 453 runs directly into the $extensions object on line 453 without proper JSON5 formatting. These should be on separate lines.
This issue also appears in the following locations of the same file:
- line 458
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.
Summary
List of notable changes:
What should reviewers focus on?
Steps to test: