Design tokens

The colours charts and reports are drawn with, shared with the Beacon app.

tokens

Design tokens: the colours Beacon draws with.

colors.json here is a vendored copy of tokens/colors.json in the beacon-ui repository, which is generated from Figma and is the source of truth. It is copied rather than fetched so this package installs and renders offline, and a CI job fails when the two copies drift apart.

Do not edit the values here. A change made in this file and not in beacon-ui is a change the drift check will reject, and correctly so: the design system does not live in this repository.

Two kinds of colour live in the file, and the distinction is deliberate:

• tokens carry a value per mode, light and dark. They are chrome: the colours a chart takes on so it sits inside the surrounding application.
• raw colours have one value regardless of mode. A correlation heatmap is a measurement scale rather than themed furniture and must not flip with the theme, and everything inside a report page is print ink that has to match the PDF it becomes.

load cached

load() -> dict[str, Any]

Read and validate the token document.

Read through importlib.resources rather than by path, so it works the same from a wheel, a zip import or a source checkout, and explicitly as UTF-8, because the file carries non-ASCII text and the default encoding is not UTF-8 on every platform this runs on.

Returns:

Name	Type	Description
dict	dict[str, Any]	The parsed document. Cached; callers must not mutate it.

Raises:

Type	Description
ConfigurationError	If the file is missing, unparseable, or does not hold what the rest of this module promises.

token_names

token_names() -> list[str]

Every token name, alphabetically.

palette

palette(mode: str = LIGHT) -> dict[str, str]

Every token's colour in one mode.

Parameters:

Name	Type	Description	Default
mode	str	LIGHT or DARK.	LIGHT

Returns:

Name	Type	Description
dict	dict[str, str]	Token name to hex colour. Values may carry an alpha channel;
	dict[str, str]	matplotlib accepts the 8-digit form directly.

Raises:

Type	Description
ConfigurationError	If mode is not a declared mode.

colour

colour(name: str, mode: str = LIGHT) -> str

One token's colour.

Parameters:

Name	Type	Description	Default
name	str	Token name, e.g. "accent".	required
mode	str	LIGHT or DARK.	LIGHT

Returns:

Name	Type	Description
str	str	Hex colour.

Raises:

Type	Description
ConfigurationError	If the token or mode is unknown. Unknown names are an error rather than a fallback: silently substituting a default would produce a chart that looks fine and is wrong.

raw_colours

raw_colours() -> dict[str, str]

The mode-independent colours, without the explanatory comment.

Heatmap stops and report-page ink. These do not change with the theme by design: a measurement scale that flipped with the surrounding chrome would make two screenshots of the same data disagree.

Returns:

Name	Type	Description
dict	dict[str, str]	Raw colour name to hex colour.

unverified

unverified(mode: str = LIGHT) -> list[str]

Tokens whose value in mode did not come from a verified Figma variable.

A placeholder renders exactly as convincingly as a real colour, so the file records where each value came from and this surfaces it. Empty is the healthy state.

Parameters:

Name	Type	Description	Default
mode	str	LIGHT or DARK.	LIGHT

Returns:

Name	Type	Description
list	list[str]	Token names, alphabetically.