shaunbent/govuk-proposal-pages

GOV.UK proposal pages

Purpose

Produce a single, self-contained HTML page that argues for a direction, explains an idea, or pitches a change, using the real GOV.UK Design System styles and a small library of reusable components.

The governing principle: show the content, don't narrate it. A list of things a team owns becomes a card grid. A set of steps becomes a flow. A comparison becomes a table with the differences highlighted. Prose is the connective tissue between components, not the main way information is carried.

Describe the content; this skill handles the look.

The output is one HTML file

Pages made with this skill are shared as files, often uploaded to SharePoint or a similar document library and linked from there. So:

• Everything lives in one .html file. CSS, fonts and images are embedded (fonts and images as base64 data URIs). No external stylesheets, scripts, fonts or images.
• The page must read correctly with JavaScript turned off. Some document libraries strip or block scripts in previews. Interactive components (such as the view switcher) are enhancements: the default state shown without JavaScript must make sense on its own.
• No build step for the reader. The file opens directly in a browser.

Files

• page-starter.html is a blank page: the GOV.UK Frontend CSS, the GDS Transport fonts embedded as base64, the full component CSS, a status banner, a hero and a footer with a change log. Every new page starts as a copy of this file. GDS Transport is licensed for GOV.UK use only; outside GOV.UK, swap it for another typeface (see NOTICE.md).
• docs/index.html is the documentation page for this skill, and it was built with the skill. Its "Components" section is the visual reference: every component, named and labelled, with when to use it, when to avoid it, and a live example. Copy component markup from the gx-specimen__demo blocks there. Don't copy the gx- classes; they only style the documentation page. It uses the same component CSS as the starter, so copied markup works without changes.

Document structure

Work out the argument before choosing components. Most proposals follow this order; drop the sections the content doesn't need.

Section	What it does	Components that often fit
Status and hero	Says what the document is and the one thing to take away	Status banner, hero
What it is	Explains the idea, if the audience may not know it	Categories, fan-out, layers, code pair
What it gives us	The benefits, early, for every group in the room	Benefit grid, wide card
Why now	The problem as it stands, with evidence	Silos, stats, compare table, many-to-one, research quote
How it works	The proposed approach	Flow, before and after, hub and spoke, fan-in, worked example
Who owns what	Responsibilities	Responsibilities, panel
Where we start	Scope and order	Phases, timeline
Risks	What could go wrong	Risk
Open questions	What you need from readers	Open questions
Success	How you'll know it worked	Success measures, outcome
Footer	Version and change log	Change log

Put "Why now" first only when readers already understand the solution space (see "Editorial principles").

Component catalogue

Every component has a name. People using this skill can ask for components by name ("use a fan-in to show where applications come from"), and you should use the same names when suggesting them. The "Components" section of docs/index.html shows each one live, with its class, when to use it, and when to avoid it. Copy the markup from there.

Page furniture

Name	Class	Use it when
Status banner	pt-topbanner	Every page. Shows the version and one line on what the document is.
Hero	pt-hero	Every page. An eyebrow tag, the title, and the sharpest sentence in the document.
Supporting note	pt-note	Meta information under a diagram, table or set of stats: sources, caveats, "illustrative".
Change log	pt-footer	The footer of every page. Newest entry first.

Cards

Name	Class	Use it when
Benefit grid	pt-owns-grid	Three or four things delivered, owned or gained.
Wide card	pt-owns-card--wide	An item that needs more room than its siblings, or to avoid one card sitting alone on a row.
Principles	pt-works-grid	Three principles or ways of working.
Categories	pt-categories	Types of a thing, each with a small visual that shows the category.
Panel	pt-card	A point that needs more room than a grid card, styled like every other card.
Risk	govuk-inset-text pt-card pt-card--warning	A risk to protect against, stated plainly and from experience.
Outcome	pt-card pt-card--success	What this becomes if it works.

Numbers

Name	Class	Use it when
Stats	pt-baseline-grid	Headline numbers. Every number has a plain label, and the set adds up to a stated total where it can.

Diagrams

Name	Class	Use it when
Fan-out	pt-fanout	One source feeding several outputs.
Fan-in	pt-fanin	Several sources that come together into one thing: inputs to a decision, data feeding one record, teams contributing to one service. Works best with three to five inputs. The example draws four curves, starting at y 12.5, 37.5, 62.5 and 87.5; for a different number of inputs, start each curve at the centre of its input (for three: 16.7, 50 and 83.3).
Hub and spoke	pt-hub	One central thing with up to four parts that connect to it.
Silos	pt-silos	The same thing held separately in several places, with nothing connecting them. Flag the copy that differs.
Many-to-one	pt-many-to-one	Several names or routes that lead to the same thing: duplicates, aliases, overlapping work.
Before and after	pt-before-after	The same thing today and as proposed, side by side.
Layers	pt-layers	Levels that build on each other, joined by labelled arrows. Connector labels are regular weight.
Flow	pt-flow	A process with numbered steps and an end state. Mark undecided destinations as open with an "Approach to agree" tag.
Phases	pt-phases	Stages of work in a real order. The current stage is filled.
Timeline	pt-timeline	Dated milestones. Past milestones filled, future ones hollow.
Spectrum	pt-spectrum	Where things sit on a range between two ends: maturity, effort, risk.
Teams	pt-squads	How teams relate, especially restructuring. Mark a team changing state as dashed.

Tables and lists

Name	Class	Use it when
Compare table	pt-compare	Several options or places side by side. Group rows, and highlight the odd value on the whole cell.
Responsibilities	pt-split	Who is responsible for what, two groups side by side.
Open questions	pt-questions	Questions you want answered, each tagged with who it's for.
Success measures	pt-check-list	Five or six checkable outcomes.

Examples and evidence

Name	Class	Use it when
Worked example	pt-example	A concrete case: a visual, then how each place handles it today.
Research quote	pt-quote	What a user, colleague or stakeholder actually said, with who said it.
Code pair	pt-code-pair	Data, code or configuration, alone or side by side. Label simplified snippets "Illustrative".
Colour dot	pt-swatch	A colour or status shown inline, in a table or a sentence. Always paired with a text label.

Interactive

Name	Class	Use it when
View switcher	pt-views	Flip a diagram between two states, such as "Today" and "Proposed". Optional, needs JavaScript.

If content doesn't fit any of these, write a short paragraph (fine, in moderation) or add a component (see "Extending the library").

Editorial principles

Structure

• One document, one throughline. Every component should serve the central argument. If something is interesting but not load-bearing, cut it.
• Explain the idea before making the case for it when the audience may not know the idea. Problem-first works when people already understand the solution space. When they don't, a problem section reads as a list of complaints with no way out. See "Document structure" for the default order.
• Put the benefits early. Readers decide whether to care in the first screen or two.
• Show the full scope with the first example. If the first example is narrow, readers assume the whole proposal is narrow. When the idea applies broadly, open with an example that hints at the breadth, then use the narrow case as evidence.
• Cut sections that don't need to be there. If a section is about a decision for a different conversation, leave it out.

Language

• Introduce a term before you use it. This includes headings, labels and table groups. If the term appears before it's explained, use a plain description instead.
• Give each term one job. If two similar words both appear (for example "decision" for a single choice and "approach" for the whole method), keep each to its own meaning throughout.
• Describe an approach as "a common way", not "the way", unless it really is the only way. It's more accurate and invites discussion.
• Use words that describe, not blame. "Defined in some places, not others" describes a situation. "Gaps" or "missing" implies someone failed.
• When the author provides wording, use it as written. Fix only grammar, and say what you changed.

Evidence

• Use real data from the source (the system, the spreadsheet, the export), not figures recalled or estimated. Say where the numbers come from.
• Flag anything read from a screenshot or summary so it can be checked before the page is shared.
• Don't overclaim status. If something was well received but not formally agreed, say so precisely, or leave the status out.
• Mark undecided choices as undecided. An "Approach to agree" tag on an option is better than presenting a guess as a decision.

Tone with mixed audiences

• Be even-handed. When showing a problem that involves several teams or places, show each one's part. A page that singles out one group gets read defensively by that group.
• Frame shared benefits for every group in the room. Describe what each group gains in its own terms. Don't name the friction between groups in the document, even if it's the real motivation. The benefits can address it without describing it.

House style

The default house style, change it to suit:

• UK English, sentence case headings, Oxford comma
• No em dashes; restructure with a comma, colon, semicolon or full stop
• No "it's not X, it's Y" constructions
• No military or combat metaphors
• Lowercase "government" unless part of a name
• Plain, direct, confident; every word earns its place, and intro lines don't repeat takeaway lines

Visual rules

• One card treatment everywhere. Cards are white, with a 1px grey border, a 4px blue top border, an optional icon, a small heading (govuk-heading-s) and small body text (govuk-body-s). Don't invent one-off card styles; restyle new content to match.
• No orphans in grids. If a grid would leave one card alone on a row, make that card wide or change the column count.
• Colour swatches are circles, matching the GOV.UK Design System colour pages.
• Comparison tables highlight the whole cell, not an inline background behind the text, so values stay aligned down each column. Every cell and group header shares the same left edge.
• Connector labels in diagrams are regular weight. Bold is for headings and the thing being pointed at.
• Supporting notes (pt-note): 16px small body text in the secondary text colour (#505a5f). Use for meta information under a diagram, table or set of stats: caveats, sources, "illustrative" labels.
• Side-by-side code blocks are the same height.
• Diagrams use box-sizing: border-box (set in the component CSS) so padding and borders never push a component out of its box.
• The hero tag stays on one line. GOV.UK tags have a 160px maximum width by default; the component CSS lifts it for the hero and banner.
• Custom fonts or images must be embedded, and only if their licence allows it. Check the licence first. Custom typefaces often need manual vertical centring: measure the rendered text and adjust padding.
• Accessibility: give diagrams a text alternative (role="img" with an aria-label that states what the diagram shows), keep visible focus states on interactive controls, and don't rely on colour alone to show a difference (the highlighted cells are also bold).

Interactive components

The view switcher (pt-views) lets a reader flip a diagram between states, for example "today" and "proposed", or "light" and "dark". It's optional:

• The default state must be the one that makes sense without JavaScript.
• Use real <button> elements with aria-pressed.
• Keep the script inline and tiny; the starter includes one you can reuse.

Build workflow

1. Gather the content first: the argument, the evidence, who it's for, and what you want them to do. Choosing components before the content is clear produces a polished page with thin substance.
2. Plan the sections using "Document structure", and pick components by name from the catalogue. If the person has asked for specific components, use those.
3. Copy page-starter.html to a new file. Fill in the banner, hero and footer.
4. Copy each component's markup from the "Components" section of docs/index.html and replace the placeholder content. Never leave placeholder text in the page.
5. If the page uses a view switcher, keep the script at the end of the starter; otherwise delete it.
6. Check the page in a browser at desktop width and at phone width (about 400px). Look for anything overflowing its box, orphaned cards, misaligned table columns and text that wraps badly.
7. Share it, expect several rounds of specific feedback, and make targeted edits rather than regenerating the page.
8. For each round, bump the version and add a change log entry. Use minor versions (1.1, 1.2) for edits and a new major version (2.0) when the approach changes.

Working with comments

When feedback arrives as comments (in SharePoint, a document tool, or a chat):

• Read every comment before changing anything, so related comments are handled together.
• Reply to each comment saying what changed, quoting new wording where it helps.
• Leave resolving comments to the person who made them, so they can check your reply.
• If a comment is ambiguous, make the most reasonable change and say what you assumed.

Extending the library

If a new component is needed:

1. Use the same visual language: GDS blue (#1d70b8) as the accent, black (#0b0c0c) for high-contrast blocks, white cards with the standard border, GDS Transport for all text.
2. Icons: 36×36 viewbox, 2px stroke, GDS blue, minimal line art, at most one filled accent shape.
3. Add the CSS to the component library in both page-starter.html and docs/index.html, with a comment saying when to use it. The component CSS block must be identical in both files.
4. Add a labelled example to the "Components" section of docs/index.html, following the existing gx-specimen pattern, and a row to the catalogue above.
5. Bump the version in the banner and change log of docs/index.html, and add an entry to CHANGELOG.md.
6. Check it at phone width.

Rebuilding the CSS from source

Only needed if the assets are lost or you want a newer govuk-frontend:

npm install govuk-frontend --no-audit --no-fund

The compiled CSS is at node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.css and the fonts at node_modules/govuk-frontend/dist/govuk/assets/fonts/. Base64-encode each font and replace the url(/assets/fonts/...) references with data:font/woff2;base64,... (or font/woff) data URIs. Then add the component library CSS from page-starter.html on top.