\n \n```\n\n**Fragments will nest other components instead of re-creating them**. This enables full customization of every nested component. For example, the Form Group component will pull in the Input component.\n\n```html\n
\n```\n\n##### π _*.html.erb\n\n**Embedded Ruby partial templates** are scripted Ruby files with HTML and Ruby code intermixed. There is no binding syntax for HTML so it is less formal but more flexible. It is much easier to write Ruby code within templates which makes it less \"componentized.\" This application doesn't operate inside of a Ruby on Rails environment so there are no helper methods, most notably the `render 'partial-name'` method for including other partials. The lowest level and simplest version of Rails `render` is `ERB.new(File.read('partial-name'), 0, 0, [*('a'..'z')].sample(8).join).result_with_hash({key: 'value'})` which can be cumbersome to manage.
.\n\n**The same rules for modifiers and nesting other components applies to ERB templates**.\n\n```erb\n
<%= modifier %><% end %>\"<% if defined?(multiple) %> data-allow-multiple<% end %>>\n \n```\n\nNesting another component:\n\n```ruby\n<%= ERB.new(File.read('packages/cfa-input/_cfa-input.html.erb'), 0, 0, '@input')\n .result_with_hash({\n input: input,\n inputGroup: (inputGroup if defined?(inputGroup))\n }.compact) %>\n```\n\nIn some cases the string `@input` in the example above needs to be unique. It can be replaced with `[*('a'..'z')].sample(8).join` to always create a random string.\n\n##### π _*.scss\n\n**Dart Sass** modules **extend** the styling for custom or USWDS components that can't be styled using USWDS settings alone. Where possible, distinguish between theme styles and USWDS styles. Always prefer USWDS Sass theme tokens, utilities, functions, and other mixins over custom methods. This ensures that custom styling remains within the design system.\n\n**Use the Block, element, modifier (BEM) naming convention**. Always prefix theme classes with `.cfa-`. Use the same name as the component for the block selector.
Read more about the BEM naming convention.\n\n```\n.cfa-block { }\n.cfa-block__element { }\n.cfa-block--modifier { }\n```\n\n**Use the CSS `.cfa-` prefix for custom styles**. This ensures clarity when using custom theme styles versus USWDS defaults. Do not add style overrides dependent on `.usa-` classes as the root class.\n\n```scss\n.cfa-button:not(.usa-button--unstyled) {\n // ...\n```\n\n**Reuse settings variables defined by theme settings**. They are always prefixed by `$theme-`. Often, they need to be passed to utility functions that will interpret the token value.
Read more about design tokens on the USWDS documentation site.\n\n```scss\n@use 'uswds-core' as *;\n\n.cfa-button.usa-button--big:not(.usa-button--unstyled) {\n font-size: font-size($theme-button-font-family, 'lg');\n // ...\n```\n\n**Always use the `units()` function** to convert unit design tokens to the spacing dimensions defined by the system. Never hard-code pixel values.
Read more about spacing unit tokens on the USWDS documentation site.\n\n```scss\n@use 'uswds-core' as *;\n\n.cfa-button:not(.usa-button--unstyled) {\n padding: units(2) units(2.5);\n\n // ...\n```\n\n**Use the `set-text-and-bg` mixin** when defining a background color and foreground text color. This ensures color combinations are run through the USWDS contrast checker. Combinations that don't have sufficient contrast (WCAG AA 2.1) will emit an exception to stdout.
Read more about color on the USWDS documentation site.\n\n```scss\n@use 'uswds-core' as *;\n\n.cfa-button.usa-button--outline:not(.usa-button--unstyled):not([disabled]):not([aria-disabled=true]) {\n @include set-text-and-bg(\n $bg-color: $theme-body-background-color,\n $preferred-text-color: 'ink',\n $context: 'CfA Button'\n );\n\n // ...\n```\n\n**Use theme and state color tokens over system color tokens**. This ensures that the color theme has continuity throughout components. Read more about color. Read more about each color token types on the USWDS documentation site:\n\n*
Theme color tokens\n*
State color tokens\n*
System color tokens\n\n```scss\n@use 'uswds-core' as *;\n\n.cfa-button--no {\n > svg {\n fill: color('error');\n\n // ...\n\n.cfa-button--yes {\n > svg {\n fill: color('success-darker');\n\n // ...\n```\n\n##### π *.js\n\n**ES JavaScript** modules provide functionality to custom components or provide a utility wrapper around external libraries. They are written using as standard
modules and defined using
class templates.\n\n* **Components properties and methods are be encapsulated**. Writing properties to global variables, such as the `window`, is discouraged. Write custom properties to the component instance, instead.\n* **All JavaScript should be considered a progressive enhancement**. There should be a suitable default state for the component if the page does not invoke JavaScript. ARIA properties, such as `aria-hidden` will only be toggled when the component is instantiated.\n* Use the `data-js` to define selectors for components. Use `aria-controls` to define target element selectors. Follow guidance defined by the
ARIA Authoring Practices Guide.\n\n**Always use a class to define a component (using the component name, capitalized and camel-cased)**:\n\n```javascript\nclass Component {\n constructor() {\n\n // ...\n\nexport default Component;\n```\n\nUsing, or, creating a class instance:\n\n```javascript\nimport Component from '@codeforamerica/uswds/packages/cfa-component/cfa-component.js';\n\nnew Component();\n```\n\nClasses can be easily extended or have settings configurations passed to them to enable, disable, or modify internal functionality. Methods and properties within them can be overridden or accessed individually. This variety makes them flexible to work with.\n\n```javascript\nimport Component from '@codeforamerica/uswds/packages/cfa-component/cfa-component.js';\n\n// Set a component property before it is initialized.\nComponent.property = 'value';\n\n// Initialize a component with custom values.\nlet component = new Component({\n property: 'value',\n method: () => {}\n});\n\n// Call a component method after initialization.\ncomponent.internalMethod();\n```\n\n**Static properties used within the class are defined before the export**. They are often set for the class within the constructor with an optional settings override that can be passed upon instantiation.\n\n```javascript\nclass Component {\n constructor(s = {}) {\n this.selector = s.selector ? s.selector : Component.selector;\n\n // ...\n\n}\n\nComponent.selector = '[data-js=\"component\"]';\n\n// ...\n\nexport default Component;\n```\n\n**Click, change, or other event listeners are added to the `body`**. This makes functions less dependent on individual elements and more compatible with reactive frameworks.\n\n```javascript\nclass Component {\n constructor() {\n\n // ...\n\n document.querySelector('body')\n .addEventListener('click', event => {\n if (event.target.matches(this.selector)) {\n this.internalMethod(event.target);\n }\n });\n\n // ...\n```\n\nClasses may be instantiated once for all elements they concern.\n\n```javascript\nimport Component from '@codeforamerica/uswds/packages/cfa-component/cfa-component.js';\n\nnew Component();\n```\n\nOr, they may be instantiated per element. However, the main selector for the component should always be stored as a static property.\n\n```javascript\n(elements => {\n for (let i = 0; i < elements.length; i++) {\n new Component(elements[i]);\n }\n})(document.querySelectorAll(Component.selector));\n```\n\nBelow is the general structure for theme component classes.\n\n```javascript\n'use strict';\n\nclass Component {\n /**\n * Component constructor\n *\n * @param {Object} s Optional settings configuration\n *\n * @return {Object} Instance of Component\n */\n constructor(s = {}) {\n /**\n * Instance setting overrides. If any of the properties are passed in the\n * s object, they are used by the instance instead of the default properties.\n */\n\n this.selector = s.selector ? s.selector : Component.selector;\n\n this.externalMethod = s.externalMethod ? s.externalMethod : Component.externalMethod;\n\n /**\n * Initialization for the progressively enhanced features\n */\n\n this.init();\n\n /**\n * Main event listener for the component\n */\n\n document.querySelector('body')\n .addEventListener('click', event => {\n if (event.target.matches(this.selector)) {\n this.internalMethod(event.target);\n }\n });\n\n return this;\n }\n\n /**\n * Initializes the component, setting progressively enhanced\n * ARIA attributes or other relevant dynamic templates.\n *\n * @return {Object} Instance of Component\n */\n init() {\n\n // ...\n\n return this;\n }\n\n /**\n * An internal class method.\n *\n * @param {Object} target Method argument\n *\n * @return {Object} Instance of Component\n */\n internalMethod(target) {\n\n // ...\n\n return this;\n }\n}\n\n/** @type {String} The main selector for the Component event listener */\nComponent.selector = '[data-js=\"component\"]';\n\n/**\n * An external class method\n */\nComponent.externalMethod = () => {}\n\nexport default Component;\n```\n\n#### Notes on external dependencies\n\nComponents *may* have external dependencies if they provide a very substantial or specific benefit necessary for that component to function.\n\n* **Do not add any design system other than the USWDS** (Bootstrap, Material, or other). Design systems are not intended to be used together. The USWDS also provides its own set of CSS utilities so Tailwindcss is also not supported at this time.\n\n* **Do not install jQuery**. It is not needed for most modern JS applications and it creates an oversized dependency if one component uses it. Use
plain JavaScript.\n\n* **Do not install Underscore or LoDash**. Use standard
Array or
Object prototypes.\n\n* **The use of reactive front-end frameworks are not supported at this time** (React.js, Vue.js, or other).\n\nNew dependencies should be installed as regular dependencies using `npm install` so that other projects can inherit them as well.\n\n#### Modifying the compilation of Sass or JavaScript\n\nThe source, distribution, and plugins that transform Sass or JavaScript can be modified in the [entrypoints.js](entrypoints.js) file. Each entrypoint is defined as an object `{}` in the export.\n\n```javascript\nmodule.exports = [\n {\n /* module settings */\n },\n {\n /* module settings */\n },\n {\n /* module settings */\n }\n];\n```\n\nEach object may either be a style or script module. The difference is determined by the extension of the input file.\n\n##### Style modules\n\nCSS is translated from the source using [styles.js](styles.js). It uses the
Dart Sass JavaScript API to compile Sass to CSS. The CSS is then run through a series of
PostCSS plugins to optimize the output:\n\n1.
purgecss. Removes unused CSS (currently unused but will be supported).\n1.
autoprefixer. Adds vendor prefixes to CSS rules.\n1.
mqpacker. Combines all media queries that are the same.\n1.
cssnano. Compresses CSS.\n\nThe attributes for style modules are documented in the [entrypoints.js](entrypoints.js) file in more detail but generally looks like the following:\n\n```javascript\n{\n input: 'src/scss/_styles.scss',\n output: [{\n file: 'dist/css/styles.css',\n options: {\n sourceMap: true,\n loadPaths: [ /* ... */ ]\n }\n }],\n plugins: [ /* ... */ ]\n}\n```\n\n##### Script modules\n\nJavaScript is translated from the source using [scripts.js](scripts.js). It uses the
Rollup.js to combine concatenate scripts and perform some transformations. The JavaScript is then run through a series of
plugins to translate the output:\n\n1.
commonJs. Enables the support for CommonJS module import.\n1.
nodeResolve. Adds support for the Node.js module resolution algorithm.\n1.
replace. Performs string transformations on the JavaScript output.\n\nThe attributes for script modules are documented in the [entrypoints.js](entrypoints.js) file in more detail but generally looks like the following:\n\n```javascript\n{\n input: 'src/js/index.js',\n output: [{\n file: 'dist/js/default.js',\n options: {\n sourceMap: true,\n loadPaths: [ /* ... */ ]\n }\n }],\n plugins: [ /* ... */ ]\n}\n```\n\n##### Module plugins\n\nWhen contributing to the theme, plugins should only be added as default plugins (defined above) if all modules benefit from it. They can be added to either [styles.js](styles.js) or [scripts.js](scripts.js) directly. Which and what order plugins run can be configured for each module object in the plugins attribute. For example, a styles module with this set will run all the default plugins:\n\n```javascript\nplugins: [\n 'purgecss',\n 'autoprefixer',\n 'mqpacker',\n 'cssnano'\n]\n```\n\nOmit a plugin by commenting it out:\n\n```javascript\nplugins: [\n // 'purgecss',\n 'autoprefixer',\n 'mqpacker',\n 'cssnano'\n]\n```\n\n##### Config.js\n\nSeveral paths, entrypoint names, distribution strings, and Node module load paths for the theme are defined in the [config.js](config.js) file.\n\n##### External projects\n\nExternal projects can use these module scripts to compile their own Sass and JavaScript. This is documented in the [@codeforamerica/uswds-starter](https://github.com/codeforamerica/uswds-starter). They need to set up their own NPM project, entrypoints.js file, and project source. This needs to be kept in mind when updating the theme's module scripts and their configuration.\n\nThey can use the plugins attribute in their entrypoints.js file to choose default plugins or configure their own plugins. For example, the `purgecss` plugin can be configured by swapping the plugin string with an instance of the plugin (
using instructions from the purgecss documentation):\n\n```javascript\nplugins: [\n purgecss({\n content: [\n path.join(__dirname, 'dist/**/*.html')\n ],\n }),\n 'autoprefixer',\n 'mqpacker',\n 'cssnano'\n]\n```\n\nNew plugins should be installed as regular dependencies using `npm install` so that other projects can inherit them as well.\n\n#### Committing changes and publishing\n\nAfter development, changes to the theme need to be staged, committed, tagged, and published to the NPM registry for other projects to inherit. [Create a pull request](https://github.com/codeforamerica/uswds/compare) with your changes for review. They will be squashed and merged into the main branch.\n\n##### Publishing\n\nThe simple workflow for this uses two NPM scripts: `version` and `publish`. They must be run sequentially. Choose an appropriate
semantic version increment: either `major`, `minor`, or `patch`. Then pass that to the `version` command. This will generate a new build for the package and production documentation site. The force flag, `-f` will force the staging of changes to the version commit.\n\n```bash\nnpm version {{ major/minor/patch }} -f\n```\n\nOnce the build and version commit and tag are complete, run the publish command to push changes to the remote. You will need to be authenticated to NPM to run this command by running the login command first.\n\n```bash\nnpm login\n```\n\nIf you are already authenticated you may skip the command above and run:\n\n```bash\nnpm publish\n```\n\nThis will push changes to the [remote repository](https://github.com/codeforamerica/uswds), publish the latest version of the documentation site to [GitHub pages](https://codeforamerica.github.io/uswds), and publish the latest package to the [NPM registry](https://www.npmjs.com/package/@codeforamerica/uswds).\n\n---\n\n### Project directory and file structure\n\n```\nβ π dist β All static files for the site are distributed here, including HTML, CSS, JavaScript, SVGs, images, and font files.\nβ π src β Folder for source files such as Sass and JavaScript modules.\n β π views β Folder for 11ty template views.\n β π _layouts β This folder contains layouts extended by other view files.\n β π _partials β This folder contains partials included in other view files.\n β π **/*.md β View files are usually Markdown files. Directories and file names reflect the URL pattern for the static site pages.\n β π scss β Folder for Sass entry points.\n β π _site.scss β Entry point for the site and theme styles are imported and configured.\n β π _styles.scss β Entry point for only the theme styles are imported and configured.\n β π js β Folder for JavaScript entry points.\n β π index.js β Entry point for where site and theme scripts are imported and configured.\nβ π packages β Folder for CfA theme components, including USWDS component stylesheets and templates for Thymeleaf and ERB.\n β π cfa-uswds-theme β This package includes the main theme settings for the USWDS.\n β π cfa-uswds β This package actively extends the USWDS core settings with the theme settings.\n β π cfa-core β This package stores settings that arenβt supported by the USWDS but are used by other component packages.\n β π cfa β This package imports all of the theme component packages.\n β π cfa-* β All additional *packages* are theme components or utilities.\n β π *.th.html β A Thymeleaf template component file for storing component markup.\n β π _*.html.erb β An Embedded Ruby partial template file for storing component markup.\n β π _*.scss β A Sass styling file for overriding or extending USWDS styles.\n β π *.js β A JavaScript file for functionality (currently, not to be confused with web components).\nβ π config.js β Configuration for the theme, including base path definitions for static and source files.\nβ π eleventy.config.js β Configuration file for the 11ty site.\nβ π entrypoints.js β Defines the configuration for Sass and JavaScript modules and their distribution.\nβ π styles.js β Node.js script for generating CSS from Sass using Sass and PostCSS.\nβ π scripts.js β Node.js script for bundling JavaScript modules using Rollup.js.\nβ π package.json β Defines the theme package for NPM, manages dependencies, and CLI scripts.\nβ π .nvmrc β Used to define the Node.js latest version number supported during development.\n```\n\n---\n\n### NPM Scripts\n\nThe following NPM scripts, which are CLI commands, are available to run the primary development functions of the application.\n\n#### Start\n\nCompile styles, scripts, views, and start the 11ty server. Watch for changes to relevant files.\n\n```bash\nnpm run start\n```\n\n#### Default\n\nCompile styles, scripts, views. Runs once on relevant files.\n\n```bash\nnpm run default\n```\n\n#### Views\n\nStart the 11ty server. Watches for changes to relevant view and component templates.\n\n```bash\nnpm run views\n```\n\n#### Scripts\n\nWatch for changes to JavaScript files then compile JavaScript using Rollup.js.\n\n```bash\nnpm run scripts\n```\n\n#### Styles\n\nWatch for changes to Sass files then compile Sass using its built-in JavaScript API.\n\n```bash\nnpm run styles\n```\n\n#### Production\n\nCompiles views, styles, and scripts for production.\n\n```bash\nnpm run production\n```\n\n#### Preview\n\nCompiles views, styles, and scripts for production and run the 11ty server in \"production mode.\" (note, this will pull assets from production).\n\n```bash\nnpm run preview\n```\n\n#### Version\n\nThis script hooks into the default
`npm version` command to compile views, scripts, and styles for production, and staging them for commit **before** NPM creates a version commit and Git version tag.\n\nThis script doesn't need to run on its own, just run `npm version {{ semantic version }}` when you are ready to commit a new version of the package to the repository before publishing.\n\n```bash\nnpm run version\n```\n\n#### Pre-publish\n\nThis script hooks into the default
`npm publish` command to push local commits and tags to remote **before** NPM publishes the latest version to its registry.\n\nThis script doesn't need to run on its own, just run `npm publish` when you are ready to publish the latest version of the package.\n\n```bash\nnpm run prepublishOnly\n```\n\n#### Publish\n\nThis script hooks into the default
`npm publish` command to push the [dist/](dist) directory to the GitHub Pages branch, gh-pages, which is the \"production\" environment for the site.\n\nThis script doesn't need to run on its own, just run `npm publish` when you are ready to publish the latest version of the package.\n\n```bash\nnpm run publish\n```\n\n---\n\n### Configuration\n\nThe [package.json](package.json) contains configuration for the package name, public homepage URL, design file, and other NPM specifics.\n\nThe [config.js](config.js) file contains common configuration for the 11ty site and compilation path definitions for source Sass and JavaScript entry points.\n\nThe [entrypoints.js](entrypoints.js) contains configuration for source Sass and JavaScript entry point modules. Default plugin settings for PostCSS and Rollup.js are defined in the [styles.js](styles.js) and [scripts.js](scripts.js) files.\n\n---\n\n### 11ty\n\nThe [eleventy.config.js](eleventy.config.js) defines the customized functionality available to templates. The main additions are library and plugin configuration,
custom shortcodes, global data, and collections. Shortcodes are noted below but documented in more detail in the [eleventy.config.js](eleventy.config.js) file.\n\n#### **Component**\n\nRender a component. The JSON context fills the template slots with the values used by the template. The first boolean value determines whether to return rendered (false, default) or escaped (true) HTML. The second boolean determines wether to return both the rendered default Thymeleaf template (false) or both Thymeleaf and ERB templates (true).\n\n```liquid\n{% component 'name' 'context (JSON String)' false false %}\n```\n\n#### Markdown\n\nCompile a Markdown string to HTML.\n\n```liquid\n{% md 'String (Markdown String)' %}\n```\n\n#### Thymeleaf\n\nRetrieve an escaped Thymeleaf template. The boolean value determines whether to return the template fragment contents (false, default) or the template fragment include statement (true).\n\n```liquid\n{% thymeleaf 'name' false %}\n```\n\n#### Embedded Ruby\n\nRetrieve an escaped Embedded Ruby template partial. The boolean value determines whether to return the template contents (false, default) or ERB partial render statement (true).\n\n```liquid\n{% erb 'name' false %}\n```\n\n#### Block\n\nCreate a code block demonstration from the supplied string. Supported syntax types are defined in the HighlightJs block in the [config.js](config.js) file.\n\n```liquid\n{% block 'type' 'String' %}\n```\n\n#### Get File\n\nRetrieve a package file path for a package by its type.\n\n```liquid\n{% getFile 'name' 'String (value of thymeleaf, erb, stylesheet, or javascript)' %}\n```\n\n#### Create ID\n\nGenerate a random string to use as a unique ID.\n\n```liquid\n{% createId %}\n```\n\n#### Create Slug\n\nGenerate a slug (URL friendly string) from a human readable string (\"My String\" would become \"my-string\").\n\n```liquid\n{% createSlug 'string' %}\n```\n","readmeFilename":"README.md"}