Add API support for design tokens

[wise-king-sullyman]

Problem Statement

PatternFly design tokens are available in @patternfly/react-tokens but there is no API endpoint to fetch them programmatically.

Key Requirement: The API must support fine-grained filtering to minimize response size for MCP/LLM consumption, reducing context bloat when fetching tokens.

Goal

Create API endpoints that expose global design tokens with a hierarchical structure consistent with existing API patterns, enabling MCPs and other consumers to fetch only the specific tokens they need.

Proposed Solution

Add design token endpoints following the existing API hierarchy pattern:

• GET /api/v6/tokens → Returns list of available token categories
• GET /api/v6/tokens/[category] → Returns tokens for a specific category
• GET /api/v6/tokens/[category]?filter=brand → Returns filtered tokens for a specific category
• GET /api/v6/tokens/all → Returns all tokens

Completion Criteria

• API Routes Created

  • Create /api/[version]/tokens/index.ts route returning array of available categories
  • Create /api/[version]/tokens/[category].ts route returning tokens for a specific category
  • Create /api/[version]/tokens/all.ts route returning all tokens grouped by category

• Route: /api/[version]/tokens (index)

  • Returns JSON array of category names
  • Categories sorted alphabetically

• Route: /api/[version]/tokens/[category]

  • Returns JSON array of token objects for the specified category
  • Each token: { name: string, value: string, var: string }
  • Return 404 if category doesn't exist
  • Support ?filter= query parameter for case-insensitive substring match on token name
  • Filter returns matching tokens or empty array (not an error)
  • This is the RECOMMENDED endpoint for MCP usage

• Route: /api/[version]/tokens/all

  • Returns JSON object with all tokens
  • Support ?filter= query parameter to filter across all categories

• Error Handling

  • Return 404 when category doesn't exist with list of valid categories
  • Return empty array/object when filter yields no matches (not an error)
  • Return appropriate error messages for invalid paths
  • Handle cases where tokens module is not available

• Documentation

  • Update src/pages/api/[version]/index.ts endpoints array with all token endpoints
  • Document all available categories
  • Document filter query parameter with examples
  • Add section on "Efficient Usage for MCPs" recommending category-specific endpoints with filtering
  • Add example flow in usage section showing token endpoints
  • Update README.mdx with new token API endpoints
  • Update OpenAPI spec in /api/openapi.json.ts if applicable

• Testing

  • Add tests for /api/[version]/tokens index route
  • Add tests for /api/[version]/tokens/[category] route (multiple categories)
  • Add tests for /api/[version]/tokens/[category]?filter= route
  • Add tests for /api/[version]/tokens/all route (verify ~773 tokens)
  • Add tests for /api/[version]/tokens/all?filter= route
  • Test filter matching (case-insensitive, substring)
  • Test error cases (invalid category, invalid paths)
  • Test empty filter results
  • Verify all expected categories are present

Out of Scope

• Component-specific CSS variables (covered in issue Add API support for CSS variables #171)
• Advanced filtering (regex, multiple filters, etc.) - can be added later if needed

---

Jira Issue: PF-2809

[github-actions]

🎉 This issue has been resolved in version 1.17.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀