A brand's theme

GET

/api/v1/brands/{slug}/theme

const url = 'http://localhost:3000/api/v1/brands/example/theme';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url http://localhost:3000/api/v1/brands/example/theme \
  --header 'Authorization: Bearer <token>'

How its pages look beyond what the rules say: which rule plays which part (accent, surface, ink, faces, logo) and the page’s measure, rhythm and chrome, with the look they give. Every ink is graded on its ground in checks: a pair under its need (4.5:1 for text, 3:1 for marks) falls back to a color that reads and is a warning. So is a setting whose rule has gone since, and the default is used.

Scope: read.

Authorizations

bearer
session
None

Parameters

Path Parameters

slug

required

string

Brand slug

Responses

200

The theme

application/json

object

data

required

object

brand

required

string

settings

required

Which rule plays which part, and the page’s measure, rhythm and chrome; left out: read from the rules

object

accent

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

accentUse

Hairline: the accent draws rules and marks, never fills

string

Allowed values: fill hairline

surface

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

panel

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

dark

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

ink

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

muted

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

head

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

body

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

label

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

logo

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

device

Any of:

string
null

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

radius

Corner radius in px

integer

<= 40

width

string

Allowed values: narrow normal wide

density

string

Allowed values: compact normal airy

scale

Heading size ratio; 1.25 when left out

number

>= 1.067 <= 1.618

nav

string

Allowed values: sidebar top overlay

band

Every page opens on a band of the brand color; header band says the same

boolean

header

A page’s opening: on the page, on a band of the brand color, or beside its cover

string

Allowed values: plain band split

separation

Between two sections on the page’s own ground: space alone, or a hairline too

string

Allowed values: space hairline

numbering

Number chapters and pages: 01, 01.2

boolean

motion

Subtle: sections reveal as they scroll in; never with reduced motion

string

Allowed values: none subtle

toc

On this page: a side column, a list under the page header, or hidden

string

Allowed values: side inline none

titles

Section titles: headings (medium), or headlines (large, huge); a section’s own size wins

string

Allowed values: medium large huge

grounds

Alternate: every other section on the page’s own ground sits on the panel, so a long page has rhythm; canvas: under its header the page sits on the panel, dotted like a whiteboard, its section titles centered

string

Allowed values: plain alternate canvas

languages

The languages readers pick from; the first is the one the pages are written in

Array<object>

<= 12 items

object

code

required

string

<= 20 characters /^[a-z]{2,3}(-[a-z0-9]{2,8})?$/

label

required

string

>= 1 characters <= 40 characters

dir

From the language when left out

string

Allowed values: ltr rtl

links

Links beside search and print on the brand’s pages: its repository, its Figma library, its site

Array<object>

<= 8 items

object

label

required

string

>= 1 characters <= 40 characters

url

required

Http or https; a link to GitHub, Figma, npm and the like shows its icon

string format: uri

<= 2000 characters

theme

required

The look the settings and rules give: grounds, inks, accent, faces and chrome

object

required

The accent, lifted for light and dark pages, and the faces, as before W3

object

key

additional properties

surface

required

Any of:

string
null

A hex color

string

panel

required

A hex color

string

dark

required

A hex color

string

ink

required

A hex color

string

muted

required

A hex color

string

onDark

required

A hex color

string

mutedOnDark

required

A hex color

string

accent

required

The fill, as the brand has it: bands and buttons

string

accentText

required

The accent where it is text (links), at 4.5:1 on the surface

string

onAccent

required

A hex color

string

accentUse

required

string

Allowed values: fill hairline

line

required

A hex color

string

faces

required

object

head

object

family

required

string

weight

number

file

The font file for its weight

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

files

Every font file of the rule, one @font-face each

Array<object>

object

required

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

filename

required

string

mime

required

string

fallback

string

google

From Google Fonts, with no files here yet: set in its fallback until they are imported

boolean

body

object

family

required

string

weight

number

file

The font file for its weight

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

files

Every font file of the rule, one @font-face each

Array<object>

object

required

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

filename

required

string

mime

required

string

fallback

string

google

From Google Fonts, with no files here yet: set in its fallback until they are imported

boolean

label

object

family

required

string

weight

number

file

The font file for its weight

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

files

Every font file of the rule, one @font-face each

Array<object>

object

required

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

filename

required

string

mime

required

string

fallback

string

google

From Google Fonts, with no files here yet: set in its fallback until they are imported

boolean

case

required

string

tracking

required

In em

number

radius

required

number

width

required

string

Allowed values: narrow normal wide

density

required

string

Allowed values: compact normal airy

scale

required

number

device

required

Any of:

string
null

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

logo

required

Any of:

object
null

object

key

required

string

nav

required

string

Allowed values: sidebar top overlay

band

required

Header is band

boolean

header

required

string

Allowed values: plain band split

separation

required

string

Allowed values: space hairline

numbering

required

boolean

motion

required

string

Allowed values: none subtle

toc

required

On this page: a side column, a list under the page header, or none

string

Allowed values: side inline none

checks

required

Contrast of each pair in the look: one that fails falls back to a color that reads, and says which

Array<object>

object

pair

required

Which color on which, e.g. ink on surface

string

required

string

required

string

ratio

required

number

need

required

The contrast it must reach: 4.5 for text, 3 for marks

number

required

boolean

used

required

The color used: fg when it passes, else its fallback

string

checks

required

Contrast of each pair in the look: one that fails falls back to a color that reads, and says which

Array<object>

object

pair

required

Which color on which, e.g. ink on surface

string

required

string

required

string

ratio

required

number

need

required

The contrast it must reach: 4.5 for text, 3 for marks

number

required

boolean

used

required

The color used: fg when it passes, else its fallback

string

warnings

required

Settings naming a rule that has gone since (the default is used), and each pair that fell back

Array<string>

Example

{
  "data": {
    "settings": {
      "accentUse": "fill",
      "width": "narrow",
      "density": "compact",
      "nav": "sidebar",
      "header": "plain",
      "separation": "space",
      "motion": "none",
      "toc": "side",
      "titles": "medium",
      "grounds": "plain",
      "languages": [
        {
          "dir": "ltr"
        }
      ]
    },
    "theme": {
      "accentUse": "fill",
      "faces": {
        "head": {
          "google": true
        },
        "body": {
          "google": true
        },
        "label": {
          "google": true
        }
      },
      "width": "narrow",
      "density": "compact",
      "nav": "sidebar",
      "header": "plain",
      "separation": "space",
      "motion": "none",
      "toc": "side"
    }
  }
}

default

An error

application/json

object

error

required

object

code

required

string

message

required

string

detail

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "detail": "example"
  }
}

A brand's theme

Authorizations

Parameters

Path Parameters

Responses

200

Example

default

Examplegenerated

Example^generated