Add more top typography page

.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}>`;
 };
 

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 }}">

layouts/layout-example.njk

@@ -8,7 +8,9 @@
 {% block skipLink %}{% endblock %}
 
 {% block main %}
+<main>
   {{ contents | safe }}
+</main>
 {% endblock %}
 
 {% block footer %}{% endblock %}

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;

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 }) }}

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"}) }}

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 }) }}

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 }) }}
 

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 }) }}

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
 

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
 

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 }}
 

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 }) }}

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 }) }}

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 }) }}

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 }) }}

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 }) }}

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"}) }}

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).

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.

src/styles/lists/index.md

@@ -0,0 +1,7 @@
+---
+layout: collection-page.njk
+title: Lists
+group: styles
+---
+
+ul, ol, dl

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>

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>

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>

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" }) }}
+
+
+

src/styles/typography/paragraphs-small/index.njk

@@ -0,0 +1,6 @@
+---
+title: Paragraphs small
+layout: layout-example.njk
+---
+
+<p><small>Lorem ipsum</small></p>

src/styles/typography/paragraphs/index.njk

@@ -0,0 +1,6 @@
+---
+title: Paragraphs
+layout: layout-example.njk
+---
+
+<p>Lorem ipsum</p>