London City Data

Getting Started

Getting up and running with the system.

The London City Data Design System (LCD-DS) helps you design and build user interfaces quickly and confidently, so that Londoners can understand the city through data.

LCD-DS is a set of design tokens, CSS classes and guidance for interfaces, charts, maps and tables.

Our component library is built on top of the system using Svelte and Tailwind. You do not need the component library, Svelte or Tailwind to use LCD-DS.

You can use it in three ways:

  • The full system for products built with the component library.

  • Adapting an existing system, for products built with other tools, which use the system's CSS.

  • Anywhere, for work in Figma, print or any other medium, which uses the system's values.

Use

Install the theme package and the component packages you need:

PackageContains
@ldn-viz/themesThe design tokens and CSS
@ldn-viz/uiInterface components, such as modals and sidebars
@ldn-viz/chartsChart components
@ldn-viz/mapsMap components
@ldn-viz/tablesTable components
@ldn-viz/utilsUtility functions, such as for colour scales
npm i @ldn-viz/themes @ldn-viz/ui

Each component package needs @ldn-viz/themes and Svelte 5.33 or later. @ldn-viz/maps also needs @ldn-viz/ui.

Import the CSS in your app's main stylesheet, before the Tailwind directives:

@import '@ldn-viz/themes/index.css';
 
@tailwind base;
@tailwind components;
@tailwind utilities;

The components are styled with Tailwind 3 classes, so add the theme package's preset to your Tailwind config. Include the component packages in content, so that Tailwind generates the classes they use:

module.exports = {
	presets: [require('@ldn-viz/themes/tailwind')],
	content: ['./src/**/*.{html,js,svelte,ts}', './node_modules/@ldn-viz/*/dist/**/*.{js,svelte}']
};

The preset sets Tailwind's colours, spacing, shadows and font families to the system's tokens, so bg-color-surface uses --color-surface.

It removes Tailwind's font sizes, weights and line heights. The system's type role classes, such as body-md, set type.

Because index.css is imported before the Tailwind directives, a utility class overrides a system class.

Add the Theme component to your app's top-level layout. It applies light or dark mode from the user's preference, which they can change with the ThemeSwitcher component.

Load the font

The system uses the Inter font. The theme package doesn't load it, so add it to your app or install it, for example from Google Fonts. Without it, text falls back to the system's sans-serif font.

How it works

The theme package has four CSS files:

FileContains
tokens.cssEvery design token as a CSS custom property
system.cssThe system's classes, such as the typesets, type roles, flow contexts and layout
reset.cssDefault styles for HTML elements
index.cssAll three, in the order reset, tokens, classes

Because the reset comes first in index.css, any class overrides its rules.

Upgrading from version 3

Version 4 changes how the theme package is imported, and renames some tokens and classes. The migration guide lists each change and what replaces it.

Next steps

  • The Foundations pages describe each part of the system, such as tokens, type and colour.
  • The Application design pages describe how to use the foundations in a product.
  • Storybook has the props and states of each component.