More documentation (#15)

* Update release workflow

* Update documentation

* Update CHANGELOG.md

.github/workflows/npm-publish.yml

@@ -11,12 +11,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - name: Check version numbers
+      - name: Get version number
+        id: get-version
         run: |
           VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,')
           # Strip "v" prefix from tag name
           [[ "${{ github.ref }}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')
-          ./tasks/validate-version.sh $VERSION
+          echo "VERSION=$VERSION" >> "$GITHUB_OUTPUT"
+      - name: Check version number
+        run: ./tasks/validate-version.sh $VERSION
+    outputs:
+      version: ${{ steps.get-version.outputs.VERSION }}
 
   lint:
     runs-on: ubuntu-latest
@@ -67,6 +72,7 @@ jobs:
     name: Build package and publish to npm
     runs-on: ubuntu-latest
     needs:
+      - check
       - lint
       - tests
       - test-build
@@ -88,14 +94,19 @@ jobs:
         run: npm whoami
       - name: Publish to npm
         run: cd package && npm publish
+      - name: Rename package directory
+        run: mv package "nationalarhives-frontend-${{ needs.check.outputs.version }}"
+      - name: Upload the package to the GitHub release
+        run: gh release upload "v${{ needs.check.outputs.version }}" "nationalarhives-frontend-${{ needs.check.outputs.version }}"
 
-  # notify-slack:
-  #   runs-on: ubuntu-latest
-  #   needs:
-  #     - publish-npm
-  #   steps:
-  #   - uses: actions/checkout@v3
-  #   - uses: rtCamp/action-slack-notify@v2
-  #     env:
-  #       SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
-  #       SLACK_TITLE: "A deployment to ${{ github.head_ref || github.ref_name }} is imminent"
+  notify-slack:
+    runs-on: ubuntu-latest
+    needs:
+      - check
+      - publish-npm
+    steps:
+    - uses: rtCamp/action-slack-notify@v2
+      env:
+        SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
+        SLACK_ICON: "https://raw.githubusercontent.com/nationalarchives/tna-frontend/main/src/nationalarchives/assets/images/apple-touch-icon.png"
+        SLACK_TITLE: "v${{ needs.check.outputs.version }} of `tna-frontend` has just been published"

CHANGELOG.md

@@ -49,6 +49,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `/nationalarchives/_prototype-kit.scss` is now the entrypoint for the GOV.UK prototype kit SASS which fixes the asset location
 - The cookie banner confirmation message is no longer outlined when highlighted
 - The import routes of the layouts for use in the prototype kit now work
+- Cookie banner header classes added
 
 ### Security
 

README.md

@@ -1,4 +1,4 @@
-<img src="./src/nationalarchives/assets/images/tna-horizontal-logo-inverted.svg" alt="The National Archives logo" title="The National Archives" width="120" />
+<img src="./src/nationalarchives/assets/images/tna-square-logo.svg" alt="The National Archives logo" title="The National Archives" width="100" />
 
 # National Archives Frontend
 

src/nationalarchives/components/cookie-banner/template.njk

@@ -4,7 +4,7 @@
 <div class="tna-cookie-banner {{ containerClasses | join(' ') }}" role="region" aria-label="Cookie usage" data-module="tna-cookie-banner" data-policies="{{ params.policies if params.policies else 'usage,settings' }}" data-preferenceskey="{{ params.cookiesPreferencesSetKey if params.cookiesPreferencesSetKey else 'cookies_preferences_set' }}"{% if params.loadScriptsOnAccept %} data-acceptscripts="{{ params.loadScriptsOnAccept }}"{% endif %}{%- for attribute, value in params.attributes %} {{ attribute }}="{{ value }}"{% endfor %} hidden>
   <div class="tna-container">
     <div class="tna-column tna-column--full tna-cookie-banner__message tna-cookie-banner__message--prompt">
-      <h2>This website uses cookies</h2>
+      <h2 class="tna-heading tna-heading--m">This website uses cookies</h2>
       <p>We use some essential cookies to make this service work.</p>
       <p>We'd also like to use analytics cookies so we can understand how you use the service and make improvements.</p>
       <div class="tna-button-group">

src/nationalarchives/stories/development/contributing.mdx

@@ -30,13 +30,3 @@ import { Meta } from "@storybook/blocks";
 1. Import and initialise your component as part of the `initAll` function in `src/nationalarchives/all.mjs`
 1. Update the check in `tasks/test-package.js` to add the JavaScript class to check for
 1. If your component uses JavaScript, ensure you add interaction tests using `@storybook/testing-library`
-
-### Best practices
-
-- [HTML standards](https://nationalarchives.github.io/developer-handbook/technology/html/)
-- [JavaScript standards](https://nationalarchives.github.io/developer-handbook/technology/javascript/)
-- [CSS standards](https://nationalarchives.github.io/developer-handbook/technology/css/)
-
-## Updating a component
-
-[TODO]

src/nationalarchives/stories/development/structure.mdx

@@ -0,0 +1,88 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Development/Structure" />
+
+# Structure
+
+The layers of the TNA frontend SCSS library is built as:
+
+1. [Variables](#variables)
+1. [Tools](#tools)
+1. [Libraries](#libraries)/[Utilities](#utilities)
+1. [Components](#components)
+1. [Overrides](#overrides)
+
+## Variables
+
+TNA frontend variables are defined in `src/nationalarchives/variables`.
+
+Lots of variables can be modified but some are fixed, such as our brand colours.
+
+An example fixed variable is `$relative-1rem-px` where we set the value of `1rem` to `16px` which makes it easier to define widths as a function of `1rem` as we mostly work on a 4px grid:
+
+| Pixels | REM         |
+| ------ | ----------- |
+| `1px`  | `0.0625rem` |
+| `2px`  | `0.125rem`  |
+| `4px`  | `0.25rem`   |
+| `8px`  | `0.5rem`    |
+| `16px` | `1rem`      |
+| `32px` | `2rem`      |
+| `64px` | `4rem`      |
+
+An example of a variable that can be modified is `$body-font-size-px` which we set to `18px` by default. This font size might not be right for all services so we have allowed it to be modified.
+
+## Tools
+
+The tools provided are reusable `@mixin` and `@function` blocks to make writing styles easier. They are defined in `src/nationalarchives/tools`.
+
+Tools rely directly on variables and can be used throughout the frontend library.
+
+As an exmaple, `colour-font()` will apply a font colour in a way that should work for all browsers and takes into consideration the light/dark theme used.
+
+## Libraries
+
+The libraries in `src/nationalarchives/lib` are a mix of third party libraries as well as some TNA ones.
+
+They can join up tools to make larger, more useful elements.
+
+## Utilities
+
+The utilities in `src/nationalarchives/utilities` are some global styles that aren't associated with a specific component.
+
+This layer is where we define some general purpose elements such as:
+
+- The `tna-template` and `tna-template__body` elements
+- Headings
+- Lists
+- Chips
+- `<p>` elements
+- General media elements like `<img>`, `<svg>`, `<picture>`, `<video>` and `<canvas>`
+- Columns
+- General form elements
+
+These elements all still adhere to the [BEM methodology](https://getbem.com/).
+
+Utilities should not implement any `!important` rules.
+
+## Components
+
+The most prominent layer of styling, the components in `src/nationalarchives/components` should use the tools already defined.
+
+Components shouldn't use variables directly. They shouldn't use static values for colour unless the colour of that component will never change, for example the message component which is always yellow.
+
+Some components may use utilities such as headings. Where these styles have already been defined, they should not be redefined. The heading in a cookie banner should use the existing `tna-heading` and `tna-heading--m` styles that already exist rather than implimenting its own.
+
+Components should not implement any `!important` rules. There are exceptions such as the skip link that needs to be visually hidden in a way that it is still available for someone navigating a site with a keyboard.
+
+Components should not care about the context or layout within which they are used. As an example, a breadcrumb *could* be placed within a card or a footer element although in reality we wouldn't allow this.
+
+## Overrides
+
+Overrides start with `tna-!--` and can only be used in HTML classes. They have `!important` rules.
+
+Examples of overrides are:
+
+- Spacing (margin, padding etc.)
+- No focus style (`.tna-!--no-focus-style`) for items such as the target element of a skip link
+- Visibly hidden content (used to add extra descriptions which appear for screenreaders only)

src/nationalarchives/stories/development/using/compiled.mdx

@@ -0,0 +1,9 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Development/Using/Compiled" />
+
+# Using the compiled files
+
+Each release (as of `v0.1.21-prerelease`) should contain a ZIP of the package.
+
+Find the release you want on the `tna-frontend` [releases page](https://github.com/nationalarchives/tna-frontend/releases) and download the package from the "Assets" dropdown.

src/nationalarchives/stories/development/using/hosted.mdx

@@ -0,0 +1,53 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Development/Using/Hosted" />
+
+# Using with a hosted solution
+
+The `@nationalarchives/frontend` package is available on [jsdelivr.com](https://www.jsdelivr.com/package/npm/@nationalarchives/frontend).
+
+While you can use the CSS and JavaScript from there, the font files which includes the icon font will have to be hosted from your web application.
+
+As a result, **using a hosted solution is not the preferred method for using the `tna-frontend` library**.
+
+## All components and styles
+
+Include the CSS in the `<head>` element of your page:
+
+```html
+<link href="https://cdn.jsdelivr.net/npm/@nationalarchives/[email protected]/nationalarchives/all.css" rel="stylesheet" integrity="sha384-6Egfw6aX1Jrwuf+APn+BMPswroudkIQ6StU095OPkNCKLEzj7ksWGmYxjend8P7g" crossorigin="anonymous">
+```
+
+### JavaScript
+
+Add the JavaScript to the end of your page just before your closing `</body>` tag:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@nationalarchives/[email protected]/nationalarchives/all.js" integrity="sha384-sBkiMlxl9svXopGxNSMVAdALjzyvh6sQHp+21PE3LGfTxAEbG4EIpK" crossorigin="anonymous"></script>
+<script>
+  // Initialise all TNA components
+  window.TNAFrontend.initAll();
+</script>
+```
+
+...or use the module syntax:
+
+```
+<script type="module">
+  import { initAll } from "https://cdn.jsdelivr.net/npm/@nationalarchives/[email protected]/nationalarchives/all.js";
+  initAll();
+</script>
+```
+
+## Specific components
+
+```html
+<link href="https://cdn.jsdelivr.net/npm/@nationalarchives/[email protected]/nationalarchives/components/tabs.css" rel="stylesheet" integrity="sha384-hkx4svJn1A7pWYlzaDRMmtIBBijZdEop+M1Y/H4Hdg8aAqZRJHG56RokLk/eqJYl" crossorigin="anonymous">
+```
+
+### JavaScript
+
+```html
+<!-- JavaScript for a single component -->
+<script src="https://cdn.jsdelivr.net/npm/@nationalarchives/[email protected]/nationalarchives/components/tabs.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
+```

src/nationalarchives/stories/development/using.mdx → src/nationalarchives/stories/development/using/npm.mdx

@@ -1,18 +1,16 @@
 import { Meta } from "@storybook/blocks";
 
-<Meta title="Development/Using" />
+<Meta title="Development/Using/NPM" />
 
-# Using the styles
-
-## NPM
+# Using with npm
 
 Install the frontend package from NPM with:
 
 ```sh
 npm install @nationalarchives/frontend
 ```
 
-### CSS
+## CSS
 
 From here, you have access to include the SCSS files from the package so you can compile the package yourself:
 
@@ -43,7 +41,7 @@ From here, you have access to include the SCSS files from the package so you can
 - `node_modules/@nationalarchives/frontend/nationalarchives/components/tabs.css`
 - `node_modules/@nationalarchives/frontend/nationalarchives/components/tabs.css.map`
 
-### JavaScript
+## JavaScript
 
 ```JavaScript
 // Import all the JavaScript
@@ -59,29 +57,3 @@ import "node_modules/@nationalarchives/frontend/nationalarchives/components/tabs
 - `node_modules/@nationalarchives/frontend/nationalarchives/all.js.map`
 - `node_modules/@nationalarchives/frontend/nationalarchives/components/tabs.js`
 - `node_modules/@nationalarchives/frontend/nationalarchives/components/tabs.js.map`
-
-## Hosted
-
-### CSS
-
-Include the CSS in the `<head>` element of your page:
-
-```html
-<!-- All styles -->
-<link href="https://cdn.jsdelivr.net/npm/@nationalarchives/[email protected]/nationalarchives/all.css" rel="stylesheet" integrity="sha384-6Egfw6aX1Jrwuf+APn+BMPswroudkIQ6StU095OPkNCKLEzj7ksWGmYxjend8P7g" crossorigin="anonymous">
-
-<!-- Styles for a single component -->
-<link href="https://cdn.jsdelivr.net/npm/@nationalarchives/[email protected]/nationalarchives/components/tabs.css" rel="stylesheet" integrity="sha384-hkx4svJn1A7pWYlzaDRMmtIBBijZdEop+M1Y/H4Hdg8aAqZRJHG56RokLk/eqJYl" crossorigin="anonymous">
-```
-
-### JavaScript
-
-Add the JavaScript to the end of your page just before your closing `</body>` tag:
-
-```html
-<!-- All JavaScript -->
-<script src="https://cdn.jsdelivr.net/npm/@nationalarchives/[email protected]/nationalarchives/all.js" integrity="sha384-sBkiMlxl9svXopGxNSMVAdALjzyvh6sQHp+21PE3LGfTxAEbG4EIpK" crossorigin="anonymous"></script>
-
-<!-- JavaScript for a single component -->
-<script src="https://cdn.jsdelivr.net/npm/@nationalarchives/[email protected]/nationalarchives/components/tabs.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
-```