From 96a7d186ca9c9712eea203a2a4a4c2f423bf4263 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Wed, 17 Nov 2021 13:45:55 -0500 Subject: [PATCH] Add "Coding Standards" section to contributing guide **Why**: To better communicate the approach to extending USWDS. --- CONTRIBUTING.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4c43c98a..850afb38 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,6 +8,16 @@ We encourage you to read this project's CONTRIBUTING policy (you are here), its If you have any questions or want to read more, check out the [18F Open Source Policy GitHub repository](https://github.com/18f/open-source-policy), or just [shoot us an email](mailto:18f@gsa.gov). +## Coding Standards + +### Extending the U.S. Web Design System + +Since the Login.gov Design System is based upon the [U.S. Web Design System (USWDS)](https://designsystem.digital.gov/), the code should reflect this: + +- Where possible, use [the available Sass theme variables](https://designsystem.digital.gov/documentation/developers/#customization-theming-and-tokens) to customize the appearance of components. These are configured under `src/scss/uswds-theme`. We only include the customized variables, to improve visibility of where differences are expected. Refer to the [USWDS theme variables source](https://github.com/uswds/uswds/tree/develop/src/stylesheets/theme) for the full set of configuration values. +- To limit side-effects and to clarify where styles are extended, customized USWDS styles should follow as close to the file location and CSS selector as possible. For example, if USWDS defines a selector `.usa-overlay` in `src/stylesheets/components/_header.scss` which defines a style `background` that we want to override, the style should be located at an identically-named selector in `src/scss/components/_header.scss` in this project. +- Prefer color and size tokens when possible. Never use hard-coded hex colors. Instead, use the `color` SCSS function with a [color token](https://design.login.gov/utilities/color/) as its argument. + ## Public domain This project is in the public domain within the United States, and