From bf3e27ad4ad3d751b210967dee406a6fdeb31cc6 Mon Sep 17 00:00:00 2001
From: Andrew Hosgood <andrew.hosgood@nationalarchives.gov.uk>
Date: Wed, 11 Oct 2023 18:05:45 +0100
Subject: [PATCH] Add more top typography page

---
 .metalsmith/markdownRenderer.js               |   8 +++-
 layouts/collection-page.njk                   |  13 +++++-
 layouts/layout-example.njk                    |   2 +
 lib/index.scss                                |  33 +++++++++++++-
 src/components/breadcrumbs/index.md           |   2 +-
 src/components/button/index.md                |   6 +--
 src/components/card/index.md                  |   4 +-
 src/components/footer/index.md                |   2 +-
 src/components/gallery/index.md               |   2 +-
 src/components/grid/index.md                  |   4 +-
 src/components/header/index.md                |   2 +-
 src/components/hero/index.md                  |   2 +-
 src/components/index-grid/index.md            |   2 +-
 src/components/message/index.md               |   2 +-
 src/components/phase-banner/index.md          |   2 +-
 src/components/picture/index.md               |   2 +-
 src/components/skip-link/index.md             |   2 +-
 src/components/tabs/index.md                  |   8 ++--
 src/styles/.DS_Store                          | Bin 0 -> 6148 bytes
 src/styles/colours/index.md                   |  11 +++++
 src/styles/index.md                           |   6 ++-
 src/styles/lists/index.md                     |   7 +++
 .../index.njk                                 |  14 ++++++
 .../headings-with-supertitles/index.njk       |  11 +++++
 src/styles/typography/headings/index.njk      |   9 ++++
 src/styles/typography/index.md                |  43 +++++++++++++++++-
 .../typography/paragraphs-small/index.njk     |   6 +++
 src/styles/typography/paragraphs/index.njk    |   6 +++
 28 files changed, 184 insertions(+), 27 deletions(-)
 create mode 100644 src/styles/.DS_Store
 create mode 100644 src/styles/colours/index.md
 create mode 100644 src/styles/lists/index.md
 create mode 100644 src/styles/typography/headings-with-separate-supertitles/index.njk
 create mode 100644 src/styles/typography/headings-with-supertitles/index.njk
 create mode 100644 src/styles/typography/headings/index.njk
 create mode 100644 src/styles/typography/paragraphs-small/index.njk
 create mode 100644 src/styles/typography/paragraphs/index.njk

diff --git a/.metalsmith/markdownRenderer.js b/.metalsmith/markdownRenderer.js
index eafedd4..0a2f24d 100644
--- a/.metalsmith/markdownRenderer.js
+++ b/.metalsmith/markdownRenderer.js
@@ -2,6 +2,9 @@ import { marked } from "marked";
 
 const markdownRenderer = new marked.Renderer();
 
+const slugify = (text) =>
+  encodeURIComponent(text.toLowerCase().trim().replace(/[\s]/g, "-"));
+
 markdownRenderer.heading = function (text, level) {
   let headingSize = "";
   switch (level) {
@@ -20,9 +23,10 @@ markdownRenderer.heading = function (text, level) {
       headingSize = "tna-heading--s";
       break;
   }
+  const slug = slugify(text);
   return `
-  <h${level} class="tna-heading ${headingSize}">
-    ${text}
+  <h${level} id="${slug}" class="tna-heading ${headingSize} tna-heading--no-link-arrow">
+    ${text} <a href="#${slug}" aria-hidden="true"><i class="fa-solid fa-link"></i></a>
   </h${level}>`;
 };
 
diff --git a/layouts/collection-page.njk b/layouts/collection-page.njk
index 2674881..c7bdc0a 100644
--- a/layouts/collection-page.njk
+++ b/layouts/collection-page.njk
@@ -1,5 +1,16 @@
 {% extends "./_design-system-base.njk" %}
 
+{% block skipLink %}
+{{ tnaSkipLink({
+  href: 'main-content',
+  text: 'Skip to main content'
+}) }}
+{{ tnaSkipLink({
+  href: group + '-list',
+  text: 'Skip to list of ' + group
+}) }}
+{% endblock %}
+
 {% block main %}
   <div class="tna-container">
     <main class="tna-column tna-column--width-3-4 tna-column--width-2-3-medium tna-column--full-small tna-column--full-tiny {{ mainClasses }} tna-section" id="main-content" role="main">
@@ -15,7 +26,7 @@
       {% endif %}
       {{ contents | safe }}
     </main>
-    <nav class="tna-column tna-column--width-1-4 tna-column--width-1-3-medium tna-column--full-small tna-column--full-tiny tna-section" role="navigation" aria-label="{{ title }} navigation">
+    <nav id="{{ group }}-list" class="tna-column tna-column--width-1-4 tna-column--width-1-3-medium tna-column--full-small tna-column--full-tiny tna-section" role="navigation" aria-label="{{ title }} navigation">
       <ul class="tna-ds-sidebar">
       {% for component in collections[group] %}
         <li class="tna-ds-sidebar__item{{ ' tna-ds-sidebar__item--current' if component.path == path }}">
diff --git a/layouts/layout-example.njk b/layouts/layout-example.njk
index 2ca9bba..254abc7 100644
--- a/layouts/layout-example.njk
+++ b/layouts/layout-example.njk
@@ -8,7 +8,9 @@
 {% block skipLink %}{% endblock %}
 
 {% block main %}
+<main>
   {{ contents | safe }}
+</main>
 {% endblock %}
 
 {% block footer %}{% endblock %}
diff --git a/lib/index.scss b/lib/index.scss
index 60af60f..615a7dc 100644
--- a/lib/index.scss
+++ b/lib/index.scss
@@ -16,6 +16,8 @@
 @use "@nationalarchives/frontend/nationalarchives/tools/typography";
 @import "prismjs/themes/prism.min";
 
+$code-background: #f1ece9;
+
 .tna-breadcrumbs {
   &__link {
     &::first-letter {
@@ -150,7 +152,7 @@
 
       :not(pre) > code[class*="language-"],
       pre[class*="language-"] {
-        background-color: #f1ece9;
+        background-color: $code-background;
 
         .language-css .token.string,
         .style .token.string,
@@ -171,6 +173,12 @@
   }
 }
 
+p {
+  code {
+    background-color: $code-background;
+  }
+}
+
 .app-example-page {
   min-height: auto;
   padding: 2rem;
@@ -202,6 +210,29 @@
   }
 }
 
+.tna-heading {
+  a[href^="#"] {
+    width: 1.5rem;
+
+    display: none;
+
+    @include typography.relative-font-size(16);
+    vertical-align: middle;
+    line-height: 1.5rem;
+    text-align: center;
+
+    &::after {
+      display: none;
+    }
+  }
+
+  &:hover {
+    a[href^="#"] {
+      display: inline-block;
+    }
+  }
+}
+
 .tna-table {
   width: 100%;
   margin-top: 2rem;
diff --git a/src/components/breadcrumbs/index.md b/src/components/breadcrumbs/index.md
index c026d7a..925a6e1 100644
--- a/src/components/breadcrumbs/index.md
+++ b/src/components/breadcrumbs/index.md
@@ -8,4 +8,4 @@ The breadcrumbs component is for...
 
 {% from "_example.njk" import example %}
 
-{{ example({group: "components", item: "breadcrumbs", example: "default", html: true, nunjucks: true, open: false}) }}
+{{ example({ group: "components", item: "breadcrumbs", example: "default", html: true, nunjucks: true, open: false }) }}
diff --git a/src/components/button/index.md b/src/components/button/index.md
index 4cc9607..be83313 100644
--- a/src/components/button/index.md
+++ b/src/components/button/index.md
@@ -8,8 +8,8 @@ The button component is for...
 
 {% from "_example.njk" import example %}
 
-{{ example({group: "components", item: "button", example: "default", html: true, nunjucks: true, open: false, size: "xxs"}) }}
+{{ example({ group: "components", item: "button", example: "default", html: true, nunjucks: true, open: false, size: "xxs"}) }}
 
-{{ example({group: "components", item: "button", example: "icon", html: true, nunjucks: true, open: false, size: "xxs"}) }}
+{{ example({ group: "components", item: "button", example: "icon", html: true, nunjucks: true, open: false, size: "xxs"}) }}
 
-{{ example({group: "components", item: "button", example: "brand-icon", html: true, nunjucks: true, open: false, size: "xxs"}) }}
+{{ example({ group: "components", item: "button", example: "brand-icon", html: true, nunjucks: true, open: false, size: "xxs"}) }}
diff --git a/src/components/card/index.md b/src/components/card/index.md
index b9a9145..e19b02c 100644
--- a/src/components/card/index.md
+++ b/src/components/card/index.md
@@ -8,6 +8,6 @@ The card component is for...
 
 {% from "_example.njk" import example %}
 
-{{ example({group: "components", item: "card", example: "default", html: true, nunjucks: true, open: false}) }}
+{{ example({ group: "components", item: "card", example: "default", html: true, nunjucks: true, open: false }) }}
 
-{{ example({group: "components", item: "card", example: "horizontal", html: true, nunjucks: false, open: false}) }}
+{{ example({ group: "components", item: "card", example: "horizontal", html: true, nunjucks: false, open: false }) }}
diff --git a/src/components/footer/index.md b/src/components/footer/index.md
index fc96b0d..d95b328 100644
--- a/src/components/footer/index.md
+++ b/src/components/footer/index.md
@@ -8,5 +8,5 @@ The footer component is for...
 
 {% from "_example.njk" import example %}
 
-{{ example({group: "components", item: "footer", example: "default", html: true, nunjucks: true, open: false}) }}
+{{ example({ group: "components", item: "footer", example: "default", html: true, nunjucks: true, open: false }) }}
 
diff --git a/src/components/gallery/index.md b/src/components/gallery/index.md
index 0e148f1..6cff95f 100644
--- a/src/components/gallery/index.md
+++ b/src/components/gallery/index.md
@@ -8,4 +8,4 @@ The gallery component is for...
 
 {% from "_example.njk" import example %}
 
-{{ example({group: "components", item: "gallery", example: "default", html: true, nunjucks: true, open: false}) }}
+{{ example({ group: "components", item: "gallery", example: "default", html: true, nunjucks: true, open: false }) }}
diff --git a/src/components/grid/index.md b/src/components/grid/index.md
index 7646d96..3ff897a 100644
--- a/src/components/grid/index.md
+++ b/src/components/grid/index.md
@@ -8,7 +8,7 @@ The grid component is for...
 
 {% from "_example.njk" import example %}
 
-{{ example({group: "components", item: "grid", example: "default", html: true, nunjucks: true, open: false}) | safe }}
+{{ example({ group: "components", item: "grid", example: "default", html: true, nunjucks: true, open: false}) | safe }}
 
 ## Column widths
 
@@ -73,7 +73,7 @@ On a 2 column grid (tiny devices), the widths available are:
 
 ## Responsive example
 
-{{ example({group: "components", item: "grid", example: "responsive", html: true, nunjucks: true, open: false}) | safe }}
+{{ example({ group: "components", item: "grid", example: "responsive", html: true, nunjucks: true, open: false}) | safe }}
 
 ## Flexible columns
 
diff --git a/src/components/header/index.md b/src/components/header/index.md
index c7896bf..13924c8 100644
--- a/src/components/header/index.md
+++ b/src/components/header/index.md
@@ -8,7 +8,7 @@ The header component is for...
 
 {% from "_example.njk" import example %}
 
-{{ example({group: "components", item: "header", example: "default", html: true, nunjucks: true, open: false}) | safe }}
+{{ example({ group: "components", item: "header", example: "default", html: true, nunjucks: true, open: false}) | safe }}
 
 ## Design history
 
diff --git a/src/components/hero/index.md b/src/components/hero/index.md
index 3f7cd01..009b18d 100644
--- a/src/components/hero/index.md
+++ b/src/components/hero/index.md
@@ -10,5 +10,5 @@ The hero component is for...
 
 ## Example
 
-{{ example({group: "components", item: "hero", example: "default", html: true, nunjucks: true, open: false}) | safe }}
+{{ example({ group: "components", item: "hero", example: "default", html: true, nunjucks: true, open: false}) | safe }}
 
diff --git a/src/components/index-grid/index.md b/src/components/index-grid/index.md
index 3e61784..b5cf019 100644
--- a/src/components/index-grid/index.md
+++ b/src/components/index-grid/index.md
@@ -8,4 +8,4 @@ The index grid component is for...
 
 {% from "_example.njk" import example %}
 
-{{ example({group: "components", item: "index-grid", example: "default", html: true, nunjucks: true, open: false}) }}
+{{ example({ group: "components", item: "index-grid", example: "default", html: true, nunjucks: true, open: false }) }}
diff --git a/src/components/message/index.md b/src/components/message/index.md
index a1c42a0..b67b5e2 100644
--- a/src/components/message/index.md
+++ b/src/components/message/index.md
@@ -8,4 +8,4 @@ The message component is for...
 
 {% from "_example.njk" import example %}
 
-{{ example({group: "components", item: "message", example: "default", html: true, nunjucks: true, open: false}) }}
+{{ example({ group: "components", item: "message", example: "default", html: true, nunjucks: true, open: false }) }}
diff --git a/src/components/phase-banner/index.md b/src/components/phase-banner/index.md
index 0cc28b9..5816cd7 100644
--- a/src/components/phase-banner/index.md
+++ b/src/components/phase-banner/index.md
@@ -8,4 +8,4 @@ The phase banner component is for...
 
 {% from "_example.njk" import example %}
 
-{{ example({group: "components", item: "phase-banner", example: "default", html: true, nunjucks: true, open: false}) }}
+{{ example({ group: "components", item: "phase-banner", example: "default", html: true, nunjucks: true, open: false }) }}
diff --git a/src/components/picture/index.md b/src/components/picture/index.md
index 360020d..2d6187b 100644
--- a/src/components/picture/index.md
+++ b/src/components/picture/index.md
@@ -8,4 +8,4 @@ The picture component is for...
 
 {% from "_example.njk" import example %}
 
-{{ example({group: "components", item: "picture", example: "default", html: true, nunjucks: true, open: false}) }}
+{{ example({ group: "components", item: "picture", example: "default", html: true, nunjucks: true, open: false }) }}
diff --git a/src/components/skip-link/index.md b/src/components/skip-link/index.md
index b4d8acf..a03ff5c 100644
--- a/src/components/skip-link/index.md
+++ b/src/components/skip-link/index.md
@@ -8,4 +8,4 @@ The skip link component is for...
 
 {% from "_example.njk" import example %}
 
-{{ example({group: "components", item: "skip-link", example: "default", html: true, nunjucks: true, open: false}) }}
+{{ example({ group: "components", item: "skip-link", example: "default", html: true, nunjucks: true, open: false }) }}
diff --git a/src/components/tabs/index.md b/src/components/tabs/index.md
index 82c7236..6612d16 100644
--- a/src/components/tabs/index.md
+++ b/src/components/tabs/index.md
@@ -8,16 +8,16 @@ The tabs component is for...
 
 {% from "_example.njk" import example %}
 
-{{ example({group: "components", item: "tabs", example: "default", html: true, nunjucks: true, open: false, size: "s"}) }}
+{{ example({ group: "components", item: "tabs", example: "default", html: true, nunjucks: true, open: false, size: "s"}) }}
 
 ## Without JavaScript
 
-{{ example({group: "components", item: "tabs", example: "default-no-js", html: false, nunjucks: false, open: false, size: "s"}) }}
+{{ example({ group: "components", item: "tabs", example: "default-no-js", html: false, nunjucks: false, open: false, size: "s"}) }}
 
 ## Without CSS
 
-{{ example({group: "components", item: "tabs", example: "default-no-css", html: false, nunjucks: false, open: false, size: "s"}) }}
+{{ example({ group: "components", item: "tabs", example: "default-no-css", html: false, nunjucks: false, open: false, size: "s"}) }}
 
 ## Without CSS or JavaScript
 
-{{ example({group: "components", item: "tabs", example: "default-no-css-no-js", html: false, nunjucks: false, open: false, size: "s"}) }}
+{{ example({ group: "components", item: "tabs", example: "default-no-css-no-js", html: false, nunjucks: false, open: false, size: "s"}) }}
diff --git a/src/styles/.DS_Store b/src/styles/.DS_Store
new file mode 100644
index 0000000000000000000000000000000000000000..2c5407616e1dcdc88a4da555eadaeb82119c7d3a
GIT binary patch
literal 6148
zcmeHKOHRW;47E!UL2SBYIalb8WvIdldI8i{0z{%zlu9f|a2hxU5=Uas^Vn1ql1i))
zs%**gCLVh}Z=yIRBA#tmQ=$nG6;Q#^DVhP1anYWP%p!xF=Gf8$ZR(rpeA)KA-S8h7
zkh?pfCACyTv-@k-*>-<;G;LKa>UIH-;<<WzkM|#!{dt;p^$V}{t-LLr)sC^3JKE6W
z_q()jG~dVP>(j-H?jwuO_b}`+uzq%M?>Ym{fHQEA3?OHV6laRwIs?vtGq7Voz7GK^
zSQ<vf^yxs8N&w&(<|OD#Eg><%ur!Q{7=f^c0yUJa#9$4FJ(yo<7!@^~*oqIfmDws3
zPOD@7klcw&MQ@z}XQ0c#kv>i&|6lE||GPo{<P10i2gLx7t9doUku10N4kx)bK(C=9
n;ujTnA?T!33|~pb=g=gu2k8Jy!>9-g#D4@54c<5df6BlYyQEA;

literal 0
HcmV?d00001

diff --git a/src/styles/colours/index.md b/src/styles/colours/index.md
new file mode 100644
index 0000000..7eea62d
--- /dev/null
+++ b/src/styles/colours/index.md
@@ -0,0 +1,11 @@
+---
+layout: collection-page.njk
+title: Colours
+group: styles
+---
+
+Always use the provided TNA colour palette.
+
+## Colour contrast
+
+You must make sure that the contrast ratio of text and interactive elements in your service meets [level AA of the Web Content Accessibility Guidelines (WCAG 2.1)](https://www.w3.org/TR/WCAG21/#contrast-minimum).
diff --git a/src/styles/index.md b/src/styles/index.md
index 69467c7..6f39b71 100644
--- a/src/styles/index.md
+++ b/src/styles/index.md
@@ -5,4 +5,8 @@ group: styles
 order: 3
 ---
 
-Hello
+Make services look and feel like The National Archives.
+
+If you are using the GOV.UK Prototype Kit with TNA Frontend or have TNA Frontend included in your build, the coded examples in the Design System will not need any additional styling.
+
+If you need to apply styles manually, you should still follow existing National Archives conventions. For example, do not assign new meanings to colours, do not change the style of buttons or adjust the thickness of borders on form inputs.
diff --git a/src/styles/lists/index.md b/src/styles/lists/index.md
new file mode 100644
index 0000000..20c1091
--- /dev/null
+++ b/src/styles/lists/index.md
@@ -0,0 +1,7 @@
+---
+layout: collection-page.njk
+title: Lists
+group: styles
+---
+
+ul, ol, dl
diff --git a/src/styles/typography/headings-with-separate-supertitles/index.njk b/src/styles/typography/headings-with-separate-supertitles/index.njk
new file mode 100644
index 0000000..c512501
--- /dev/null
+++ b/src/styles/typography/headings-with-separate-supertitles/index.njk
@@ -0,0 +1,14 @@
+---
+title: Headings with separate supertitles
+layout: layout-example.njk
+---
+
+<hgroup class="tna-hgroup tna-hgroup--xl">
+  <p class="tna-hgroup__supertitle">Supertitle</p>
+  <h3 class="tna-hgroup__title">Title</h3>
+</hgroup>
+
+<hgroup class="tna-hgroup tna-hgroup--l">
+  <p class="tna-hgroup__supertitle">Supertitle</p>
+  <h3 class="tna-hgroup__title">Title</h3>
+</hgroup>
diff --git a/src/styles/typography/headings-with-supertitles/index.njk b/src/styles/typography/headings-with-supertitles/index.njk
new file mode 100644
index 0000000..744cec0
--- /dev/null
+++ b/src/styles/typography/headings-with-supertitles/index.njk
@@ -0,0 +1,11 @@
+---
+title: Headings with supertitles
+layout: layout-example.njk
+---
+
+<hgroup class="tna-hgroup tna-hgroup--l">
+  <h3>
+    <span class="tna-hgroup__supertitle">Supertitle</span>
+    <span class="tna-hgroup__title">Title</span>
+  </h3>
+</hgroup>
diff --git a/src/styles/typography/headings/index.njk b/src/styles/typography/headings/index.njk
new file mode 100644
index 0000000..5ce4f87
--- /dev/null
+++ b/src/styles/typography/headings/index.njk
@@ -0,0 +1,9 @@
+---
+title: Headings
+layout: layout-example.njk
+---
+
+<h1 class="tna-heading tna-heading--xl">tna-heading--xl</h1>
+<h2 class="tna-heading tna-heading--l">tna-heading--l</h2>
+<h3 class="tna-heading tna-heading--m">tna-heading--m</h3>
+<h4 class="tna-heading tna-heading--s">tna-heading--s</h4>
diff --git a/src/styles/typography/index.md b/src/styles/typography/index.md
index 4b2e353..9e310c1 100644
--- a/src/styles/typography/index.md
+++ b/src/styles/typography/index.md
@@ -4,4 +4,45 @@ title: Typography
 group: styles
 ---
 
-h1, h2
+{% from "_example.njk" import example %}
+
+## Headings
+
+Write all headings in sentence case.
+
+Use heading tags, such as `<h1>`, `<h2>` and so on, to tag the headings on a page. Apply a heading class, such as `tna-heading--l`, to style them visually. Style headings consistently to create a clear content structure throughout your service.
+
+{{ example({ group: "styles", item: "typography", example: "headings", html: true, nunjucks: false, open: false }) }}
+
+### Headings with supertitles
+
+Sometimes you may need to make it clear that a page is part of a larger section or group. To do this, you can use a heading group with a supertitle above the main heading.
+
+The supertitle should be short, at most two words.
+
+By default, the supertitle is a contrasting colour to the text, usually inverted. It is controlled by the accent colour of the page.
+
+{{ example({ group: "styles", item: "typography", example: "headings-with-separate-supertitles", html: true, nunjucks: false, open: false, size: "s" }) }}
+
+If the caption should be considered part of the page heading, you can also nest the supertitle within the heading.
+
+{{ example({ group: "styles", item: "typography", example: "headings-with-supertitles", html: true, nunjucks: false, open: false, size: "xs" }) }}
+
+## Paragraphs
+
+### Body
+
+The default paragraph font size is 18px.
+
+{{ example({ group: "styles", item: "typography", example: "paragraphs", html: true, nunjucks: false, open: false, size: "xxs" }) }}
+
+### Small
+
+You can use the `<small>` element sparingly to make your paragraph font size smaller: 15px.
+
+The majority of your body copy should use the standard 18px paragraph size.
+
+{{ example({ group: "styles", item: "typography", example: "paragraphs-small", html: true, nunjucks: false, open: false, size: "xxs" }) }}
+
+
+
diff --git a/src/styles/typography/paragraphs-small/index.njk b/src/styles/typography/paragraphs-small/index.njk
new file mode 100644
index 0000000..f2ffabd
--- /dev/null
+++ b/src/styles/typography/paragraphs-small/index.njk
@@ -0,0 +1,6 @@
+---
+title: Paragraphs small
+layout: layout-example.njk
+---
+
+<p><small>Lorem ipsum</small></p>
diff --git a/src/styles/typography/paragraphs/index.njk b/src/styles/typography/paragraphs/index.njk
new file mode 100644
index 0000000..6a1cc19
--- /dev/null
+++ b/src/styles/typography/paragraphs/index.njk
@@ -0,0 +1,6 @@
+---
+title: Paragraphs
+layout: layout-example.njk
+---
+
+<p>Lorem ipsum</p>