Welcome to the web.dev design system

This design system will help you to maintain consistency around the web.dev website by providing CSS structure, design tokens, typography rules and spacing rules, along with a comprehensive component library.

Quick start

For developers

This design system should be treated as the source of truth for any front-end development work that requires CSS.

About the CSS

The design system is built around CUBE CSS, a methodology that’s orientated towards simplicity and pragmatism. Versus the previous system on web.dev, a lot of CSS is declared as high up as possible—globally—rather than concentrated on complex BEM components.

The CSS is pre-processed using SCSS, which in turn, uses Gorko to provide structure, mixins and generated utility classes. The design system uses utilities regularly, so ensure you read up on how Gorko generates them. They are defined here.

Everything in CSS is powered by design tokens, which are defined here. The design tokens mainly define colors, fonts, spacing, sizes, transitions and decorative elements, such as border radius.

Lastly, the whole design system is theme-driven. This means that tokens are applied to contexts, rather than directly to elements. This makes working with dark/light themes much easier with less authored code. Read more in the color section.

SCSS file and folder structure

The structure is as follows:

src
└── scss
    ├── blocks
    ├── compositions
    ├── functions
    ├── mixins
    ├── pages
    ├── utilities
    ├── web-components
    ├── _config.scss
    ├── _fonts.scss
    ├── _reset.scss
    ├── _rollout.scss
    ├── _themes.scss (generated)
    ├── _tokens.scss (generated)
    └── next.scss

The Sass folder mostly resembles the CUBE CSS structure and is as follows:

1. blocks: contained components
2. compositions: layout compositions
3. functions: Sass functions used across the SCSS files
4. mixins: Sass mixins used across the SCSS files
5. pages: specific styles for pages and page types
6. utilities: core utilities
7. web-components: styles for specific web-components
8. _config.scss: core Gorko configuration
9. _fonts.scss: @font-face declarations
10. _reset.scss: a lightweight CSS reset
11. _rollout.scss: Temporary styles to provide a bridge between the old system and new system while the new system is rolled out
12. _themes.scss: an auto-generated file by src/site/_data/design/themes.js
13. _tokens.scss: an auto-generated file by src/site/_data/design/tokens.js
14. next.css: the main SCSS file that pulls everything together and defines global CSS

For authors

Please use the same component guide in the handbook as always.

How to use the pattern/component generator

To prevent repetitive file creation, you can use the pattern generator to create a new pattern, or pattern's variant with a npm task.

Example

Let's say you want a new pattern called "my-pattern":

npm run patterns:create -- -p my-pattern -n my-pattern -t My\ Pattern

This will create the following folder and file structure:

web.dev
└── src/
    └── component-library/
        └── my-pattern/
            ├── my-pattern.njk
            ├── my-pattern.json
            └── my-pattern.md

Let's you want to create a variant of "my-pattern":

npm run patterns:create -- -p my-pattern/variants -n my-pattern-primary -t Primary

It'll result in this structure:

web.dev
└── src/
    └── components/
        └── patterns/
            └── my-pattern/
                ├── my-pattern.njk
                ├── my-pattern.json
                ├── my-pattern.md
                └── variants/
                    ├── my-pattern-primary.njk
                    └── my-pattern-primary.json

Arguments

There are 2 required arguments to pass in—-p and -n. The rest are optional.

Make sure you add the -- after npm run patterns:create so the arguments get passed into the task.

Also make sure you escape spaces with a \.

• -p is the path from src/components/patterns
• -n is the file name
• -t is the title. If this is not set, the -n will be used
• -sm allows you to skip markup being generated if you are generating a variant