Merge pull request #8567 from cfpb/ans_atomic_docs

Update outdated docs

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.
 

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';

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';

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 *;

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';

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 *;

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';

cfgov/unprocessed/css/main.scss

@@ -1,6 +1,6 @@
 /* ==========================================================================
    consumerfinance.gov
-   Main Less file
+   Main SCSS file
    ========================================================================== */
 
 /* Base styles

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 %}

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
-<div class="a-tag">Tag label {{ svg_icon('error') }}</div>
-```
-
-### 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
-<div
-  class="m-notification
-         m-notification--visible
-         m-notification--error"
->
-  {{ svg_icon('error') }}
-  <div class="m-notification__content" role="alert">
-    <div class="m-notification__message">Page not found.</div>
-  </div>
-</div>
-```
-
-### 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
-<div class="o-expandable">
-  <button class="o-expandable__header">
-    <div class="o-expandable__label">…</div>
-  </button>
-</div>
-```
-
-### 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:

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/<atoms|molecules|organisms>/`.
 (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/<app-name>/css/`.
+      its SCSS file should live in `cfgov/unprocessed/<app-name>/css/`.
 
 #### Adding JavaScript
 

docs/running-virtualenv.md

@@ -125,10 +125,10 @@ 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
+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

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)))];