Getting started

Installation

Install the design system in your project as a python package:

pip install git+https://github.com/DemocracyClub/design-system.git@python-package

Now simply import dc_design_system:

import dc_design_system

The only thing this package does is to expose the directory it lives in, which we’ll use in the Sass compilation step to follow. It’s also needed to path to the images and fonts folders.

>>> import dc_design_system
>>> dc_design_system.DC_SYSTEM_PATH
'/home/symroe/.envs/design_system/lib/python3.8/site-packages/dc_design_system'

Structure

The design system folder contains fonts, images and Sass partials:

📁 fonts
📁 images
📁 partials
tokens.css
index.template.scss
docs.scss

The tokens.css file holds the design system’s values — colours, scales, type — as CSS custom properties. It is the single source of truth for them, and partials/_variables.scss maps the Sass variables onto it. You do not need to do anything with this file to compile the Sass, but it is what you should reference if you are writing your own CSS against the design system. See CSS custom properties.

The docs.scss file can be ignored. This just powers the design system used inside this documentation.

The index.template.scss file is a template for how you would pull in the partials and get the system running in your project.

Sass compilation

The first thing you need to do is take index.template.scss, rename it if you desire, and make it the “in” file for Sass compilation. To reach the associated partials, you will need to configure libsass to use the folder exposed in the installation step above as an include-path.

Note the optional-styles block in that file. For efficiency, you should comment out any components here you know you don’t need, keeping the design system’s footprint as small as possible. In the following example, I have commented out the Sidebar, Table, and Select components.

@mixin optional-styles {
  @include description-lists;
  @include button;
  @include cta;
  @include cluster;
  @include grid;
  // @include sidebar;
  @include details;
  @include card;
  @include candidate;
  @include breadcrumbs;
  // @include table;
  @include header;
  @include footer;
  @include radio;
  @include checkbox;
  // @include select;
  @include filter;
  @include party;
}

Scoping

Also in index.template.scss you will notice the following line:

$scope: false;

If set to true, all of the styles you generate are scoped to the ds-scope class. For example, the .ds-stack > * selector will become .ds-scope .ds-stack > *, meaning you must have a parent with class="ds-scope" for the styles to be honoured.

<div class="ds-scope">
  <!-- design system styles honoured -->
</div>

<div>
  <!-- design system styles NOT honoured -->
</div>

This allows you to more safely add design system components alongside existing styles. Ideally, you would not use scoping and just defer to the design system for all your styling. Unless there is a real need for scoping, best to leave it as false.

CSS optimization

Although the design system—even including all of the components—is relatively small, it’s still recommended you minimize the output CSS using a tool like CSSO(https://github.com/css/csso). Include the minimized file in a <link> element in the head of your document in the standard fashion.

<link rel="stylesheet" href="path/to/system.min.css" />

Local development

This project can be run locally if you want to view the in-browser docs/demo.

In order to do this, you'll need to have node v18 available due to this project's dependency on node-sass. Newer versions of node will fail to build node-sass's native binding.

If you're using nvm, you can run nvm use from the project's root to switch version — .nvmrc pins the correct one.

Run the following commands to get everything nicely set up.

npm install
npm start

You will then be able to access via localhost in your browser. The demo page is at /layout-demo/index.html.

If you want to run the Lighthouse tests locally, you'll also need to make sure the Lighthouse node package is available globally: npm install -g lighthouse@11.7.1

Next steps

Follow the HTML examples in individual components docs. If you are making a page layout from scratch, see Page layout.

Adding or changing components

Update or create a partial file containing the component style such as system/partials/_date-picker.scss.

If a new component is added:

Create a src-site/components/new-component.md file to explain it's use with an html example.
Add the html example to src-site/usage/composition.md to be sure it's included in Lighthouse tests.
Add the partial to system/docs.scss (twice, import the mixin at the top, then add it to optional-styles)
Run npm run watch:eleventy to view changes to source site.
Once changes are complete, update the version in package.json and lock it with npm install