govuk-frontend-versioning.md

govuk-frontend-versioning.md

GOV.UK Frontend - How we version

Prior art

• Variable exposing mixin proposal

The public API: or what you can depend on

Note: If you want to use anything that is not listed here to extend or create your own components please contact us and we might be able to make something public that you can depend on. If you depend on something that is not listed here, it can and will likely be broken without warning.

Exposed from Design System main site and GOV.UK Frontend development review application.

• Globals
  • HTML
• Components
  • HTML
  • Nunjucks Macro
    • Macro name
    • Parameters

Exposed from https://www.npmjs.com/package/@govuk-frontend/all

• Icons
• Globals
  • Settings
    • ❓ What should people override in here?
    • ❓ How do people theme GOV.UK Frontend?
    • Colours (sass variables)
    • Measurements (sass variables)
    • Media-queries (sass variables)
    • Paths (sass variables)
    • Spacing (sass variables)
    • Typography (sass variables)
  • Tools
    • Exports (sass mixin)
    • File url (sass mixin)
    • Iff (sass mixin)
    • Legacy ie (sass variable + mixin)
    • px to em (sass variable + mixin)
      • ❌ Remove?
  • Helpers
    • Arrow (sass mixin)
    • Clearfix (sass mixin)
    • Device pixels (sass mixin)
    • Media queries (sass mixin)
    • Spacing (sass mixin)
    • Typography (sass mixin)
    • Visually hidden (sass mixin)
  • Core
    • Links
    • Lists
      • ❓ Issues with specificity
    • Prose scope
    • Typography
  • Objects
    • Grid
    • Main wrapper
    • Shapes
      • ❌ Remove? Move into component, since only used in one place?
    • Width container
  • Overrides
    • Spacing
    • Typography
    • Width
• Components
  • SCSS
    • 🔒 private, do not edit?
  • Nunjucks Macro
    • See Design System comments
  • Nunjucks Template:
    • 🔒 private? use macro interface instead
  • Documentation.yml:
    • 🔒 private?
    • ❓ should we publish this?
  • tests:
    • 🔒 private?
    • ❓ should we publish this?
  • Example.html:
    • ❌ Remove?
  • Example.njk:
    • ❌ Remove?

How we version this public api, breaking changes etc

Morningstar Design System's documentation is a good basis.

• Morning star versioning documentation

Macros

Version on the lowest abstraction

What happens if we make a breaking change that would not be breaking to users of our macros? We should version as if users are using HTML, but make it clear in the changelog that macro users may not have difficulty updating.

Additions needed:

• Macros
• JavaScript (when we figure JS out)
• How to avoid breaking changes
• How to deprecate and communicate changes to allow for people to migrate away from an old syntax.

Questions:

• Is the format the easiest to action?
• Is this only for the internal dev team?
• Does this need to be extended to what is in the design system?

How do I create my own themed version of GOV.UK Frontend while allowing for updates?

Guidance around how to make your own GOV.UK Frontend build and what globals you can change.

How do I extend or fork the public api while allowing for updates?

Note: Example guidance, would need proper thought before recommending anything.

Extending component source files always has some form of risk, there are a few ways you can do this, each with different levels of risk.

Do not:

• override existing CSS classes, this will make it difficult to upgrade in the future.

Do:

• Small changes: Use a modifier class (http://getbem.com/naming/)
  • Note: If your modifier class impacts layout [link], or colour then it may be hard to upgrade, consider forking.
• Big changes: Fork a component into a new component

Examples Updating the button to work on a dark background. Note we're using an 'app' namespace, learn about namespacing here: [link]

Do not:

...
.service-page button {
  background: white;
  color: black;
}
...

Do:

...
.app-c-button--inverse {
  background: white;
  color: black;
}
...

  <button class="govuk-c-button app-c-button--inverse">
    Continue
  </button>