+
+ 3763 - Percentage width expands open state too much
+
+ When a Dropdown (or DatePicker) is given a percentage width, the closed input
+ sizes correctly, but the open menu expands far past the parent and the viewport.
+ The percentage is passed straight to the Popover container, where it no longer
+ resolves against the Dropdown's parent.
+
+
+ Expected: the open width should match the closed width. Open each control below
+ and compare the open menu width to the dashed parent box.
+
+
+
+
+
+
+ Dropdown with width="100%"
+
+
+ The dropdown should be exactly as wide as the 320px dashed box, both closed and
+ open. Buggy behaviour: the open menu blows past the box.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Dropdown with width="50%"
+
+
+ Any percentage triggers the bug, not just 100%. The closed input is half the
+ box; the open menu should match it.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ DatePicker with width="100%"
+
+
+ Reported by Vidit: the same percentage-width problem affects the DatePicker.
+ The open calendar should not exceed the box width.
+
+
+
+
+
+
+
+
+
+
+
+ DatePicker with width="50%"
+
+
+ Case from Benji: with a narrow percentage the input is much smaller than the
+ calendar's natural width, so the open calendar cannot match the input and
+ overflows the box. Expected: the open calendar should not exceed the maximum
+ width, not shrink to the tiny input.
+
+
+
+
+
+
+
+
+
+
+
+ DatePicker with width="100%" in a wide container
+
+
+ Opposite case: the input is far wider than the calendar's natural width.
+ Expected: the open calendar stays at its natural width (left aligned under the
+ input), it should not stretch to fill the wide input.
+
+
+
+
+
+
+
+
+
+
+
+ DatePicker with an invalid width
+
+
+ The width "5 0%" (note the stray space) is not a valid CSS dimension. Open the
+ browser console: the DatePicker should log an error explaining the width is
+ invalid, instead of failing silently.
+
+
+
+
+
+
+
+
+
+
{method.name}()
+
+
+ {method.description &&
{method.description}
}
+
+
{method.signature}{method.returnType ? `: ${method.returnType}` : ""}
+
+
+
+ {method.params.map((param) => (
+
+
+ {param.name}
+ {param.required && (
+
+ )}
+
+
+ {param.type}
+ {param.values && param.values.length > 0 && (
+ {param.values.join(" | ")}
+ )}
+
+ {param.description && (
+
+ {param.description}
+
+ )}
+
+
+
+ {section.pages.map((page) => (
+
+ ))}
+
+
+ );
+ };
+
const primaryContent = (
<>
{/* Back to parent menu */}
@@ -48,50 +77,7 @@ export function GetStartedSubMenu({
- {/* Top-level pages */}
- {items.topPages.map((page) => (
-
- ))}
-
- {/* Grouped sections */}
-
- {items.groups.map((group) => {
- const containsCurrentPage = group.pages.some((p) => p.url === currentUrl);
-
- const handleGroupClickCapture = () => {
- if (!isOpen && onExpandMenu) {
- onExpandMenu();
- }
- };
-
- return (
-
-
- {group.pages.map((page) => (
-
- ))}
-
-
- );
- })}
-
+
+
+ | Tool |
+ How it works |
+ What it gives your AI |
+
+
+
+
+ | GoA Design System MCP |
+ Lookup tool. Your AI calls it on demand. |
+ Component APIs, examples, and guidance, like asking a reference librarian |
+
+
+ | Skills |
+ Instructions that load when the work matches. |
+ Layered instructions for using the Design System in your work, like a playbook for the work at hand |
+
+
+ | MD files |
+ Static reference. Pasted upfront, stays in your AI's session. |
+ The full Design System reference, like a textbook on the desk |
+
+
+ | Figma MCP |
+ Lookup tool. Your AI calls it on demand. |
+ Read a design in Figma to get the components, variables, and specs, like lifting measurements off a blueprint |
+
+
+
+
+
+
+ All tools read from the same content this site renders, so answers stay consistent no matter which one you use.
+
+
+GoA Design System MCP
+Your AI pulls live Design System knowledge as it builds, so it uses the right components, the right props, and real examples instead of guessing.
+View more
+
+Skills
+Plain Markdown instruction files give your AI a workflow to follow when the work matches, so it builds a GoA service with the right structure, templates, and patterns from the start.
+View more
+
+
+ MD files
+
+
+Useful when you want to give your AI broad Design System context, include the reference in a project, or reach for the content offline.
+How to access it: Per-framework downloadable bundles (React, Angular, Web Components).
+
+Figma MCP
+Built and maintained by Figma. Pair it with the GoA Design System MCP when work spans design and code, so your AI can bridge Figma designs to real coded components from the Design System.
+How to access it: Figma's guide to the MCP server
+
+
diff --git a/docs/src/content/get-started/ai-tools-and-resources/goa-design-system-mcp.mdx b/docs/src/content/get-started/ai-tools-and-resources/goa-design-system-mcp.mdx
new file mode 100644
index 0000000000..f05e477c8e
--- /dev/null
+++ b/docs/src/content/get-started/ai-tools-and-resources/goa-design-system-mcp.mdx
@@ -0,0 +1,253 @@
+---
+id: ai-tools-and-resources/goa-design-system-mcp
+title: GoA Design System MCP
+navLabel: Design System MCP
+description: A live lookup tool your AI uses for component APIs, examples, and guidance
+section: ai-tools-and-resources
+order: 2
+status: published
+---
+import DropInCallout from "../../../components/DropInCallout.astro";
+import { CodeSnippet } from "../../../components/CodeSnippet";
+import { CodeCopy } from "../../../components/CodeCopy";
+import { withBase } from "@/lib/base-url";
+
+GoA Design System MCP
+The live lookup tool your AI calls when it needs Design System component APIs, examples, or guidance.
+
+
+
+
+View tool-specific setup
+
+
+ The MCP is one tool in a larger AI toolset. For the overview of all available AI tools and how they fit together, see AI tools and resources.
+
+
+What's included
+
+Everything the MCP returns comes from the same content this site renders.
+
+
+
+
+
+ | Type |
+ What's in it |
+
+
+
+
+ | Components |
+ The full GoA component library with props, variants, and accessibility notes. React, Angular, and Web Components. |
+
+
+ | Examples |
+ Workspace and Public form product types, page patterns, section patterns, and smaller task examples. |
+
+
+ | Guidance |
+ Do's, don'ts, and tips that apply across components. Accessibility grounded in WCAG 2.2 AA. |
+
+
+
+
+
+What can you ask?
+
+Ask your AI in plain language. It calls the MCP when a component, example, or guidance answer fits the request.
+
+
+
+
+
+ | About a component |
+
+
+
+
+ |
+
+ "What props does the Table component have?"
+
+
+ |
+
+
+ |
+
+ "How does FormItem handle error states?"
+
+
+ |
+
+
+ |
+
+ "Which GoA component should I use for a card layout?"
+
+
+ |
+
+
+
+
+
+
+
+
+
+ | For an example or pattern |
+
+
+
+
+ |
+
+ "Find dashboard examples in the workspace product type"
+
+
+ |
+
+
+ |
+
+ "Show me React examples for a question page"
+
+
+ |
+
+
+ |
+
+ "What's a good example of a filter bar?"
+
+
+ |
+
+
+
+
+
+
+
+
+
+ | For guidance, do's, and don'ts |
+
+
+
+
+ |
+
+ "What's the guidance for labelling buttons?"
+
+
+ |
+
+
+ |
+
+ "Show me the do's and don'ts for dropdowns"
+
+
+ |
+
+
+ |
+
+ "What accessibility guidance applies to forms?"
+
+
+ |
+
+
+
+
+
+Setup
+
+Find your AI tool below to connect it. There's nothing to install.
+
+
+ To verify your setup, restart your AI tool and ask "Look up the GoA Button component." You should get a response covering Button's props, variants, and usage.
+
+
+Claude Code (CLI)
+
+View Claude Code's MCP documentation
+
+The fastest path is the claude mcp add command:
+
+
+
+Claude Desktop
+
+View Claude Desktop's MCP setup guide
+
+Claude Desktop only supports local (stdio) MCP servers, so connect through the mcp-remote bridge. Edit the config file at:
+
+
+ - Mac:
~/Library/Application Support/Claude/claude_desktop_config.json
+ - Windows:
%APPDATA%\Claude\claude_desktop_config.json
+
+
+
+
+Cursor
+
+View Cursor's MCP documentation
+
+Cursor supports remote HTTP MCP servers directly. Open Settings > Tools & MCP to add a server, or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project:
+
+
+
+ChatGPT
+
+View ChatGPT's MCP connectors guide
+
+Custom apps are in beta and require a ChatGPT Plus or Pro subscription.
+
+
+ - In ChatGPT, open Settings > Apps > Advanced settings and turn on Developer mode.
+ - Select Add app. A New App form opens.
+ - Enter a Name (for example, "GoA Design System").
+ - Under Connection, select Server URL and paste the MCP endpoint URL:
+ - Set Authentication to None.
+ - Check I understand and want to continue to acknowledge the risk warning.
+ - Save.
+
+
+
+ Using a different AI tool? If it supports remote MCP servers, paste the MCP endpoint URL into its config. For stdio-only tools, bridge through npx mcp-remote <URL>. View the list of MCP-compatible clients
+
+
+
diff --git a/docs/src/content/get-started/ai-tools-and-resources/skills.mdx b/docs/src/content/get-started/ai-tools-and-resources/skills.mdx
new file mode 100644
index 0000000000..f9fde561da
--- /dev/null
+++ b/docs/src/content/get-started/ai-tools-and-resources/skills.mdx
@@ -0,0 +1,50 @@
+---
+id: ai-tools-and-resources/skills
+title: Skills
+navLabel: Skills
+description: Plain Markdown instruction files that give your AI a workflow to follow, for building GoA services
+section: ai-tools-and-resources
+order: 3
+status: published
+---
+import DropInCallout from "../../../components/DropInCallout.astro";
+import { CodeSnippet } from "../../../components/CodeSnippet";
+import { withBase } from "@/lib/base-url";
+
+Skills
+Plain Markdown instruction files give your AI a workflow to follow when the work matches. They follow the open SKILL.md standard, so the same files work across Claude Code, Cursor, Copilot, and more.
+
+
+ Skills are one tool in a larger AI toolset. For the overview of all available AI tools and how they fit together, see AI tools and resources.
+
+
+Available skills
+
+using-goa-design-system
+This skill identifies the right product type, page and section templates, and components for what you're building. Describe what you're working on in plain language (a public form or a case-management tool, for example), and it pulls the relevant structure and live component specs from the MCP.
+It loads when you're scoping or building a screen, page, or feature, so your AI follows the Design System's structure from the start rather than guessing.
+How to add it:
+
+View on GitHub
+
+content-design
+This skill writes user-facing copy tailored to its reader (a citizen or a worker) because the same message requires a different approach for each audience.
+It loads when you're working on the words in a service: labels, guidance, errors, empty states, and notifications.
+How to add it:
+
+View on GitHub
+
+How they work
+Each skill is a folder with a SKILL.md file plus any supporting notes. Your AI reads the short description at startup and loads the full instructions only when your request matches, so they add capability without crowding the context.
+Because they follow the open Agent Skills standard, the same files work in Claude Code, Cursor, GitHub Copilot, and other tools that read the format.
+
+Updates
+Skills track the dev branch of the GoA Design System repository. To keep them current, run:
+
+To update automatically, add npx skills update -g -y to a SessionStart hook in your AI tool and they refresh every session. You'll only get an update when a skill itself changes, not every time something else in the repo changes.
+
+
+ Using a tool without the skills CLI? Clone a skill folder from the skills directory into your tool's skills folder, for example ~/.claude/skills, .cursor/skills, or .github/skills.
+
+
+
diff --git a/docs/src/content/get-started/contribute.mdx b/docs/src/content/get-started/contribute.mdx
index 8e6f4e0437..ea77f0e1e9 100644
--- a/docs/src/content/get-started/contribute.mdx
+++ b/docs/src/content/get-started/contribute.mdx
@@ -2,8 +2,8 @@
id: contribute
title: Contribute
description: How to contribute to the GoA Design System
-section: appendix
-order: 2
+section: contribute
+order: 1
status: published
---
import { withBase } from "@/lib/base-url";
diff --git a/docs/src/content/get-started/out-of-support.mdx b/docs/src/content/get-started/out-of-support.mdx
index fa61fea200..ab9e254813 100644
--- a/docs/src/content/get-started/out-of-support.mdx
+++ b/docs/src/content/get-started/out-of-support.mdx
@@ -2,8 +2,8 @@
id: out-of-support
title: Out of support versions
description: Design System versions that are no longer supported
-section: appendix
-order: 3
+section: out-of-support
+order: 1
status: published
---
import { withBase } from "@/lib/base-url";
diff --git a/docs/src/content/get-started/qa-testing.mdx b/docs/src/content/get-started/qa-testing.mdx
index edb2d726e1..df80b892a3 100644
--- a/docs/src/content/get-started/qa-testing.mdx
+++ b/docs/src/content/get-started/qa-testing.mdx
@@ -2,7 +2,7 @@
id: qa-testing
title: QA testing
description: Testing process for Design System components
-section: appendix
+section: qa-testing
order: 1
status: published
---
diff --git a/docs/src/content/get-started/roadmap.mdx b/docs/src/content/get-started/roadmap.mdx
index 0672ebdd37..f7743071f5 100644
--- a/docs/src/content/get-started/roadmap.mdx
+++ b/docs/src/content/get-started/roadmap.mdx
@@ -16,12 +16,12 @@ status: published
-Now
-Focus: Drive DS 2.0 adoption momentum, protect post-launch stability, and prove DS 2.0 helps teams move faster through prescriptive guidance and examples.
+Q1 (April - June)
+Focus: Drive design system adoption momentum, enable AI-assisted workflows through the design system MCP, and make an informed decision on Vue support.
-DS 2.0 adoption and satisfaction measurement
-Objective: Establish reliable DS 2.0 adoption tracking and reporting, and pair it with satisfaction signals from designers, developers, and end users to understand whether DS 2.0 is improving service outcomes as teams upgrade.
-Benefit: Enables accurate progress reporting and provides evidence that DS 2.0 is improving usability, accessibility, and experience quality, not only adoption.
+Design system adoption and satisfaction measurement
+Objective: Establish reliable design system adoption tracking and reporting, and pair it with satisfaction signals from designers, developers, and end users to understand whether the updated design system is improving service outcomes as teams upgrade.
+Benefit: Enables accurate progress reporting and provides evidence that the updated design system is improving usability, accessibility, and experience quality, not only adoption.
Examples:
- Create a mechanism to reliably collect and report adoption rate
@@ -31,16 +31,26 @@ status: published
Product acceleration enablement
-Objective: Provide prescriptive guidance and resources that help teams get to screens, prototypes, and working experiences faster using DS 2.0.
+Objective: Provide prescriptive guidance and resources that help teams get to screens, prototypes, and working experiences faster using the updated design system.
Benefit: Reduces time to first screens and improves consistency by helping teams start from proven patterns instead of building from scratch.
Examples:
- - Create resources that show how to quickly prototype with DS 2.0 components and examples
+ - Create resources that show how to quickly prototype with design system components and examples
- Provide contextual starting points for teams using Public form and Workspace templates
- - Pilot DS 2.0 with teams to generate strong examples to share
+ - Pilot the updated design system with teams to generate strong examples to share
- Create and publish migration success stories
+Vue support decision
+Objective: Explore and define the minimum work required to confidently state the design system officially supports Vue, including scope, constraints, and support model.
+Benefit: Prevents unclear commitments and reduces strategic risk by enabling an informed investment decision aligned to organizational needs.
+Examples:
+
+ - Define what "official Vue support" means
+ - Outline the minimum supportable scope
+ - Identify implications for documentation, maintenance, testing, and support
+
+
Design system MCP
Objective: Stand up the design system Model Context Protocol (MCP) capability so AI tools and platforms can reliably access design system guidance, components, patterns, and standards.
Benefit: Helps teams generate more consistent, standards-aligned front-ends by making trusted design system context available directly in AI-assisted workflows.
@@ -52,31 +62,49 @@ status: published
Document recommended workflows for teams
-Vue support decision
-Objective: Explore and define the minimum work required to confidently state DS 2.0 officially supports Vue, including scope, constraints, and support model.
-Benefit: Prevents unclear commitments and reduces strategic risk by enabling an informed investment decision aligned to organizational needs.
+
+
+Q2 (July - September)
+Focus: Improve the core Public form and Workspace experience and execute on the chosen Vue direction.
+
+
+Objective: Build on the existing public form offering to make it faster to implement and easier to use, while preserving the flexibility product teams need.
+Benefit: Unlocks downstream public form capability work and reduces the effort required for teams to build consistent, high-quality public-facing services.
Examples:
- - Define what "official Vue support" means
- - Outline the minimum supportable scope
- - Identify implications for documentation, maintenance, testing, and support
+ - Identify gaps and opportunities in the current public form offering
+ - Determine what needs to be built, adapted, or improved to better support the public form use case
+ - Deliver improvements so teams can build on a more complete and supportable foundation
-
-
-Next
-Focus: Improve the core Public form and Workspace experience, mature reusable patterns and examples, reduce adoption friction through better packaging, and execute on the chosen Vue direction.
-
Public form and Workspace capability improvements
Objective: Enhance key Public form and Workspace capabilities based on adoption needs and workflow requirements.
-Benefit: Improves feature sets and reduces the need for custom one-off solutions by making common workflows easier to implement with DS 2.0.
-Example:
+Benefit: Improves feature sets and reduces the need for custom one-off solutions by making common workflows easier to implement with the updated design system.
+Examples:
- Build the review, revise, resubmit feature
+ - Navigation pattern for multi-step Workspace workflows
+ - Comments component for Workspace
+ - Combined Public form and Workspace playground
+Vue follow-through
+Objective: Based on Vue discovery, either implement formal Vue support or clearly position Angular and React as the recommended approach for teams using AI-assisted workflows.
+Benefit: Provides clear direction to product teams and reduces uncertainty, enabling progress on a supported path while keeping support sustainable for the design system team.
+Examples:
+
+ - Publish Vue support guidance and expectations
+ - Implement agreed scope if approved
+ - Publish recommended alternatives if Vue support is not pursued
+
+
+
+
+Q3 (October - December)
+Focus: Mature reusable patterns and examples, and reduce adoption friction through better library packaging and tech stack upgrades.
+
Examples and pattern maturity
-Objective: Expand and refine examples and position them as adaptable reusable patterns that teams can apply with confidence.
+Objective: Expand and refine examples and position them as adaptable reusable assets that teams can apply with confidence.
Benefit: Improves self-serve success and product consistency, reducing implementation variance and support demand over time.
Examples:
@@ -93,20 +121,10 @@ status: published
- Update to Svelte 5
-Vue follow-through
-Objective: Based on Vue discovery, either implement formal Vue support or clearly position Angular and React as the recommended approach for teams using AI-assisted workflows.
-Benefit: Provides clear direction to product teams and reduces uncertainty, enabling progress on a supported path while keeping support sustainable for the design system team.
-Examples:
-
- - Publish Vue support guidance and expectations
- - Implement agreed scope if approved
- - Publish recommended alternatives if Vue support is not pursued
-
-
-Later
-Focus: Support DS 2.0 version updates and improve documentation and communications quality to support scaling and sustainability.
+Q4 (January - March)
+Focus: Support design system version updates and improve documentation and communications quality to support scaling and sustainability.
Documentation and communications improvements
Objective: Improve how teams access and understand design system guidance, and communicate design system value areas like accessibility more clearly.
@@ -117,8 +135,8 @@ status: published
Articulate accessibility work more clearly (what is covered and how it supports teams)
-Targeted capacity support for DS 2.0 version updates
-Objective: Provide targeted design system team capacity to help remaining DS 1.x product teams complete the DS 2.0 version update.
+Targeted capacity support for design system version updates
+Objective: Provide targeted design system team capacity to help remaining product teams complete the design system version update.
Benefit: Accelerates adoption progress and unblocks teams facing more difficult migrations, supporting adoption targets while keeping support sustainable through a focus on teams most in need.
Example:
diff --git a/docs/src/layouts/BaseLayout.astro b/docs/src/layouts/BaseLayout.astro
index 0f9905158d..aaf0b4fe02 100644
--- a/docs/src/layouts/BaseLayout.astro
+++ b/docs/src/layouts/BaseLayout.astro
@@ -107,12 +107,24 @@ const ogUrl = new URL(withBase(Astro.url.pathname), Astro.site).href;
html {
color-scheme: light;
+ /* Match the page's grey wrapper so the scroll overflow / overscroll
+ area (visible on elastic scroll) blends instead of showing white.
+ Same token as .layout-wrapper, so it matches in light/dark/forced-dark. */
+ background: var(--goa-color-greyscale-50);
}
html[data-theme="dark"] {
color-scheme: dark;
}
+ /* Below 624px the layouts flip the page wrapper to white, so match the
+ overscroll area there too instead of leaving it grey. */
+ @media (max-width: 623px) {
+ html {
+ background: var(--goa-color-greyscale-white);
+ }
+ }
+
body {
font: var(--goa-typography-body-m);
color: var(--goa-color-text-default);
diff --git a/docs/src/layouts/PreviewLayout.astro b/docs/src/layouts/PreviewLayout.astro
index 112c4a3468..f6b2a5f064 100644
--- a/docs/src/layouts/PreviewLayout.astro
+++ b/docs/src/layouts/PreviewLayout.astro
@@ -48,7 +48,7 @@ const resolvedBackUrl = withBase(backUrl);
-
+