-
Notifications
You must be signed in to change notification settings - Fork 3
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Unify colors and add styles docs #2069
Merged
Merged
Changes from all commits
Commits
Show all changes
22 commits
Select commit
Hold shift + click to select a range
9a8a834
Add styles doc written during react-uswds migration
haworku 0fb4916
Add MCR color scheme
haworku 3d6da8d
MCR colors setup. Add documentation tweaks
haworku ee13554
yarn build is working
haworku 7bccc83
Merge remote-tracking branch 'origin/main' into styles-docs
haworku 1bf796f
Cleanup - go through landing page, form pages, settings pages
haworku d2b9ec1
Move back to @import usage to get app deploying
haworku 8fbef5a
link to custom not colors
haworku 52781e5
Fix state dashboard styling
haworku b774420
Pull out overrides as seperate module, distinct from custom
haworku 2b21df2
Move towards @use in each module.scss file. Document that @import …
haworku 812bd08
Add stylelint and run scss linter
haworku 87f540d
Merge remote-tracking branch 'origin/main' into styles-docs
haworku d5c7f3e
Run yarn at root
haworku 609a3a8
Fix yarn build error by importing sass for sass commands
haworku 5f12aa6
Stylelint updates - run on precommit, disallow hex variables for color
haworku 851f227
Storybook changes. Address @kelseylistrom comments.
haworku 2caaa7b
Cleanup yarn.lock
haworku 6fd991f
Cleanup Colors.module.scss
haworku fd6fe27
Address @pearl-truss code review
haworku 3354b84
Address @pearl-truss code review. Also get lint-staged working and ya…
haworku b3f78b6
Merge remote-tracking branch 'origin/main' into styles-docs
haworku File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,105 @@ | ||
# How to style with CSS and SCSS | ||
|
||
## Colors | ||
|
||
MC-Review has an application specific color palette written in SCSS. All color variables in the palette are prefixed with `$mcr-`. The palette is viewable in Storybook as well (`Global/Colors`). Anytime you need a color prefer the variable - e.g. $mcr-gold-base. Avoid using color hex codes directly or using random design system variables for color. | ||
|
||
The colors variables are defined in `styles/mcrColors.scss`. By reusing color variables from one place, we make future refactors easy and reduce styles tech debt. For example, if we needed to add a dark mode in the application or do a re-design, we start from one place. Note that we have colors in the application coming from both USWDS and CMDS currently in the application. These patterns are easier to see when our colors are defined in one place. | ||
|
||
## Containers | ||
|
||
Containers are the presentational elements that position content on the page. Look at designs and note the background color,the overall width of the content, and any obvious gutters between or margin/padding around content. | ||
|
||
We currently have ~three types of containers in the application. See our `custom.scss` for scss variables and mixins related to containers. Whenever you create a new page, one of your first considerations should be the container, making sure it is using `flex`, and determining which type of container you need. Make sure your container stretches the height and width you expect by expanding and shrinking the viewport and seeing how content inside behaves. There should not be gaps, for example, between the bottom of the page container and the footer. Also note the background color of the container and the margin. If areas have a lot of gray space, that is likely the base color of our main HTML document body. If the background looks white, that's probably `$mcr-foundation-white`. | ||
|
||
## Text | ||
|
||
Make sure heading levels (`h2`, `h3` etc) are properly used for text content. There are clear [guidelines](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements) around heading levels to follow. For example, page titles should always have some kind of heading, use only one h1 per page, headings should be nested by level, etc. If the heading is not styled the way you expect by default, CSS can be used to override things like font weight, size, etc. If you are noticing something with heading that need to be overridden across the app, this likely calls for global styles. | ||
|
||
Note also that there is a specific color to be used for links (`$$mcr-foundation-link`) and hint text (`$mcr-foundation-hint`). | ||
|
||
## Technologies related to styles in MC-Review | ||
|
||
### Sass / SCSS stylesheets | ||
|
||
[Sass](https://sass-lang.com/documentation/file.SASS_REFERENCE.html) is the way we write styles in the project. It is an extension of CSS. All files that `.scss` extension use Sass. Some basic concepts of Sass that are good to understand/review that are listed below. | ||
|
||
- How to [load SCSS](https://sass-lang.com/documentation/at-rules/use#loading-members) | ||
- How to [use nested selectors](https://sass-lang.com/documentation/style-rules#nesting) | ||
- How to [structure a Sass stylesheet](https://sass-lang.com/documentation/syntax/structure) | ||
|
||
### United States Web Design System | ||
|
||
See the ADR on [`Use USWDS as the design system`](../architectural-decision-records/014-use-uswds-design-system.md). | ||
|
||
What this means for styling the application is that you will see some USWDS language and patterns. This can also be used a common language between design and engineering. For example, the names of our components follow [USWDS names for components](https://designsystem.digital.gov/components/overview/). And when you look at our application in the dev tool, every class with `usa-*` in front of it is coming from USWDS. USWDS has [design tokens](https://designsystem.digital.gov/design-tokens/) and mixins we can rely on as well. | ||
|
||
## Style patterns in MC-Review | ||
|
||
### Styles should be as narrowly scoped as possible | ||
|
||
This is 101 but easy to forget. Please read [this section](https://github.com/trussworks/Engineering-Playbook/blob/main/docs/web/frontend/developing-ui.md#style-with-css-modules) of the Truss eng playbook for a good summary. | ||
|
||
TL;DR Less is more with styles. In our application, the preferred way to style React code is via locally scoped [CSS module](https://github.com/css-modules/css-modules), written as a `<component>.module.scss` file. This is stored alongside React component files. We also use [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference#selectors) to further target styles. Tightly scoped styles and CSS [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) ensure separation of concerns. | ||
|
||
Example of scoped styles in use: | ||
- Shared styles live close to the workflow they apply to. For example, directories in `/pages` folder may share a `*.module.scss` stylesheet if needed for templates in that area of the application. CSS selectors should be used to further scope down styles. | ||
- Re-useable atomic components (see `/components` folder) have self contained styles. There is a named `*.module.scss` file for each component. | ||
|
||
|
||
### Global styles live in `styles/custom.scss` | ||
|
||
Global styles should be uncommmon. They generally change only during a styles refactor across the application. | ||
|
||
The `styles/custom.scss` is also the main file imported into components to reference global SCSS variables. This file `@forward`s the MCR color palette and USWDS sass variables to the rest of the application. | ||
|
||
### Import styles with `@use` | ||
- Prefer namespaced scss imports with [`@use`](https://sass-lang.com/documentation/at-rules/use/) over [`@import`](https://sass-lang.com/documentation/at-rules/import/) for scss to reduce loading styles multiple times. Sass team is deprecating [`@import`](https://github.com/sass/sass/blob/main/accepted/module-system.md#timeline). | ||
|
||
In `*.module.scss` files this looks like (at top of file): | ||
``` | ||
@use '../../styles/custom.scss' as custom; | ||
@use '../../styles/uswdsImports.scss' as uswds; | ||
``` | ||
|
||
and then referring to varibles and mixins inline with the [namespace](https://sass-lang.com/documentation/at-rules/use/#choosing-a-namespace) - such as `custom.$mcr-foundation-white` or `@include uswds.uswds-at-media(tablet)` | ||
|
||
### Watch out for global style overrides that can impact UI across the application. | ||
|
||
Always nest your scss styles code in a css class to benefit from [the advantages of CSS/SCSS modules](https://css-tricks.com/css-modules-part-1-need/). Eencapsulates styles in classes throughout `[component].module.scss`. Do not use html and `usa-*` class overrides at the top level of the module files. This will override global styles across the application. | ||
|
||
If you must, make global overrides changes in (`overrides.scss`). Here are concrete examples where global style overrides are needed: | ||
|
||
1. We are dealing with container elements that repeat throughout the application outside of a specific component (divs, cards, display tables) | ||
2. We need override a behavior in USWDS that we can't control via settings throughout the application | ||
3. We want to hide an element from the screen using our global screenreader only class | ||
|
||
|
||
### Compose together styles in React component files using the `classnames` package | ||
|
||
- Sometimes React components have complex logic related to styles. To assist with this and follow patterns from `@trussworks/react-uswds` we use [`classnames`](https://github.com/JedWatson/classnames) package to compose together styles from different places. In the future if desired, we could make a similar utility in code and remove this dependency. | ||
|
||
Example of complex conditional styles from ActionButton: | ||
|
||
```react | ||
const classes = classnames( | ||
{ | ||
'usa-button--outline-disabled': isDisabled && isOutline, | ||
'usa-button--disabled': isDisabled, | ||
'usa-button--active': isLoading && !isSuccess, | ||
[styles.successButton]: isSuccess && !isDisabled, | ||
[styles.disabledCursor]: isDisabled || isLoading, | ||
}, | ||
className | ||
) | ||
``` | ||
|
||
In this example, ActionButton has different states (loading, disabled,success) that can be combined and there are is secondary visual variant (outline) to consider. | ||
|
||
The `'usa-button---'` classes are string literals for the class coming directly from USWDS. We want to use these in some cases. Then there are variables like `styles.disabledCursor` which come from the component module SCSS file. Finally, there is the `className` is coming from React props passed into the component from the parent. Ut is a best practice is to apply any consumer defined `className` styles last in re-useable components. | ||
|
||
The logic can be understood as | ||
|
||
1. USWDS styles are conditionally applied | ||
2. component specific styles from the module `styles` object are conditionally applied | ||
3. `className` prop is applied to all instances of the component (also overriding anything applied earlier if styles reference to the same CSS attribute). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,14 @@ | ||
{ | ||
"extends": "stylelint-config-recommended-scss", | ||
"rules": { | ||
"color-no-hex": true | ||
}, | ||
"overrides": [ | ||
{ | ||
"files": ["src/styles/**"], | ||
"rules": { | ||
"color-no-hex": null | ||
} | ||
} | ||
] | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
14 changes: 7 additions & 7 deletions
14
services/app-web/src/components/ChangeHistory/ChangeHistory.module.scss
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,56 @@ | ||
// stylelint-disable selector-pseudo-class-no-unknown | ||
@use '../../styles/custom.scss' as custom; | ||
|
||
:export { | ||
mcr: { | ||
primary: { | ||
lighter: custom.$mcr-primary-lighter; | ||
light: custom.$mcr-primary-light; | ||
base: custom.$mcr-primary-base; | ||
dark: custom.$mcr-primary-dark; | ||
darkest: custom.$mcr-primary-darkest; | ||
} | ||
cmsblue: { | ||
lightest: custom.$mcr-cmsblue-lightest; | ||
base: custom.$mcr-cmsblue-base; | ||
dark: custom.$mcr-cmsblue-dark; | ||
darkest: custom.$mcr-cmsblue-darkest; | ||
} | ||
cyan: { | ||
light: custom.$mcr-cyan-light; | ||
base: custom.$mcr-cyan-base; | ||
dark: custom.$mcr-cyan-dark; | ||
} | ||
gold: { | ||
base: custom.$mcr-gold-base; | ||
dark: custom.$mcr-gold-dark; | ||
darker: custom.$mcr-gold-darker; | ||
} | ||
gray: { | ||
dark: custom.$mcr-gray-dark; | ||
base : custom.$mcr-gray-base; | ||
lighter: custom.$mcr-gray-lighter; | ||
lightest: custom.$mcr-gray-lightest; | ||
} | ||
foundation: { | ||
white: custom.$mcr-foundation-white; | ||
ink : custom.$mcr-foundation-ink; | ||
hint: custom.$mcr-foundation-hint; | ||
link: custom.$mcr-foundation-link; | ||
focus: custom.$mcr-foundation-focus; | ||
visited: custom.$mcr-foundation-visited; | ||
|
||
} | ||
success: { | ||
base: custom.$mcr-success-base; | ||
hover: custom.$mcr-success-hover; | ||
dark: custom.$mcr-success-dark; | ||
} | ||
error: { | ||
light: custom.$mcr-error-light; | ||
base: custom.$mcr-error-base; | ||
dark: custom.$mcr-error-dark; | ||
} | ||
} | ||
|
||
} |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I haven't been able to get this to work. I enabled vscode-stylelint to test this, are you using something different?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was running stylelint in app-web manually
npx styelint **/*.scss
- let me surface that as a yarn command also and document. It should be hooked into lint-staged as well (precommit script) I'll double check that.