@defra/docusaurus-theme-govuk 0.0.20-alpha → 0.0.22-alpha

package/README.md

@@ -2,9 +2,13 @@
 
 A Docusaurus 3 theme that applies the [GOV.UK Design System](https://design-system.service.gov.uk/) to your documentation site.
 
+## Intended use
+
+This theme is intended for **developer documentation sites**, not public-facing government services. Certain GOV.UK assets are intentionally omitted or substituted for licensing reasons — for example, the crown logo is not included and GDS Transport is not bundled. See [Making your service look like GOV.UK](https://www.gov.uk/service-manual/design/making-your-service-look-like-govuk#if-your-service-isnt-on-govuk) for the relevant guidance.
+
 ## Features
 
-- Full GOV.UK Design System shell: Header (with crown crest), Service Navigation, Phase Banner, Footer
+- Full GOV.UK Design System shell: Header, Service Navigation, Phase Banner, Footer
 - GOV.UK typography applied to all Markdown/MDX content via prose scoping
 - Sidebar navigation driven by configuration (not Docusaurus's built-in sidebar UI)
 - Syntax-highlighted code blocks with copy button

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/docusaurus-theme-govuk",
-  "version": "0.0.20-alpha",
+  "version": "0.0.22-alpha",
   "description": "A Docusaurus theme implementing the GOV.UK Design System for consistent, accessible documentation sites",
   "main": "index.js",
   "license": "MIT",

package/src/css/prose-scope.scss

@@ -5,15 +5,15 @@
 .app-prose-scope {
   // Headings
   h1:not(.app-no-prose *) {
-    @extend %govuk-heading-xl;
+    @extend %govuk-heading-l;
   }
 
   h2:not(.app-no-prose *) {
-    @extend %govuk-heading-l;
+    @extend %govuk-heading-m;
   }
 
   h3:not(.app-no-prose *) {
-    @extend %govuk-heading-m;
+    @extend %govuk-heading-s;
   }
 
   h4:not(.app-no-prose *) {
@@ -110,19 +110,6 @@
     }
   }
 
-  // Override GDS Transport on all prose elements. This must come after the
-  // @extend rules above (which bake in "GDS Transport" from govuk-frontend) so
-  // that cascade order wins at equal specificity. app-no-prose content is
-  // excluded so host apps can render GDS Transport there if licensed.
-  h1:not(.app-no-prose *),
-  h2:not(.app-no-prose *),
-  h3:not(.app-no-prose *),
-  h4:not(.app-no-prose *),
-  p:not(.app-no-prose *),
-  li:not(.app-no-prose *),
-  a:not(.app-no-prose *) {
-    font-family: Helvetica, Arial, sans-serif;
-  }
 
 
   // Code block copy button

package/src/css/theme.scss

@@ -11,16 +11,24 @@
 @import 'govuk-frontend/dist/govuk/objects/grid';
 
 /*
- * Set the default font on the body so that ALL elements
- * (header, footer, service-nav, etc.) inherit the same stack.
- * The prose-scope only covers content inside .app-prose-scope;
- * without this, outer chrome inherits the browser default serif.
- * GDS Transport is not bundled — Helvetica/Arial is used instead.
+ * Font: Helvetica/Arial (not GDS Transport).
+ *
+ * GDS Transport is Crown Copyright and may only be used on gov.uk domains.
+ * This theme is designed for use on non-gov.uk domains (e.g. GitHub Pages),
+ * so Helvetica/Arial is used throughout as a visually similar alternative.
+ *
+ * !important is required for two reasons:
+ *   1. @not-govuk injects its own CSS via the JS bundle after static
+ *      stylesheets load, which would otherwise win the cascade.
+ *   2. govuk-frontend mixins (e.g. govuk-font) bake GDS Transport directly
+ *      into compiled output; !important ensures those are always overridden.
  */
 body,
+h1, h2, h3, h4, h5, h6,
+p, li, a, span:not(pre *):not(code *), label, legend, dt, dd, caption, summary,
 [class^="govuk-"],
 [class*=" govuk-"] {
-  font-family: Helvetica, Arial, sans-serif;
+  font-family: Helvetica, Arial, sans-serif !important;
 }
 
 // Restore GDS Transport inside .app-no-prose containers (e.g. map examples in

package/src/theme/Heading/index.js

@@ -1,9 +1,9 @@
 import React from 'react';
 
 const headingClasses = {
-  h1: 'govuk-heading-xl',
-  h2: 'govuk-heading-l',
-  h3: 'govuk-heading-m',
+  h1: 'govuk-heading-l',
+  h2: 'govuk-heading-m',
+  h3: 'govuk-heading-s',
   h4: 'govuk-heading-s',
   h5: 'govuk-heading-s',
   h6: 'govuk-heading-s',