Welcome to the web.dev design system
Quick start #
All the available colors and guides for their usage
How the theming stying works and how to use it
Font sizes, the size scale and available fonts
The spacing scale and spacing utilities
Flexible and skeletal compositional layouts that work site-wide
Flexible utilities that solve common UI problems
The CSS Methodology all of the CSS in this system uses
Gorko CSS Framework
Documentation for the CSS (Sass) framework that’s used in this design system
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:
├── _themes.scss (generated)
├── _tokens.scss (generated)
The Sass folder mostly resembles the CUBE CSS structure and is as follows:
blocks: contained components
compositions: layout compositions
functions: Sass functions used across the SCSS files
mixins: Sass mixins used across the SCSS files
pages: specific styles for pages and page types
utilities: core utilities
web-components: styles for specific web-components
_config.scss: core Gorko configuration
_reset.scss: a lightweight CSS reset
_rollout.scss: Temporary styles to provide a bridge between the old system and new system while the new system is rolled out
_themes.scss: an auto-generated file by
_tokens.scss: an auto-generated file by
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.
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:
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:
There are 2 required arguments to pass in—
-n. The rest are optional.
-pis the path from
-nis the file name
-tis the title. If this is not set, the
-nwill be used
-smallows you to skip markup being generated if you are generating a variant