Skip to content

Latest commit

 

History

History
96 lines (60 loc) · 2.84 KB

002-restructure-based-on-single-package.md

File metadata and controls

96 lines (60 loc) · 2.84 KB

Restructure single GOV.UK Frontend package

Date: 2018-05-10

Status: Accepted

Context

We implemented the 002 Proposal in alphagov/govuk-frontend#680

We have then restructured the code base in alphagov/govuk-frontend#693

This is to:

  • solve issues around components importing files that export CSS
  • take advantage of the single package - the old structure was based around each folder being it's own package.
  • make the entry points to files clearer.
  • better reflect conventions by giving each layer it's own folder, this moves them out of a confusingly named 'global' parent folder.

Decision

Structure

GOV.UK Frontend is broken into a number of layers in order to help provide a logical structure, loosely following the conventions of ITCSS.

  1. Settings
  2. Tools
  3. Helpers
  4. Core
  5. Objects
  6. Components
  7. Utilities
  8. Overrides

Each folder has its own entry point (_all.scss).

Settings

Global variables for the project, for example colour palettes and spacing and typography scales.

This layer should not output any CSS.

Tools

Mixins or functions that implement either logic (e.g. conditionally outputting CSS) or calculations, and that need to be made available globally.

This layer should not output any CSS.

Helpers

Mixins that abstract common styling (for example, focus states or visually hidden content)

This layer should not output any CSS.

Core

Basic content styles for typography, links etc. The classes defined in this layer would generally correspond to an HTML element - for example paragraphs, headings, lists or links.

Objects

Objects can range from something as simple as a wrapper element, to layout systems.

They may be used in any number of unrelated contexts to the one you can currently see it in. This means that making modifications to these types of class could potentially have knock-on effects in other places.

Components

Discrete pieces of UI. In most cases these will map to the components in the Design System.

Utilities

Utility classes – for example clearing floats, visually hiding content.

Overrides

Classes that map to a specific property – for example margin or font weight - and override all other layers. Rules in this layer will generally be marked as !important.

Class names within this layer use an additional prefix -!-, for example .govuk-!-w-regular.

Consequences

The paths to import the project are changed, this has been detailed in the release notes for GOV.UK Frontend.