HTTP API: design

The one declaration of how every surface of this tool looks — the semantic roles, the status vocabulary, the type scale, the theme contract — as this executable carries it: its fingerprint, its tokens, what any one of them means, and whether the colours it pairs are readable on one another. The stylesheets the site and the Cockpit load, the tokens the executable's own pages compile in, and the dataset the site's templates read are all projections of it; a page compares its `--mj-design` with this fingerprint to know whether it is wearing the design this executable was built with.

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

design

GET /api/v1/design design.system

The design system

What the design is: the fingerprint every stylesheet carries, the identity, the type stacks, the theme contract with the pre-paint statement every surface runs, the audit widths, how many tokens of each kind, and every generated file the declaration is projected into.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_design
MCP resource {"name": "design", "uri": "majordomus://design"}

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/design"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	DesignReport	The design system: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/design/contrast design.contrast

Whether the declared colours can be read

Every foreground the design puts on a ground, in both themes, measured against WCAG 2.1 AA: the pair, the palette entries behind it, the ratio and the threshold. The pairs are not a list — they are derived from the declaration, which files each status's text with its own ground, and from the primitives that consume it, where a rule that sets a colour and a background states a pair and a rule that sets only a colour states a foreground that lands on every ground a container sets. A pair below the threshold is a finding that names the role, the ground, the theme, the measured ratio and the required one.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_design_contrast

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/design/contrast"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	ContrastReport	Whether the declared colours can be read: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/design/explain design.explain

What a design token means

One token by name or by the custom property it becomes: what it is for, what it resolves to in each theme, which Flowbite names are synonyms of it, which state words it colours, and which generated files it reaches.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_design_explain

Query parameters

name	type	required	description	examples
token	string	yes	A role (`fg`), a status (`ok`), a state word (`succeeded`), a type step (`meta`), a palette entry (`gray-600`), or the custom property any of them becomes (`--mj-fg`).	role: "fg"state: "succeeded"

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/design/explain?token=fg"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	Token	What a design token means: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/design/tokens design.tokens

The design tokens

Every token of the design, explained: roles with their light and dark values, statuses with their text, ground and border and the state words filed under them, the type scale, the layout values, the theme contract, the palette. Narrow it to one kind.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_design_tokens

Query parameters

name	type	required	description	examples
kind	TokenKind \| null	no	Only tokens of this kind.	roles: "role"

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/design/tokens?kind=role"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	TokenList	The design tokens: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

Carries

"text" | "non_text"

What a colour is doing where it was found.

textText: held to MINIMUM_TEXT.
non_textA border or an outline: measured against MINIMUM_NON_TEXT, reported, not enforced.

Used by Measured

ColourPart

object

One part of a colour token — a role has one, a status has its text, ground and border.

property	type	required	description
part	string	yes	`fg`, `bg` or `line`.
css	string	yes	The custom property a surface reads.
light	Resolved → Resolved	yes	In the light theme.
dark	Resolved → Resolved	yes	In the dark theme.

Used by Token

ContrastReport

object

Every pair the declaration and its consumers state, measured.

property	type	required	description
fingerprint	string	yes	The fingerprint of the declaration measured.
standard	string	yes	The standard the thresholds come from.
minimum_text	number (double)	yes	The ratio asked of text.
minimum_non_text	number (double)	yes	The ratio asked of a non-text element that carries meaning.
sources	array of Source → Source	yes	The stylesheets read, and whether each was found.
measured	integer (uint)	yes	How many pairs were derived and measured.
pairs	array of Measured → Measured	yes	Every pair, in a stable order: theme, then what it carries, then the two tokens.
composed	integer (uint)	yes	Declarations skipped because their value is composed at run time.
findings	array of string	yes	One line per enforced pair that falls short, naming role, ground, theme, measured ratio and required ratio.
readable	boolean	yes	Whether every enforced pair reaches its threshold.

Used by design.contrast

DesignReport

object

The design system: what it is and where it goes.

property	type	required	description
fingerprint	string	yes	SHA-256 of the declaration's canonical form.
design	string	yes	The first twelve digits, as every stylesheet carries them in `--mj-design`.
schema	integer (uint64)	yes	The format version of the declaration.
source	string	yes	Where the declaration lives, repository-relative.
identity	Identity → Identity	yes	Who this is.
font	Fonts → Fonts	yes	The two type stacks.
theme	ThemeView → ThemeView	yes	The theme contract.
viewports	array of integer (uint32)	yes	The widths a browser audit measures every page at.
tallies	TokenTallies → TokenTallies	yes	How many of each kind of token.
projections	array of ProjectionView → ProjectionView	yes	Every generated file the declaration is projected into.

Used by design.system

Fonts

object

The two type stacks.

property	type	required	description
sans	string	yes	The system stack.
mono	string	yes	The monospace stack.

Used by DesignReport

Identity

object

Who this is.

property	type	required	description
name	string	yes	The product name every surface shows.
mark	string	yes	The mark, relative to the design directory.
logo	string	yes	The full logo, relative to the design directory.
social	string	yes	The social preview image, relative to the design directory.

Used by DesignReport

Measured

object

One measured pair: a foreground on a ground, in one theme.

property	type	required	description
foreground	string	yes	The foreground token, as the declaration names it (`muted`, `ok`).
foreground_entry	string	yes	The palette entry it resolves to in this theme.
foreground_value	string	yes	The literal that entry holds.
ground	string	yes	The ground token.
ground_entry	string	yes	The palette entry the ground resolves to in this theme.
ground_value	string	yes	The literal that entry holds.
theme	string	yes	`light` or `dark`.
carries	Carries → Carries	yes	Text, or a border.
ratio	number (double)	yes	The measured ratio, to two decimal places.
required	number (double)	yes	What the standard asks of this pair.
passes	boolean	yes	Whether it reaches it.
enforced	boolean	yes	Whether falling short is a finding. False for a border; see the module documentation.
seen	string	yes	Where the pair was read: the stylesheet and the selector that states it.

Used by ContrastReport

ProjectionView

object

One generated projection of the design and what it is for.

property	type	required	description
path	string	yes	Repository-relative path.
read_by	string	yes	What reads it.

Used by DesignReport

Resolved

object

What a colour reference resolved to.

property	type	required	description
reference	string	yes	The palette entry or role the declaration named.
css	string	yes	The CSS value a stylesheet gets: the literal of a palette entry, or `var(--mj-<role>)`.
literal	string	yes	The literal after every reference is followed.

Used by ColourPart

Source

object

One stylesheet the pair set was derived from.

property	type	required	description
path	string	yes	Where it was read from, as the caller named it.
rules	integer (uint)	yes	How many rules of it state a colour.

Used by ContrastReport

ThemeView

object

The theme contract as a client reads it.

property	type	required	description
class	string	yes	The class on the root element that means dark.
storage_key	string	yes	The `localStorage` key the person's choice is kept under.
bootstrap	string	yes	The one pre-paint statement every surface runs.

Used by DesignReport

Token

object

One token, explained: where it came from, what it resolves to, what reads it.

property	type	required	description
name	string	yes	The name as declared.
kind	TokenKind → TokenKind	yes	What kind of token.
about	string	yes	What it is for, from the declaration.
css	array of string	yes	The custom properties and Tailwind utilities it becomes.
parts	array of ColourPart → ColourPart	no	For a colour token: its parts, each resolved per theme.
value	string \| null	no	For a scalar token: the value.
role	string \| null	no	For a state word: the status it is filed under.
states	array of string	no	For a status: the state words filed under it.
aliases	array of string	no	The Flowbite names that are synonyms of it.
projections	array of string	yes	The generated files the token reaches.

Used by design.explain TokenList

TokenKind

What kind of thing a token is.

fontA type stack.
paletteA raw palette entry.
roleA semantic surface role.
statusA status meaning.
stateA state word, filed under a status.
toneA tone: a hue for identity, never for meaning.
typeA step of the type scale.
trackingA letter-spacing.
layoutA shared layout value.
radiusA corner radius.
motionA duration.
themeThe theme contract.

Used by design.tokens Token

TokenList

object

The tokens, listed.

property	type	required	description
fingerprint	string	yes	The fingerprint of the declaration they came from.
total	integer (uint)	yes	How many are listed.
tokens	array of Token → Token	yes	The tokens, in the inventory's order.

Used by design.tokens

TokenTallies

object

How many of each kind of token.

property	type	required	description
palette	integer (uint)	yes	Raw palette entries.
roles	integer (uint)	yes	Semantic roles.
statuses	integer (uint)	yes	Status meanings.
states	integer (uint)	yes	State words filed under a status.
type_steps	integer (uint)	yes	Steps of the type scale.
aliases	integer (uint)	yes	Flowbite names declared as synonyms.

Used by DesignReport