Components are part of patterns

Components are intended for re-use and should be named for what they are; that is:

• vf-box (not "vf-introduction")
• vf-button (not "vf-call-to-action")
• vf-grid (not "vf-wide-layout")
• vf-header (not "vf-big-headline")
• vf-form

This ensures that that a box will always be rectangular-ish pattern on pages, whereas an "introduction" may be a box today, but become simply large text after a redesign.

When naming components, use something simple and obvious.

Component types

We use a variation of the atomic design methodology. We use: elements, blocks, and containers.

• element: a heading or button
• block: a teaser, summary or search form
• container: would be a group of summaries

More about VF component types

Components have

• Lots of code
  • CHANGELOG.md: Notable changes
  • index.scss: Used to generate a standalone version of the component's CSS
  • package.json: Version information and any required npm dependencies
    • you should avoid npm-requiring other VF components
  • README.md: Information on the role and how to use a component
  • vf-sample.config.yml: Configuration information about the compony, release status, type of component, variants
  • vf-sample.njk: A Nunjuck-based template
  • vf-sample.scss: Styling
  • vf-sample.js: JavaScript
  • vf-sample.react.js: React wrapper
  • Dynamic files made at build time
    • _package.variables.scss_: Variables extracted from package.json that can be used in the Sass, such as a version number
    • _vf-sample.precompiled.js_: A compiled version of the Nunjucks template
    • _vf-sample.css_: Standalone CSS made from the index.scss
• An HTML code template (Nunjucks)
• Documentation on how to use

If your pattern is primarily intended to be used for particular websites or a brand, give it a name that is attached to the role it performs; that is:

• vf-group-masthead
• vf-registration-form
• vf-start-page

Naming for the role the pattern does allows us to change the future visual structure, so a "display headline" today may have a black background, but tomorrow might have no background and be large and italic text.

Patterns have

• An HTML code template (Nunjucks)

• Documentation on how to use

For further guidance on the distinctions, see: Patterns ≠ Components and UK.gov's information on patterns vs components.

And see these VF guidance entries:

• How to make a component

• Components types