Design Tokens API

The designTokens query returns your project’s design tokens — both the raw W3C Design Tokens Format Module document and a flat, server-resolved view. Use the resolved arrays at runtime; use source for build-time tooling like Style Dictionary.

For the feature overview, see Design Tokens. For the config shape, see Defining Design Tokens.

Query


query DesignTokens {
  designTokens {
    source
 
    colors          { path name description value }
    fontFamilies    { path name description value }
    fontWeights     { path name description value }
    fontSizes       { path name description value }
    lineHeights     { path name description value }
    letterSpacings  { path name description value }
    typography {
      path
      name
      description
      label
      tag
      value {
        fontFamily
        fontSize
        fontWeight
        lineHeight
        letterSpacing
        textTransform
      }
    }
    spacings        { path name description value }
    radii           { path name description value }
    shadows {
      path
      name
      description
      layers {
        offsetX
        offsetY
        blur
        spread
        color
        inset
      }
    }
    borders {
      path
      name
      description
      value { color width style }
    }
  }
}

No arguments. The query is scoped to the project of the API key making the request.

Channels

By default the query reads the published snapshot — the storefront-safe one. To preview unpublished edits, send the X-Foir-Schema-Channel: draft header on a request authenticated with a key that holds the drafts:read scope.


POST /graphql HTTP/1.1
Host: api.foir.io
Content-Type: application/json
x-api-key: sk_live_...
X-Foir-Schema-Channel: draft

Public keys (pk_…) ignore the channel header and always read published — the safer default for storefront builds.

Field reference

DesignTokens

Field	Type	Description
`source`	`JSON`	The raw W3C document with `{path.to.token}` references intact. For build tooling.
`colors`	`[DesignTokenColor!]!`	Resolved color tokens.
`fontFamilies`	`[DesignTokenFontFamily!]!`	Resolved font-family tokens (each value is a string array — primary + fallbacks).
`fontWeights`	`[DesignTokenFontWeight!]!`	Resolved numeric font weights (100–900).
`fontSizes`	`[DesignTokenDimension!]!`	Resolved font sizes (CSS length strings).
`lineHeights`	`[DesignTokenNumber!]!`	Resolved unitless line-height multipliers.
`letterSpacings`	`[DesignTokenDimension!]!`	Resolved letter-spacing values.
`typography`	`[DesignTokenTypography!]!`	Composite tokens: fontFamily + fontSize + fontWeight + lineHeight + letterSpacing + optional textTransform.
`spacings`	`[DesignTokenDimension!]!`	Resolved spacing scale (`spacing.*`).
`radii`	`[DesignTokenDimension!]!`	Resolved corner-radius scale (`radius.*`).
`shadows`	`[DesignTokenShadow!]!`	Multi-layer drop shadows.
`borders`	`[DesignTokenBorder!]!`	Stamped borders — width + style + color.

Every resolved array is sorted by path for stable output.

Common fields

Every token type carries:

Field	Type	Description
`path`	`String!`	Dotted path identifying the token (e.g. `color.brand.primary`).
`name`	`String!`	The leaf segment of `path` (e.g. `primary`).
`description`	`String`	The `$description` from the W3C document.

Type-specific values

Type	`value` shape
`DesignTokenColor`	`String!` — CSS color string (hex, `rgb()`, etc.).
`DesignTokenFontFamily`	`[String!]!` — primary + fallback stack.
`DesignTokenFontWeight`	`Int!` — 100–900.
`DesignTokenDimension`	`String!` — any CSS length: `16px`, `1rem`, `clamp(...)`.
`DesignTokenNumber`	`Float!` — unitless.
`DesignTokenTypography`	`DesignTokenTypographyValue!` — see below. Also exposes `label` and `tag` for editor metadata.
`DesignTokenShadow`	`[DesignTokenShadowLayer!]!` via `layers` — one entry per layer.
`DesignTokenBorder`	`DesignTokenBorderValue!` — `{ color, width, style }`.

DesignTokenTypographyValue

Field	Type	Description
`fontFamily`	`[String!]!`	Resolved font-family stack.
`fontSize`	`String!`	Resolved CSS length.
`fontWeight`	`Int!`	Resolved 100–900 weight.
`lineHeight`	`Float!`	Resolved unitless line height.
`letterSpacing`	`String!`	Resolved CSS length.
`textTransform`	`String`	Optional — `uppercase`, `lowercase`, `capitalize`.

DesignTokenShadowLayer

Field	Type
`offsetX`, `offsetY`, `blur`, `spread`, `color`	`String!`
`inset`	`Boolean!`

Examples

Resolved colors → CSS variables


query Colors {
  designTokens {
    colors { path value }
  }
}


const css = data.designTokens.colors
  .map(c => `--${c.path.replaceAll('.', '-')}: ${c.value};`)
  .join('\n');
// --color-brand-primary: #2c4433;
// --color-brand-accent:  #d4553a;

Typography → ready-to-render styles


query Typography {
  designTokens {
    typography {
      path
      label
      tag
      value {
        fontFamily
        fontSize
        fontWeight
        lineHeight
        letterSpacing
        textTransform
      }
    }
  }
}

The composite value is fully resolved — no need to look up the referenced primitives separately.

Raw document for Style Dictionary


query Source {
  designTokens { source }
}

source returns the W3C document with {path.to.token} references intact. Feed it to your build pipeline of choice.

Previewing a draft


curl https://api.foir.io/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_..." \
  -H "X-Foir-Schema-Channel: draft" \
  -d '{"query":"{ designTokens { spacings { path value } } }"}'

Use this in preview environments to render the next-version look before clicking Publish.

Errors

Status	Message	Cause
401	`API key or admin token required`	Missing or invalid `x-api-key` / `Authorization` header.
403	`X-Foir-Schema-Channel: draft requires drafts:read scope`	You sent `X-Foir-Schema-Channel: draft` with a key that doesn’t have the `drafts:read` scope.

Validation errors (cycles, unknown references, bad $type) surface at write time — foir push and the admin editor reject them before they reach the read API. The designTokens query itself returns the stored document or an empty document for projects that haven’t authored tokens yet.