# primer/primitives architecture

> Architecture diagram of the GitHub repository primer/primitives, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/primer/primitives
- Repository: https://github.com/primer/primitives

## Overview

Primer Primitives is a design-token library for Primer. Token data is configured and processed through its Style Dictionary extensions, then emitted in formats for CSS, JavaScript/TypeScript, Figma, documentation, fallbacks, and LLM guidance. The README documents the token and theme workflow, but the listed tree omits `src/tokens`; edges from token data are therefore shown without assigning it an unsupported repository path. The sampled files confirm the LLM filtering and formatting branch; other platform wiring is represented only at the documented capability level.

Main entry points: [`src/primerStyleDictionary.ts`](https://github.com/primer/primitives/blob/main/src/primerStyleDictionary.ts) (Dictionary config), [`src/platforms/llmGuidelines.ts`](https://github.com/primer/primitives/blob/main/src/platforms/llmGuidelines.ts) (LLM guidelines), [`src/preprocessors/themeOverrides.ts`](https://github.com/primer/primitives/blob/main/src/preprocessors/themeOverrides.ts) (Theme preprocessors), [`src/platforms/css.ts`](https://github.com/primer/primitives/blob/main/src/platforms/css.ts) (CSS platform)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Token processing"]
  node_dictionary["Dictionary config"]
  node_preprocessors["Theme preprocessors<br/>[themeOverrides.ts]"]
  node_inheritance["Group inheritance"]
  node_filters["Token filters<br/>[index.ts]"]
  node_transformers["Token transforms<br/>[index.ts]"]
end

subgraph group_outputs["Token outputs"]
  node_css["CSS platform<br/>[css.ts]"]
  node_themes["Theme CSS<br/>[index.ts]"]
  node_javascript["JavaScript exports<br/>[javascript.ts]"]
  node_typescript["TypeScript exports<br/>[typescript.ts]"]
  node_figma["Figma export<br/>[figma.ts]"]
  node_fallbacks["Fallback values<br/>[fallbacks.ts]"]
  node_deprecated["Deprecated tokens<br/>[deprecatedJson.ts]"]
  node_docs["Documentation JSON<br/>[docJson.ts]"]
  node_llm["LLM guidelines<br/>[llmGuidelines.ts]"]
  node_llmformat["Guideline formatter"]
end

subgraph group_metadata["Validation and metadata"]
  node_schemas["Token schemas<br/>[designToken.ts]"]
  node_llmfilter["LLM extension filter"]
end

node_author(("Token author"))
node_consumer(("Primer consumers"))
node_figmausers(("Figma users"))

node_author -->|"provides tokens"| node_dictionary
node_dictionary -->|"validates tokens"| node_schemas
node_dictionary -->|"configures themes"| node_preprocessors
node_preprocessors -->|"inherits properties"| node_inheritance
node_dictionary -->|"selects tokens"| node_filters
node_dictionary -->|"transforms tokens"| node_transformers
node_dictionary -->|"builds CSS"| node_css
node_dictionary -->|"builds themes"| node_themes
node_dictionary -->|"builds exports"| node_javascript
node_dictionary -->|"builds definitions"| node_typescript
node_dictionary -->|"builds export"| node_figma
node_dictionary -->|"builds fallbacks"| node_fallbacks
node_dictionary -->|"builds JSON"| node_deprecated
node_dictionary -->|"builds JSON"| node_docs
node_dictionary -->|"configures platform"| node_llm
node_llm -->|"filters tokens"| node_llmfilter
node_llm -->|"formats guidelines"| node_llmformat
node_css -->|"provides variables"| node_consumer
node_themes -->|"provides themes"| node_consumer
node_javascript -->|"provides exports"| node_consumer
node_typescript -->|"provides types"| node_consumer
node_figma -->|"provides token data"| node_figmausers

click node_dictionary "https://github.com/primer/primitives/blob/main/src/primerStyleDictionary.ts"
click node_preprocessors "https://github.com/primer/primitives/blob/main/src/preprocessors/themeOverrides.ts"
click node_inheritance "https://github.com/primer/primitives/blob/main/src/preprocessors/inheritGroupProperties.ts"
click node_filters "https://github.com/primer/primitives/blob/main/src/filters/index.ts"
click node_transformers "https://github.com/primer/primitives/blob/main/src/transformers/index.ts"
click node_schemas "https://github.com/primer/primitives/blob/main/src/schemas/designToken.ts"
click node_css "https://github.com/primer/primitives/blob/main/src/platforms/css.ts"
click node_themes "https://github.com/primer/primitives/blob/main/src/platforms/index.ts"
click node_javascript "https://github.com/primer/primitives/blob/main/src/platforms/javascript.ts"
click node_typescript "https://github.com/primer/primitives/blob/main/src/platforms/typescript.ts"
click node_figma "https://github.com/primer/primitives/blob/main/src/platforms/figma.ts"
click node_fallbacks "https://github.com/primer/primitives/blob/main/src/platforms/fallbacks.ts"
click node_deprecated "https://github.com/primer/primitives/blob/main/src/platforms/deprecatedJson.ts"
click node_docs "https://github.com/primer/primitives/blob/main/src/platforms/docJson.ts"
click node_llm "https://github.com/primer/primitives/blob/main/src/platforms/llmGuidelines.ts"
click node_llmfilter "https://github.com/primer/primitives/blob/main/src/filters/hasLlmExtensions.ts"
click node_llmformat "https://github.com/primer/primitives/blob/main/src/formats/markdownLlmGuidelines.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dictionary,node_preprocessors,node_inheritance,node_filters,node_transformers,node_figmausers toneBlue
class node_css,node_themes,node_javascript,node_typescript,node_figma,node_fallbacks,node_deprecated,node_docs,node_llm,node_llmformat toneAmber
class node_schemas,node_llmfilter toneMint
class node_author,node_consumer toneIndigo
```

## Components

### Token processing

- [Dictionary config](https://github.com/primer/primitives/blob/main/src/primerStyleDictionary.ts): `src/primerStyleDictionary.ts`
- [Theme preprocessors](https://github.com/primer/primitives/blob/main/src/preprocessors/themeOverrides.ts): `src/preprocessors/themeOverrides.ts`
- [Group inheritance](https://github.com/primer/primitives/blob/main/src/preprocessors/inheritGroupProperties.ts): `src/preprocessors/inheritGroupProperties.ts`
- [Token filters](https://github.com/primer/primitives/blob/main/src/filters/index.ts): `src/filters/index.ts`
- [Token transforms](https://github.com/primer/primitives/blob/main/src/transformers/index.ts): `src/transformers/index.ts`

### Token outputs

- [CSS platform](https://github.com/primer/primitives/blob/main/src/platforms/css.ts): `src/platforms/css.ts`
- [Theme CSS](https://github.com/primer/primitives/blob/main/src/platforms/index.ts): `src/platforms/index.ts`
- [JavaScript exports](https://github.com/primer/primitives/blob/main/src/platforms/javascript.ts): `src/platforms/javascript.ts`
- [TypeScript exports](https://github.com/primer/primitives/blob/main/src/platforms/typescript.ts): `src/platforms/typescript.ts`
- [Figma export](https://github.com/primer/primitives/blob/main/src/platforms/figma.ts): `src/platforms/figma.ts`
- [Fallback values](https://github.com/primer/primitives/blob/main/src/platforms/fallbacks.ts): `src/platforms/fallbacks.ts`
- [Deprecated tokens](https://github.com/primer/primitives/blob/main/src/platforms/deprecatedJson.ts): `src/platforms/deprecatedJson.ts`
- [Documentation JSON](https://github.com/primer/primitives/blob/main/src/platforms/docJson.ts): `src/platforms/docJson.ts`
- [LLM guidelines](https://github.com/primer/primitives/blob/main/src/platforms/llmGuidelines.ts): `src/platforms/llmGuidelines.ts`
- [Guideline formatter](https://github.com/primer/primitives/blob/main/src/formats/markdownLlmGuidelines.ts): `src/formats/markdownLlmGuidelines.ts`

### Validation and metadata

- [Token schemas](https://github.com/primer/primitives/blob/main/src/schemas/designToken.ts): `src/schemas/designToken.ts`
- [LLM extension filter](https://github.com/primer/primitives/blob/main/src/filters/hasLlmExtensions.ts): `src/filters/hasLlmExtensions.ts`

### Other components

- **Token author**
- **Primer consumers**
- **Figma users**

## Connections

- Token author → Dictionary config: provides tokens
- Dictionary config → Token schemas: validates tokens
- Dictionary config → Theme preprocessors: configures themes
- Theme preprocessors → Group inheritance: inherits properties
- Dictionary config → Token filters: selects tokens
- Dictionary config → Token transforms: transforms tokens
- Dictionary config → CSS platform: builds CSS
- Dictionary config → Theme CSS: builds themes
- Dictionary config → JavaScript exports: builds exports
- Dictionary config → TypeScript exports: builds definitions
- Dictionary config → Figma export: builds export
- Dictionary config → Fallback values: builds fallbacks
- Dictionary config → Deprecated tokens: builds JSON
- Dictionary config → Documentation JSON: builds JSON
- Dictionary config → LLM guidelines: configures platform
- LLM guidelines → LLM extension filter: filters tokens
- LLM guidelines → Guideline formatter: formats guidelines
- CSS platform → Primer consumers: provides variables
- Theme CSS → Primer consumers: provides themes
- JavaScript exports → Primer consumers: provides exports
- TypeScript exports → Primer consumers: provides types
- Figma export → Figma users: provides token data