Repository navigation
Decision index
Jump to a topic:
- Decision record
- Brand
- GOV.UK basis and handover
- Theming and component status
- Using the kit
- Layout and navigation
- Components
- Contribution and maintenance
| ID |
Decision |
Status |
|---|---|---|
| ADR‑001 | The site carries product-team decisions; the wiki indexes all decisions | ACCEPTED |
| ID |
Decision |
Status |
|---|---|---|
| IDR‑001 | The i.AI brand is a corporate brand and is not applied to product interfaces | SUPERSEDED |
| IDR‑002 | Products are branded either GOV.UK or a government department | SUPERSEDED |
| IDR‑003 | Brand is the product name, header, font, brand colour and logo | SUPERSEDED |
| IDR‑004 | The i.AI brand colour will be used in our products | ACCEPTED |
| IDR‑005 | Three brands: how each brand looks | ACCEPTED |
| IDR‑006 | Brand is the product name, header, service navigation, footer, typeface, brand colour and logo | ACCEPTED |
| ID |
Decision |
Status |
|---|---|---|
| ADR‑002 | Start with the GOV.UK Design System | ACCEPTED |
| ADR‑003 | Extend GOV.UK only where needed | ACCEPTED |
| ADR‑004 | Target GOV.UK Frontend v6.5.0 | ACCEPTED |
| ID |
Decision |
Status |
|---|---|---|
| ADR‑005 | Theme with tokens (CSS variables), not hardcoded values | ACCEPTED |
| ADR‑006 | Components are standard or experimental | ACCEPTED |
| ID |
Decision |
Status |
|---|---|---|
| ADR‑019 | The kit is called the i.AI Design Kit | ACCEPTED |
| ADR‑020 | We'll optimise the Design Kit for use by AI agents as well as humans | ACCEPTED, amended by ADR-001 |
| ADR‑021 | Agents read GitHub directly; no MCP for now | ACCEPTED |
| ADR‑022 | The kit is accessible by humans and AI | ACCEPTED |
| ADR‑023 | We'll optimise the Design Kit for designing in code, not Figma | ACCEPTED |
| ADR‑024 | We will target the three routes used in i.AI | ACCEPTED |
| IDR‑004 | Content principles for the kit | ACCEPTED |
| ID |
Decision |
Status |
|---|---|---|
| IDR‑007 | Horizontal layout option | ACCEPTED |
| IDR‑008 | Information density is solved per product through layout patterns | ACCEPTED |
| IDR‑009 | One thing per page in app-style products | TO DECIDE |
| IDR‑010 | External public page and internal app structure | ACCEPTED |
| ID |
Decision |
Status |
|---|---|---|
| IDR‑011 | Toggle: an accessible pattern with no disabled state | ACCEPTED |
| IDR‑012 | Card prominence and interactivity are independent axes | ACCEPTED |
| IDR‑013 | Clickable cards fill on hover | ACCEPTED |
| IDR‑014 | Card link treatment | ACCEPTED |
| IDR‑015 | Card icons are introduced in markup | ACCEPTED |
| IDR‑016 | Subtle variants of input components | ACCEPTED |
| IDR‑017 | Tertiary button built from existing styles | ACCEPTED |
Component library decisions repo
| ID |
Decision |
Status |
|---|---|---|
| ADR‑025 | We'll assume that the Design Kit will not have a dedicated team | ACCEPTED |
| ADR‑026 | Federated, high-trust contribution model | ACCEPTED |
Status: ACCEPTED · Date: 2 October 2026 · Amends ADR-020 · Source: Draft ADR-026
Context. Decisions were recorded in three places: the design-system repo, the component-library repo and a separate draft. Copying between them creates copies that drift apart.
Decision.
- The design kit site publishes the seven decisions that apply to product teams, at /principles/decision-record: IDR-001, ADR-002, ADR-003, ADR-013, ADR-020, ADR-023 and ADR-025. ADR-002, ADR-003, ADR-020 and ADR-025 merge other decisions; the site carries only its own part of each.
- The repo wiki indexes all decisions. Design-system decisions are listed with a summary and a link. Component-library decisions are linked only. Decisions in neither repo are written in full here.
- Both repos keep their own decision files.
Consequences. When a repo decision changes, its wiki entry needs updating. Agents reading the site see only the seven decisions and need pointing to the wiki and repos for the rest.
Open. Whether the repos keeping their own files has a review point.
Status: SUPERSEDED (IDR-004)
The i.AI brand is our corporate brand, used for things like our website, decks, communications and recruitment. It was designed primarily to advertise i.AI to potential hires and present us as a modern place to work.
We have different aims for our products. Namely, to be easy to use, accessible and trustworthy.
We will not use the i.AI brand to brand the products we build.
Status: SUPERSEDED (IDR-005)
Using GOV.UK or branded as a government department is best practice for building products inside the government. It has the benefit of trustworthiness and means we do not need to create a new brand identity for our products.
Products are branded as one of two options, depending on their audience:
- A government department, when the product is for a specific department's use. If it is not tied to a specific department, the department is i.AI and the generic header is used.
- GOV.UK, when the product is for use by the general public or across the public sector.
The department brand is the default. A product that is experimental or unsure starts here and can switch to a different department or GOV.UK later.
Most products start as department-branded and move to GOV.UK as they are rolled out more widely, rather than starting as GOV.UK.
This allows us to take advantage of using the GOV.UK Frontend
Status: SUPERSEDED (IDR-004)
(IDR-002)states that we will need products that are branded either full GOV.UK or as a government department.
We therefore need to know how to switch between the different brands in a way that enables us to use the same functionality to avoid having two design systems.
The Service Manual guidance on when your product is not in GOV.UK states that to use the GOV.UK Frontend when you are not GOV.UK your product must not:
- identify itself as being part of GOV.UK
- use the crown or GOV.UK logotype in the header
- use the GDS Transport typeface
- suggest that it’s an official UK government website if it’s not
- use the GOV.UK brand colours
Brand is the product name, header, font, brand colour and the logo. Changing these is enough to shift the two brands set out in IDR-002
This also allows us to use the GOV.UK Frontend for all our products.
Status: ACCEPTED (supersedes IDR-001)
The i.AI brand colour is the brand of our department.
We will use the i.AI brand to brand the products we build.
- I.AI products are branded differently to department products
- The pink is striking and needs to be managed in products - see IDR-006
Status: ACCEPTED · Date: 4 and 23 September 2026, aligned 2 October 2026 · Source: Draft ADR-018 Supersedes (IDR-002)
Context. Products sat on an implicit spectrum from close to GOV.UK to far from it, with no shared vocabulary. Experimental products carrying the GOV.UK brand create reputational risk.
Decision. Every product carries one of three brands. Each brand changes only the elements in IDR-002.
- GOV.UK: blue header with the crown, GDS Transport, green buttons, everything else standard.
- i.AI: light header with the i.AI logo, Inter, and pink as the single brand colour (the closest pink in the GOV.UK palette). Uses selected elements of the i.AI corporate brand (logo, typeface, colour) so products feel part of the corporate brand family, without copying ai.gov.uk exactly.
- Departmental: the GOV.UK generic header with the department's logo, black by default, recoloured to the department's colour on request.
All three brands run the same kit functionality and differ by theme only.
Rationale. GOV.UK Frontend's generic header is designed to be customised this way. One flexible template avoids building a frontend for every department. The i.AI logo works better on a light background.
Consequences.
- A theme variant is an extra step for switching between brands
- Components now need versioning to fit with all three themes - previously limited to generic header which was already made by GOV.UK
Open. How users respond to pink, which has had internal pushback. Whether i.AI products keep standard blue links and green buttons. Who decides which brand a new product carries.
IDR-006 — A product brand is it's product name, header, service navigation, footer, typeface, brand colour and logo
Status: ACCEPTED · Date: 6 October 2026 · Source: new; merges Draft ADR-019, Draft ADR-027, DS-003 and Draft IDR-013 (Supersedes IDR-003)
- Due to pink being added and new i.AI header, the service navigation needed a styling upgrade to fit with the brand.
- In order to protect against further components needing variants, we have limited the branding decision to only include service navigation
For the purposes of the Design Kit, a product brand consists of seven elements: the product name, header, service navigation, footer, typeface, brand colours and logo. Changing these is enough to move a product between the three brands. Nothing else counts as brand.
Typeface.
- i.AI-branded products use Inter, with the font stack Inter, Helvetica, Arial.
- GOV.UK-branded products on the GOV.UK domain use GDS Transport through GOV.UK Frontend defaults, with no overrides and no other fallback.
- Products not on the GOV.UK domain use GOV.UK Frontend's fallback stack (Helvetica, Arial).
Navigation. The service navigation is styled by brand. What it contains, and any further navigation such as a sidebar or a customised top bar, is tailored to each product. Wider templates are acceptable where there is a good reason, such as complex tables or maps.
Consequences.
- The header, service navigation and footer components each need a version for each brand.
- Inter adds a font download, and switching brand needs a layout check.
Open.
- Whether brand colour extends to links and buttons in i.AI-branded and departmental products.
- The GDS Transport and crown licensing position for civil servant tools outside a GOV.UK service domain.
- The typeface for departmental products.
Status: ACCEPTED · Date: 6 October 2026 · Published on the site as "We'll use an adapted version of the GOV.UK Design System" · Source: merges SITE-2, DS-004 and DS-005
Decision. Every product starts from the GOV.UK Design System: GOV.UK Frontend as the code basis, and its guidance and principles. We adapt it by adding the styles, components and patterns our products need (ADR-003).
Rationale. Some products must be branded GOV.UK, so using the GOV.UK Design System everywhere is simpler. GOV.UK Frontend was made for informational websites and forms used rarely by the public; our products are apps civil servants use repeatedly for complex tasks, so it needs extending. Building on GOV.UK lets us share components and fixes with other departments, and take theirs.
Status: ACCEPTED · Date: 6 October 2026 · Published on the site as "We'll only extend the GOV.UK Design System where necessary" · Source: merges SITE-3, DS-006, DS-007, Draft ADR-001, Draft ADR-002, Draft ADR-006, Draft ADR-007 and Draft ADR-025
Decision.
Add, don't change. We only add to the kit to meet a currently unmet need: use what exists; make something new only when you need to; consider contributing it back. Styles (colour, borders, typography) are the fixed base. New components are built from existing styles, and new patterns from existing components. Existing styles change only where they form part of a brand (IDR-002).
Record every departure. Departures from GOV.UK Frontend are recorded as answers to pain points, not starting places. For example, a product should not start with a two panel layout, but can use one if a linear flow is making the app less usable. Each departure is recorded against four fields:
- the GOV.UK pattern departed from
- what the product needed that the pattern did not provide
- what was built instead
- what would need to be true to promote it to a general pattern
Keep it reversible. Products must be able to stand alone as i.AI, be handed over as a GOV.UK product, or be handed to a department. Components wrap and layer GOV.UK Frontend rather than fork it: no markup changes, no class renames. Deleting every extension class returns valid stock GOV.UK markup with no further edits. This applies to components; layout and navigation are patterns built from stock components and are outside it.
Components with no GOV.UK equivalent (for example a toggle, card or chart) stay as they are when a product converts to full GOV.UK. Where another department has already built one, we copy its styles and JS into the kit rather than depend on that department's design system.
Rationale. A layered rule replaces a subjective "does it look like GOV.UK?" test with something checkable. Consistently recorded departures are the evidence base for future AI design patterns. Wrapping keeps standard markup, so a receiving team can strip the layer without a migration project.
Consequences.
- Brand-new styles should be rare and need a strong case.
- The kit becomes the central register of product departures. Recording them costs effort mid-build, when teams are least inclined.
- Handover must state which components have no GOV.UK equivalent; the receiving team inherits or replaces them. The card has no upstream layer to strip back to.
Status: ACCEPTED · Date: August 2026 · Source: Draft ADR-008
Decision. The kit targets GOV.UK Frontend v6.5.0, with automated tests (CL-0006) to flag when to bump versions.
Rationale. The kit extends version-bound class names and variables, and pinning keeps the benefit of GOV.UK's maintenance work.
Consequences. Products on earlier versions may need some refactoring. Which version each of the eight repos is on is still to be verified.
Open. Nothing enforces v6.5.0 yet: the packages accept govuk-frontend 6 or later and the kit site uses ^6.4.0. Pin a minimum of 6.5.0, or amend this decision to cover v6.
Status: ACCEPTED · Date: August 2026 · Source: Draft ADR-004
Decision. All visual values live in design tokens and CSS variables. No component carries a hardcoded visual value. GOV.UK Frontend's own component variables are not updated.
Rationale. Switching theme means only updating tokens, so brand decisions can change without rework. Leaving GOV.UK's variables alone avoids maintaining them.
Consequences. Every component build must be checked against this. GOV.UK Frontend uses the link-colour variable for more than links, which constrains theming i.AI-branded products.
Status: ACCEPTED · Date to confirm · Source: Draft ADR-029
Decision. Every component is standard or experimental.
- Standard: in the GOV.UK Design System, or a standard component in the real world that GOV.UK lacks (for example, the toggle). No label.
- Experimental: components we are less confident in (for example, an AI confidence score). Labelled.
Rationale. The label tells people and agents where to take care. Whether a component is proven matters more to a team than where it came from.
Open. How a component moves from experimental to standard. How a receiving department tells which components have no GOV.UK equivalent (ADR-003).
See docs/architecture/decisions/ in the component-library repo.
Status: ACCEPTED · Date: 4 September 2026 · Source: Draft ADR-023
Decision. The kit is named the i.AI Design Kit.
Rationale. "Design system" carries preconceptions, such as restricting which colours people can use. A different word gives room to make something new. The name can change later.
Consequences. Content must make clear the kit is for engineers too. The feedback channel is #iai-design-kit.
Status: ACCEPTED, amended by ADR-001 · Published on the site · Date: 29 September 2026, merged 6 October 2026 · Source: merges SITE-4 and Draft ADR-014
Decision. The Design Kit is optimised for both humans and AI agents, and is authored once for both. There is no separate agent-facing copy of components, tokens, guidance or decisions. Site content is written in pure markup, and agent skills are mainly about how to read it.
Rationale. AI helps small teams design in code and helps developers do design, but we do not want to build too much reliance on AI into our workflows. A hand-maintained agent copy drifts from the human one, and the copy agents read is the one nobody proofreads.
Consequences. Skills need to read site content reliably. The site is behind a login now and will be public in the long term. Under ADR-001, decisions are spread across the site, wiki and repos, but each still has one copy.
Status: ACCEPTED · Date: August 2026 · Source: Draft ADR-017
Decision. Agents are pointed directly to the kit content in GitHub, through skills. No MCP. No Figma MCP either, as the kit does not support Figma (ADR-023).
Rationale. An MCP would only point the agent to the same GitHub content. Reading GitHub directly works in more tools, and has been tested.
Consequences. Skills need building and linking with centralised skills work across i.AI.
Status: ACCEPTED · Date: 23 and 24 September 2026 · Source: Draft ADR-024
Decision. The kit always offers a non-AI route alongside the AI-assisted one. The AI-assisted route is a skill teams import into the tools they already use: it asks which brand the product carries (IDR-001), then generates a starting page. Components and patterns stay available directly on the site. Guidance is written for AI agents in general, tested with Claude but not specific to it.
Rationale. Teams want AI to get them to a starting point, then adjust it themselves. An AI-only route would exclude people who work differently.
Consequences. The current skill does not yet branch by brand. Skills must be maintained alongside the site.
Status: ACCEPTED · Published on the site · Date: 29 September 2026 · Source: SITE-5
Summary. The Design Kit is optimised for working in code. Figma is not supported. Designing in code lets us build, test and iterate faster, and maintaining a Figma version would need more resources than we have. Teams may still use Figma for visual exploration.
Status: ACCEPTED · Date: 4 September 2026 · Source: DS-012 (design-system repo)
Summary. The kit targets the three routes people use in i.AI:
- a designer prototyping in code, using an agent skill that reads the design kit
- an engineer starting a new product from the cookie cutter, using an agent setup that points to the design kit
- engineers adding components to an existing product
Figma and the GOV.UK Prototype Kit are not supported (ADR-023). The site's get-started pages match the routes: Design a prototype, Build a product interface, Update a product interface.
Status: ACCEPTED · Date: 23 September 2026 · Source: Draft IDR-016
Decision. Navigation labels fit on a single line. Icons are not used until genuinely needed. Where GOV.UK already provides guidance, the kit links to it rather than restating it.
Rationale. Single-line labels are easier to scan. Icons are often strong for the first item in a list and weak for the rest. The less guidance the kit writes, the less of it can become wrong.
Consequences. Agents need to follow links out to GOV.UK, so skills must be tested against linked content too.
Status: ACCEPTED · Date: August 2026 · Source: Draft IDR-009
Decision. When linear navigation complicates the view and pushes content below the fold, use the side-navigation variant of the service navigation, or the two-pane layouts used in our products.
Rationale. A repeated pain point, so it should be a pattern rather than re-solved per product:
- In Minute, the header, phase banner, service navigation, breadcrumb, title and toolbar pushed the main content below the fold; some users did not know they could scroll to actions.
- In Education, teachers needed context alongside tasks, which forced a two-pane view.
- In Extract, the planning document, map actions and up to 100 TPOs needed a horizontal layout.
Consequences. A linear flow stays the default and may be the best option; switch only where needed. The simplicity principle should be stated in the kit's principles.
Status: ACCEPTED · Date: 2 October 2026 · Source: Draft ADR-028
Decision. Stock GOV.UK spacing stays the default. Where density causes a real problem in a product, it is solved as an answer to that pain point (ADR-003), using the horizontal layout (IDR-005) and product-specific navigation (IDR-002).
Rationale. Changing spacing for every brand would change a non-brand style, which ADR-003 does not allow. The evidence (Minute, Consult, Education) is product-specific.
Consequences. GOV.UK-branded products stay visually identical to stock GOV.UK. Vertical spacing in complex tables still needs a pattern, with Consult as the test case.
Status: TO DECIDE · Raised: 24 August 2026, reopened 2 October 2026 · Source: Draft ADR-030
Context. One thing per page simplifies a flow for first-time users but loses context. In Extract, reviewing up to 100 TPOs one per page was unworkable. In Education, users needed lesson plans, conversation history and marking criteria together to answer questions.
Suggested owner. Design.
Status: ACCEPTED · Date: August 2026, scope confirmed October 2026 · Source: Draft IDR-012
Decision. Each product has a publicly accessible, static HTML sign-in page describing the app, with privacy policy, user guidance and accessibility pages. It uses the classic GOV.UK look, with the GDS header and footer, for every brand. This is a conscious exception to IDR-003. The app itself sits behind it.
Rationale. People without access can find out about the product and who to contact.
Consequences. The kit needs clear guidance, especially on the technical set-up.
Status: ACCEPTED · Date: August 2026 · Source: merges Draft IDR-002 and Draft IDR-003
Decision. The toggle is built on Kitty Giraudel's accessible toggle pattern (2021), with the Intelligence Community Design System (ICDS) as the closest precedent. It has no disabled state.
Rationale. GOV.UK Frontend has no toggle, and building one from scratch would re-solve solved accessibility problems. ICDS serves internal tools and is WCAG 2.2 AA tested; Giraudel's pattern is the well-documented underlying implementation. Disabled controls do not say why an option is unavailable and are poorly served by assistive technology; GOV.UK guidance is to omit the control or show static text with an explanation.
Consequences. Attribution is owed, and accessibility claims must be re-tested, not assumed. Teams needing to show an unavailable option must omit the toggle or show static text plus explanation; the guidance needs to travel with the component.
Status: ACCEPTED · Date: August 2026 · Source: Draft IDR-005
Decision. The card varies on two independent axes: prominence (visual weight) and interactivity (whether the whole card is clickable).
Rationale. Teams need high-prominence static cards and low-prominence clickable ones. Two switches cover every combination without a new named variant each time.
Consequences. Every visual property belongs to one axis only. The full combination matrix must be tested.
Status: ACCEPTED · Date: August 2026 · Source: Draft IDR-006
Decision. Clickable cards are white at rest and fill with ink on hover, reversing the text out.
Rationale. A full fill shows the whole card is the target. A border change would clash with the prominence axis (IDR-010).
Consequences. Reversed text and focus-over-fill must pass contrast; focus-over-fill is untested. Touch and active states are undefined. Icons must reverse with the text.
Status: ACCEPTED · Date: August 2026 · Source: Draft IDR-007
Decision. The heading link on a clickable card keeps its underline. Visited state is suppressed with govuk-link--no-visited-state in the markup.
Rationale. Relying on the border for interactivity would make it signal both axes (IDR-010). The stock modifier keeps the decision visible in markup and survives stripping at handover.
Consequences. Users cannot tell which cards they have visited: fine for navigation into an app, wrong for links to content. The guidance must travel with the component. Whether Layer 2's dotted visited underline applies here is undecided.
To check. Whether "Layer 2" still means anything now the old brand categories have gone.
Status: ACCEPTED · Date: August 2026 · Source: Draft IDR-008
Decision. The card icon is an optional slot filled with inline SVG in the markup.
Rationale. Inline SVG inherits currentColor, so it reverses on hover without extra CSS, and the card does not become an icon system by accident.
Consequences. Each team supplies its own SVG, so icons will vary until a kit icon set exists. Accessible naming or hiding sits with the consuming team.
Status: ACCEPTED · Date: August 2026, condition added October 2026 · Source: Draft IDR-010
Decision. Input components have subtle variants, built from existing GOV.UK styles (ADR-003), for actions to be found when needed rather than not to be missed.
Rationale. GOV.UK was designed for infrequent forms where nothing should be missed. Our apps are used repeatedly, with actions not needed on every visit, such as Minute's "change data retention" setting.
Consequences. The site must explain when to use the subtle versions.
Status: ACCEPTED · Date: 7 September 2026 · Source: Draft IDR-014
Decision. Where a quieter action is needed, use a smaller, subtler tertiary button built from existing GOV.UK styles, rather than restyling the primary and secondary buttons.
Rationale. It extends rather than changes GOV.UK (ADR-003), and fits inside control bars and editors where a full button is too loud.
Consequences. A tertiary button sits visually close to tags, so the "tag looks like a button" problem still needs solving. Contrast has not been tested.
Status: ACCEPTED · Published on the site · Date: 29 September 2026, merged 6 October 2026 · Source: merges SITE-7 and DS-013
Summary. The Design Kit will not have a dedicated team. Supporting, maintaining and contributing to it is shared across teams, through a Slack channel for advice and contribution, a pull request system, and contribution guides that help people get as far as they can without help. ADR-026 holds the detail.
Status: ACCEPTED · Date: 7 September 2026, updated 2 October 2026 · Source: Draft ADR-021
Decision. Anyone can contribute.
- Check the kit and use what exists.
- If something is new and viable (for example, needed by two or more teams), raise a pull request to the component-library repo, using its template. If unsure, build it locally and share it in #iai-design-kit.
- Post a short heads-up in #iai-design-kit before raising a pull request. This is a sense check, not a sign-off.
- Pull requests are reviewed asynchronously for maintainability, accessibility and design; all three must approve. One person can cover more than one.
- Disputes go to the Head of Profession.
- A small part-time core team merges, releases and announces contributions, and can take over rework.
- Contributors use their own version until the kit version is published.
- Rejected components are recorded with the reason.
- Every 2 weeks, product repos are checked for local components worth adding.
- Every quarter, a named design person and frontend person spend time on kit debt, including promoting experimental components to standard (ADR-006).
Rationale. Trades process certainty for delivery speed, and gatekeeping for agency. Pull requests keep code, design and accessibility comments in one place. The model can be tightened if quality problems appear.
Consequences. Errors are harder to undo in a shared kit, so guides and accessibility standards must be clear. People less familiar with Git get pairing and training.
Open. Who is in the core team. Named reviewers for each perspective. The review deadline. Who writes the decision record entry for an accepted contribution. Graduation criteria for local components.
| Item | Status | Suggested owner |
|---|---|---|
| IDR-007 — One thing per page in app-style products | To decide | Design |
| ADR-011 — Does the frontend package bundle GOV.UK Frontend? | To decide | Component library engineers |
| ADR-014 — Which frameworks the component library supports | To decide | Component library engineers |
| ADR-015 — Are i.AI projects built in Astro? | To confirm | Engineering |
| ADR-008 — Does the copy-and-paste HTML route still apply? | To confirm | Engineering |
| ADR-004 — Pin GOV.UK Frontend at a minimum of 6.5.0, or allow any v6? | Open | Component library engineers |
| ADR-017 — Which class prefix i.AI additions use | To decide | Component library engineers |
| ADR-006 — Date standard and experimental statuses were agreed | To confirm | Design |
| IDR-012 — Whether "Layer 2" still means anything | To check | Design |