From 2a9d19065bcb8980ad2eb030a27bee1b44db8176 Mon Sep 17 00:00:00 2001 From: Ans Date: Wed, 11 Sep 2024 14:29:35 -0400 Subject: [PATCH 1/2] Update outdated docs --- CONTRIBUTING.md | 2 +- .../apps/owning-a-home/css/main.scss | 2 +- .../apps/paying-for-college/css/main.scss | 4 +- .../apps/regulations3k/css/main.scss | 2 +- .../unprocessed/apps/retirement/css/main.scss | 4 +- .../rural-or-underserved-tool/css/main.scss | 2 +- .../teachers-digital-platform/css/main.scss | 2 +- cfgov/unprocessed/css/main.scss | 2 +- cfgov/v1/jinja2/v1/layouts/base.html | 2 +- docs/atomic-structure.md | 192 +----------------- docs/editing-components.md | 18 +- docs/running-virtualenv.md | 2 +- esbuild/copy.js | 2 +- stylelint.config.js | 14 +- test/cypress/spec-map.js | 28 +-- 15 files changed, 51 insertions(+), 227 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5935b1c57be..1006fa85832 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,7 +38,7 @@ The overall test coverage of the codebase should not decrease. Python code is expected to follow [PEP8](https://www.python.org/dev/peps/pep-0008/) and [not commit atrocities](https://www.youtube.com/watch?v=wf-BqAjZb8M). -JavaScript, CSS/Less, and markup should follow our +JavaScript, CSS/SCSS, and markup should follow our [front-end standards](https://github.com/cfpb/development). When in doubt, mimic the styles and patterns in the existing codebase. diff --git a/cfgov/unprocessed/apps/owning-a-home/css/main.scss b/cfgov/unprocessed/apps/owning-a-home/css/main.scss index da38e9449df..9550db0b389 100644 --- a/cfgov/unprocessed/apps/owning-a-home/css/main.scss +++ b/cfgov/unprocessed/apps/owning-a-home/css/main.scss @@ -1,6 +1,6 @@ /* ========================================================================== Buying a House - Main Less file + Main SCSS file ========================================================================== */ @use './brand-header'; diff --git a/cfgov/unprocessed/apps/paying-for-college/css/main.scss b/cfgov/unprocessed/apps/paying-for-college/css/main.scss index 7082a0371ef..291f8f4dad8 100644 --- a/cfgov/unprocessed/apps/paying-for-college/css/main.scss +++ b/cfgov/unprocessed/apps/paying-for-college/css/main.scss @@ -2,8 +2,8 @@ paying-for-college ========================================================================== */ -// This is your project's main Less file. -// Project-specific Less rules go after the imports. +// This is your project's main SCSS file. +// Project-specific SCSS rules go after the imports. // Import Design System components. @import '../../../css/main'; diff --git a/cfgov/unprocessed/apps/regulations3k/css/main.scss b/cfgov/unprocessed/apps/regulations3k/css/main.scss index b8f216f2439..8b93f36c650 100644 --- a/cfgov/unprocessed/apps/regulations3k/css/main.scss +++ b/cfgov/unprocessed/apps/regulations3k/css/main.scss @@ -1,6 +1,6 @@ /* ========================================================================== Regulations 3000 - Main Less file for Regulations pages + Main SCSS file for Regulations pages ========================================================================== */ @use '@cfpb/cfpb-design-system/src/utilities' as *; diff --git a/cfgov/unprocessed/apps/retirement/css/main.scss b/cfgov/unprocessed/apps/retirement/css/main.scss index 226419bb34c..766c257445f 100644 --- a/cfgov/unprocessed/apps/retirement/css/main.scss +++ b/cfgov/unprocessed/apps/retirement/css/main.scss @@ -2,8 +2,8 @@ Retirement ========================================================================== */ -// This is your project's main Less file. -// Project-specific Less rules go after the imports. +// This is your project's main SCSS file. +// Project-specific SCSS rules go after the imports. // Import the claiming.scss file @import 'claiming'; diff --git a/cfgov/unprocessed/apps/rural-or-underserved-tool/css/main.scss b/cfgov/unprocessed/apps/rural-or-underserved-tool/css/main.scss index 9898ba65a2b..fc79a821fe4 100644 --- a/cfgov/unprocessed/apps/rural-or-underserved-tool/css/main.scss +++ b/cfgov/unprocessed/apps/rural-or-underserved-tool/css/main.scss @@ -1,6 +1,6 @@ /* ========================================================================== Rural or underserved tool - Main Less file + Main SCSS file ========================================================================== */ @use '@cfpb/cfpb-design-system/src/abstracts' as *; diff --git a/cfgov/unprocessed/apps/teachers-digital-platform/css/main.scss b/cfgov/unprocessed/apps/teachers-digital-platform/css/main.scss index 83408b6c350..5a5b84f0143 100644 --- a/cfgov/unprocessed/apps/teachers-digital-platform/css/main.scss +++ b/cfgov/unprocessed/apps/teachers-digital-platform/css/main.scss @@ -2,7 +2,7 @@ Teachers Digital Platform ========================================================================== */ -// Project specific Less goes here or you can break it up into discrete files. +// Project specific SCSS goes here or you can break it up into discrete files. @import 'atoms/icon'; @import 'molecules/form-fields'; @import 'molecules/search-hero'; diff --git a/cfgov/unprocessed/css/main.scss b/cfgov/unprocessed/css/main.scss index 697bb6df929..76233723c31 100644 --- a/cfgov/unprocessed/css/main.scss +++ b/cfgov/unprocessed/css/main.scss @@ -1,6 +1,6 @@ /* ========================================================================== consumerfinance.gov - Main Less file + Main SCSS file ========================================================================== */ /* Base styles diff --git a/cfgov/v1/jinja2/v1/layouts/base.html b/cfgov/v1/jinja2/v1/layouts/base.html index cb0103138a6..981470ca081 100644 --- a/cfgov/v1/jinja2/v1/layouts/base.html +++ b/cfgov/v1/jinja2/v1/layouts/base.html @@ -122,7 +122,7 @@ ====== The number of stylesheets here must be kept to a minimum. Unless adding a significant amount of CSS that is specific to a single page or - section of the site, all new styles should be added to cfgov/v1/unprocessed/css/main.less. + section of the site, all new styles should be added to cfgov/v1/unprocessed/css/main.scss. #} {% block css %} diff --git a/docs/atomic-structure.md b/docs/atomic-structure.md index 7ba6bdc8537..f2e0f9c2e5d 100644 --- a/docs/atomic-structure.md +++ b/docs/atomic-structure.md @@ -1,179 +1,26 @@ # Notes on Atomic Design -Our components employ the concept of atomic design, meaning that -we break them down into atoms, molecules, and organisms, +In general, our components employ the concept of atomic design, +meaning that we break them down into atoms, molecules, and organisms, each successive level being more complex than the previous. (We do not currently use the template or page concepts as described in [Brad Frost's seminal article introducing atomic design](http://bradfrost.com/blog/post/atomic-web-design/)). -Our components are composed (on the front-end) of HTML, Less, and JavaScript. +Our components are composed (on the front-end) of HTML, SCSS (Sass), and JavaScript. If a component doesn’t have user interactions or require styling, -then it won’t have an associated JS and/or Less file. -Components that are available for adding to a Wagtail page also -require some Python programming—see the -[creating and editing components](editing-components.md) page for details. +then it won’t have an associated JS and/or SCSS file. -We compose our atomic components as follows: +## CSS class name prefixes -## Atoms - -The smallest kind of component. -May not contain any other components. -Prefixed with `a-` in class names. - -### HTML - -```html -
Tag label {{ svg_icon('error') }}
-``` - -### Less - -```css -.a-tag { - cursor: default; - display: inline-block; - padding: 5px 10px; - … -} -``` - -### JavaScript - -None of our atoms require any JavaScript at this time. - -## Molecules - -The medium-sized component. -May contain atoms. -Prefixed with `m-` in class names. - -### HTML - -```html -
- {{ svg_icon('error') }} - -
-``` - -### Less - -```css -.m-notification { - display: none; - position: relative; - padding: @notification-padding-px; - … -} -``` - -### JavaScript - -```js -const BASE_CLASS = 'm-notification'; -function Notification( element ) { - // Constants for the state of this Notification. - const SUCCESS = 'success'; - const WARNING = 'warning'; - const ERROR = 'error'; - - // Constants for the Notification modifiers. - const MODIFIER_VISIBLE = BASE_CLASS + '__visible'; - const _dom = atomicHelpers.checkDom( element, BASE_CLASS ); - const _contentDom = _dom.querySelector( '.' + BASE_CLASS + '_content' ); - … -} -``` - -The Notification molecule can be instantiated -by adding the following to your project's JavaScript code: - -```js -const notification = new Notification(_dom); -notification.init(); -``` - -## Organisms - -The largest component. -May contain atoms, molecules, or -(if no other solution is viable) other organisms. -Prefixed with `o-` in class names. - -### HTML - -```html -
- -
-``` - -### Less - -```css -.o-expandable { - position: relative; - - &__header { - padding: 0; - border: 0; - … - } - … -} -``` - -### JavaScript - -```js -const BASE_CLASS = 'o-expandable'; -function Expandable( element ) { - // Bitwise flags for the state of this Expandable. - const COLLAPSED = 0; - const COLLAPSING = 1; - const EXPANDING = 2; - const EXPANDED = 3; - - // The Expandable element will directly be the Expandable - // when used in an ExpandableGroup, otherwise it can be the parent container. - const _dom = atomicHelpers.checkDom( element, BASE_CLASS ); - const _target = _dom.querySelector( '.' + BASE_CLASS + '_header' ); - const _content = _dom.querySelector( '.' + BASE_CLASS + '_content' ); - … -} -``` - -The Expandable organism can be instantiated -by adding the following to your project's JavaScript code: - -```js -const expandable = new Expandable(_dom.querySelector('.o-expandable')); -expandable.init(_expandable.EXPANDED); -``` - -or - -```js -import { - instantiateAll, - Expandable, -} from '@cfpb/cfpb-design-system/src/index.js'; -instantiateAll('.o-expandable', Expandable); -``` +The atomic components have CSS class names with the prefixes `a-`, `m-`, `o-`, +corresponding to atoms, molecules, and organisms. Additionally, utility classes +have the `u-` prefix. These classes are for one-off adjustments, that are shared +across several components and don't fit neatly into the atomic hierarchy. ## Folder structure Our atomic components are separated and named based on asset type. -HTML, Less, and JavaScript for each component are in separate directories. +HTML, SCSS, and JavaScript for each component are in separate directories. ### HTML @@ -185,7 +32,7 @@ consumerfinance.gov/cfgov/v1/jinja2/v1/includes/organisms/ !!! note - Some of our foundational components get their Less and JavaScript + Some of our foundational components get their SCSS and JavaScript from the [Design System](https://cfpb.github.io/design-system/), but the HTML for their Wagtail block templates is stored in the above folders. @@ -216,23 +63,6 @@ consumerfinance.gov/test/unit_tests/js/organisms/ JavaScript components are built to be rendered on the server and then enhanced via JavaScript on the client. -The basic interface for the components is as follows: - -```js -function AtomicComponent(domElement) { - // Ensure the passed in Element is in the DOM. - // Query and store references to sub-elements. - // Instantiate child atomic components. - // Bind necessary events for referenced DOM elements. - // Perform other initialization related tasks. - this.init = function init() {}; - - // General teardown function - // We don't remove the element from the DOM so - // we need to unbind the events. - this.destroy = function destroy() {}; -} -``` We generally favor composition over inheritance. You can get more information by reading the following: diff --git a/docs/editing-components.md b/docs/editing-components.md index cc5b6752713..dcb9fefeb67 100644 --- a/docs/editing-components.md +++ b/docs/editing-components.md @@ -254,13 +254,13 @@ those context variables can also be output with simple Jinja2 expression tags: #### Adding CSS If a component needs any custom styling not already provided -by the [Design System](https://github.com/cfpb/design-system) or consumerfinance.gov, -you can add it by creating a new -[Less](http://lesscss.org/) file for the component. +by the [Design System](https://github.com/cfpb/design-system) +or consumerfinance.gov, you can add it by creating a new +[SCSS](https://sass-lang.com/) file for the component. !!! note - Please be sure that you actually need new Less before creating it. + Please be sure that you actually need new SCSS before creating it. We have a wide array of styles already available in the [Design System components](https://cfpb.github.io/design-system/components/) and [here in consumerfinance.gov](https://github.com/cfpb/consumerfinance.gov/tree/main/cfgov/unprocessed/css), @@ -273,13 +273,13 @@ for site-wide use, this file should live in `cfgov/unprocessed/css//`. (Choose the deepest folder according to the atomic rank of the component.) Continuing the `RelatedContent` example, if it needed its own styles, -it would live at `cfgov/unprocessed/css/molecules/related-content.less`. +it would live at `cfgov/unprocessed/css/molecules/related-content.scss`. -Newly-created Less files need to be imported into the project's main -`main.less` file, located at `cfgov/unprocessed/css/main.less`. +Newly-created SCSS files need to be imported (with `@use`) into the project's +main `main.scss` file, located at `cfgov/unprocessed/css/main.scss`. Please place them in the appropriate section for their atomic rank. -Because consumerfinance.gov uses `main.less` to build a single CSS file +Because consumerfinance.gov uses `main.scss` to build a single CSS file for almost the entire project, it is not necessary to tell the Python model anything about a component-specific stylesheet (for general-purpose, site-wide components). @@ -288,7 +288,7 @@ That is _not_ the case with JavaScript, as we will see in the next section. !!! note If you're working on a component that belongs to a particular sub-app, - its Less file should live in `cfgov/unprocessed//css/`. + its SCSS file should live in `cfgov/unprocessed//css/`. #### Adding JavaScript diff --git a/docs/running-virtualenv.md b/docs/running-virtualenv.md index f4ebd410c9b..4e20c5e25aa 100644 --- a/docs/running-virtualenv.md +++ b/docs/running-virtualenv.md @@ -125,7 +125,7 @@ The following yarn tasks are available: ``` yarn scripts # Build the Javascript with esbuild -yarn styles # Build the Less with esbuild w/ its PostCSSPlugin +yarn styles # Build the SCSS with esbuild and its PostCSS plugin yarn copy # Move static files to the output directory yarn build # Run scripts, styles, and copy along with app-specific scripts yarn watch # Run the build then watch JS and LESS changes diff --git a/esbuild/copy.js b/esbuild/copy.js index 9d2c9d5ec28..ddcea13d2ff 100644 --- a/esbuild/copy.js +++ b/esbuild/copy.js @@ -13,7 +13,7 @@ async function copy(baseConfig) { const files = await getFiles(resolvedBase); const staticFiles = files.filter( - (v) => !v.match(/\/\.[-.\w]*$|\.js$|\.less$|\.css$/i), + (v) => !v.match(/\/\.[-.\w]*$|\.js$|\.scss$|\.css$/i), ); const inDirs = [...new Set(staticFiles.map((v) => dirname(v)))]; diff --git a/stylelint.config.js b/stylelint.config.js index 3439715fe36..487ec4a0f47 100644 --- a/stylelint.config.js +++ b/stylelint.config.js @@ -9,25 +9,21 @@ declaration-block-no-redundant-longhand-properties - declaration-empty-line-before - Turned off. TODO: Turn on this rule and work out what style we want. -declaration-property-value-no-unknown - - Turned off for Less per documentation guidance. media-feature-range-notation - - Prefer prefixed values, since Less doesn't support ranges. -media-query-no-invalid - - Turned off because of https://github.com/ssivanatarajan/stylelint-less/issues/6 + Prefer prefixed values, traditionally used since Less doesn't support ranges. + TODO: Turn on this rule and migrate to newer style. no-descending-specificity - Turned off, but probably shouldn't be. TODO: Turn on this rule and see if issues can be fixed. number-max-precision - - TODO: See if long decimal values can be shortened using the unit helper. + TODO: See if long decimal values can be shortened. rule-empty-line-before - Custom setting that differs from stylelint-config-standard. selector-id-pattern - Turned off. TODO: Turn on this rule and work out regex for BEM syntax. selector-class-pattern - - Turned off. - TODO: Turn on this rule and work out regex for BEM syntax. + getBEM style syntax check for classes. scss/operator-no-newline-after - Turned off. Prettier(?) wraps long lines, so sometimes the + operator ends up at the end of the line. @@ -42,9 +38,7 @@ export default { 'color-function-notation': ['legacy'], 'declaration-block-no-redundant-longhand-properties': null, 'declaration-empty-line-before': null, - 'declaration-property-value-no-unknown': null, 'media-feature-range-notation': ['prefix'], - 'media-query-no-invalid': null, 'no-descending-specificity': null, 'number-max-precision': 10, 'rule-empty-line-before': [ diff --git a/test/cypress/spec-map.js b/test/cypress/spec-map.js index f4db26aff9c..8c59e479bc2 100644 --- a/test/cypress/spec-map.js +++ b/test/cypress/spec-map.js @@ -19,7 +19,7 @@ const directories = [ 'cfgov/unprocessed/apps/filing-instruction-guide', 'cfgov/filing_instruction_guide', 'cfgov/unprocessed/js/organisms/SecondaryNav.js', - 'cfgov/unprocessed/css/organisms/secondary-nav.less', + 'cfgov/unprocessed/css/organisms/secondary-nav.scss', 'cfgov/v1/jinja2/v1/includes/organisms/secondary-nav-fig.html', ], 'compliance/small-business-lending', @@ -85,7 +85,7 @@ const directories = [ [ [ 'cfgov/unprocessed/js/routes/on-demand/chart.js', - 'cfgov/unprocessed/css/on-demand/chart.less', + 'cfgov/unprocessed/css/on-demand/chart.scss', 'cfgov/v1/jinja2/v1/includes/organisms/chart.html', /cfgov\/v1\/.*\.py/, ], @@ -104,7 +104,7 @@ const directories = [ 'cfgov/unprocessed/js/routes/on-demand/filterable-list-controls.js', 'cfgov/unprocessed/js/organisms/FilterableListControls.js', 'cfgov/unprocessed/js/modules/util/FormModel.js', - 'cfgov/unprocessed/css/organisms/filterable-list-controls.less', + 'cfgov/unprocessed/css/organisms/filterable-list-controls.scss', 'cfgov/v1/jinja2/v1/includes/organisms/filterable-list-controls.html', 'cfgov/v1/jinja2/v1/includes/organisms/filterable-list-results.html', /cfgov\/v1\/.*\.py/, @@ -115,7 +115,7 @@ const directories = [ [ 'cfgov/unprocessed/js/organisms/Footer.js', 'cfgov/unprocessed/js/modules/footer-button.js', - 'cfgov/unprocessed/css/organisms/footer.less', + 'cfgov/unprocessed/css/organisms/footer.scss', 'cfgov/v1/jinja2/v1/includes/organisms/footer.html', /cfgov\/v1\/.*\.py/, ], @@ -128,11 +128,11 @@ const directories = [ 'cfgov/unprocessed/js/organisms/MegaMenuDesktop.js', 'cfgov/unprocessed/js/organisms/MegaMenuMobile.js', 'cfgov/unprocessed/js/molecules/GlobalSearch.js', - 'cfgov/unprocessed/css/organisms/header.less', - 'cfgov/unprocessed/css/organisms/mega-menu.less', - 'cfgov/unprocessed/css/molecules/global-eyebrow.less', - 'cfgov/unprocessed/css/molecules/global-header-cta.less', - 'cfgov/unprocessed/css/molecules/global-search.less', + 'cfgov/unprocessed/css/organisms/header.scss', + 'cfgov/unprocessed/css/organisms/mega-menu.scss', + 'cfgov/unprocessed/css/molecules/global-eyebrow.scss', + 'cfgov/unprocessed/css/molecules/global-header-cta.scss', + 'cfgov/unprocessed/css/molecules/global-search.scss', 'cfgov/v1/jinja2/v1/includes/organisms/header.html', 'cfgov/mega_menu/jinja2/mega_menu', 'cfgov/v1/jinja2/v1/includes/molecules/global-eyebrow.html', @@ -145,7 +145,7 @@ const directories = [ [['cfgov/v1/jinja2/v1/layouts/base.html'], 'components/meta'], [ [ - 'cfgov/unprocessed/css/organisms/filterable-list-controls.less', + 'cfgov/unprocessed/css/organisms/filterable-list-controls.scss', 'cfgov/unprocessed/js/organisms/FilterableListControls.js', 'cfgov/v1/jinja2/v1/includes/organisms/filterable-list-controls.html', /cfgov\/v1\/.*\.py/, @@ -167,8 +167,8 @@ const directories = [ [ [ 'cfgov/unprocessed/js/routes/on-demand/mortgage-performance-trends.js', - 'cfgov/unprocessed/css/on-demand/mortgage-performance-trends.less', - 'cfgov/unprocessed/css/on-demand/chart.less', + 'cfgov/unprocessed/css/on-demand/mortgage-performance-trends.scss', + 'cfgov/unprocessed/css/on-demand/chart.scss', 'cfgov/unprocessed/js/organisms/MortgagePerformanceTrends', 'cfgov/v1/jinja2/v1/includes/organisms/mortgage-chart.html', 'cfgov/v1/jinja2/v1/includes/organisms/mortgage-map.html', @@ -181,7 +181,7 @@ const directories = [ [ 'cfgov/unprocessed/apps/paying-for-college', 'cfgov/unprocessed/js/organisms/SecondaryNav.js', - 'cfgov/unprocessed/css/organisms/secondary-nav.less', + 'cfgov/unprocessed/css/organisms/secondary-nav.scss', 'cfgov/paying_for_college', ], 'paying-for-college/disclosures', @@ -190,7 +190,7 @@ const directories = [ [ 'cfgov/unprocessed/apps/paying-for-college', 'cfgov/unprocessed/js/organisms/SecondaryNav.js', - 'cfgov/unprocessed/css/organisms/secondary-nav.less', + 'cfgov/unprocessed/css/organisms/secondary-nav.scss', 'cfgov/paying_for_college', ], 'paying-for-college/your-financial-path-to-graduation', From eb113fbc882e35d4986dfac34ec5381a712e0e2f Mon Sep 17 00:00:00 2001 From: Ans Date: Wed, 11 Sep 2024 14:57:17 -0400 Subject: [PATCH 2/2] Update docs/running-virtualenv.md Co-authored-by: Wyatt Pearsall --- docs/running-virtualenv.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/running-virtualenv.md b/docs/running-virtualenv.md index 4e20c5e25aa..046b3f57108 100644 --- a/docs/running-virtualenv.md +++ b/docs/running-virtualenv.md @@ -128,7 +128,7 @@ yarn scripts # Build the Javascript with esbuild yarn styles # Build the SCSS with esbuild and its PostCSS plugin yarn copy # Move static files to the output directory yarn build # Run scripts, styles, and copy along with app-specific scripts -yarn watch # Run the build then watch JS and LESS changes +yarn watch # Run the build then watch JS and SCSS changes yarn lint # Run frontend linting yarn jest # Run frontend tests yarn test # Run both