Practical decision guide for AI coding agents designing, implementing, reviewing, refactoring, and testing UK government digital services.
This file synthesises official guidance into rules an agent can apply. Prefer the linked authoritative sources when this file and upstream guidance diverge.
- Decide with the hierarchy in Authority and conflict resolution.
- Classify every choice as must, should, or consider (see below).
- Prefer Design System + GOV.UK Frontend over inventing UI, unless research shows a justified exception.
- Ask “does the user still succeed?” when HTML-only, CSS fails, JS fails, assistive tech, or another channel is in play.
- Do not treat this repo (or any template) as assessment-ready by default — assessment readiness is earned through research, accessibility evidence, security, and operational maturity.
| Label | Meaning for the agent |
|---|---|
| Must | Legal duty, Service Standard / TCoP non-negotiable for live users, or explicit “must” in official guidance. Do not ship without it (or a documented, valid exception). |
| Should | Strong official recommendation. Default unless evidence shows a better user outcome and you can justify the trade-off. |
| Consider | Contextual. Use judgement, user research, and constraints (legacy, policy, channel mix). Document the choice. |
When official guidance uses “must” / “should” / “can”, mirror that language. Do not harden soft guidance into absolutes.
Prefer sources in this order when they overlap:
- Law and regulations — Equality Act 2010 / DDA 1995 (NI); Public Sector Bodies Accessibility Regulations 2018 (WCAG 2.2 AA + accessibility statement).
- Service Standard and Service Manual — how services must be designed and run for users.
- Technology Code of Practice (TCoP) — how technology projects are designed, bought, and assured (including spend controls).
- GOV.UK Design System — styles, components, patterns, and when/how to use them (user-facing consistency and researched defaults).
- GOV.UK Frontend docs + release notes + fixture HTML — technical contract for markup, CSS, JS, and upgrades.
- AI Playbook for the UK Government — when the service uses or is affected by AI.
- Government Design Principles — underlying philosophy when no more specific rule exists.
- Roadmaps / GitHub project boards — planning signal only; not a licence to ship unreleased chrome.
Community discussions and prototypes are starting points, not contracts. Validate with research for your users before adopting.
Government services exist so people can do something they need, often with no real alternative. The people who need a service most are often those who find it hardest to use.
Optimise for:
| Goal | Why it matters |
|---|---|
| User need first | Wrong problem → wasted public money and failed journeys. |
| Whole journey | Users should not need to understand departmental boundaries. |
| Simplicity | Complexity causes errors, cost, and loss of trust. |
| Inclusion | Legal duty + better outcomes for everyone (situational and permanent needs). |
| Progressive enhancement | Networks, devices, browsers, and JS fail; core tasks must still work. |
| Security & privacy | Services hold personal and sensitive data; failure harms people and trust. |
| Reliability & operations | Limited choice of when/how people access government. |
| Reuse & openness | Avoid reinventing solved problems; reduce lock-in; share learning. |
| Sustainability | Digital services consume energy and materials; minimise impact. |
| Evidence | Research and performance data beat assumptions. |
Government Design Principles (compressed for decisions): start with user needs; do less; design with data; do the hard work to make it simple; iterate; this is for everyone; understand context; build services not websites; be consistent not uniform; make things open; minimise environmental impact.
Work top-down. Do not jump to UI frameworks or AI because they are available.
1. What user need and whole-problem journey is this for?
2. Is a new digital transaction needed, or would content, API, campaign, or reuse suffice?
3. What constraints are real (law, policy, offline channels) vs assumed?
4. Can Design System patterns/components meet the need?
5. Does HTML-first progressive enhancement cover the core task?
6. What accessibility, privacy, security, and operational risks appear?
7. What evidence (research, analytics, fixtures, tests) will prove it works?
8. Only then: implementation detail (stack, components, JS enhancement, AI).
The Service Standard is the primary product/engineering contract. Translate points into implementation behaviour:
| Point | Agent implication |
|---|---|
| 1. Understand users and needs | Do not invent journeys from assumptions. Prototype to learn; use research and data. Prefer throwaway prototypes early. |
| 2. Solve a whole problem | Scope by user mental model, not org chart. Reuse existing solutions (including existing AI) before building. Minimise re-asking for the same data (with privacy respect). Do not design the service around a technology, COTS product, or generative AI. |
| 3. Joined-up channels | Online + letters + phone + face-to-face must cohere. Code changes that break offline scripts or letters fail the standard. |
| 4. Simple to use | Success first time with minimum help. Match GOV.UK look/feel and content style for GOV.UK services. Test usability often. |
| 5. Everyone can use it | WCAG 2.2 AA, assisted digital for non-digital users, research with disabled people and protected characteristics. |
| 6. Multidisciplinary team | Implementation must be reviewable by design, content, research, security, ops. If AI is used, someone who understands it must be available to the team. |
| 7. Agile | Small releases; avoid contracts/tech that block iteration. |
| 8. Iterate frequently | Architecture must allow continuous improvement after go-live, not only bugfixes. |
| 9. Secure + privacy | Secure by Design; risk ownership; third-party due diligence; privacy-preserving data handling; security UX that enables journeys rather than blocking them unnecessarily. |
| 10. Success metrics | Instrument meaningful outcomes; central government publishes mandatory KPIs. Monitor bias/ethics where relevant, not only uptime. |
| 11. Right tools | Cost-effective, exit-friendly, understand total cost of ownership and AI impact on UX/inclusion/decision reliability. Prefer common platforms where appropriate. |
| 12. Open code | Publish new code openly by default (minus secrets); justify exceptions. |
| 13. Open standards & common patterns | Use Design System / common platforms; contribute useful new patterns; publish non-sensitive data openly when appropriate. |
| 14. Reliable service | Uptime, deployability, monitoring, QA not left solely to automation; environments like production; plan for incidents. |
Per Service Manual guidance on applying the standard:
- Can often iterate after release: imperfect UX, incomplete join-up, content polish — if research continues.
- Cannot iterate your way out of before real users: accessibility and security/privacy failures; AI used without understanding risks or without meeting identified user needs.
Avoid technology or contract choices that freeze the service so it cannot improve.
Use TCoP for all technology work; align with mandatory points for spend control. Practical defaults for agents:
| TCoP theme | Default stance |
|---|---|
| User needs | Technology follows researched needs, not vendor demos. |
| Accessible & inclusive | Infrastructure and interfaces include everyone; accessibility is not a frontend-only concern. |
| Open source | Prefer open source; publish code; avoid unnecessary proprietary lock-in. |
| Open standards | Interoperability over custom protocols; easier upgrades and exits. |
| Cloud first | Prefer public cloud per policy unless constraints justify otherwise. |
| Secure | Proportionate security across lifecycle; Secure by Design. |
| Privacy integral | Privacy by design; minimise personal data. |
| Share & reuse | Prefer common government components/platforms before building anew. |
| Integrate & adapt | Work with legacy deliberately; plan evolution. |
| Better use of data | Quality, ethics, and reuse — not hoarding. |
| Purchasing strategy | Commercial + technical fit; short enough contracts to allow change; accessibility in procurement. |
| Sustainable technology | Prefer efficient architectures, fewer heavy client bundles, sensible retention. |
| Meet Service Standard | If building a service, TCoP does not replace the Service Standard. |
- Meet WCAG 2.2 Level AA for websites and public-facing apps in scope of the regulations.
- Publish and maintain an accessibility statement (from public beta for services); keep it findable (typically every page / app store listing / in-app).
- Work with common assistive technologies (screen readers, magnifiers, speech recognition).
- Include disabled people in user research.
- Accessibility is a whole-team duty (content, design, development, research, product).
- Make non-digital parts accessible too (letters, contact channels, alternative formats).
- Assisted digital support is separate from accessibility: plan help for people who cannot use the digital service alone.
Public services are often compulsory. Inaccessible services exclude people who need them most, breach legal duties, and usually harm everyone (clarity, mobile use, keyboard use, resilience).
- Semantic HTML and logical source order / heading outline.
- One clear main
h1per page; do not skip heading levels for styling. - Visible focus styles; never remove outlines without an equivalent accessible focus indicator (do not override GOV.UK’s focus treatment).
- Full keyboard operability for all tasks.
- Sufficient colour contrast; do not repurpose Design System colours with new meanings.
- Form errors: error summary + field errors, matching wording; focus management to the summary;
Error:prefix in page title when validating. - Prefer labels, hints, and accessible names from Design System components over custom ARIA.
- Do not rely on colour, shape, or position alone to convey meaning.
- Test with assistive tech for JS-enhanced behaviour; automated checks are necessary but not sufficient.
- Plan audits before public beta; fix issues early (cheaper than late rework).
- Regulations list exempt content types (e.g. some legacy PDFs, live AV, certain third-party content). Explain exemptions in the statement; Equality Act reasonable adjustments still apply.
- Disproportionate burden is a documented legal assessment, not “we ran out of time/knowledge”. Agents must not claim it casually.
- Schools/nurseries and some bodies have partial/full exemptions from the regulations — still consider Equality Act duties.
All government services must follow progressive enhancement: HTML first, then CSS, then JavaScript as enhancement — even if a parent product uses JS heavily.
Why: CSS/JS fail for many real reasons (network, corporate proxies, extensions, CDN outages, browser bugs, users disabling JS). Core needs must still be met. Semantic HTML also underpins accessibility.
| Layer | Rule |
|---|---|
| HTML | Core journeys work with HTML alone (forms, navigation, content). Correct semantics; sensible document outline. |
| CSS | Enhance presentation. Avoid CSS-in-JS that leaves the page unstyled when JS fails. Prefer fault-tolerant CSS. |
| JavaScript | Enhance existing HTML/CSS that already provides the capability (e.g. autocomplete enhancing a native control). Feature-detect; treat JS as non-fault-tolerant. |
| SPA | Do not build the service as a single-page application that owns navigation in JS. Breaks assistive tech context, focus, history, and recovery from network errors. |
| Client frameworks | Should not use a client-side JS framework if the UI is mostly Design System components. If used: justify with user evidence; isolate components so failure is local; keep core tasks HTML-capable. |
| COTS / suppliers | Put progressive enhancement (and accessibility) into requirements and contracts. |
If a task truly cannot work without JS, must provide an alternative channel (phone, in-person, etc.) that meets the need.
- Use GOV.UK Frontend (current supported major) as the implementation of Design System styles/components — not deprecated stacks (Elements / Toolkit / old Template) for new work.
- Prefer Nunjucks macros (or equivalent maintained wrappers) over long-term copy-paste of HTML from the website.
- When building wrappers in another language: treat official
fixtures.jsonhtmlas the parity contract. Compare your output to fixtures; ignore known framework-only differences deliberately, do not “fix” fixtures to pass. - Initialise JS with
type="module"; include the supportedjs-enabled/govuk-frontend-supportedsnippet; callinitAll/createAllfor components you ship. - Import only the JS you need in production builds for performance, but ensure every interactive component you render is initialised.
- Respect browser support grades (A/B/C/X). Grade X (no
type="module", including IE) must still get usable HTML/CSS; Frontend JS will not run. - Keep CSS via the supported Sass/
@usepipeline (Dart Sass); do not treat precompiled CSS as the long-term customisation story if you need overrides. - Do not restyle GOV.UK primitives ad hoc (buttons, input borders, colour meanings).
- Serve over HTTPS with HSTS; do not hotlink assets from GOV.UK or other services (URLs change).
- Before upgrading Frontend: read releases and Design System “What’s new”; treat breaking changes as migration work with fixture re-checks.
- Prefer Stable Design System components/patterns.
- Trial (and experimental community work): may be used to learn, with clear awareness they can change; contribute research back; do not treat as frozen API.
- Do not ship unreleased Design System chrome from roadmaps/boards as if it were production guidance.
- Use styles for layout, typography, colour, images — look and feel like GOV.UK.
- Use components for reusable UI (inputs, navigation, tables, etc.).
- Use patterns for tasks (question pages, addresses, accounts, validation). Patterns compose components; they are not new low-level widgets.
- Read each component/pattern’s “when to use” / research notes before adapting.
- Be consistent, not uniform: same language and patterns where possible; adapt when evidence demands; share improvements back.
Must / should:
- Know why each question is asked; only ask what you need (question protocol).
- Never mark required fields with asterisks; mark optional fields with “(optional)” on label/legend.
- Question pages include back link, page heading, continue action (
novalidateon forms using Design System validation patterns). - Prefer one thing per page unless research supports combining.
- Do not use back link and breadcrumbs together.
- Allow “I do not know” / “I’m not sure” when valid.
- Do not re-ask for the same information in one journey; pre-populate or offer reuse.
- On errors: error summary at top of
main(below back link/breadcrumbs, aboveh1), plus field errors; same wording in both places; link to the right control (first errored field in a group). - Retain user-entered values after errors.
- Prefer plain text component options; treat HTML options as trusted/sanitised only.
- Follow GOV.UK style for GOV.UK services (plain English, clear error messages, clear reasons for questions).
- Content design is part of accessibility and completion rates — not decoration.
Should avoid creating new low-level components when Design System ones exist. If you must:
- Start from existing components/patterns and research.
- Meet accessibility and progressive enhancement bars.
- Share publicly (Service Standard point 13) when reusable.
- Add inset text / clear explanation when using something outside Design System norms so users and assessors understand risk.
Must:
- Threat-model early; maintain risk assessment through the lifecycle.
- Secure by Design / government cyber expectations; proportionate controls.
- Collect/process/store personal data lawfully and minimally; privacy is integral, not a bolt-on.
- Due diligence on third-party software and integrations.
- Protect sessions, secrets, and admin interfaces; never commit credentials.
- Cookies/similar tech: follow Service Manual rules; do not surprise users.
- Frontend hardening (e.g. CSP): allow the GOV.UK Frontend inline snippet via hash/nonce correctly; do not weaken CSP casually.
- Security processes must be usable — research them; avoid controls that push users into unsafe workarounds.
Should:
- Regular dependency updates and vulnerability testing.
- Separate asset hosting concerns thoughtfully (performance vs cookie scope) without breaking HTTPS assumptions.
Why: Slow or down services exclude carers, people on poor networks, and anyone with limited time windows. Heavy client JS harms lower-powered devices.
Should:
- Minimise JS/CSS weight; server-render HTML; enhance progressively.
- Measure frontend performance; test on low-end devices and constrained networks.
- Automate deployments with minimal downtime; keep prod-like pre-production environments.
- Monitor availability and user outcomes (including bias/ethics where automated decisions exist).
- QA is a team responsibility — automation helps but does not replace exploratory/human QA.
- Prefer efficient implementations (sustainability + performance align).
Must (reliability mindset): Have a proportionate incident response plan; do not design systems that only specialists can operate.
Apply the AI Playbook and Service Standard AI updates together.
Must:
- Only use AI when it meets an identified user need — not because it is novel.
- Understand limitations (no guaranteed accuracy; bias; hallucination; security threats such as prompt injection / data poisoning where relevant).
- Use AI lawfully, ethically, responsibly; engage legal, data protection, and assurance early.
- Keep meaningful human control at the right stages; high-risk decisions need human validation.
- Secure AI systems; do not leak personal data into models/prompts inappropriately.
- Ensure team access to expertise that understands the AI and its impact.
- Be open: label automated responses; use ATRS where required for algorithmic transparency.
Should:
- Prefer non-AI solutions when they are simpler and sufficient (Playbook: right tool for the job).
- Monitor drift, bias, and quality in live operation.
- Reuse cross-government approaches; collaborate rather than siloing models.
- Assess environmental cost of training/inference.
Consider: Design System roadmap items on AI-in-service patterns are exploratory — wait for published patterns where possible; research any interim design.
Should / must as marked:
- Must (default): New source code open and reusable under appropriate licences; explain exceptions (e.g. unannounced sensitive policy).
- Prefer open standards and common platforms (Pay, Notify, One Login, Design System, etc.) over bespoke.
- Publish useful non-personal, non-sensitive data openly when appropriate.
- Design for exit: avoid lock-in that prevents iteration (contracts, proprietary formats, framework traps).
- Manage dependencies deliberately; keep Frontend and critical libs current enough to receive fixes.
- Document decisions that affect assessors and future teams (especially exceptions to Design System or PE).
Roadmaps and GitHub org project boards (e.g. Design System team boards) show intent. They change.
Should:
- Watch Design System roadmap and govuk-frontend releases.
- Plan migrations (Sass module changes, new components, brand refreshes) rather than forking forever.
- Feed research back via Design System community channels when you learn something reusable.
Must not:
- Depend on unreleased components as if stable.
- Copy experimental GitHub discussion HTML into production without research and accessibility review.
- Identify the user task and relevant pattern.
- Compose components (macros/wrappers), not pasted markup.
- Ensure page template / chrome: skip link, phase banner if needed, header/footer, language if applicable.
- One
h1; back link or breadcrumbs. - Forms:
novalidate, labels/hints, optional marking, error summary pattern. - HTML-only success path; then CSS; then GOV.UK Frontend JS modules.
- Content in plain English; explain why you ask.
- Security headers and HTTPS assumptions intact.
- Check WCAG risks (name, role, value, focus, errors, contrast).
- Add or update tests (fixture parity for wrappers; journey tests for pages).
Flag as blocking if any of these are true:
- Core task requires JS/SPA navigation without an alternative.
- Custom component duplicates Design System without justification.
- Missing error summary/field errors or inaccessible error wiring.
- Focus styles removed; keyboard traps; missing names/labels.
- Personal data logged or exposed; secrets committed.
- Accessibility or security regressed for real-user release.
- AI feature lacks human oversight / user-need justification / transparency.
Flag as should-fix if: unnecessary client framework, oversized bundles, re-asking data, inconsistent GOV.UK content style, skipped research notes on a pattern deviation.
- Fix the wrapper/implementation, not the fixture.
- Re-read macro options and escaping behaviour.
- After Frontend upgrades, expect intentional HTML changes — update implementation to match new fixtures.
- Re-read the relevant Design System pattern/component page.
- Apply Service Standard points 1, 4, 5, 9, 13 and progressive enhancement.
- Choose the option that maximises successful completion for the widest set of users with the least lock-in.
- Record the assumption and what research/data would validate it.
Copy and mentally tick before finishing a change:
- User need and journey context understood (not org-chart scoped)
- Design System pattern/component used (or justified exception)
- Works with HTML only for the core task; no SPA navigation
- GOV.UK Frontend correctly integrated (CSS, assets,
type="moduleJS, init) - WCAG 2.2 AA risks addressed; errors and focus correct
- Privacy/security sensible; no secrets; HTTPS/HSTS posture preserved
- Content clear; only necessary questions; optional fields marked correctly
- Performance reasonable on low-end / poor network
- Monitoring/operability not made worse
- AI (if any): needed, supervised, transparent, lawful
- Open/reuse posture preserved; fixtures/tests updated
- Exceptions documented with rationale
When sources conflict, follow Authority and conflict resolution. When this file conflicts with those URLs, the URLs win — update this file in a later change.