Components

Components are a great way to help structure code and share between prototypes.

With the prototype kit, this can include Javascript, Sass, macros and layouts.

One of the benefits of doing this is setting what a component does, and more importantly, doesn’t.

Before the GOV.UK Design system there was GOV.UK Elements which didn’t provide components.

This led to a couple of examples of components in nunjucks and marko to help make development easier.

Now with the ability to create plugins we can share versions of components that are in an early stage of development.

Even within a prototype, it can be useful to build components, to keep your design consistent.

For this lets use the big number component from the publishing guide.

Breakdown

We’ll need to do the following steps for a component:

Macro
Styles
Plugin configuration

Macro

Our macro doesn’t have to replicate the whole of the big number ruby gem but we can use it as a base of what we want it to do.

If we look at the versions listed on the docs we can see that we have a that we have versions with number, labels and a link.

We also have the ability to add aria, attributes and margins.

A couple of things before we start

We should pre-fix our component with something, this helps keep it in our namespace compared with govuk.
Instead of passing variables directly we’ve followed govuk and passed in a params object, this can help with larger macros as a flat structure can be diffcult to read.

{% macro exampleBigNumber( params ) %}
    <div class="gem-c-big-number">
        {# make things happen #}
    </div>
{% endmacro %}

We can now take our parameters to:

Add an optional url
Add a number
Add an optional label

This will generate most of the examples listed on the docs website.

{% macro exampleBigNumber( params ) %}
<div class="gem-c-big-number">
    {% if params.href %}
    <a class="govuk-link gem-c-big-number__link" href="{{ params.href }}">
    {% endif %}
        <span class="gem-c-big-number__value">
            {{ params.number }}
        </span>
        {% if params.label %}
        <span class="govuk-visually-hidden">&nbsp;</span>
        <span class="gem-c-big-number__label">
            {{ params.label }}
        </span>
        {% endif %}
    {% if params.href %}
    </a>
    {% endif %}
</div>
{% endmacro %}

We can now use this in a view and generate some examples

{% from "./components/big-number.njk" import exampleBigNumber %}

{{
    exampleBigNumber(
        {
            number: 119,
            label: "Open consultations"
        }
    )
}}

{{
    exampleBigNumber(
        {
            number: 23,
            label: "Ministerial departments",
            href: "/a-link-to-something"
        }
    )
}}

{{
    exampleBigNumber(
        {
            number: "-20",
            label: "is a negative number"
        }
    )
}}

Styles

Since this is a component we can lift the styles from the publisher github

If you look at the code example a lot of this uses govuk frontend Sass API reference.

.gem-c-big-number {
    margin-bottom: govuk-spacing(3);
    @include govuk-text-colour;
  }

  .gem-c-big-number__value {
    line-height: 1;
    font-size: 80px;
    font-size: govuk-px-to-rem(80px);
    @include govuk-font($size: false, $weight: bold);
  }

  .gem-c-big-number__label {
    @include govuk-font($size: 19, $weight: bold);

    // This pseudo element is to bypass an issue with NVDA where block level elements are dictated separately.
    // What's happening here is that the label and the number technically have an inline relationship
    // but appear to have a block relationship thanks to this element
    &::before {
      content: "";
      display: block;
    }
  }

  .gem-c-big-number__link {
    display: inline-block;
    text-decoration: none;

    // Add govuk-link hover decoration to main value if no label present but a href attribute is
    .gem-c-big-number__value--decorated {
      @include govuk-link-decoration;
      @include govuk-link-style-no-underline;
    }

    .gem-c-big-number__label {
      @include govuk-link-decoration;
    }

    &:hover,
    &:active {
      .gem-c-big-number__label,
      .gem-c-big-number__value--decorated {
        @include govuk-link-hover-decoration;
      }
    }

    &:focus,
    &:focus:hover {
      .gem-c-big-number__label,
      .gem-c-big-number__value--decorated {
        text-decoration: none;
      }
    }
  }

  .gem-c-big-number__suffix {
    vertical-align: middle;
  }

Once the file is created we can include this in our /app/sass/application.sass

//
// For guidance on how to add CSS and SCSS see:
// https://prototype-kit.service.gov.uk/docs/adding-css-javascript-and-images
//

// Add extra styles here

@import "components/big-number";

Plugin configuration

Based on our sass file and component we can add the ability to install these into another prototype from github.

The prototype-demo-component has an example of cards using the same method.

{
    "sass": [
      "/app/assets/sass/components/_big-number.scss"
    ],
    "nunjucksPaths": [
        "/app/views"
    ],
    "nunjucksMacros": [
        {
          "macroName": "exampleBigNumber",
          "importFrom": "/components/big-number.njk"
        }
    ]
}

Exercises

Add the ability to add a class to our example component
Based on that class create a new “important” version.
Spend some time going through your protoype looking for where you are repeating code From Pages to Patterns: An Exercise for Everyone is a great process for this
Make a macro of this
Build out some templates on a single page