London City Data

Design Tokens

A single source of truth

Design tokens are named values for the decisions in the system: colours, type, spacing, flow, the layout grid, shadows and elevation.

The tokens are defined in Figma and published in the @ldn-viz/themes package. Each semantic token is named for its purpose, such as --color-text-muted for secondary text. When a token's value changes, everything that uses the token takes the new value.

Use

The components use the tokens already. In your own markup, each token is a CSS custom property:

.summary {
	color: var(--color-text-muted);
	padding: var(--spacing-4);
}

If your app uses Tailwind, as the component library does, the theme package's preset makes each token a utility. The utility's prefix comes first, then the token name without the --, so bg-color-surface sets the background to --color-surface. Spacing utilities use the numbered scale, so p-4 is 16px of padding.

To use a colour in JavaScript, for example to pass it to a chart library, use theme from @ldn-viz/ui. It returns the value for the current mode:

import { theme } from '@ldn-viz/ui';
 
const seriesColour = theme.tokenNameToValue('data.primary');

Use a class for typography and flow tokens. A type role, such as title-md, is set by five tokens: font family, size, weight, line height and letter spacing. Each of those tokens has a value for each typeset and breakpoint. The class sets the text to the values for the typeset and breakpoint it's in, so use the class rather than the tokens. A flow token, such as --flow-section, takes its value from the nearest flow context class, such as flow-standard. See Typography and Flow for more detail.

<section class="flow-standard">
	<h2 class="title-md">Housing completions</h2>
	<p class="body-md">…</p>
</section>

How it works

Primitive and semantic tokens

Tokens are in two tiers. A primitive token is named by its value or its step on a scale, such as a light mode or dark mode blue at step 700. A semantic is an alias to a primitive token and says what a value is for, such as --color-surface-accent.

Light

#0067b4 (Raw value)
--primitive-color-mode-light-blue-700 (Primitive)
--color-palette-blue-700 (Semantic)
--color-surface-accent (Semantic)

Dark

#4c9fea (Raw value)
--primitive-color-mode-dark-blue-700 (Primitive)
--color-palette-blue-700 (Semantic)
--color-surface-accent (Semantic)

Use semantic tokens only. In the example above the semantic token --color-palette-blue-700 aliases a different primitive depending on the user preference for light or dark mode. This lets us adjust colours to be accessible in different modes. Primitive custom properties start with --primitive-, so a use of one is easy to spot.

Reading a token name

A token name is built from segments, from general to specific:

category → variant → concept → role → emphasis → state → value

A segment that doesn't apply is left out, and the rest keep their order. --color-interactive-primary-hover is the category color, the concept interactive, the role primary and the state hover.

SegmentWhat it saysExamples
CategoryThe kind of valuecolor spacing typography flow grid shadow elevation
VariantA mode, scope, breakpoint, typeset or contextinverse static chart geo md product standard
ConceptThe thing the value is forcanvas surface interactive text border data
RoleIts place in a hierarchy, or what it signalsprimary secondary positive negative caution title
EmphasisLess contrast than the defaultmuted wash
StateAn interaction, selection or availability statehover active selected disabled
ValueA size, step or propertysm md lg 4 font-size

Names are lowercase, with hyphens between words. A fractional step uses a hyphen, so --spacing-0-5 is 2px.

A default token has no -default suffix. --color-border is the default border colour, and there's no --color-border-default. A flow context and a size are always named, as in --flow-standard-loose and --shadow-md.

Typography tokens have a breakpoint and a size in the same name. In --typography-md-product-title-md-font-size, the first md is the breakpoint and the second is the size of the title. The smallest breakpoint is base, which covers widths below sm.

Concepts

An interface is a stack. The canvas is at the base, and surfaces sit above it at elevation steps 1 to 6. A surface is coloured surface, or surface-muted to set it apart from what is around it. Text, labels, borders and interactive elements sit on a surface.

TextTokencanvassurfacesurface-mutedtextlabelborderinteractiveElevationelevation-1 to 6elevation-0Button

Inverse

The inverse variant is for content on an inverse background. The inverse surface is dark in light mode and light in dark mode. Use inverse tokens together, such as --color-inverse-text on --color-inverse-surface.

Light

--color-text
--color-surface
--color-inverse-text
--color-inverse-surface

Dark

--color-text
--color-surface
--color-inverse-text
--color-inverse-surface

Usage aliases

We provide a set of usage aliases for users who aren't fully engaged with the system and just want to know "what's the right class for a card title". A usage alias is a class named for the place it's used, such as card-title or chart-tick. These classes are an extra layer of semantic sugar. Each one applies a type role for a specific component, as in card-title. Typography lists them.

Reference

These tables list every published semantic token, with its value.

Colour

The colour tokens are grouped by concept. Each has a value for light mode and dark mode. Colour explains how to choose one.

Palette

The palette provides the lowest level semantic tokens. Many of the other semantic tokens are aliases of values within the palette. Each color has values at 100 - 1100

Quantitative colour scales can be based on the palette colors. See Quantitative colour.

TokenLightDark
--color-palette-grey-100 #f0f1f2 #192023
--color-palette-grey-200 #d6d8da #2b3338
--color-palette-grey-300 #bdc0c2 #3d454b
--color-palette-grey-400 #a4a8ac #52595e
--color-palette-grey-500 #8c9295 #676e73
--color-palette-grey-600 #757c80 #7e8488
--color-palette-grey-700 #5f666b #959b9e
--color-palette-grey-800 #495157 #adb2b4
--color-palette-grey-900 #353d43 #c5c8ca
--color-palette-grey-1000 #232a2e #e0e1e2
--color-palette-grey-1100 #13181c #f9f9f9
--color-palette-blue-100 #e6f2fd #001f42
--color-palette-blue-200 #b9dbfd #003162
--color-palette-blue-300 #90c5f9 #004582
--color-palette-blue-400 #65adf1 #0059a2
--color-palette-blue-500 #3c96e4 #006fc0
--color-palette-blue-600 #0e7ed1 #2287d9
--color-palette-blue-700 #0067b4 #4c9fea
--color-palette-blue-800 #005194 #75b6f5
--color-palette-blue-900 #003c74 #9dccfb
--color-palette-blue-1000 #002953 #cbe4fd
--color-palette-blue-1100 #001835 #f5f9fe
--color-palette-green-100 #e9f4eb #002508
--color-palette-green-200 #bde0c5 #003b12
--color-palette-green-300 #94cda2 #00501d
--color-palette-green-400 #6ab880 #00662a
--color-palette-green-500 #41a362 #007e3c
--color-palette-green-600 #148d49 #279552
--color-palette-green-700 #007534 #51ac6e
--color-palette-green-800 #005d24 #7ac08d
--color-palette-green-900 #004617 #a2d4ae
--color-palette-green-1000 #00300d #cde7d2
--color-palette-green-1100 #001d05 #f6faf7
--color-palette-yellow-100 #fff71c #221f00
--color-palette-yellow-200 #e8db00 #363200
--color-palette-yellow-300 #cfc300 #4b4500
--color-palette-yellow-400 #b6ab00 #615a00
--color-palette-yellow-500 #9d9400 #776f00
--color-palette-yellow-600 #867d00 #8e8500
--color-palette-yellow-700 #6e6700 #a79d00
--color-palette-yellow-800 #575100 #c0b400
--color-palette-yellow-900 #423d00 #d8cc00
--color-palette-yellow-1000 #2d2a00 #f2e500
--color-palette-yellow-1100 #1b1800 #ffff77
--color-palette-orange-100 #ffece4 #410900
--color-palette-orange-200 #ffcdb6 #631400
--color-palette-orange-300 #ffac88 #831f00
--color-palette-orange-400 #ff8657 #a42d00
--color-palette-orange-500 #f36428 #c53e00
--color-palette-orange-600 #d94b00 #e4530c
--color-palette-orange-700 #b83700 #fc6f38
--color-palette-orange-800 #972700 #ff956b
--color-palette-orange-900 #751a00 #ffb898
--color-palette-orange-1000 #530f00 #ffd9c8
--color-palette-orange-1100 #350600 #fff7f4
--color-palette-red-100 #ffede9 #480000
--color-palette-red-200 #ffccc4 #6b0000
--color-palette-red-300 #ffaa9e #8f0000
--color-palette-red-400 #ff8478 #b50000
--color-palette-red-500 #ff554d #dc000b
--color-palette-red-600 #f21a24 #fb2f31
--color-palette-red-700 #cd0000 #ff695f
--color-palette-red-800 #a50000 #ff9387
--color-palette-red-900 #7f0000 #ffb6ab
--color-palette-red-1000 #5a0000 #ffd8d2
--color-palette-red-1100 #3a0000 #fff7f6
--color-palette-pink-100 #ffecef #470012
--color-palette-pink-200 #ffcad2 #69001f
--color-palette-pink-300 #ffa7b6 #8d002e
--color-palette-pink-400 #ff809a #b2003e
--color-palette-pink-500 #ff4f7a #d80053
--color-palette-pink-600 #ec1f61 #f5326a
--color-palette-pink-700 #c9004a #ff6588
--color-palette-pink-800 #a20037 #ff90a6
--color-palette-pink-900 #7d0027 #ffb4c1
--color-palette-pink-1000 #590019 #ffd7dd
--color-palette-pink-1100 #39000d #fff7f8
--color-palette-darkpink-100 #fbeef2 #44001f
--color-palette-darkpink-200 #f5cdda #660033
--color-palette-darkpink-300 #eeaec4 #890049
--color-palette-darkpink-400 #e48fae #a81761
--color-palette-darkpink-500 #d77099 #bd3c76
--color-palette-darkpink-600 #c85183 #ce5c8b
--color-palette-darkpink-700 #b52f6e #dd7ca1
--color-palette-darkpink-800 #9e0159 #e89bb7
--color-palette-darkpink-900 #7a0040 #f1b9cc
--color-palette-darkpink-1000 #57002a #f8d9e3
--color-palette-darkpink-1100 #380018 #fdf7f9
--color-palette-purple-100 #faedfd #360840
--color-palette-purple-200 #f1cbfa #521260
--color-palette-purple-300 #e7aaf5 #6e1e80
--color-palette-purple-400 #d98aec #8a2d9e
--color-palette-purple-500 #c96bde #a440bb
--color-palette-purple-600 #b450cb #bc5ad3
--color-palette-purple-700 #9a39b0 #d077e5
--color-palette-purple-800 #7e2792 #df96f0
--color-palette-purple-900 #621972 #eab5f7
--color-palette-purple-1000 #460d53 #f4d8fb
--color-palette-purple-1100 #2c0535 #fcf7fe
--color-palette-turquoise-100 #d6f8f1 #07241f
--color-palette-turquoise-200 #96e6d7 #0f3832
--color-palette-turquoise-300 #70d0c0 #184c44
--color-palette-turquoise-400 #57b8a8 #226258
--color-palette-turquoise-500 #459f91 #2e796d
--color-palette-turquoise-600 #36887b #3b9083
--color-palette-turquoise-700 #297065 #4ca99b
--color-palette-turquoise-800 #1e5951 #5fc1b2
--color-palette-turquoise-900 #14433c #7cd8c9
--color-palette-turquoise-1000 #0b2e29 #abeee1
--color-palette-turquoise-1100 #051b18 #f1fbf9

Canvas

TokenLightDark
--color-canvas #ffffff #0e1316
--color-canvas-muted #f7f8f9 #151b1e

Surface

TokenLightDark
--color-surface #ffffff #0e1316
--color-surface-accent #0067b4 #4c9fea
--color-surface-accent-muted #e6f2fd #003162
--color-surface-negative-muted #ffede9 #6b0000
--color-surface-positive-muted #e9f4eb #003b12
--color-surface-caution-muted #ffece4 #631400
--color-surface-neutral-muted #f0f1f2 #192023
--color-surface-empty-muted #f0f1f2 #192023
--color-surface-muted #f0f1f2 #192023
--color-surface-alpha-muted #ffecef #69001f
--color-surface-beta-muted #e6f2fd #003162
--color-surface-alpha #c9004a #d80053
--color-surface-beta #007acc #007acc
--color-surface-neutral #d6d8da #2b3338
--color-surface-negative #cd0000 #ff695f
--color-surface-positive #007534 #51ac6e
--color-surface-caution #b83700 #fc6f38
--color-surface-empty #bdc0c2 #3d454b

Text

TokenLightDark
--color-text #353d43 #ffffff
--color-text-muted #5f666b #c5c8ca
--color-text-wash #5f666b #c5c8ca

Label

TokenLightDark
--color-label #353d43 #ffffff
--color-label-muted #5f666b #c5c8ca

Border

TokenLightDark
--color-border #5f666b #c5c8ca
--color-border-muted #8c9295 #676e73
--color-border-wash #d6d8da #52595e

Interactive

TokenLightDark
--color-interactive-selected #0067b4 #006fc0
--color-interactive-on #0067b4 #006fc0
--color-interactive-off #8c9295 #676e73
--color-interactive-dragged #3c96e4 #006fc0
--color-interactive-primary #0067b4 #006fc0
--color-interactive-primary-active #003c74 #004582
--color-interactive-primary-muted #e6f2fd #001f42
--color-interactive-primary-muted-hover #b9dbfd #003162
--color-interactive-primary-muted-active #90c5f9 #004582
--color-interactive-primary-hover #005194 #0059a2
--color-interactive-primary-text #0067b4 #4c9fea
--color-interactive-primary-text-hover #005194 #75b6f5
--color-interactive-primary-text-active #003c74 #9dccfb
--color-interactive-secondary #5f666b #adb2b4
--color-interactive-secondary-hover #495157 #c5c8ca
--color-interactive-secondary-active #353d43 #e0e1e2
--color-interactive-secondary-muted #d6d8da #2b3338
--color-interactive-secondary-muted-hover #bdc0c2 #3d454b
--color-interactive-secondary-muted-active #a4a8ac #52595e
--color-interactive-negative #cd0000 #ff695f
--color-interactive-negative-hover #a50000 #ff9387
--color-interactive-negative-active #7f0000 #ffb6ab
--color-interactive-negative-muted #ffede9 #6b0000
--color-interactive-negative-muted-hover #ffccc4 #8f0000
--color-interactive-negative-muted-active #ffaa9e #b50000
--color-interactive-positive #007534 #51ac6e
--color-interactive-positive-hover #005d24 #7ac08d
--color-interactive-positive-active #004617 #a2d4ae
--color-interactive-positive-muted #e9f4eb #003b12
--color-interactive-positive-muted-hover #bde0c5 #003b12
--color-interactive-positive-muted-active #94cda2 #00501d
--color-interactive-caution #b83700 #fc6f38
--color-interactive-caution-hover #972700 #ff956b
--color-interactive-caution-active #751a00 #ffb898
--color-interactive-caution-muted-hover #ffcdb6 #831f00
--color-interactive-caution-muted-active #ffac88 #a42d00
--color-interactive-caution-muted #ffece4 #631400
--color-interactive-disabled #8c9295 #959b9e
--color-interactive-disabled-muted #d6d8da #3d454b
--color-interactive-focus #0067b4 #006fc0
--color-interactive-error #cd0000 #ff695f

Inverse

TokenLightDark
--color-inverse-canvas #0e1316 #ffffff
--color-inverse-canvas-muted #151b1e #f7f8f9
--color-inverse-text #ffffff #2b3338
--color-inverse-text-muted #bdc0c2 #676e73
--color-inverse-text-wash #bdc0c2 #676e73
--color-inverse-surface #13181c #f9f9f9
--color-inverse-surface-muted #353d43 #e0e1e2
--color-inverse-chart-label #ffffff #2b3338
--color-inverse-chart-label-muted #bdc0c2 #676e73
--color-inverse-chart-axis #ffffff #2b3338
--color-inverse-chart-grid #232a2e #e0e1e2
--color-inverse-chart-surface #0e1316 #ffffff
--color-inverse-geo-feature #ffffff #2b3338
--color-inverse-geo-feature-muted #8c9295 #676e73
--color-inverse-geo-interactive #0067b4 #4c9fea
--color-inverse-geo-interactive-hover #005194 #75b6f5
--color-inverse-geo-interactive-selected #fff200 #fff200
--color-inverse-geo-interactive-focus #0067b4 #4c9fea
--color-inverse-geo-interactive-disabled #8c9295 #959b9e
--color-inverse-geo-interactive-error #cd0000 #ff695f
--color-inverse-geo-label #ffffff #2b3338
--color-inverse-geo-label-muted #bdc0c2 #676e73
--color-inverse-geo-annotation #ffffff #2b3338
--color-inverse-geo-annotation-muted #bdc0c2 #676e73
--color-inverse-border #ffffff #2b3338
--color-inverse-border-muted #8c9295 #676e73
--color-inverse-border-wash #52595e #d6d8da

Static

TokenLightDark
--color-static-brand #007acc #007acc
--color-static-white #ffffff #ffffff
--color-static-black #000000 #000000
--color-static-gla-darkblue #00577d #00577d
--color-static-gla-blue #007acc #007acc
--color-static-gla-cyan #00aeef #00aeef
--color-static-gla-green #008743 #008743
--color-static-gla-yellow #fff200 #fff200
--color-static-gla-mustard #dca000 #dca000
--color-static-gla-orange #e85713 #e85713
--color-static-gla-red #eb001b #eb001b
--color-static-gla-pink #e7135d #e7135d
--color-static-gla-darkpink #9e0059 #9e0059
--color-static-gla-purple #ae4ac6 #ae4ac6
--color-static-gla-grey #353d42 #353d42

Data

TokenLightDark
--color-data-categorical-blue #007acc #00aeef
--color-data-categorical-darkpink #9e0059 #9e0059
--color-data-categorical-pink #e7135d #da4476
--color-data-categorical-red #eb001b #eb001b
--color-data-categorical-yellow #fff200 #fff200
--color-data-categorical-green #41a362 #41a362
--color-data-categorical-purple #460d53 #ae4ac6
--color-data-categorical-orange #f36428 #f36428
--color-data-categorical-turquoise #57b8a8 #7cd8c9
--color-data-primary #007acc #00aeef
--color-data-secondary #9e0059 #da4476
--color-data-tertiary #f36428 #f36428
--color-data-neutral-0 #bdc0c2 #3d454b
--color-data-neutral-1 #a4a8ac #52595e
--color-data-positive #007acc #00aeef
--color-data-negative #eb001b #eb001b
--color-data-empty #d6d8da #2b3338
--color-data-context #bdc0c2 #3d454b
--color-data-male #41a362 #41a362
--color-data-female #460d53 #ae4ac6

Chart

TokenLightDark
--color-chart-axis #353d43 #ffffff
--color-chart-grid #d6d8da #2b3338
--color-chart-surface #ffffff #0e1316
--color-chart-label #353d43 #ffffff
--color-chart-label-muted #5f666b #c5c8ca

Geo

TokenLightDark
--color-geo-feature #5f666b #c5c8ca
--color-geo-feature-muted #8c9295 #676e73
--color-geo-interactive #0067b4 #4c9fea
--color-geo-interactive-hover #005194 #75b6f5
--color-geo-interactive-selected #fff200 #fff200
--color-geo-interactive-focus #0067b4 #4c9fea
--color-geo-interactive-disabled #8c9295 #959b9e
--color-geo-interactive-error #cd0000 #ff695f
--color-geo-label #353d43 #ffffff
--color-geo-label-muted #5f666b #c5c8ca
--color-geo-annotation #353d43 #ffffff
--color-geo-annotation-muted #5f666b #c5c8ca

Typography

Choose a typeset and a breakpoint to see the values for each role. Typography explains the roles and typesets.

product
base

Each value is the token --typography-base-product-{role}-{property}.

Rolefont-sizeline-heightfont-weightletter-spacing
display-lg40px48px7000px
display-md36px44px7000px
display-sm32px40px7000px
headline-lg30px38px7000px
headline-md28px36px7000px
headline-sm26px34px7000px
subhead-lg24px32px4000px
subhead-md22px30px4000px
subhead-sm20px28px4000px
title-lg22px30px6000px
title-md20px28px6000px
title-sm18px26px6000px
subtitle-lg20px28px4000px
subtitle-md18px26px4000px
subtitle-sm16px24px4000px
body-lg18px26px4000px
body-md16px24px4000px
body-sm14px22px4000px
label-lg18px26px5000px
label-md14px22px5000px
label-sm12px20px5000px
metric-lg28px32px7000px
metric-md24px28px7000px
metric-sm20px24px7000px
eyebrow14px18px5000px
caption-sm12px16px4000px
caption-md14px18px4000px
caption-lg16px20px4000px

Spacing

Spacing explains the scale.

TokenValuePixels
--spacing-px0.0625rem1px
--spacing-0-50.125rem2px
--spacing-10.25rem4px
--spacing-1-50.375rem6px
--spacing-20.5rem8px
--spacing-2-50.625rem10px
--spacing-30.75rem12px
--spacing-3-50.875rem14px
--spacing-41rem16px
--spacing-51.25rem20px
--spacing-61.5rem24px
--spacing-71.75rem28px
--spacing-82rem32px
--spacing-102.5rem40px
--spacing-123rem48px
--spacing-143.5rem56px
--spacing-164rem64px
--spacing-205rem80px
--spacing-246rem96px

Flow

Flow explains the contexts and steps.

TokenValuePixels
--flow-spacious-tight0.25rem4px
--flow-spacious1rem16px
--flow-spacious-loose1.5rem24px
--flow-spacious-section2.5rem40px
--flow-standard-tight0.25rem4px
--flow-standard0.5rem8px
--flow-standard-loose1rem16px
--flow-standard-section1.5rem24px
--flow-compact-tight0.25rem4px
--flow-compact0.25rem4px
--flow-compact-loose0.5rem8px
--flow-compact-section0.5rem8px

Layout grid

These tokens set the padding at the edge of a container, for each breakpoint and layout. Layout grid explains the layouts.

TokenValuePixels
--grid-base-contained-container-padding1rem16px
--grid-base-fluid-container-padding1rem16px
--grid-sm-contained-container-padding2rem32px
--grid-sm-fluid-container-padding1rem16px
--grid-md-contained-container-padding2rem32px
--grid-md-fluid-container-padding1.5rem24px
--grid-lg-contained-container-padding4rem64px
--grid-lg-fluid-container-padding1.5rem24px
--grid-xl-contained-container-padding5rem80px
--grid-xl-fluid-container-padding1.5rem24px
--grid-2xl-contained-container-padding6rem96px
--grid-2xl-fluid-container-padding1.5rem24px

Elevation

Elevation explains the levels.

TokenValueExample
--elevation-00px 0px 0px 0px #00000000
--elevation-10px 1px 2px 0px #0000000d
--elevation-20px 1px 3px 0px #0000001a, 0px 1px 2px -1px #0000001a
--elevation-30px 2px 4px -2px #0000001a, 0px 4px 6px -1px #0000001a
--elevation-40px 4px 6px -4px #0000001a, 0px 10px 15px -3px #0000001a
--elevation-50px 8px 10px -6px #0000001a, 0px 20px 25px -5px #0000001a
--elevation-60px 25px 50px -12px #00000040

Shadow

To set a level of elevation, use an elevation token. --shadow-inner has no elevation step.

TokenValueExample
--shadow0px 1px 3px 0px #0000001a, 0px 1px 2px -1px #0000001a
--shadow-innerinset 0px 2px 4px 0px #0000000d
--shadow-sm0px 1px 2px 0px #0000000d
--shadow-md0px 2px 4px -2px #0000001a, 0px 4px 6px -1px #0000001a
--shadow-lg0px 4px 6px -4px #0000001a, 0px 10px 15px -3px #0000001a
--shadow-xl0px 8px 10px -6px #0000001a, 0px 20px 25px -5px #0000001a
--shadow-2xl0px 25px 50px -12px #00000040

Breakpoints

Breakpoints are used in media queries and as Tailwind prefixes, such as md:. A custom property can't be used in a media query, so breakpoints have no semantic tokens. Write the width in the media query.

BreakpointMinimum width
baseNone
sm640px
md768px
lg1024px
xl1280px
2xl1536px

The full rules for tokens are in the specification.