Amsterdam Design System: CSS components

This package provides stylesheets for all components in the Amsterdam Design System and some general utilities. Use it to apply the visual design of the City of Amsterdam to your HTML elements or non-React components.

Introduction

We publish our components’ stylesheets as a separate package to help replicating them in other libraries, platforms, or SaaS applications. The classes are a contract between the component’s definition and its implementations and they facilitate ongoing upgrades.

Our React components use these classes in the HTML they render. You should use that package if your application uses React.

A couple of utility classes are included for general use: aspect ratio, bottom margin, gap, and visually hidden.

Installation

The stylesheets reference our design tokens. Both packages need to be installed.

npm install @amsterdam/design-system-css @amsterdam/design-system-tokens

Usage

The set of classes for a component can be seen as a blueprint for its markup and features. An .ams-component root selector applies the essential styles of the component to its element, and additional classes like .ams-component--variant modify its appearance or behaviour.

The classes employ the naming convention of NL Design System. Other communities only need to overwrite design tokens to use our components with their branding.

In JSX

Import the main stylesheet and use the class names in your markup.

import "@amsterdam/design-system-assets/font/index.css"
import "@amsterdam/design-system-css/dist/index.css"
import "@amsterdam/design-system-tokens/dist/index.css"

export const App = () => (
  <p className="ams-paragraph">Hello, world!</p>
)

In HTML

Although it is not a typical use case, the stylesheet can be included in an HTML page directly.

<!doctype html>
<html lang="en">
  <head>
    <link rel="stylesheet" href="node_modules/@amsterdam/design-system-assets/font/index.css" />
    <link rel="stylesheet" href="node_modules/@amsterdam/design-system-css/dist/index.css" />
    <link rel="stylesheet" href="node_modules/@amsterdam/design-system-tokens/dist/index.css" />
  </head>
  <body class="ams-body">
    <p class="ams-paragraph">Hello, world!</p>
  </body>
</html>

Compact Mode

Load the compact tokens to use the compact appearance of the design system, e.g. for internal websites with a high information density. They override the spacious ones; the stylesheets can remain unchanged.

Lo-fi Mode

Load the Lo-fi tokens to present pages as a sketch, e.g. to keep a design review focused on structure and content. They override the default appearance; the stylesheets can remain unchanged here as well.

Global styles

Some elements of your document are out of reach for the Design System components. However, their styles can influence the appearance of the components.

Set a class on the body

Add the ams-body class to your document’s <body> tag. This removes white space that the browser might add. In Compact Mode, it also sets the background color to match the Page component seamlessly.

We don’t have a separate, global reset stylesheet. This follows from our component-based architecture: every component overwrites user agent styles on the elements they render. You shouldn’t need a reset stylesheet.

Keep the base font size

Do not change the base font-size – e.g. through html { font-size: 62.5% }. Our typography system expects 1rem to be the browser default of 16 pixels.

Updating

We follow semantic versioning and publish a change log to guide you through updates. The classes are a public API of the design system. Note that detecting changed or deleted classes is still a manual process.

Support

Contact us if you have a question, find an issue, or want to contribute. Find ways to reach us on designsystem.amsterdam.