mp-design-system 1.2.64 → 1.2.65

package/src/components/colour.njk

@@ -1,327 +0,0 @@
----
-title: Color
-layout: system-page
-sidebar: components
----
-
-{% from "components/alert/macro.njk" import alert %}
-{% from "components/prose/macro.njk" import prose, markdown %}
-
-{% set content %}
-The color palette is based on the existing brand colors, tweaked to increase vibrance and clarity in digital applications. Color contrast ratios should be checked with a tool like the [webAIM contrast checker](https://webaim.org/resources/contrastchecker/) to ensure all text meets WCAG AA requirements.
-
-A limited set of color tints and shades are available for element backgrounds, borders, icons, etc. These can also be used to increase contrast where appropriate, for example darkening a blue text link which appears on a light blue background.
-{% endset %}
-
-<div class="u-flow--l">
-  {{ alert({
-    content: "<p>This page explains how to use color on the web. For print or other uses, see the <a href='/brand/colors'>Brand ➝ colors</a> page.</p>",
-    type: "info"
-  })}}
-
-  {{ markdown({
-    content: content
-  }) }}
-
-  {% set colors = [
-    {
-        name: 'MP Petrol',
-        key: 'Petrol',
-        steps: [
-            {
-                name: "-1",
-                hex: '003039',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 0,
-                hex: '005461',
-                cmyk: '93/54/49/27',
-                pantone: '3165'
-            },
-            {
-                name: 1,
-                hex: '3d7b87',
-                cmyk: '',
-                pantone: ''
-            },                
-            {
-                name: 2,
-                hex: 'bfd3d6',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 3,
-                hex: 'ebf1f2',
-                cmyk: '',
-                pantone: ''
-            }
-        ]
-    },
-    {
-        name: 'MP Blue',
-        key: 'Blue',
-        steps: [
-            {
-                name: "-1",
-                hex: '00758c',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 0,
-                hex: '00a2c2',
-                cmyk: '77/17/17/0',
-                pantone: '7460'
-            },
-            {
-                name: 1,
-                hex: '47bcd3',
-                cmyk: '',
-                pantone: ''
-            },                
-            {
-                name: 2,
-                hex: 'c2e9f0',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 3,
-                hex: 'ebf8fa',
-                cmyk: '',
-                pantone: ''
-            }
-        ]
-    },
-    {
-        name: 'MP Green',
-        key: 'Green',
-        steps: [
-            {
-                name: "-1",
-                hex: '0e7a0e',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 0,    
-                hex: '13aa13',
-                cmyk: '81/4/100/0',
-                pantone: '2423'
-            },
-            {
-                name: 1,
-                hex: '55c255',
-                cmyk: '',
-                pantone: ''
-            },                
-            {
-                name: 2,
-                hex: 'c6ebc6',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 3,
-                hex: 'ecf8ec',
-                cmyk: '',
-                pantone: ''
-            }
-        ]
-    },
-    {
-        name: 'MP Rubine',
-        key: 'Red',
-        steps: [
-            {
-                name: "-1",
-                hex: '94003f',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 0,    
-                hex: 'ce0058',
-                cmyk: '14/100/50/2',
-                pantone: 'Rubine Red'
-            },
-            {
-                name: 1,
-                hex: 'dc4787',
-                cmyk: '',
-                pantone: ''
-            },                
-            {
-                name: 2,
-                hex: 'f3c2d7',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 3,
-                hex: 'fbebf2',
-                cmyk: '',
-                pantone: ''
-            }
-        ]
-    },
-    {
-        name: 'MP Charcoal',
-        key: 'Grey',
-        steps: [
-            
-            {
-                name: "-1",
-                hex: '252525',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 0,    
-                hex: '333333',
-                cmyk: '0/0/0/95',
-                pantone: '447'
-            },
-            {
-                name: 1,
-                hex: '6c6c6c',
-                cmyk: '',
-                pantone: ''
-            },                
-            {
-                name: 2,
-                hex: 'cecece',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 3,
-                hex: 'efefef',
-                cmyk: '',
-                pantone: ''
-            }
-        ]
-    },
-    {
-        name: 'MP Utility Blue',
-        key: 'Utility blue',
-        steps: [
-            {
-                name: "-1",
-                hex: '004f7e',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 0,    
-                hex: '006daf',
-                cmyk: '90/55/5/0',
-                pantone: '3553'
-            },
-            {
-                name: 1,
-                hex: '4796c5',
-                cmyk: '',
-                pantone: ''
-            },                
-            {
-                name: 2,
-                hex: 'c2dcec',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 3,
-                hex: 'ebf3f9',
-                cmyk: '',
-                pantone: ''
-            }
-        ]
-    },
-    {
-        name: 'MP Utility Gold',
-        key: 'Utility orange',
-        steps: [
-            {
-                name: "-1",
-                hex: 'ae7809',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 0,    
-                hex: 'f2a60d',
-                cmyk: '4/38/100/0',
-                pantone: '130'
-            },
-            {
-                name: 1,
-                hex: 'f6bf51',
-                cmyk: '',
-                pantone: ''
-            },                
-            {
-                name: 2,
-                hex: 'fceac5',
-                cmyk: '',
-                pantone: ''
-            },
-            {
-                name: 3,
-                hex: 'fef8ec',
-                cmyk: '',
-                pantone: ''
-            }
-        ]
-    }
-] %}
-
-<div class="u-flow--2xs">
-    {% for color in colors %}
-        <h3 class="c-h c-h--step-1">{{ color.name }}</h3>
-        <div class="c-library__swatch-grid">
-            {% for step in color.steps %}
-                {% set classname %}
-                    {{- 'c-library__swatch'}}{# Let's build a string #}
-                    {{ 'u-bg-'+color.key | slug}}{# Set the background color to color.key -#}
-                    {{ '-step-'+step.name if step.name!=0 }} {# If it's not step zero, add the -step-x suffix -#}
-                    {# Set the text color to white, or a dark color #}
-                    {{ 'u-'+color.key|slug+'-step--1' if (step.name==2) or (step.name==3) else 'u-white' -}}
-                {% endset %}
-                <div class="{{classname}}">
-                    <span>Step {{step.name}}</span>
-                </div>
-            {% endfor %}
-        </div>
-    {% endfor%}
-</div>
-
-{% set content %}
-### SCSS function
-
-Color can be applied via a `SCSS` function. The `color()` function takes two arguments, one for the **color** and one for the **shade/tint**. Like typography, this uses the 'step' syntax to lighten/darken the base color (step 0). For example:
-
-```scss
-.c-component {
-  background: color('petrol', 'step-3');
-  color: color('blue');
-}
-```
-
-### Utility classes
-
-You can also use utility classes to apply color, with one set for the `color` property, and another for `background-color`:
-
-```html
-<p class="u-blue">Blue text</p>
-<div class="u-bg-petrol-step-3">Petrol step 3 background</p>
-```
-{% endset %}
-
-{{ markdown({
-  content: content
-}) }}
-</div>

package/src/components/creating-a-component.md

@@ -1,163 +0,0 @@
----
-title: Creating a component
-layout: content-page
-sidebar: components
----
-
-Once you've [established a new pattern is required](/components), it's time to create a new component. For the purpose of this tutorial, let's assume the component is called **Filter Bar**.
-
-First of all, create a directory to house the component: `src/_includes/components/filter-bar`
-
-{% alert %}
-**Note**, use kebab-case for directory & file names.
-{% endalert %}
-
-Next up, a few files will need to be created in that new folder:
-
-- `filter-bar.njk` - The component code
-- `macro.njk` - The wrapper around the component
-- `filter-bar.scss` - _Optional:_ For styling the component
-- `filter-bar.config.js` - _Optional:_ For rendering the component in {{ config.name }}
-- `filter-bar.md` - _Optional:_ For documenting the component
-
-## `filter-bar.njk`
-
-Variables passed to this file can be accessed via the `params` variable. Other than that, this is a totally encapsulated file, with no access to global variables. Here's a very basic component that outputs the title parameter:
-
-```html
-<div class="mp c-filter-bar">
-  <h2 class="c-h c-h--step-2">{% brace %} params.title {% endbrace %}</h2>
-</div>
-```
-
-You can also include other components inside this one. You can import it via the other component's macro, then call it like a function:
-
-```html
-{% brace 'silent' %} from "components/icon/macro.njk" import icon {% endbrace %}
-
-<div class="mp c-filter-bar">
-  <h2 class="c-h c-h--step-2">{% brace %} params.title {% endbrace %}</h2>
-  {% brace %} icon({
-    id: 'twitter'
-  }) {% endbrace %}
-</div>
-```
-
-These components aren't being included directly into application code, but **will be used for reference**, so think through the component composition and create sensible logic that can be recreated in Razor, DXA, PHP and any other language this is converted to. [Read more about Nunjuck templating](https://mozilla.github.io/nunjucks/templating.html).
-
-### `macro.njk`
-
-Every component has a corresponding macro file, allowing us to instantiate a component in a totally encapsulated area. The macro itself uses another `.njk` file to render the component, allowing us to render the component in the same way within {{ config.name }}.
-
-```html
-{% brace 'silent' %} from "components/component/component.njk" import c {% endbrace %}
-
-{% brace 'silent' %} macro filterBar(params) {% endbrace %}
-  {% brace %} c({ name: 'filter-bar' }, params) {% endbrace %}
-{% brace 'silent' %} endmacro {% endbrace %}
-```
-
-{% alert %}
-**Note**, use camelCase for the macro name.
-{% endalert %}
-
-This `c` component takes two parameters:
-
-1. Component object with three parameters
-    1. `name`: a string matching the `.njk` file name
-    2. `folder`: _Optional:_ by default, the same as the `name`
-    3. `root`: _Optional:_ by default, `../`, effectively the `src/_includes/components` directory
-2. The `params` object, passed in from the macros own parameters
-
-### `filter-bar.scss`
-
-This `SCSS` file has access to all the mixins, functions and foundational elements documented in {{ config.name }}. To add it to the main bundle, head to `src/assets/scss/components/index.scss` and add a new line pointing to your file:
-
-```scss
-@import '~comp/filter-bar/filter-bar.scss';
-```
-
-{% alert %}
-**Note**, `~comp` is a shorthand to the `src/_includes/components` directory.
-{% endalert %}
-
-### `filter-bar.config.js`
-
-This file drives the component rendering for {{ config.name }}. It takes cues from [Fractal](https://fractal.build/) and [Storybook](https://storybook.js.org/), and is effectively a big object that tells {{ config.name }} how to render the component, and what data to render it with. Let's run through the minimum viable config file:
-
-```js
-module.exports = {
-  title: 'Filter bar',
-  component: {
-    name: 'filter-bar',
-  },
-  context: {
-    title: 'Filter bar title'
-  }
-}
-```
-
-There are three mandatory sections:
-
-1. `title`: the name of component
-2. `component`: the same object we passed into the `c()` component, controling `name`, `folder`, and `root`
-3. `context`: the data used to render the component
-
-If this is all correct, you should see 'Filter bar' in the components section of the {{ config.name }} sidebar.
-
-#### Additional parameters
-
-- `preview`: Which 'preview' file should the component use to render. These live in `src/_includes/components/component` and allow you to test a component in a grid, with a different colour background, or in a totally different setting. To render your component with a new preview:
-    - Create the `preview-[PREVIEW NAME].njk` file
-    - Add any wrapping markup
-    - Insert: `{% brace %} comp | safe {% endbrace %}` wherever you wish to output the component
-    - Add `preview: '[PREVIEW NAME]'` to your original component
-- `docs`: Does this component have a documentation markdown file (more on this later)? 
-- `figma`: A link to the originally designed component within Figma
-- `status`: A string representation of how 'complete' the component is. This is 'slugified' and can be styled according to the name
-- `version`: A numeric value that can be increased every time you change the component
-- `category`: Components can be grouped in the {{ config.name }} sidebar. Categories are stored globally. To reference a category:
-    1. Require the categories file in `filter-bar.config.js`: 
-    ```js
-    const categories = require('../component/categories');
-    ```
-    2. If you need a new category, create a new key/value pair in the above file
-    3. Add the `category` parameter: `category: categories.card`
-- `props`: an array of prop tables, allowing you to document the inputs and outputs of the component:
-
-```js
-{
-  props: [
-    {
-      title: 'Table title', // optional, defaults to 'Props'
-      table: [
-        ['Parameter name', 'Parameter type', 'Parameter description']
-      ]
-    }
-  ]
-}
-```
-
-- `variants`: Variants are used to render the same component with different data, allowing you to test the parameters thoroughly, as well as test for extreme amounts of content and edge-cases. In {{ config.name }}, the variant objects are written like components within components. You must pass in a new `title` and a `context` object. {{ config.name }} will then merge the original component data with this new variant object to create a rendering context. This means you only have to pass the **differences** between the components, not every piece of context. It also means you can supply a different `preview` element, allowing you to test the same component in different scenarios.
-
-```js
-{
-  variants: [
-    {
-      title: 'With long title',
-      context: {
-        title: 'Cras mattis consectetur purus sit amet fermentum. Etiam porta sem malesuada magna mollis euismod.'
-      }
-    },
-    {
-      title: 'In a grid',
-      preview: 'cards-three',
-      context: {}
-    }
-  ]
-}
-```
-
-### `filter-bar.md`
-
-Finally, you can create a Markdown file for a component. This is a space for you to write about the component in whatever way you deem helpful. This could be research insights, documentation of internal decisions, a changelog - it's up to you. This renders using the `prose()` component, so any styling from {{ config.name }} will be included here.

package/src/components/css.md

@@ -1,65 +0,0 @@
----
-title: CSS Approach
-layout: content-page
-sidebar: components
----
-
-The CSS approach for {{ config.name }} is based around [ITCSS](https://www.creativebloq.com/web-design/manage-large-scale-web-projects-new-css-architecture-itcss-41514731) + [BEM](http://getbem.com/), two methodologies designed to help scale CSS on large projects.
-
-![ITCSS diagram](/static/img/itcss.svg)
-
-## ITCSS
-
-ITCSS separates the CSS into layers, ranging from the most generic & wide-reaching (settings) to the highest specificity (utilities). Components and Utilities are the most commonly used sections of the inverted triangle. Note, we tend not to use the 'generic' layer.
-
-### Settings
-Foundations for typography, space, colour, shadows, font stacks. In SCSS, this area produces no CSS, in PostCSS this adds variables to the `:root` element.
-
-### Tools
-SCSS mixins & functions - no 'CSS' actually generated.
-
-### Elements
-Code that targets HTML elements directly. The reset lives here, `<body>` styling, sensible `input` styles too. Anything that has 'global', but low specificity implications.
-
-### Objects
-Any parent elements that wrap around child components/elements and provide opinionated styling lives here. Wrapper, Grid, Prose all fall into this camp. Objects are prefixed with `o-`.
-
-### Components
-Most of the CSS lives in this group. Each component is an encapsulated 'block' (more on that later) that styles within. Components **should not** leak padding or margin, nor control their width or height; this should be controlled by the objects above. They use the `c-` prefix.
-
-### Utilities
-Utilities are classes that do one thing really well. For example: `.u-hidden` hides elements on the page in a non destructive way (still visible to screenreaders). There are auto-generated spacing, typography and colour classes to help compose a page (and prototype new components before refactoring them into the above groups). The `u-` prefix is used for utilities.
-
-## BEM
-We use BEM as a naming methodology, with `__` used for elements, and `--` used for modifiers.
-
-```scss
-/* Pattern */
-.Block {
-  &__element {}
-  &--modifier {}
-}
-
-/* Usage */
-.c-tag {
-  background: color('petrol');
-  color: color('petrol', 'step-3');
-
-  &__title {
-    font-weight: weight('bold');
-  }
-
-  &--inverted {
-    background: color('petrol', 'step-3');
-    color: color('petrol');
-  }
-}
-```
-
-For more information about BEM see [getbem.com](http://getbem.com/)
-
-### SCSS variables vs. CSS custom properties
-
-{{ config.name }} is designed to support IE11+, which leaves a large support gap for custom properties—sadly, polyfilling is patchy at best. For this reason, the design system relies more on SCSS variables than custom properties.
-
-However, the fluid typographic and space system does require runtime variables. For this reason, there are a number of powerful mixins in play, that provide solid fallbacks to older browsers, whilst still letting new browsers use custom properties.

package/src/components/flow.njk

@@ -1,131 +0,0 @@
----
-title: Flow
-layout: system-page
-sidebar: components
----
-
-{% from "components/prose/macro.njk" import markdown %}
-{% from "components/alert/macro.njk" import alert %}
-
-<div class="u-flow--m">
-  {% set content %}
-  Add the class `u-flow` to any container, to space its contents.
-  ```html
-  <div class="u-flow">
-    <h1>Flow</h1>
-    <p>Example</p>
-    <img src="example.jpg" />
-    <div>Example</div>
-  </div>
-  ```
-
-  Spacing content effectively is imperative to good component composition. Taking learnings from broader CSS spacing paradigms, rather than dictate spacing at a child-level, we set the rules at a parent-level, overriding at a child-level where appropriate.
-
-  With this approach, we can add any number of new children to a parent without breaking this existing variants. This mindset is crucial to extending the design system over time.
-
-  To achieve this, we use the **flow** concept. The [lobotomised owl selector](https://alistapart.com/article/axiomatic-css-and-lobotomized-owls/) `* + *` does the heavy lifting here. Rather than every element 'pushing down', any children that follow another child 'push up'.
-  
-  {% set dont %}
-  ```scss
-  .parent > * {
-    margin-bottom: 1rem;
-
-    &:last-child {
-      margin-bottom: 0;
-    }
-  }
-  ```
-  {% endset %}
-  {{ alert({
-    content: dont,
-    type: 'error'
-  }) }}
-
-  {% set do %}
-  ```scss
-  .parent > * + * {
-    margin-top: 1rem;
-  }
-  ```
-  {% endset %}
-  {{ alert({
-    content: do,
-    type: 'success'
-  }) }}
-
-  This also means we don't have to reset the last child and remove unnecessary space.
-
-  ## Utility classes
-
-  Instead of writing the above for every component, utility classes have been created to handle this consistently. These inherit from the [Space](/components/space) system underpinning the design, and use the same 't-shirt sizing' concept.
-  
-  `.u-flow` will produce a 'small' space, and `.u-flow--l` a 'large' one.
-
-  {% set dont %}
-  ```html
-  <div class="c-component">
-    <h2 class="c-component__title u-margin-top-m">...</h2>
-  </div>
-  ```
-  {% endset %}
-  {{ alert({
-    content: dont,
-    type: 'error'
-  }) }}
-
-  {% set do %}
-  ```html
-  <div class="c-component u-flow--m">
-    <h2 class="c-component__title">...</h2>
-  </div>
-  ```
-  {% endset %}
-
-  {{ alert({
-    content: do,
-    type: 'success'
-  }) }}
-
-  ## SCSS Mixin
-
-  It's also possible to apply the flow concept to a component's SCSS via the mixin: `flow($size)`.
-
-  #### Source → Compiled
-
-  <table class="c-table">
-    <thead>
-      <tr>
-        <th>Source</th>
-        <th>Compiled</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr>
-        <td>
-
-  ```scss
-  .c-component {
-    @include flow('l');
-  }
-  ```
-
-</td>
-<td>
-
-  ```scss
-  .c-component > * + * {
-    margin-top: 36px;
-    margin-top: var(--space-l);
-  }
-  ```
-
-</td>
-</tr>
-</tbody>
-</table>
-  {% endset %}
-  {{ markdown({
-    content: content
-  }) }}
-</div>
-