+
+ 3602 FileUploadInput and FileUploadCard Improvements
+ +
+ @for (f of smallFiles; track f.id) {
+
+
+
+ @for (f of largeFiles; track f.id) {
+
diff --git a/apps/prs/angular/src/routes/bugs/3602/bug3602.component.ts b/apps/prs/angular/src/routes/bugs/3602/bug3602.component.ts
new file mode 100644
index 0000000000..c88e1ae6b4
--- /dev/null
+++ b/apps/prs/angular/src/routes/bugs/3602/bug3602.component.ts
@@ -0,0 +1,76 @@
+import { Component } from "@angular/core";
+import { CommonModule } from "@angular/common";
+import {
+ GoabFileUploadInputOnSelectFileDetail,
+ GoabFileUploadOnDeleteDetail,
+} from "@abgov/ui-components-common";
+import {
+ GoabFileUploadCard,
+ GoabFileUploadInput,
+ GoabFormItem,
+} from "@abgov/angular-components";
+
+type UploadedFile = {
+ id: string;
+ filename: string;
+ size: number;
+ type?: string;
+ progress: number;
+};
+
+@Component({
+ standalone: true,
+ selector: "abgov-bug3602",
+ templateUrl: "./bug3602.component.html",
+ imports: [CommonModule, GoabFileUploadInput, GoabFileUploadCard, GoabFormItem],
+})
+export class Bug3602Component {
+ smallFiles: UploadedFile[] = [];
+ largeFiles: UploadedFile[] = [];
+
+ onSmallFileSelect(detail: GoabFileUploadInputOnSelectFileDetail) {
+ const file = detail.file;
+ this.smallFiles = [
+ ...this.smallFiles,
+ {
+ id: `${file.name}-${Date.now()}`,
+ filename: file.name,
+ size: file.size,
+ type: file.type,
+ progress: -1,
+ },
+ ];
+ }
+
+ onLargeFileSelect(detail: GoabFileUploadInputOnSelectFileDetail) {
+ const file = detail.file;
+ this.largeFiles = [
+ ...this.largeFiles,
+ {
+ id: `${file.name}-${Date.now()}`,
+ filename: file.name,
+ size: file.size,
+ type: file.type,
+ progress: -1,
+ },
+ ];
+ }
+
+ private removeFirstMatchingFile(files: UploadedFile[], id: string): UploadedFile[] {
+ const index = files.findIndex((f) => f.id === id);
+ if (index === -1) {
+ return files;
+ }
+ return [...files.slice(0, index), ...files.slice(index + 1)];
+ }
+
+ onSmallFileDelete(detail: GoabFileUploadOnDeleteDetail, id: string) {
+ console.log("Deleting file with id:", id);
+ this.smallFiles = this.removeFirstMatchingFile(this.smallFiles, id);
+ }
+
+ onLargeFileDelete(detail: GoabFileUploadOnDeleteDetail, id: string) {
+ console.log("Deleting file with id:", id);
+ this.largeFiles = this.removeFirstMatchingFile(this.largeFiles, id);
+ }
+}
diff --git a/apps/prs/angular/src/routes/bugs/3602/bug3602.route.json b/apps/prs/angular/src/routes/bugs/3602/bug3602.route.json
new file mode 100644
index 0000000000..bfbd38665a
--- /dev/null
+++ b/apps/prs/angular/src/routes/bugs/3602/bug3602.route.json
@@ -0,0 +1,6 @@
+{
+ "title": "FileUploadInput and FileUploadCard Improvements",
+ "path": "bugs/3602",
+ "id": "3602",
+ "type": "bug"
+}
diff --git a/apps/prs/angular/src/routes/bugs/3605/bug3605.component.html b/apps/prs/angular/src/routes/bugs/3605/bug3605.component.html
new file mode 100644
index 0000000000..0a11c5877d
--- /dev/null
+++ b/apps/prs/angular/src/routes/bugs/3605/bug3605.component.html
@@ -0,0 +1,447 @@
+
+ Issue 3605
+
+ Use
+
+
+
+
+ View on GitHub
+
+
+
+
+
+ For every section: Tab should show the focus ring with the correct gap/offset.
+ Click should not leave a lingering ring. Mouse-down (
+
+
+ MicrositeHeader
+ Tab through the links inside the header. Click any link.
+
+
+
+ Chip and FilterChip
+ Chip (deprecated)
+
+
+
+ FilterChip
+
+
+
+
+
+ Plain link reset
+ Unstyled anchors pick up the global reset from
+
+
+
+
+ TextArea error state
+
+ Tab into the error text area. Click into it. The focus-within container pattern
+ applies on focus, which is correct for text inputs.
+
+
+
+
+ Button
+
+ Click and Tab each variant. Watch for lingering rings after mouse-up.
+
+
+ Default
+
+ Primary
+ Secondary
+ Tertiary
+
+
+ Destructive
+
+ Primary destructive
+ Secondary destructive
+ Tertiary destructive
+
+
+ Inverse (on dark bg)
+
+
+
+ Checkbox
+ Tab to each. Click each. No ring on mouse click.
+
+
+
+
+
+
+ 7. Link — outer-container ring gated by JS modality check
+
+
+ Ring sits on the outer container so it wraps icon + text together. The component
+ listens for
+
+ Plain links
+
+ First link
+ Second link
+ Third link
+
+
+ Links with leading icons
+
+ Download file
+ Learn more
+ Open in new tab
+
+
+ Links with trailing icons
+
+ Continue
+ See more
+ External resource
+
+
+ Links with both icons
+
+ Download and continue
+
+
+
+
+ Notification
+
+ Slotted anchors in notifications now use focus-visible. Keyboard only.
+
+
+
+ Info notification with a link inside.
+
+
+
+
+
+ 9. Tooltip —
+
+ Previously mouse-clicking the tooltip trigger revealed the tooltip. Now hover for mouse,
+ keyboard focus for keyboard.
+
+
+
+ Hover or Tab me
+
+
+
+
+
+
+ 10. Details —
+
+ Previously clicking the summary left a hover-ish style. Now click just toggles open;
+ keyboard focus shows the focused look.
+
+
+ Content inside the details component.
+
+
+
+
+
+ 11. DataGrid — realistic table usage
+
+
+ Typical pattern:
+
+
+
+
+ Name
+ Role
+ Status
+ Actions
+
+
+
+
+ Alice Johnson
+ Developer
+ View
+
+ Bob Smith
+ Designer
+ View
+
+ Carol White
+ Manager
+ View
+
+ David Brown
+ Analyst
+ View
+
+
+
+
+ DataGrid around a table with row checkboxes
+
+ Adds a select-all checkbox to the header row and per-row checkboxes. When focus
+ lands on a cell whose only focusable child is the checkbox, focus delegates to
+ the checkbox itself. The corner cells should still show the rounded focus
+ treatment.
+
+
+
+
+
+ Name
+ Role
+ Status
+ Actions
+
+
+
+
+ Alice Johnson
+ Developer
+ View
+
+ Bob Smith
+ Designer
+ View
+
+ Carol White
+ Manager
+ View
+
+ David Brown
+ Analyst
+ View
+
+
+
+
+ DataGrid around a sortable table
+
+ goab-table with onSort handler and goab-table-sort-header on each column. Age
+ column starts ascending. Tab into a sort header, press Enter or Space to
+ toggle. Click a sort header with mouse should sort but not leave a lingering
+ ring. Arrow keys still navigate cells.
+
+
+
+
+
+
+ Name
+
+
+ Role
+
+
+ Age
+
+
+
+
+ @for (p of sortablePeople; track p.name) {
+
+ {{ p.name }}
+ {{ p.role }}
+ {{ p.age }}
+
+ }
+
+
+
+
+ DataGrid around cards (layout mode)
+
+
+
+
+
+
+
+
+
+
+
diff --git a/apps/prs/angular/src/routes/bugs/3605/bug3605.component.ts b/apps/prs/angular/src/routes/bugs/3605/bug3605.component.ts
new file mode 100644
index 0000000000..295ad455ad
--- /dev/null
+++ b/apps/prs/angular/src/routes/bugs/3605/bug3605.component.ts
@@ -0,0 +1,72 @@
+import { Component } from "@angular/core";
+import { CommonModule } from "@angular/common";
+import {
+ GoabBadge,
+ GoabBlock,
+ GoabButton,
+ GoabCheckbox,
+ GoabChip,
+ GoabContainer,
+ GoabDataGrid,
+ GoabDetails,
+ GoabDivider,
+ GoabFilterChip,
+ GoabLink,
+ GoabMenuAction,
+ GoabMenuButton,
+ GoabMicrositeHeader,
+ GoabNotification,
+ GoabTable,
+ GoabTableSortHeader,
+ GoabText,
+ GoabTextArea,
+ GoabTooltip,
+} from "@abgov/angular-components";
+import { GoabTableOnSortDetail } from "@abgov/ui-components-common";
+
+@Component({
+ standalone: true,
+ selector: "abgov-bug3605",
+ templateUrl: "./bug3605.component.html",
+ imports: [
+ CommonModule,
+ GoabBadge,
+ GoabBlock,
+ GoabButton,
+ GoabCheckbox,
+ GoabChip,
+ GoabContainer,
+ GoabDataGrid,
+ GoabDetails,
+ GoabDivider,
+ GoabFilterChip,
+ GoabLink,
+ GoabMenuAction,
+ GoabMenuButton,
+ GoabMicrositeHeader,
+ GoabNotification,
+ GoabTable,
+ GoabTableSortHeader,
+ GoabText,
+ GoabTextArea,
+ GoabTooltip,
+ ],
+})
+export class Bug3605Component {
+ sortablePeople = [
+ { name: "Alice Johnson", role: "Developer", age: 32 },
+ { name: "Bob Smith", role: "Designer", age: 28 },
+ { name: "Carol White", role: "Manager", age: 45 },
+ { name: "David Brown", role: "Analyst", age: 38 },
+ ];
+
+ onSort(detail: GoabTableOnSortDetail) {
+ const by = detail.sortBy as "name" | "role" | "age";
+ const dir = detail.sortDir;
+ this.sortablePeople = [...this.sortablePeople].sort((a, b) => {
+ if (a[by] < b[by]) return dir === 1 ? -1 : 1;
+ if (a[by] > b[by]) return dir === 1 ? 1 : -1;
+ return 0;
+ });
+ }
+}
diff --git a/apps/prs/angular/src/routes/bugs/3605/bug3605.route.json b/apps/prs/angular/src/routes/bugs/3605/bug3605.route.json
new file mode 100644
index 0000000000..1c9f9257e0
--- /dev/null
+++ b/apps/prs/angular/src/routes/bugs/3605/bug3605.route.json
@@ -0,0 +1,6 @@
+{
+ "title": "Focus visible across interactive components",
+ "path": "bugs/3605",
+ "id": "3605",
+ "type": "bug"
+}
diff --git a/apps/prs/angular/src/routes/bugs/3668/bug3668.component.html b/apps/prs/angular/src/routes/bugs/3668/bug3668.component.html
new file mode 100644
index 0000000000..3c6d55d43c
--- /dev/null
+++ b/apps/prs/angular/src/routes/bugs/3668/bug3668.component.html
@@ -0,0 +1,117 @@
+:focus-visible across interactive components
+ :active)
+ on buttons should still show the pressed/focused look.
+ assets/css/reset.css.
+ Primary inverse
+ Secondary inverse
+ Tertiary inverse
+
+
+
+ focusin on the slotted anchor and checks
+ .matches(':focus-visible') to keep keyboard-only semantics across the
+ slot boundary.
+
+
+ Important notification with a link inside.
+
+
+
+
+ Emergency notification with a link inside.
+
+
+ .tooltip:focus .tooltip-text → :focus-visible
+ summary:focus → :focus-visible
+ goab-data-grid wrapping a goab-table. Focus styling
+ is JS-driven, now guarded with a keyboard-input tracker so mouse click doesn't show the ring.
+ keyboardNav="layout". Each card is a row, cells include the checkbox, name,
+ badge, stat blocks, and menu button.
+
+
+
+
+
+
+ Mike Zwei
+
+
+
+
+
+
+ Updated
+ Jun 30, 2022 at 2:30 PM
+
+
+ Email
+ mike.zwei@gmail.com
+
+
+ Program
+ Wee Wild Ones Curry
+
+
+
+
+ Program ID
+ 74528567
+
+
+ Service access
+ Claims Adjustments
+
+
+
+
+
+
+
+
+ Emma Stroman
+
+
+
+
+
+
+ Updated
+ Nov 28, 2021 at 1:30 PM
+
+
+ Email
+ emma.stroman@gmail.com
+
+
+ Program
+ Fort McMurray
+
+
+
+
+ Program ID
+ 74522643
+
+
+ Service access
+ Claims Adjustments
+
+
+
+ Bug #3668: Temporary notification refinements
+
+
+
+
+ View on GitHub
+
+
+
+
+
+ 1. Indeterminate and progress variants should not have a dark grey border, and
+ should have a raised-heavy shadow. 2. Action button should be a tertiary
+ button, not a text button. 3. Below 360px, message and action button stack
+ vertically with button right-aligned.
+
+
+
+
+ Test Cases
+
+
+ Test 1: Indeterminate and progress variants (border + shadow)
+
+
+ Click each to trigger. Inspect the notification surface. Indeterminate and
+ progress should NOT have a dark grey border and SHOULD have a raised-heavy shadow
+ (matching basic/success/failure).
+
+
+
+ Basic (reference)
+
+
+ Success (reference)
+
+
+ Failure (reference)
+
+ Indeterminate
+ Progress
+
+
+ Test 2: Action button style
+
+ The action button should render as a tertiary button, not a text button. Inspect
+ the button element.
+
+ Show with action button
+
+ Test 3: Stacking below 360px
+
+ Resize your browser below 360px width and trigger a notification with an action.
+ Message and action button should stack vertically with button right-aligned.
+
+
+
+ Show with action (then resize to 360px)
+
+
+ Show with long content + action
+
+
+
+
+ Test 4: Centered controller overlay blocks underlying UI
+
+
+ Click the button below to show a centered notification, then try clicking the
+ fixed Underlying target button at the bottom-right while the notification is
+ visible. If the count does not increase until the notification disappears, the
+ full-width controller overlay is blocking pointer events outside the snackbar.
+
+
+
+ Show centered notification
+
+
+ Reset target count
+
+
+
+ Underlying target clicks: {{ underlyingTargetClicks }}
+
+
+
diff --git a/apps/prs/angular/src/routes/bugs/3668/bug3668.component.ts b/apps/prs/angular/src/routes/bugs/3668/bug3668.component.ts
new file mode 100644
index 0000000000..ed8b351b7f
--- /dev/null
+++ b/apps/prs/angular/src/routes/bugs/3668/bug3668.component.ts
@@ -0,0 +1,100 @@
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
+import {
+ GoabBlock,
+ GoabButton,
+ GoabDetails,
+ GoabDivider,
+ GoabLink,
+ GoabTemporaryNotificationCtrl,
+ GoabText,
+} from "@abgov/angular-components";
+import { TemporaryNotification } from "@abgov/ui-components-common";
+
+@Component({
+ standalone: true,
+ selector: "abgov-bug3668",
+ templateUrl: "./bug3668.component.html",
+ imports: [
+ GoabBlock,
+ GoabButton,
+ GoabDetails,
+ GoabDivider,
+ GoabLink,
+ GoabTemporaryNotificationCtrl,
+ GoabText,
+ ],
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+})
+export class Bug3668Component {
+ underlyingTargetClicks = 0;
+
+ showBasic() {
+ TemporaryNotification.show("Basic notification for comparison", {
+ type: "basic",
+ duration: 8000,
+ });
+ }
+
+ showSuccess() {
+ TemporaryNotification.show("Successfully saved", {
+ type: "success",
+ duration: 8000,
+ });
+ }
+
+ showFailure() {
+ TemporaryNotification.show("Something went wrong", {
+ type: "failure",
+ duration: 8000,
+ });
+ }
+
+ showIndeterminate() {
+ const uuid = TemporaryNotification.show("Loading something indeterminate...", {
+ type: "indeterminate",
+ });
+ setTimeout(() => TemporaryNotification.dismiss(uuid), 5000);
+ }
+
+ showProgress() {
+ const uuid = TemporaryNotification.show("Uploading file...", {
+ type: "progress",
+ });
+ let value = 0;
+ const interval = setInterval(() => {
+ value += 10;
+ TemporaryNotification.setProgress(uuid, value);
+ if (value >= 100) clearInterval(interval);
+ }, 500);
+ }
+
+ showWithAction() {
+ TemporaryNotification.show("Item deleted", {
+ type: "basic",
+ duration: 8000,
+ actionText: "Undo",
+ });
+ }
+
+ showLongContent() {
+ TemporaryNotification.show(
+ "Your application for the Alberta Works program has been successfully submitted and is now being reviewed by our team. You will receive a confirmation email shortly.",
+ { type: "basic", duration: 15000, actionText: "View details" },
+ );
+ }
+
+ showControllerOverlayIssue() {
+ TemporaryNotification.show(
+ "Overlay repro: while this centered notification is visible, try clicking the underlying target button at the bottom-right.",
+ { type: "basic", duration: 12000 },
+ );
+ }
+
+ incrementUnderlyingTargetClicks() {
+ this.underlyingTargetClicks += 1;
+ }
+
+ resetUnderlyingTargetClicks() {
+ this.underlyingTargetClicks = 0;
+ }
+}
diff --git a/apps/prs/angular/src/routes/bugs/3668/bug3668.route.json b/apps/prs/angular/src/routes/bugs/3668/bug3668.route.json
new file mode 100644
index 0000000000..0562f9ca27
--- /dev/null
+++ b/apps/prs/angular/src/routes/bugs/3668/bug3668.route.json
@@ -0,0 +1,6 @@
+{
+ "title": "Temporary Notification Refinements",
+ "path": "bugs/3668",
+ "id": "3668",
+ "type": "bug"
+}
diff --git a/apps/prs/angular/src/routes/bugs/3892/bug3892.component.html b/apps/prs/angular/src/routes/bugs/3892/bug3892.component.html
new file mode 100644
index 0000000000..3b8653f10d
--- /dev/null
+++ b/apps/prs/angular/src/routes/bugs/3892/bug3892.component.html
@@ -0,0 +1,187 @@
+
+
+
+ Open popover
+
+
+
+
+
+
+
+ Open drawer
+
+
+
+
+
+
+
+
+
+ Open modal
+
+
+
+
+
\ No newline at end of file
diff --git a/apps/prs/angular/src/routes/bugs/3892/bug3892.component.ts b/apps/prs/angular/src/routes/bugs/3892/bug3892.component.ts
new file mode 100644
index 0000000000..5caa5dab5d
--- /dev/null
+++ b/apps/prs/angular/src/routes/bugs/3892/bug3892.component.ts
@@ -0,0 +1,111 @@
+import { CommonModule } from "@angular/common";
+import { Component } from "@angular/core";
+import {
+ GoabButton,
+ GoabContainer,
+ GoabDatePicker,
+ GoabDrawer,
+ GoabDropdown,
+ GoabDropdownItem,
+ GoabMenuAction,
+ GoabMenuButton,
+ GoabModal,
+ GoabPopover,
+ GoabPushDrawer,
+} from "@abgov/angular-components";
+import type {
+ GoabDatePickerOnChangeDetail,
+ GoabDropdownOnChangeDetail,
+} from "@abgov/ui-components-common";
+
+@Component({
+ standalone: true,
+ selector: "abgov-bug3892",
+ templateUrl: "./bug3892.component.html",
+ imports: [
+ CommonModule,
+ GoabButton,
+ GoabContainer,
+ GoabDatePicker,
+ GoabDrawer,
+ GoabDropdown,
+ GoabDropdownItem,
+ GoabMenuAction,
+ GoabMenuButton,
+ GoabModal,
+ GoabPopover,
+ GoabPushDrawer,
+ ],
+})
+export class Bug3892Component {
+ popoverDate = "";
+ popoverProvince = "";
+
+ drawerOpen = false;
+ drawerDate = "";
+ drawerProvince = "";
+
+ pushDrawerOpen = false;
+ pushDrawerDate = "";
+ pushDrawerProvince = "";
+
+ modalOpen = false;
+ modalDate = "";
+ modalProvince = "";
+
+ handlePopoverDateChange(detail: GoabDatePickerOnChangeDetail): void {
+ this.popoverDate = detail.valueStr || "";
+ }
+
+ handlePopoverProvinceChange(detail: GoabDropdownOnChangeDetail): void {
+ this.popoverProvince = detail.value || "";
+ }
+
+ openDrawer(): void {
+ this.drawerOpen = true;
+ }
+
+ handleDrawerClose(): void {
+ this.drawerOpen = false;
+ }
+
+ handleDrawerDateChange(detail: GoabDatePickerOnChangeDetail): void {
+ this.drawerDate = detail.valueStr || "";
+ }
+
+ handleDrawerProvinceChange(detail: GoabDropdownOnChangeDetail): void {
+ this.drawerProvince = detail.value || "";
+ }
+
+ openPushDrawer(): void {
+ this.pushDrawerOpen = true;
+ }
+
+ handlePushDrawerClose(): void {
+ this.pushDrawerOpen = false;
+ }
+
+ handlePushDrawerDateChange(detail: GoabDatePickerOnChangeDetail): void {
+ this.pushDrawerDate = detail.valueStr || "";
+ }
+
+ handlePushDrawerProvinceChange(detail: GoabDropdownOnChangeDetail): void {
+ this.pushDrawerProvince = detail.value || "";
+ }
+
+ openModal(): void {
+ this.modalOpen = true;
+ }
+
+ handleModalClose(): void {
+ this.modalOpen = false;
+ }
+
+ handleModalDateChange(detail: GoabDatePickerOnChangeDetail): void {
+ this.modalDate = detail.valueStr || "";
+ }
+
+ handleModalProvinceChange(detail: GoabDropdownOnChangeDetail): void {
+ this.modalProvince = detail.value || "";
+ }
+}
\ No newline at end of file
diff --git a/apps/prs/angular/src/routes/bugs/3892/bug3892.route.json b/apps/prs/angular/src/routes/bugs/3892/bug3892.route.json
new file mode 100644
index 0000000000..68606580b6
--- /dev/null
+++ b/apps/prs/angular/src/routes/bugs/3892/bug3892.route.json
@@ -0,0 +1,6 @@
+{
+ "type": "bug",
+ "id": "3892",
+ "path": "bugs/3892",
+ "title": "Nested close propagation"
+}
\ No newline at end of file
diff --git a/apps/prs/angular/src/routes/docs/accordion/accordion.component.html b/apps/prs/angular/src/routes/docs/accordion/accordion.component.html
index d0226905a1..ed3794ba8b 100644
--- a/apps/prs/angular/src/routes/docs/accordion/accordion.component.html
+++ b/apps/prs/angular/src/routes/docs/accordion/accordion.component.html
@@ -2,8 +2,8 @@
+
+
+ 3892 - Nested close propagation
++ This page tests the issue where popover close events are propegating to parent + drawers and modals. +
+
+
+
+ Popover
+Open the popover and interact with all controls.
+
+
+
+
+
+
+ + Expected: using the date picker, dropdown, and menu button updates values + and leaves the popover open. +
+
+
+
+ Drawer
+Open the drawer and interact with all controls.
+
+
+
+
+
+
+ + Expected: using the date picker, dropdown, and menu button updates values + and leaves the drawer open. +
+Push drawer
+Open the push drawer and interact with all controls.
+ +
+ Open push drawer
+
+
+
+
+
+
+
+
+
+
+ + Expected: using the date picker, dropdown, and menu button updates values + and leaves the push drawer open. +
+
+
+
+ Modal
+Open the modal and interact with all controls.
+
+
+
+
+
+
+ + Expected: using the date picker, dropdown, and menu button updates values + and leaves the modal open. +
+Accordion
Basic
Open by default
@@ -82,7 +82,8 @@Hide and show many sections of information
heading="How do I create an account?" headingSize="medium" [open]="expandedList[0]" - (onChange)="toggleAccordion(0, $event)"> + (onChange)="toggleAccordion(0, $event)" +> To create an account you will need to contact your office admin. @@ -90,22 +91,50 @@Hide and show many sections of information
heading="What verification is needed to sign documents digitally?" headingSize="medium" [open]="expandedList[1]" - (onChange)="toggleAccordion(1, $event)"> - You will need to verify your identity through our two factor authentication in addition to the digital signature. + (onChange)="toggleAccordion(1, $event)" +> + You will need to verify your identity through our two factor authentication in addition + to the digital signature.
+ View all
+
+Notification panel
+ +Basic notification panel
+With urgent notifications
+Notification type badges
+
+ Feature 3636: Accordion actions slot and list view variant
+
+ The GoAAccordion component now includes an optional slot for action buttons in the
+ header, as well as a new "list view" variant that features a filled header background
+ and hover state.
+
+
+
diff --git a/apps/prs/angular/src/routes/features/feat3636/feat3636.component.ts b/apps/prs/angular/src/routes/features/feat3636/feat3636.component.ts
new file mode 100644
index 0000000000..264448f2f3
--- /dev/null
+++ b/apps/prs/angular/src/routes/features/feat3636/feat3636.component.ts
@@ -0,0 +1,15 @@
+import { Component } from "@angular/core";
+import {
+ GoabAccordion,
+ GoabBadge,
+ GoabButton,
+ GoabText,
+} from "@abgov/angular-components";
+
+@Component({
+ standalone: true,
+ selector: "abgov-feat3636",
+ templateUrl: "./feat3636.component.html",
+ imports: [GoabAccordion, GoabBadge, GoabButton, GoabText],
+})
+export class Feat3636Component {}
diff --git a/apps/prs/angular/src/routes/features/feat3636/feat3636.route.json b/apps/prs/angular/src/routes/features/feat3636/feat3636.route.json
new file mode 100644
index 0000000000..3f0882b1c3
--- /dev/null
+++ b/apps/prs/angular/src/routes/features/feat3636/feat3636.route.json
@@ -0,0 +1,6 @@
+{
+ "title": "Accordion actions slot and list view variant",
+ "path": "features/3636",
+ "id": "3636",
+ "type": "feature"
+}
diff --git a/apps/prs/angular/src/routes/features/feat3814/feat3814.component.css b/apps/prs/angular/src/routes/features/feat3814/feat3814.component.css
new file mode 100644
index 0000000000..b57a6b5cf6
--- /dev/null
+++ b/apps/prs/angular/src/routes/features/feat3814/feat3814.component.css
@@ -0,0 +1,19 @@
+:host {
+ display: block;
+}
+
+.search-menu-badge {
+ color: var(--goa-color-greyscale-600);
+ height: 1.25rem;
+ min-width: 1.25rem;
+ line-height: 1;
+ text-align: center;
+ font-size: var(--goa-font-size-2);
+ background-color: var(--goa-color-greyscale-100);
+ border: 1px solid var(--goa-color-greyscale-200);
+ border-radius: var(--goa-border-radius-s);
+ padding: var(--goa-space-3xs) var(--goa-space-xs);
+ display: inline-block;
+ vertical-align: top;
+ margin-top: var(--goa-space-3xs);
+}
diff --git a/apps/prs/angular/src/routes/features/feat3814/feat3814.component.html b/apps/prs/angular/src/routes/features/feat3814/feat3814.component.html
new file mode 100644
index 0000000000..6506ccaaf3
--- /dev/null
+++ b/apps/prs/angular/src/routes/features/feat3814/feat3814.component.html
@@ -0,0 +1,47 @@
+
+ Actions slot examples
+
+
+
+ This example places a button in the actions slot while keeping heading text and
+ content as standard body copy.
+
+
+
+
+ Edit
+
+
+
+
+ This example mixes badges and controls inside the actions slot.
+
+
+
+
+
+
+
+
+ View all
+
+
+ Heading content examples
+
+
+
+ The heading content slot can display status indicators such as badges.
+
+
+
+
+
+
+
+ Preview
+
+
+
+
+ Multiple indicators can be grouped in heading content when more context is needed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Manage
+
+
+ Icon position and fixed width examples
+
+
+
+
+
+
+ A narrow fixed-width accordion using the default icon position.
+
+
+
+
+ Open
+
+
+
+
+ A wider fixed-width accordion with the icon moved to the right side.
+
+
+
+
+
+
+
+ Details
+
+
+ Filled/List View Style
+
+
+ stuff goes in here
+
+
+
+
+
+
+
+
+
+ stuff goes in here
+
+
+
+
+
+
+
+
+
+ stuff goes in here
+
+
+
+
+
+
+
+
+
+ stuff goes in here
+
+
+
+
+
+
+
+
+
+
+ 1 Comment(s)
+ View
+
+
+ 4 Comment(s)
+ View
+
+
+ 3 Comment(s)
+ View
+
+
+ 8 Comment(s)
+ View
+
+ Multi-line Heading with Centered Chevron
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + 👀The chevron should be centered here +
+
+ 1 Comment(s)
+ View
+
+ + 👀The chevron should be centered here +
+
+ 1 Comment(s)
+ View
+
+ + 👀The chevron should be centered here +
+
+ 1 Comment(s)
+ View
+
+ + 👀The chevron should be centered here +
+
+ 1 Comment(s)
+ View
+
+ + 👀The chevron should be centered here +
+
+ 1 Comment(s)
+ View
+
+ + 👀The chevron should be centered here +
++ 👀The chevron should be centered here +
++ 👀The chevron should be centered here +
++ 👀The chevron should be centered here +
++ 👀The chevron should be centered here +
+
+ 1 Comment(s)
+ View
+
+ + 👀The chevron should be centered here +
+
+ 1 Comment(s)
+ View
+
+
+ Feature 3814: Work Side Menu trailingContent slot
+
+
+ This page demonstrates the new trailingContent slot on Work Side Menu Item.
+ The first item shows a keyboard shortcut hint and the second item shows a badge.
+
+
+
+
+
+
+
+3602 FileUploadInput and FileUploadCard Improvements
+
+
+ handleFileChange(detail, setSmallFiles)}
+ />
+
+
+ handleFileChange(detail, setLargeFiles)}
+ />
+
+
+
+ );
+}
diff --git a/apps/prs/react/src/routes/bugs/bug3605.tsx b/apps/prs/react/src/routes/bugs/bug3605.tsx
new file mode 100644
index 0000000000..939769f373
--- /dev/null
+++ b/apps/prs/react/src/routes/bugs/bug3605.tsx
@@ -0,0 +1,485 @@
+import "@abgov/style";
+import { useState } from "react";
+import {
+ GoabBadge,
+ GoabBlock,
+ GoabButton,
+ GoabCheckbox,
+ GoabChip,
+ GoabContainer,
+ GoabDataGrid,
+ GoabDetails,
+ GoabDivider,
+ GoabFilterChip,
+ GoabLink,
+ GoabMenuAction,
+ GoabMenuButton,
+ GoabMicrositeHeader,
+ GoabNotification,
+ GoabTable,
+ GoabTableSortHeader,
+ GoabText,
+ GoabTextarea,
+ GoabTooltip,
+} from "@abgov/react-components";
+
+export function Bug3605Route() {
+ const [sortablePeople, setSortablePeople] = useState([
+ { name: "Alice Johnson", role: "Developer", age: 32 },
+ { name: "Bob Smith", role: "Designer", age: 28 },
+ { name: "Carol White", role: "Manager", age: 45 },
+ { name: "David Brown", role: "Analyst", age: 38 },
+ ]);
+
+ return (
+
+ {smallFiles.map((f) => (
+ setSmallFiles((prev) => prev.filter((item) => item.id !== f.id))}
+ />
+ ))}
+
+
+ {largeFiles.map((f) => (
+ setLargeFiles((prev) => prev.filter((item) => item.id !== f.id))}
+ />
+ ))}
+
+
+
+ Issue 3605
+
+
+ Use focus-visible across interactive components
+
+
+
+
+
+ View on GitHub
+
+
+
+
+
+ For every section: Tab should show the focus ring with the correct gap and offset.
+ Click should not leave a lingering ring. Mouse-down on buttons should still show the
+ pressed state.
+
+
+
+ MicrositeHeader
+ Tab through the links inside the header. Click any link.
+
+
+
+ Chip and FilterChip
+ Chip (deprecated)
+
+
+
+ FilterChip
+
+
+
+
+
+ Plain link reset
+ Unstyled anchors pick up the global reset from assets/css/reset.css.
+
+
+
+
+ TextArea error state
+
+ Tab into the error text area. Click into it. The focus-within container pattern
+ applies on focus, which is correct for text inputs.
+
+
+
+
+ Button
+
+ Click and Tab each variant. Watch for lingering rings after mouse-up.
+
+
+ Default
+
+ Primary
+ Secondary
+ Tertiary
+
+
+ Destructive
+
+ Primary destructive
+ Secondary destructive
+ Tertiary destructive
+
+
+ Inverse (on dark bg)
+
+
+
+ Checkbox
+ Tab to each. Click each. No ring on mouse click.
+
+
+
+
+
+ Link
+
+ Ring sits on the outer container so it wraps icon + text together. The component
+ listens for
+
+ Plain links
+
+ First link
+ Second link
+ Third link
+
+
+ Links with leading icons
+
+ Download file
+ Learn more
+ Open in new tab
+
+
+ Links with trailing icons
+
+ Continue
+ See more
+ External resource
+
+
+
+
+ Notification
+
+ Slotted anchors in notifications now use focus-visible. Keyboard only.
+
+
+
+ Info notification with a link inside.
+
+
+
+
+ Tooltip
+
+ Hover for mouse, keyboard focus for keyboard. Mouse click on the trigger does
+ not reveal the tooltip.
+
+
+
+ Hover or Tab me
+
+
+
+
+
+ Details
+
+ Click just toggles open. Keyboard focus shows the focused look.
+
+
+ Content inside the details component.
+
+
+
+
+ DataGrid around a table
+
+ Typical pattern: GoabDataGrid wrapping a GoabTable. Focus styling is JS-driven,
+ now guarded with a keyboard-input tracker so mouse click does not show the ring.
+ Arrow keys navigate cells.
+
+
+
+
+
+ Name
+ Role
+ Status
+ Actions
+
+
+
+
+ Alice Johnson
+ Developer
+ View
+
+ Bob Smith
+ Designer
+ View
+
+ Carol White
+ Manager
+ View
+
+ David Brown
+ Analyst
+ View
+
+
+
+
+ DataGrid around a table with row checkboxes
+
+ Adds a select-all checkbox to the header row and per-row checkboxes.
+ When focus lands on a cell whose only focusable child is the checkbox,
+ focus delegates to the checkbox itself. The corner cells should still
+ show the rounded focus treatment.
+
+
+
+
+
+ Name
+ Role
+ Status
+ Actions
+
+
+
+
+ Alice Johnson
+ Developer
+ View
+
+ Bob Smith
+ Designer
+ View
+
+ Carol White
+ Manager
+ View
+
+ David Brown
+ Analyst
+ View
+
+
+
+
+ DataGrid around a sortable table
+
+ GoabTable with onSort handler and GoabTableSortHeader on each column. Age
+ column starts ascending. Tab into a sort header, press Enter or Space to
+ toggle. Click a sort header with mouse should sort but not leave a
+ lingering ring. Arrow keys still navigate cells.
+
+
+ {
+ const by = e.sortBy as "name" | "role" | "age";
+ const dir = e.sortDir;
+ setSortablePeople([...sortablePeople].sort((a, b) => {
+ if (a[by] < b[by]) return dir === 1 ? -1 : 1;
+ if (a[by] > b[by]) return dir === 1 ? 1 : -1;
+ return 0;
+ }));
+ }}
+ >
+
+
+
+ Name
+
+
+ Role
+
+
+ Age
+
+
+
+
+ {sortablePeople.map((p) => (
+
+ {p.name}
+ {p.role}
+ {p.age}
+
+ ))}
+
+
+
+
+ DataGrid around cards (layout mode)
+
+ keyboardNav="layout". Each card is a row, cells include the checkbox,
+ name, badge, stat blocks, and menu button.
+
+
+
+
+
+
+
+
+
+
+ );
+}
+
+export default Bug3605Route;
diff --git a/apps/prs/react/src/routes/bugs/bug3625.tsx b/apps/prs/react/src/routes/bugs/bug3625.tsx
index 3ae0b9667c..a66d88fa88 100644
--- a/apps/prs/react/src/routes/bugs/bug3625.tsx
+++ b/apps/prs/react/src/routes/bugs/bug3625.tsx
@@ -8,23 +8,11 @@ import {
GoabFormItem,
GoabText,
} from "@abgov/react-components";
-import { useEffect, useState } from "react";
-import v2TokensUrl from "@abgov/design-tokens-v2/dist/tokens.css?url";
+import { useState } from "react";
export function Bug3625Route() {
const [controlledOpen, setControlledOpen] = useState(false);
- // Inject the v2 design tokens
- useEffect(() => {
- const link = document.createElement("link");
- link.rel = "stylesheet";
- link.href = v2TokensUrl;
- document.head.appendChild(link);
- return () => {
- document.head.removeChild(link);
- };
- }, []);
-
return (
+ Primary inverse
+ Secondary inverse
+ Tertiary inverse
+
+
+
+ focusin on the slotted anchor and checks{" "}
+ .matches(':focus-visible') to keep keyboard-only semantics across the
+ slot boundary.
+
+
+ Important notification with a link inside.
+
+
+
+
+ Emergency notification with a link inside.
+
+
+
+
+
+
+
+
+ Mike Zwei
+
+
+
+
+
+
+ Updated
+ Jun 30, 2022 at 2:30 PM
+
+
+ Email
+ mike.zwei@gmail.com
+
+
+ Program
+ Wee Wild Ones Curry
+
+
+
+
+ Program ID
+ 74528567
+
+
+ Service access
+ Claims Adjustments
+
+
+
+
+
+
+
+
+ Emma Stroman
+
+
+
+
+
+
+ Updated
+ Nov 28, 2021 at 1:30 PM
+
+
+ Email
+ emma.stroman@gmail.com
+
+
+ Program
+ Fort McMurray
+
+
+
+
+ Program ID
+ 74522643
+
+
+ Service access
+ Claims Adjustments
+
+
+ Bug 3625: Accordion Refinement
diff --git a/apps/prs/react/src/routes/bugs/bug3668.tsx b/apps/prs/react/src/routes/bugs/bug3668.tsx new file mode 100644 index 0000000000..858c184dbc --- /dev/null +++ b/apps/prs/react/src/routes/bugs/bug3668.tsx @@ -0,0 +1,212 @@ +import { + GoabBlock, + GoabText, + GoabDivider, + GoabDetails, + GoabLink, + GoabButton, + GoabTemporaryNotificationCtrl, +} from "@abgov/react-components"; +import { TemporaryNotification } from "@abgov/ui-components-common"; +import { useState } from "react"; + +export function Bug3668Route() { + const [underlyingTargetClicks, setUnderlyingTargetClicks] = useState(0); + + const showBasic = () => { + TemporaryNotification.show("Basic notification for comparison", { + type: "basic", + duration: 8000, + }); + }; + + const showIndeterminate = () => { + const uuid = TemporaryNotification.show("Loading something indeterminate...", { + type: "indeterminate", + }); + setTimeout(() => TemporaryNotification.dismiss(uuid), 5000); + }; + + const showProgress = () => { + const uuid = TemporaryNotification.show("Uploading file...", { + type: "progress", + }); + let value = 0; + const interval = setInterval(() => { + value += 10; + TemporaryNotification.setProgress(uuid, value); + if (value >= 100) clearInterval(interval); + }, 500); + }; + + const showWithAction = () => { + TemporaryNotification.show("Item deleted", { + type: "basic", + duration: 8000, + actionText: "Undo", + }); + }; + + const showSuccess = () => { + TemporaryNotification.show("Successfully saved", { + type: "success", + duration: 8000, + }); + }; + + const showFailure = () => { + TemporaryNotification.show("Something went wrong", { + type: "failure", + duration: 8000, + }); + }; + + const showControllerOverlayIssue = () => { + TemporaryNotification.show( + "Overlay repro: while this centered notification is visible, try clicking the underlying target button at the bottom-right.", + { + type: "basic", + duration: 12000, + }, + ); + }; + + return ( +
+
+ Bug #3668: Temporary notification refinements
+
+
+
+
+
+ View on GitHub
+
+
+
+
+
+ 1. Indeterminate and progress variants should not have a dark grey border, and
+ should have a raised-heavy shadow. 2. Action button should be a tertiary
+ button, not a text button. 3. Below 360px, message and action button stack
+ vertically with button right-aligned.
+
+
+
+
+ Test Cases
+
+
+ Test 1: Indeterminate and progress variants (border + shadow)
+
+
+ Click each to trigger. Inspect the notification surface. Indeterminate and
+ progress should NOT have a dark grey border and SHOULD have a raised-heavy shadow
+ (matching basic/success/failure).
+
+
+
+ Basic (reference)
+
+
+ Success (reference)
+
+
+ Failure (reference)
+
+ Indeterminate
+ Progress
+
+
+ Test 2: Action button style
+
+ The action button should render as a tertiary button, not a text button. Inspect
+ the button element.
+
+ Show with action button
+
+ Test 3: Stacking below 360px
+
+ Resize your browser below 360px width and trigger a notification with an action.
+ Message and action button should stack vertically with button right-aligned.
+
+
+
+ Show with action (then resize to 360px)
+
+ {
+ TemporaryNotification.show(
+ "Your application for the Alberta Works program has been successfully submitted and is now being reviewed by our team. You will receive a confirmation email shortly.",
+ { type: "basic", duration: 15000, actionText: "View details" },
+ );
+ }}
+ >
+ Show with long content + action
+
+
+
+
+ Test 4: Centered controller overlay blocks underlying UI
+
+
+ Click the button below to show a centered notification, then try clicking the
+ fixed Underlying target button at the bottom-right while the notification is
+ visible. If the count does not increase until the notification disappears, the
+ full-width controller overlay is blocking pointer events outside the snackbar.
+
+
+
+ Show centered notification
+
+ {
+ setUnderlyingTargetClicks(0);
+ }}
+ >
+ Reset target count
+
+
+
+ Underlying target clicks: {underlyingTargetClicks}
+
+
+
+ );
+}
+
+export default Bug3668Route;
diff --git a/apps/prs/react/src/routes/bugs/bug3892.tsx b/apps/prs/react/src/routes/bugs/bug3892.tsx
new file mode 100644
index 0000000000..0ade0fbe87
--- /dev/null
+++ b/apps/prs/react/src/routes/bugs/bug3892.tsx
@@ -0,0 +1,280 @@
+import { useState } from "react";
+import {
+ GoabButton,
+ GoabDatePicker,
+ GoabDrawer,
+ GoabDropdown,
+ GoabDropdownItem,
+ GoabMenuAction,
+ GoabMenuButton,
+ GoabModal,
+ GoabPopover,
+ GoabPushDrawer,
+ GoabText,
+ GoabContainer,
+} from "@abgov/react-components";
+import type {
+ GoabDatePickerOnChangeDetail,
+ GoabDropdownOnChangeDetail,
+} from "@abgov/ui-components-common";
+
+const stackStyle = {
+ display: "grid",
+ gap: "1.5rem",
+};
+
+export function Bug3892Route() {
+ const [popoverDate, setPopoverDate] = useState("");
+ const [popoverProvince, setPopoverProvince] = useState("");
+
+ const [drawerOpen, setDrawerOpen] = useState(false);
+ const [drawerDate, setDrawerDate] = useState("");
+ const [drawerProvince, setDrawerProvince] = useState("");
+
+ const [pushDrawerOpen, setPushDrawerOpen] = useState(false);
+ const [pushDrawerDate, setPushDrawerDate] = useState("");
+ const [pushDrawerProvince, setPushDrawerProvince] = useState("");
+
+ const [modalOpen, setModalOpen] = useState(false);
+ const [modalDate, setModalDate] = useState("");
+ const [modalProvince, setModalProvince] = useState("");
+
+ const handlePopoverDateChange = (detail: GoabDatePickerOnChangeDetail) => {
+ setPopoverDate(detail.valueStr || "");
+ };
+
+ const handlePopoverProvinceChange = (detail: GoabDropdownOnChangeDetail) => {
+ setPopoverProvince(detail.value || "");
+ };
+
+ const handleDrawerDateChange = (detail: GoabDatePickerOnChangeDetail) => {
+ setDrawerDate(detail.valueStr || "");
+ };
+
+ const handleDrawerClose = () => {
+ setDrawerOpen(false);
+ };
+
+ const handleDrawerProvinceChange = (detail: GoabDropdownOnChangeDetail) => {
+ setDrawerProvince(detail.value || "");
+ };
+
+ const handlePushDrawerDateChange = (detail: GoabDatePickerOnChangeDetail) => {
+ setPushDrawerDate(detail.valueStr || "");
+ };
+
+ const handlePushDrawerProvinceChange = (detail: GoabDropdownOnChangeDetail) => {
+ setPushDrawerProvince(detail.value || "");
+ };
+
+ const handlePushDrawerClose = () => {
+ setPushDrawerOpen(false);
+ };
+
+ const handleModalDateChange = (detail: GoabDatePickerOnChangeDetail) => {
+ setModalDate(detail.valueStr || "");
+ };
+
+ const handleModalProvinceChange = (detail: GoabDropdownOnChangeDetail) => {
+ setModalProvince(detail.value || "");
+ };
+
+ const handleModalClose = () => {
+ setModalOpen(false);
+ };
+
+ return (
+
+
+ Open popover}>
+
+
+
+
+ setDrawerOpen(true)}>Open drawer
+
+
+
+
+
+
+
+ Push drawer
+
+ Open the push drawer and interact with all controls.
+
+
+
+
+ setModalOpen(true)}>Open modal
+
+
+
+
+
+ );
+}
\ No newline at end of file
diff --git a/apps/prs/react/src/routes/docs/accordion/accordion.tsx b/apps/prs/react/src/routes/docs/accordion/accordion.tsx
index 72ba82a9f7..cd3ad438c0 100644
--- a/apps/prs/react/src/routes/docs/accordion/accordion.tsx
+++ b/apps/prs/react/src/routes/docs/accordion/accordion.tsx
@@ -33,8 +33,8 @@ export function DocsAccordionRoute() {
+ 3892 - Nested close propagation
+
+ This page tests the issue where popover close events are propegating to parent
+ drawers and modals.
+
+
+
+
+
+ Popover
+
+ Open the popover and interact with all controls.
+
+
+
+
+ Expected: using the date picker, dropdown, and menu button updates values
+ and leaves the popover open.
+
+
+
+
+
+
+
+
+ Drawer
+
+ Open the drawer and interact with all controls.
+
+
+
+
+ Expected: using the date picker, dropdown, and menu button updates values
+ and leaves the drawer open.
+
+
+
+
+
+
+
+ setPushDrawerOpen(true)}>
+ Open push drawer
+
+
+
+
+
+
+
+ Expected: using the date picker, dropdown, and menu button updates values
+ and leaves the push drawer open.
+
+
+
+
+
+
+
+
+ Modal
+
+ Open the modal and interact with all controls.
+
+
+
+
+ Expected: using the date picker, dropdown, and menu button updates values
+ and leaves the modal open.
+
+
+
+
+
+
+ Basic
Open by default
@@ -77,11 +77,14 @@ export function DocsAccordionRoute() {Examples
Expand or collapse part of a form
-- Date of referral
- January 27, 2021 @@ -104,7 +107,12 @@ export function DocsAccordionRoute() {
Hide and show many sections of information
-
+
);
}
diff --git a/apps/prs/react/src/routes/docs/work-side-notification-panel/work-side-notification-panel.tsx b/apps/prs/react/src/routes/docs/work-side-notification-panel/work-side-notification-panel.tsx
new file mode 100644
index 0000000000..610e067253
--- /dev/null
+++ b/apps/prs/react/src/routes/docs/work-side-notification-panel/work-side-notification-panel.tsx
@@ -0,0 +1,299 @@
+import { useState } from "react";
+import {
+ GoabWorkSideMenu,
+ GoabWorkSideMenuItem,
+ GoabWorkSideNotificationItem,
+ GoabWorkSideNotificationPanel,
+ type GoabWorkSideNotificationItemProps,
+} from "@abgov/react-components";
+
+type NotificationItem = GoabWorkSideNotificationItemProps & { id: string };
+
+const initialBasicItems: NotificationItem[] = [
+ {
+ id: "1",
+ title: "New case assigned",
+ description: "Case #12345 has been assigned to you for review.",
+ timestamp: "2025-03-15T10:30:00Z",
+ type: "info",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "2",
+ title: "Document uploaded",
+ description: "A new document was uploaded to Case #12340.",
+ timestamp: "2025-03-15T09:15:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "3",
+ title: "Case resolved",
+ description: "Case #12330 has been marked as resolved.",
+ timestamp: "2025-03-14T16:00:00Z",
+ type: "success",
+ readStatus: "read",
+ priority: "normal",
+ },
+];
+
+const initialUrgentItems: NotificationItem[] = [
+ {
+ id: "1",
+ title: "System maintenance",
+ description: "Scheduled maintenance tonight at 11 PM. All services will be unavailable.",
+ timestamp: "2025-03-15T14:00:00Z",
+ type: "critical",
+ readStatus: "unread",
+ priority: "urgent",
+ },
+ {
+ id: "2",
+ title: "Deadline approaching",
+ description: "Case #12345 response is due in 2 hours.",
+ timestamp: "2025-03-15T12:00:00Z",
+ type: "warning",
+ readStatus: "unread",
+ priority: "urgent",
+ },
+ {
+ id: "3",
+ title: "New comment on case",
+ description: "A team member commented on Case #12340.",
+ timestamp: "2025-03-15T11:00:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+];
+
+const initialAllTypeItems: NotificationItem[] = [
+ {
+ id: "1",
+ title: "New comment on case",
+ description: "A team member commented on Case #12340.",
+ timestamp: "2025-03-15T10:00:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "2",
+ title: "Case #12345 assigned",
+ description: "Case #12345 has been assigned to you for review.",
+ timestamp: "2025-03-15T09:00:00Z",
+ type: "info",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "3",
+ title: "Case resolved",
+ description: "Case #12330 has been marked as resolved.",
+ timestamp: "2025-03-15T08:00:00Z",
+ type: "success",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "4",
+ title: "Deadline approaching",
+ description: "Case #12345 response is due in 2 hours.",
+ timestamp: "2025-03-15T07:00:00Z",
+ type: "warning",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "5",
+ title: "System maintenance",
+ description: "Scheduled maintenance tonight at 11 PM. All services will be unavailable.",
+ timestamp: "2025-03-15T06:00:00Z",
+ type: "critical",
+ readStatus: "unread",
+ priority: "normal",
+ },
+];
+
+export function DocsWorkSideNotificationPanelRoute() {
+ const [basicItems, setBasicItems] = useState(initialBasicItems);
+ const [urgentItems, setUrgentItems] = useState(initialUrgentItems);
+ const [allTypeItems, setAllTypeItems] = useState(initialAllTypeItems);
+
+ function navigate(path: string) {
+ console.log("navigate", path);
+ }
+
+ // --- Basic notification panel handlers ---
+ function handleMarkAllBasicNotificationsRead() {
+ setBasicItems((items) =>
+ items.map((item) => ({ ...item, readStatus: "read" })),
+ );
+ }
+
+ function handleViewAllBasicNotifications() {
+ console.log("view all basic notifications");
+ }
+
+ function handleClickBasicNotification(id: string) {
+ setBasicItems((items) =>
+ items.map((item) =>
+ item.id === id ? { ...item, readStatus: "read" } : item,
+ ),
+ );
+ }
+
+ // --- Urgent notification panel handlers ---
+ function handleMarkAllUrgentNotificationsRead() {
+ setUrgentItems((items) =>
+ items.map((item) => ({ ...item, readStatus: "read" })),
+ );
+ }
+
+ function handleViewAllUrgentNotifications() {
+ console.log("view all urgent notifications");
+ }
+
+ function handleClickUrgentNotification(id: string) {
+ setUrgentItems((items) =>
+ items.map((item) =>
+ item.id === id ? { ...item, readStatus: "read" } : item,
+ ),
+ );
+ }
+
+ // --- Notification type badges panel handlers ---
+ function handleMarkAllNotificationTypesRead() {
+ setAllTypeItems((items) =>
+ items.map((item) => ({ ...item, readStatus: "read" })),
+ );
+ }
+
+ function handleViewAllNotificationTypes() {
+ console.log("view all notification types");
+ }
+
+ function handleClickNotificationType(id: string) {
+ setAllTypeItems((items) =>
+ items.map((item) =>
+ item.id === id ? { ...item, readStatus: "read" } : item,
+ ),
+ );
+ }
+
+ return (
+ Benji
+
+
+ 1 Comment(s)
+
+
+ View
+
+
+ }
+ >
+ -
+
- Date of referral +
- January 27, 2021 +
- Work safety concerns +
- None +
- Type of referral +
- Word of mouth, internet search +
- Intake received from another site +
- Yes +
+ navigate(path)}
+ primaryContent={
+ <>
+ handleMarkAllBasicNotificationsRead()}
+ onViewAll={() => handleViewAllBasicNotifications()}
+ >
+ {basicItems.map(({ id, ...item }) => (
+ handleClickBasicNotification(id)}
+ />
+ ))}
+
+ }
+ />
+ }
+ />
+
+ navigate(path)}
+ primaryContent={
+ <>
+ handleMarkAllUrgentNotificationsRead()}
+ onViewAll={() => handleViewAllUrgentNotifications()}
+ >
+ {urgentItems.map(({ id, ...item }) => (
+ handleClickUrgentNotification(id)}
+ />
+ ))}
+
+ }
+ />
+ }
+ />
+
+ navigate(path)}
+ primaryContent={
+ handleMarkAllNotificationTypesRead()}
+ onViewAll={() => handleViewAllNotificationTypes()}
+ >
+ {allTypeItems.map(({ id, ...item }) => (
+ handleClickNotificationType(id)}
+ />
+ ))}
+
+ }
+ />
+ }
+ />
+
+ );
+}
diff --git a/apps/prs/react/src/routes/everything-b.tsx b/apps/prs/react/src/routes/everything-b.tsx
index f8360e2c7b..c8e9f9f747 100644
--- a/apps/prs/react/src/routes/everything-b.tsx
+++ b/apps/prs/react/src/routes/everything-b.tsx
@@ -38,9 +38,7 @@ import {
GoabAppFooterMetaSection,
GoabAppFooterNavSection,
GoabFileUploadInput,
- GoabFileUploadCard,
GoabSideMenuHeading,
- GoabAccordion,
GoabSkeleton,
GoabCheckbox,
GoabFormStep,
@@ -53,11 +51,9 @@ import {
GoabTableSortHeader,
GoabGrid,
} from "@abgov/react-components";
-import "@abgov/style";
import {
GoabDropdownOnChangeDetail,
GoabInputOnChangeDetail,
- GoabSkeletonSize,
GoabTextAreaOnChangeDetail,
} from "@abgov/ui-components-common";
@@ -81,7 +77,7 @@ export function EverythingBRoute() {
const [step, setStep] = useStateNotification panel
+ +Basic notification panel
+With urgent notifications
+Notification type badges
+@@ -1133,6 +1130,17 @@ export function EverythingRoute(): JSX.Element { ))} +
Drawer
diff --git a/apps/prs/react/src/routes/features/feat2885.tsx b/apps/prs/react/src/routes/features/feat2885.tsx index bed09d78b3..c5863f9a5b 100644 --- a/apps/prs/react/src/routes/features/feat2885.tsx +++ b/apps/prs/react/src/routes/features/feat2885.tsx @@ -1,4 +1,4 @@ -import { useState, useEffect } from "react"; +import { useState } from "react"; import { GoabIconButton, GoabWorkSideMenu, @@ -7,9 +7,6 @@ import { GoabWorkSideNotificationPanel, } from "@abgov/react-components"; -// ?url suffix tells Vite to resolve the path without injecting the CSS -import v2TokensUrl from "@abgov/design-tokens-v2/dist/tokens.css?url"; - type Notification = { id: string; title: string; @@ -23,18 +20,6 @@ type Notification = { export function Feat2885Route() { const [menuOpen, setMenuOpen] = useState(true); - // Dynamically load v2 design tokens only while this page is mounted, - // so they don't leak into other routes in the SPA. - useEffect(() => { - const link = document.createElement("link"); - link.rel = "stylesheet"; - link.href = v2TokensUrl; - document.head.appendChild(link); - return () => { - document.head.removeChild(link); - }; - }, []); - // Helper to get date at specific days ago const daysAgo = (days: number, hours = 0) => { const date = new Date(); diff --git a/apps/prs/react/src/routes/features/feat3229.tsx b/apps/prs/react/src/routes/features/feat3229.tsx index a84e8c5285..3d380f26f9 100644 --- a/apps/prs/react/src/routes/features/feat3229.tsx +++ b/apps/prs/react/src/routes/features/feat3229.tsx @@ -1,4 +1,4 @@ -import { useState, useEffect } from "react"; +import { useState } from "react"; import { GoabBadge, GoabBlock, @@ -9,7 +9,6 @@ import { } from "@abgov/react-components"; import { GoabMenuButtonOnActionDetail } from "@abgov/ui-components-common"; -import v2TokensUrl from "@abgov/design-tokens-v2/dist/tokens.css?url"; // Menu actions with icon + text const menuActionsWithIcons = ( @@ -34,49 +33,6 @@ const menuActionsTextOnly = ( export function Feat3229Route() { const [lastAction, setLastAction] = useState
+
+ Feature 3636: Accordion actions slot and list view variant
+
+
+ The GoAAccordion component now includes an optional slot for action buttons in the
+ header, as well as a new "list view" variant that features a filled header
+ background and hover state.
+
+
+
+ This example mixes badges and controls inside the actions slot.
+
+
+
+
+
+ Actions slot examples
+
+
+ Edit
+
+ }
+ >
+
+ This example places a button in the actions slot while keeping heading text
+ and content as standard body copy.
+
+
+
+
+
+ View all
+
+
+ }
+ >
+
+ Heading content examples
+
+
+ Preview
+
+ }
+ open
+ >
+
+ The heading content slot can display status indicators such as badges.
+
+
+
+
+
+ }
+ actions={
+
+
+ Manage
+
+
+ }
+ >
+
+ Icon position and fixed width examples
+
+
+ A wider fixed-width accordion with the icon moved to the right side.
+
+
+
+
+
+ Open
+
+ }
+ open
+ >
+
+ A narrow fixed-width accordion using the default icon position.
+
+
+
+
+
+ Details
+
+
+ }
+ open
+ >
+
+ Filled/List View Style
+ stuff goes in here
+
+
+ stuff goes in here
+
+ stuff goes in here
+
+ stuff goes in here
+
+
+
+
+ 1 Comment(s)
+
+
+ View
+
+
+ }
+ open
+ >
+
+
+ 4 Comment(s)
+
+
+ View
+
+
+ }
+ open
+ >
+
+
+ 3 Comment(s)
+
+
+ View
+
+
+ }
+ open
+ >
+
+
+ 8 Comment(s)
+
+
+ View
+
+
+ }
+ open
+ >
+ Multi-line Heading with Centered Chevron
+
+
+
+ 1 Comment(s)
+
+
+ View
+
+
+ }
+ >
+
+
+ 1 Comment(s)
+
+
+ View
+
+
+ }
+ >
+ + + 👀 + + The chevron should be centered in the heading +
+ +
+
+ 1 Comment(s)
+
+
+ View
+
+
+ }
+ iconPosition="right"
+ >
+ + + 👀 + + The chevron should be centered here +
+ ++ + 👀 + + The chevron should be centered here +
+ ++ + 👀 + + The chevron should be centered here +
++ + 👀 + + The chevron should be centered here +
+ ++ + 👀 + + The chevron should be centered here +
+ ++ + 👀 + + The chevron should be centered here +
+ ++ + 👀 + + The chevron should be centered here +
+ +
+
+ 1 Comment(s)
+
+
+ View
+
+
+ }
+ secondaryText="Secondary text that is long enough to wrap onto multiple lines and push the heading content and actions down"
+ >
+ + + 👀 + + The chevron should be centered here +
+ +
+
+ 1 Comment(s)
+
+
+ View
+
+
+ }
+ secondaryText="Secondary text that is long enough to wrap onto multiple lines and push the heading content and actions down"
+ iconPosition="right"
+ >
+ + + 👀 + + The chevron should be centered here +
+ + + + ); +} diff --git a/apps/prs/react/src/routes/features/feat3814.tsx b/apps/prs/react/src/routes/features/feat3814.tsx new file mode 100644 index 0000000000..b4d3b6f896 --- /dev/null +++ b/apps/prs/react/src/routes/features/feat3814.tsx @@ -0,0 +1,75 @@ +import { + GoabBadge, + GoabContainer, + GoabText, + GoabWorkSideMenu, + GoabWorkSideMenuItem, +} from "@abgov/react-components"; + +export function Feat3814Route() { + return ( +
+
+ Feature 3814: Work Side Menu trailingContent slot
+
+
+
+ This page demonstrates the new trailingContent slot on Work Side Menu Item. The
+ first item shows a keyboard shortcut hint and the second item shows a badge.
+
+
+
+
+
+ );
+}
+
+export default Feat3814Route;
diff --git a/apps/prs/react/src/styles.css b/apps/prs/react/src/styles.css
index 90d4ee0072..4b7fecca73 100644
--- a/apps/prs/react/src/styles.css
+++ b/apps/prs/react/src/styles.css
@@ -1 +1,4 @@
/* You can add global styles to this file, and also import other style files */
+@import "../../../../dist/libs/web-components/index.css";
+@import "@abgov/design-tokens-v2/dist/tokens.css";
+@import "@abgov/design-tokens-v2/dist/dark-theme.css";
diff --git a/apps/prs/web/src/app/App.svelte b/apps/prs/web/src/app/App.svelte
index d26edda9d7..d7be253032 100644
--- a/apps/prs/web/src/app/App.svelte
+++ b/apps/prs/web/src/app/App.svelte
@@ -1,8 +1,10 @@
@@ -13,5 +15,6 @@
+
+
+ Ctrl K
+
+ }
+ />
+
+
+ Issue 3605
+ Use
+
+ For every section: Tab should show the focus ring with the correct gap/offset.
+ Click should not leave a lingering ring. Mouse-down (
+
+
+ + +
+ 1. MicrositeHeader —
+ Tab through the links inside the header. Click any link.
+
+ Report a problem
+
+
+ Report a problem
+
+
+
+
+ + +
+ 2. Chip —
+ V1 Chip (deprecated, still in scope per brief).
+ FilterChip V2 (production)
+
+ Chip div is
+ FilterChip V1 (fixed in this PR)
+
+ Whole chip is
+
+
+
+ + +
+ 3. Plain link reset — use
+
+ Unstyled anchors pick up the global reset from
+
+
+
+
+ + +
+ 4. TextArea error state —
+
+ Tab into each error text area. Click into each. The
+ V1 error
+ V2 error
+
+
+
+ + +
+ 5. Button — drop
+
+ Click and Tab each variant across V1 and V2. Watch for lingering rings after mouse-up.
+
+
+ V1 — default
+ V1 — destructive
+ V1 — inverse (on dark bg)
+ V2 — default
+ V2 — destructive
+ V2 — inverse (on dark bg)
+
+
+
+ + +
+ 6. Checkbox — drop
+
+ V1 had 10 rules pairing
+
+ V1 — normal
+ V1 — error
+ V2 — normal
+ V2 — error
+
+
+
+ + +
+ 7. Link — outer-container ring gated by JS modality check
+
+ Ring sits on the outer container so it wraps icon + text together, matching pre-#3605
+ visuals. Pure CSS couldn't carry keyboard-only semantics across the slot boundary
+ (
+
+ Plain links
+
+
+ Links with leading icons
+
+
+ Links with trailing icons
+
+
+ Links with both icons
+
+
+
+
+ + +
+ 8. Notification —
+
+ 8 rules (V1 + V2 variants) styled slotted anchors on
+
+ V1 Notifications
+
+ Info notification with a link inside.
+
+
+ Important notification with a link inside.
+
+
+ V2 Notifications
+
+ Information high with a link inside.
+
+
+ Important high with a link inside.
+
+
+ Emergency high with a link inside.
+
+
+
+
+ + +
+ 9. Tooltip —
+
+ Previously mouse-clicking the tooltip trigger revealed the tooltip. Now hover for mouse,
+ keyboard focus for keyboard (standard tooltip behavior).
+
+
+
+
+ + +
+ 10. Details —
+
+ Previously clicking the summary left a hover-ish style. Now click just toggles open;
+ keyboard focus shows the focused look.
+
+
+ Content inside the details component.
+
+
+
+
+ + +
+ 11. DataGrid — realistic table usage
+
+ Typical pattern:
+
+
+
+
+ Name
+ Role
+ Status
+ Actions
+
+
+
+
+ Alice Johnson
+ Developer
+ View
+
+ Bob Smith
+ Designer
+ View
+
+ Carol White
+ Manager
+ View
+
+ David Brown
+ Analyst
+ View
+
+
+
+
+ DataGrid around cards (layout mode)
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 6599ce45c9..57d9c920d4 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -88,10 +88,6 @@ category: inputs-and-actions # determines nav section
tags: [action, submit]
relatedComponents: [button-group, icon-button]
figmaUrl: https://www.figma.com/...
-githubUrl: https://github.com/...
-webComponentTag: goa-button
-reactClassName: GoabButton
-angularSelector: goab-button
hidden: true # optional — hide from nav (used for subcomponents, deprecated, internal)
subcomponent: true # optional — show API on parent component page
---
@@ -219,6 +215,13 @@ export const buttonConfigurations: ComponentConfigurations = {
This is a common source of errors when writing configuration code since all three are in the same file.
+**Preview customization:** Two optional fields on `ComponentConfigurations` let you customize the sandbox preview without affecting the code snippet users see:
+
+- `previewStyle` — CSS applied to the preview container (e.g. background color, flex layout). Example: workspace components use a grey background with a content card to simulate the app layout.
+- `previewWrapper` — HTML template that wraps the component code in the preview only. Use `{{slot}}` as the placeholder for the component code. The code snippet shown to users contains just the component code, not the wrapper.
+
+See `work-side-notification-panel.ts` or `work-side-menu.ts` for examples.
+
---
## How to: common changes
@@ -261,7 +264,6 @@ status: stable
category: structure-and-navigation
relatedComponents:
- tab # <-- this is how the parent discovers the subcomponent
-webComponentTag: goa-tabs
---
```
@@ -277,7 +279,6 @@ hidden: true # not shown in nav
subcomponent: true # API appears on parent page
relatedComponents:
- tabs
-webComponentTag: goa-tab
---
```
@@ -289,19 +290,11 @@ Result: the Tabs page shows "Tab Props", "Tab Slots" (and "Tab Events" if any ex
2. Add its slug to the parent's `relatedComponents` array
3. Ensure API data exists. If the Svelte component has its own directory (`libs/web-components/src/components/my-sub/`), the extraction script handles it automatically. If it's a nested file inside the parent's directory (like `WorkSideMenuGroup.svelte` inside `work-side-menu/`), you need to manually create the API JSON in `generated/component-apis/my-sub.json`
-**Current subcomponent mappings:**
-
-| Parent | Subcomponents |
-| -------------- | ----------------------------------------- |
-| Header | App Header Menu |
-| File uploader | File Upload Card |
-| Footer | Footer Meta Section, Footer Nav Section |
-| Form stepper | Form Step |
-| Menu button | Menu Action |
-| Radio | Radio Item |
-| Side menu | Side Menu Group, Side Menu Heading |
-| Tabs | Tab |
-| Work Side Menu | Work Side Menu Group, Work Side Menu Item |
+To see all current subcomponent mappings, search for `subcomponent: true` in the MDX files:
+
+```bash
+grep -rl "subcomponent: true" docs/src/content/components/
+```
### Hide a component from navigation
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 6523a7cc5a..9a7aa8fe73 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -5,6 +5,8 @@ import path from "node:path";
import react from "@astrojs/react";
import mdx from "@astrojs/mdx";
+import { buildAliasRedirects } from "./src/scripts/aliases-to-redirects.mjs";
+
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const workspaceRoot = path.resolve(__dirname, "..");
@@ -29,10 +31,25 @@ export default defineConfig({
"/examples/show-multiple-actions-in-a-compact-table",
"/examples/communicate-a-future-service-outage":
"/examples/notify-the-user-of-a-future-service-outage",
+ // workspace-product / public-form-product were stub entries that existed
+ // only to populate the size:product card on /examples/. The grid now
+ // synthesizes those cards directly from the productTypes collection, so
+ // these slugs no longer resolve. Redirect to the real overviews in case
+ // anything cached or bookmarked the old URLs from the PR preview.
+ "/examples/workspace-product": "/examples/workspace",
+ "/examples/public-form-product": "/examples/public-form",
+ // Old "give-{background,context}-..." slugs once redirected to the
+ // give-more-information-...-{a,b} variants. Those variants have since
+ // been folded into question-page, so route directly there to avoid
+ // a two-hop chain through the alias-derived redirects below.
"/examples/give-background-information-before-asking-a-question":
- "/examples/give-more-information-before-asking-a-question-a",
+ "/examples/question-page",
"/examples/give-context-before-asking-a-long-answer-question":
- "/examples/give-more-information-before-asking-a-question-b",
+ "/examples/question-page",
+ // Auto-derived redirects from `aliases` frontmatter on examples and
+ // productTypes entries. Single source of truth lives in MDX; adding
+ // an alias to an entry creates the redirect on the next build.
+ ...buildAliasRedirects(),
},
build: {
chunkSizeWarningLimit: 1000,
diff --git a/docs/generated/component-apis/accordion.json b/docs/generated/component-apis/accordion.json
index 132e50b852..913aae44d2 100644
--- a/docs/generated/component-apis/accordion.json
+++ b/docs/generated/component-apis/accordion.json
@@ -1,131 +1,366 @@
{
"componentSlug": "accordion",
"extractedFrom": "libs/web-components/src/components/accordion/Accordion.svelte",
- "props": [
- {
- "name": "open",
- "type": "boolean",
- "required": false,
- "default": "false",
- "description": "Sets the state of the accordion container open or closed."
- },
- {
- "name": "heading",
- "type": "string",
- "required": true,
- "default": "",
- "description": "Sets the heading text."
- },
- {
- "name": "secondarytext",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Sets secondary text."
- },
- {
- "name": "headingSize",
- "type": "\"small\" | \"medium\"",
- "typeLabel": "GoabAccordionHeadingSize",
- "values": [
- "small",
- "medium"
+ "frameworks": {
+ "react": {
+ "props": [
+ {
+ "name": "heading",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the heading text."
+ },
+ {
+ "name": "headingSize",
+ "type": "GoabAccordionHeadingSize",
+ "required": false,
+ "default": "small",
+ "description": "Sets the heading size of the accordion container heading."
+ },
+ {
+ "name": "headingType",
+ "type": "GoabAccordionHeadingType",
+ "required": false,
+ "default": "normal",
+ "description": "Sets the accordion style variant."
+ },
+ {
+ "name": "iconPosition",
+ "type": "GoabAccordionIconPosition",
+ "required": false,
+ "default": "left",
+ "description": "Sets the position of the expand/collapse icon."
+ },
+ {
+ "name": "maxWidth",
+ "type": "string",
+ "required": false,
+ "default": "none",
+ "description": "Sets the maximum width of the accordion."
+ },
+ {
+ "name": "mb",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "ml",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "mr",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "mt",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "open",
+ "type": "boolean",
+ "required": false,
+ "default": null,
+ "description": "Sets the state of the accordion container open or closed."
+ },
+ {
+ "name": "secondaryText",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets secondary text displayed alongside the heading."
+ },
+ {
+ "name": "testId",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets a data-testid attribute for automated testing."
+ }
],
- "required": false,
- "default": "small",
- "description": "Sets the heading size of the accordion container heading."
- },
- {
- "name": "id",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Unique identifier for the accordion."
- },
- {
- "name": "maxWidth",
- "type": "string",
- "required": false,
- "default": "none",
- "description": "Sets the maximum width of the accordion."
- },
- {
- "name": "testId",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Sets a data-testid attribute for automated testing."
- },
- {
- "name": "mt",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Top margin."
- },
- {
- "name": "mr",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Right margin."
- },
- {
- "name": "mb",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": "xs",
- "description": "Bottom margin."
- },
- {
- "name": "ml",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Left margin."
- },
- {
- "name": "iconposition",
- "type": "\"left\" | \"right\"",
- "values": [
- "left",
- "right"
+ "events": [
+ {
+ "name": "onChange",
+ "type": "(open: boolean) => void",
+ "description": "Callback fired when the accordion is opened or closed. Receives the new open state as a boolean.",
+ "frameworks": [
+ "react"
+ ]
+ }
],
- "required": false,
- "default": "left",
- "description": "Sets the position of the expand/collapse icon."
- }
- ],
- "events": [
- {
- "name": "onChange",
- "type": "(event: Event) => void",
- "description": "",
- "frameworks": [
- "react"
+ "slots": [
+ {
+ "name": "actions",
+ "type": "ReactNode",
+ "description": "Sets content rendered in the accordion heading, right-aligned before the expand/collapse icon.",
+ "required": false
+ },
+ {
+ "name": "headingContent",
+ "type": "ReactNode",
+ "description": "Sets content rendered within the accordion heading, alongside the heading text.",
+ "required": false
+ }
]
},
- {
- "name": "_change",
- "type": "CustomEvent",
- "description": "",
- "frameworks": [
- "angular"
+ "angular": {
+ "props": [
+ {
+ "name": "heading",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the heading text."
+ },
+ {
+ "name": "headingSize",
+ "type": "GoabAccordionHeadingSize",
+ "required": false,
+ "default": null,
+ "description": "Sets the heading size of the accordion container heading."
+ },
+ {
+ "name": "headingType",
+ "type": "GoabAccordionHeadingType",
+ "required": false,
+ "default": null,
+ "description": "Sets the accordion style variant."
+ },
+ {
+ "name": "iconPosition",
+ "type": "GoabAccordionIconPosition",
+ "required": false,
+ "default": null,
+ "description": "Sets the position of the expand/collapse icon."
+ },
+ {
+ "name": "maxWidth",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the maximum width of the accordion."
+ },
+ {
+ "name": "mb",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the bottom margin spacing token."
+ },
+ {
+ "name": "ml",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the left margin spacing token."
+ },
+ {
+ "name": "mr",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the right margin spacing token."
+ },
+ {
+ "name": "mt",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the top margin spacing token."
+ },
+ {
+ "name": "open",
+ "type": "boolean",
+ "required": false,
+ "default": null,
+ "description": "Sets the state of the accordion container open or closed."
+ },
+ {
+ "name": "secondaryText",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets secondary text."
+ },
+ {
+ "name": "testId",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the data-testid attribute for automated testing."
+ }
+ ],
+ "events": [
+ {
+ "name": "onChange",
+ "type": "(event: boolean) => void",
+ "description": "Emits when the accordion opens or closes. Emits the new open state as a boolean.",
+ "frameworks": [
+ "angular"
+ ]
+ }
+ ],
+ "slots": [
+ {
+ "name": "actions",
+ "type": "TemplateRef",
+ "description": "Sets content rendered in the accordion heading, right-aligned before the expand/collapse icon.",
+ "required": false
+ },
+ {
+ "name": "headingContent",
+ "type": "TemplateRef",
+ "description": "Sets content rendered within the accordion heading, alongside the heading text.",
+ "required": false
+ }
]
- }
- ],
- "slots": [
- {
- "name": "default",
- "description": ""
},
- {
- "name": "headingcontent",
- "description": ""
+ "webComponents": {
+ "props": [
+ {
+ "name": "heading",
+ "type": "string",
+ "required": true,
+ "default": "",
+ "description": "Sets the heading text."
+ },
+ {
+ "name": "heading-type",
+ "type": "\"normal\" | \"filled\"",
+ "typeLabel": "GoabAccordionHeadingType",
+ "values": [
+ "normal",
+ "filled"
+ ],
+ "required": false,
+ "default": "normal",
+ "description": "Sets the accordion style variant. @default \"normal\""
+ },
+ {
+ "name": "headingsize",
+ "type": "\"small\" | \"medium\"",
+ "typeLabel": "GoabAccordionHeadingSize",
+ "values": [
+ "small",
+ "medium"
+ ],
+ "required": false,
+ "default": "small",
+ "description": "Sets the heading size of the accordion container heading."
+ },
+ {
+ "name": "iconposition",
+ "type": "\"left\" | \"right\"",
+ "typeLabel": "GoabAccordionIconPosition",
+ "values": [
+ "left",
+ "right"
+ ],
+ "required": false,
+ "default": "left",
+ "description": "Sets the position of the expand/collapse icon."
+ },
+ {
+ "name": "id",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Unique identifier for the accordion."
+ },
+ {
+ "name": "maxwidth",
+ "type": "string",
+ "required": false,
+ "default": "none",
+ "description": "Sets the maximum width of the accordion."
+ },
+ {
+ "name": "mb",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": "xs",
+ "description": "Bottom margin."
+ },
+ {
+ "name": "ml",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Left margin."
+ },
+ {
+ "name": "mr",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Right margin."
+ },
+ {
+ "name": "mt",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Top margin."
+ },
+ {
+ "name": "open",
+ "type": "boolean",
+ "required": false,
+ "default": "false",
+ "description": "Sets the state of the accordion container open or closed."
+ },
+ {
+ "name": "secondarytext",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Sets secondary text."
+ },
+ {
+ "name": "testid",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Sets a data-testid attribute for automated testing."
+ }
+ ],
+ "events": [
+ {
+ "name": "_change",
+ "type": "CustomEvent<{ open: boolean }>",
+ "description": "",
+ "frameworks": [
+ "webComponents"
+ ]
+ }
+ ],
+ "slots": [
+ {
+ "name": "actions",
+ "description": "Sets content rendered in the accordion heading, right-aligned before the expand/collapse icon.",
+ "required": false
+ },
+ {
+ "name": "headingcontent",
+ "description": "Sets content rendered within the accordion heading, alongside the heading text.",
+ "required": false
+ }
+ ]
}
- ]
+ }
}
\ No newline at end of file
diff --git a/docs/generated/component-apis/app-header-menu.json b/docs/generated/component-apis/app-header-menu.json
index 1e8fca8a88..def03aea4c 100644
--- a/docs/generated/component-apis/app-header-menu.json
+++ b/docs/generated/component-apis/app-header-menu.json
@@ -1,57 +1,124 @@
{
"componentSlug": "app-header-menu",
"extractedFrom": "libs/web-components/src/components/app-header-menu/AppHeaderMenu.svelte",
- "props": [
- {
- "name": "heading",
- "type": "string",
- "required": true,
- "default": null,
- "description": "The menu heading text displayed as the dropdown trigger."
- },
- {
- "name": "leadingIcon",
- "type": "GoAIconType",
- "typeLabel": "GoAIconType",
- "required": true,
- "default": null,
- "description": "Icon displayed before the heading text."
- },
- {
- "name": "type",
- "type": "\"primary\" | \"secondary\"",
- "values": [
- "primary",
- "secondary"
+ "frameworks": {
+ "react": {
+ "props": [
+ {
+ "name": "heading",
+ "type": "string",
+ "required": true,
+ "default": null,
+ "description": "The menu heading text displayed as the dropdown trigger."
+ },
+ {
+ "name": "leadingIcon",
+ "type": "GoabIconType",
+ "required": false,
+ "default": null,
+ "description": "Icon displayed before the heading text."
+ },
+ {
+ "name": "slotName",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Slot name used to place this menu in the correct slot of the parent component."
+ },
+ {
+ "name": "testId",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets a data-testid attribute for automated testing."
+ }
],
- "required": false,
- "default": "primary",
- "description": "The menu style variant. Primary uses bold text, secondary uses regular weight."
+ "events": [],
+ "slots": []
},
- {
- "name": "version",
- "type": "\"1\" | \"2\"",
- "values": [
- "1",
- "2"
+ "angular": {
+ "props": [
+ {
+ "name": "heading",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "The menu heading text displayed as the dropdown trigger."
+ },
+ {
+ "name": "leadingIcon",
+ "type": "GoabIconType",
+ "required": false,
+ "default": null,
+ "description": "Icon displayed before the heading text."
+ },
+ {
+ "name": "slotName",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the slot name for the component."
+ },
+ {
+ "name": "testId",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets a data-testid attribute for automated testing."
+ }
],
- "required": false,
- "default": "1",
- "description": "The header version this menu is used with."
+ "events": [],
+ "slots": []
},
- {
- "name": "testId",
- "type": "string",
- "required": false,
- "default": "rootEl",
- "description": "Sets a data-testid attribute for automated testing."
- }
- ],
- "events": [],
- "slots": [
- {
- "name": "default",
- "description": ""
+ "webComponents": {
+ "props": [
+ {
+ "name": "heading",
+ "type": "string",
+ "required": true,
+ "default": null,
+ "description": "The menu heading text displayed as the dropdown trigger."
+ },
+ {
+ "name": "leadingicon",
+ "type": "GoabIconType",
+ "typeLabel": "GoabIconType",
+ "required": true,
+ "default": null,
+ "description": "Icon displayed before the heading text."
+ },
+ {
+ "name": "testid",
+ "type": "string",
+ "required": false,
+ "default": "rootEl",
+ "description": "Sets a data-testid attribute for automated testing."
+ },
+ {
+ "name": "type",
+ "type": "\"primary\" | \"secondary\"",
+ "values": [
+ "primary",
+ "secondary"
+ ],
+ "required": false,
+ "default": "primary",
+ "description": "The menu style variant. Primary uses bold text, secondary uses regular weight."
+ },
+ {
+ "name": "version",
+ "type": "\"1\" | \"2\"",
+ "values": [
+ "1",
+ "2"
+ ],
+ "required": false,
+ "default": "1",
+ "description": "Design system version for styling."
+ }
+ ],
+ "events": [],
+ "slots": []
}
- ]
+ }
}
\ No newline at end of file
diff --git a/docs/generated/component-apis/app-header-navigation.json b/docs/generated/component-apis/app-header-navigation.json
deleted file mode 100644
index 8d8a1251fc..0000000000
--- a/docs/generated/component-apis/app-header-navigation.json
+++ /dev/null
@@ -1,38 +0,0 @@
-{
- "componentSlug": "app-header-navigation",
- "extractedFrom": "libs/web-components/src/components/app-header-navigation/AppHeaderNavigation.svelte",
- "props": [
- {
- "name": "version",
- "type": "\"1\" | \"2\"",
- "values": [
- "1",
- "2"
- ],
- "required": false,
- "default": "1",
- "description": ""
- },
- {
- "name": "windowWidth",
- "type": "number",
- "required": true,
- "default": null,
- "description": ""
- },
- {
- "name": "mobile",
- "type": "boolean",
- "required": false,
- "default": "false",
- "description": ""
- }
- ],
- "events": [],
- "slots": [
- {
- "name": "default",
- "description": ""
- }
- ]
-}
\ No newline at end of file
diff --git a/docs/generated/component-apis/app-header.json b/docs/generated/component-apis/app-header.json
index 164f93138c..77e42d64f3 100644
--- a/docs/generated/component-apis/app-header.json
+++ b/docs/generated/component-apis/app-header.json
@@ -1,106 +1,258 @@
{
"componentSlug": "app-header",
"extractedFrom": "libs/web-components/src/components/app-header/AppHeader.svelte",
- "props": [
- {
- "name": "version",
- "type": "\"1\" | \"2\"",
- "values": [
- "1",
- "2"
+ "frameworks": {
+ "react": {
+ "props": [
+ {
+ "name": "fullMenuBreakpoint",
+ "type": "number",
+ "required": false,
+ "default": null,
+ "description": "Sets the breakpoint in px for the full menu to display."
+ },
+ {
+ "name": "heading",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Set the service name to display in the app header."
+ },
+ {
+ "name": "maxContentWidth",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Maximum width of the content area."
+ },
+ {
+ "name": "secondaryText",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "V2 only: Secondary text displayed under the service name."
+ },
+ {
+ "name": "testId",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets a data-testid attribute for automated testing."
+ },
+ {
+ "name": "url",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Set the URL to link from the alberta.ca logo. A full url is required."
+ }
],
- "required": false,
- "default": "1",
- "description": ""
- },
- {
- "name": "heading",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Set the service name to display in the app header."
- },
- {
- "name": "secondarytext",
- "type": "string",
- "required": false,
- "default": "",
- "description": "V2 only: Secondary text displayed under the service name."
- },
- {
- "name": "url",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Set the URL to link from the alberta.ca logo. A full url is required."
- },
- {
- "name": "testId",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Sets a data-testid attribute for automated testing."
- },
- {
- "name": "maxcontentwidth",
- "type": "any",
- "required": false,
- "default": "",
- "description": "Maximum width of the content area."
- },
- {
- "name": "fullmenubreakpoint",
- "type": "number",
- "required": false,
- "default": "TABLET_BP",
- "description": "Sets the breakpoint in px for the full menu to display."
- },
- {
- "name": "hasmenuclickhandler",
- "type": "boolean",
- "required": false,
- "default": "false",
- "description": "When true, clicking the menu button dispatches _menuClick event instead of toggling the menu. Use for custom menu handling."
- }
- ],
- "events": [
- {
- "name": "onMenuClick",
- "type": "(event: Event) => void",
- "description": "",
- "frameworks": [
- "react"
+ "events": [
+ {
+ "name": "onMenuClick",
+ "type": "() => void",
+ "description": "Callback fired when the menu button is clicked. When provided, clicking the menu button dispatches a custom event instead of toggling the menu.",
+ "frameworks": [
+ "react"
+ ]
+ }
+ ],
+ "slots": [
+ {
+ "name": "banner",
+ "description": "",
+ "required": false
+ },
+ {
+ "name": "navigation",
+ "description": "",
+ "required": false
+ },
+ {
+ "name": "phase",
+ "description": "",
+ "required": false
+ },
+ {
+ "name": "utilities",
+ "description": "",
+ "required": false
+ }
]
},
- {
- "name": "_menuClick",
- "type": "CustomEvent",
- "description": "",
- "frameworks": [
- "angular"
+ "angular": {
+ "props": [
+ {
+ "name": "fullMenuBreakpoint",
+ "type": "number",
+ "required": false,
+ "default": null,
+ "description": "Sets the breakpoint in px for the full menu to display."
+ },
+ {
+ "name": "heading",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the service name to display in the app header."
+ },
+ {
+ "name": "maxContentWidth",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Maximum width of the content area."
+ },
+ {
+ "name": "secondaryText",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "V2 only: Secondary text displayed under the service name."
+ },
+ {
+ "name": "testId",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets a data-testid attribute for automated testing."
+ },
+ {
+ "name": "url",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the URL to link from the alberta.ca logo. A full url is required."
+ }
+ ],
+ "events": [
+ {
+ "name": "onMenuClick",
+ "type": "() => void",
+ "description": "Emits when the menu button is clicked. Used for custom menu handling.",
+ "frameworks": [
+ "angular"
+ ]
+ }
+ ],
+ "slots": [
+ {
+ "name": "banner",
+ "description": "",
+ "required": false
+ },
+ {
+ "name": "navigation",
+ "description": "",
+ "required": false
+ },
+ {
+ "name": "phase",
+ "description": "",
+ "required": false
+ },
+ {
+ "name": "utilities",
+ "description": "",
+ "required": false
+ }
]
- }
- ],
- "slots": [
- {
- "name": "default",
- "description": ""
- },
- {
- "name": "banner",
- "description": ""
- },
- {
- "name": "phase",
- "description": ""
},
- {
- "name": "utilities",
- "description": ""
- },
- {
- "name": "navigation",
- "description": ""
+ "webComponents": {
+ "props": [
+ {
+ "name": "fullmenubreakpoint",
+ "type": "number",
+ "required": false,
+ "default": "TABLET_BP",
+ "description": "Sets the breakpoint in px for the full menu to display."
+ },
+ {
+ "name": "hasmenuclickhandler",
+ "type": "boolean",
+ "required": false,
+ "default": "false",
+ "description": "When true, clicking the menu button dispatches _menuClick event instead of toggling the menu. Use for custom menu handling."
+ },
+ {
+ "name": "heading",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Set the service name to display in the app header."
+ },
+ {
+ "name": "maxcontentwidth",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Maximum width of the content area."
+ },
+ {
+ "name": "secondarytext",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "V2 only: Secondary text displayed under the service name."
+ },
+ {
+ "name": "testid",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Sets a data-testid attribute for automated testing."
+ },
+ {
+ "name": "url",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Set the URL to link from the alberta.ca logo. A full url is required."
+ },
+ {
+ "name": "version",
+ "type": "\"1\" | \"2\"",
+ "values": [
+ "1",
+ "2"
+ ],
+ "required": false,
+ "default": "1",
+ "description": "Design system version for styling."
+ }
+ ],
+ "events": [
+ {
+ "name": "_menuClick",
+ "type": "CustomEvent",
+ "description": "",
+ "frameworks": [
+ "webComponents"
+ ]
+ }
+ ],
+ "slots": [
+ {
+ "name": "banner",
+ "description": "",
+ "required": false
+ },
+ {
+ "name": "navigation",
+ "description": "",
+ "required": false
+ },
+ {
+ "name": "phase",
+ "description": "",
+ "required": false
+ },
+ {
+ "name": "utilities",
+ "description": "",
+ "required": false
+ }
+ ]
}
- ]
+ }
}
\ No newline at end of file
diff --git a/docs/generated/component-apis/badge.json b/docs/generated/component-apis/badge.json
index cc16d9e39b..ca313bc451 100644
--- a/docs/generated/component-apis/badge.json
+++ b/docs/generated/component-apis/badge.json
@@ -1,140 +1,334 @@
{
"componentSlug": "badge",
"extractedFrom": "libs/web-components/src/components/badge/Badge.svelte",
- "props": [
- {
- "name": "type",
- "type": "\"information\" | \"important\" | \"emergency\" | \"success\" | \"dark\" | \"midtone\" | \"light\" | \"archived\" | \"aqua\" | \"black\" | \"blue\" | \"green\" | \"orange\" | \"pink\" | \"red\" | \"violet\" | \"white\" | \"yellow\" | \"aqua-light\" | \"black-light\" | \"blue-light\" | \"green-light\" | \"orange-light\" | \"pink-light\" | \"red-light\" | \"violet-light\" | \"yellow-light\" | \"sky\" | \"prairie\" | \"lilac\" | \"pasture\" | \"sunset\" | \"dawn\" | \"default\"",
- "typeLabel": "GoabBadgeType",
- "values": [
- "information",
- "important",
- "emergency",
- "success",
- "dark",
- "midtone",
- "light",
- "archived",
- "aqua",
- "black",
- "blue",
- "green",
- "orange",
- "pink",
- "red",
- "violet",
- "white",
- "yellow",
- "aqua-light",
- "black-light",
- "blue-light",
- "green-light",
- "orange-light",
- "pink-light",
- "red-light",
- "violet-light",
- "yellow-light",
- "sky",
- "prairie",
- "lilac",
- "pasture",
- "sunset",
- "dawn",
- "default"
+ "frameworks": {
+ "react": {
+ "props": [
+ {
+ "name": "ariaLabel",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Accessible label for screen readers."
+ },
+ {
+ "name": "content",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Text label of the badge."
+ },
+ {
+ "name": "emphasis",
+ "type": "GoabBadgeEmphasis",
+ "required": false,
+ "default": "strong",
+ "description": "Sets the visual emphasis. 'subtle' for less prominent, 'strong' for more emphasis."
+ },
+ {
+ "name": "iconType",
+ "type": "GoabIconType",
+ "required": false,
+ "default": null,
+ "description": "Icon type to display in the badge."
+ },
+ {
+ "name": "mb",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "ml",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "mr",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "mt",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "size",
+ "type": "GoabBadgeSize",
+ "required": false,
+ "default": "medium",
+ "description": "Sets the size of the badge."
+ },
+ {
+ "name": "testId",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets a data-testid attribute for automated testing."
+ },
+ {
+ "name": "type",
+ "type": "GoabBadgeType",
+ "required": true,
+ "default": null,
+ "description": "Sets the context and colour of the badge."
+ }
],
- "required": true,
- "default": null,
- "description": "Defines the context and colour of the badge."
+ "events": [],
+ "slots": []
},
- {
- "name": "testId",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Sets a data-testid attribute for automated testing."
- },
- {
- "name": "content",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Text label of the badge."
- },
- {
- "name": "icon",
- "type": "string",
- "required": false,
- "default": "",
- "description": "@deprecated Use icontype instead. Includes an icon in the badge.",
- "deprecated": true
- },
- {
- "name": "icontype",
- "type": "GoAIconType",
- "typeLabel": "GoAIconType",
- "required": false,
- "default": null,
- "description": "Icon type to display in the badge."
- },
- {
- "name": "ariaLabel",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Accessible label for screen readers."
- },
- {
- "name": "size",
- "type": "\"medium\" | \"large\"",
- "typeLabel": "GoabBadgeSize",
- "values": [
- "medium",
- "large"
+ "angular": {
+ "props": [
+ {
+ "name": "ariaLabel",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the accessible label for screen readers."
+ },
+ {
+ "name": "content",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the text label of the badge."
+ },
+ {
+ "name": "emphasis",
+ "type": "GoabBadgeEmphasis",
+ "required": false,
+ "default": "strong",
+ "description": "Sets the visual emphasis. 'subtle' for less prominent, 'strong' for more emphasis."
+ },
+ {
+ "name": "iconType",
+ "type": "GoabIconType",
+ "required": false,
+ "default": null,
+ "description": "Sets the icon type to display in the badge."
+ },
+ {
+ "name": "mb",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the bottom margin spacing token."
+ },
+ {
+ "name": "ml",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the left margin spacing token."
+ },
+ {
+ "name": "mr",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the right margin spacing token."
+ },
+ {
+ "name": "mt",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the top margin spacing token."
+ },
+ {
+ "name": "size",
+ "type": "GoabBadgeSize",
+ "required": false,
+ "default": "medium",
+ "description": "Sets the size of the badge."
+ },
+ {
+ "name": "testId",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the data-testid attribute for automated testing."
+ },
+ {
+ "name": "type",
+ "type": "GoabBadgeType",
+ "required": false,
+ "default": null,
+ "description": "Sets the context and colour of the badge."
+ }
],
- "required": false,
- "default": "medium",
- "description": "Sets the size of the badge."
+ "events": [],
+ "slots": []
},
- {
- "name": "emphasis",
- "type": "",
- "required": false,
- "default": "strong",
- "description": "Sets the visual emphasis. 'subtle' for less prominent, 'strong' for more emphasis."
- },
- {
- "name": "mt",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Top margin."
- },
- {
- "name": "mr",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Right margin."
- },
- {
- "name": "mb",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Bottom margin."
- },
- {
- "name": "ml",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Left margin."
+ "webComponents": {
+ "props": [
+ {
+ "name": "arialabel",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Accessible label for screen readers."
+ },
+ {
+ "name": "content",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Text label of the badge."
+ },
+ {
+ "name": "emphasis",
+ "type": "",
+ "required": false,
+ "default": "strong",
+ "description": "Sets the visual emphasis. 'subtle' for less prominent, 'strong' for more emphasis."
+ },
+ {
+ "name": "icontype",
+ "type": "GoabIconType",
+ "typeLabel": "GoabIconType",
+ "required": false,
+ "default": null,
+ "description": "Icon type to display in the badge."
+ },
+ {
+ "name": "justify-content",
+ "type": "\"center\" | \"flex-start\" | \"flex-end\" | \"space-between\" | \"\"",
+ "values": [
+ "center",
+ "flex-start",
+ "flex-end",
+ "space-between"
+ ],
+ "required": false,
+ "default": "",
+ "description": "justify-content value for the badge container."
+ },
+ {
+ "name": "mb",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Bottom margin."
+ },
+ {
+ "name": "min-width",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "min-width value for the badge container (e.g. \"20px\", \"var(--goa-space-m)\")."
+ },
+ {
+ "name": "ml",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Left margin."
+ },
+ {
+ "name": "mr",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Right margin."
+ },
+ {
+ "name": "mt",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Top margin."
+ },
+ {
+ "name": "size",
+ "type": "\"medium\" | \"large\"",
+ "typeLabel": "GoabBadgeSize",
+ "values": [
+ "medium",
+ "large"
+ ],
+ "required": false,
+ "default": "medium",
+ "description": "Sets the size of the badge."
+ },
+ {
+ "name": "testid",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Sets a data-testid attribute for automated testing."
+ },
+ {
+ "name": "type",
+ "type": "\"information\" | \"important\" | \"emergency\" | \"success\" | \"dark\" | \"midtone\" | \"light\" | \"archived\" | \"aqua\" | \"black\" | \"blue\" | \"green\" | \"orange\" | \"pink\" | \"red\" | \"violet\" | \"white\" | \"yellow\" | \"aqua-light\" | \"black-light\" | \"blue-light\" | \"green-light\" | \"orange-light\" | \"pink-light\" | \"red-light\" | \"violet-light\" | \"yellow-light\" | \"sky\" | \"prairie\" | \"lilac\" | \"pasture\" | \"sunset\" | \"dawn\" | \"default\"",
+ "typeLabel": "GoabBadgeType",
+ "values": [
+ "information",
+ "important",
+ "emergency",
+ "success",
+ "dark",
+ "midtone",
+ "light",
+ "archived",
+ "aqua",
+ "black",
+ "blue",
+ "green",
+ "orange",
+ "pink",
+ "red",
+ "violet",
+ "white",
+ "yellow",
+ "aqua-light",
+ "black-light",
+ "blue-light",
+ "green-light",
+ "orange-light",
+ "pink-light",
+ "red-light",
+ "violet-light",
+ "yellow-light",
+ "sky",
+ "prairie",
+ "lilac",
+ "pasture",
+ "sunset",
+ "dawn",
+ "default"
+ ],
+ "required": true,
+ "default": null,
+ "description": "Defines the context and colour of the badge."
+ },
+ {
+ "name": "version",
+ "type": "\"1\" | \"2\"",
+ "typeLabel": "GoabBadgeVersion",
+ "values": [
+ "1",
+ "2"
+ ],
+ "required": false,
+ "default": "1",
+ "description": "Design system version for styling."
+ }
+ ],
+ "events": [],
+ "slots": []
}
- ],
- "events": [],
- "slots": []
+ }
}
\ No newline at end of file
diff --git a/docs/generated/component-apis/block.json b/docs/generated/component-apis/block.json
index 499c8e80e5..7de90b6ce5 100644
--- a/docs/generated/component-apis/block.json
+++ b/docs/generated/component-apis/block.json
@@ -1,105 +1,270 @@
{
"componentSlug": "block",
"extractedFrom": "libs/web-components/src/components/block/Block.svelte",
- "props": [
- {
- "name": "gap",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": "m",
- "description": "Spacing between items. Uses design system spacing tokens."
- },
- {
- "name": "direction",
- "type": "\"row\" | \"column\"",
- "values": [
- "row",
- "column"
+ "frameworks": {
+ "react": {
+ "props": [
+ {
+ "name": "alignment",
+ "type": "GoabBlockAlignment",
+ "required": false,
+ "default": "normal",
+ "description": "Primary axis alignment of child components."
+ },
+ {
+ "name": "direction",
+ "type": "GoabBlockDirection",
+ "required": false,
+ "default": "row",
+ "description": "Stacking direction of child components."
+ },
+ {
+ "name": "gap",
+ "type": "Spacing",
+ "required": false,
+ "default": "m",
+ "description": "Spacing between items. Uses design system spacing tokens."
+ },
+ {
+ "name": "maxWidth",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the maximum width of the block container."
+ },
+ {
+ "name": "mb",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "minWidth",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the minimum width of the block container."
+ },
+ {
+ "name": "ml",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "mr",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "mt",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "testId",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets a data-testid attribute for automated testing."
+ },
+ {
+ "name": "width",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the width of the block container."
+ }
],
- "required": false,
- "default": "row",
- "description": "Stacking direction of child components."
+ "events": [],
+ "slots": []
},
- {
- "name": "alignment",
- "type": "\"center\" | \"start\" | \"end\" | \"normal\"",
- "values": [
- "center",
- "start",
- "end",
- "normal"
+ "angular": {
+ "props": [
+ {
+ "name": "alignment",
+ "type": "GoabBlockAlignment",
+ "required": false,
+ "default": null,
+ "description": "Sets the primary axis alignment of child components."
+ },
+ {
+ "name": "direction",
+ "type": "GoabBlockDirection",
+ "required": false,
+ "default": null,
+ "description": "Sets the stacking direction of child components."
+ },
+ {
+ "name": "gap",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the spacing between items. Uses design system spacing tokens."
+ },
+ {
+ "name": "maxWidth",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the maximum width of the block container."
+ },
+ {
+ "name": "mb",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the bottom margin spacing token."
+ },
+ {
+ "name": "minWidth",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the minimum width of the block container."
+ },
+ {
+ "name": "ml",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the left margin spacing token."
+ },
+ {
+ "name": "mr",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the right margin spacing token."
+ },
+ {
+ "name": "mt",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the top margin spacing token."
+ },
+ {
+ "name": "testId",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the data-testid attribute for automated testing."
+ },
+ {
+ "name": "width",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the width of the block container. Defaults to max-content."
+ }
],
- "required": false,
- "default": "normal",
- "description": "Primary axis alignment of child components."
- },
- {
- "name": "testId",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Sets a data-testid attribute for automated testing."
- },
- {
- "name": "minWidth",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Sets the minimum width of the block container."
- },
- {
- "name": "maxWidth",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Sets the maximum width of the block container."
- },
- {
- "name": "width",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Sets the width of the block container. Defaults to max-content."
+ "events": [],
+ "slots": []
},
- {
- "name": "mt",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Top margin."
- },
- {
- "name": "mr",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Right margin."
- },
- {
- "name": "mb",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Bottom margin."
- },
- {
- "name": "ml",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Left margin."
- }
- ],
- "events": [],
- "slots": [
- {
- "name": "default",
- "description": ""
+ "webComponents": {
+ "props": [
+ {
+ "name": "alignment",
+ "type": "\"center\" | \"start\" | \"end\" | \"normal\"",
+ "values": [
+ "center",
+ "start",
+ "end",
+ "normal"
+ ],
+ "required": false,
+ "default": "normal",
+ "description": "Primary axis alignment of child components."
+ },
+ {
+ "name": "direction",
+ "type": "\"row\" | \"column\"",
+ "values": [
+ "row",
+ "column"
+ ],
+ "required": false,
+ "default": "row",
+ "description": "Stacking direction of child components."
+ },
+ {
+ "name": "gap",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": "m",
+ "description": "Spacing between items. Uses design system spacing tokens."
+ },
+ {
+ "name": "max-width",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Sets the maximum width of the block container."
+ },
+ {
+ "name": "mb",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Bottom margin."
+ },
+ {
+ "name": "min-width",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Sets the minimum width of the block container."
+ },
+ {
+ "name": "ml",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Left margin."
+ },
+ {
+ "name": "mr",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Right margin."
+ },
+ {
+ "name": "mt",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Top margin."
+ },
+ {
+ "name": "testid",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Sets a data-testid attribute for automated testing."
+ },
+ {
+ "name": "width",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Sets the width of the block container. Defaults to max-content."
+ }
+ ],
+ "events": [],
+ "slots": []
}
- ]
+ }
}
\ No newline at end of file
diff --git a/docs/generated/component-apis/button-group.json b/docs/generated/component-apis/button-group.json
index 8014882d01..948bb7f955 100644
--- a/docs/generated/component-apis/button-group.json
+++ b/docs/generated/component-apis/button-group.json
@@ -1,77 +1,186 @@
{
"componentSlug": "button-group",
"extractedFrom": "libs/web-components/src/components/button-group/ButtonGroup.svelte",
- "props": [
- {
- "name": "alignment",
- "type": "\"start\" | \"end\" | \"center\"",
- "typeLabel": "GoabButtonGroupButtonAlignment",
- "values": [
- "start",
- "end",
- "center"
+ "frameworks": {
+ "react": {
+ "props": [
+ {
+ "name": "alignment",
+ "type": "GoabButtonGroupAlignment",
+ "required": true,
+ "default": null,
+ "description": "Positions the button group in the page layout."
+ },
+ {
+ "name": "gap",
+ "type": "GoabButtonGroupGap",
+ "required": false,
+ "default": "relaxed",
+ "description": "Sets the spacing between buttons in the button group."
+ },
+ {
+ "name": "mb",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "ml",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "mr",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "mt",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": ""
+ },
+ {
+ "name": "testId",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets a data-testid attribute for automated testing."
+ }
],
- "required": false,
- "default": "start",
- "description": "Positions the button group in the page layout."
+ "events": [],
+ "slots": []
},
- {
- "name": "gap",
- "type": "\"relaxed\" | \"compact\"",
- "typeLabel": "GoabButtonGroupGap",
- "values": [
- "relaxed",
- "compact"
+ "angular": {
+ "props": [
+ {
+ "name": "alignment",
+ "type": "GoabButtonGroupAlignment",
+ "required": false,
+ "default": null,
+ "description": "Positions the button group in the page layout."
+ },
+ {
+ "name": "gap",
+ "type": "GoabButtonGroupGap",
+ "required": false,
+ "default": null,
+ "description": "Sets the spacing between buttons in the button group."
+ },
+ {
+ "name": "mb",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the bottom margin spacing token."
+ },
+ {
+ "name": "ml",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the left margin spacing token."
+ },
+ {
+ "name": "mr",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the right margin spacing token."
+ },
+ {
+ "name": "mt",
+ "type": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Sets the top margin spacing token."
+ },
+ {
+ "name": "testId",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Sets the data-testid attribute for automated testing."
+ }
],
- "required": false,
- "default": "relaxed",
- "description": "Sets the spacing between buttons in the button group."
+ "events": [],
+ "slots": []
},
- {
- "name": "testId",
- "type": "string",
- "required": false,
- "default": "",
- "description": "Sets a data-testid attribute for automated testing."
- },
- {
- "name": "mt",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Top margin."
- },
- {
- "name": "mr",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Right margin."
- },
- {
- "name": "mb",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Bottom margin."
- },
- {
- "name": "ml",
- "type": "Spacing",
- "typeLabel": "Spacing",
- "required": false,
- "default": null,
- "description": "Left margin."
- }
- ],
- "events": [],
- "slots": [
- {
- "name": "default",
- "description": ""
+ "webComponents": {
+ "props": [
+ {
+ "name": "alignment",
+ "type": "\"start\" | \"end\" | \"center\"",
+ "typeLabel": "GoabButtonGroupButtonAlignment",
+ "values": [
+ "start",
+ "end",
+ "center"
+ ],
+ "required": false,
+ "default": "start",
+ "description": "Positions the button group in the page layout."
+ },
+ {
+ "name": "gap",
+ "type": "\"relaxed\" | \"compact\"",
+ "typeLabel": "GoabButtonGroupGap",
+ "values": [
+ "relaxed",
+ "compact"
+ ],
+ "required": false,
+ "default": "relaxed",
+ "description": "Sets the spacing between buttons in the button group."
+ },
+ {
+ "name": "mb",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Bottom margin."
+ },
+ {
+ "name": "ml",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Left margin."
+ },
+ {
+ "name": "mr",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Right margin."
+ },
+ {
+ "name": "mt",
+ "type": "Spacing",
+ "typeLabel": "Spacing",
+ "required": false,
+ "default": null,
+ "description": "Top margin."
+ },
+ {
+ "name": "testid",
+ "type": "string",
+ "required": false,
+ "default": "",
+ "description": "Sets a data-testid attribute for automated testing."
+ }
+ ],
+ "events": [],
+ "slots": []
}
- ]
+ }
}
\ No newline at end of file
diff --git a/docs/generated/component-apis/button.json b/docs/generated/component-apis/button.json
index 3ccbd384e7..3ee01667b2 100644
--- a/docs/generated/component-apis/button.json
+++ b/docs/generated/component-apis/button.json
@@ -1,141 +1,405 @@
{
"componentSlug": "button",
"extractedFrom": "libs/web-components/src/components/button/Button.svelte",
- "props": [
- {
- "name": "type",
- "type": "\"primary\" | \"submit\" | \"secondary\" | \"tertiary\" | \"start\" | \"text\"",
- "typeLabel": "GoabButtonType",
- "values": [
- "primary",
- "submit",
- "secondary",
- "tertiary",
- "start",
- "text"
+ "frameworks": {
+ "react": {
+ "props": [
+ {
+ "name": "action",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Action identifier passed in click events for event delegation patterns."
+ },
+ {
+ "name": "actionArg",
+ "type": "string",
+ "required": false,
+ "default": null,
+ "description": "Single argument value passed with the action in click events."
+ },
+ {
+ "name": "actionArgs",
+ "type": "Record:focus-visible across interactive components:active)
+ on buttons should still show the pressed/focused look.
+ + + +
a:focus → a:focus-visible+ + +
.chip:focus → .chip:focus-visible
+
+
+ role="presentation"; the close goa-icon-button is
+ the focusable element. goa-icon-button already uses :focus-visible
+ (no change needed here).
+
+
+
+ tabindex="0" role="button". Removed class:focused
+ binding; outline now on .chip:focus-visible .delete-icon.
+
+
+ + + +
:focus-visible onlyassets/css/reset.css.
+ Dropped both :focus and :focus-within — on plain
+ <a> they both match on mouse click (HTML doesn't allow focusable
+ children inside <a>, so :focus-within has no real use
+ here).
+ + + +
.error:focus + V2 combined selector:focus-within container
+ pattern should still apply on focus (correct).
+ + + +
:focus from combined selectors
+ Primary
+ Secondary
+ Tertiary
+
+
+
+ Primary destructive
+ Secondary destructive
+ Tertiary destructive
+
+
+
+ Primary inverse
+ Secondary inverse
+ Tertiary inverse
+
+
+
+ Primary
+ Secondary
+ Tertiary
+
+
+
+ Primary destructive
+ Secondary destructive
+ Tertiary destructive
+
+
+
+ Primary inverse
+ Secondary inverse
+ Tertiary inverse
+
+ + + +
:has(:focus) duplicates from V1:has(:focus-visible) with :has(:focus).
+ The :focus duplicate fired on mouse click. V2 already correct.
+
+
+
+
+
+
+
+
+
+
+
+ + + +
:focus-within matches on click; :has(::slotted(a:focus-visible))
+ isn't reliable), so the component listens for focusin on the slotted
+ anchor and checks .matches(':focus-visible') before flipping a class.
+ + + +
::slotted(a:focus) → :focus-visible:focus. Now keyboard only.
+ + + +
.tooltip:focus .tooltip-text → :focus-visible
+
+ Hover or Tab me
+
+
+ + + +
summary:focus → :focus-visible+ + +
goa-data-grid wrapping a goa-table. Cells contain
+ badges, buttons, and text. Focus styling is JS-driven via
+ setFocusedStyle. Describe what looks wrong (mouse click leaving an outline?
+ UA default ring on a cell? ring jumping?).
+ keyboardNav="layout". Each card is a row, cells include the checkbox, name,
+ badge, stat blocks, and menu button.
+
+
+
+
+
+
+ Mike Zwei
+
+
+
+
+ Updated
+ Jun 30, 2022 at 2:30 PM
+
+
+ Email
+ mike.zwei@gmail.com
+
+
+ Program
+ Wee Wild Ones Curry
+
+
+
+
+ Program ID
+ 74528567
+
+
+ Service access
+ Claims Adjustments
+
+
+
+
+
+
+
+
+ Emma Stroman
+
+
+
+
+ Updated
+ Nov 28, 2021 at 1:30 PM
+
+
+ Email
+ emma.stroman@gmail.com
+
+
+ Program
+ Fort McMurray
+
+
+
+
+ Program ID
+ 74522643
+
+
+ Service access
+ Claims Adjustments
+
+
+
- {imageUrl && 
}
+ {imageUrl && })
}
{title}
@@ -30,7 +32,7 @@ const isDisabled = !linkTo;
) : (
- {imageUrl &&
-
+
);
diff --git a/docs/src/components/CodeSnippet.css b/docs/src/components/CodeSnippet.css
index d24afe3361..d8916fd894 100644
--- a/docs/src/components/CodeSnippet.css
+++ b/docs/src/components/CodeSnippet.css
@@ -170,3 +170,15 @@ code {
.hljs-built_in { color: #6639ba; }
.hljs-title { color: #6639ba; }
.hljs-params { color: #953800; }
+
+/* Dark mode: lighter hue-preserved variants for readability on dark code bg */
+:root[data-theme="dark"] .hljs-keyword { color: #79c0ff; }
+:root[data-theme="dark"] .hljs-string { color: #7ee787; }
+:root[data-theme="dark"] .hljs-number { color: #79c0ff; }
+:root[data-theme="dark"] .hljs-comment { color: #8b949e; }
+:root[data-theme="dark"] .hljs-tag { color: #79c0ff; }
+:root[data-theme="dark"] .hljs-attr { color: #79c0ff; }
+:root[data-theme="dark"] .hljs-name { color: #7ce38b; }
+:root[data-theme="dark"] .hljs-built_in { color: #d2a8ff; }
+:root[data-theme="dark"] .hljs-title { color: #d2a8ff; }
+:root[data-theme="dark"] .hljs-params { color: #ffa657; }
diff --git a/docs/src/components/CodeSnippet.tsx b/docs/src/components/CodeSnippet.tsx
index 376c95bfc4..daef55060b 100644
--- a/docs/src/components/CodeSnippet.tsx
+++ b/docs/src/components/CodeSnippet.tsx
@@ -219,44 +219,50 @@ export function CodeSnippet({
? VALID_FRAMEWORKS.filter((k) => Boolean(frameworkCode[k]))
: [];
+ const syncGoaTabsSelection = (framework: Framework) => {
+ if (!tabsRef.current || availableFrameworks.length === 0 || !availableFrameworks.includes(framework)) {
+ return;
+ }
+
+ const goaTabs = tabsRef.current.querySelector("goa-tabs");
+ if (!goaTabs) return;
+
+ const targetIndex = availableFrameworks.indexOf(framework);
+ const tabs = goaTabs.querySelectorAll('[role="tab"]');
+ const targetTab = tabs[targetIndex] as HTMLElement | undefined;
+ if (!targetTab) return;
+
+ tabs.forEach((tab, i) => {
+ tab.setAttribute("aria-selected", i === targetIndex ? "true" : "false");
+ tab.setAttribute("tabindex", i === targetIndex ? "0" : "-1");
+ });
+
+ const tabContents = goaTabs.querySelectorAll("goa-tab");
+ tabContents.forEach((content, i) => {
+ content.dispatchEvent(
+ new CustomEvent("tabs:set-open", {
+ composed: true,
+ detail: { open: i === targetIndex },
+ }),
+ );
+ });
+ };
+
+ useEffect(() => {
+ const stored = getFrameworkPreference();
+ if (availableFrameworks.length > 0 && availableFrameworks.includes(stored)) {
+ setSelectedFramework(stored);
+ syncGoaTabsSelection(stored);
+ }
+ }, [availableFrameworks]);
+
// Subscribe to global framework preference changes from other components.
// Directly manipulate the tab DOM state without triggering focus or hash changes.
useEffect(() => {
return subscribeToFrameworkPreference((framework) => {
if (availableFrameworks.length === 0 || availableFrameworks.includes(framework)) {
setSelectedFramework(framework);
-
- // Directly switch goa-tabs without triggering focus
- if (tabsRef.current) {
- const goaTabs = tabsRef.current.querySelector("goa-tabs");
- if (goaTabs) {
- const targetIndex = availableFrameworks.indexOf(framework);
- const tabs = goaTabs.querySelectorAll('[role="tab"]');
-
- // Check if already on the correct tab
- const targetTab = tabs[targetIndex] as HTMLElement;
- if (targetTab && targetTab.getAttribute("aria-selected") === "true") {
- return; // Already selected, nothing to do
- }
-
- // Update tab button states (aria-selected, tabindex)
- tabs.forEach((tab, i) => {
- tab.setAttribute("aria-selected", i === targetIndex ? "true" : "false");
- tab.setAttribute("tabindex", i === targetIndex ? "0" : "-1");
- });
-
- // Tell each goa-tab content whether it should be open
- const tabContents = goaTabs.querySelectorAll("goa-tab");
- tabContents.forEach((content, i) => {
- content.dispatchEvent(
- new CustomEvent("tabs:set-open", {
- composed: true,
- detail: { open: i === targetIndex },
- }),
- );
- });
- }
- }
+ syncGoaTabsSelection(framework);
}
});
}, [availableFrameworks]);
diff --git a/docs/src/components/ComponentSandbox.tsx b/docs/src/components/ComponentSandbox.tsx
index 8cd0b38c95..32a5849472 100644
--- a/docs/src/components/ComponentSandbox.tsx
+++ b/docs/src/components/ComponentSandbox.tsx
@@ -51,6 +51,11 @@ export function ComponentSandbox({
return stored === 'angular' ? 'angular' : 'react';
});
+ useEffect(() => {
+ const stored = getFrameworkPreference();
+ setActiveTab(stored === 'angular' ? 'angular' : 'react');
+ }, []);
+
// Subscribe to global framework preference changes
useEffect(() => {
return subscribeToFrameworkPreference((framework) => {
diff --git a/docs/src/components/ComponentsGrid.tsx b/docs/src/components/ComponentsGrid.tsx
index cdf07f2a7b..fba586356a 100644
--- a/docs/src/components/ComponentsGrid.tsx
+++ b/docs/src/components/ComponentsGrid.tsx
@@ -49,9 +49,6 @@ export interface Component {
| "utilities";
tags?: string[];
relatedComponents?: string[];
- webComponentTag?: string;
- reactClassName?: string;
- angularSelector?: string;
};
}
diff --git a/docs/src/components/ConfigurationPreview.tsx b/docs/src/components/ConfigurationPreview.tsx
index 612ba5e6be..71b4303f86 100644
--- a/docs/src/components/ConfigurationPreview.tsx
+++ b/docs/src/components/ConfigurationPreview.tsx
@@ -10,11 +10,12 @@
* Code snippet changes based on selected framework preference.
*/
-import { useState, useEffect, useRef, useCallback } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
// Note: Using web component directly for v2 styling (React wrapper doesn't pass version prop)
+import { GoabTooltip } from "@abgov/react-components";
import { CodeSnippet } from "./CodeSnippet";
import { useGitHubIssueCount } from "../hooks/useGitHubIssueCount";
-import type { ComponentConfigurations } from "../data/configurations/types";
+import type { ComponentConfigurations } from "@/data/configurations";
import DOMPurify from "dompurify";
// Allow GoA web component custom elements through DOMPurify.
@@ -65,21 +66,23 @@ export function ConfigurationPreview({
webComponentCode.js ? `` : "",
].join("");
+ const previewHtml = configurations.previewWrapper
+ ? configurations.previewWrapper.replace("{{slot}}", rawCode)
+ : rawCode;
+
// Extract script content before sanitization
- const scriptMatch = rawCode.match(/
diff --git a/docs/src/components/SiteNav.tsx b/docs/src/components/SiteNav.tsx
index ab38664798..cd89579beb 100644
--- a/docs/src/components/SiteNav.tsx
+++ b/docs/src/components/SiteNav.tsx
@@ -21,6 +21,7 @@ import {
FoundationsSubMenu,
type MenuSection,
type NavCategory,
+ type GetStartedNav,
} from "./nav";
interface SiteNavProps {
@@ -32,6 +33,8 @@ interface SiteNavProps {
initialSection?: MenuSection;
/** Component nav categories (from content collection, passed by Astro layout) */
categories?: NavCategory[];
+ /** Get Started submenu structure (from content collection, passed by Astro layout) */
+ getStartedNav?: GetStartedNav;
}
// Sections that have submenus (show submenu when navigated to)
@@ -90,11 +93,18 @@ function getInitialMenuState(): boolean {
return true;
}
+const EMPTY_GET_STARTED_NAV: GetStartedNav = {
+ topPages: [],
+ groups: [],
+ bottomPages: [],
+};
+
export function SiteNav({
currentSlug,
currentCategory,
initialSection,
categories = [],
+ getStartedNav = EMPTY_GET_STARTED_NAV,
}: SiteNavProps) {
// Menu state - persisted on desktop, always closed on mobile
const [isOpen, setIsOpen] = useState(getInitialMenuState);
@@ -216,6 +226,7 @@ export function SiteNav({
onBack={handleBack}
onExpandMenu={handleExpandMenu}
currentUrl={currentUrl}
+ items={getStartedNav}
/>
);
diff --git a/docs/src/components/TokensGrid.tsx b/docs/src/components/TokensGrid.tsx
index d7ea0b00af..7bd2c59108 100644
--- a/docs/src/components/TokensGrid.tsx
+++ b/docs/src/components/TokensGrid.tsx
@@ -30,6 +30,7 @@ import {
import { useTwoLevelSort } from "../hooks/useTwoLevelSort";
import { useContainerNarrow } from "../hooks/useContainerWidth";
+import { useIsDarkMode } from "../hooks/useIsDarkMode";
import type { FlatToken } from "../lib/tokens";
import { InlineSearch, type SlashCommand } from "./search/InlineSearch";
@@ -100,7 +101,22 @@ function toScssSyntax(cssName: string): string {
return cssName.replace(/^--/, "$");
}
+/**
+ * Pick the active-theme variant of a token's display values. Returns light values
+ * when not in dark mode, or when the token has no dark variant.
+ */
+function activeOf(token: FlatToken, isDark: boolean): { value: string; resolvedValue: string } {
+ if (isDark && token.darkValue) {
+ return {
+ value: token.darkValue,
+ resolvedValue: token.darkResolvedValue ?? token.resolvedValue,
+ };
+ }
+ return { value: token.value, resolvedValue: token.resolvedValue };
+}
+
export function TokensGrid({ tokens, filterGroups }: TokensGridProps) {
+ const isDark = useIsDarkMode();
// State
const [filterDrawerOpen, setFilterDrawerOpen] = useState(false);
const [isSticky, setIsSticky] = useState(false);
@@ -343,7 +359,8 @@ export function TokensGrid({ tokens, filterGroups }: TokensGridProps) {
// Render token preview (color, opacity, etc.)
const renderPreview = (token: FlatToken) => {
- const value = token.resolvedValue || token.value;
+ const active = activeOf(token, isDark);
+ const value = active.resolvedValue || active.value;
if (token.isColor) {
return (
);
}
@@ -578,18 +595,16 @@ export function TokensGrid({ tokens, filterGroups }: TokensGridProps) {
display: "flex",
alignItems: "center",
justifyContent: "center",
- backgroundColor: "white",
- borderRadius: 4,
}}
- title={token.value}
+ title={active.value}
>
@@ -731,7 +746,7 @@ export function TokensGrid({ tokens, filterGroups }: TokensGridProps) {
{renderPreview(token)}
{getFormattedTokenName(token.name)}
- {token.value}
+ {activeOf(token, isDark).value}
{getFormattedTokenName(token.name)}
{token.value}
+ {activeOf(token, isDark).value}
- {PAGE_GROUPS.map((group) => {
+ {items.groups.map((group) => {
const containsCurrentPage = group.pages.some((p) => p.url === currentUrl);
const handleGroupClickCapture = () => {
@@ -128,8 +85,12 @@ export function GetStartedSubMenu({
{/* Bottom pages */}
- {BOTTOM_PAGES.map((page) => (
- ` uses `heading-l` (not the default `heading-xl`) to match the Figma spec for page-scale error states.
diff --git a/docs/src/content/examples/404-error-page/index.mdx b/docs/src/content/examples/404-error-page/index.mdx
deleted file mode 100644
index ab54a3a44c..0000000000
--- a/docs/src/content/examples/404-error-page/index.mdx
+++ /dev/null
@@ -1,37 +0,0 @@
----
-id: 404-error-page
-title: Page not found (404)
-categories:
- - content-layout
-scale: page
-userType: both
-tags:
- - error
- - page-structure
- - "404"
-components:
- - page-block
- - block
- - text
- - icon
- - button
-status: published
-fullWidth: true
-previewStyle: "padding: 0"
-accessibilityNotes: 'Uses a plain h1 as the page landmark. The decorative icon and accent bar are aria-hidden. No role="alert" is applied because the ARIA alert role is reserved for dynamically inserted messages; a static error route does not meet that criterion.'
----
-
-A full page that tells the user a page can't be found, with an action to get them back on track.
-
-## When to use
-
-- A user navigates to a URL that doesn't exist in your service.
-- A resource has been moved or deleted and you need a catch-all route.
-- As the fallback route rendered by your router's outlet.
-
-## Considerations
-
-- Keep the message short and give the user one clear next step.
-- Render the pattern inside your existing layout (e.g. as the route in a `GoabOneColumnLayout` outlet) so it sits below your service's header and above its footer.
-- A small amount of custom CSS covers the icon-in-circle treatment, the brand-color accent bar, centred text, and the icon scaled beyond `xlarge`. Each is a pattern the design system doesn't yet cover and is tracked as a gap for the library to absorb over time.
-- The `` uses `heading-l` (not the default `heading-xl`) to match the Figma spec for page-scale error states.
diff --git a/docs/src/content/examples/500-error-page/index.mdx b/docs/src/content/examples/500-error-page/index.mdx
deleted file mode 100644
index 5c2194a473..0000000000
--- a/docs/src/content/examples/500-error-page/index.mdx
+++ /dev/null
@@ -1,37 +0,0 @@
----
-id: 500-error-page
-title: Server problem (500)
-categories:
- - content-layout
-scale: page
-userType: both
-tags:
- - error
- - page-structure
- - "500"
-components:
- - page-block
- - block
- - text
- - icon
- - button
-status: published
-fullWidth: true
-previewStyle: "padding: 0"
-accessibilityNotes: 'Uses a plain h1 as the page landmark. The decorative icon and accent bar are aria-hidden. No role="alert" is applied because the ARIA alert role is reserved for dynamically inserted messages; a static error route does not meet that criterion.'
----
-
-A full page that tells the user the service is temporarily unable to respond, with an action to try again or return home.
-
-## When to use
-
-- A server-side error interrupted the user's request and there is nothing they can do to fix it themselves.
-- A background dependency of your service is down.
-- As a fallback for uncaught errors that reach the outer error boundary of your app.
-
-## Considerations
-
-- Take responsibility in the copy. The user did not cause this; acknowledge that and give them one clear action.
-- This example uses "Go to home page" as the safe fallback action. If the failure is likely transient and the user can recover by retrying, swap the button's `onClick` for your retry handler and change the label to "Try again".
-- A small amount of custom CSS covers the icon-in-circle treatment, the brand-color accent bar, centred text, and the icon scaled beyond `xlarge`. Each is a pattern the design system doesn't yet cover and is tracked as a gap for the library to absorb over time.
-- The `` uses `heading-l` (not the default `heading-xl`) to match the Figma spec for page-scale error states.
diff --git a/docs/src/content/examples/add-a-filter-chip/index.mdx b/docs/src/content/examples/add-a-filter-chip/index.mdx
index 77217bdd26..7e9173fb2b 100644
--- a/docs/src/content/examples/add-a-filter-chip/index.mdx
+++ b/docs/src/content/examples/add-a-filter-chip/index.mdx
@@ -1,10 +1,7 @@
---
id: add-a-filter-chip
title: Add a filter chip
-categories:
- - inputs-and-actions
-scale: interaction
-userType: both
+size: interaction
tags:
- filtering
- chips
diff --git a/docs/src/content/examples/add-a-record-using-a-drawer/index.mdx b/docs/src/content/examples/add-a-record-using-a-drawer/index.mdx
index cd07b09ac4..c9d2e654c5 100644
--- a/docs/src/content/examples/add-a-record-using-a-drawer/index.mdx
+++ b/docs/src/content/examples/add-a-record-using-a-drawer/index.mdx
@@ -1,10 +1,8 @@
---
id: add-a-record-using-a-drawer
title: Add a record using a drawer
-categories:
- - structure-and-navigation
-scale: task
-userType: worker
+size: section
+productType: workspace
tags:
- drawer
- forms
diff --git a/docs/src/content/examples/add-and-edit-lots-of-filters/index.mdx b/docs/src/content/examples/add-and-edit-lots-of-filters/index.mdx
index 615118ea61..df5951f2ca 100644
--- a/docs/src/content/examples/add-and-edit-lots-of-filters/index.mdx
+++ b/docs/src/content/examples/add-and-edit-lots-of-filters/index.mdx
@@ -1,10 +1,8 @@
---
id: add-and-edit-lots-of-filters
title: Add and edit lots of filters
-categories:
- - structure-and-navigation
-scale: task
-userType: worker
+size: section
+productType: workspace
tags:
- filtering
- drawer
diff --git a/docs/src/content/examples/add-another-item-in-a-modal/index.mdx b/docs/src/content/examples/add-another-item-in-a-modal/index.mdx
index 8e7232bf28..794c7611e1 100644
--- a/docs/src/content/examples/add-another-item-in-a-modal/index.mdx
+++ b/docs/src/content/examples/add-another-item-in-a-modal/index.mdx
@@ -1,10 +1,7 @@
---
id: add-another-item-in-a-modal
title: Add another item in a modal
-categories:
- - inputs-and-actions
-scale: task
-userType: both
+size: section
tags:
- modal
- forms
diff --git a/docs/src/content/examples/ask-a-long-answer-question-with-a-maximum-word-count/index.mdx b/docs/src/content/examples/ask-a-long-answer-question-with-a-maximum-word-count/index.mdx
index 0e507e54ad..4c9b078f35 100644
--- a/docs/src/content/examples/ask-a-long-answer-question-with-a-maximum-word-count/index.mdx
+++ b/docs/src/content/examples/ask-a-long-answer-question-with-a-maximum-word-count/index.mdx
@@ -1,10 +1,8 @@
---
id: ask-a-long-answer-question-with-a-maximum-word-count
title: Ask a long answer question with a maximum word count
-categories:
- - forms
-scale: task
-userType: citizen
+size: interaction
+productType: public-form
tags:
- forms
- text-area
diff --git a/docs/src/content/examples/ask-a-user-for-a-birthday/index.mdx b/docs/src/content/examples/ask-a-user-for-a-birthday/index.mdx
index c461ae3dea..5069834fa7 100644
--- a/docs/src/content/examples/ask-a-user-for-a-birthday/index.mdx
+++ b/docs/src/content/examples/ask-a-user-for-a-birthday/index.mdx
@@ -1,10 +1,8 @@
---
id: ask-a-user-for-a-birthday
title: Ask a user for a birthday
-categories:
- - forms
-scale: task
-userType: citizen
+size: interaction
+productType: public-form
tags:
- forms
- date-input
diff --git a/docs/src/content/examples/ask-a-user-for-an-address/index.mdx b/docs/src/content/examples/ask-a-user-for-an-address/index.mdx
index 5180a342cd..9f1959e1c0 100644
--- a/docs/src/content/examples/ask-a-user-for-an-address/index.mdx
+++ b/docs/src/content/examples/ask-a-user-for-an-address/index.mdx
@@ -1,10 +1,8 @@
---
id: ask-a-user-for-an-address
title: Ask a user for an address
-categories:
- - forms
-scale: task
-userType: citizen
+size: section
+productType: public-form
tags:
- forms
- address
diff --git a/docs/src/content/examples/ask-a-user-for-an-indian-registration-number/index.mdx b/docs/src/content/examples/ask-a-user-for-an-indian-registration-number/index.mdx
index 58b355be21..aa67ee504c 100644
--- a/docs/src/content/examples/ask-a-user-for-an-indian-registration-number/index.mdx
+++ b/docs/src/content/examples/ask-a-user-for-an-indian-registration-number/index.mdx
@@ -1,10 +1,8 @@
---
id: ask-a-user-for-an-indian-registration-number
title: Ask a user for an Indian registration number
-categories:
- - forms
-scale: task
-userType: citizen
+size: interaction
+productType: public-form
tags:
- forms
- identity
diff --git a/docs/src/content/examples/ask-a-user-for-direct-deposit-information/index.mdx b/docs/src/content/examples/ask-a-user-for-direct-deposit-information/index.mdx
index 2dc73560b1..79413ea5f7 100644
--- a/docs/src/content/examples/ask-a-user-for-direct-deposit-information/index.mdx
+++ b/docs/src/content/examples/ask-a-user-for-direct-deposit-information/index.mdx
@@ -1,10 +1,8 @@
---
id: ask-a-user-for-direct-deposit-information
title: Ask a user for direct deposit information
-categories:
- - forms
-scale: task
-userType: citizen
+size: section
+productType: public-form
tags:
- forms
- banking
diff --git a/docs/src/content/examples/ask-a-user-for-dollar-amounts/index.mdx b/docs/src/content/examples/ask-a-user-for-dollar-amounts/index.mdx
index 51eeae7f6c..9198b22e01 100644
--- a/docs/src/content/examples/ask-a-user-for-dollar-amounts/index.mdx
+++ b/docs/src/content/examples/ask-a-user-for-dollar-amounts/index.mdx
@@ -1,10 +1,8 @@
---
id: ask-a-user-for-dollar-amounts
title: Ask a user for dollar amounts
-categories:
- - forms
-scale: task
-userType: citizen
+size: interaction
+productType: public-form
tags:
- forms
- currency
diff --git a/docs/src/content/examples/ask-a-user-one-question-at-a-time/angular.html b/docs/src/content/examples/ask-a-user-one-question-at-a-time/angular.html
deleted file mode 100644
index 84c106cdae..0000000000
--- a/docs/src/content/examples/ask-a-user-one-question-at-a-time/angular.html
+++ /dev/null
@@ -1,19 +0,0 @@
-
- Back
-
-
-
-
-
- Save and continue
diff --git a/docs/src/content/examples/ask-a-user-one-question-at-a-time/angular.ts b/docs/src/content/examples/ask-a-user-one-question-at-a-time/angular.ts
deleted file mode 100644
index a46a1b448b..0000000000
--- a/docs/src/content/examples/ask-a-user-one-question-at-a-time/angular.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import { Component } from "@angular/core";
-import { GoabRadioGroupOnChangeDetail } from "@abgov/ui-components-common";
-
-@Component({
- selector: "app-ask-a-user-one-question-at-a-time",
- templateUrl: "./angular.html",
- styles: [
- `
- a.back-link::before {
- content: "";
- display: inline-block;
- width: 42px;
- height: 24px;
- vertical-align: middle;
- background: url('data:image/svg+xml,')
- center center no-repeat;
- }
-
- a.back-link:visited::before,
- a.back-link:hover::before {
- background: url('data:image/svg+xml,')
- center center no-repeat;
- }
-
- a.back-link {
- margin-top: var(--goa-space-m);
- }
- `,
- ],
-})
-export class AskAUserOneQuestionAtATimeComponent {
- selectedValue = "";
-
- onSchoolChange(event: GoabRadioGroupOnChangeDetail): void {
- this.selectedValue = event.value as string;
- }
-}
diff --git a/docs/src/content/examples/ask-a-user-one-question-at-a-time/index.mdx b/docs/src/content/examples/ask-a-user-one-question-at-a-time/index.mdx
deleted file mode 100644
index 16add605d0..0000000000
--- a/docs/src/content/examples/ask-a-user-one-question-at-a-time/index.mdx
+++ /dev/null
@@ -1,37 +0,0 @@
----
-id: ask-a-user-one-question-at-a-time
-title: Ask a user one question at a time
-categories:
- - forms
-scale: page
-userType: citizen
-tags:
- - forms
- - questions
- - public-form
-components:
- - form-item
- - radio-group
- - radio-item
- - button
-status: published
-previewImage: /images/examples/ask-a-user-one-question-at-a-time.webp
----
-
-Ask a user one question at a time.
-
-## When to use
-
-Use this pattern when:
-
-- Building a public-facing form for citizens
-- You want to reduce cognitive load by focusing on one question
-- The question requires careful consideration from the user
-- Following the one-question-per-page pattern for government services
-
-## Considerations
-
-- Include a back link to allow users to navigate to previous questions
-- Use a large label size to make the question prominent
-- Provide help text when the question may need clarification
-- Use a clear call-to-action button to progress
diff --git a/docs/src/content/examples/ask-a-user-one-question-at-a-time/react.tsx b/docs/src/content/examples/ask-a-user-one-question-at-a-time/react.tsx
deleted file mode 100644
index 0615ad3f04..0000000000
--- a/docs/src/content/examples/ask-a-user-one-question-at-a-time/react.tsx
+++ /dev/null
@@ -1,35 +0,0 @@
-import {
- GoabButton,
- GoabFormItem,
- GoabLink,
- GoabRadioGroup,
- GoabRadioItem,
-} from "@abgov/react-components";
-
-export function AskAUserOneQuestionAtATime() {
- return (
- <>
-
- Back
-
-
- {}}
- >
-
-
-
- Save and continue
-
-
- );
-}
diff --git a/docs/src/content/examples/ask-a-user-one-question-at-a-time/web-components.html b/docs/src/content/examples/ask-a-user-one-question-at-a-time/web-components.html
deleted file mode 100644
index b788d88fc4..0000000000
--- a/docs/src/content/examples/ask-a-user-one-question-at-a-time/web-components.html
+++ /dev/null
@@ -1,22 +0,0 @@
-
- Back
-
-
-
-
-
- Save and continue
-
-
diff --git a/docs/src/content/examples/basic-page-layout/index.mdx b/docs/src/content/examples/basic-page-layout/index.mdx
index 7c74326203..b7e2b019b6 100644
--- a/docs/src/content/examples/basic-page-layout/index.mdx
+++ b/docs/src/content/examples/basic-page-layout/index.mdx
@@ -1,10 +1,7 @@
---
id: basic-page-layout
title: Basic page layout
-categories:
- - content-layout
-scale: page
-userType: both
+size: page
tags:
- layout
- page-structure
@@ -19,6 +16,7 @@ status: published
fullWidth: true
previewStyle: "padding: 0; max-height: 600px"
previewImage: /images/examples/basic-page-layout.webp
+previewFullWidth: true
---
A basic page template to use as a starting point.
diff --git a/docs/src/content/examples/basic-page-layout/react.tsx b/docs/src/content/examples/basic-page-layout/react.tsx
index b91d797d11..1d7c1db36e 100644
--- a/docs/src/content/examples/basic-page-layout/react.tsx
+++ b/docs/src/content/examples/basic-page-layout/react.tsx
@@ -15,7 +15,7 @@ export function BasicPageLayout() {
Sign in
-
+
You have completed the application
-
-
- You will receive a copy of the confirmation to the email
- person@email.com
- Confirmation number: 1234ABC
-
-
-Go back to the dashboard, or direct your user somewhere else useful.
-Other information about what was just completed, other tertiary information, and/or
- contact information.
-
- Phone: 780 123 4567
-
- Email: information@gov.ab.ca
-
-
-
- Go to application
- Back to dashboard
-
diff --git a/docs/src/content/examples/confirm-that-an-application-was-submitted/angular.ts b/docs/src/content/examples/confirm-that-an-application-was-submitted/angular.ts
deleted file mode 100644
index 817bed0c4c..0000000000
--- a/docs/src/content/examples/confirm-that-an-application-was-submitted/angular.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-import { Component } from "@angular/core";
-
-@Component({
- selector: "app-confirm-that-an-application-was-submitted",
- templateUrl: "./angular.html",
-})
-export class ConfirmThatAnApplicationWasSubmittedComponent {}
diff --git a/docs/src/content/examples/confirm-that-an-application-was-submitted/index.mdx b/docs/src/content/examples/confirm-that-an-application-was-submitted/index.mdx
deleted file mode 100644
index 6aa9364d72..0000000000
--- a/docs/src/content/examples/confirm-that-an-application-was-submitted/index.mdx
+++ /dev/null
@@ -1,39 +0,0 @@
----
-id: confirm-that-an-application-was-submitted
-title: Confirm that an application was submitted
-categories:
- - feedback-and-alerts
-scale: page
-userType: citizen
-tags:
- - confirmation
- - success
- - callout
- - application
-components:
- - callout
- - button
- - button-group
-figmaUrl: https://www.figma.com/design/Jpy1Ea5qglwnp1SgGnagY9/%E2%9D%96-Component-library-%7C-DDD?node-id=63353-169579
-status: published
-previewImage: /images/examples/confirm-that-an-application-was-submitted.webp
----
-
-Display a confirmation screen to indicate successful application submission.
-
-## When to use
-
-Use this pattern when:
-
-- A user has successfully completed an application or form
-- You need to confirm the submission was received
-- Users need a confirmation number for their records
-- You want to provide next steps after submission
-
-## Considerations
-
-- Use a success callout to clearly indicate success
-- Include a confirmation number users can reference later
-- Mention where a confirmation email will be sent
-- Provide clear next steps and navigation options
-- Include contact information for questions
diff --git a/docs/src/content/examples/confirm-that-an-application-was-submitted/react.tsx b/docs/src/content/examples/confirm-that-an-application-was-submitted/react.tsx
deleted file mode 100644
index 5a6d308496..0000000000
--- a/docs/src/content/examples/confirm-that-an-application-was-submitted/react.tsx
+++ /dev/null
@@ -1,42 +0,0 @@
-import {
- GoabButton,
- GoabButtonGroup,
- GoabCallout,
- GoabText,
-} from "@abgov/react-components";
-
-export function ConfirmThatAnApplicationWasSubmitted() {
- return (
- <>
-
- You have completed the application
-
-
-
-
- You will receive a copy of the confirmation to the email person@email.com
-
-
- Confirmation number: 1234ABC
-
-
-
-
- Go back to the dashboard, or direct your user somewhere else useful.
-
-
- Other information about what was just completed, other tertiary information,
- and/or contact information.
-
- Phone: 780 123 4567
-
- Email: information@gov.ab.ca
-
-
-
- Go to application
- Back to dashboard
-
-
- );
-}
diff --git a/docs/src/content/examples/confirm-that-an-application-was-submitted/web-components.html b/docs/src/content/examples/confirm-that-an-application-was-submitted/web-components.html
deleted file mode 100644
index ccdbdb6f19..0000000000
--- a/docs/src/content/examples/confirm-that-an-application-was-submitted/web-components.html
+++ /dev/null
@@ -1,25 +0,0 @@
-You have completed the application
-
-
- You will receive a copy of the confirmation to the email person@email.com
- Confirmation number: 1234ABC
-
-
-Go back to the dashboard, or direct your user somewhere else useful.
-Other information about what was just completed, other tertiary information, and/or
- contact information.
-
- Phone: 780 123 4567
-
- Email: information@gov.ab.ca
-
-
-
- Go to application
- Back to dashboard
-
diff --git a/docs/src/content/examples/copy-to-clipboard/index.mdx b/docs/src/content/examples/copy-to-clipboard/index.mdx
index 439cc4a776..6b9f5dc34d 100644
--- a/docs/src/content/examples/copy-to-clipboard/index.mdx
+++ b/docs/src/content/examples/copy-to-clipboard/index.mdx
@@ -1,10 +1,7 @@
---
id: copy-to-clipboard
title: Copy to clipboard
-categories:
- - inputs-and-actions
-scale: interaction
-userType: both
+size: interaction
tags:
- clipboard
- copy
diff --git a/docs/src/content/examples/disabled-button-with-a-required-field/index.mdx b/docs/src/content/examples/disabled-button-with-a-required-field/index.mdx
index ee961c2bc4..db920cbfb7 100644
--- a/docs/src/content/examples/disabled-button-with-a-required-field/index.mdx
+++ b/docs/src/content/examples/disabled-button-with-a-required-field/index.mdx
@@ -1,10 +1,7 @@
---
id: disabled-button-with-a-required-field
title: Disabled button with a required field
-categories:
- - inputs-and-actions
-scale: interaction
-userType: both
+size: interaction
tags:
- button
- form
diff --git a/docs/src/content/examples/display-numbers-in-a-table-so-they-can-be-scanned-easily/index.mdx b/docs/src/content/examples/display-numbers-in-a-table-so-they-can-be-scanned-easily/index.mdx
index ba920ccf82..ab1bc725cb 100644
--- a/docs/src/content/examples/display-numbers-in-a-table-so-they-can-be-scanned-easily/index.mdx
+++ b/docs/src/content/examples/display-numbers-in-a-table-so-they-can-be-scanned-easily/index.mdx
@@ -1,10 +1,8 @@
---
id: display-numbers-in-a-table-so-they-can-be-scanned-easily
title: Display numbers in a table so they can be scanned easily
-categories:
- - content-layout
-scale: task
-userType: worker
+size: section
+productType: workspace
tags:
- table
- numbers
diff --git a/docs/src/content/examples/display-user-information/index.mdx b/docs/src/content/examples/display-user-information/index.mdx
index 6fc54f492b..ba97c6141a 100644
--- a/docs/src/content/examples/display-user-information/index.mdx
+++ b/docs/src/content/examples/display-user-information/index.mdx
@@ -1,10 +1,8 @@
---
id: display-user-information
title: Display user information
-categories:
- - content-layout
-scale: task
-userType: worker
+size: section
+productType: workspace
tags:
- container
- user-info
diff --git a/docs/src/content/examples/dynamically-add-an-item-to-a-dropdown-list/index.mdx b/docs/src/content/examples/dynamically-add-an-item-to-a-dropdown-list/index.mdx
index 00d5cb5551..96f1f8d3d2 100644
--- a/docs/src/content/examples/dynamically-add-an-item-to-a-dropdown-list/index.mdx
+++ b/docs/src/content/examples/dynamically-add-an-item-to-a-dropdown-list/index.mdx
@@ -1,10 +1,7 @@
---
id: dynamically-add-an-item-to-a-dropdown-list
title: Dynamically add an item to a dropdown list
-categories:
- - inputs-and-actions
-scale: interaction
-userType: both
+size: interaction
tags:
- dropdown
- dynamic
diff --git a/docs/src/content/examples/dynamically-change-items-in-a-dropdown-list/index.mdx b/docs/src/content/examples/dynamically-change-items-in-a-dropdown-list/index.mdx
index 2483250d66..faa2b79321 100644
--- a/docs/src/content/examples/dynamically-change-items-in-a-dropdown-list/index.mdx
+++ b/docs/src/content/examples/dynamically-change-items-in-a-dropdown-list/index.mdx
@@ -1,10 +1,7 @@
---
id: dynamically-change-items-in-a-dropdown-list
title: Dynamically change items in a dropdown list
-categories:
- - inputs-and-actions
-scale: interaction
-userType: both
+size: interaction
tags:
- dropdown
- dynamic
diff --git a/docs/src/content/examples/401-error-page/angular.html b/docs/src/content/examples/error-pages/401/angular.html
similarity index 100%
rename from docs/src/content/examples/401-error-page/angular.html
rename to docs/src/content/examples/error-pages/401/angular.html
diff --git a/docs/src/content/examples/401-error-page/angular.ts b/docs/src/content/examples/error-pages/401/angular.ts
similarity index 100%
rename from docs/src/content/examples/401-error-page/angular.ts
rename to docs/src/content/examples/error-pages/401/angular.ts
diff --git a/docs/src/content/examples/401-error-page/react.tsx b/docs/src/content/examples/error-pages/401/react.tsx
similarity index 100%
rename from docs/src/content/examples/401-error-page/react.tsx
rename to docs/src/content/examples/error-pages/401/react.tsx
diff --git a/docs/src/content/examples/401-error-page/web-components.html b/docs/src/content/examples/error-pages/401/web-components.html
similarity index 100%
rename from docs/src/content/examples/401-error-page/web-components.html
rename to docs/src/content/examples/error-pages/401/web-components.html
diff --git a/docs/src/content/examples/404-error-page/angular.html b/docs/src/content/examples/error-pages/404/angular.html
similarity index 100%
rename from docs/src/content/examples/404-error-page/angular.html
rename to docs/src/content/examples/error-pages/404/angular.html
diff --git a/docs/src/content/examples/404-error-page/angular.ts b/docs/src/content/examples/error-pages/404/angular.ts
similarity index 100%
rename from docs/src/content/examples/404-error-page/angular.ts
rename to docs/src/content/examples/error-pages/404/angular.ts
diff --git a/docs/src/content/examples/404-error-page/react.tsx b/docs/src/content/examples/error-pages/404/react.tsx
similarity index 100%
rename from docs/src/content/examples/404-error-page/react.tsx
rename to docs/src/content/examples/error-pages/404/react.tsx
diff --git a/docs/src/content/examples/404-error-page/web-components.html b/docs/src/content/examples/error-pages/404/web-components.html
similarity index 100%
rename from docs/src/content/examples/404-error-page/web-components.html
rename to docs/src/content/examples/error-pages/404/web-components.html
diff --git a/docs/src/content/examples/500-error-page/angular.html b/docs/src/content/examples/error-pages/500/angular.html
similarity index 100%
rename from docs/src/content/examples/500-error-page/angular.html
rename to docs/src/content/examples/error-pages/500/angular.html
diff --git a/docs/src/content/examples/500-error-page/angular.ts b/docs/src/content/examples/error-pages/500/angular.ts
similarity index 100%
rename from docs/src/content/examples/500-error-page/angular.ts
rename to docs/src/content/examples/error-pages/500/angular.ts
diff --git a/docs/src/content/examples/500-error-page/react.tsx b/docs/src/content/examples/error-pages/500/react.tsx
similarity index 100%
rename from docs/src/content/examples/500-error-page/react.tsx
rename to docs/src/content/examples/error-pages/500/react.tsx
diff --git a/docs/src/content/examples/500-error-page/web-components.html b/docs/src/content/examples/error-pages/500/web-components.html
similarity index 100%
rename from docs/src/content/examples/500-error-page/web-components.html
rename to docs/src/content/examples/error-pages/500/web-components.html
diff --git a/docs/src/content/examples/error-pages/index.mdx b/docs/src/content/examples/error-pages/index.mdx
new file mode 100644
index 0000000000..f63761dab3
--- /dev/null
+++ b/docs/src/content/examples/error-pages/index.mdx
@@ -0,0 +1,90 @@
+---
+id: error-pages
+title: Error pages
+size: page
+description: Standard error screens for Government of Alberta services. Use when a user lands somewhere that is missing, forbidden, or broken so they understand what happened and what to do next.
+previewImage: /thumbnails/error-pages-404.png
+hideHero: true
+components:
+ - page-block
+ - block
+ - text
+ - icon
+ - link
+ - button
+tags:
+ - error
+ - error page
+ - "401"
+ - "404"
+ - "500"
+ - page not found
+ - unauthorized
+ - restricted access
+ - server error
+ - server problem
+ - page-structure
+aliases:
+ - 401-error-page
+ - 404-error-page
+ - 500-error-page
+status: published
+---
+
+import PreviewContainer from "../../../components/PreviewContainer.astro";
+
+## Types of error pages
+
+### Restricted access (401)
+
+The user is not authorized, either because they need to sign in or because they lack the right permission.
+
+
-
- Primary users: citizens, public, external
- You are designing a public service for citizens. It should be designed to be as simple
- and intuitive as possible, while ensuring citizens can make complete and informed
- decisions for themselves using the service.
-
- There is an emphasis on an accessible experience with a low cognitive load for users
- who use the service infrequently.
-
-
-
-Pages
-
-
-
- 1. Start page
-
- This is the starting point for a citizen to begin your form from within your service
- or from Alberta.ca.
-
-
- 2. Task list page (optional)
-
- Outline the entire process for the user and help them through the process by
- breaking down an experience into individual tasks.
-
-
- 3. Question pages
-
- Ask a user a question or a small set of related questions.
-
-
- 4. Review page
-
- Let users check answers before submitting information to a service.
-
-
- 5. Results page
-
- Let users know that they've completed a form, application, or task and tell them
- what to do next.
-
-
-
diff --git a/docs/src/content/examples/public-form/angular.ts b/docs/src/content/examples/public-form/angular.ts
deleted file mode 100644
index fb2b7a40ae..0000000000
--- a/docs/src/content/examples/public-form/angular.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-import { Component } from "@angular/core";
-
-@Component({
- selector: "app-public-form",
- templateUrl: "./angular.html",
-})
-export class PublicFormComponent {}
diff --git a/docs/src/content/examples/public-form/index.mdx b/docs/src/content/examples/public-form/index.mdx
deleted file mode 100644
index 969e089442..0000000000
--- a/docs/src/content/examples/public-form/index.mdx
+++ /dev/null
@@ -1,35 +0,0 @@
----
-id: public-form
-title: Public form
-categories:
- - forms
-scale: product
-userType: citizen
-tags:
- - form
- - public
- - citizen
- - pattern
-components: []
-status: published
-previewImage: /images/examples/public-form.webp
----
-
-The public form pattern provides a structure for citizen-facing form experiences, emphasizing simplicity, accessibility, and low cognitive load.
-
-## When to use
-
-Use this pattern when:
-
-- Designing a public service for citizens
-- Building forms that should be simple and intuitive
-- Users need to make informed decisions while completing the form
-- The service should accommodate users who use it infrequently
-
-## Considerations
-
-- Follow the "one idea per page" principle to reduce cognitive load
-- Break complex forms into multiple pages with single questions
-- Use task list pages for longer processes with multiple sections
-- Consider using simple progress indicators rather than horizontal steppers
-- Ensure all form elements meet WCAG 2.2 AA accessibility standards
diff --git a/docs/src/content/examples/public-form/react.tsx b/docs/src/content/examples/public-form/react.tsx
deleted file mode 100644
index bc97714020..0000000000
--- a/docs/src/content/examples/public-form/react.tsx
+++ /dev/null
@@ -1,68 +0,0 @@
-import { GoabDetails, GoabGrid, GoabText } from "@abgov/react-components";
-
-export function PublicForm() {
- return (
- <>
-
-
- Primary users: citizens, public, external
-
-
- You are designing a public service for citizens. It should be designed to be as
- simple and intuitive as possible, while ensuring citizens can make complete and
- informed decisions for themselves using the service.
-
-
- There is an emphasis on an accessible experience with a low cognitive load for
- users who use the service infrequently.
-
-
-
-
- Pages
-
-
-
-
-
- 1. Start page
-
-
- This is the starting point for a citizen to begin your form from within your
- service or from Alberta.ca.
-
-
-
- 2. Task list page (optional)
-
-
- Outline the entire process for the user and help them through the process by
- breaking down an experience into individual tasks.
-
-
-
- 3. Question pages
-
-
- Ask a user a question or a small set of related questions.
-
-
-
- 4. Review page
-
-
- Let users check answers before submitting information to a service.
-
-
-
- 5. Results page
-
-
- Let users know that they've completed a form, application, or task and tell
- them what to do next.
-
-
-
-
- );
-}
diff --git a/docs/src/content/examples/public-form/web-components.html b/docs/src/content/examples/public-form/web-components.html
deleted file mode 100644
index fa147357d0..0000000000
--- a/docs/src/content/examples/public-form/web-components.html
+++ /dev/null
@@ -1,45 +0,0 @@
-
-
- Primary users: citizens, public, external
- You are designing a public service for citizens. It should be designed to be as simple
- and intuitive as possible, while ensuring citizens can make complete and informed
- decisions for themselves using the service.
-
- There is an emphasis on an accessible experience with a low cognitive load for users
- who use the service infrequently.
-
-
-
-Pages
-
-
-
- 1. Start page
-
- This is the starting point for a citizen to begin your form from within your service
- or from Alberta.ca.
-
-
- 2. Task list page (optional)
-
- Outline the entire process for the user and help them through the process by
- breaking down an experience into individual tasks.
-
-
- 3. Question pages
-
- Ask a user a question or a small set of related questions.
-
-
- 4. Review page
-
- Let users check answers before submitting information to a service.
-
-
- 5. Results page
-
- Let users know that they've completed a form, application, or task and tell them
- what to do next.
-
-
-
diff --git a/docs/src/content/examples/question-page/index.mdx b/docs/src/content/examples/question-page/index.mdx
index d23077989a..ab95516c23 100644
--- a/docs/src/content/examples/question-page/index.mdx
+++ b/docs/src/content/examples/question-page/index.mdx
@@ -1,39 +1,172 @@
---
id: question-page
title: Question page
-categories:
- - forms
-scale: page
-userType: citizen
+size: page
+productType: public-form
+description: "A question page presents one focused step in a multi-step form. Several variants adapt the shape: section titles, progress indicators, supporting context, expandable help, and grouped fields."
tags:
- forms
- question
- wizard
- one-thing-per-page
+ - public-form
+ - section-title
+ - progress
+ - context
+ - help
+ - details
+ - grouped-fields
+ - address
components:
- form-item
- input
+ - text-area
+ - radio-group
+ - radio-item
+ - dropdown
+ - dropdown-item
+ - details
+ - block
- button
- button-group
+aliases:
+ - ask-a-user-one-question-at-a-time
+ - give-more-information-before-asking-a-question-a
+ - give-more-information-before-asking-a-question-b
+ - show-more-information-to-help-answer-a-question
+ - show-a-list-to-help-answer-a-question
+ - show-a-section-title-on-a-question-page
+ - show-a-simple-progress-indicator-on-a-question-page
+ - show-a-simple-progress-indicator-on-a-question-page-with-multiple-questions
+ - group-related-questions-together-on-a-question-page
status: published
-previewImage: /images/examples/question-page.webp
+previewImage: /images/examples/question-page.png
+hideHero: true
---
-A question page pattern that presents one question at a time to help users focus, reduce cognitive load, and navigate complex forms more easily.
+import PreviewContainer from "../../../components/PreviewContainer.astro";
+
+## Types of question pages
+
+### Ask one question at a time
+
+The default question page. One idea per page reduces cognitive load and keeps users moving through the flow.
+
+
Workspaces should be adapted to fit each service's context and user needs. The reference example is a starting point to expand on, not a rigid template.
-categories: []
-scale: product
-userType: worker
-tags:
- - workspace
- - worker
- - service
- - case-management
- - dashboard
- - pattern
-components:
- - work-side-menu
- - table
- - badge
- - tabs
- - container
- - accordion
- - drawer
- - button
- - block
-previewImage: /thumbnails/workspace-preview.png
-status: published
----
-
-View demo
-
-import LinkCard from "../../../components/LinkCard.astro";
-
-
-
- Main workspace navigation
-
-
-
-
- Contextual case navigation
-
-
-
-View demo
-
----
-
-## Dashboard
-
-The dashboard gives staff an overview of their work.
-
-Include the information that helps them understand priorities and act quickly, such as:
-
-- counts or status summaries
-- trends or workload charts
-- links to assigned or high-priority work
-
-The layout uses [containers](/components/container) and [blocks](/components/block) to organize content into scannable sections.
-
-
-
-View demo
-
----
-
-## Data views
-
-Workers need different ways to view, scan, and act on records depending on the task. Choose the data view that best supports the task.
-
-- **Table view** — Dense, scannable rows with sortable columns. Best for users who need to compare fields across many records at once.
-- **Card view** — Each record as a card showing key details grouped into sections. Useful when records have more complex data that doesn't fit neatly into columns.
-- **Expandable list view** — Compact rows that expand inline to reveal detail. A middle ground between the density of a table and the richness of cards.
-
-Any view can be combined with grouping (for example, group by priority or status) to organize records into collapsible sections. Users can also search, filter by status using [tabs](/components/tabs), sort with multi-level sorting, and manage active filters with [filter chips](/components/filter-chip).
-
-
- Table view
-
-
-
-
- Card view
-
-
-
-
- Expandable list view
-
-
-
-View demo
-
----
-
-## Case detail
-
-Use the case detail view to help users review and act on a single record.
-
-Break long content into sections using [accordions](/components/accordion) to organize submitted data into collapsible sections. A table-of-contents sidebar helps users navigate long case content. [Badges](/components/badge) show case status, and action buttons in the header provide quick access to review, assign, and comment actions.
-
-
-
-View demo
-
----
-
-## Sticky action bar
-
-A scroll-aware header that pins to the top of the content area as the user scrolls. Use it to keep the most important tools visible.
-
-Set the content for each page based on the task:
-
-- On a cases list page, keep tools such as search and key actions visible.
-- On a detail page, keep the case name and key actions visible.
-
-Do not pin everything. Keep only the information and actions people need to continue their work without losing context.
-
-
-
-View demo
-
----
-
-## Push drawer
-
-Use a [push drawer](/components/drawer) for focused work that should happen without leaving the current page.
-
-This works well for actions such as:
-
-- approving or denying a record
-- requesting more information
-- completing a short decision form
-- reviewing supporting details while taking action
-
-Use it when users need to keep the main record in view while completing the task.
-
-
-
-View demo
-
----
-
-## Keyboard-accessible data views
-
-Workspace data views use the [data grid](/components/data-grid) to make table and card layouts fully keyboard navigable. Users can use arrow keys to move between cells and rows, making it possible to scan and act on records without a mouse. This is especially important in workspace contexts where staff are processing high volumes of cases and keyboard navigation is significantly faster than clicking. For assistive technology users, screen readers announce cell content and position as the user navigates.
-
----
-
-## Components built for workspace
-
-Workspace patterns are supported by component features designed for denser, more productive interfaces:
-
-- **Compact inputs** — Every input component now has a `compact` variant that reduces height and spacing. This lets you build tighter forms and toolbars without sacrificing usability.
-- **Compact badges and notifications** — [Badges](/components/badge) and [notification banners](/components/notification) also have compact sizing to fit within dense data views and action bars.
-- **Badge variants** — [Badges](/components/badge) now include `strong` and `subtle` emphasis options, giving you control over visual weight depending on context.
-- **Data grid** — The [data grid](/components/data-grid) works with the table component to support accessible, keyboard-navigable data views. Use them together when the user needs to move through records efficiently without relying on a mouse.
-- **Segmented tabs** — A new [tab](/components/tab) variant that works as a segmented toggle for switching between views or modes within a workspace, rather than navigating between pages.
-- **Enhanced filter chips** — [Filter chips](/components/filter-chip) now support secondary text and secondary icons, making them more useful for richer filtering in workspace data views.
-
----
-
-## Get started
-
-Use one of the workspace templates as a starting point for your service. Each template includes the sidebar navigation, dashboard, data views, and case detail patterns described above.
-
-
- Automated accessibility
+Automated accessibility testing tools help you identify potential accessibility issues. Use them as a starting point.
+
+
+ However, these tools are not a complete solution. They can produce:
+
+
+ - False positives – flagging issues that are not actual problems
+ - False negatives – missing real accessibility barriers
+
+
+ To ensure your digital product is accessible, combine automated testing with manual testing and apply
+ human judgment.
+
+Why automated tools alone are not enough
+
+False positives
+
+ Automated tools may flag elements as non-compliant even when they work correctly for users. For
+ example, a tool may report that an input is "missing an id" even though it is correctly associated with a
+ label using a valid method, such as wrapping the input inside a <label> element.
+
+
+False negatives
+
+ Automated tools cannot detect nuanced or context-specific issues. For example, all interactive
+ elements may be tabbable, but the order jumps around the page. Tools often don't judge whether the
+ tab order is logical for completing the task.
+
+
+Real user experience
+
+ Accessibility ensures real people can use a product effectively. Automated tools cannot fully simulate
+ how users interact with your product.
+
+Steps for effective accessibility testing
+
+
+ -
+ Run automated tools to get an initial assessment.
+
+ -
+ Manually verify flagged issues and review the element's intent and context.
+
+ -
+ Do additional manual testing for issues automated tools cannot detect:
+
+ - Test with a screen reader, such as VoiceOver (macOS) or NVDA (Windows)
+ - Test keyboard navigation by checking focus visibility and order
+
+
+ -
+ Report findings
+
+ - Record what you tested, what failed, and how to reproduce it
+ - If the issue relates to a design system component, submit it using the design system bug report form
+
+
+
+Why this process matters
+
+ Automated tools provide helpful insight. Relying only on automation can result in:
+
+
+ - Time spent fixing issues that are not real barriers
+ - Missed opportunities to address genuine accessibility issues
+ - A false sense of compliance without meaningful usability improvements
+
+
+ Combine automated and manual testing to identify real barriers. This approach improves accessibility
+ and overall product quality.
+
+Component lifecycle
+The component lifecycle defines the stages each Design System component moves through, from Experimental to Production to Legacy.
+
+
+ To request a new component or propose an enhancement, follow the
+ design contribution process.
+
+Experimental
+
+ Experimental components are new or significantly updated. They are available for testing and feedback
+ before public release.
+
+
+Characteristics
+
+ - Feedback is gathered from selected teams
+ - May be unstable or include breaking changes
+ - Limited documentation
+
+Production
+
+ Production components are stable and ready for broader adoption.
+
+
+Characteristics
+
+ - Fully documented, including design guidelines, properties, and examples
+ - Meet accessibility and design system standards
+ - Optimized for mobile use
+ - Actively maintained with updates and bug fixes
+ - Publicly available documentation
+
+Legacy
+
+ Legacy components are older components maintained primarily to support older implementations. If
+ possible, transition to production is recommended.
+
+
+Characteristics
+
+ - No active maintenance or updates
+ - Critical issues may remain unresolved
+ - Recommended alternative clearly identified
+ - Marked as "Legacy" in official documentation
+
+Contribute
+The Design System is a shared resource used and improved by service teams. All roles are encouraged to contribute.
+
+
+ Start by using existing Design System components and patterns. If a component or pattern does not
+ meet your needs, follow the contribution process below.
+
+Design contribution process
+
+ If a required component or example does not exist in production,
+ contact the Design System team. We will review the request together and determine next steps.
+
+
+1. Contact the team
+
+ Book a design system drop-in hours session.
+
+Be prepared to:
+
+ - Describe the component or pattern and its purpose
+ - Explain your user needs and service goals
+ - Share iterations explored with and without the Design System
+
+
+
+ There are open contribution files in Figma for every component and pattern in the design system, including unpublished ideas and experiments.
+
+
+2. Contribution criteria
+A proposed component or pattern must meet the following criteria.
+
+Proposal criteria
+Useful
+
+ Evidence shows it supports multiple teams or services. Provide screenshots or links to demonstrate usage.
+
+
+Unique
+
+ It does not duplicate an existing component or pattern. If replacing an existing component, provide
+ evidence that the new approach improves usability or accessibility.
+
+
+Publication standards
+To be published, the solution must be:
+
+Usable
+
+ Improves clarity, usability, and accessibility for users. Is informed by research and addresses a
+ validated user need.
+
+
+Universal
+
+ Inclusive and accessible. Meets or exceeds accessibility standards.
+ WCAG 2.2 AA is the minimum requirement.
+
+
+3. Backlog and collaboration
+
+ If approved, the item is added to the
+ Design System's backlog.
+
+
+ When development begins, the Design System team will collaborate with you to confirm detailed requirements.
+
+Code contribution process
+
+ The Design System supports multiple development frameworks through Web Components. Contributing full
+ components can be complex. Smaller contributions are encouraged.
+
+
+Recommended contribution types
+
+ - Bug fixes
+ - Documentation updates
+ - Enhancements to existing components
+
+
+ Start by contacting the team in the #design-system-support Slack channel.
+
+
+ Select an issue tagged ready-for-contribution from the
+ backlog.
+ Confirm which issue you will work on.
+
+
+
+ Since the repository is public, use a personal GitHub account instead of your Enterprise Managed User (EMU) account.
+
+
+Set up your contribution environment
+
+ - Clone the ui-components repository.
+ - Open the repository in your IDE.
+ - Create a branch named:
contributions/story-number
+ -
+ Run the following commands:
+
npm i
+npm run build
+
+ -
+ The playgrounds for local testing are located in:
+
/apps/dev/angular
+/apps/dev/react
+
+
+
+Run playground environments
+Angular
+npm run dev:watch
+npm run serve:dev:angular
+
+React
+npm run dev:watch
+npm run serve:dev:react
+
+Repository structure
+
+React wrappers
+/libs/react-components/src/lib
+Each folder represents a single component with its associated unit tests and wrapper code.
+
+Angular wrappers
+/libs/angular-components/src/lib/components
+Each folder represents a single component with its associated unit tests and wrapper code.
+
+Web Components
+/libs/web-components/src/components
+
+ - Unit tests as
{"*.spec.ts"}
+ - Component code as
{"*.svelte"}
+
+
+Testing requirements
+
+ - Write all unit tests in Svelte.
+ - If updating React or Angular wrappers, write unit tests in those respective frameworks.
+ -
+ Add browser testing using Jest for React wrappers and Svelte components when appropriate.
+ These can be found in:
libs/react-components/specs
+
+ - Manually test components in both React and Angular.
+ -
+ Create test files that others can use to manually test the PR. These can be created in:
+
/apps/prs/angular
+/apps/prs/react
+
+ - Follow the conventions already used in those files to create your test files.
+
+A Design System developer will also manually test the pull request.
+
+Submit your contribution
+Use the following commit message format:
+
+Bug fix
+fix(#storyNumber): short description (7 words max)
+
+Feature request
+feat(#storyNumber): short description (7 words max)
+
+
+ - Create a pull request from your branch to the
dev branch.
+ - Notify the design system team of the PR.
+
+Overview
+As a designer, you use the design system through Figma.
+In Figma, you can access:
+
+
+ - Design tokens
+ - Components
+ - Patterns
+
+
+
+ The design system library in Figma aligns with coded components used by developers. Start with
+ design system components for common parts of your service. This helps developers use the matching
+ coded components and reduces custom work.
+
+
+ Start with the design system. Validate your design through user testing. If usability issues arise,
+ or the problem cannot be solved within the system, consider creating a custom solution.
+
+Design with development in mind
+
+ When selecting components, prioritize those with a "goa-" prefix, such as
+ goa-input. These components exist in both design and development. Using them reduces
+ the need for custom development.
+
+Choose shared components whenever possible to maintain consistency and efficiency.
+
+Design tokens
+Design system components in Figma and code are built using design tokens.
+
+ Use tokens to communicate design decisions clearly. Developers can reference the same tokens in code.
+
+Instead of sharing hex values or pixel adjustments, reference semantic tokens.
+For example:
+
+ - Colour:
--goa-color-info-default
+ - Spacing:
--goa-spacing-m
+
+Using tokens reduces back-and-forth and keeps design and development aligned.
+
+Components
+All design system components are available in Figma and in code.
+
+ These components are designed to meet
+ WCAG 2.2 accessibility standards.
+
+Avoid detaching components. Instead:
+
+ - Use variants
+ - Show or hide layers within the component
+
+
+ Use #figma for Figma-related issues, including library updates, missing components,
+ broken instances, or component behaviour in Figma.
+
+
+ Use #design-system-support for design system guidance, component usage questions,
+ standards, and implementation support.
+
+Keep your components up to date. Figma will notify you when library updates are available.
+
+Figma file templates and helper components
+Each digital service project folder includes a starter Figma template.
+Use this template to:
+
+ - Organize your design file
+ - Support developer handoff
+ - Help team members navigate files
+
+
+ Helper components are also available. Use them to clearly communicate intent when sharing designs
+ with developers and other team members.
+
+Designing for dark mode
+
+ Dark mode is handled by the design system. Here's what that means for your designs.
+
+
+
+
+ Available in code now, not in Figma yet. Design in light mode and work with a developer to see your designs in dark mode.
+
+
+
+How it works
+
+ We have an experimental version of dark mode you can try out in your service. It's handled automatically in code, so designers don't need to do anything different. The Figma library doesn't have a dark mode yet, so keep designing in light mode like you always have. Your designs will translate to dark mode when developers add the dark mode theme to your service.
+
+
+Custom components and styles
+
+ If you're using design system components, they all work with dark mode automatically.
+
+
+ If you have custom components that use our design tokens, they'll switch to dark mode along with the rest of the system. Always worth testing to make sure things look right in both modes.
+
+
+ If your custom components don't use our design tokens, they won't switch on their own. You'll need to handle dark mode for those yourself. We recommend using design tokens where you can so most of this happens automatically.
+
+
+ Either way, you can extend dark mode for custom needs by working with developers to add custom dark mode styles to your service.
+
+
+ The same goes for illustrations and images with set colors. These look the same in both modes, so check whether they read well on a dark background or whether you need a dark version.
+
+
+Try it and share feedback
+
+ Dark mode is still being tested. Try it out in your service and let the design system team know what works, what doesn't, and what's missing.
+
+
+Ways to apply dark mode in your service
+
+ Two ways users end up in dark mode. Use either, or both:
+
+
+ - System settings. If their operating system is in dark mode, your service follows automatically.
+ - A toggle in your service. Let users switch modes themselves through a preferences or settings screen.
+
diff --git a/docs/src/content/get-started/designers/designing-with-ds.mdx b/docs/src/content/get-started/designers/designing-with-ds.mdx
new file mode 100644
index 0000000000..3be1641e5b
--- /dev/null
+++ b/docs/src/content/get-started/designers/designing-with-ds.mdx
@@ -0,0 +1,71 @@
+---
+id: designers/designing-with-ds
+title: Designing with Design System 2.0
+description: How to start new designs and update existing projects to Design System 2.0
+section: designers
+order: 2
+status: published
+---
+import DropInCallout from "../../../components/DropInCallout.astro";
+
+Designing with Design System 2.0
+What's new in DS 2.0 and how to start using it in your designs.
+
+ The Digital Design and Delivery (DDD) Design System has evolved to better support how service teams
+ design and build digital government services. Design System 2.0 includes an updated design
+ language, new tokens, refreshed components, and ready-to-use templates.
+
+Starting a new design
+
+ Use DS 2.0 templates as your starting point. Templates package layout, navigation, spacing, and
+ example content that you can adapt to your service. Some templates are built for specific service types
+ (for example, public-facing forms and workspace applications), and others are more general-purpose
+ starting points you can use across many kinds of pages and flows.
+
+
+Starting from an existing design
+
+Library swap
+
+ Use a library swap if
+ your goal is to convert most of the file to DS 2.0 in one pass.
+
+
+ - Make a copy of your file before you start.
+ - Expect mixed results. Some screens may need cleanup after the swap.
+
+
+Manual rebuild
+Use a manual rebuild if you need more control.
+
+ - Rebuild your highest value screens first.
+ - Consider using DS 2.0 templates as a base to speed things up.
+
+Update an existing project to the new design library
+
+Approach 1: Developer-first
+Use this approach in most cases.
+
+ - A developer creates a new branch and completes the upgrade steps.
+ - The team runs the upgraded application to see what changed.
+ - Designers review the upgraded screens and identify what needs design updates.
+
+When reviewing the upgraded branch, watch for:
+
+ - Spacing and layout rhythm
+ - Typography scale and weight usage
+ - Dense or constrained screens (these often have the highest risk during an update)
+
+
+Approach 2: Design-first
+Use this approach when you want design work to move ahead of development work.
+
+ - Identify custom elements that support your users' needs.
+ - Create an inventory and prioritize items by importance and effort.
+ - Redesign the highest priority items using the visual design values in the Styles library.
+
+
+
+ In most cases, start with the developer-first approach. It helps you quickly see what changed in your real product, so you can focus design effort where it matters most.
+
+User experience guidelines
+Digital products built for the Government of Alberta should comply with these guidelines to ensure a quality user experience for Albertans.
+
+
+ - User-centered: Designed with a clear understanding of users, their goals, tasks, environments, and context of use, using user-centered design methods.
+ - Usable: Interfaces will be easy to use, enabling users to find the information they need and complete tasks successfully.
+ - Accessible: Digital products will be inclusive, ensuring usability for everyone, regardless of physical or cognitive ability.
+ - Trustworthy: Experiences will feel familiar and recognizable as a Government of Alberta product, ensuring users' security and privacy.
+ - Modern: Digital experiences will meet present-day user expectations and preferences for aesthetics and interaction.
+
+
+
+ For more details on the process of assessing compliance to each guideline, refer to our
+ User Experience Guidelines and Design System Checklist.
+
+Usability testing
+
+ Usability testing is our preferred method to understand user needs as they relate to each guideline.
+
+Suitable usability testing includes:
+
+ - Diverse user group: Real users from different demographic, behavioural backgrounds, and geographical regions within Alberta that will experience the problem or benefit of the product.
+ - Inclusive testing: Users with various physical and/or cognitive abilities, literacy levels, and tech savviness.
+ - Device variety: A diverse range of devices that reflect users' preferred choice when interacting with government services.
+ - Tasks: Activities that cover tasks and service process from end-to-end.
+
+
+ Frequent usability testing should be conducted to maintain product usability, effectiveness and
+ alignment to the user needs as they evolve over time.
+
+
+ For guidance on the process of usability testing, refer to our
+ Understanding Usability documentation.
+
+Overview
+As a developer, you use the Design System through tokens, components, examples, and templates.
+
+
+ The DDD Design System is built using Web Components. Web Components are framework-agnostic.
+ You can use them with Angular, React, or other front-end frameworks.
+
+The Design System includes:
+
+ - Tokens
+ - Components
+ - Examples
+ - Templates
+
+
+ Designers use equivalent resources in Figma. When they design with Design System components, you
+ can build with the matching coded components. This reduces custom development and rework.
+
+
+ All Design System components are designed and built to meet
+ WCAG 2.2 accessibility standards.
+
+Tokens
+
+ Access the tokens as an
+ NPM package.
+
+
+ Import the SCSS or CSS file into your project. Replace hard-coded values with Design System token variables.
+
+
+ Designers reference the same tokens in their tools. This keeps design and development aligned during handoff.
+
+
+Components
+Components are reusable user interface elements built for use across services.
+You can:
+
+ - Use components individually
+ - Combine them into patterns
+ - Apply them in different contexts
+
+Components are available:
+
+ - As Web Components
+ - As Angular wrappers
+ - As React wrappers
+
+
+ Refer to the Design System technologies documentation
+ for implementation details.
+
+
+Examples
+
+ Examples are multiple components assembled in realistic service contexts. They help you understand
+ how to apply Design System guidance in a working interface.
+
+You can use examples to:
+
+ - Understand how components work together
+ - Use them as a starting point for building parts of your interface
+ - Use proven approaches to meet user needs
+
+
+ Examples help you build with more consistency and less rework. Use them to guide implementation,
+ then adjust them to meet the needs of your product.
+
+
+Templates
+
+ Templates are opinionated starting points for common service types. They package layout, navigation,
+ spacing, and example content so you can start with a proven structure instead of building from scratch.
+
+You can use templates to:
+
+ - Start a new product with a proven structure
+ - Learn how components work together in a real layout
+ - Adapt a proven starting point to fit your service needs
+
+
+ Templates help teams move faster, reduce rework, and stay aligned with Design System guidance.
+
+Supported browsers
+Design System components are tested across supported browsers and devices.
+
+
+ We support the latest version of each browser listed on this page. Support applies to the browser and
+ operating system combinations shown in the table below. On mobile, support is limited to the browser
+ and operating system combinations listed for Android and iOS.
+
+
+Browser and operating system support
+
+
+
+
+
+ Browser
+ Windows
+ Mac OS
+ Android
+ iOS
+
+
+
+
+ Google Chrome
+ Yes
+ Yes
+ Yes
+ Yes
+
+
+ Microsoft Edge
+ Yes
+ Yes
+
+
+ Mozilla Firefox
+ Yes
+ Yes
+ Yes
+
+
+ Apple Safari
+ N/A
+ Yes
+ N/A
+ Yes
+
+
+
+
+
+Representative mobile OS used in testing
+
+ - Android OS: 10+
+ - iOS: 15+
+
+Testing guidance
+
+ Use supported browsers and operating system versions when developing and testing services. If you
+ encounter a browser-specific issue, follow the
+ Verify a bug process.
+
+Verify a bug
+Follow this process when you encounter an issue with a Design System component.
+
+
+ These steps help confirm whether the issue is caused by the Design System, your product setup, or
+ custom code. This process applies to Angular and React implementations.
+
+
+1. Check versions
+Confirm you are using the latest version of:
+
+ - Web Components
+ - Angular or React
+
+
+ If you are not using the latest version, upgrade and retest. If the issue remains, continue to the next step.
+
+
+2. Test with product templates
+Use the official Angular or React product templates to isolate the issue.
+
+This helps determine whether the issue exists outside your project configuration.
+
+3. Recreate the issue
+Create a minimal test environment.
+
+ - Use only the code required for the example to function
+ - Include only the component experiencing the issue
+ - Remove unrelated dependencies or custom logic
+
+Confirm whether the issue can be replicated.
+
+4. Share and report
+If you can reproduce the issue:
+
+ - Share the template application link in the #design-system-support Slack channel
+ - Provide a link to your repository so the team can review and replicate the issue
+
+
+ Following these steps will help to ensure efficient investigation and quicker resolution of
+ design system component issues.
+
+Dark mode theme
+
+ Toggle light and dark mode using the React useTheme hook or the Angular
+ GoabThemeService. The user's choice persists across sessions.
+
+
+
+
+ Dark mode is still being tested. The CSS API and tokens may evolve as we iterate.
+
+
+
+
+
+ Theme switching requires @abgov/design-tokens version 2.8.0 or
+ higher with the dark theme stylesheet imported. See Setup
+ for installation steps.
+
+
+
+How it works
+
+ Both the React provider and the Angular service write a data-theme
+ attribute on the document root (<html>). Design tokens scoped
+ to :root[data-theme="dark"] activate via CSS cascade,
+ automatically applying dark colors to every component without re-rendering.
+
+
+Initial mode priority
+
+ On first load, the active mode is resolved in this order:
+
+
+ - The user's previously chosen mode, read from local storage
+ - The operating system preference (light or dark)
+ - The framework default (light)
+
+
+React
+
+ The React package exposes a context provider and a hook.
+
+
+1. Wrap your app with GoabThemeProvider
+
+ Place the provider near the top of your app, alongside other framework
+ providers such as BrowserRouter:
+
+{`// main.tsx
+import { GoabThemeProvider } from "@abgov/react-components";
+import { BrowserRouter } from "react-router-dom";
+import "@abgov/design-tokens/dist/tokens.css";
+import "@abgov/design-tokens/dist/dark-theme.css";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+
+
+
+ ,
+);`}
+
+2. Read and toggle theme with useTheme
+
+ Inside any component below the provider, call useTheme() to read
+ the current mode and switch theme:
+
+{`import { GoabButton, useTheme } from "@abgov/react-components";
+
+function ThemeToggle() {
+ const { mode, toggle } = useTheme();
+ const isDark = mode === "dark";
+
+ return (
+
+ {isDark ? "Light mode" : "Dark mode"}
+
+ );
+}`}
+
+API
+{`interface GoabThemeContextValue {
+ /** Current theme mode. */
+ mode: "light" | "dark";
+ /** Set theme to a specific mode. */
+ setMode: (next: "light" | "dark") => void;
+ /** Flip between light and dark. */
+ toggle: () => void;
+}
+
+interface GoabThemeProviderProps {
+ children: ReactNode;
+ /** Initial mode used when no stored or system preference is found. @default "light" */
+ defaultMode?: "light" | "dark";
+}`}
+
+
+
+ useTheme throws if called outside of GoabThemeProvider.
+
+
+
+Angular
+
+ The Angular package exposes a root-provided service backed by a Signal.
+
+
+1. Import the dark theme stylesheet
+
+ Add the import to your global stylesheet (typically src/styles.css):
+
+@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+@import "@abgov/design-tokens/dist/dark-theme.css";
+
+2. Inject GoabThemeService
+
+ The service is provided in root, so inject it from any component or service:
+
+{`// app.component.ts
+import { Component, inject } from "@angular/core";
+import { GoabThemeService } from "@abgov/angular-components";
+
+@Component({
+ selector: "app-root",
+ templateUrl: "./app.component.html",
+})
+export class AppComponent {
+ readonly theme = inject(GoabThemeService);
+
+ toggleTheme() {
+ this.theme.toggle();
+ }
+}`}
+
+3. Bind to the signal in templates
+
+ Read theme.mode() as a signal — Angular tracks the dependency
+ automatically and re-renders when the mode changes:
+
+{`
+
+ {{ theme.mode() === "dark" ? "Light mode" : "Dark mode" }}
+ `}
+
+API
+{`@Injectable({ providedIn: "root" })
+class GoabThemeService {
+ /** Read-only signal — use in templates: theme.mode() === "dark". */
+ readonly mode: Signal<"light" | "dark">;
+ /** Set theme to a specific mode. */
+ setMode(next: "light" | "dark"): void;
+ /** Flip between light and dark. */
+ toggle(): void;
+}`}
+
+Custom styling for dark mode
+
+ If you're using design system components, they handle dark mode automatically.
+
+
+ If your custom CSS uses design system tokens, dark mode is handled too. The tokens cascade to their dark values when data-theme="dark" is active.
+
+{`.my-card {
+ background-color: var(--goa-color-surface-card);
+}`}
+
+ Always verify in both modes.
+
+
+ If your custom CSS uses values that aren't from our design tokens (specific colors, backgrounds, hardcoded styles), those won't switch on their own. You can either swap them out for design tokens where possible, or extend dark mode by setting up your own custom property and overriding it under :root[data-theme="dark"]:
+
+{`/* Default (light) value */
+:root {
+ --my-card-background: #f9f9f9;
+}
+
+/* Dark mode value */
+:root[data-theme="dark"] {
+ --my-card-background: #1a1a1a;
+}
+
+/* Use it in your component */
+.my-card {
+ background-color: var(--my-card-background);
+}`}
+
+Using design tokens in SCSS
+
+
+
+ Dark theme support requires CSS custom properties. Sass variables
+ ({`$goa-*`}) are inlined at compile time and cannot flip when the
+ theme changes. Reference tokens via {`var(--goa-*)`} wherever a
+ value should respond to theme switching.
+
+
+
+
+ The simplest setup imports only tokens.css and uses
+ {`var(--goa-*)`} everywhere — every token automatically participates
+ in theme switching, and there is one syntax to remember.
+
+{`@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+@import "@abgov/design-tokens/dist/dark-theme.css";`}
+{`.my-card {
+ background: var(--goa-color-surface-card);
+ font-family: var(--goa-font-family-sans);
+ padding: var(--goa-space-m);
+ transition-duration: var(--goa-motion-duration-medium-2);
+}`}
+
+When you need Sass variables
+
+ Some workflows need Sass arithmetic, mixins, or functions over token values
+ (for example {`$goa-space-m * 2`}). In that case, import
+ tokens.scss alongside the CSS files and use {`$goa-*`}
+ for compile-time values only — never for colors, surfaces, or anything that
+ should flip with theme.
+
+{`@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+@import "@abgov/design-tokens/dist/dark-theme.css";
+@import "@abgov/design-tokens/dist/tokens.scss";`}
+{`.my-card {
+ // Theme-responsive — must use var()
+ background: var(--goa-color-surface-card);
+
+ // Compile-time only — Sass arithmetic OK
+ padding: $goa-space-m * 2;
+ border-radius: $goa-border-radius-m;
+}`}
diff --git a/docs/src/content/get-started/developers/setup.mdx b/docs/src/content/get-started/developers/setup.mdx
new file mode 100644
index 0000000000..3eda4feeca
--- /dev/null
+++ b/docs/src/content/get-started/developers/setup.mdx
@@ -0,0 +1,128 @@
+---
+id: developers/setup
+title: Developer setup
+navLabel: Setup
+description: Set up Angular, React, or Web Components to use the GoA Design System
+section: developers
+order: 2
+status: published
+---
+import DropInCallout from "../../../components/DropInCallout.astro";
+
+Developer setup
+Set up the Government of Alberta Design System in Angular, React, or directly with Web Components.
+
+Angular UI components
+
+ Supported versions: 18, 19, 20, 21
+
+
+ This is the web component library and utilizes Angular's web component
+ integration.
+
+
+1. Add dependencies
+npm i @abgov/web-components
+npm i @abgov/angular-components
+npm i @abgov/ui-components-common
+npm i @abgov/design-tokens
+
+2. Link ionicons in app/index.html
+
+ Add the following in the head element:
+
+{`
+`}
+
+3. Update src/app/app.module.ts
+
+ Update src/app/app.module.ts as per the four steps below:
+
+{`// 1. Import the CUSTOM_ELEMENTS_SCHEMA
+import { CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
+
+// 2. Import the libs
+import "@abgov/web-components";
+import { AngularComponentsModule } from "@abgov/angular-components";
+
+@NgModule({
+ declarations: [AppComponent],
+ imports: [
+ // 3. Add the needed imports
+ BrowserModule,
+ AngularComponentsModule,
+ ],
+ providers: [],
+ bootstrap: [AppComponent],
+ // 4. Add the CUSTOM_ELEMENTS_SCHEMA to the NgModule
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ })
+export class AppModule {}`}
+
+4. Add the styles link in src/styles.css
+@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+
+React UI components
+
+ Supported versions: 17, 18, 19
+
+
+ This library contains React components which wrap the Government of Alberta Web
+ Components.
+
+
+1. Add dependencies
+npm i @abgov/react-components
+npm i @abgov/web-components
+npm i @abgov/ui-components-common
+npm i @abgov/design-tokens
+
+2. Link ionicons in app/index.html
+
+ Add the following to the head element:
+
+{`
+`}
+
+3. Import the web components in src/main.tsx
+import "@abgov/web-components";
+
+4. Import the styles in src/index.css
+@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+
+Web components
+
+ This library contains web components from the Government of Alberta.
+
+
+1. Add dependencies
+npm i @abgov/web-components
+npm i @abgov/design-tokens
+
+2. Link ionicons in index.html
+
+ Add the following in the head element:
+
+{`
+`}
+
+3. Import the web components into src/main.js
+import "@abgov/web-components";
+
+4. Add the styles link in your main CSS file
+
+ Add the following in src/assets/main.css or wherever your main CSS file is
+ located:
+
+@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+
+Technologies
+An overview of the technologies used in the Design System.
+
+How the technologies fit together
+
+ The Design System is built on Web Components. Most component functionality lives in the core Web
+ Components layer. Angular and React wrappers sit on top of that layer to make the components easier
+ to use in those frameworks.
+
+
+ We use Svelte to author the components that are compiled to custom elements. You can use the Design
+ System through the core Web Components or through Angular and React wrappers.
+
+})
+Web Components
+
+ Web Components
+ are a set of standard web technologies that allow you to create reusable custom elements. Each component
+ includes its own structure, styling, and behaviour. This keeps it independent from the rest of your code.
+
+
+ In the Design System, Web Components are the core library. They are framework-agnostic, so teams
+ can use them in different front-end environments.
+
+
+Benefits of using Web Components
+
+ - Reuse: Build once and use across pages, applications, and frameworks
+ - Browser support: Work in modern browsers without additional libraries
+ - Maintenance: Modular and self-contained structure simplifies updates
+ - Encapsulation: Structure, style, and behaviour remain isolated from other page elements
+ - Reliability: Code is not spread across HTML and JS files, thereby avoiding inconsistencies
+ - Flexibility: Use inline, import, or compile components as needed
+ - Composability: Combine components or integrate them with other components
+
+
+
+ Do not use Web Components directly unless there is a specific reason to do so. Using wrappers provides type checking and developer helpers that are not available when working with the core Web Components alone.
+
+Svelte
+
+ Svelte is the framework used to generate the
+ Design System Web Components. Svelte combines JavaScript (logic), HTML (structure), and CSS (style)
+ within a single file. It compiles these into efficient, reusable components.
+
+Why Svelte
+We use Svelte to:
+
+ - Build reusable Web Components
+ - Keep component logic, structure, and styling together
+ - Support integration with multiple front-end frameworks
+
+Angular
+
+
+ Supported versions: 18, 19, 20, 21
+
+
+
+ Angular is a TypeScript-based framework for building
+ web applications. The Design System supports Angular through Angular wrappers around the core Web Components.
+
+
+How Web Components and Angular work together
+Angular wrappers are created around the Web Components. These wrappers:
+
+ - Manage component properties and events
+ - Support form binding (Reactive and Template-driven)
+ - Allow integration within Angular applications
+
+The Angular application interacts with the wrapper, which renders the underlying Web Component.
+React
+
+
+ Supported versions: 17, 18, 19
+
+
+
+ React is an open-source JavaScript library used to
+ build user interfaces from reusable components.
+
+
+How Web Components and React work together
+React wrappers are created around the Web Components. These wrappers:
+
+ - Manage properties and events
+ - Enable integration within React applications
+
+The React application interacts with the wrapper, which renders the underlying Web Component.
+Updating your product
+The updated design system includes a new design language, updated design tokens and components, and new templates. For your product, updating means:
+
+ - Your service stays aligned with the current GoA standard as more services update and users move between them
+ - You get access to new component properties, examples, and templates that reduce build time for common service types
+ - Your product remains supported — the legacy design system stops receiving fixes after September 2026
+
+
+ Most of the update applies automatically. Most of the work will be reviewing what changed in
+ your product and deciding where design follow-up is needed. These steps help you work through
+ the process.
+
+
+Use the developer-first approach
+
+ The developer-first approach lets you see what actually changed in your product before
+ committing to design work.
+
+
+ When you run the update first, spacing, typography, and token changes apply automatically. You
+ can then review the result with your team and focus design and development effort on the screens
+ that need it most. This avoids redesigning screens based on assumptions about what will change
+ before you update.
+
+
+Migration walkthrough
+
+ The migration walkthrough steps through four stages — legacy design system, upgrade applied,
+ layout and styling fixes, and custom component updates — and shows the visual impact on your
+ interface at each stage. The walkthrough covers both public form and workspace product types.
+ Review it with your team before you start: it helps designers and developers see where changes
+ occur, and gives product owners a clearer picture of the scope for planning.
+
+
+ Explore the migration walkthrough
+
+
+Why we recommend updating all at once
+
+ Applying the update to some parts of your product but not others tends to cause the update to
+ stall. Teams focus on a few components then deprioritize the rest, leaving the product in a
+ mixed state that becomes harder to resolve over time. Reviewing your updated application
+ together in step 3 is designed to address this. Reviewing the full update in a branch before
+ committing gives your team a clear picture of the actual work involved. Use that branch to plan
+ your migration window — you are not committing to proceeding until you are ready.
+
+
+Migration steps
+
+Step 1: Create a branch
+
+ Create a dedicated branch for the update. Keeping it separate from your regular development
+ work lets your team review the changes before merging.
+
+git checkout -b ds-migration
+Use a branch name that works for your team — this is just an example.
+
+Step 2: Run the version update
+
+ Follow the steps in Setup to install the
+ updated packages. Run your application after installing the updates. Do this before making any
+ other changes.
+
+
+Step 3: Review the updated application as a team
+
+ Walk through your application with your product team. At this stage, the team will identify
+ what needs attention and decide what to prioritize.
+
+What to look for:
+
+
+
+
+
+ Area
+ What to look for
+
+
+
+
+ Spacing and layout
+ Screens that feel too tight or unbalanced
+
+
+ Typography
+ Headings or body text that look off in size or weight
+
+
+ Dense or data-heavy screens
+ These carry the most risk during an update and often need the most follow-up
+
+
+ Custom components
+ Anything built outside the design system that needs manual alignment
+
+
+
+
+
+
+ Record what you find. A list of screens and issues is enough at this stage. Your designers and
+ product owner can use that output to plan and prioritize work.
+
+
+Understanding the effort
+
+ There is no single estimate for how long a migration takes. It varies depending on your
+ product. The main factors are:
+
+
+
+
+
+
+ Factor
+ Impact on migration effort
+
+
+
+
+ App size
+ More screens means more to test and review after the update
+
+
+ Design system utilization
+ Products with more custom code need more manual alignment
+
+
+ Developer familiarity
+ Developers with more design system experience move faster through the migration steps
+
+
+
+
+
+
+ Use the team review of your updated application in step 3 to build a realistic estimate for
+ your own product before committing to a timeline.
+
+
+Getting help
+
+ - Bring what you find when reviewing your updated application to drop-in hours to get feedback on what to prioritize
+ - If you find a problem with the design system itself, reach out on the support channel rather than working around it
+
+
+Start with the design system
+Start with the design system to build on the research and experience of other service teams. This helps you avoid repeating work that has already been done.
+
+
+ The design system gives you a strong foundation for common service needs. It allows your team to focus on the specific challenges of your product.
+ Build on it. Do not start from scratch.
+
+
+Design system by role
+
+
+
+Why start with the design system?
+
+Streamline collaboration
+
+ Designers and developers work from shared components and guidance. This reduces rework and misalignment.
+
+
+Improve accessibility
+Accessibility is built into both the design and coded components.
+
+Reduce testing effort
+Components are tested across devices, browsers, and service contexts.
+
+Maintain consistency
+
+ Components align with the broader system to create a cohesive user experience across government services.
+
+
+Spend more time on high-value work
+Using existing components saves time. You can focus on work that improves service quality, including:
+
+ - Usability testing
+ - User research
+ - Content design
+ - Accessibility reviews
+ - Design quality checks
+ - Low-fidelity prototyping and testing
+
+This leads to better outcomes for users.
+How to use the design system in your service
+Follow these steps when designing and building your service.
+
+Use system components first
+Start with existing components and patterns. These meet most user needs.
+
+Identify gaps through user testing
+Test your service with users. Identify needs that are not covered by current components.
+
+Before you design something new
+
+ Check what's already available and what's in progress. The team can point you to existing components,
+ solutions other teams have built, and planned work that may meet your need.
+
+
+Design and test new solutions when you need them
+
+ If you still have a gap, design a new solution and test it with users. Move forward only when
+ testing shows clear user value.
+
+
+Share what you learn
+
+ Share your findings with the design system team. Your solution may become part of the design system.
+
+
+
+ Do not create custom components without a clear user need.
+ Unnecessary customization:
+
+ - Increases maintenance effort
+ - Slows delivery
+ - Reduces consistency
+
+ Always confirm the need through research and testing.
+
+
+
+ View the design system governance process
+
+Migration guide
+Design System 2.0 (DS 2.0) becomes the Government of Alberta standard in March 2026. New products starting after launch should use DS 2.0. Existing active products should plan their move to DS 2.0 during the recommended migration window, which runs from March 2026 to September 2026.
+
+Migration pathways
+The right migration path depends on your product's context, including team funding and capacity, other delivery obligations, product lifecycle, and the effort required to update. The three pathways are standard migration, late migration, and no migration.
+
+Starting a new product
+If your product starts after March 2026, start with DS 2.0. Migration pathways apply to existing products moving from DS 1.x to DS 2.0.
+
+Compare the pathways
+
+
+
+
+
+ Pathway
+ Use it when
+ Recommendation
+
+
+
+
+ Standard migration Your product has an active funded team and can migrate by September 2026 Recommended default
+
+ Late migration Your team cannot meet the standard window because of delivery timelines, dependencies, or capacity constraints Only when necessary
+
+ No migration Your product does not have an active funded team and/or is not in a position to upgrade Only in specific cases
+
+
+
+
+
+Standard migration
+Standard migration is the default pathway for active products.
+Choose this path if your product has an active funded team and can schedule migration work between March 2026 and September 2026. This is the recommended path for most teams because it keeps your product aligned with the current standard and gives you the best support.
+Use this pathway when:
+
+ - your product is actively maintained
+ - your team can reserve time to migrate by September 2026
+ - you want access to the latest templates, components, tokens, and guidance
+
+Plan for work across the product team. Typical upgrade tasks include the library updates, adjusting spacing and typography, and updating custom code to align with the DS 2.0 visual design. This is a significant update and will usually involve design, development, and testing.
+
+Late migration
+Late migration is a last-resort pathway for active products.
+Choose this path only when delivery deadlines, dependencies, or capacity constraints make the standard migration window unrealistic. This path gives your team more time, but it also increases risk and reduces your ongoing support.
+Use this pathway when:
+
+ - a major delivery deadline blocks migration work
+ - critical dependencies prevent the upgrade during the standard window
+ - capacity or funding makes the standard window unrealistic
+
+Delaying migration means your product will wait longer to benefit from DS 2.0 improvements. Over time, unresolved issues will accumulate and your product will be inconsistent with the new standard for longer.
+
+No migration
+No migration is an opt-out pathway for specific situations.
+Choose this path only when your product does not have an active funded team and/or is not in a position to upgrade. In these cases, the product may remain on DS 1.x.
+Teams on this path should understand that the product will not receive DS 2.0 improvements and will not align with the current standard. Support for DS 1.x is limited from March to September and ends after September 2026.
+
+What changes after launch
+After the DS 2.0 launch in March 2026:
+
+ - New products should use DS 2.0
+ - Active products should aim to migrate by September 2026
+ - After launch, web components will move to version 2.x. Although this is a major version update, it does not include breaking changes.
+ - Angular 4.x and React 6.x receive limited fixes or features from March to September
+ - Support for DS 1.0 ends after September 2026
+ - Web components will update to a new major version after September 2026
+
+
+How to choose a pathway
+Use these questions to guide your decision:
+
+ - Is this a new product starting after March 2026?
+ - Does the product have an active funded team?
+ - Can the team schedule migration work before September 2026?
+ - Are there delivery deadlines or dependencies that block the standard window?
+ - Is the team prepared to accept reduced support and higher maintenance risk if migration is delayed?
+
+
+Related guidance
+
+ Review the setup steps for developers
+
diff --git a/docs/src/content/get-started/out-of-support.mdx b/docs/src/content/get-started/out-of-support.mdx
new file mode 100644
index 0000000000..fa61fea200
--- /dev/null
+++ b/docs/src/content/get-started/out-of-support.mdx
@@ -0,0 +1,43 @@
+---
+id: out-of-support
+title: Out of support versions
+description: Design System versions that are no longer supported
+section: appendix
+order: 3
+status: published
+---
+import { withBase } from "@/lib/base-url";
+import DropInCallout from "../../components/DropInCallout.astro";
+
+Out-of-support versions
+With the launch of the new Design System, support for Angular v4 and lower, and React v6 and lower is significantly reduced.
+
+What this means
+
+Fewer fixes or patches
+Bug fixes and security updates are no longer prioritized for these versions.
+
+No new features
+All new features and enhancements are released only in the current major version.
+
+Use at your own risk
+Existing projects may continue to run. However:
+
+ - Compatibility with new browsers or operating systems is not guaranteed
+ - Compatibility with future framework updates is not guaranteed
+ - Issues discovered in these versions will not be resolved
+
+
+
+ Projects using Angular v4 and lower, and React v6 and lower will continue to function. New issues or defects identified in these versions may not be fixed.
+
+What to do next
+
+ Upgrade to the latest supported version. Refer to the
+ Developer setup page.
+
+
+ If you need support planning your upgrade,
+ book time in drop-in hours.
+
+QA testing
+This page outlines the testing process for the Design System. The process ensures components function correctly and integrate within products.
+
+Testing objectives
+QA testing ensures that:
+
+ - Coded components match the design specifications
+ - Components work in both React and Angular implementations
+ - Components are responsive across screen sizes
+ - Components meet accessibility requirements
+ - Mobile behaviour is validated
+ - Documentation on the Design System website is accurate
+
+Test cases
+
+Component testing
+
+ - Confirm the rendered component matches design and styling guidelines
+ - Confirm configured properties display correctly
+ - Confirm the expected event triggers when interacting with the component
+
+
+Responsiveness testing
+
+ - Test components on mobile, tablet, and desktop screen sizes
+ - Use browser developer tools to simulate devices
+
+
+Accessibility testing
+
+ - Run Lighthouse audits to review accessibility scores
+ - Confirm appropriate ARIA (Accessible Rich Internet Applications) roles and labels
+ - Test keyboard navigation
+ - Test with NVDA screen reader
+
+
+Cross-browser testing
+
+ - Test on the latest versions of Chrome, Firefox, Safari, and Edge
+ - Use Chrome device mode to simulate mobile environments
+ - Confirm consistent appearance and behaviour across browsers
+
+
+Bug testing
+When a bug is fixed:
+
+ - Reproduce the issue using the main branch.
+ - Verify the fix in the pull request branch.
+ - Retest the component across all relevant areas.
+
+Confirm the issue no longer occurs.
+Reporting
+
+ - Document updated test results, findings, and screenshots in the pull request comments
+ - Log newly discovered issues in GitHub
+
+Roadmap
+A high-level summary of the work the design system team plans to focus on in the 2026-27 Fiscal Year.
+
+The roadmap is subject to change as we gather new information. We will communicate updates to ensure product teams can align and plan their work accordingly.
+
+For more details on our priorities and day-to-day activities, see our design system backlog.
+
+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.
+
+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.
+Examples:
+
+ Create a mechanism to reliably collect and report adoption rate Track upgrade progress against the adoption schedule Capture qualitative signals from teams (developer and designer feedback themes) Capture end-user feedback where available (citizen or worker satisfaction, accessibility and usability feedback)
+
+Product acceleration enablement
+Objective: Provide prescriptive guidance and resources that help teams get to screens, prototypes, and working experiences faster using DS 2.0.
+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 Provide contextual starting points for teams using Public form and Workspace templates Pilot DS 2.0 with teams to generate strong examples to share Create and publish migration success stories
+
+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.
+Examples:
+
+ Define the initial MCP scope and supported design system resources Stand up the MCP server and validate the hosting and maintenance approach Test the MCP use in real product workflows and capture gaps to address 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.
+Examples:
+
+ Define what "official Vue support" means Outline the minimum supportable scope Identify implications for documentation, maintenance, testing, and support
+
+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:
+
+ Build the review, revise, resubmit feature
+
+Examples and pattern maturity
+Objective: Expand and refine examples and position them as adaptable reusable patterns that teams can apply with confidence.
+Benefit: Improves self-serve success and product consistency, reducing implementation variance and support demand over time.
+Examples:
+
+ Continue expanding and refining examples Show how components and examples combine into larger contexts and workflows
+
+Library packaging and tech stack upgrades
+Objective: Reduce friction in how design system assets are bundled and adopted across libraries and update important tech stacks.
+Benefit: Lowers setup and upgrade complexity, and keeps the design system up to date with the latest supported versions.
+Examples:
+
+ Improve how code libraries are bundled together (React, web components, tokens) 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.
+
+Documentation and communications improvements
+Objective: Improve how teams access and understand design system guidance, and communicate design system value areas like accessibility more clearly.
+Benefit: Increases trust, improves reuse, and supports self-serve adoption by making guidance easier to consume and share.
+Examples:
+
+ Add markdown file download to website documentation 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.
+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:
+
+
+ Focus migration support on late adopters facing systemic barriers to upgrading
diff --git a/docs/src/content/productTypes/public-form/index.mdx b/docs/src/content/productTypes/public-form/index.mdx
new file mode 100644
index 0000000000..d74d27da0b
--- /dev/null
+++ b/docs/src/content/productTypes/public-form/index.mdx
@@ -0,0 +1,166 @@
+---
+id: public-form
+title: Public form
+summary: For citizen-facing services where users apply for a benefit, request a service, or submit information. Designed around simplicity and low cognitive load, with plain-language questions, focused pages that ask one thing at a time, save-and-resume, and a clear confirmation of what happens next.
The reference example is a starting point to expand on, not a rigid template. Adapt it to fit each service's context.
+heroImage: /images/examples/my-applications-page.png
+demoUrl: https://digital-service-demo-v2.netlify.app/
+tags:
+ - form
+ - public
+ - citizen
+ - pattern
+components: []
+status: published
+---
+
+View demo
+
+import PreviewContainer from "../../../components/PreviewContainer.astro";
+
+Primary user: Citizens applying for a service, benefit, permit, or status update.
+
+## Pages
+
+A public form is built from a small set of page types. Combine and adapt them to fit the work the service supports.
+
+### Start page
+
+The starting point for a citizen to begin your form from within your service or from Alberta.ca.
+
+
Workspaces should be adapted to fit each service's context and user needs. The reference example is a starting point to expand on, not a rigid template.
+heroImage: /thumbnails/workspace-preview.png
+demoUrl: https://digital-service-demo-v2.netlify.app/workspace
+sourceUrl: https://github.com/GovAlta/goa-workspace-playground
+tags:
+ - workspace
+ - worker
+ - service
+ - case-management
+ - dashboard
+ - pattern
+components:
+ - work-side-menu
+ - table
+ - badge
+ - tabs
+ - container
+ - accordion
+ - drawer
+ - button
+ - block
+status: published
+---
+
+View demo
+
+import LinkCard from "../../../components/LinkCard.astro";
+import PreviewContainer from "../../../components/PreviewContainer.astro";
+
+
+ Primary user: Service delivery staff
+
+## Pages
+
+Combine and adapt these to fit the work your service supports.
+
+### Dashboard
+
+The landing view of a workspace, showing staff their counts, trends, and assigned work.
+
+
+
+
+
+
+
+
+
+
+
+
+
+### Sidebar navigation
+
+Use the [work side menu](/components/work-side-menu) as the primary navigation for a workspace.
+
+Keep top-level navigation focused on the main areas of work. When a user opens a record or case, switch to contextual navigation that supports that task. This puts the user into a focused mode with relevant navigation items (like sections of an application, comments, reminders) and a back link to return to the main view. The sidebar can adapt to what the user is doing, it doesn't have to show everything at once.
+
+
+
+
+ Main workspace navigation
+
+
+
+
+
+ Contextual case navigation
+
+
+
+
+
+### Sticky action bar
+
+A scroll-aware header that pins to the top of the content area as the user scrolls. Use it to keep the most important tools visible.
+
+Set the content for each page based on the task:
+
+- On a cases list page, keep tools such as search and key actions visible.
+- On a detail page, keep the case name and key actions visible.
+
+Do not pin everything. Keep only the information and actions people need to continue their work without losing context.
+
+
+
+### Push drawer
+
+Use a [push drawer](/components/push-drawer) for focused work that should happen without leaving the current page.
+
+This works well for actions such as:
+
+- approving or denying a record
+- requesting more information
+- completing a short decision form
+- reviewing supporting details while taking action
+
+Use it when users need to keep the main record in view while completing the task.
+
+
+
+---
+
+## Components built for workspace
+
+Workspace patterns are supported by component features designed for denser, more productive interfaces:
+
+- **Compact inputs.** Every input component now has a `compact` variant that reduces height and spacing. This lets you build tighter forms and toolbars without sacrificing usability.
+- **Compact badges and notifications.** [Badges](/components/badge) and [notification banners](/components/notification) also have compact sizing to fit within dense data views and action bars.
+- **Badge variants.** [Badges](/components/badge) now include `strong` and `subtle` emphasis options, giving you control over visual weight depending on context.
+- **Data grid.** The [data grid](/components/data-grid) works with the table component to support accessible, keyboard-navigable data views. Use them together when the user needs to move through records efficiently without relying on a mouse.
+- **Segmented tabs.** A new [tab](/components/tab) variant that works as a segmented toggle for switching between views or modes within a workspace, rather than navigating between pages.
+- **Enhanced filter chips.** [Filter chips](/components/filter-chip) now support secondary text and secondary icons, making them more useful for richer filtering in workspace data views.
+
+---
+
+## Keyboard-accessible data views
+
+Workspace data views use the [data grid](/components/data-grid) to make table and card layouts fully keyboard navigable. Users can use arrow keys to move between cells and rows, making it possible to scan and act on records without a mouse. This is especially important in workspace contexts where staff are processing high volumes of cases and keyboard navigation is significantly faster than clicking. For assistive technology users, screen readers announce cell content and position as the user navigates.
+
+---
+
+## When to use
+
+Use the workspace when your service needs to support regular, task-based work, such as:
+
+- Reviewing and processing submissions
+- Managing case files, applications, or requests
+- Moving between dashboards, lists, and detail views
+- Taking actions such as approve, deny, assign, or request more information
+
+## When not to use
+
+- Citizen-facing services. Use the [public form](/examples/public-form) pattern instead.
+- Content-only pages that do not involve case management.
+- Simple internal tools that do not need structured case processing.
+
+---
+
+## Get started
+
+Use one of the workspace templates as a starting point for your service. Each template includes the sidebar navigation, dashboard, data views, and case detail patterns described above.
+
+
+
Applications are typically processed within 10 business days.
+ `,
+ },
+ },
+ {
+ id: "filled",
+ name: "Filled accordion",
+ description: "Single accordion with filled type",
+ code: {
+ react: `
+ You will need to provide proof of identity, proof of address,
+ and any relevant supporting documentation.
+ `,
+ angular: `
+ You will need to provide proof of identity, proof of address,
+ and any relevant supporting documentation.
+ `,
+ webComponents: `
+ You will need to provide proof of identity, proof of address,
+ and any relevant supporting documentation.
+ `,
+ },
+ },
+ {
+ id: "actions",
+ name: "Accordion with actions",
+ description: "Accordion with actions slot content",
+ code: {
+ react: `
+
+ View all
+
+
+ }
+>
+
+ This example mixes badges and controls inside the actions slot.
+
+ `,
+ angular: `
+
+ This example mixes badges and controls inside the actions slot.
+
+
+
+
+
+ View all
+
+ `,
+ webComponents: `
+
+ This example mixes badges and controls inside the actions slot.
+
+
+
+ View all
+
+
`,
},
},
diff --git a/docs/src/data/configurations/index.ts b/docs/src/data/configurations/index.ts
index d01d86eaa0..cbfbe46429 100644
--- a/docs/src/data/configurations/index.ts
+++ b/docs/src/data/configurations/index.ts
@@ -54,6 +54,7 @@ export { sideMenuConfigurations } from "./side-menu";
export { sideMenuGroupConfigurations } from "./side-menu-group";
export { sideMenuHeadingConfigurations } from "./side-menu-heading";
export { workSideMenuConfigurations } from "./work-side-menu";
+export { workSideNotificationPanelConfigurations } from "./work-side-notification-panel";
export { menuButtonConfigurations } from "./menu-button";
export { appHeaderConfigurations } from "./app-header";
export { appHeaderMenuConfigurations } from "./app-header-menu";
@@ -122,6 +123,7 @@ import { sideMenuConfigurations } from "./side-menu";
import { sideMenuGroupConfigurations } from "./side-menu-group";
import { sideMenuHeadingConfigurations } from "./side-menu-heading";
import { workSideMenuConfigurations } from "./work-side-menu";
+import { workSideNotificationPanelConfigurations } from "./work-side-notification-panel";
import { menuButtonConfigurations } from "./menu-button";
import { appHeaderConfigurations } from "./app-header";
import { appHeaderMenuConfigurations } from "./app-header-menu";
@@ -196,6 +198,7 @@ export const configurationRegistry: ConfigurationRegistry = {
"side-menu-group": sideMenuGroupConfigurations,
"side-menu-heading": sideMenuHeadingConfigurations,
"work-side-menu": workSideMenuConfigurations,
+ "work-side-notification-panel": workSideNotificationPanelConfigurations,
"menu-button": menuButtonConfigurations,
"app-header": appHeaderConfigurations,
"app-header-menu": appHeaderMenuConfigurations,
diff --git a/docs/src/data/configurations/push-drawer.ts b/docs/src/data/configurations/push-drawer.ts
index f0d2a3ffb4..923e112b17 100644
--- a/docs/src/data/configurations/push-drawer.ts
+++ b/docs/src/data/configurations/push-drawer.ts
@@ -51,6 +51,7 @@ export const pushDrawerConfigurations: ComponentConfigurations = {
componentSlug: "push-drawer",
componentName: "Push Drawer",
defaultConfigurationId: "basic",
+ previewStyle: "padding: 0;",
configurations: [
{
diff --git a/docs/src/data/configurations/shared/shared-previews.ts b/docs/src/data/configurations/shared/shared-previews.ts
new file mode 100644
index 0000000000..7894d697e9
--- /dev/null
+++ b/docs/src/data/configurations/shared/shared-previews.ts
@@ -0,0 +1,22 @@
+/**
+ * Shared preview style/wrapper templates for ConfigurationPreview.
+ *
+ * Use these when a component is meant to be seen inside a larger product layout
+ * (e.g. work-side-menu and notification panel sit next to a workspace area).
+ *
+ * - previewStyle: CSS applied to the preview container (replaces inline cssText).
+ * - previewWrapper: HTML around the component. `{{slot}}` is replaced with the
+ * component code at render time. Only used in the preview, never in the code
+ * snippet shown to users.
+ */
+
+export const workspacePreviewStyle =
+ "background: var(--goa-color-greyscale-50, #f8f8f8); padding: 0; display: flex; min-height: 500px;";
+
+export const workspacePreviewWrapper = `{{slot}}
+
+
+ Dashboard
+ Welcome back.
+
+`;
diff --git a/docs/src/data/configurations/temporary-notification.ts b/docs/src/data/configurations/temporary-notification.ts
index 5c1bc5789e..23b64478c5 100644
--- a/docs/src/data/configurations/temporary-notification.ts
+++ b/docs/src/data/configurations/temporary-notification.ts
@@ -108,29 +108,40 @@ export class SomeOtherComponent {
{
id: "with-progress",
name: "Progress and indeterminate",
- description:
- "Notifications for loading states (note: progress and indeterminate types may have rendering issues)",
+ description: "Notifications for loading states",
code: {
react: ` {
- const uuid = TemporaryNotification.show("Uploading file...", { type: "progress" });
- TemporaryNotification.setProgress(uuid, 65);
+ const uuid = TemporaryNotification.show("Uploading file...", { type: "progress", duration: "long" });
+ // Simulate progress; in real usage, drive this from your operation's progress events.
+ let progress = 0;
+ const interval = setInterval(() => {
+ progress = Math.min(progress + 10, 100);
+ TemporaryNotification.setProgress(uuid, progress);
+ if (progress >= 100) clearInterval(interval);
+ }, 500);
}} mb="xs">Progress
{
- TemporaryNotification.show("Processing your request...", { type: "indeterminate" });
+ TemporaryNotification.show("Processing your request...", { type: "indeterminate", duration: "long" });
}}>Indeterminate `,
angular: {
ts: `import { TemporaryNotification } from "@abgov/ui-components-common";
export class SomeOtherComponent {
showProgress() {
- const uuid = TemporaryNotification.show("Uploading file...", { type: "progress" });
- TemporaryNotification.setProgress(uuid, 65);
+ const uuid = TemporaryNotification.show("Uploading file...", { type: "progress", duration: "long" });
+ // Simulate progress; in real usage, drive this from your operation's progress events.
+ let progress = 0;
+ const interval = setInterval(() => {
+ progress = Math.min(progress + 10, 100);
+ TemporaryNotification.setProgress(uuid, progress);
+ if (progress >= 100) clearInterval(interval);
+ }, 500);
}
showIndeterminate() {
- TemporaryNotification.show("Processing your request...", { type: "indeterminate" });
+ TemporaryNotification.show("Processing your request...", { type: "indeterminate", duration: "long" });
}
}`,
template: ` {
+ TemporaryNotification.show("Item moved to trash", {
+ type: "basic",
+ duration: "long",
+ actionText: "Undo",
+ action: () => {
+ console.log("Undo clicked");
+ },
+ });
+}}>Show notification `,
+ angular: {
+ ts: `import { TemporaryNotification } from "@abgov/ui-components-common";
+
+export class SomeOtherComponent {
+ showWithAction() {
+ TemporaryNotification.show("Item moved to trash", {
+ type: "basic",
+ duration: "long",
+ actionText: "Undo",
+ action: () => {
+ console.log("Undo clicked");
+ },
+ });
+ }
+}`,
+ template: `Show notification `,
+ },
+ webComponents: `Show notification
+
+`,
diff --git a/docs/src/data/configurations/types.ts b/docs/src/data/configurations/types.ts
index c73938b0e7..3bd0e0a7b9 100644
--- a/docs/src/data/configurations/types.ts
+++ b/docs/src/data/configurations/types.ts
@@ -94,6 +94,13 @@ export interface ComponentConfigurations {
/** Default configuration ID to show on page load */
defaultConfigurationId: string;
+ /** Optional inline CSS for the preview container (e.g. background color for workspace context) */
+ previewStyle?: string;
+
+ /** Optional HTML that wraps each config's webComponents code in the preview only (not shown in code snippet).
+ * Use {{slot}} as placeholder for the component code. */
+ previewWrapper?: string;
+
/** All available configurations */
configurations: ComponentConfiguration[];
}
diff --git a/docs/src/data/configurations/work-side-menu.ts b/docs/src/data/configurations/work-side-menu.ts
index bfb35371e1..bae643cbef 100644
--- a/docs/src/data/configurations/work-side-menu.ts
+++ b/docs/src/data/configurations/work-side-menu.ts
@@ -5,11 +5,14 @@
*/
import type { ComponentConfigurations } from "./types";
+import { workspacePreviewStyle, workspacePreviewWrapper } from "./shared/shared-previews";
export const workSideMenuConfigurations: ComponentConfigurations = {
componentSlug: "work-side-menu",
componentName: "Work side menu",
defaultConfigurationId: "basic",
+ previewStyle: workspacePreviewStyle,
+ previewWrapper: workspacePreviewWrapper,
configurations: [
{
@@ -49,7 +52,7 @@ export const workSideMenuConfigurations: ComponentConfigurations = {
{
id: "with-user-profile",
name: "With user profile",
- description: "Menu showing user name and role",
+ description: "Menu showing user name and role with an account menu",
code: {
react: `
-
-
- `,
+ angular: `
+
+
+
+ `,
webComponents: `
`,
},
},
diff --git a/docs/src/data/configurations/work-side-notification-panel.ts b/docs/src/data/configurations/work-side-notification-panel.ts
new file mode 100644
index 0000000000..ac467b5420
--- /dev/null
+++ b/docs/src/data/configurations/work-side-notification-panel.ts
@@ -0,0 +1,784 @@
+/**
+ * WorkSideNotificationPanel Component Configurations
+ *
+ * Notification center panel used within a work side menu item's popover.
+ */
+
+import type { ComponentConfigurations } from "./types";
+import { workspacePreviewStyle, workspacePreviewWrapper } from "./shared/shared-previews";
+
+export const workSideNotificationPanelConfigurations: ComponentConfigurations = {
+ componentSlug: "work-side-notification-panel",
+ componentName: "Notification panel",
+ defaultConfigurationId: "basic",
+ previewStyle: workspacePreviewStyle,
+ previewWrapper: workspacePreviewWrapper,
+
+ configurations: [
+ {
+ id: "basic",
+ name: "Basic notification panel",
+ description:
+ "Panel with a mix of read and unread notifications in a work side menu",
+ code: {
+ react: {
+ ts: `const initialItems: (GoabWorkSideNotificationItemProps & { id: string })[] = [
+ {
+ id: "1",
+ title: "New case assigned",
+ description: "Case #12345 has been assigned to you for review.",
+ timestamp: "2025-03-15T10:30:00Z",
+ type: "info",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "2",
+ title: "Document uploaded",
+ description: "A new document was uploaded to Case #12340.",
+ timestamp: "2025-03-15T09:15:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "3",
+ title: "Case resolved",
+ description: "Case #12330 has been marked as resolved.",
+ timestamp: "2025-03-14T16:00:00Z",
+ type: "success",
+ readStatus: "read",
+ priority: "normal",
+ },
+];
+
+const [items, setItems] = useState(initialItems);
+
+const handleMarkAllRead = () => {
+ setItems((items) => items.map((item) => ({ ...item, readStatus: "read" })));
+};
+
+const handleViewAll = () => {
+ console.log("view all");
+};
+
+const handleClick = (id: string) => {
+ setItems((items) =>
+ items.map((item) => (item.id === id ? { ...item, readStatus: "read" } : item)),
+ );
+};`,
+ jsx: ` navigate(path)}
+ primaryContent={
+ <>
+
+ {items.map(({ id, ...item }) => (
+ handleClick(id)}
+ />
+ ))}
+
+ }
+ />
+ }
+/>`,
+ },
+ angular: {
+ ts: `interface NotificationItem {
+ id: string;
+ title: string;
+ description: string;
+ timestamp: string;
+ type: GoabWorkSideNotificationItemType;
+ readStatus: GoabWorkSideNotificationReadStatus;
+ priority: GoabWorkSideNotificationPriority;
+}
+
+export class SomeOtherComponent {
+ items: NotificationItem[] = [
+ {
+ id: "1",
+ title: "New case assigned",
+ description: "Case #12345 has been assigned to you for review.",
+ timestamp: "2025-03-15T10:30:00Z",
+ type: "info",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "2",
+ title: "Document uploaded",
+ description: "A new document was uploaded to Case #12340.",
+ timestamp: "2025-03-15T09:15:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "3",
+ title: "Case resolved",
+ description: "Case #12330 has been marked as resolved.",
+ timestamp: "2025-03-14T16:00:00Z",
+ type: "success",
+ readStatus: "read",
+ priority: "normal",
+ },
+ ];
+
+ handleMarkAllRead() {
+ this.items = this.items.map((item) => ({ ...item, readStatus: "read" }));
+ }
+
+ handleViewAll() {
+ console.log("view all");
+ }
+
+ handleClick(id: string) {
+ this.items = this.items.map((item) =>
+ item.id === id ? { ...item, readStatus: "read" } : item,
+ );
+ }
+}`,
+ template: `
+
+
+
+
+
+
+
+ @for (item of items; track item.id) {
+
+ `,
+ },
+ webComponents: {
+ html: `
+
+
+
+
+ `,
+ js: `const panel = container.querySelector("goa-work-side-notification-panel");
+const items = container.querySelectorAll("goa-work-side-notification-item");
+
+items.forEach((item) => {
+ item.addEventListener("_click", () => {
+ item.setAttribute("read-status", "read");
+ });
+});
+
+panel.addEventListener("_markAllRead", () => {
+ items.forEach((item) => item.setAttribute("read-status", "read"));
+});
+
+panel.addEventListener("_viewAll", () => {
+ console.log("view all");
+});`,
+ },
+ },
+ },
+ {
+ id: "urgent-notifications",
+ name: "With urgent notifications",
+ description: "Menu with urgent priority notifications in the panel",
+ code: {
+ react: {
+ ts: `const initialItems: (GoabWorkSideNotificationItemProps & { id: string })[] = [
+ {
+ id: "1",
+ title: "System maintenance",
+ description: "Scheduled maintenance tonight at 11 PM. All services will be unavailable.",
+ timestamp: "2025-03-15T14:00:00Z",
+ type: "critical",
+ readStatus: "unread",
+ priority: "urgent",
+ },
+ {
+ id: "2",
+ title: "Deadline approaching",
+ description: "Case #12345 response is due in 2 hours.",
+ timestamp: "2025-03-15T12:00:00Z",
+ type: "warning",
+ readStatus: "unread",
+ priority: "urgent",
+ },
+ {
+ id: "3",
+ title: "New comment on case",
+ description: "A team member commented on Case #12340.",
+ timestamp: "2025-03-15T11:00:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+];
+
+const [items, setItems] = useState(initialItems);
+
+const handleMarkAllRead = () => {
+ setItems((items) => items.map((item) => ({ ...item, readStatus: "read" })));
+};
+
+const handleViewAll = () => {
+ console.log("view all");
+};
+
+const handleClick = (id: string) => {
+ setItems((items) =>
+ items.map((item) => (item.id === id ? { ...item, readStatus: "read" } : item)),
+ );
+};`,
+ jsx: ` navigate(path)}
+ primaryContent={
+ <>
+
+ {items.map(({ id, ...item }) => (
+ handleClick(id)}
+ />
+ ))}
+
+ }
+ />
+ }
+/>`,
+ },
+ angular: {
+ ts: `interface NotificationItem {
+ id: string;
+ title: string;
+ description: string;
+ timestamp: string;
+ type: GoabWorkSideNotificationItemType;
+ readStatus: GoabWorkSideNotificationReadStatus;
+ priority: GoabWorkSideNotificationPriority;
+}
+
+export class SomeOtherComponent {
+ items: NotificationItem[] = [
+ {
+ id: "1",
+ title: "System maintenance",
+ description: "Scheduled maintenance tonight at 11 PM. All services will be unavailable.",
+ timestamp: "2025-03-15T14:00:00Z",
+ type: "critical",
+ readStatus: "unread",
+ priority: "urgent",
+ },
+ {
+ id: "2",
+ title: "Deadline approaching",
+ description: "Case #12345 response is due in 2 hours.",
+ timestamp: "2025-03-15T12:00:00Z",
+ type: "warning",
+ readStatus: "unread",
+ priority: "urgent",
+ },
+ {
+ id: "3",
+ title: "New comment on case",
+ description: "A team member commented on Case #12340.",
+ timestamp: "2025-03-15T11:00:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ ];
+
+ handleMarkAllRead() {
+ this.items = this.items.map((item) => ({ ...item, readStatus: "read" }));
+ }
+
+ handleViewAll() {
+ console.log("view all");
+ }
+
+ handleClick(id: string) {
+ this.items = this.items.map((item) =>
+ item.id === id ? { ...item, readStatus: "read" } : item,
+ );
+ }
+}`,
+ template: `
+
+
+
+
+
+
+
+ @for (item of items; track item.id) {
+
+ `,
+ },
+ webComponents: {
+ html: `
+
+
+
+
+ `,
+ js: `const panel = container.querySelector("goa-work-side-notification-panel");
+const items = container.querySelectorAll("goa-work-side-notification-item");
+
+items.forEach((item) => {
+ item.addEventListener("_click", () => {
+ item.setAttribute("read-status", "read");
+ });
+});
+
+panel.addEventListener("_markAllRead", () => {
+ items.forEach((item) => item.setAttribute("read-status", "read"));
+});
+
+panel.addEventListener("_viewAll", () => {
+ console.log("view all");
+});`,
+ },
+ },
+ },
+ {
+ id: "notification-types",
+ name: "Notification type badges",
+ description: "All notification item type variants with their badge icons",
+ code: {
+ react: {
+ ts: `const initialItems: (GoabWorkSideNotificationItemProps & { id: string })[] = [
+ {
+ id: "1",
+ title: "New comment on case",
+ description: "A team member commented on Case #12340.",
+ timestamp: "2025-03-15T10:00:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "2",
+ title: "Case #12345 assigned",
+ description: "Case #12345 has been assigned to you for review.",
+ timestamp: "2025-03-15T09:00:00Z",
+ type: "info",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "3",
+ title: "Case resolved",
+ description: "Case #12330 has been marked as resolved.",
+ timestamp: "2025-03-15T08:00:00Z",
+ type: "success",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "4",
+ title: "Deadline approaching",
+ description: "Case #12345 response is due in 2 hours.",
+ timestamp: "2025-03-15T07:00:00Z",
+ type: "warning",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "5",
+ title: "System maintenance",
+ description: "Scheduled maintenance tonight at 11 PM. All services will be unavailable.",
+ timestamp: "2025-03-15T06:00:00Z",
+ type: "critical",
+ readStatus: "unread",
+ priority: "normal",
+ },
+];
+
+const [items, setItems] = useState(initialItems);
+
+const handleMarkAllRead = () => {
+ setItems((items) => items.map((item) => ({ ...item, readStatus: "read" })));
+};
+
+const handleViewAll = () => {
+ console.log("view all");
+};
+
+const handleClick = (id: string) => {
+ setItems((items) =>
+ items.map((item) => (item.id === id ? { ...item, readStatus: "read" } : item)),
+ );
+};`,
+ jsx: ` navigate(path)}
+ primaryContent={
+
+ {items.map(({ id, ...item }) => (
+ handleClick(id)}
+ />
+ ))}
+
+ }
+ />
+ }
+/>`,
+ },
+ angular: {
+ ts: `interface NotificationItem {
+ id: string;
+ title: string;
+ description: string;
+ timestamp: string;
+ type: GoabWorkSideNotificationItemType;
+ readStatus: GoabWorkSideNotificationReadStatus;
+ priority: GoabWorkSideNotificationPriority;
+}
+
+export class SomeOtherComponent {
+ items: NotificationItem[] = [
+ {
+ id: "1",
+ title: "New comment on case",
+ description: "A team member commented on Case #12340.",
+ timestamp: "2025-03-15T10:00:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "2",
+ title: "Case #12345 assigned",
+ description: "Case #12345 has been assigned to you for review.",
+ timestamp: "2025-03-15T09:00:00Z",
+ type: "info",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "3",
+ title: "Case resolved",
+ description: "Case #12330 has been marked as resolved.",
+ timestamp: "2025-03-15T08:00:00Z",
+ type: "success",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "4",
+ title: "Deadline approaching",
+ description: "Case #12345 response is due in 2 hours.",
+ timestamp: "2025-03-15T07:00:00Z",
+ type: "warning",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "5",
+ title: "System maintenance",
+ description: "Scheduled maintenance tonight at 11 PM. All services will be unavailable.",
+ timestamp: "2025-03-15T06:00:00Z",
+ type: "critical",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ ];
+
+ handleMarkAllRead() {
+ this.items = this.items.map((item) => ({ ...item, readStatus: "read" }));
+ }
+
+ handleViewAll() {
+ console.log("view all");
+ }
+
+ handleClick(id: string) {
+ this.items = this.items.map((item) =>
+ item.id === id ? { ...item, readStatus: "read" } : item,
+ );
+ }
+}`,
+ template: `
+
+
+
+
+
+
+
+ @for (item of items; track item.id) {
+
+ `,
+ },
+ webComponents: {
+ html: `
+
+
+
+
+ `,
+ js: `const panel = container.querySelector("goa-work-side-notification-panel");
+const items = container.querySelectorAll("goa-work-side-notification-item");
+
+items.forEach((item) => {
+ item.addEventListener("_click", () => {
+ item.setAttribute("read-status", "read");
+ });
+});
+
+panel.addEventListener("_markAllRead", () => {
+ items.forEach((item) => item.setAttribute("read-status", "read"));
+});
+
+panel.addEventListener("_viewAll", () => {
+ console.log("view all");
+});`,
+ },
+ },
+ },
+ ],
+};
diff --git a/docs/src/hooks/index.ts b/docs/src/hooks/index.ts
index 652c65f682..e61376a796 100644
--- a/docs/src/hooks/index.ts
+++ b/docs/src/hooks/index.ts
@@ -5,3 +5,4 @@
export { useTwoLevelSort, type SortConfig, type SortLevel } from './useTwoLevelSort';
export { useCompactToolbar, useMobile, COMPACT_TOOLBAR_BREAKPOINT, MOBILE_BREAKPOINT } from './useCompactToolbar';
export { useViewSettings, type ViewSettings, type LayoutType, type GroupByField } from './useViewSettings';
+export { useIsDarkMode } from './useIsDarkMode';
diff --git a/docs/src/hooks/useIsDarkMode.ts b/docs/src/hooks/useIsDarkMode.ts
new file mode 100644
index 0000000000..24afeb84cd
--- /dev/null
+++ b/docs/src/hooks/useIsDarkMode.ts
@@ -0,0 +1,42 @@
+/**
+ * useIsDarkMode.ts
+ *
+ * Watches the active theme via the `data-theme` attribute on .
+ * Returns true when in dark mode. Reacts to toggle changes via MutationObserver.
+ *
+ * Why read from the DOM attribute instead of localStorage:
+ * - The pre-paint script in BaseLayout.astro sets `data-theme` from
+ * localStorage > prefers-color-scheme > "light", so the attribute is
+ * the source of truth for what's currently rendered.
+ * - localStorage has no in-tab change event; MutationObserver on the
+ * attribute is the cleanest way to react to toggle in other islands.
+ * - localStorage may be blocked (private mode, sandboxed iframe); the
+ * DOM attribute is always set.
+ *
+ * Astro islands cannot share React context, so the DOM attribute is the
+ * cross-island sync channel for theme.
+ */
+
+import { useEffect, useState } from "react";
+
+export function useIsDarkMode(): boolean {
+ const [isDark, setIsDark] = useState(
+ () =>
+ typeof document !== "undefined" &&
+ document.documentElement.getAttribute("data-theme") === "dark",
+ );
+
+ useEffect(() => {
+ if (typeof document === "undefined") return;
+ const observer = new MutationObserver(() => {
+ setIsDark(document.documentElement.getAttribute("data-theme") === "dark");
+ });
+ observer.observe(document.documentElement, {
+ attributes: true,
+ attributeFilter: ["data-theme"],
+ });
+ return () => observer.disconnect();
+ }, []);
+
+ return isDark;
+}
diff --git a/docs/src/layouts/BaseLayout.astro b/docs/src/layouts/BaseLayout.astro
index b9f9d3fa4c..0f9905158d 100644
--- a/docs/src/layouts/BaseLayout.astro
+++ b/docs/src/layouts/BaseLayout.astro
@@ -2,6 +2,7 @@
// Import v2 design tokens and web component styles
import '@abgov/web-components/index.css';
import '@design-tokens/tokens.css';
+import '@design-tokens/dark-theme.css';
// Import search styles eagerly so inline search inputs don't flash unstyled
import '../components/search/search.css';
@@ -26,6 +27,24 @@ const ogUrl = new URL(withBase(Astro.url.pathname), Astro.site).href;
+
+
+
+
+
+
+
+
+
+
+ {backLabel}
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/src/layouts/TokensLayout.astro b/docs/src/layouts/TokensLayout.astro
index 6549a769aa..c7e73a8e36 100644
--- a/docs/src/layouts/TokensLayout.astro
+++ b/docs/src/layouts/TokensLayout.astro
@@ -16,6 +16,7 @@ import Breadcrumbs from '../components/Breadcrumbs.astro';
import { SiteNav } from '../components/SiteNav';
import { MobileHeader } from '../components/MobileHeader';
import { getNavCategories } from '../lib/nav-categories';
+import { getGetStartedNav } from '../lib/get-started-nav';
interface Props {
title: string;
@@ -24,6 +25,7 @@ interface Props {
const { title, description } = Astro.props;
const navCategories = await getNavCategories();
+const getStartedNav = await getGetStartedNav();
---
@@ -36,6 +38,7 @@ const navCategories = await getNavCategories();
client:only="react"
initialSection="tokens"
categories={navCategories}
+ getStartedNav={getStartedNav}
/>
diff --git a/docs/src/lib/base-url.ts b/docs/src/lib/base-url.ts
index 1ea988dbab..47e91e8df0 100644
--- a/docs/src/lib/base-url.ts
+++ b/docs/src/lib/base-url.ts
@@ -3,6 +3,8 @@ export const BASE_URL = import.meta.env.BASE_URL;
export function withBase(path: string): string {
if (!path) return BASE_URL;
if (path.startsWith("http://") || path.startsWith("https://")) return path;
+ // Idempotent: skip if path is already prefixed with BASE_URL.
+ if (BASE_URL !== "/" && path.startsWith(BASE_URL)) return path;
const clean = path.startsWith("/") ? path.slice(1) : path;
return `${BASE_URL}${clean}`;
}
diff --git a/docs/src/lib/content-queries.ts b/docs/src/lib/content-queries.ts
index 2be5abcf8e..c3a8ac8fdf 100644
--- a/docs/src/lib/content-queries.ts
+++ b/docs/src/lib/content-queries.ts
@@ -9,6 +9,7 @@ export interface PropDefinition {
required: boolean;
default: string | null;
description: string;
+ deprecated?: boolean;
}
export interface EventDefinition {
@@ -20,24 +21,34 @@ export interface EventDefinition {
export interface SlotDefinition {
name: string;
+ type?: string;
description: string;
+ required?: boolean;
+}
+
+export interface FrameworkApiData {
+ props: PropDefinition[];
+ events: EventDefinition[];
+ slots: SlotDefinition[];
+}
+
+export interface FrameworkApiMap {
+ react: FrameworkApiData;
+ angular: FrameworkApiData;
+ webComponents: FrameworkApiData;
}
export interface SubComponentApi {
name: string;
webComponentTag: string;
description: string;
- props: PropDefinition[];
- events: EventDefinition[];
- slots: SlotDefinition[];
+ frameworks: FrameworkApiMap;
}
export interface ComponentApi {
componentSlug: string;
extractedFrom: string;
- props: PropDefinition[];
- events: EventDefinition[];
- slots: SlotDefinition[];
+ frameworks: FrameworkApiMap;
subComponents?: SubComponentApi[];
}
@@ -89,7 +100,9 @@ export async function getExamplesForComponent(
): Promise[]> {
const allExamples = await getCollection("examples");
- return allExamples.filter((example) => example.data.components.includes(componentSlug));
+ return allExamples.filter(
+ (example) => !example.data.hidden && example.data.components.includes(componentSlug),
+ );
}
/**
@@ -165,7 +178,7 @@ export async function getContentByTag(tag: string) {
return {
components: components.filter((c) => c.data.tags?.includes(tag)),
guidance: guidance.filter((g) => g.data.tags?.includes(tag)),
- examples: examples.filter((e) => e.data.tags?.includes(tag)),
+ examples: examples.filter((e) => !e.data.hidden && e.data.tags?.includes(tag)),
};
}
diff --git a/docs/src/lib/example-size.ts b/docs/src/lib/example-size.ts
new file mode 100644
index 0000000000..133656c6d3
--- /dev/null
+++ b/docs/src/lib/example-size.ts
@@ -0,0 +1,13 @@
+/**
+ * Page-scale entries (page, task, product) render a PreviewContainer
+ * card linking to the entry's docs page rather than an inline sandbox,
+ * because their composition usually depends on app shell, mock data, or
+ * external sources that don't render usefully inline. Section and
+ * interaction snippets render inline with a sandbox plus framework code
+ * tabs.
+ */
+const PAGE_SCALES = ["page", "task", "product"] as const;
+
+export function isPageScale(size: string): boolean {
+ return (PAGE_SCALES as readonly string[]).includes(size);
+}
diff --git a/docs/src/lib/get-started-nav.ts b/docs/src/lib/get-started-nav.ts
new file mode 100644
index 0000000000..d73df4cb40
--- /dev/null
+++ b/docs/src/lib/get-started-nav.ts
@@ -0,0 +1,77 @@
+/**
+ * get-started-nav.ts
+ *
+ * Builds the Get Started submenu structure from the content collection.
+ * Used by layouts to pass nav data to SiteNav -> GetStartedSubMenu.
+ *
+ * Section convention:
+ * - "intro" => top-level pages above grouped sections
+ * - "designers" => Designers group
+ * - "developers" => Developers group
+ * - "appendix" => top-level pages below grouped sections
+ */
+
+import { getCollection } from "astro:content";
+
+export interface GetStartedNavItem {
+ label: string;
+ url: string;
+}
+
+export interface GetStartedNavGroup {
+ name: string;
+ slug: string;
+ pages: GetStartedNavItem[];
+}
+
+export interface GetStartedNav {
+ topPages: GetStartedNavItem[];
+ groups: GetStartedNavGroup[];
+ bottomPages: GetStartedNavItem[];
+}
+
+/** Display metadata for the grouped sections (not stored in content collection) */
+const GROUP_META: Record = {
+ designers: { name: "Designers" },
+ developers: { name: "Developers" },
+};
+
+/** Canonical display order for grouped sections in the submenu */
+const GROUP_ORDER = ["designers", "developers"];
+
+function entryToItem(entry: {
+ slug: string;
+ data: { title: string; navLabel?: string };
+}): GetStartedNavItem {
+ return {
+ label: entry.data.navLabel ?? entry.data.title,
+ url: entry.slug === "index" ? "/get-started" : `/get-started/${entry.slug}`,
+ };
+}
+
+function bySection(
+ entries: Awaited>>,
+ section: string,
+): typeof entries {
+ return entries
+ .filter((e) => e.data.section === section)
+ .sort((a, b) => a.data.order - b.data.order);
+}
+
+export async function getGetStartedNav(): Promise {
+ const entries = await getCollection("get-started");
+ const published = entries.filter((e) => e.data.status !== "deprecated");
+
+ const topPages = bySection(published, "intro").map(entryToItem);
+ const bottomPages = bySection(published, "appendix").map(entryToItem);
+
+ const groups = GROUP_ORDER.filter((slug) =>
+ published.some((e) => e.data.section === slug),
+ ).map((slug) => ({
+ name: GROUP_META[slug].name,
+ slug,
+ pages: bySection(published, slug).map(entryToItem),
+ }));
+
+ return { topPages, groups, bottomPages };
+}
diff --git a/docs/src/lib/tokens.ts b/docs/src/lib/tokens.ts
index e36d74171b..ce244064dd 100644
--- a/docs/src/lib/tokens.ts
+++ b/docs/src/lib/tokens.ts
@@ -29,6 +29,10 @@ export interface FlatToken {
isColor: boolean;
/** Description if available */
description?: string;
+ /** Dark mode "as defined" value (only set if token is themed). */
+ darkValue?: string;
+ /** Dark mode resolved value (only set if token is themed). */
+ darkResolvedValue?: string;
}
/**
@@ -98,15 +102,35 @@ function boxShadowToCss(shadow: {
}
/**
- * Format a token value for display
+ * Check if a value is a themed value (has `light` and `dark` keys).
+ * These are emitted by Style Dictionary for tokens that flip between modes.
+ * The inner values may be strings (e.g. colors) or objects (e.g. box shadows).
*/
-function formatValue(value: string | number | object): string {
+function isThemedValue(value: unknown): value is { light: unknown; dark: unknown } {
+ return (
+ typeof value === "object" &&
+ value !== null &&
+ "light" in value &&
+ "dark" in value
+ );
+}
+
+/**
+ * Format a token value for display. For themed `{ light, dark }` values,
+ * returns the light variant (recursively formatted, so themed box-shadow
+ * objects, themed strings, etc. all flatten correctly).
+ */
+function formatValue(value: unknown): string {
if (typeof value === "string") {
return value;
}
if (typeof value === "number") {
return String(value);
}
+ // Themed value: recurse on the light variant
+ if (isThemedValue(value)) {
+ return formatValue(value.light);
+ }
// Convert box-shadow objects to CSS syntax
if (isBoxShadowObject(value)) {
return boxShadowToCss(value);
@@ -213,7 +237,10 @@ function flattenTokensRecursive(
const tokenPath = currentPath.slice(1).join("/");
const tokenType = value.type || "unknown";
- // Keep original value, resolve for preview
+ // Detect themed { light, dark } shape, split into separate light + dark fields.
+ const themed = isThemedValue(value.value) ? value.value : null;
+
+ // Keep original value, resolve for preview (light by default for themed values)
const rawValue = formatValue(value.value);
let resolvedValue: string;
@@ -226,6 +253,18 @@ function flattenTokensRecursive(
typeof rawValue === "string" ? resolveTokenReference(rawValue, rootTokens) : rawValue;
}
+ // Resolve dark variant if the value is themed
+ let darkValue: string | undefined;
+ let darkResolvedValue: string | undefined;
+ if (themed) {
+ // Themed inner value may be a string, box-shadow object, etc.
+ // Formatting recursively lets it produce a CSS string for any shape.
+ darkValue = formatValue(themed.dark);
+ darkResolvedValue = isTokenReference(darkValue)
+ ? resolveTokenReference(darkValue, rootTokens)
+ : darkValue;
+ }
+
const isColor =
tokenType === "color" ||
(typeof resolvedValue === "string" && resolvedValue.startsWith("#"));
@@ -239,6 +278,8 @@ function flattenTokensRecursive(
type: tokenType,
isColor,
description: value.description,
+ darkValue,
+ darkResolvedValue,
});
} else if (typeof value === "object" && value !== null) {
// Recurse into nested object
diff --git a/docs/src/pages/components/[slug].astro b/docs/src/pages/components/[slug].astro
index 5929614b2c..3c3b3641dc 100644
--- a/docs/src/pages/components/[slug].astro
+++ b/docs/src/pages/components/[slug].astro
@@ -112,13 +112,13 @@ const v1DocsUrl = `https://v1.design.alberta.ca/components/${slug}`;
{api ? (
<>
- {sub.name}
{sub.description}
-
diff --git a/docs/src/pages/examples/[family]/[page]/index.astro b/docs/src/pages/examples/[family]/[page]/index.astro
new file mode 100644
index 0000000000..a5da1c88d6
--- /dev/null
+++ b/docs/src/pages/examples/[family]/[page]/index.astro
@@ -0,0 +1,134 @@
+---
+/**
+ * Template Detail Page
+ *
+ * Deep dive for a single template or sub-pattern.
+ * Hero with preview image plus a thin action bar (Live preview, Source, StackBlitz),
+ * followed by MDX body (when to use, considerations, components used, etc.).
+ * No framework code tabs at this scale. Source link goes to GitHub.
+ */
+import { getCollection, render } from 'astro:content';
+import ExamplesPageLayout from '../../../../layouts/ExamplesPageLayout.astro';
+import Breadcrumbs from '../../../../components/Breadcrumbs.astro';
+import PreviewContainer from '../../../../components/PreviewContainer.astro';
+
+export async function getStaticPaths() {
+ const examples = await getCollection('examples');
+ // Nested page-scale entries whose slug is "/". Today's
+ // set: workspace/dashboard, workspace/index-page, workspace/case-detail.
+ const nested = examples.filter((e) => e.slug.includes('/') && e.data.size === 'page');
+ return nested.map((entry) => {
+ const [family, page] = entry.slug.split('/');
+ return {
+ params: { family, page },
+ props: { entry },
+ };
+ });
+}
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+const { data } = entry;
+const { family, page } = Astro.params;
+// data is narrowed to the page-shape by the getStaticPaths filter
+const pageData = data as Extract;
+
+// Emit a Live preview URL so the action bar renders consistently with
+// the family overview. Whether the preview iframes an external demo
+// (workspace) or renders locally (page-scale templates) is decided
+// by the preview route itself.
+const internalPreviewUrl = `/examples/${family}/${page}/preview`;
+---
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/[family]/[page]/preview.astro b/docs/src/pages/examples/[family]/[page]/preview.astro
new file mode 100644
index 0000000000..4933cfec2d
--- /dev/null
+++ b/docs/src/pages/examples/[family]/[page]/preview.astro
@@ -0,0 +1,61 @@
+---
+/**
+ * Template Live Preview
+ *
+ * Standalone full-viewport preview of a template. Iframes the template's
+ * configured previewUrl (typically the workspace demo app) and wraps it
+ * with a minimal top bar so users can navigate back to the docs. This is
+ * the "isolated preview" distinct from the full working demo linked via
+ * the "View demo" CTA in the walkthrough.
+ */
+import { getCollection } from 'astro:content';
+import PreviewLayout from "../../../../layouts/PreviewLayout.astro";
+
+export async function getStaticPaths() {
+ const examples = await getCollection('examples');
+ // Nested examples with a previewUrl: the page-detail route wires the
+ // Live preview button here, and this route iframes the externally-hosted demo.
+ const nested = examples.filter(
+ (e) => e.slug.includes('/') && e.data.size === 'page' && e.data.previewUrl,
+ );
+ return nested.map((entry) => {
+ const [family, page] = entry.slug.split('/');
+ return {
+ params: { family, page },
+ props: { entry },
+ };
+ });
+}
+
+const { entry } = Astro.props;
+const { data } = entry;
+const { family, page } = Astro.params;
+const backUrl = `/examples/${family}/${page}`;
+const backLabel = `Back to ${data.title}`;
+const pageData = data as Extract;
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/[family]/index.astro b/docs/src/pages/examples/[family]/index.astro
new file mode 100644
index 0000000000..c7d45a0b16
--- /dev/null
+++ b/docs/src/pages/examples/[family]/index.astro
@@ -0,0 +1,150 @@
+---
+/**
+ * Service Type Overview Page
+ *
+ * Landing page for a service type. Renders the MDX body of the matching
+ * entry in the `productTypes` collection (workspace, public-form). Follows
+ * the flexible-doc-page pattern: prose walkthrough with inline demo CTAs,
+ * images, and links to nested example pages.
+ */
+import { getCollection, render } from 'astro:content';
+import ExamplesPageLayout from '../../../layouts/ExamplesPageLayout.astro';
+import Breadcrumbs from '../../../components/Breadcrumbs.astro';
+import { TableOfContents } from '../../../components/TableOfContents';
+
+export async function getStaticPaths() {
+ const productTypes = await getCollection('productTypes');
+ return productTypes.map((entry) => ({
+ params: { family: entry.data.id },
+ props: { entry },
+ }));
+}
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+const { data } = entry;
+
+// Family overview cover shows the whole demo app, not a single-page preview,
+// so no Live preview button. View demo alone covers the CTA.
+---
+
+
+
+
+
+ {data.title}
+ {data.summary && }
+
+
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/[family]/preview.astro b/docs/src/pages/examples/[family]/preview.astro
new file mode 100644
index 0000000000..73c3a161d2
--- /dev/null
+++ b/docs/src/pages/examples/[family]/preview.astro
@@ -0,0 +1,48 @@
+---
+/**
+ * Family Live Preview
+ *
+ * Standalone full-viewport preview of a template family's main demo route.
+ * Same chrome as [page]/preview.astro so the family overview's "Live preview"
+ * button lands on the same shape as the detail pages' buttons.
+ */
+import { getCollection } from 'astro:content';
+import PreviewLayout from "../../../layouts/PreviewLayout.astro";
+
+export async function getStaticPaths() {
+ const productTypes = await getCollection('productTypes');
+ const withDemo = productTypes.filter((entry) => entry.data.demoUrl);
+ return withDemo.map((entry) => ({
+ params: { family: entry.data.id },
+ props: { entry },
+ }));
+}
+
+const { entry } = Astro.props;
+const { data } = entry;
+const backUrl = `/examples/${data.id}`;
+const backLabel = `Back to ${data.title}`;
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/[slug].astro b/docs/src/pages/examples/[slug].astro
index 930c953abf..65618d4881 100644
--- a/docs/src/pages/examples/[slug].astro
+++ b/docs/src/pages/examples/[slug].astro
@@ -13,17 +13,21 @@ import { getCollection, render } from 'astro:content';
import ExamplesPageLayout from '../../layouts/ExamplesPageLayout.astro';
import Breadcrumbs from '../../components/Breadcrumbs.astro';
import ExampleDisplay from '../../components/ExampleDisplay.astro';
+import PreviewContainer from '../../components/PreviewContainer.astro';
import { TableOfContents } from '../../components/TableOfContents';
import { getExampleCode } from '../../lib/example-code';
+import { isPageScale } from '../../lib/example-size';
-
-// Generate static paths for all examples
+// Generate static paths for flat examples only. Nested entries
+// (workspace/dashboard, etc) are handled by [family]/[page]/index.astro.
export async function getStaticPaths() {
const examples = await getCollection('examples');
- return examples.map((example) => ({
- params: { slug: example.slug },
- props: { example },
- }));
+ return examples
+ .filter((example) => !example.slug.includes('/') && !example.data.hidden)
+ .map((example) => ({
+ params: { slug: example.slug },
+ props: { example },
+ }));
}
const { example } = Astro.props;
@@ -37,37 +41,48 @@ const { Content } = await render(example);
const code = await getExampleCode(example.slug);
const hasCode = !!(code.react || code.angular || code.webComponents);
+// Page-and-larger entries render with a PreviewContainer at the top instead
+// of framework code tabs, mirroring the workspace page detail shape. The
+// framework files still exist on disk and are linked via GitHub.
+// Section-sized entries keep the sandbox + framework tabs treatment.
+const pageScale = isPageScale(data.size);
+const showCodeTabs = !pageScale && hasCode;
+const useTopPreview = pageScale && data.previewImage && !data.hideHero;
+const githubBlobBase = 'https://github.com/GovAlta/ui-components/blob/dev/docs/src/content/examples';
+const githubTreeBase = 'https://github.com/GovAlta/ui-components/tree/dev/docs/src/content/examples';
+type WithSourceUrls = { reactSourceUrl?: string; angularSourceUrl?: string; previewUrl?: string };
+const pageData = data as typeof data & WithSourceUrls;
+const reactSourceUrl =
+ pageData.reactSourceUrl ?? (code.react ? `${githubBlobBase}/${slug}/react.tsx` : undefined);
+const angularSourceUrl =
+ pageData.angularSourceUrl ?? (code.angular ? `${githubTreeBase}/${slug}` : undefined);
+// /examples/[slug]/preview.astro auto-generates a Live preview route for
+// every flat-slug page-scale entry with a sibling react.tsx. So if this
+// entry has React code, link the PreviewContainer image to its preview.
+const previewUrl =
+ pageData.previewUrl ?? (pageScale && code.react ? `/examples/${slug}/preview` : undefined);
+
// Get related examples if defined
let relatedExamples: typeof example[] = [];
if (data.relatedExamples?.length) {
const allExamples = await getCollection('examples');
relatedExamples = allExamples.filter(e =>
+ !e.data.hidden &&
data.relatedExamples?.includes(e.data.id)
);
}
-// Format category for display
-function formatCategory(category: string): string {
- return category
+// Format size for display ("page" -> "Page", "component" -> "Component", "digital-service" -> "Digital service")
+function formatSize(size: string): string {
+ return size
.split('-')
- .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+ .map((word, i) => (i === 0 ? word.charAt(0).toUpperCase() + word.slice(1) : word))
.join(' ');
}
-// Format scale for display
-function formatScale(scale: string): string {
- return scale.charAt(0).toUpperCase() + scale.slice(1);
-}
-
-// Format user type for display
-function formatUserType(userType: string): string {
- if (userType === 'both') return 'Citizen & Worker';
- return userType.charAt(0).toUpperCase() + userType.slice(1);
-}
-
-// Format component name to sentence case (e.g., "form-item" → "Form item")
-function formatComponentName(component: string): string {
- return component
+// Format service type for display ("public-form" -> "Public form")
+function formatProductType(productType: string): string {
+ return productType
.split('-')
.map((word, i) => i === 0 ? word.charAt(0).toUpperCase() + word.slice(1) : word)
.join(' ');
@@ -82,37 +97,56 @@ const v1DocsUrl = `https://v1.design.alberta.ca/examples/${slug}`;
currentSlug={slug}
>
-
- {data.categories.map((cat: string) => (
-
-
- {hasCode ? (
+
+ {showCodeTabs ? (
- ) : data.previewImage ? (
+ ) : useTopPreview ? (
+
+ {data.title}
+ {data.description && (
+
+ )}
+
+ ) : (
{data.title}
{data.description && (
)}
-
- 
-
- ) : null}
+ )}
- {!hasCode ? (
+ {!showCodeTabs ? (
)}
+ {/* end of code-tabs vs TOC switch */}
+
{relatedExamples.length > 0 && (
@@ -214,10 +250,11 @@ const v1DocsUrl = `https://v1.design.alberta.ca/examples/${slug}`;
margin-bottom: var(--goa-space-2xl, 2.5rem);
}
+ /* Use goa-text typography tokens so MDX headings match the design system's
+ heading scale without authors having to wrap each heading in . */
.example-content :global(h2) {
- font-size: 1.25rem;
- font-weight: 600;
- margin: var(--goa-space-xl, 2rem) 0 var(--goa-space-m, 1rem);
+ font: var(--goa-typography-heading-m);
+ margin: var(--goa-space-2xl, 2.5rem) 0 var(--goa-space-m, 1rem);
color: var(--goa-color-text-default, #333);
}
@@ -225,6 +262,12 @@ const v1DocsUrl = `https://v1.design.alberta.ca/examples/${slug}`;
margin-top: 0;
}
+ .example-content :global(h3) {
+ font: var(--goa-typography-heading-s);
+ margin: var(--goa-space-2xl, 2.5rem) 0 var(--goa-space-s, 0.5rem);
+ color: var(--goa-color-text-default, #333);
+ }
+
.example-content :global(p) {
margin-bottom: var(--goa-space-m, 1rem);
max-width: 65ch;
diff --git a/docs/src/pages/examples/[slug]/preview.astro b/docs/src/pages/examples/[slug]/preview.astro
new file mode 100644
index 0000000000..7098c794a8
--- /dev/null
+++ b/docs/src/pages/examples/[slug]/preview.astro
@@ -0,0 +1,87 @@
+---
+/**
+ * Generic preview route for flat-slug page-scale examples.
+ *
+ * Renders the page's React component full-screen wrapped in PreviewLayout.
+ * Astro hydration needs static imports so it can ship the right JS bundle
+ * to the client, hence the SLUG_TO_COMPONENT map below. Adding a new
+ * page-scale entry means one import + one map entry here.
+ *
+ * Workspace pages (nested slugs) use [family]/[page]/preview.astro which
+ * iframes an external demo. Error-page variants and question-page variants
+ * have their own routes.
+ */
+import { getCollection } from "astro:content";
+import PreviewLayout from "../../../layouts/PreviewLayout.astro";
+import { StartPage } from "../../../content/examples/start-page/react";
+import { TaskListPage } from "../../../content/examples/task-list-page/react";
+import { ReviewPage } from "../../../content/examples/review-page/react";
+import { ResultPage } from "../../../content/examples/result-page/react";
+import { BasicPageLayout } from "../../../content/examples/basic-page-layout/react";
+
+export async function getStaticPaths() {
+ // Inline list — Astro's getStaticPaths runs in an isolated module context
+ // and cannot see frontmatter top-level constants like SLUG_TO_COMPONENT.
+ // Keep this list in sync with the SLUG_TO_COMPONENT map above when adding
+ // page-scale entries that need a preview route.
+ const slugsWithPreview = new Set([
+ "start-page",
+ "task-list-page",
+ "review-page",
+ "result-page",
+ "basic-page-layout",
+ ]);
+ const examples = await getCollection("examples");
+ return examples
+ .filter(
+ (e) =>
+ !e.slug.includes("/") &&
+ e.data.size !== "section" &&
+ slugsWithPreview.has(e.slug),
+ )
+ .map((entry) => ({
+ params: { slug: entry.slug },
+ props: { entry },
+ }));
+}
+
+const { entry } = Astro.props;
+const { slug } = Astro.params;
+const { data } = entry;
+const fullWidth = data.previewFullWidth === true;
+
+const githubBlob = `https://github.com/GovAlta/ui-components/blob/dev/docs/src/content/examples/${slug}/react.tsx`;
+const githubFolder = `https://github.com/GovAlta/ui-components/tree/dev/docs/src/content/examples/${slug}`;
+---
+
+
+
+ {/* Each branch is its own statically-imported JSX element so Astro
+ can wire up client:load hydration. Add a new branch when adding
+ a page-scale entry that needs a preview route. */}
+ {slug === "start-page" &&
+
+
diff --git a/docs/src/pages/examples/error-pages/401/preview.astro b/docs/src/pages/examples/error-pages/401/preview.astro
new file mode 100644
index 0000000000..6c2dc91688
--- /dev/null
+++ b/docs/src/pages/examples/error-pages/401/preview.astro
@@ -0,0 +1,76 @@
+---
+/**
+ * Error pages: 401 live preview
+ *
+ * Render-local preview. Composition mirrors
+ * content/examples/error-pages/401/web-components.html so the rendered
+ * preview is visually identical to the source a consumer would paste.
+ */
+import PreviewLayout from "../../../../layouts/PreviewLayout.astro";
+import { withBase } from "@/lib/base-url";
+
+const homeUrl = withBase("/");
+---
+
+
+
+
+
+
+
+ Error 401
+
+
+
+
+ Restricted access
+
+ We cannot provide access to this page without valid credentials. Please sign in or
+ contact support at
+
+ cs.licensingsupport@gov.ab.ca
+
+ to request access.
+
+
+
+
+ Go to home page
+
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/error-pages/404/preview.astro b/docs/src/pages/examples/error-pages/404/preview.astro
new file mode 100644
index 0000000000..05343bdff1
--- /dev/null
+++ b/docs/src/pages/examples/error-pages/404/preview.astro
@@ -0,0 +1,71 @@
+---
+/**
+ * Error pages: 404 live preview
+ *
+ * Render-local preview. Composition mirrors
+ * content/examples/error-pages/404/web-components.html so the rendered
+ * preview is visually identical to the source a consumer would paste.
+ */
+import PreviewLayout from "../../../../layouts/PreviewLayout.astro";
+import { withBase } from "@/lib/base-url";
+
+const homeUrl = withBase("/");
+---
+
+
+
+
+
+
+
+ Error 404
+
+
+
+
+ Page not found
+
+ The page you're looking for doesn't exist or has been moved.
+
+
+
+
+ Go to home page
+
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/error-pages/500/preview.astro b/docs/src/pages/examples/error-pages/500/preview.astro
new file mode 100644
index 0000000000..9f8eb71b6a
--- /dev/null
+++ b/docs/src/pages/examples/error-pages/500/preview.astro
@@ -0,0 +1,72 @@
+---
+/**
+ * Error pages: 500 live preview
+ *
+ * Render-local preview. Composition mirrors
+ * content/examples/error-pages/500/web-components.html so the rendered
+ * preview is visually identical to the source a consumer would paste.
+ */
+import PreviewLayout from "../../../../layouts/PreviewLayout.astro";
+import { withBase } from "@/lib/base-url";
+
+const homeUrl = withBase("/");
+---
+
+
+
+
+
+
+
+ Error 500
+
+
+
+
+ We are experiencing a problem
+
+ We cannot load this page right now. Please try again in a few minutes. We apologize
+ for the inconvenience.
+
+
+
+
+ Go to home page
+
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/index.astro b/docs/src/pages/examples/index.astro
index 75692da9e2..990a81abef 100644
--- a/docs/src/pages/examples/index.astro
+++ b/docs/src/pages/examples/index.astro
@@ -16,21 +16,43 @@ import Breadcrumbs from '../../components/Breadcrumbs.astro';
import { ExamplesGrid } from '../../components/ExamplesGrid';
-// Get all examples
+// Pull both collections so the grid can surface product-type overviews
+// alongside their member examples. Synthesizing the productTypes entries
+// at render time avoids the stub-MDX duplication we used to have in the
+// examples collection.
const allExamples = await getCollection('examples');
+const allProductTypes = await getCollection('productTypes');
+
+// Transform examples to the shape ExamplesGrid expects, excluding hidden entries.
+const exampleEntries = allExamples
+ .filter((example) => !example.data.hidden)
+ .map(example => ({
+ slug: example.slug,
+ data: example.data,
+ body: example.data.description || example.body,
+ }));
+
+// Synthesize a size:product card per productType. The slug matches the
+// /examples/[productType]/ route the [family] page handler already serves.
+const productTypeEntries = allProductTypes.map(productType => ({
+ slug: productType.slug,
+ data: {
+ id: productType.data.id,
+ title: productType.data.title,
+ description: productType.data.summary.replace(/<[^>]+>/g, ''),
+ size: 'product' as const,
+ components: productType.data.components ?? [],
+ tags: productType.data.tags ?? [],
+ status: productType.data.status,
+ previewImage: productType.data.heroImage,
+ },
+ body: productType.data.summary,
+}));
-// Sort by title (default)
-const sortedExamples = allExamples.sort((a, b) =>
+const examples = [...exampleEntries, ...productTypeEntries].sort((a, b) =>
a.data.title.localeCompare(b.data.title)
);
-// Transform to the shape ExamplesGrid expects
-const examples = sortedExamples.map(example => ({
- slug: example.slug,
- data: example.data,
- body: example.data.description || example.body,
-}));
-
---
({
For citizens submitting applications and requests
-
-
-
- Digital service
- How workspace and public form connect end-to-end
-
+
+
+
+
diff --git a/docs/src/pages/examples/question-page/variants/grouped/preview.astro b/docs/src/pages/examples/question-page/variants/grouped/preview.astro
new file mode 100644
index 0000000000..79eb3f4bbd
--- /dev/null
+++ b/docs/src/pages/examples/question-page/variants/grouped/preview.astro
@@ -0,0 +1,24 @@
+---
+import PreviewLayout from "../../../../../layouts/PreviewLayout.astro";
+import { GroupRelatedQuestionsTogetherOnAQuestionPage } from "../../../../../content/examples/question-page/variants/grouped/react";
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/question-page/variants/help-details/preview.astro b/docs/src/pages/examples/question-page/variants/help-details/preview.astro
new file mode 100644
index 0000000000..18ffa1be51
--- /dev/null
+++ b/docs/src/pages/examples/question-page/variants/help-details/preview.astro
@@ -0,0 +1,24 @@
+---
+import PreviewLayout from "../../../../../layouts/PreviewLayout.astro";
+import { ShowMoreInformationToHelpAnswerAQuestion } from "../../../../../content/examples/question-page/variants/help-details/react";
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/question-page/variants/one-question/preview.astro b/docs/src/pages/examples/question-page/variants/one-question/preview.astro
new file mode 100644
index 0000000000..218f2534c3
--- /dev/null
+++ b/docs/src/pages/examples/question-page/variants/one-question/preview.astro
@@ -0,0 +1,24 @@
+---
+import PreviewLayout from "../../../../../layouts/PreviewLayout.astro";
+import { QuestionPage } from "../../../../../content/examples/question-page/variants/one-question/react";
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/question-page/variants/progress-indicator/preview.astro b/docs/src/pages/examples/question-page/variants/progress-indicator/preview.astro
new file mode 100644
index 0000000000..6761fdbc0f
--- /dev/null
+++ b/docs/src/pages/examples/question-page/variants/progress-indicator/preview.astro
@@ -0,0 +1,24 @@
+---
+import PreviewLayout from "../../../../../layouts/PreviewLayout.astro";
+import { ShowASimpleProgressIndicatorOnAQuestionPage } from "../../../../../content/examples/question-page/variants/progress-indicator/react";
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/question-page/variants/section-title/preview.astro b/docs/src/pages/examples/question-page/variants/section-title/preview.astro
new file mode 100644
index 0000000000..50e13f7d3e
--- /dev/null
+++ b/docs/src/pages/examples/question-page/variants/section-title/preview.astro
@@ -0,0 +1,24 @@
+---
+import PreviewLayout from "../../../../../layouts/PreviewLayout.astro";
+import { ShowASectionTitleOnAQuestionPage } from "../../../../../content/examples/question-page/variants/section-title/react";
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/foundations/content-guidelines/error-messages.astro b/docs/src/pages/foundations/content-guidelines/error-messages.astro
index d9a2e26e76..ad5f35f8f4 100644
--- a/docs/src/pages/foundations/content-guidelines/error-messages.astro
+++ b/docs/src/pages/foundations/content-guidelines/error-messages.astro
@@ -525,27 +525,27 @@ const formatPatterns: PatternGroup[] = [
}
:global(.explicit-example span.green) {
- background-color: #cde9b9;
+ background-color: var(--goa-color-extended-pasture-border);
}
:global(.explicit-example span.blue) {
- background-color: #bcdae7;
+ background-color: var(--goa-color-extended-sky-border);
}
:global(.explicit-example span.yellow) {
- background-color: #fadfb1;
+ background-color: var(--goa-color-extended-prairie-border);
}
:global(.explicit-example span.greenUnder) {
- text-decoration: underline solid #cde9b9 3px;
+ text-decoration: underline solid var(--goa-color-extended-pasture-border) 3px;
}
:global(.explicit-example span.blueUnder) {
- text-decoration: underline solid #bcdae7 3px;
+ text-decoration: underline solid var(--goa-color-extended-sky-border) 3px;
}
:global(.explicit-example span.yellowUnder) {
- text-decoration: underline solid #fadfb1 3px;
+ text-decoration: underline solid var(--goa-color-extended-prairie-border) 3px;
}
@media (min-width: 768px) {
diff --git a/docs/src/pages/get-started/[...slug].astro b/docs/src/pages/get-started/[...slug].astro
new file mode 100644
index 0000000000..263038105d
--- /dev/null
+++ b/docs/src/pages/get-started/[...slug].astro
@@ -0,0 +1,25 @@
+---
+import { getCollection, render } from "astro:content";
+import DocumentationPageLayout from "../../layouts/DocumentationPageLayout.astro";
+
+export async function getStaticPaths() {
+ const entries = await getCollection("get-started");
+ return entries.map((entry) => ({
+ // The "index" entry maps to the collection root URL (/get-started).
+ // Astro's [...slug] rest route accepts undefined for the parent path.
+ params: { slug: entry.slug === "index" ? undefined : entry.slug },
+ props: { entry },
+ }));
+}
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+---
+
+
+
diff --git a/docs/src/pages/get-started/automated-accessibility.astro b/docs/src/pages/get-started/automated-accessibility.astro
deleted file mode 100644
index 061b16c880..0000000000
--- a/docs/src/pages/get-started/automated-accessibility.astro
+++ /dev/null
@@ -1,92 +0,0 @@
----
-/**
- * Get Started - Automated Accessibility
- *
- * Guidance on combining automated and manual accessibility testing.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Automated accessibility
-
- Automated accessibility testing tools help you identify potential accessibility issues. Use them as a starting point.
-
-
-
- However, these tools are not a complete solution. They can produce:
-
-
- - False positives – flagging issues that are not actual problems
- - False negatives – missing real accessibility barriers
-
-
- To ensure your digital product is accessible, combine automated testing with manual testing and apply
- human judgment.
-
- Why automated tools alone are not enough
-
- False positives
-
- Automated tools may flag elements as non-compliant even when they work correctly for users. For
- example, a tool may report that an input is "missing an id" even though it is correctly associated with a
- label using a valid method, such as wrapping the input inside a <label> element.
-
-
- False negatives
-
- Automated tools cannot detect nuanced or context-specific issues. For example, all interactive
- elements may be tabbable, but the order jumps around the page. Tools often don't judge whether the
- tab order is logical for completing the task.
-
-
- Real user experience
-
- Accessibility ensures real people can use a product effectively. Automated tools cannot fully simulate
- how users interact with your product.
-
- Steps for effective accessibility testing
-
-
- -
- Run automated tools to get an initial assessment.
-
- -
- Manually verify flagged issues and review the element's intent and context.
-
- -
- Do additional manual testing for issues automated tools cannot detect:
-
- - Test with a screen reader, such as VoiceOver (macOS) or NVDA (Windows)
- - Test keyboard navigation by checking focus visibility and order
-
-
- -
- Report findings
-
- - Record what you tested, what failed, and how to reproduce it
- - If the issue relates to a design system component, submit it using the design system bug report form
-
-
-
- Why this process matters
-
- Automated tools provide helpful insight. Relying only on automation can result in:
-
-
- - Time spent fixing issues that are not real barriers
- - Missed opportunities to address genuine accessibility issues
- - A false sense of compliance without meaningful usability improvements
-
-
- Combine automated and manual testing to identify real barriers. This approach improves accessibility
- and overall product quality.
-
-
diff --git a/docs/src/pages/get-started/component-lifecycle.astro b/docs/src/pages/get-started/component-lifecycle.astro
deleted file mode 100644
index 42b0df0f4a..0000000000
--- a/docs/src/pages/get-started/component-lifecycle.astro
+++ /dev/null
@@ -1,67 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Component Lifecycle
- *
- * Defines the stages each Design System component moves through.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Component lifecycle
-
- The component lifecycle defines the stages each Design System component moves through, from
- Experimental to Production to Legacy.
-
-
-
- To request a new component or propose an enhancement, follow the
- design contribution process.
-
- Experimental
-
- Experimental components are new or significantly updated. They are available for testing and feedback
- before public release.
-
-
- Characteristics
-
- - Feedback is gathered from selected teams
- - May be unstable or include breaking changes
- - Limited documentation
-
- Production
-
- Production components are stable and ready for broader adoption.
-
-
- Characteristics
-
- - Fully documented, including design guidelines, properties, and examples
- - Meet accessibility and design system standards
- - Optimized for mobile use
- - Actively maintained with updates and bug fixes
- - Publicly available documentation
-
- Legacy
-
- Legacy components are older components maintained primarily to support older implementations. If
- possible, transition to production is recommended.
-
-
- Characteristics
-
- - No active maintenance or updates
- - Critical issues may remain unresolved
- - Recommended alternative clearly identified
- - Marked as "Legacy" in official documentation
-
-
diff --git a/docs/src/pages/get-started/contribute.astro b/docs/src/pages/get-started/contribute.astro
deleted file mode 100644
index 7a2ea6d675..0000000000
--- a/docs/src/pages/get-started/contribute.astro
+++ /dev/null
@@ -1,188 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Contribute
- *
- * How to contribute to the Design System (design and code).
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Contribute
-
- The Design System is a shared resource used and improved by service teams. All roles are encouraged
- to contribute.
-
-
-
- Start by using existing Design System components and patterns. If a component or pattern does not
- meet your needs, follow the contribution process below.
-
- Design contribution process
-
- If a required component or example does not exist in production,
- contact the Design System team. We will review the request together and determine next steps.
-
-
- 1. Contact the team
-
- Book a design system drop-in hours session.
-
- Be prepared to:
-
- - Describe the component or pattern and its purpose
- - Explain your user needs and service goals
- - Share iterations explored with and without the Design System
-
-
-
- There are open contribution files in Figma for every component and pattern in the design system,
- including unpublished ideas and experiments.
-
-
- 2. Contribution criteria
- A proposed component or pattern must meet the following criteria.
-
- Proposal criteria
- Useful
-
- Evidence shows it supports multiple teams or services. Provide screenshots or links to demonstrate usage.
-
-
- Unique
-
- It does not duplicate an existing component or pattern. If replacing an existing component, provide
- evidence that the new approach improves usability or accessibility.
-
-
- Publication standards
- To be published, the solution must be:
-
- Usable
-
- Improves clarity, usability, and accessibility for users. Is informed by research and addresses a
- validated user need.
-
-
- Universal
-
- Inclusive and accessible. Meets or exceeds accessibility standards.
- WCAG 2.2 AA is the minimum requirement.
-
-
- 3. Backlog and collaboration
-
- If approved, the item is added to the
- Design System's backlog.
-
-
- When development begins, the Design System team will collaborate with you to confirm detailed requirements.
-
- Code contribution process
-
- The Design System supports multiple development frameworks through Web Components. Contributing full
- components can be complex. Smaller contributions are encouraged.
-
-
- Recommended contribution types
-
- - Bug fixes
- - Documentation updates
- - Enhancements to existing components
-
-
- Start by contacting the team in the #design-system-support Slack channel.
-
-
- Select an issue tagged ready-for-contribution from the
- backlog.
- Confirm which issue you will work on.
-
-
-
- Since the repository is public, use a personal GitHub account instead of your Enterprise Managed User (EMU) account.
-
-
- Set up your contribution environment
-
- - Clone the ui-components repository.
- - Open the repository in your IDE.
- - Create a branch named:
contributions/story-number
- -
- Run the following commands:
-
npm i
-npm run build
-
- -
- The playgrounds for local testing are located in:
-
/apps/dev/angular
-/apps/dev/react
-
-
-
- Run playground environments
- Angular
- npm run dev:watch
-npm run serve:dev:angular
-
- React
- npm run dev:watch
-npm run serve:dev:react
-
- Repository structure
-
- React wrappers
- /libs/react-components/src/lib
- Each folder represents a single component with its associated unit tests and wrapper code.
-
- Angular wrappers
- /libs/angular-components/src/lib/components
- Each folder represents a single component with its associated unit tests and wrapper code.
-
- Web Components
- /libs/web-components/src/components
-
- - Unit tests as
*.spec.ts
- - Component code as
*.svelte
-
-
- Testing requirements
-
- - Write all unit tests in Svelte.
- - If updating React or Angular wrappers, write unit tests in those respective frameworks.
- -
- Add browser testing using Jest for React wrappers and Svelte components when appropriate.
- These can be found in:
libs/react-components/specs
-
- - Manually test components in both React and Angular.
- -
- Create test files that others can use to manually test the PR. These can be created in:
-
/apps/prs/angular
-/apps/prs/react
-
- - Follow the conventions already used in those files to create your test files.
-
- A Design System developer will also manually test the pull request.
-
- Submit your contribution
- Use the following commit message format:
-
- Bug fix
- fix(#storyNumber): short description (7 words max)
-
- Feature request
- feat(#storyNumber): short description (7 words max)
-
-
- - Create a pull request from your branch to the
dev branch.
- - Notify the design system team of the PR.
-
-
diff --git a/docs/src/pages/get-started/designers.astro b/docs/src/pages/get-started/designers.astro
deleted file mode 100644
index 2d8a3b163d..0000000000
--- a/docs/src/pages/get-started/designers.astro
+++ /dev/null
@@ -1,94 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Designers Overview
- *
- * Overview of design system resources for designers.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Overview
-
- As a designer, you use the design system through Figma.
-
- In Figma, you can access:
-
-
- - Design tokens
- - Components
- - Patterns
-
-
-
- The design system library in Figma aligns with coded components used by developers. Start with
- design system components for common parts of your service. This helps developers use the matching
- coded components and reduces custom work.
-
-
- Start with the design system. Validate your design through user testing. If usability issues arise,
- or the problem cannot be solved within the system, consider creating a custom solution.
-
- Design with development in mind
-
- When selecting components, prioritize those with a "goa-" prefix, such as
- goa-input. These components exist in both design and development. Using them reduces
- the need for custom development.
-
- Choose shared components whenever possible to maintain consistency and efficiency.
-
- Design tokens
- Design system components in Figma and code are built using design tokens.
-
- Use tokens to communicate design decisions clearly. Developers can reference the same tokens in code.
-
- Instead of sharing hex values or pixel adjustments, reference semantic tokens.
- For example:
-
- - Colour:
--goa-color-info-default
- - Spacing:
--goa-spacing-m
-
- Using tokens reduces back-and-forth and keeps design and development aligned.
-
- Components
- All design system components are available in Figma and in code.
-
- These components are designed to meet
- WCAG 2.2 accessibility standards.
-
- Avoid detaching components. Instead:
-
- - Use variants
- - Show or hide layers within the component
-
-
- Use #figma for Figma-related issues, including library updates, missing components,
- broken instances, or component behaviour in Figma.
-
-
- Use #design-system-support for design system guidance, component usage questions,
- standards, and implementation support.
-
- Keep your components up to date. Figma will notify you when library updates are available.
-
- Figma file templates and helper components
- Each digital service project folder includes a starter Figma template.
- Use this template to:
-
- - Organize your design file
- - Support developer handoff
- - Help team members navigate files
-
-
- Helper components are also available. Use them to clearly communicate intent when sharing designs
- with developers and other team members.
-
-
diff --git a/docs/src/pages/get-started/designers/designing-with-ds.astro b/docs/src/pages/get-started/designers/designing-with-ds.astro
deleted file mode 100644
index a875429941..0000000000
--- a/docs/src/pages/get-started/designers/designing-with-ds.astro
+++ /dev/null
@@ -1,81 +0,0 @@
----
-/**
- * Get Started - Designers - Designing with Design System 2.0
- *
- * How to start new designs and update existing projects to DS 2.0.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../../layouts/DocumentationPageLayout.astro';
----
-
-
- Designing with Design System 2.0
-
- What's new in DS 2.0 and how to start using it in your designs.
-
-
- The Digital Design and Delivery (DDD) Design System has evolved to better support how service teams
- design and build digital government services. Design System 2.0 includes an updated design
- language, new tokens, refreshed components, and ready-to-use templates.
-
- Starting a new design
-
- Use DS 2.0 templates as your starting point. Templates package layout, navigation, spacing, and
- example content that you can adapt to your service. Some templates are built for specific service types
- (for example, public-facing forms and workspace applications), and others are more general-purpose
- starting points you can use across many kinds of pages and flows.
-
-
- Starting from an existing design
-
- Library swap
-
- Use a library swap if
- your goal is to convert most of the file to DS 2.0 in one pass.
-
-
- - Make a copy of your file before you start.
- - Expect mixed results. Some screens may need cleanup after the swap.
-
-
- Manual rebuild
- Use a manual rebuild if you need more control.
-
- - Rebuild your highest value screens first.
- - Consider using DS 2.0 templates as a base to speed things up.
-
- Update an existing project to the new design library
-
- Approach 1: Developer-first
- Use this approach in most cases.
-
- - A developer creates a new branch and completes the upgrade steps.
- - The team runs the upgraded application to see what changed.
- - Designers review the upgraded screens and identify what needs design updates.
-
- When reviewing the upgraded branch, watch for:
-
- - Spacing and layout rhythm
- - Typography scale and weight usage
- - Dense or constrained screens (these often have the highest risk during an update)
-
-
- Approach 2: Design-first
- Use this approach when you want design work to move ahead of development work.
-
- - Identify custom elements that support your users' needs.
- - Create an inventory and prioritize items by importance and effort.
- - Redesign the highest priority items using the visual design values in the Styles library.
-
-
-
- In most cases, start with the developer-first approach. It helps you quickly see what changed in your
- real product, so you can focus design effort where it matters most.
-
-
diff --git a/docs/src/pages/get-started/designers/ux-guidelines.astro b/docs/src/pages/get-started/designers/ux-guidelines.astro
deleted file mode 100644
index b44c9c82e5..0000000000
--- a/docs/src/pages/get-started/designers/ux-guidelines.astro
+++ /dev/null
@@ -1,55 +0,0 @@
----
-/**
- * Get Started - Designers - User Experience Guidelines
- *
- * UX guidelines for Government of Alberta digital products.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../../layouts/DocumentationPageLayout.astro';
----
-
-
- User experience guidelines
-
- Digital products built for the Government of Alberta should comply with these guidelines to ensure a
- quality user experience for Albertans.
-
-
-
- - User-centered: Designed with a clear understanding of users, their goals, tasks, environments, and context of use, using user-centered design methods.
- - Usable: Interfaces will be easy to use, enabling users to find the information they need and complete tasks successfully.
- - Accessible: Digital products will be inclusive, ensuring usability for everyone, regardless of physical or cognitive ability.
- - Trustworthy: Experiences will feel familiar and recognizable as a Government of Alberta product, ensuring users' security and privacy.
- - Modern: Digital experiences will meet present-day user expectations and preferences for aesthetics and interaction.
-
-
-
- For more details on the process of assessing compliance to each guideline, refer to our
- User Experience Guidelines and Design System Checklist.
-
- Usability testing
-
- Usability testing is our preferred method to understand user needs as they relate to each guideline.
-
- Suitable usability testing includes:
-
- - Diverse user group: Real users from different demographic, behavioural backgrounds, and geographical regions within Alberta that will experience the problem or benefit of the product.
- - Inclusive testing: Users with various physical and/or cognitive abilities, literacy levels, and tech savviness.
- - Device variety: A diverse range of devices that reflect users' preferred choice when interacting with government services.
- - Tasks: Activities that cover tasks and service process from end-to-end.
-
-
- Frequent usability testing should be conducted to maintain product usability, effectiveness and
- alignment to the user needs as they evolve over time.
-
-
- For guidance on the process of usability testing, refer to our
- Understanding Usability documentation.
-
-
diff --git a/docs/src/pages/get-started/developers.astro b/docs/src/pages/get-started/developers.astro
deleted file mode 100644
index b34d1c3712..0000000000
--- a/docs/src/pages/get-started/developers.astro
+++ /dev/null
@@ -1,104 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Developers Overview
- *
- * Overview of design system resources for developers.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Overview
-
- As a developer, you use the Design System through tokens, components, examples, and templates.
-
-
-
- The DDD Design System is built using Web Components. Web Components are framework-agnostic.
- You can use them with Angular, React, or other front-end frameworks.
-
- The Design System includes:
-
- - Tokens
- - Components
- - Examples
- - Templates
-
-
- Designers use equivalent resources in Figma. When they design with Design System components, you
- can build with the matching coded components. This reduces custom development and rework.
-
-
- All Design System components are designed and built to meet
- WCAG 2.2 accessibility standards.
-
- Tokens
-
- Access the tokens as an
- NPM package.
-
-
- Import the SCSS or CSS file into your project. Replace hard-coded values with Design System token variables.
-
-
- Designers reference the same tokens in their tools. This keeps design and development aligned during handoff.
-
-
- Components
- Components are reusable user interface elements built for use across services.
- You can:
-
- - Use components individually
- - Combine them into patterns
- - Apply them in different contexts
-
- Components are available:
-
- - As Web Components
- - As Angular wrappers
- - As React wrappers
-
-
- Refer to the Design System technologies documentation
- for implementation details.
-
-
- Examples
-
- Examples are multiple components assembled in realistic service contexts. They help you understand
- how to apply Design System guidance in a working interface.
-
- You can use examples to:
-
- - Understand how components work together
- - Use them as a starting point for building parts of your interface
- - Use proven approaches to meet user needs
-
-
- Examples help you build with more consistency and less rework. Use them to guide implementation,
- then adjust them to meet the needs of your product.
-
-
- Templates
-
- Templates are opinionated starting points for common service types. They package layout, navigation,
- spacing, and example content so you can start with a proven structure instead of building from scratch.
-
- You can use templates to:
-
- - Start a new product with a proven structure
- - Learn how components work together in a real layout
- - Adapt a proven starting point to fit your service needs
-
-
- Templates help teams move faster, reduce rework, and stay aligned with Design System guidance.
-
-
diff --git a/docs/src/pages/get-started/developers/browsers.astro b/docs/src/pages/get-started/developers/browsers.astro
deleted file mode 100644
index 3ced88e5fc..0000000000
--- a/docs/src/pages/get-started/developers/browsers.astro
+++ /dev/null
@@ -1,87 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Developers - Supported browsers
- *
- * Browser and OS support matrix for Design System components.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../../layouts/DocumentationPageLayout.astro';
----
-
-
- Supported browsers
-
- Design System components are tested across supported browsers and devices.
-
-
-
- We support the latest version of each browser listed on this page. Support applies to the browser and
- operating system combinations shown in the table below. On mobile, support is limited to the browser
- and operating system combinations listed for Android and iOS.
-
-
- Browser and operating system support
-
-
-
-
-
- Browser
- Windows
- Mac OS
- Android
- iOS
-
-
-
-
- Google Chrome
- Yes
- Yes
- Yes
- Yes
-
-
- Microsoft Edge
- Yes
- Yes
-
-
- Mozilla Firefox
- Yes
- Yes
- Yes
-
-
- Apple Safari
- N/A
- Yes
- N/A
- Yes
-
-
-
-
-
- Representative mobile OS used in testing
-
- - Android OS: 10+
- - iOS: 15+
-
- Testing guidance
-
- Use supported browsers and operating system versions when developing and testing services. If you
- encounter a browser-specific issue, follow the
- Verify a bug process.
-
-
diff --git a/docs/src/pages/get-started/developers/bug.astro b/docs/src/pages/get-started/developers/bug.astro
deleted file mode 100644
index ffabd0fc5e..0000000000
--- a/docs/src/pages/get-started/developers/bug.astro
+++ /dev/null
@@ -1,65 +0,0 @@
----
-/**
- * Get Started - Developers - Verify a bug
- *
- * Process for verifying and reporting Design System component issues.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../../layouts/DocumentationPageLayout.astro';
----
-
-
- Verify a bug
-
- Follow this process when you encounter an issue with a Design System component.
-
-
-
- These steps help confirm whether the issue is caused by the Design System, your product setup, or
- custom code. This process applies to Angular and React implementations.
-
-
- 1. Check versions
- Confirm you are using the latest version of:
-
- - Web Components
- - Angular or React
-
-
- If you are not using the latest version, upgrade and retest. If the issue remains, continue to the next step.
-
-
- 2. Test with product templates
- Use the official Angular or React product templates to isolate the issue.
-
- This helps determine whether the issue exists outside your project configuration.
-
- 3. Recreate the issue
- Create a minimal test environment.
-
- - Use only the code required for the example to function
- - Include only the component experiencing the issue
- - Remove unrelated dependencies or custom logic
-
- Confirm whether the issue can be replicated.
-
- 4. Share and report
- If you can reproduce the issue:
-
- - Share the template application link in the #design-system-support Slack channel
- - Provide a link to your repository so the team can review and replicate the issue
-
-
- Following these steps will help to ensure efficient investigation and quicker resolution of
- design system component issues.
-
-
diff --git a/docs/src/pages/get-started/developers/setup.astro b/docs/src/pages/get-started/developers/setup.astro
deleted file mode 100644
index 326b964dfe..0000000000
--- a/docs/src/pages/get-started/developers/setup.astro
+++ /dev/null
@@ -1,141 +0,0 @@
----
-/**
- * Get Started - Developers - Setup
- *
- * Setup instructions for Angular, React, and Web Components.
- * Based on the current website content with DS 2.0 token updates.
- */
-import DocumentationPageLayout from "../../../layouts/DocumentationPageLayout.astro";
-import DropInCallout from "../../../components/DropInCallout.astro";
----
-
-
- Developer setup
-
- Set up the Government of Alberta Design System in Angular, React, or directly with Web
- Components.
-
-
- Angular UI components
-
- Supported versions: 18, 19, 20, 21
-
-
- This is the web component library and utilizes Angular's web component
- integration.
-
-
- 1. Add dependencies
- npm i @abgov/web-components
-npm i @abgov/angular-components
-npm i @abgov/ui-components-common
-npm i @abgov/design-tokens
-
- 2. Link ionicons in app/index.html
-
- Add the following in the head element:
-
- <script type="module" src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.esm.js"></script>
-<script nomodule src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.js"></script>
-
- 3. Update src/app/app.module.ts
-
- Update src/app/app.module.ts as per the four steps below:
-
- // 1. Import the CUSTOM_ELEMENTS_SCHEMA
-import { CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
-
-// 2. Import the libs
-import "@abgov/web-components";
-import { AngularComponentsModule } from "@abgov/angular-components";
-
-@NgModule({
- declarations: [AppComponent],
- imports: [
- // 3. Add the needed imports
- BrowserModule,
- AngularComponentsModule,
- ],
- providers: [],
- bootstrap: [AppComponent],
- // 4. Add the CUSTOM_ELEMENTS_SCHEMA to the NgModule
- schemas: [CUSTOM_ELEMENTS_SCHEMA],
- })
-export class AppModule {}
-
- 4. Add the styles link in src/styles.css
- @import "@abgov/web-components/index.css";
-@import "@abgov/design-tokens/dist/tokens.css";
-
- React UI components
-
- Supported versions: 17, 18, 19
-
-
- This library contains React components which wrap the Government of Alberta Web
- Components.
-
-
- 1. Add dependencies
- npm i @abgov/react-components
-npm i @abgov/web-components
-npm i @abgov/ui-components-common
-npm i @abgov/design-tokens
-
- 2. Link ionicons in app/index.html
-
- Add the following to the head element:
-
- <script type="module" src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.esm.js"></script>
-<script nomodule src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.js"></script>
-
- 3. Import the web components in src/main.tsx
- import "@abgov/web-components";
-
- 4. Import the styles in src/index.css
- @import "@abgov/web-components/index.css";
-@import "@abgov/design-tokens/dist/tokens.css";
-
- Web components
-
- This library contains web components from the Government of Alberta.
-
-
- 1. Add dependencies
- npm i @abgov/web-components
-npm i @abgov/design-tokens
-
- 2. Link ionicons in index.html
-
- Add the following in the head element:
-
- <script type="module" src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.esm.js"></script>
-<script nomodule src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.js"></script>
-
- 3. Import the web components into src/main.js
- import "@abgov/web-components";
-
- 4. Add the styles link in your main CSS file
-
- Add the following in src/assets/main.css or wherever your main CSS file is
- located:
-
- @import "@abgov/web-components/index.css";
-@import "@abgov/design-tokens/dist/tokens.css";
-
-
diff --git a/docs/src/pages/get-started/developers/technologies.astro b/docs/src/pages/get-started/developers/technologies.astro
deleted file mode 100644
index 272d9a8a12..0000000000
--- a/docs/src/pages/get-started/developers/technologies.astro
+++ /dev/null
@@ -1,111 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Developers - Technologies
- *
- * Overview of Design System technologies: Web Components, Svelte, Angular, React.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../../layouts/DocumentationPageLayout.astro';
----
-
-
- Technologies
-
- An overview of the technologies used in the Design System.
-
-
- How the technologies fit together
-
- The Design System is built on Web Components. Most component functionality lives in the core Web
- Components layer. Angular and React wrappers sit on top of that layer to make the components easier
- to use in those frameworks.
-
-
- We use Svelte to author the components that are compiled to custom elements. You can use the Design
- System through the core Web Components or through Angular and React wrappers.
-
-
- Web Components
-
- Web Components
- are a set of standard web technologies that allow you to create reusable custom elements. Each component
- includes its own structure, styling, and behaviour. This keeps it independent from the rest of your code.
-
-
- In the Design System, Web Components are the core library. They are framework-agnostic, so teams
- can use them in different front-end environments.
-
-
- Benefits of using Web Components
-
- - Reuse: Build once and use across pages, applications, and frameworks
- - Browser support: Work in modern browsers without additional libraries
- - Maintenance: Modular and self-contained structure simplifies updates
- - Encapsulation: Structure, style, and behaviour remain isolated from other page elements
- - Reliability: Code is not spread across HTML and JS files, thereby avoiding inconsistencies
- - Flexibility: Use inline, import, or compile components as needed
- - Composability: Combine components or integrate them with other components
-
-
-
- Do not use Web Components directly unless there is a specific reason to do so. Using wrappers provides
- type checking and developer helpers that are not available when working with the core Web Components alone.
-
- Svelte
-
- Svelte is the framework used to generate the
- Design System Web Components. Svelte combines JavaScript (logic), HTML (structure), and CSS (style)
- within a single file. It compiles these into efficient, reusable components.
-
- Why Svelte
- We use Svelte to:
-
- - Build reusable Web Components
- - Keep component logic, structure, and styling together
- - Support integration with multiple front-end frameworks
-
- Angular
-
-
- Supported versions: 18, 19, 20, 21
-
-
-
- Angular is a TypeScript-based framework for building
- web applications. The Design System supports Angular through Angular wrappers around the core Web Components.
-
-
- How Web Components and Angular work together
- Angular wrappers are created around the Web Components. These wrappers:
-
- - Manage component properties and events
- - Support form binding (Reactive and Template-driven)
- - Allow integration within Angular applications
-
- The Angular application interacts with the wrapper, which renders the underlying Web Component.
- React
-
-
- Supported versions: 17, 18, 19
-
-
-
- React is an open-source JavaScript library used to
- build user interfaces from reusable components.
-
-
- How Web Components and React work together
- React wrappers are created around the Web Components. These wrappers:
-
- - Manage properties and events
- - Enable integration within React applications
-
- The React application interacts with the wrapper, which renders the underlying Web Component.
-
diff --git a/docs/src/pages/get-started/index.astro b/docs/src/pages/get-started/index.astro
deleted file mode 100644
index 1b92e400aa..0000000000
--- a/docs/src/pages/get-started/index.astro
+++ /dev/null
@@ -1,108 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Landing Page
- *
- * Overview of the design system and how to use it in your service.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Start with the design system
-
- Start with the design system to build on the research and experience of other service teams.
- This helps you avoid repeating work that has already been done.
-
-
-
- The design system gives you a strong foundation for common service needs. It allows your team
- to focus on the specific challenges of your product.
- Build on it. Do not start from scratch.
-
-
- Design system by role
-
-
-
- Why start with the design system?
-
- Streamline collaboration
-
- Designers and developers work from shared components and guidance. This reduces rework and misalignment.
-
-
- Improve accessibility
- Accessibility is built into both the design and coded components.
-
- Reduce testing effort
- Components are tested across devices, browsers, and service contexts.
-
- Maintain consistency
-
- Components align with the broader system to create a cohesive user experience across government services.
-
-
- Spend more time on high-value work
- Using existing components saves time. You can focus on work that improves service quality, including:
-
- - Usability testing
- - User research
- - Content design
- - Accessibility reviews
- - Design quality checks
- - Low-fidelity prototyping and testing
-
- This leads to better outcomes for users.
- How to use the design system in your service
- Follow these steps when designing and building your service.
-
- Use system components first
- Start with existing components and patterns. These meet most user needs.
-
- Identify gaps through user testing
- Test your service with users. Identify needs that are not covered by current components.
-
- Before you design something new
-
- Check what's already available and what's in progress. The team can point you to existing components,
- solutions other teams have built, and planned work that may meet your need.
-
-
- Design and test new solutions when you need them
-
- If you still have a gap, design a new solution and test it with users. Move forward only when
- testing shows clear user value.
-
-
- Share what you learn
-
- Share your findings with the design system team. Your solution may become part of the design system.
-
-
-
- Do not create custom components without a clear user need.
- Unnecessary customization:
-
- - Increases maintenance effort
- - Slows delivery
- - Reduces consistency
-
- Always confirm the need through research and testing.
-
-
-
- View the design system governance process
-
-
diff --git a/docs/src/pages/get-started/migration-guide.astro b/docs/src/pages/get-started/migration-guide.astro
deleted file mode 100644
index b43c6678e3..0000000000
--- a/docs/src/pages/get-started/migration-guide.astro
+++ /dev/null
@@ -1,232 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Developers - Migration guide
- *
- * Migration pathways and guidance for moving products from DS 1.x to DS 2.0.
- * Content adapted from Confluence.
- */
-import DocumentationPageLayout from "../../layouts/DocumentationPageLayout.astro";
----
-
-
- Migration guide
-
- Design System 2.0 (DS 2.0) becomes the Government of Alberta standard in March 2026.
- New products starting after launch should use DS 2.0. Existing active products should
- plan their move to DS 2.0 during the recommended migration window, which runs from
- March 2026 to September 2026.
-
-
- Migration pathways
-
- The right migration path depends on your product's context, including team
- funding and capacity, other delivery obligations, product lifecycle, and the effort
- required to update. The three pathways are standard migration, late migration, and no
- migration.
-
-
- Starting a new product
-
- If your product starts after March 2026, start with DS 2.0. Migration pathways apply
- to existing products moving from DS 1.x to DS 2.0.
-
-
- Compare the pathways
-
-
-
-
-
- Pathway
- Use it when
- Recommendation
-
-
-
-
-
- Standard migration
-
-
-
- Your product has an active funded team and can migrate by September 2026
-
-
-
- Recommended default
-
-
-
-
- Late migration
-
-
-
- Your team cannot meet the standard window because of delivery timelines,
- dependencies, or capacity constraints
-
-
-
- Only when necessary
-
-
-
-
- No migration
-
-
-
- Your product does not have an active funded team and/or is not in a
- position to upgrade
-
-
-
- Only in specific cases
-
-
-
-
-
-
-
-
- Standard migration
-
-
- Standard migration is the default pathway for active products.
-
-
- Choose this path if your product has an active funded team and can schedule migration
- work between March 2026 and September 2026. This is the recommended path for most
- teams because it keeps your product aligned with the current standard and gives you
- the best support.
-
- Use this pathway when:
-
-
- - your product is actively maintained
- - your team can reserve time to migrate by September 2026
- - you want access to the latest templates, components, tokens, and guidance
-
-
-
- Plan for work across the product team. Typical upgrade tasks include the library
- updates, adjusting spacing and typography, and updating custom code to align with the
- DS 2.0 visual design. This is a significant update and will usually involve design,
- development, and testing.
-
-
- Late migration
-
- Late migration is a last-resort pathway for active products.
-
-
- Choose this path only when delivery deadlines, dependencies, or capacity constraints
- make the standard migration window unrealistic. This path gives your team more time,
- but it also increases risk and reduces your ongoing support.
-
- Use this pathway when:
-
-
- - a major delivery deadline blocks migration work
- - critical dependencies prevent the upgrade during the standard window
- - capacity or funding makes the standard window unrealistic
-
-
-
- Delaying migration means your product will wait longer to benefit from DS 2.0
- improvements. Over time, unresolved issues will accumulate and your product will be
- inconsistent with the new standard for longer.
-
-
- No migration
-
- No migration is an opt-out pathway for specific situations.
-
-
- Choose this path only when your product does not have an active funded team and/or is
- not in a position to upgrade. In these cases, the product may remain on DS 1.x.
-
-
- Teams on this path should understand that the product will not receive DS 2.0
- improvements and will not align with the current standard. Support for DS 1.x is
- limited from March to September and ends after September 2026.
-
-
- What changes after launch
-
- After the DS 2.0 launch in March 2026:
-
-
-
- - New products should use DS 2.0
- - Active products should aim to migrate by September 2026
- -
- After launch, web components will move to version 2.x. Although this is a major
- version update, it does not include breaking changes.
-
- -
- Angular 4.x and React 6.x receive limited fixes or features from March to
- September
-
- - Support for DS 1.0 ends after September 2026
- - Web components will update to a new major version after September 2026
-
-
-
- How to choose a pathway
-
- Use these questions to guide your decision:
-
-
-
- - Is this a new product starting after March 2026?
- - Does the product have an active funded team?
- - Can the team schedule migration work before September 2026?
- -
- Are there delivery deadlines or dependencies that block the standard window?
-
- -
- Is the team prepared to accept reduced support and higher maintenance risk if
- migration is delayed?
-
-
-
-
- Related guidance
-
- Review the setup steps for developers
-
-
diff --git a/docs/src/pages/get-started/out-of-support.astro b/docs/src/pages/get-started/out-of-support.astro
deleted file mode 100644
index 3944d67e3a..0000000000
--- a/docs/src/pages/get-started/out-of-support.astro
+++ /dev/null
@@ -1,54 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Out of Support Versions
- *
- * Information about unsupported Design System versions.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Out-of-support versions
-
- With the launch of the new Design System, support for Angular v4 and lower, and React v6 and lower
- is significantly reduced.
-
-
- What this means
-
- Fewer fixes or patches
- Bug fixes and security updates are no longer prioritized for these versions.
-
- No new features
- All new features and enhancements are released only in the current major version.
-
- Use at your own risk
- Existing projects may continue to run. However:
-
- - Compatibility with new browsers or operating systems is not guaranteed
- - Compatibility with future framework updates is not guaranteed
- - Issues discovered in these versions will not be resolved
-
-
-
- Projects using Angular v4 and lower, and React v6 and lower will continue to function.
- New issues or defects identified in these versions may not be fixed.
-
- What to do next
-
- Upgrade to the latest supported version. Refer to the
- version update guide.
-
-
- If you need support planning your upgrade,
- book time in drop-in hours.
-
-
diff --git a/docs/src/pages/get-started/qa-testing.astro b/docs/src/pages/get-started/qa-testing.astro
deleted file mode 100644
index 146cb12778..0000000000
--- a/docs/src/pages/get-started/qa-testing.astro
+++ /dev/null
@@ -1,77 +0,0 @@
----
-/**
- * Get Started - QA Testing
- *
- * Testing process for Design System components.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- QA testing
-
- This page outlines the testing process for the Design System. The process ensures components
- function correctly and integrate within products.
-
-
- Testing objectives
- QA testing ensures that:
-
- - Coded components match the design specifications
- - Components work in both React and Angular implementations
- - Components are responsive across screen sizes
- - Components meet accessibility requirements
- - Mobile behaviour is validated
- - Documentation on the Design System website is accurate
-
- Test cases
-
- Component testing
-
- - Confirm the rendered component matches design and styling guidelines
- - Confirm configured properties display correctly
- - Confirm the expected event triggers when interacting with the component
-
-
- Responsiveness testing
-
- - Test components on mobile, tablet, and desktop screen sizes
- - Use browser developer tools to simulate devices
-
-
- Accessibility testing
-
- - Run Lighthouse audits to review accessibility scores
- - Confirm appropriate ARIA (Accessible Rich Internet Applications) roles and labels
- - Test keyboard navigation
- - Test with NVDA screen reader
-
-
- Cross-browser testing
-
- - Test on the latest versions of Chrome, Firefox, Safari, and Edge
- - Use Chrome device mode to simulate mobile environments
- - Confirm consistent appearance and behaviour across browsers
-
-
- Bug testing
- When a bug is fixed:
-
- - Reproduce the issue using the main branch.
- - Verify the fix in the pull request branch.
- - Retest the component across all relevant areas.
-
- Confirm the issue no longer occurs.
- Reporting
-
- - Document updated test results, findings, and screenshots in the pull request comments
- - Log newly discovered issues in GitHub
-
-
diff --git a/docs/src/pages/get-started/roadmap.astro b/docs/src/pages/get-started/roadmap.astro
deleted file mode 100644
index 070656eab6..0000000000
--- a/docs/src/pages/get-started/roadmap.astro
+++ /dev/null
@@ -1,347 +0,0 @@
----
-/**
- * Get Started - Roadmap
- *
- * High-level roadmap for the design system team's 2026-27 fiscal year.
- * Content adapted from Confluence.
- */
-import DocumentationPageLayout from "../../layouts/DocumentationPageLayout.astro";
----
-
-
- Roadmap
-
- A high-level summary of the work the design system team plans to focus on in the
- 2026-27 Fiscal Year.
-
-
-
- The roadmap is subject to change as we gather new information. We will communicate
- updates to ensure product teams can align and plan their work accordingly.
-
-
-
- For more details on our priorities and day-to-day activities, see our
-
- design system backlog.
-
-
-
- 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.
-
-
- 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.
-
-
- Examples:
-
-
- -
-
Create a mechanism to reliably collect and report adoption rate
-
- -
-
Track upgrade progress against the adoption schedule
-
- -
-
Capture qualitative signals from teams (developer and designer feedback themes)
-
- -
-
Capture end-user feedback where available (citizen or worker satisfaction,
- accessibility and usability feedback)
-
-
-
- Product acceleration enablement
-
- Objective: Provide prescriptive guidance and resources that help teams
- get to screens, prototypes, and working experiences faster using DS 2.0.
-
-
- 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
-
- -
-
Provide contextual starting points for teams using Public form and Workspace
- templates
-
- -
-
Pilot DS 2.0 with teams to generate strong examples to share
-
- -
-
Create and publish migration success stories
-
-
-
- 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.
-
-
- Examples:
-
-
- -
-
Define the initial MCP scope and supported design system resources
-
- -
-
Stand up the MCP server and validate the hosting and maintenance approach
-
- -
-
Test the MCP use in real product workflows and capture gaps to address
-
- -
-
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.
-
-
- Examples:
-
-
- -
-
Define what "official Vue support" means
-
- -
-
Outline the minimum supportable scope
-
- -
-
Identify implications for documentation, maintenance, testing, and support
-
-
-
- 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:
-
-
- -
-
Build the review, revise, resubmit feature
-
-
-
- Examples and pattern maturity
-
- Objective: Expand and refine examples and position them as adaptable reusable
- patterns that teams can apply with confidence.
-
-
- Benefit: Improves self-serve success and product consistency, reducing
- implementation variance and support demand over time.
-
-
- Examples:
-
-
- -
-
Continue expanding and refining examples
-
- -
-
Show how components and examples combine into larger contexts and workflows
-
-
-
- Library packaging and tech stack upgrades
-
- Objective: Reduce friction in how design system assets are bundled and
- adopted across libraries and update important tech stacks.
-
-
- Benefit: Lowers setup and upgrade complexity, and keeps the design system
- up to date with the latest supported versions.
-
-
- Examples:
-
-
- -
-
Improve how code libraries are bundled together (React, web components, tokens)
-
- -
-
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.
-
-
- Documentation and communications improvements
-
- Objective: Improve how teams access and understand design system guidance,
- and communicate design system value areas like accessibility more clearly.
-
-
- Benefit: Increases trust, improves reuse, and supports self-serve adoption
- by making guidance easier to consume and share.
-
-
- Examples:
-
-
- -
-
Add markdown file download to website documentation
-
- -
-
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.
-
-
- 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:
-
-
-
- -
-
Focus migration support on late adopters facing systemic barriers to upgrading
-
-
-
diff --git a/docs/src/pages/index.astro b/docs/src/pages/index.astro
index 1c720ba5a7..d925a33b14 100644
--- a/docs/src/pages/index.astro
+++ b/docs/src/pages/index.astro
@@ -76,26 +76,6 @@ import CardLite from '../components/CardLite.astro';
/>
-
- Research tools
-
- Conduct research with your users to validate your design decisions. Test your assumptions, gather insights, and ensure your service meets real user needs.
-
-
- Understand your service
@@ -103,24 +83,44 @@ import CardLite from '../components/CardLite.astro';
Research tools
+
+ Conduct research with your users to validate your design decisions. Test your assumptions, gather insights, and ensure your service meets real user needs.
+
+
+
@@ -28,6 +30,7 @@ const navCategories = await getNavCategories();
client:only="react"
initialSection="components"
categories={navCategories}
+ getStartedNav={getStartedNav}
/>
diff --git a/docs/src/scripts/aliases-to-redirects.mjs b/docs/src/scripts/aliases-to-redirects.mjs
new file mode 100644
index 0000000000..b8cb3254f2
--- /dev/null
+++ b/docs/src/scripts/aliases-to-redirects.mjs
@@ -0,0 +1,114 @@
+/**
+ * Build a redirects map from `aliases` frontmatter on entries in the
+ * examples and productTypes content collections.
+ *
+ * Each alias on an entry becomes a redirect from `/examples/${alias}` to
+ * the entry's canonical URL. Both collections route under `/examples/`,
+ * so product-type aliases (none today, but supported) also redirect there
+ * via the [family] route.
+ *
+ * Imported from astro.config.mjs at config-load time. Sync fs reads keep
+ * the function callable before the content collection pipeline runs.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DOCS_ROOT = join(__dirname, "../..");
+
+const COLLECTION_ROOTS = [
+ join(DOCS_ROOT, "src/content/examples"),
+ join(DOCS_ROOT, "src/content/productTypes"),
+];
+
+/**
+ * Minimal YAML frontmatter parser. Mirrors the parser in
+ * build-search-index.ts. Only handles the subset our content uses:
+ * scalar values and list-of-strings for `aliases`.
+ */
+function parseFrontmatter(content) {
+ const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+ if (!match) return {};
+
+ const result = {};
+ let currentKey = null;
+ let currentArray = null;
+
+ for (const line of match[1].split("\n")) {
+ const arrayItem = line.match(/^\s+-\s+(.*)/);
+ if (arrayItem && currentArray) {
+ currentArray.push(arrayItem[1].trim());
+ continue;
+ }
+
+ const kv = line.match(/^(\w+):\s*(.*)/);
+ if (!kv) continue;
+
+ if (currentKey && currentArray) {
+ result[currentKey] = currentArray;
+ }
+ currentKey = kv[1];
+ const value = kv[2].trim();
+ if (value === "" || value === "|") {
+ currentArray = [];
+ } else {
+ currentArray = null;
+ result[currentKey] = value.replace(/^["']|["']$/g, "");
+ }
+ }
+
+ if (currentKey && currentArray) {
+ result[currentKey] = currentArray;
+ }
+ return result;
+}
+
+/**
+ * Recursively find every `index.mdx` under a collection root, including
+ * nested entries like `examples/workspace/dashboard/index.mdx`.
+ */
+function findIndexMdx(dir) {
+ const out = [];
+ for (const entry of readdirSync(dir)) {
+ const path = join(dir, entry);
+ if (!statSync(path).isDirectory()) continue;
+ const indexPath = join(path, "index.mdx");
+ try {
+ if (statSync(indexPath).isFile()) out.push(indexPath);
+ } catch {
+ // No index.mdx in this directory; keep recursing.
+ }
+ out.push(...findIndexMdx(path));
+ }
+ return out;
+}
+
+export function buildAliasRedirects() {
+ const redirects = {};
+
+ for (const root of COLLECTION_ROOTS) {
+ try {
+ statSync(root);
+ } catch {
+ continue;
+ }
+
+ for (const file of findIndexMdx(root)) {
+ const fm = parseFrontmatter(readFileSync(file, "utf-8"));
+ if (!Array.isArray(fm.aliases) || fm.aliases.length === 0) continue;
+
+ const slug = relative(root, dirname(file));
+ const target = `/examples/${slug}`;
+
+ for (const alias of fm.aliases) {
+ const from = `/examples/${alias}`;
+ if (from === target) continue;
+ redirects[from] = target;
+ }
+ }
+ }
+
+ return redirects;
+}
diff --git a/docs/src/scripts/build-search-index.ts b/docs/src/scripts/build-search-index.ts
index 3b2258ff69..e6c4137fa8 100644
--- a/docs/src/scripts/build-search-index.ts
+++ b/docs/src/scripts/build-search-index.ts
@@ -8,7 +8,7 @@
*/
import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdirSync } from 'node:fs';
-import { join, basename, dirname } from 'node:path';
+import { join, basename, dirname, relative, sep } from 'node:path';
import { fileURLToPath } from 'node:url';
// Get directory paths relative to this script
@@ -20,6 +20,8 @@ const ROOT = join(__dirname, '../..');
// Content directories
const COMPONENTS_DIR = join(ROOT, 'src/content/components');
const EXAMPLES_DIR = join(ROOT, 'src/content/examples');
+const GET_STARTED_DIR = join(ROOT, 'src/content/get-started');
+const PRODUCT_TYPES_DIR = join(ROOT, 'src/content/productTypes');
const OUTPUT_FILE = join(ROOT, 'public/search-index.json');
// ============================================================================
@@ -43,15 +45,26 @@ interface ExampleEntry {
title: string;
description?: string;
status: string;
- categories: string[];
+ size: string; // "interaction" | "section" | "page" | "task" | "product"
+ productType?: string; // "workspace" | "public-form"
tags: string[];
- components: string[]; // What components this example uses
- scale: string;
- userType: string;
+ components: string[]; // What components this example uses
+ aliases: string[]; // Secondary slugs that surface this entry in search
slug: string;
}
-type SearchEntry = ComponentEntry | ExampleEntry;
+interface PageEntry {
+ type: 'page';
+ id: string;
+ title: string;
+ description?: string;
+ status: string;
+ category: string; // High-level grouping for filter UI ("get started")
+ tags: string[]; // Synthesized from section so queries like "developer setup" hit
+ slug: string; // URL path without leading slash (e.g. "get-started/developers/setup")
+}
+
+type SearchEntry = ComponentEntry | ExampleEntry | PageEntry;
// ============================================================================
// Frontmatter Parsing
@@ -155,6 +168,20 @@ function extractFirstParagraph(body: string): string | undefined {
return paragraph || undefined;
}
+function isHidden(frontmatter: Record): boolean {
+ return String(frontmatter.hidden ?? '').toLowerCase() === 'true';
+}
+
+function normalizeDescription(value: string | undefined): string | undefined {
+ if (!value) return undefined;
+
+ const withoutHtml = value.replace(/<[^>]+>/g, ' ');
+ const withoutMarkdownLinks = withoutHtml.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '$1');
+ const normalized = withoutMarkdownLinks.replace(/\s+/g, ' ').trim();
+
+ return normalized || undefined;
+}
+
// ============================================================================
// File Processing
// ============================================================================
@@ -170,7 +197,7 @@ function processComponent(filePath: string): ComponentEntry | null {
const id = basename(filePath, '.mdx');
// Skip hidden components
- if (frontmatter.hidden === true || frontmatter.hidden === 'true') {
+ if (isHidden(frontmatter)) {
return null;
}
@@ -178,7 +205,9 @@ function processComponent(filePath: string): ComponentEntry | null {
type: 'component',
id,
name: String(frontmatter.name || id),
- description: frontmatter.description ? String(frontmatter.description) : undefined,
+ description: normalizeDescription(
+ frontmatter.description ? String(frontmatter.description) : undefined,
+ ),
status: String(frontmatter.status || 'stable'),
category: String(frontmatter.category || 'utilities'),
tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : [],
@@ -193,15 +222,27 @@ function processComponent(filePath: string): ComponentEntry | null {
/**
* Process an example MDX file into a search entry.
* Examples live in subdirectories: examples/[name]/index.mdx
+ * or nested: examples/[family]/[page]/index.mdx
+ *
+ * The slug is derived from the path relative to EXAMPLES_DIR so that nested
+ * entries (workspace/dashboard, etc.) get path-shaped slugs matching Astro's
+ * content-collection routing. Frontmatter `id` is kept for stable cross-
+ * references but no longer drives the URL.
*/
function processExample(filePath: string): ExampleEntry | null {
try {
const content = readFileSync(filePath, 'utf-8');
const { frontmatter, body } = parseFrontmatter(content);
- // Get ID from directory name
- const dirName = basename(dirname(filePath));
- const id = String(frontmatter.id || dirName);
+ // Skip hidden examples
+ if (isHidden(frontmatter)) {
+ return null;
+ }
+
+ // Slug = path within EXAMPLES_DIR (e.g., "workspace/dashboard", "start-page").
+ // Use forward slashes on every OS so URLs are consistent.
+ const slug = relative(EXAMPLES_DIR, dirname(filePath)).split(sep).join('/');
+ const id = String(frontmatter.id || basename(dirname(filePath)));
// Extract description from body if not in frontmatter
const description = frontmatter.description
@@ -212,18 +253,20 @@ function processExample(filePath: string): ExampleEntry | null {
type: 'example',
id,
title: String(frontmatter.title || id),
- description,
+ description: normalizeDescription(description),
status: String(frontmatter.status || 'published'),
- categories: Array.isArray(frontmatter.categories)
- ? frontmatter.categories.map(String)
- : [],
+ size: String(frontmatter.size || 'section'),
+ productType: frontmatter.productType
+ ? String(frontmatter.productType)
+ : undefined,
tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : [],
components: Array.isArray(frontmatter.components)
? frontmatter.components.map(String)
: [],
- scale: String(frontmatter.scale || 'interaction'),
- userType: String(frontmatter.userType || 'both'),
- slug: String(frontmatter.slug || id),
+ aliases: Array.isArray(frontmatter.aliases)
+ ? frontmatter.aliases.map(String)
+ : [],
+ slug,
};
} catch (error) {
console.error(`Error processing example ${filePath}:`, error);
@@ -231,6 +274,110 @@ function processExample(filePath: string): ExampleEntry | null {
}
}
+/**
+ * Synthesize search tags from a Get Started section.
+ * Includes the singular form so a query like "developer setup" matches
+ * a page whose section is "developers".
+ */
+function tagsForSection(section: string): string[] {
+ const singular: Record = {
+ designers: 'designer',
+ developers: 'developer',
+ };
+ const tags = [section];
+ if (singular[section]) tags.push(singular[section]);
+ return tags;
+}
+
+/**
+ * Process a Get Started MDX file into a search entry.
+ * The collection root holds the index page; nested folders are URL segments.
+ */
+function processGetStartedPage(filePath: string): PageEntry | null {
+ try {
+ const content = readFileSync(filePath, 'utf-8');
+ const { frontmatter } = parseFrontmatter(content);
+
+ // Derive ID from path relative to the collection root, minus the extension.
+ // e.g. "developers/setup.mdx" -> "developers/setup"
+ // Normalize backslashes to forward slashes so Windows-built indexes still produce valid URLs.
+ const relPath = filePath
+ .slice(GET_STARTED_DIR.length + 1)
+ .replace(/\.mdx$/, '')
+ .replace(/\\/g, '/');
+
+ // The index entry lives at /get-started, every other entry under /get-started/.
+ const slug = relPath === 'index' ? 'get-started' : `get-started/${relPath}`;
+
+ const section = String(frontmatter.section || '');
+
+ return {
+ type: 'page',
+ id: String(frontmatter.id || relPath),
+ title: String(frontmatter.title || relPath),
+ description: frontmatter.description ? String(frontmatter.description) : undefined,
+ status: String(frontmatter.status || 'published'),
+ category: 'get started',
+ tags: section ? tagsForSection(section) : [],
+ slug,
+ };
+ } catch (error) {
+ console.error(`Error processing get-started page ${filePath}:`, error);
+ return null;
+ }
+}
+
+/**
+ * Process a productType MDX file into a search entry.
+ *
+ * ProductTypes are the "starting points" for each kind of digital service
+ * (workspace, public-form). Their overview pages live at /examples/[slug]/
+ * via the [family]/index.astro route, so we synthesize them into the same
+ * search shape as page-scale examples with size="product". This replaces
+ * the hand-authored stub entries that previously lived in examples/.
+ */
+function processProductType(filePath: string): ExampleEntry | null {
+ try {
+ const content = readFileSync(filePath, 'utf-8');
+ const { frontmatter, body } = parseFrontmatter(content);
+
+ const slug = relative(PRODUCT_TYPES_DIR, dirname(filePath))
+ .split(sep)
+ .join('/');
+ const id = String(frontmatter.id || slug);
+
+ // Summary may contain inline HTML formatting (br, span) for the overview
+ // page. Take the prose before the first tag — enough for search results,
+ // which truncate to ~80 chars anyway, and safer than regex-stripping.
+ const description = frontmatter.summary
+ ? String(frontmatter.summary).split('<')[0].trim()
+ : frontmatter.description
+ ? String(frontmatter.description)
+ : extractFirstParagraph(body);
+
+ return {
+ type: 'example',
+ id,
+ title: String(frontmatter.title || id),
+ description,
+ status: String(frontmatter.status || 'published'),
+ size: 'product',
+ productType: undefined,
+ tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : [],
+ components: Array.isArray(frontmatter.components)
+ ? frontmatter.components.map(String)
+ : [],
+ aliases: Array.isArray(frontmatter.aliases)
+ ? frontmatter.aliases.map(String)
+ : [],
+ slug,
+ };
+ } catch (error) {
+ console.error(`Error processing productType ${filePath}:`, error);
+ return null;
+ }
+}
+
/**
* Recursively find all MDX files in a directory.
*/
@@ -288,6 +435,32 @@ function main() {
}
console.log(` Found ${exampleFiles.length} files, indexed ${entries.length - exampleCount} examples`);
+ // Process Get Started pages
+ console.log('Processing get-started pages...');
+ const getStartedFiles = findMdxFiles(GET_STARTED_DIR);
+ const getStartedCount = entries.length;
+ for (const file of getStartedFiles) {
+ const entry = processGetStartedPage(file);
+ if (entry) {
+ entries.push(entry);
+ }
+ }
+ console.log(` Found ${getStartedFiles.length} files, indexed ${entries.length - getStartedCount} pages`);
+
+ // Process productTypes (workspace, public-form, etc.) — surfaced as
+ // size:product overview entries so the same Cmd-K query that finds a
+ // page-scale entry also finds the introductory page for its product type.
+ console.log('Processing productTypes...');
+ const productTypeFiles = findMdxFiles(PRODUCT_TYPES_DIR);
+ const productTypeCountBefore = entries.length;
+ for (const file of productTypeFiles) {
+ const entry = processProductType(file);
+ if (entry) {
+ entries.push(entry);
+ }
+ }
+ console.log(` Found ${productTypeFiles.length} files, indexed ${entries.length - productTypeCountBefore} productTypes`);
+
// Ensure public directory exists
const publicDir = dirname(OUTPUT_FILE);
if (!existsSync(publicDir)) {
diff --git a/docs/src/scripts/extract-api.ts b/docs/src/scripts/extract-api.ts
index 2c7f7cadee..6eb01bdedc 100644
--- a/docs/src/scripts/extract-api.ts
+++ b/docs/src/scripts/extract-api.ts
@@ -15,6 +15,7 @@
import * as fs from "fs";
import * as path from "path";
import { fileURLToPath } from "url";
+import * as ts from "typescript";
// =============================================================================
// Configuration
@@ -31,6 +32,10 @@ const UI_COMPONENTS_PATH = path.join(
"libs/web-components/src/components",
);
const OUTPUT_PATH = path.join(WORKSPACE_ROOT, "docs/generated/component-apis");
+const DOCS_COMPONENT_CONTENT_PATH = path.join(
+ WORKSPACE_ROOT,
+ "docs/src/content/components",
+);
// =============================================================================
// Output Types (matching content model spec)
@@ -51,20 +56,36 @@ interface ExtractedEvent {
name: string;
type: string;
description: string; // Empty - filled by human content
- frameworks: ("react" | "angular" | "web-component")[];
+ frameworks: ("react" | "angular" | "webComponents")[];
}
interface ExtractedSlot {
name: string;
+ type?: string;
description: string; // Empty - filled by human content
+ required?: boolean;
}
interface ExtractedComponentAPI {
componentSlug: string;
extractedFrom: string;
- props: ExtractedProp[];
- events: ExtractedEvent[];
- slots: ExtractedSlot[];
+ frameworks: {
+ react: {
+ props: ExtractedProp[];
+ events: ExtractedEvent[];
+ slots: ExtractedSlot[];
+ };
+ angular: {
+ props: ExtractedProp[];
+ events: ExtractedEvent[];
+ slots: ExtractedSlot[];
+ };
+ webComponents: {
+ props: ExtractedProp[];
+ events: ExtractedEvent[];
+ slots: ExtractedSlot[];
+ };
+ };
}
// =============================================================================
@@ -90,6 +111,119 @@ interface ParsedPropRaw {
deprecated: boolean;
}
+interface WrapperExtraction {
+ found: boolean;
+ props: ExtractedProp[];
+ events: ExtractedEvent[];
+ slotDescriptions: Record;
+ slotNameAliases: Record;
+ slotRequired: Record;
+}
+
+const INTERNAL_PROP_NAMES = new Set(["publicformsummaryorder", "filterablecontext", "version"]);
+const INTERNAL_SLOT_NAMES = new Set(["version"]);
+const INTERNAL_EVENT_NAMES = new Set(["_revealChange", "_update"]);
+
+const DOCS_EXCLUDED_COMPONENTS = new Set(["focus-trap", "form-stepper", "scrollable"]);
+const DOCS_FORCED_COMPONENTS = new Set(["table-sort-header"]);
+const WRAPPER_COMPONENT_ALIASES: Record = {
+ "temporary-notification": "temporary-notification-ctrl",
+};
+const WEB_COMPONENT_INTERNAL_EVENT_OVERRIDES: Record> = {
+ "work-side-menu-group": new Set(["_hoverItem"]),
+ "work-side-menu-item": new Set([
+ "_blurItem",
+ "_desktopPopoverClose",
+ "_desktopPopoverOpen",
+ "_hoverItem",
+ "_itemCurrent",
+ "_mobilePopoverClose",
+ "_mobilePopoverOpen",
+ "_mountItem",
+ "_navigate",
+ ]),
+};
+const WEB_COMPONENT_EVENT_TYPE_OVERRIDES: Record> = {
+ dropdown: {
+ _change: "CustomEvent<{ name?: string; value?: string; event: Event }>",
+ },
+ "file-upload-input": {
+ _selectFile: "CustomEvent<{ file: File; event: Event }>",
+ },
+};
+const SLOT_TYPE_OVERRIDES: Record<
+ string,
+ Partial>>
+> = {
+ footer: {
+ react: {
+ nav: "GoabAppFooterNavSection",
+ meta: "GoabAppFooterMetaSection",
+ },
+ angular: {
+ nav: "GoabAppFooterNavSection",
+ meta: "GoabAppFooterMetaSection",
+ },
+ webComponents: {
+ nav: "goa-app-footer-nav-section",
+ meta: "goa-app-footer-meta-section",
+ },
+ },
+};
+const ALLOW_INTERNAL_PROP_BY_COMPONENT: Record> = {
+ "microsite-header": new Set(["version"]),
+};
+
+function shouldSkipInternalProp(componentName: string, propName: string): boolean {
+ const normalizedComponentName = toKebabCase(componentName);
+ const normalizedName = propName.toLowerCase();
+ if (ALLOW_INTERNAL_PROP_BY_COMPONENT[normalizedComponentName]?.has(normalizedName)) {
+ return false;
+ }
+ return INTERNAL_PROP_NAMES.has(normalizedName);
+}
+
+function shouldAllowInternalProp(componentName: string, propName: string): boolean {
+ const normalizedComponentName = toKebabCase(componentName);
+ return Boolean(
+ ALLOW_INTERNAL_PROP_BY_COMPONENT[normalizedComponentName]?.has(propName.toLowerCase()),
+ );
+}
+
+function isInternalPropName(propName: string): boolean {
+ return INTERNAL_PROP_NAMES.has(propName.toLowerCase());
+}
+
+function isStandardV1V2VersionProp(prop: ExtractedProp | undefined): boolean {
+ if (!prop || prop.name.toLowerCase() !== "version") return false;
+
+ const values = (prop.values || []).map((value) => String(value).replace(/['"]/g, "").trim());
+ if (values.length === 2 && values.includes("1") && values.includes("2")) {
+ return true;
+ }
+
+ const normalizedType = String(prop.type || "")
+ .replace(/['"]/g, "")
+ .replace(/\s+/g, "");
+
+ return normalizedType === "1|2";
+}
+
+function specializeAngularValuePropFromReact(
+ angularProps: ExtractedProp[],
+ reactProps: ExtractedProp[],
+): void {
+ const angularValueProp = angularProps.find((prop) => prop.name === "value");
+ const reactValueProp = reactProps.find((prop) => prop.name === "value");
+
+ if (!angularValueProp || !reactValueProp) return;
+ if (angularValueProp.type !== "unknown | null | undefined") return;
+ if (!reactValueProp.type || reactValueProp.type === "unknown") return;
+
+ angularValueProp.type = reactValueProp.type;
+ angularValueProp.values = reactValueProp.values;
+}
+
// =============================================================================
// JSDoc Parser
// =============================================================================
@@ -153,11 +287,35 @@ function parseJSDocContent(rawComment: string): {
const description = cleaned
.replace(/@required\s*/gi, "")
.replace(/@internal\s*/gi, "")
+ .replace(/@deprecated\s*/gi, "")
.trim();
return { description, required, internal, deprecated };
}
+function parseDescriptionFromJSDoc(rawComment: string | undefined): string {
+ if (!rawComment) return "";
+ const { description } = parseJSDocContent(rawComment);
+ return description;
+}
+
+function extractDefaultFromDescription(description: string): {
+ description: string;
+ defaultValue: string | null;
+} {
+ const defaultMatch = description.match(/@default\s+([^@]+)/i);
+ const defaultValue = defaultMatch ? defaultMatch[1].trim().replace(/^["']|["']$/g, "") : null;
+ const cleanDescription = description.replace(/@default\s+([^@]+)/gi, "").trim();
+ return {
+ description: cleanDescription,
+ defaultValue,
+ };
+}
+
+function isReadonlyDescription(description: string): boolean {
+ return /read[ -]?only\b|set by the component\b/i.test(description);
+}
+
// =============================================================================
// Svelte Parser
// =============================================================================
@@ -274,18 +432,11 @@ function extractProps(
typeAliases: Map,
): ParsedPropRaw[] {
const props: ParsedPropRaw[] = [];
+ const customElementPropAttributeMap = extractCustomElementPropAttributeMap(content);
// Build JSDoc map for descriptions
const jsDocMap = buildJSDocMap(content);
- // Internal props to skip (used by public forms system, not useful for devs)
- const internalProps = new Set([
- "publicformsummaryorder",
- "action",
- "actionarg",
- "actionargs",
- ]);
-
// Match: export let propName: Type = defaultValue;
const propMatches = content.matchAll(
/export\s+let\s+(\w+)(?:\s*:\s*([^=;]+?))?(?:\s*=\s*([^;]+?))?;/g,
@@ -293,16 +444,18 @@ function extractProps(
for (const match of propMatches) {
const rawName = match[1];
- let type = match[2]?.trim() || "any";
const defaultStr = match[3]?.trim();
+ let type = match[2]?.trim() || inferTypeFromDefault(defaultStr);
// Skip private props (starting with _)
if (rawName.startsWith("_")) continue;
- // Skip internal props
- if (internalProps.has(rawName.toLowerCase())) continue;
+ // Keep `version` on Web Component docs; wrappers are filtered later.
+ if (rawName.toLowerCase() !== "version" && shouldSkipInternalProp(componentName, rawName)) {
+ continue;
+ }
- const name = toReactPropName(rawName);
+ const name = customElementPropAttributeMap.get(rawName) || rawName.toLowerCase();
let typeLabel: string | undefined;
let values: string[] | undefined;
@@ -317,8 +470,8 @@ function extractProps(
// Handle special types
if (type.includes("GoAIconType") || type.includes("GoaIconType")) {
- typeLabel = "GoAIconType";
- type = "GoAIconType";
+ typeLabel = "GoabIconType";
+ type = "GoabIconType";
} else if (type === "Spacing" || type.includes("Spacing")) {
typeLabel = "Spacing";
type = "Spacing";
@@ -382,12 +535,23 @@ function extractProps(
// Get JSDoc info from map (description + required flag)
const jsDocInfo = jsDocMap.get(rawName);
- // Skip @internal props — not for public API docs
- if (jsDocInfo?.internal) continue;
+ // Keep Svelte `version` visible in Web Component docs.
+ if (
+ jsDocInfo?.internal &&
+ rawName.toLowerCase() !== "version" &&
+ !shouldAllowInternalProp(componentName, rawName)
+ ) {
+ continue;
+ }
+
+ // Skip @deprecated props — not for public API docs
+ if (jsDocInfo?.deprecated) continue;
const description = jsDocInfo?.description || "";
- // Use @required from JSDoc if present, otherwise fall back to checking if no default value
- const isRequired = jsDocInfo?.required || defaultStr === undefined;
+ const isReadonly = isReadonlyDescription(description);
+ // Use @required from JSDoc if present, otherwise fall back to checking if no default value.
+ // Read-only, component-managed values should not be presented as consumer-required props.
+ const isRequired = Boolean(jsDocInfo?.required) || (!isReadonly && defaultStr === undefined);
props.push({
name,
@@ -406,12 +570,28 @@ function extractProps(
return props;
}
+function extractCustomElementPropAttributeMap(content: string): Map {
+ const map = new Map();
+ const optionsTagMatch = content.match(/();
@@ -435,17 +615,6 @@ function extractEvents(content: string): string[] {
}
}
- // Pattern 3: _rootEl?.dispatchEvent(new CustomEvent("_eventName", ...))
- const rootElMatches = content.matchAll(
- /_rootEl\??\s*\.?\s*dispatchEvent\s*\(\s*new\s+CustomEvent\s*\(\s*["']([^"']+)["']/g,
- );
- for (const match of rootElMatches) {
- const eventName = match[1];
- if (!eventName.includes("::")) {
- eventNames.add(eventName);
- }
- }
-
return Array.from(eventNames);
}
@@ -463,13 +632,893 @@ function extractSlots(content: string): string[] {
}
}
- // Default slot: or |>[^<]*<\/slot>)/.test(content);
- if (hasDefaultSlot && !seenNames.has("default")) {
- slotNames.unshift("default");
+ return slotNames;
+}
+
+function parseWrapperPropValues(type: string): string[] | undefined {
+ if (!type.includes("|")) return undefined;
+ const values = type
+ .split("|")
+ .map((v) => v.trim().replace(/['"]/g, ""))
+ .filter((v) => v.length > 0 && v !== "undefined" && v !== "null");
+ return values.length > 0 ? values : undefined;
+}
+
+function inferTypeFromDefault(defaultValue: string | undefined): string {
+ if (!defaultValue) return "any";
+
+ const trimmed = defaultValue.trim();
+ if (trimmed === "true" || trimmed === "false") return "boolean";
+ if (!isNaN(Number(trimmed))) return "number";
+ if (/^["'`]/.test(trimmed)) return "string";
+ if (trimmed.startsWith("[")) return "unknown[]";
+ if (trimmed.startsWith("{")) return "Record";
+
+ return "any";
+}
+
+function normalizeName(value: string): string {
+ return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function getMatchingSlotName(propName: string, slotNames: string[]): string | null {
+ if (propName === "children") {
+ return "default";
}
- return slotNames;
+ const normalizedPropName = normalizeName(propName);
+ const directMatch =
+ slotNames.find((slotName) => normalizeName(slotName) === normalizedPropName) ?? null;
+ if (directMatch) return directMatch;
+
+ // Common wrapper naming pattern: slot "account" exposed as prop "accountContent".
+ const contentSuffixMatch = propName.match(/^(.+?)content$/i);
+ if (contentSuffixMatch?.[1]) {
+ const baseName = normalizeName(contentSuffixMatch[1]);
+ return slotNames.find((slotName) => normalizeName(slotName) === baseName) ?? null;
+ }
+
+ return null;
+}
+
+interface ReactCallbackAliasInfo {
+ typeParam?: string;
+ defaultTypeArg?: string;
+ detailType: string;
+}
+
+interface ReactInterfaceInfo {
+ name: string;
+ exported: boolean;
+ extendsNames: string[];
+ declaration: ts.InterfaceDeclaration;
+}
+
+function getTypeReferenceName(typeNode: ts.TypeReferenceNode, sourceFile: ts.SourceFile): string {
+ const typeName = typeNode.typeName.getText(sourceFile);
+ return typeName.split(".").pop() || typeName;
+}
+
+function createTsSourceFile(filePath: string, content: string): ts.SourceFile {
+ const scriptKind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+ return ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, scriptKind);
+}
+
+function getNodeDecorators(node: ts.Node): readonly ts.Decorator[] {
+ if (typeof ts.canHaveDecorators === "function" && ts.canHaveDecorators(node)) {
+ return ts.getDecorators(node) ?? [];
+ }
+
+ const legacyDecorators = (node as { decorators?: readonly ts.Decorator[] }).decorators;
+ return legacyDecorators ?? [];
+}
+
+function getDecoratorCall(node: ts.Node, decoratorName: string): ts.CallExpression | null {
+ for (const decorator of getNodeDecorators(node)) {
+ const expression = decorator.expression;
+ if (ts.isCallExpression(expression) && ts.isIdentifier(expression.expression)) {
+ if (expression.expression.text === decoratorName) {
+ return expression;
+ }
+ }
+
+ if (ts.isIdentifier(expression) && expression.text === decoratorName) {
+ return null;
+ }
+ }
+
+ return null;
+}
+
+function isAngularInputRequired(inputDecoratorCall: ts.CallExpression | null): boolean {
+ if (!inputDecoratorCall || inputDecoratorCall.arguments.length === 0) return false;
+
+ const firstArg = inputDecoratorCall.arguments[0];
+ if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return false;
+
+ const requiredProp = firstArg.properties.find((prop) => {
+ if (!ts.isPropertyAssignment(prop)) return false;
+ if (ts.isIdentifier(prop.name)) return prop.name.text === "required";
+ if (ts.isStringLiteral(prop.name)) return prop.name.text === "required";
+ return false;
+ });
+
+ if (!requiredProp || !ts.isPropertyAssignment(requiredProp)) return false;
+
+ return requiredProp.initializer.kind === ts.SyntaxKind.TrueKeyword;
+}
+
+function hasDecorator(node: ts.Node, decoratorName: string): boolean {
+ for (const decorator of getNodeDecorators(node)) {
+ const expression = decorator.expression;
+ if (ts.isCallExpression(expression) && ts.isIdentifier(expression.expression)) {
+ if (expression.expression.text === decoratorName) {
+ return true;
+ }
+ }
+
+ if (ts.isIdentifier(expression) && expression.text === decoratorName) {
+ return true;
+ }
+ }
+
+ return false;
+}
+
+function parseReactInterfaces(content: string, filePath: string): Map {
+ const interfaces = new Map();
+ const sourceFile = createTsSourceFile(filePath, content);
+
+ for (const statement of sourceFile.statements) {
+ if (!ts.isInterfaceDeclaration(statement)) continue;
+
+ const name = statement.name.text;
+ const exported = statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+ const extendsNames =
+ statement.heritageClauses
+ ?.filter((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword)
+ .flatMap((clause) =>
+ clause.types
+ .map((typeNode) => typeNode.expression.getText(sourceFile))
+ .map((value) => value.split(".").pop() || value)
+ .filter(Boolean),
+ ) ?? [];
+
+ interfaces.set(name, {
+ name,
+ exported,
+ extendsNames,
+ declaration: statement,
+ });
+ }
+
+ return interfaces;
+}
+
+function resolvePrimaryReactPropsInterface(
+ componentName: string,
+ interfaces: Map,
+): string | null {
+ const componentPart = capitalize(toCamelCase(componentName));
+ const candidates = [`Goab${componentPart}Props`, `GoA${componentPart}Props`];
+
+ for (const name of candidates) {
+ const match = interfaces.get(name);
+ if (match?.exported) return name;
+ }
+
+ for (const name of candidates) {
+ if (interfaces.has(name)) return name;
+ }
+
+ for (const info of interfaces.values()) {
+ if (info.exported && /^(?:Goab|GoA)\w+Props$/.test(info.name)) {
+ return info.name;
+ }
+ }
+
+ for (const info of interfaces.values()) {
+ if (/^(?:Goab|GoA)\w+Props$/.test(info.name)) {
+ return info.name;
+ }
+ }
+
+ return null;
+}
+
+function collectReactInterfaceMembers(
+ interfaceName: string,
+ interfaces: Map,
+ sourceFile: ts.SourceFile,
+ visited: Set = new Set(),
+): ts.TypeElement[] {
+ if (visited.has(interfaceName)) return [];
+ visited.add(interfaceName);
+
+ const info = interfaces.get(interfaceName);
+ if (!info) return [];
+
+ const inheritedMembers = info.extendsNames.flatMap((baseName) =>
+ collectReactInterfaceMembers(baseName, interfaces, sourceFile, visited),
+ );
+
+ return [...inheritedMembers, ...info.declaration.members];
+}
+
+function getFunctionLikeFirstParameterType(
+ fn: ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression,
+): ts.TypeNode | null {
+ return fn.parameters[0]?.type ?? null;
+}
+
+function resolvePrimaryReactComponentParameterType(
+ componentName: string,
+ sourceFile: ts.SourceFile,
+): ts.TypeNode | null {
+ const componentPart = capitalize(toCamelCase(componentName));
+ const candidates = [`Goab${componentPart}`, `GoA${componentPart}`];
+
+ for (const statement of sourceFile.statements) {
+ if (
+ ts.isFunctionDeclaration(statement) &&
+ statement.name &&
+ candidates.includes(statement.name.text) &&
+ statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+ ) {
+ return getFunctionLikeFirstParameterType(statement);
+ }
+
+ if (
+ ts.isVariableStatement(statement) &&
+ statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+ ) {
+ for (const declaration of statement.declarationList.declarations) {
+ if (!ts.isIdentifier(declaration.name) || !candidates.includes(declaration.name.text)) continue;
+ if (!declaration.initializer) continue;
+
+ if (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer)) {
+ return getFunctionLikeFirstParameterType(declaration.initializer);
+ }
+ }
+ }
+ }
+
+ return null;
+}
+
+function collectReactTypeNodeMembers(
+ typeNode: ts.TypeNode | null,
+ interfaces: Map,
+ sourceFile: ts.SourceFile,
+ visitedTypeRefs: Set = new Set(),
+): ts.TypeElement[] {
+ if (!typeNode) return [];
+
+ if (ts.isParenthesizedTypeNode(typeNode)) {
+ return collectReactTypeNodeMembers(typeNode.type, interfaces, sourceFile, visitedTypeRefs);
+ }
+
+ if (ts.isIntersectionTypeNode(typeNode)) {
+ return typeNode.types.flatMap((memberType) =>
+ collectReactTypeNodeMembers(memberType, interfaces, sourceFile, visitedTypeRefs),
+ );
+ }
+
+ if (ts.isTypeLiteralNode(typeNode)) {
+ return [...typeNode.members];
+ }
+
+ if (ts.isTypeReferenceNode(typeNode)) {
+ const typeName = getTypeReferenceName(typeNode, sourceFile);
+ if (visitedTypeRefs.has(typeName)) return [];
+ visitedTypeRefs.add(typeName);
+ return collectReactInterfaceMembers(typeName, interfaces, sourceFile);
+ }
+
+ return [];
+}
+
+function hasReactMarginsInHierarchy(
+ interfaceName: string,
+ interfaces: Map,
+ visited: Set = new Set(),
+): boolean {
+ if (visited.has(interfaceName)) return false;
+ visited.add(interfaceName);
+
+ const info = interfaces.get(interfaceName);
+ if (!info) return false;
+
+ if (info.extendsNames.includes("Margins")) {
+ return true;
+ }
+
+ return info.extendsNames.some((baseName) =>
+ hasReactMarginsInHierarchy(baseName, interfaces, visited),
+ );
+}
+
+function extractReactCallbackAliases(sourceFile: ts.SourceFile): Map {
+ const aliases = new Map();
+ for (const statement of sourceFile.statements) {
+ if (!ts.isTypeAliasDeclaration(statement)) continue;
+ if (!ts.isFunctionTypeNode(statement.type)) continue;
+
+ const aliasName = statement.name.text;
+ const typeParam = statement.typeParameters?.[0]?.name.text;
+ const defaultTypeArg = statement.typeParameters?.[0]?.default?.getText(sourceFile)?.trim();
+ const detailType = cleanType(
+ statement.type.parameters[0]?.type?.getText(sourceFile)?.trim() || "unknown",
+ );
+
+ aliases.set(aliasName, {
+ typeParam,
+ defaultTypeArg,
+ detailType,
+ });
+ }
+
+ return aliases;
+}
+
+function parseGenericAliasUsage(type: string): { alias: string; typeArg?: string } {
+ const aliasMatch = type.match(/^([A-Za-z_]\w*)(?:<\s*([^>]+)\s*>)?$/);
+ if (!aliasMatch) {
+ return { alias: type };
+ }
+
+ return {
+ alias: aliasMatch[1],
+ typeArg: aliasMatch[2]?.trim(),
+ };
+}
+
+function resolveReactCallbackEventType(
+ callbackType: string,
+ callbackAliases: Map,
+): string {
+ if (callbackType.includes("=>")) {
+ return callbackType;
+ }
+
+ const { alias, typeArg } = parseGenericAliasUsage(callbackType);
+ const aliasInfo = callbackAliases.get(alias);
+ if (!aliasInfo) {
+ return callbackType;
+ }
+
+ const toFunctionSignature = (detailType: string) => `(detail: ${detailType}) => void`;
+
+ if (!aliasInfo.typeParam) {
+ return toFunctionSignature(aliasInfo.detailType);
+ }
+
+ const resolvedTypeArg = typeArg || aliasInfo.defaultTypeArg;
+ if (!resolvedTypeArg) {
+ return toFunctionSignature(aliasInfo.detailType);
+ }
+
+ const typeParamPattern = new RegExp(`\\b${aliasInfo.typeParam}\\b`, "g");
+ let resolvedDetailType = aliasInfo.detailType.replace(typeParamPattern, resolvedTypeArg);
+
+ // Keep docs concise when the generic argument matches the alias default.
+ if (aliasInfo.defaultTypeArg && resolvedTypeArg === aliasInfo.defaultTypeArg) {
+ const defaultGenericPattern = new RegExp(`\\<\\s*${escapeRegExp(resolvedTypeArg)}\\s*\\>`, "g");
+ resolvedDetailType = resolvedDetailType.replace(defaultGenericPattern, "");
+ }
+
+ return toFunctionSignature(resolvedDetailType);
+}
+
+function isReactCallbackAliasType(
+ type: string,
+ callbackAliases: Map,
+): boolean {
+ if (type.includes("=>")) {
+ return true;
+ }
+
+ const { alias } = parseGenericAliasUsage(type);
+ return callbackAliases.has(alias);
+}
+
+function isFunctionType(type: string): boolean {
+ return /^\(\s*[^)]*\)\s*=>\s*.+$/.test(type.trim());
+}
+
+function isSlotCarrierType(type: string): boolean {
+ return /React(?:\.[A-Za-z]+)?(?:Node|Element)(?:<.+?>)?|JSX\.Element|TemplateRef\s*<.+?>/.test(type);
+}
+
+function isPureSlotCarrierType(type: string): boolean {
+ const members = type
+ .split("|")
+ .map((part) => part.trim())
+ .filter((part) => part.length > 0 && part !== "null" && part !== "undefined");
+
+ if (members.length === 0) return false;
+ return members.every((part) => isSlotCarrierType(part));
+}
+
+function toEventCallbackType(type: string): string {
+ if (type === "void") {
+ return "() => void";
+ }
+ return `(event: ${type}) => void`;
+}
+
+function dedupeByName(items: T[]): T[] {
+ const seen = new Set();
+ return items.filter((item) => {
+ if (seen.has(item.name)) return false;
+ seen.add(item.name);
+ return true;
+ });
+}
+
+function createEmptyWrapperExtraction(found: boolean = false): WrapperExtraction {
+ return {
+ found,
+ props: [],
+ events: [],
+ slotDescriptions: {},
+ slotNameAliases: {},
+ slotRequired: {},
+ };
+}
+
+function findImmediateJsDocBefore(content: string, markerIndex: number): string | undefined {
+ const beforeMarker = content.slice(0, markerIndex);
+ const start = beforeMarker.lastIndexOf("/**");
+ if (start === -1) return undefined;
+
+ const end = beforeMarker.indexOf("*/", start + 3);
+ if (end === -1) return undefined;
+
+ const tail = beforeMarker.slice(end + 2);
+ if (!/^\s*$/.test(tail)) return undefined;
+
+ return beforeMarker.slice(start + 3, end);
+}
+
+function extractAngularBaseComponentProps(): Map {
+ const baseFile = path.join(
+ WORKSPACE_ROOT,
+ "libs/angular-components/src/lib/components/base.component.ts",
+ );
+
+ if (!fs.existsSync(baseFile)) return new Map();
+
+ const content = fs.readFileSync(baseFile, "utf-8");
+ const sourceFile = createTsSourceFile(baseFile, content);
+ const props = new Map();
+
+ const classDecls = sourceFile.statements.filter(
+ (node): node is ts.ClassDeclaration => ts.isClassDeclaration(node),
+ );
+
+ for (const classDecl of classDecls) {
+ for (const member of classDecl.members) {
+ if (!ts.isPropertyDeclaration(member)) continue;
+ if (!hasDecorator(member, "Input")) continue;
+ if (!member.name || !ts.isIdentifier(member.name)) continue;
+
+ const rawComment = findImmediateJsDocBefore(content, member.getStart(sourceFile));
+ const propName = member.name.text;
+ const inputDecorator = getDecoratorCall(member, "Input");
+ const rawDefault = member.initializer?.getText(sourceFile)?.trim();
+ const rawType = cleanType(member.type?.getText(sourceFile)?.trim() || inferTypeFromDefault(rawDefault));
+ const fullDescription = parseDescriptionFromJSDoc(rawComment);
+ const { description, defaultValue: descriptionDefault } = extractDefaultFromDescription(fullDescription);
+ const defaultValue = descriptionDefault ?? parseDefaultValue(rawDefault);
+
+ props.set(propName, {
+ name: propName,
+ type: rawType,
+ values: parseWrapperPropValues(rawType),
+ required: isAngularInputRequired(inputDecorator),
+ default: defaultValue,
+ description,
+ });
+ }
+ }
+
+ return props;
+}
+
+function findFirstFileByName(root: string, targetName: string): string | null {
+ if (!fs.existsSync(root)) return null;
+ const stack = [root];
+
+ while (stack.length > 0) {
+ const current = stack.pop();
+ if (!current) continue;
+ const entries = fs.readdirSync(current, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(current, entry.name);
+ if (entry.isDirectory()) {
+ stack.push(fullPath);
+ } else if (entry.isFile() && entry.name === targetName) {
+ return fullPath;
+ }
+ }
+ }
+
+ return null;
+}
+
+function escapeRegExp(value: string): string {
+ return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function findFirstFileContaining(
+ root: string,
+ extensions: string[],
+ searchText: string,
+): string | null {
+ if (!fs.existsSync(root)) return null;
+ const stack = [root];
+ const searchPattern = new RegExp(
+ `(?:<\\s*${escapeRegExp(searchText)}(?=[\\s>/])|["']${escapeRegExp(searchText)}["'])`,
+ );
+
+ while (stack.length > 0) {
+ const current = stack.pop();
+ if (!current) continue;
+ const entries = fs.readdirSync(current, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(current, entry.name);
+ if (entry.isDirectory()) {
+ stack.push(fullPath);
+ } else if (
+ entry.isFile() &&
+ extensions.some((ext) => entry.name.endsWith(ext)) &&
+ !entry.name.includes(".spec.")
+ ) {
+ const content = fs.readFileSync(fullPath, "utf-8");
+ if (searchPattern.test(content)) {
+ return fullPath;
+ }
+ }
+ }
+ }
+
+ return null;
+}
+
+function findFirstFileMatchingPattern(
+ root: string,
+ extensions: string[],
+ pattern: RegExp,
+): string | null {
+ if (!fs.existsSync(root)) return null;
+ const stack = [root];
+
+ while (stack.length > 0) {
+ const current = stack.pop();
+ if (!current) continue;
+ const entries = fs.readdirSync(current, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(current, entry.name);
+ if (entry.isDirectory()) {
+ stack.push(fullPath);
+ } else if (
+ entry.isFile() &&
+ extensions.some((ext) => entry.name.endsWith(ext)) &&
+ !entry.name.includes(".spec.")
+ ) {
+ const content = fs.readFileSync(fullPath, "utf-8");
+ if (pattern.test(content)) {
+ return fullPath;
+ }
+ }
+ }
+ }
+
+ return null;
+}
+
+function extractReactWrapperApi(
+ componentName: string,
+ tagName: string,
+ slotNames: string[],
+ wrapperComponentName: string = componentName,
+): WrapperExtraction {
+ const reactRoot = path.join(WORKSPACE_ROOT, "libs/react-components/src/lib");
+ const reactFileNameCandidates = [
+ `${wrapperComponentName}.tsx`,
+ `${wrapperComponentName.replace(/-/g, "")}.tsx`,
+ ];
+ const reactTagPattern = new RegExp(`<\\s*${escapeRegExp(tagName)}(?=[\\s>/])`);
+
+ const reactFile =
+ reactFileNameCandidates.map((name) => findFirstFileByName(reactRoot, name)).find(Boolean) ??
+ findFirstFileMatchingPattern(reactRoot, [".tsx"], reactTagPattern) ??
+ findFirstFileContaining(reactRoot, [".tsx"], tagName);
+
+ if (!reactFile) return createEmptyWrapperExtraction();
+
+ const content = fs.readFileSync(reactFile, "utf-8");
+ const sourceFile = createTsSourceFile(reactFile, content);
+ const interfaces = parseReactInterfaces(content, reactFile);
+ const primaryInterfaceName = resolvePrimaryReactPropsInterface(wrapperComponentName, interfaces);
+ if (!primaryInterfaceName) return createEmptyWrapperExtraction(true);
+
+ const interfaceMembers = collectReactInterfaceMembers(primaryInterfaceName, interfaces, sourceFile);
+ const componentParameterType = resolvePrimaryReactComponentParameterType(
+ wrapperComponentName,
+ sourceFile,
+ );
+ const componentParameterMembers = collectReactTypeNodeMembers(
+ componentParameterType,
+ interfaces,
+ sourceFile,
+ new Set([primaryInterfaceName]),
+ );
+ const reactMembers = [...interfaceMembers, ...componentParameterMembers];
+ const callbackAliases = extractReactCallbackAliases(sourceFile);
+
+ const props: ExtractedProp[] = [];
+ const events: ExtractedEvent[] = [];
+ const slotDescriptions: Record = {};
+ const slotNameAliases: Record = {};
+ const slotRequired: Record = {};
+
+ for (const member of reactMembers) {
+ if (!ts.isPropertySignature(member)) continue;
+ if (!member.name || !ts.isIdentifier(member.name)) continue;
+
+ const rawComment = findImmediateJsDocBefore(content, member.getStart(sourceFile));
+ const propName = member.name.text;
+ const optional = Boolean(member.questionToken);
+ const rawType = cleanType(member.type?.getText(sourceFile)?.trim() || "any");
+ const { internal, deprecated } = parseJSDocContent(rawComment || "");
+
+ // Skip @deprecated props and internal-only props — not for public API docs
+ if (deprecated || (internal && !shouldAllowInternalProp(componentName, propName))) continue;
+
+ const fullDescription = parseDescriptionFromJSDoc(rawComment);
+ const { description, defaultValue } = extractDefaultFromDescription(fullDescription);
+ const isReadonly = isReadonlyDescription(description);
+ const isRequired = !optional && !isReadonly;
+
+ if (shouldSkipInternalProp(componentName, propName)) continue;
+
+ const values = parseWrapperPropValues(rawType);
+ const slotName = getMatchingSlotName(propName, slotNames);
+
+ if (slotName && isSlotCarrierType(rawType)) {
+ if (description) {
+ slotDescriptions[slotName] = description;
+ }
+ slotNameAliases[slotName] = propName;
+ slotRequired[slotName] = Boolean(slotRequired[slotName]) || isRequired;
+ if (isPureSlotCarrierType(rawType)) {
+ continue;
+ }
+ }
+
+ if (
+ propName.startsWith("on") &&
+ (isReactCallbackAliasType(rawType, callbackAliases) || isFunctionType(rawType))
+ ) {
+ events.push({
+ name: propName,
+ type: isReactCallbackAliasType(rawType, callbackAliases)
+ ? resolveReactCallbackEventType(rawType, callbackAliases)
+ : rawType,
+ description,
+ frameworks: ["react"],
+ });
+ continue;
+ }
+
+ props.push({
+ name: propName,
+ type: rawType,
+ values,
+ required: isRequired,
+ default: defaultValue,
+ description,
+ });
+ }
+
+ // Inject inherited margin props when the interface extends Margins
+ if (hasReactMarginsInHierarchy(primaryInterfaceName, interfaces)) {
+ const existingNames = new Set(props.map((p) => p.name));
+ const marginProps: ExtractedProp[] = ["mt", "mr", "mb", "ml"]
+ .filter((name) => !existingNames.has(name))
+ .map((name) => ({
+ name,
+ type: "Spacing",
+ required: false,
+ default: null,
+ description: "",
+ }));
+ props.push(...marginProps);
+ }
+
+ const dedupedProps = dedupeByName(props).sort((a, b) => a.name.localeCompare(b.name));
+ const dedupedEvents = dedupeByName(events).sort((a, b) => a.name.localeCompare(b.name));
+
+ return {
+ found: true,
+ props: dedupedProps,
+ events: dedupedEvents,
+ slotDescriptions,
+ slotNameAliases,
+ slotRequired,
+ };
+}
+
+function extractAngularWrapperApi(
+ componentName: string,
+ tagName: string,
+ slotNames: string[],
+ wrapperComponentName: string = componentName,
+): WrapperExtraction {
+ const angularRoot = path.join(WORKSPACE_ROOT, "libs/angular-components/src/lib/components");
+ const angularSelector = tagName.replace(/^goa-/, "goab-");
+ const angularFileNameCandidates = [
+ `${wrapperComponentName}.ts`,
+ `${wrapperComponentName.replace(/-/g, "")}.ts`,
+ ];
+ const angularSelectorPattern = new RegExp(`selector\\s*:\\s*["']${escapeRegExp(angularSelector)}["']`);
+ const angularTagPattern = new RegExp(`<\\s*${escapeRegExp(tagName)}(?=[\\s>/])`);
+
+ const angularFile =
+ angularFileNameCandidates
+ .map((name) => findFirstFileByName(angularRoot, name))
+ .find(Boolean) ??
+ findFirstFileMatchingPattern(angularRoot, [".ts"], angularSelectorPattern) ??
+ findFirstFileMatchingPattern(angularRoot, [".ts"], angularTagPattern) ??
+ findFirstFileContaining(angularRoot, [".ts"], tagName);
+
+ if (!angularFile) return createEmptyWrapperExtraction();
+
+ const content = fs.readFileSync(angularFile, "utf-8");
+ const sourceFile = createTsSourceFile(angularFile, content);
+
+ const props: ExtractedProp[] = [];
+ const events: ExtractedEvent[] = [];
+ const slotDescriptions: Record = {};
+ const slotNameAliases: Record = {};
+ const slotRequired: Record = {};
+
+ const classDecl = sourceFile.statements.find(
+ (node): node is ts.ClassDeclaration => ts.isClassDeclaration(node) && hasDecorator(node, "Component"),
+ );
+
+ if (!classDecl) return createEmptyWrapperExtraction(true);
+
+ for (const member of classDecl.members) {
+ if (!ts.isPropertyDeclaration(member)) continue;
+ if (!member.name || !ts.isIdentifier(member.name)) continue;
+
+ const inputDecorator = getDecoratorCall(member, "Input");
+ if (!inputDecorator && !hasDecorator(member, "Input")) continue;
+
+ const rawComment = findImmediateJsDocBefore(content, member.getStart(sourceFile));
+ const { internal, deprecated } = parseJSDocContent(rawComment || "");
+ const propName = member.name.text;
+ const rawDefault = member.initializer?.getText(sourceFile)?.trim();
+ const rawType = cleanType(member.type?.getText(sourceFile)?.trim() || inferTypeFromDefault(rawDefault));
+
+ const fullDescription = parseDescriptionFromJSDoc(rawComment);
+ const { description, defaultValue: descriptionDefault } = extractDefaultFromDescription(fullDescription);
+ const isReadonly = isReadonlyDescription(description);
+ const required = !isReadonly && isAngularInputRequired(inputDecorator);
+
+ // Skip @deprecated props and internal-only props — not for public API docs
+ if (deprecated || (internal && !shouldAllowInternalProp(componentName, propName))) continue;
+
+ if (shouldSkipInternalProp(componentName, propName)) continue;
+
+ const values = parseWrapperPropValues(rawType);
+ const slotName = getMatchingSlotName(propName, slotNames);
+
+ if (slotName && isSlotCarrierType(rawType)) {
+ if (description) {
+ slotDescriptions[slotName] = description;
+ }
+ slotNameAliases[slotName] = propName;
+ slotRequired[slotName] = Boolean(slotRequired[slotName]) || required;
+ if (isPureSlotCarrierType(rawType)) {
+ continue;
+ }
+ }
+
+ const defaultValue = descriptionDefault ?? parseDefaultValue(rawDefault);
+
+ props.push({
+ name: propName,
+ type: rawType,
+ values,
+ required,
+ default: defaultValue,
+ description,
+ });
+ }
+
+ for (const member of classDecl.members) {
+ if (!ts.isPropertyDeclaration(member)) continue;
+ if (!member.name || !ts.isIdentifier(member.name)) continue;
+ const outputDecorator = getDecoratorCall(member, "Output");
+ if (!outputDecorator && !hasDecorator(member, "Output")) continue;
+
+ const rawComment = findImmediateJsDocBefore(content, member.getStart(sourceFile));
+ const { deprecated: eventDeprecated } = parseJSDocContent(rawComment || "");
+ if (eventDeprecated) continue;
+
+ const eventName = member.name.text;
+ let eventType = "void";
+
+ if (member.type && ts.isTypeReferenceNode(member.type)) {
+ const typeName = member.type.typeName.getText(sourceFile);
+ if (typeName.endsWith("EventEmitter")) {
+ eventType = member.type.typeArguments?.[0]?.getText(sourceFile)?.trim() || "void";
+ }
+ }
+
+ if (
+ (eventType === "void" || eventType === "CustomEvent") &&
+ member.initializer &&
+ ts.isNewExpression(member.initializer)
+ ) {
+ const expr = member.initializer;
+ const ctorName = expr.expression.getText(sourceFile);
+ if (ctorName.endsWith("EventEmitter")) {
+ eventType = expr.typeArguments?.[0]?.getText(sourceFile)?.trim() || "void";
+ }
+ }
+
+ const description = parseDescriptionFromJSDoc(rawComment);
+
+ events.push({
+ name: eventName,
+ type: toEventCallbackType(eventType),
+ description,
+ frameworks: ["angular"],
+ });
+ }
+
+ // Inject inherited props when the class extends common Angular base wrappers.
+ const extendsName = classDecl.heritageClauses
+ ?.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword)
+ ?.types?.[0]
+ ?.expression
+ ?.getText(sourceFile);
+
+ if (extendsName && (extendsName === "GoabBaseComponent" || extendsName === "GoabControlValueAccessor")) {
+ const existingNames = new Set(props.map((p) => p.name));
+ const baseComponentProps = extractAngularBaseComponentProps();
+ const inheritedPropNames =
+ extendsName === "GoabControlValueAccessor"
+ ? ["id", "disabled", "error", "value", "mt", "mr", "mb", "ml", "testId"]
+ : ["mt", "mr", "mb", "ml", "testId"];
+
+ const baseProps = inheritedPropNames
+ .map((name) => baseComponentProps.get(name))
+ .filter((prop): prop is ExtractedProp => Boolean(prop))
+ .filter((prop) => !existingNames.has(prop.name));
+
+ props.push(...baseProps);
+ }
+
+ const dedupedProps = dedupeByName(props).sort((a, b) => a.name.localeCompare(b.name));
+ const dedupedEvents = dedupeByName(events).sort((a, b) => a.name.localeCompare(b.name));
+
+ return {
+ found: true,
+ props: dedupedProps,
+ events: dedupedEvents,
+ slotDescriptions,
+ slotNameAliases,
+ slotRequired,
+ };
}
// =============================================================================
@@ -502,37 +1551,284 @@ function generateTypeLabel(
// Event Transformation
// =============================================================================
-function transformEvents(rawEventNames: string[]): ExtractedEvent[] {
- const events: ExtractedEvent[] = [];
+function inferDetailPropertyType(key: string, expression: string): string {
+ const expr = expression.trim();
+ const lowerKey = key.toLowerCase();
+
+ if (lowerKey === "name") return "string";
+ if (lowerKey === "label") return "string";
+ if (lowerKey === "labels") return "string[]";
+ if (lowerKey === "sortby") return "string";
+ if (lowerKey === "sortdir") return "number";
+ if (lowerKey === "sorts") return '{ column: string; direction: "asc" | "desc" }[]';
+ if (lowerKey === "tab") return "number";
+ if (lowerKey === "page") return "number";
+ if (lowerKey === "url") return "string";
+ if (lowerKey === "values") return "string[]";
+
+ if (lowerKey === "value") {
+ if (/newselectedvalues|array\.from\s*\(/i.test(expr)) return "string[]";
+ if (/_date\.date/.test(expr)) return "Date | string | null";
+ if (/\binput\.value\b/.test(expr)) return "string";
+ if (/\.value\b/.test(expr) && !/\bdetail\.value\b/.test(expr)) return "string";
+ if (/\boutput\b/.test(expr)) return "string";
+ if (/^newvalue$/i.test(expr)) return "string";
+ if (/^_?value$/.test(expr)) return "string";
+ if (/detail\.value/.test(expr)) return "string | unknown[]";
+ }
- for (const rawName of rawEventNames) {
- // Skip internal events
- if (rawName.includes("::") || rawName.includes(":")) continue;
+ if (lowerKey === "valuestr") return "string";
+ if (lowerKey === "key") {
+ if (/\.key\b/.test(expr)) return "string";
+ }
+ if (lowerKey === "action") {
+ if (/\.action\b/.test(expr)) return "string";
+ }
+ if (lowerKey === "size") {
+ if (/\.size\b/.test(expr)) return '"normal" | "compact"';
+ }
- // Raw event name (e.g., "_click") -> base name (e.g., "click")
- const baseName = rawName.replace(/^_/, "");
+ if (expr === "true" || expr === "false") return "boolean";
+ if (/^[-+]?\d+(\.\d+)?$/.test(expr)) return "number";
+ if (/^["'`].*["'`]$/.test(expr)) return "string";
+ if (/^\{[\s\S]*\}$/.test(expr)) return "Record";
+ if (/^\[[\s\S]*\]$/.test(expr)) return "unknown[]";
+ if (/\b(open|checked|disabled|selected|expanded|collapsed|visible|active)\b/i.test(expr)) {
+ return "boolean";
+ }
+ if (/(open|checked|disabled|selected|expanded|collapsed|visible|active)/.test(lowerKey)) {
+ return "boolean";
+ }
+ if (/\b(event|e)\b/.test(expr)) return "Event";
- // React event name: onClick, onChange, etc.
- const reactName = `on${capitalize(baseName)}`;
+ return "unknown";
+}
- // Add React event
- events.push({
- name: reactName,
- type: "(event: Event) => void",
- description: "",
- frameworks: ["react"],
- });
+function inferDetailPropertyOptional(key: string, expression: string): boolean {
+ const expr = expression.trim();
+ const lowerKey = key.toLowerCase();
- // Add Angular event (uses the raw name with underscore)
- events.push({
- name: rawName,
- type: "CustomEvent",
- description: "",
- frameworks: ["angular"],
- });
+ if (
+ (lowerKey === "action" || lowerKey === "size") &&
+ /\baction\.(action|size)\b/.test(expr)
+ ) {
+ return true;
}
- return events;
+ return false;
+}
+
+function buildCustomEventTypeFromDetail(detailObjectLiteral: string): string {
+ const objectBody = detailObjectLiteral.replace(/^\{\s*|\s*\}$/g, "");
+ if (!objectBody) return "CustomEvent";
+
+ const parsedMembers = objectBody
+ .split(",")
+ .map((part) => part.trim())
+ .filter(Boolean)
+ .map((part) => {
+ const keyValueMatch = part.match(/^([A-Za-z_$][\w$]*)\s*:\s*([\s\S]+)$/);
+ if (keyValueMatch) {
+ const key = keyValueMatch[1];
+ const value = keyValueMatch[2].trim();
+ return {
+ key,
+ type: inferDetailPropertyType(key, value),
+ optional: inferDetailPropertyOptional(key, value),
+ };
+ }
+
+ const shorthandMatch = part.match(/^([A-Za-z_$][\w$]*)$/);
+ if (shorthandMatch) {
+ const key = shorthandMatch[1];
+ return { key, type: inferDetailPropertyType(key, key), optional: false };
+ }
+
+ return null;
+ })
+ .filter((member): member is { key: string; type: string; optional: boolean } =>
+ Boolean(member),
+ );
+
+ if (!parsedMembers.length) return "CustomEvent>";
+
+ // Cross-field heuristics for common patterns in component events.
+ const hasLabels = parsedMembers.some((m) => m.key.toLowerCase() === "labels");
+ const hasValueStr = parsedMembers.some((m) => m.key.toLowerCase() === "valuestr");
+
+ const members = parsedMembers.map((member) => {
+ if (member.key.toLowerCase() === "value") {
+ if (hasLabels) {
+ return `${member.key}${member.optional ? "?" : ""}: string[]`;
+ }
+ if (hasValueStr) {
+ return `${member.key}${member.optional ? "?" : ""}: Date | string | null`;
+ }
+ }
+ return `${member.key}${member.optional ? "?" : ""}: ${member.type}`;
+ });
+
+ return `CustomEvent<{ ${members.join("; ")} }>`;
+}
+
+function scoreCustomEventType(eventType: string): number {
+ if (eventType === "CustomEvent" || eventType === "CustomEvent>" || eventType === "CustomEvent") {
+ return 0;
+ }
+
+ const detailMatch = eventType.match(/CustomEvent<\{([\s\S]*)\}>/);
+ if (!detailMatch?.[1]) return 0;
+
+ const body = detailMatch[1];
+ const keyCount = body.split(";").filter((part) => part.trim().length > 0).length;
+ const unknownCount = (body.match(/\bunknown\b/g) || []).length;
+
+ return keyCount * 10 - unknownCount * 6;
+}
+
+function splitTopLevelArgs(argsSource: string): string[] {
+ const parts: string[] = [];
+ let current = "";
+ let parenDepth = 0;
+ let braceDepth = 0;
+ let bracketDepth = 0;
+ let inString = false;
+ let stringQuote = "";
+
+ for (let i = 0; i < argsSource.length; i++) {
+ const ch = argsSource[i];
+ const prev = i > 0 ? argsSource[i - 1] : "";
+
+ if (inString) {
+ current += ch;
+ if (ch === stringQuote && prev !== "\\") {
+ inString = false;
+ stringQuote = "";
+ }
+ continue;
+ }
+
+ if (ch === '"' || ch === "'" || ch === "`") {
+ inString = true;
+ stringQuote = ch;
+ current += ch;
+ continue;
+ }
+
+ if (ch === "(") parenDepth++;
+ else if (ch === ")") parenDepth--;
+ else if (ch === "{") braceDepth++;
+ else if (ch === "}") braceDepth--;
+ else if (ch === "[") bracketDepth++;
+ else if (ch === "]") bracketDepth--;
+
+ if (ch === "," && parenDepth === 0 && braceDepth === 0 && bracketDepth === 0) {
+ parts.push(current.trim());
+ current = "";
+ continue;
+ }
+
+ current += ch;
+ }
+
+ if (current.trim().length > 0) {
+ parts.push(current.trim());
+ }
+
+ return parts;
+}
+
+function getCustomEventType(eventName: string, content: string): string {
+ const escapedName = escapeRegExp(eventName);
+ const eventPattern = new RegExp(
+ `new\\s+CustomEvent\\s*\\(\\s*["']${escapedName}["']\\s*,\\s*\\{([\\s\\S]*?)\\}\\s*\\)`,
+ "g",
+ );
+
+ const dispatchCallStartPattern = /dispatch(?:<[^>]+>)?\s*\(/g;
+
+ const detailLiterals: string[] = [];
+
+ for (const match of content.matchAll(eventPattern)) {
+ const eventOptions = match[1];
+ const detailMatch = eventOptions.match(/detail\s*:\s*(\{[\s\S]*?\})/);
+ if (detailMatch?.[1]) {
+ detailLiterals.push(detailMatch[1]);
+ }
+ }
+
+ for (const match of content.matchAll(dispatchCallStartPattern)) {
+ const startIndex = match.index ?? -1;
+ if (startIndex < 0) continue;
+
+ const openParenIndex = startIndex + match[0].length - 1;
+ let depth = 0;
+ let endIndex = -1;
+
+ for (let i = openParenIndex; i < content.length; i++) {
+ const ch = content[i];
+ if (ch === "(") depth++;
+ if (ch === ")") {
+ depth--;
+ if (depth === 0) {
+ endIndex = i;
+ break;
+ }
+ }
+ }
+
+ if (endIndex === -1) continue;
+
+ const callArgsSource = content.slice(openParenIndex + 1, endIndex);
+ const args = splitTopLevelArgs(callArgsSource);
+ if (args.length < 3) continue;
+
+ const eventArg = args[1].trim();
+ const eventMatch = eventArg.match(/^["']([^"']+)["']$/);
+ if (!eventMatch || eventMatch[1] !== eventName) continue;
+
+ const detailLiteral = args[2].trim();
+ if (detailLiteral.startsWith("{") && detailLiteral.endsWith("}")) {
+ detailLiterals.push(detailLiteral);
+ }
+ }
+
+ let bestEventType = "CustomEvent>";
+ let bestScore = -1;
+
+ for (const literal of detailLiterals) {
+ const typed = buildCustomEventTypeFromDetail(literal);
+ const score = scoreCustomEventType(typed);
+ if (score > bestScore) {
+ bestScore = score;
+ bestEventType = typed;
+ }
+ }
+
+ if (detailLiterals.length > 0) {
+ return bestEventType;
+ }
+
+ return "CustomEvent";
+}
+
+function transformWebComponentEvents(
+ componentName: string,
+ rawEventNames: string[],
+ content: string,
+): ExtractedEvent[] {
+ const internalOverrides = WEB_COMPONENT_INTERNAL_EVENT_OVERRIDES[componentName] || new Set();
+ const typeOverrides = WEB_COMPONENT_EVENT_TYPE_OVERRIDES[componentName] || {};
+
+ return rawEventNames
+ .filter((rawName) => !INTERNAL_EVENT_NAMES.has(rawName) && !internalOverrides.has(rawName))
+ .filter((rawName) => !rawName.includes("::") && !rawName.includes(":"))
+ .map((rawName) => ({
+ name: rawName,
+ type: typeOverrides[rawName] || getCustomEventType(rawName, content),
+ description: "",
+ frameworks: ["webComponents"],
+ }));
}
// =============================================================================
@@ -611,30 +1907,88 @@ function parseDefaultValue(str: string | undefined): string | null {
return str;
}
+function getAllComponentNames(): string[] {
+ const componentNames = new Set();
+ const documentedComponentSlugs = new Set(
+ fs
+ .readdirSync(DOCS_COMPONENT_CONTENT_PATH, { withFileTypes: true })
+ .filter((entry) => entry.isFile() && entry.name.endsWith(".mdx"))
+ .map((entry) => entry.name.replace(/\.mdx$/, "")),
+ );
+ const stack = [UI_COMPONENTS_PATH];
+
+ while (stack.length > 0) {
+ const current = stack.pop();
+ if (!current) continue;
+
+ const entries = fs.readdirSync(current, { withFileTypes: true });
+ for (const entry of entries) {
+ const fullPath = path.join(current, entry.name);
+
+ if (entry.isDirectory()) {
+ stack.push(fullPath);
+ } else if (
+ entry.isFile() &&
+ entry.name.endsWith(".svelte") &&
+ !entry.name.includes(".test.")
+ ) {
+ const content = fs.readFileSync(fullPath, "utf-8");
+ const slug = toKebabCase(path.basename(entry.name, ".svelte"));
+ if (
+ extractTagName(content) &&
+ documentedComponentSlugs.has(slug) &&
+ !DOCS_EXCLUDED_COMPONENTS.has(slug)
+ ) {
+ componentNames.add(slug);
+ }
+ }
+ }
+ }
+
+ for (const forcedComponent of DOCS_FORCED_COMPONENTS) {
+ componentNames.add(forcedComponent);
+ }
+
+ return Array.from(componentNames).sort((a, b) => a.localeCompare(b));
+}
+
+function removeStaleApiFiles(validComponentNames: string[]): void {
+ if (!fs.existsSync(OUTPUT_PATH)) return;
+
+ const validFiles = new Set(validComponentNames.map((name) => `${name}.json`));
+ const entries = fs.readdirSync(OUTPUT_PATH, { withFileTypes: true });
+
+ for (const entry of entries) {
+ if (entry.isFile() && entry.name.endsWith(".json") && !validFiles.has(entry.name)) {
+ fs.unlinkSync(path.join(OUTPUT_PATH, entry.name));
+ console.log(` Removed stale file: ${entry.name}`);
+ }
+ }
+}
+
// =============================================================================
// Main Extraction
// =============================================================================
function extractComponentAPI(componentName: string): ExtractedComponentAPI | null {
const componentPath = path.join(UI_COMPONENTS_PATH, componentName);
- if (!fs.existsSync(componentPath) || !fs.statSync(componentPath).isDirectory()) {
- console.error(`Component directory not found: ${componentName}`);
- return null;
- }
- // Find the main Svelte file
+ // Find the Svelte file by the component's public name first, then fall back
+ // to any .svelte file inside a matching directory.
const svelteFileName = `${capitalize(toCamelCase(componentName))}.svelte`;
- let svelteFilePath = path.join(componentPath, svelteFileName);
+ let svelteFilePath = findFirstFileByName(UI_COMPONENTS_PATH, svelteFileName);
- if (!fs.existsSync(svelteFilePath)) {
- // Try to find any .svelte file
+ if (!svelteFilePath && fs.existsSync(componentPath) && fs.statSync(componentPath).isDirectory()) {
const files = fs.readdirSync(componentPath);
const svelteFile = files.find((f) => f.endsWith(".svelte"));
- if (!svelteFile) {
- console.error(`No Svelte file found in: ${componentName}`);
- return null;
+ if (svelteFile) {
+ svelteFilePath = path.join(componentPath, svelteFile);
}
- svelteFilePath = path.join(componentPath, svelteFile);
+ }
+
+ if (!svelteFilePath) {
+ console.error(`No Svelte file found for: ${componentName}`);
+ return null;
}
const content = fs.readFileSync(svelteFilePath, "utf-8");
@@ -650,11 +2004,49 @@ function extractComponentAPI(componentName: string): ExtractedComponentAPI | nul
const typeAliases = extractTypeAliases(content);
const validators = extractValidators(content);
const rawProps = extractProps(content, validators, componentName, typeAliases);
- const rawEventNames = extractEvents(content);
+ let eventContent = content;
+ let rawEventNames = extractEvents(content);
+ const explicitEventsByComponent: Record> = {
+ "file-upload-card": new Set(["_cancel", "_delete"]),
+ };
+ const explicitEvents = explicitEventsByComponent[componentName];
+ if (explicitEvents) {
+ rawEventNames = Array.from(new Set([...rawEventNames, ...explicitEvents]));
+ }
+ const companionEventsByComponent: Record> = {
+ "work-side-menu": new Set(["_navigate"]),
+ "push-drawer": new Set(["_close"]),
+ };
+ const companionEvents = companionEventsByComponent[componentName];
+
+ if (companionEvents) {
+ const componentDir = path.dirname(svelteFilePath);
+ const siblingFiles = fs
+ .readdirSync(componentDir)
+ .filter((name) => name.endsWith(".svelte") && path.join(componentDir, name) !== svelteFilePath);
+
+ for (const siblingFile of siblingFiles) {
+ const siblingPath = path.join(componentDir, siblingFile);
+ const siblingContent = fs.readFileSync(siblingPath, "utf-8");
+ const siblingEventNames = extractEvents(siblingContent).filter((eventName) => companionEvents.has(eventName));
+ if (siblingEventNames.length > 0) {
+ rawEventNames = [...rawEventNames, ...siblingEventNames];
+ eventContent += `\n${siblingContent}`;
+ }
+ }
+
+ rawEventNames = Array.from(new Set(rawEventNames));
+ }
const slotNames = extractSlots(content);
+ const wrapperComponentName = WRAPPER_COMPONENT_ALIASES[componentName] ?? componentName;
+ const reactWrapper = extractReactWrapperApi(componentName, tagName, slotNames, wrapperComponentName);
+ const angularWrapper = extractAngularWrapperApi(componentName, tagName, slotNames, wrapperComponentName);
+
+ // Default slot content is implied by usage examples and is intentionally omitted
+ // from the API docs to reduce noise.
// Transform to output format
- const props: ExtractedProp[] = rawProps.map((p) => ({
+ let webComponentProps: ExtractedProp[] = rawProps.map((p) => ({
name: p.name,
type: p.type,
typeLabel: p.typeLabel,
@@ -665,12 +2057,90 @@ function extractComponentAPI(componentName: string): ExtractedComponentAPI | nul
...(p.deprecated && { deprecated: true }),
}));
- const events = transformEvents(rawEventNames);
+ let webComponentEvents = transformWebComponentEvents(componentName, rawEventNames, eventContent);
+ if (componentName === "side-menu-group") {
+ webComponentEvents = webComponentEvents.filter((event) => event.name !== "_open");
+ }
+ const slotDescriptions = {
+ ...angularWrapper.slotDescriptions,
+ ...reactWrapper.slotDescriptions,
+ };
+ const slotNameAliases = {
+ ...angularWrapper.slotNameAliases,
+ ...reactWrapper.slotNameAliases,
+ };
+ const slotRequired = {
+ ...angularWrapper.slotRequired,
+ ...reactWrapper.slotRequired,
+ };
- const slots: ExtractedSlot[] = slotNames.map((name) => ({
- name,
- description: "", // Filled by human content
- }));
+ const hasWrapperSlotEvidence = (name: string): boolean =>
+ Boolean(slotNameAliases[name] || slotDescriptions[name]) ||
+ Object.prototype.hasOwnProperty.call(slotRequired, name);
+
+ const createSlots = (
+ framework: "react" | "angular" | "webComponents",
+ type?: string,
+ useAliasNames: boolean = true,
+ ): ExtractedSlot[] =>
+ slotNames
+ .filter(
+ (name) =>
+ !INTERNAL_SLOT_NAMES.has(name.toLowerCase()) &&
+ !(name === "content" && !slotNameAliases[name] && !slotDescriptions[name]),
+ )
+ .map((name) => {
+ const rawDescription = slotDescriptions[name] || "";
+ const description =
+ framework === "angular"
+ ? rawDescription.replace(/ReactNode/g, "ngTemplate")
+ : rawDescription;
+ return {
+ name: useAliasNames ? slotNameAliases[name] || name : name,
+ type:
+ SLOT_TYPE_OVERRIDES[componentName]?.[framework]?.[name] ||
+ (type && hasWrapperSlotEvidence(name) ? type : undefined),
+ description,
+ required: slotRequired[name] || false,
+ };
+ });
+
+ const reactSlots = createSlots("react", "ReactNode", true);
+ const angularSlots = createSlots("angular", "TemplateRef", true);
+ const webComponentSlots = createSlots("webComponents", undefined, false);
+
+ let reactProps: ExtractedProp[] = reactWrapper.found ? [...reactWrapper.props] : [];
+ let angularProps: ExtractedProp[] = angularWrapper.found ? [...angularWrapper.props] : [];
+
+ specializeAngularValuePropFromReact(angularProps, reactProps);
+
+ const webComponentVersionProp = webComponentProps.find(
+ (prop) => prop.name.toLowerCase() === "version",
+ );
+ const hideVersionOutsideWeb = isStandardV1V2VersionProp(webComponentVersionProp);
+
+ reactProps = reactProps.filter(
+ (prop) =>
+ !shouldSkipInternalProp(componentName, prop.name) &&
+ !(hideVersionOutsideWeb && prop.name.toLowerCase() === "version"),
+ );
+ angularProps = angularProps.filter(
+ (prop) =>
+ !shouldSkipInternalProp(componentName, prop.name) &&
+ !(hideVersionOutsideWeb && prop.name.toLowerCase() === "version"),
+ );
+ webComponentProps = webComponentProps.filter(
+ (prop) => prop.name.toLowerCase() === "version" || !shouldSkipInternalProp(componentName, prop.name),
+ );
+
+ reactProps = dedupeByName(reactProps).sort((a, b) => a.name.localeCompare(b.name));
+ angularProps = dedupeByName(angularProps).sort((a, b) => a.name.localeCompare(b.name));
+
+ webComponentProps.sort((a, b) => a.name.localeCompare(b.name));
+ webComponentEvents.sort((a, b) => a.name.localeCompare(b.name));
+ reactSlots.sort((a, b) => a.name.localeCompare(b.name));
+ angularSlots.sort((a, b) => a.name.localeCompare(b.name));
+ webComponentSlots.sort((a, b) => a.name.localeCompare(b.name));
// Relative path from workspace root
const relativePath = path.relative(WORKSPACE_ROOT, svelteFilePath);
@@ -678,9 +2148,83 @@ function extractComponentAPI(componentName: string): ExtractedComponentAPI | nul
return {
componentSlug: toKebabCase(componentName),
extractedFrom: relativePath,
- props,
- events,
- slots,
+ frameworks: {
+ react: {
+ props: reactWrapper.found ? reactProps : [],
+ events: reactWrapper.found ? reactWrapper.events : [],
+ slots: reactWrapper.found ? reactSlots : [],
+ },
+ angular: {
+ props: angularWrapper.found ? angularProps : [],
+ events: angularWrapper.found ? angularWrapper.events : [],
+ slots: angularWrapper.found ? angularSlots : [],
+ },
+ webComponents: {
+ props: webComponentProps,
+ events: webComponentEvents,
+ slots: webComponentSlots,
+ },
+ },
+ };
+}
+
+function mergeItemArray(
+ next: T[],
+ existing: T[],
+ context: string,
+): T[] {
+ const existingByName = new Map(existing.map((item) => [item.name, item]));
+ const nextNames = new Set(next.map((item) => item.name));
+
+ // Backfill non-empty descriptions from existing into new items that have empty ones
+ const merged: T[] = next.map((item) => {
+ const existingItem = existingByName.get(item.name);
+ if (existingItem && !item.description && existingItem.description) {
+ return { ...item, description: existingItem.description };
+ }
+ return item;
+ });
+
+ // Preserve items from existing that are absent in the new extraction
+ // (but skip deprecated entries — they are intentionally excluded)
+ for (const existingItem of existing) {
+ if (!nextNames.has(existingItem.name)) {
+ if ((existingItem as Record).deprecated) continue;
+ console.warn(
+ ` Preserved manually-added entry "${existingItem.name}" in ${context} (not found in extraction — check source)`,
+ );
+ merged.push(existingItem);
+ }
+ }
+
+ return merged.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function mergeWithExisting(
+ next: ExtractedComponentAPI,
+ existing: ExtractedComponentAPI,
+): ExtractedComponentAPI {
+ const fw = next.frameworks;
+ const ex = existing.frameworks;
+ return {
+ ...next,
+ frameworks: {
+ react: {
+ props: mergeItemArray(fw.react.props, ex.react.props, `${next.componentSlug}.json [react props]`),
+ events: mergeItemArray(fw.react.events, ex.react.events, `${next.componentSlug}.json [react events]`),
+ slots: mergeItemArray(fw.react.slots, ex.react.slots, `${next.componentSlug}.json [react slots]`),
+ },
+ angular: {
+ props: mergeItemArray(fw.angular.props, ex.angular.props, `${next.componentSlug}.json [angular props]`),
+ events: mergeItemArray(fw.angular.events, ex.angular.events, `${next.componentSlug}.json [angular events]`),
+ slots: mergeItemArray(fw.angular.slots, ex.angular.slots, `${next.componentSlug}.json [angular slots]`),
+ },
+ webComponents: {
+ props: mergeItemArray(fw.webComponents.props, ex.webComponents.props, `${next.componentSlug}.json [webComponents props]`),
+ events: mergeItemArray(fw.webComponents.events, ex.webComponents.events, `${next.componentSlug}.json [webComponents events]`),
+ slots: mergeItemArray(fw.webComponents.slots, ex.webComponents.slots, `${next.componentSlug}.json [webComponents slots]`),
+ },
+ },
};
}
@@ -691,7 +2235,20 @@ function saveComponentAPI(api: ExtractedComponentAPI): void {
}
const filePath = path.join(OUTPUT_PATH, `${api.componentSlug}.json`);
- fs.writeFileSync(filePath, JSON.stringify(api, null, 2));
+
+ // Merge with existing file to preserve manually-added entries that the extractor
+ // cannot see (e.g. props defined in function-level intersections, or wrapper gaps).
+ let merged = api;
+ if (fs.existsSync(filePath)) {
+ try {
+ const existing = JSON.parse(fs.readFileSync(filePath, "utf-8")) as ExtractedComponentAPI;
+ merged = mergeWithExisting(api, existing);
+ } catch {
+ // Malformed existing file — overwrite with fresh extraction
+ }
+ }
+
+ fs.writeFileSync(filePath, JSON.stringify(merged, null, 2));
console.log(` Created: ${filePath}`);
}
@@ -715,11 +2272,8 @@ function main() {
let componentNames: string[];
if (args.includes("--all")) {
- // Get all component directories
- componentNames = fs.readdirSync(UI_COMPONENTS_PATH).filter((name) => {
- const componentPath = path.join(UI_COMPONENTS_PATH, name);
- return fs.statSync(componentPath).isDirectory();
- });
+ componentNames = getAllComponentNames();
+ removeStaleApiFiles(componentNames);
} else {
componentNames = args;
}
diff --git a/libs/angular-components/src/index.ts b/libs/angular-components/src/index.ts
index 55aebfe4b6..10e50c69ad 100644
--- a/libs/angular-components/src/index.ts
+++ b/libs/angular-components/src/index.ts
@@ -1,3 +1,4 @@
export * from "./lib/angular-components.module";
export * from "./lib/components";
+export * from "./lib/theme/theme.service";
export * from "@abgov/ui-components-common";
diff --git a/libs/angular-components/src/lib/components/accordion/accordion.spec.ts b/libs/angular-components/src/lib/components/accordion/accordion.spec.ts
index d91a1205e1..0425266ea4 100644
--- a/libs/angular-components/src/lib/components/accordion/accordion.spec.ts
+++ b/libs/angular-components/src/lib/components/accordion/accordion.spec.ts
@@ -5,6 +5,7 @@ import { By } from "@angular/platform-browser";
import {
GoabAccordionHeadingSize,
GoabAccordionIconPosition,
+ GoabAccordionHeadingType,
} from "@abgov/ui-components-common";
@Component({
@@ -17,6 +18,7 @@ import {
[headingSize]="headingSize"
[headingContent]="headingContent"
[iconPosition]="iconPosition"
+ [headingType]="headingType"
maxWidth="480px"
>
test content
@@ -29,8 +31,21 @@ class TestAccordionComponent {
open?: boolean;
headingSize?: GoabAccordionHeadingSize;
iconPosition?: GoabAccordionIconPosition;
+ headingType?: GoabAccordionHeadingType;
}
+@Component({
+ standalone: true,
+ imports: [GoabAccordion],
+ template: `
+
+ test content
+ This is the actions content
+
+ `,
+})
+class TestAccordionWithActionsComponent {}
+
describe("GoabAccordion", () => {
let fixture: ComponentFixture;
let component: TestAccordionComponent;
@@ -48,6 +63,7 @@ describe("GoabAccordion", () => {
component.open = true;
component.headingSize = "large" as GoabAccordionHeadingSize;
component.iconPosition = "right" as GoabAccordionIconPosition;
+ component.headingType = "filled" as GoabAccordionHeadingType;
fixture.detectChanges();
tick();
@@ -64,7 +80,33 @@ describe("GoabAccordion", () => {
expect(accordionElement.getAttribute("headingsize")).toBe("large");
expect(accordionElement.getAttribute("maxwidth")).toBe("480px");
expect(accordionElement.getAttribute("iconposition")).toBe("right");
+ expect(accordionElement.getAttribute("heading-type")).toBe("filled");
const headingContent = accordionElement.querySelector("[slot='headingcontent']");
expect(headingContent.textContent).toContain("This is the headingcontent");
});
});
+
+describe("GoabAccordion actions slot", () => {
+ let fixture: ComponentFixture;
+
+ beforeEach(fakeAsync(() => {
+ TestBed.configureTestingModule({
+ imports: [GoabAccordion, TestAccordionWithActionsComponent],
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ }).compileComponents();
+
+ fixture = TestBed.createComponent(TestAccordionWithActionsComponent);
+ fixture.detectChanges();
+ tick();
+ fixture.detectChanges();
+ }));
+
+ it("should render the actions slot content", () => {
+ const accordionElement = fixture.debugElement.query(
+ By.css("goa-accordion"),
+ ).nativeElement;
+ const actionsSlot = accordionElement.querySelector("[slot='actions']");
+ expect(actionsSlot).toBeTruthy();
+ expect(actionsSlot.textContent).toContain("This is the actions content");
+ });
+});
diff --git a/libs/angular-components/src/lib/components/accordion/accordion.ts b/libs/angular-components/src/lib/components/accordion/accordion.ts
index d8d80f3202..1d93b78da5 100644
--- a/libs/angular-components/src/lib/components/accordion/accordion.ts
+++ b/libs/angular-components/src/lib/components/accordion/accordion.ts
@@ -1,6 +1,7 @@
import {
GoabAccordionHeadingSize,
GoabAccordionIconPosition,
+ GoabAccordionHeadingType,
} from "@abgov/ui-components-common";
import {
CUSTOM_ELEMENTS_SCHEMA,
@@ -28,9 +29,11 @@ import { GoabBaseComponent } from "../base.component";
[attr.secondarytext]="secondaryText"
[attr.open]="open"
[attr.headingsize]="headingSize"
+ [attr.heading-type]="headingType"
[attr.maxwidth]="maxWidth"
[attr.testid]="testId"
[attr.iconposition]="iconPosition"
+ [attr.heading-type]="headingType"
[attr.mt]="mt"
[attr.mb]="mb"
[attr.ml]="ml"
@@ -40,6 +43,11 @@ import { GoabBaseComponent } from "../base.component";
;
+ /** Sets the actions content template reference, rendered right-aligned in the heading before the expand/collapse icon. */
+ @Input() actions?: TemplateRef;
/** Sets the maximum width of the accordion. */
@Input() maxWidth?: string;
/** Sets the position of the expand/collapse icon. */
@Input() iconPosition?: GoabAccordionIconPosition;
+ /** Sets the accordion style variant. */
+ @Input() headingType?: GoabAccordionHeadingType;
/** Emits when the accordion opens or closes. Emits the new open state as a boolean. */
@Output() onChange = new EventEmitter();
diff --git a/libs/angular-components/src/lib/components/chip/chip.ts b/libs/angular-components/src/lib/components/chip/chip.ts
index 615c0411a8..99f4d97070 100644
--- a/libs/angular-components/src/lib/components/chip/chip.ts
+++ b/libs/angular-components/src/lib/components/chip/chip.ts
@@ -56,17 +56,17 @@ export class GoabChip extends GoabBaseComponent implements OnInit {
}, 0);
}
- /** @deprecated Use GoAFilterChip instead. Icon displayed at the start of the chip. */
+ /** @deprecated Use GoabFilterChip (goab-filter-chip) instead. Icon displayed at the start of the chip. */
@Input() leadingIcon?: GoabIconType | null;
- /** @deprecated Use GoAFilterChip instead. Shows an error state on the chip. */
+ /** @deprecated Use GoabFilterChip (goab-filter-chip) instead. Shows an error state on the chip. */
@Input({ transform: booleanAttribute }) error?: boolean;
- /** @deprecated Use GoAFilterChip instead. When true, shows a delete icon and makes chip clickable. */
+ /** @deprecated Use GoabFilterChip (goab-filter-chip) instead. When true, shows a delete icon and makes chip clickable. */
@Input({ transform: booleanAttribute }) deletable?: boolean;
- /** @deprecated Use GoAFilterChip instead. The text content displayed in the chip. */
+ /** @deprecated Use GoabFilterChip (goab-filter-chip) instead. The text content displayed in the chip. */
@Input() content?: string = "";
- /** @deprecated Use GoAFilterChip instead. The chip variant style. */
+ /** @deprecated Use GoabFilterChip (goab-filter-chip) instead. The chip variant style. */
@Input() variant?: GoabChipVariant;
- /** @deprecated Use GoAFilterChip instead. The icon theme - outline or filled. */
+ /** @deprecated Use GoabFilterChip (goab-filter-chip) instead. The icon theme - outline or filled. */
@Input() iconTheme?: GoabChipTheme;
/** Emits when the chip is clicked. */
diff --git a/libs/angular-components/src/lib/components/drawer/drawer.ts b/libs/angular-components/src/lib/components/drawer/drawer.ts
index 29ff92aff0..c6f5ae6541 100644
--- a/libs/angular-components/src/lib/components/drawer/drawer.ts
+++ b/libs/angular-components/src/lib/components/drawer/drawer.ts
@@ -25,7 +25,7 @@ import { GoabDrawerPosition, GoabDrawerSize } from "@abgov/ui-components-common"
[attr.maxsize]="maxSize"
[attr.testid]="testId"
[attr.version]="version"
- (_close)="_onClose()"
+ (_close)="_onClose($event)"
>
;
+ /** Content rendered in the actions slot. */
+ @Input() actions?: TemplateRef;
ngOnInit(): void {
setTimeout(() => {
diff --git a/libs/angular-components/src/lib/components/microsite-header/microsite-header.ts b/libs/angular-components/src/lib/components/microsite-header/microsite-header.ts
index ce0dbc6f73..5fe6393368 100644
--- a/libs/angular-components/src/lib/components/microsite-header/microsite-header.ts
+++ b/libs/angular-components/src/lib/components/microsite-header/microsite-header.ts
@@ -65,7 +65,7 @@ export class GoabMicrositeHeader implements OnInit {
}
/** Emits when the feedback link is clicked. */
- @Output() onFeedbackClick = new EventEmitter();
+ @Output() onFeedbackClick = new EventEmitter();
getVersionAsString(): string {
return typeof this.version === "string" ? this.version : "";
diff --git a/libs/angular-components/src/lib/components/modal/modal.ts b/libs/angular-components/src/lib/components/modal/modal.ts
index 6b5906f782..0562ad7391 100644
--- a/libs/angular-components/src/lib/components/modal/modal.ts
+++ b/libs/angular-components/src/lib/components/modal/modal.ts
@@ -32,7 +32,7 @@ import { NgTemplateOutlet } from "@angular/common";
[attr.closable]="closable"
[attr.transition]="transition"
[attr.heading]="getHeadingAsString()"
- (_close)="_onClose()"
+ (_close)="_onClose($event)"
>
@if (this.heading !== "" && getHeadingAsTemplate() !== null) {
@@ -91,7 +91,7 @@ export class GoabModal implements OnInit {
@Input() actions!: TemplateRef;
/** Emits when the modal is closed. */
- @Output() onClose = new EventEmitter();
+ @Output() onClose = new EventEmitter();
getHeadingAsString(): string {
return this.heading instanceof TemplateRef ? "" : this.heading;
@@ -102,7 +102,8 @@ export class GoabModal implements OnInit {
return this.heading instanceof TemplateRef ? this.heading : null;
}
- _onClose() {
+ _onClose(event: Event) {
+ if (event.target !== event.currentTarget) return;
this.onClose.emit();
}
}
diff --git a/libs/angular-components/src/lib/components/push-drawer/push-drawer.ts b/libs/angular-components/src/lib/components/push-drawer/push-drawer.ts
index 1adaeb09cf..db5ab60a4f 100644
--- a/libs/angular-components/src/lib/components/push-drawer/push-drawer.ts
+++ b/libs/angular-components/src/lib/components/push-drawer/push-drawer.ts
@@ -23,7 +23,7 @@ import {
[attr.testid]="testId"
[attr.width]="width"
[attr.version]="version"
- (_close)="_onClose()"
+ (_close)="_onClose($event)"
>
;
/** Emits when the push drawer closes. */
- @Output() onClose = new EventEmitter();
+ @Output() onClose = new EventEmitter();
isReady = false;
@@ -66,7 +66,8 @@ export class GoabPushDrawer implements OnInit {
}, 0);
}
- _onClose() {
+ _onClose(event: Event) {
+ if (event.target !== event.currentTarget) return;
this.onClose.emit();
}
diff --git a/libs/angular-components/src/lib/components/radio-group/radio-group.ts b/libs/angular-components/src/lib/components/radio-group/radio-group.ts
index d22518a691..1d25bf8ab5 100644
--- a/libs/angular-components/src/lib/components/radio-group/radio-group.ts
+++ b/libs/angular-components/src/lib/components/radio-group/radio-group.ts
@@ -63,6 +63,8 @@ export class GoabRadioGroup extends GoabControlValueAccessor implements OnInit {
version = "2";
/** The name for the radio group. Used for accessibility and change events. */
@Input() name?: string;
+ /** The currently selected value in the radio group. */
+ @Input() override value?: string;
/** Sets the layout direction. 'vertical' stacks items, 'horizontal' places them in a row. */
@Input() orientation?: GoabRadioGroupOrientation;
/** Defines how the radio group will be announced by screen readers. */
diff --git a/libs/angular-components/src/lib/components/radio-item/radio-item.ts b/libs/angular-components/src/lib/components/radio-item/radio-item.ts
index 1a88274803..cbccd7c354 100644
--- a/libs/angular-components/src/lib/components/radio-item/radio-item.ts
+++ b/libs/angular-components/src/lib/components/radio-item/radio-item.ts
@@ -69,7 +69,7 @@ export class GoabRadioItem extends GoabBaseComponent implements OnInit {
@Input() revealAriaLabel?: string;
/** Disables this radio option. Also disabled if the parent RadioGroup is disabled. */
@Input({ transform: booleanAttribute }) disabled?: boolean;
- /** Sets this radio option as checked/selected. */
+ /** @internal Sets this radio option as checked/selected. */
@Input({ transform: booleanAttribute }) checked?: boolean;
/** Shows an error state on this radio option. */
@Input({ transform: booleanAttribute }) error?: boolean;
diff --git a/libs/angular-components/src/lib/components/table-sort-header/table-sort-header.ts b/libs/angular-components/src/lib/components/table-sort-header/table-sort-header.ts
index 7ebffb98e5..16e99b20ae 100644
--- a/libs/angular-components/src/lib/components/table-sort-header/table-sort-header.ts
+++ b/libs/angular-components/src/lib/components/table-sort-header/table-sort-header.ts
@@ -17,6 +17,7 @@ import {
[attr.name]="name"
[attr.direction]="direction"
[attr.sort-order]="sortOrder"
+ [attr.version]="version"
>
+
+
+ 2
+
+ `,
+})
+class TestWorkSideMenuItemWithTrailingContentComponent {
+ label = "Trailing item";
+ url = "/trailing";
+}
+
describe("GoabWorkSideMenuItem", () => {
it("should render and set the props correctly", fakeAsync(() => {
TestBed.configureTestingModule({
@@ -96,4 +116,26 @@ describe("GoabWorkSideMenuItem", () => {
expect(popoverContent).toBeTruthy();
expect(popoverContent.nativeElement.textContent).toBe("Popover content here");
}));
+
+ it("should render trailing content into the trailingContent slot", fakeAsync(() => {
+ TestBed.configureTestingModule({
+ imports: [TestWorkSideMenuItemWithTrailingContentComponent],
+ }).compileComponents();
+
+ const fixture = TestBed.createComponent(TestWorkSideMenuItemWithTrailingContentComponent);
+ fixture.detectChanges();
+ tick();
+ fixture.detectChanges();
+
+ const slotDiv = fixture.debugElement.query(
+ By.css('[slot="trailingContent"]'),
+ );
+ expect(slotDiv).toBeTruthy();
+
+ const trailingContent = fixture.debugElement.query(
+ By.css(".trailing-test-content"),
+ );
+ expect(trailingContent).toBeTruthy();
+ expect(trailingContent.nativeElement.textContent).toBe("2");
+ }));
});
diff --git a/libs/angular-components/src/lib/components/work-side-menu-item/work-side-menu-item.ts b/libs/angular-components/src/lib/components/work-side-menu-item/work-side-menu-item.ts
index 527530fe87..493ddcd709 100644
--- a/libs/angular-components/src/lib/components/work-side-menu-item/work-side-menu-item.ts
+++ b/libs/angular-components/src/lib/components/work-side-menu-item/work-side-menu-item.ts
@@ -31,6 +31,11 @@ import { NgTemplateOutlet } from "@angular/common";
}
+ @if (trailingContent) {
+
+ ;
+ /** Template reference for the trailing content slot. */
+ @Input() trailingContent!: TemplateRef;
isReady = false;
diff --git a/libs/angular-components/src/lib/components/work-side-menu/work-side-menu.ts b/libs/angular-components/src/lib/components/work-side-menu/work-side-menu.ts
index ac1bce228e..7218e747ea 100644
--- a/libs/angular-components/src/lib/components/work-side-menu/work-side-menu.ts
+++ b/libs/angular-components/src/lib/components/work-side-menu/work-side-menu.ts
@@ -64,7 +64,7 @@ export class GoabWorkSideMenu implements OnInit {
/** Template reference for the account slot content. */
@Input() accountContent!: TemplateRef;
/** Emits when the side menu is toggled open or closed. */
- @Output() onToggle = new EventEmitter();
+ @Output() onToggle = new EventEmitter();
/** Emits when a navigation link is clicked. Emits the URL as a string. */
@Output() onNavigate = new EventEmitter();
diff --git a/libs/angular-components/src/lib/theme/theme.service.spec.ts b/libs/angular-components/src/lib/theme/theme.service.spec.ts
new file mode 100644
index 0000000000..f64c406512
--- /dev/null
+++ b/libs/angular-components/src/lib/theme/theme.service.spec.ts
@@ -0,0 +1,202 @@
+import { ApplicationRef } from "@angular/core";
+import { TestBed } from "@angular/core/testing";
+import { GoabThemeService } from "./theme.service";
+
+const STORAGE_KEY = "goab-theme";
+const ATTRIBUTE = "data-theme";
+
+function mockMatchMedia(prefersDark: boolean) {
+ Object.defineProperty(window, "matchMedia", {
+ writable: true,
+ value: jest.fn().mockImplementation((query: string) => ({
+ matches: query === "(prefers-color-scheme: dark)" ? prefersDark : false,
+ media: query,
+ onchange: null,
+ addListener: jest.fn(),
+ removeListener: jest.fn(),
+ addEventListener: jest.fn(),
+ removeEventListener: jest.fn(),
+ dispatchEvent: jest.fn(),
+ })),
+ });
+}
+
+function flushEffects() {
+ TestBed.inject(ApplicationRef).tick();
+}
+
+describe("GoabThemeService", () => {
+ beforeEach(() => {
+ localStorage.clear();
+ document.documentElement.removeAttribute(ATTRIBUTE);
+ mockMatchMedia(false);
+ TestBed.resetTestingModule();
+ TestBed.configureTestingModule({});
+ });
+
+ describe("initial mode resolution", () => {
+ it("defaults to 'light' when localStorage, attribute, and system preference are absent", () => {
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+ });
+
+ it("reads 'dark' from localStorage when present", () => {
+ localStorage.setItem(STORAGE_KEY, "dark");
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("reads 'light' from localStorage when present", () => {
+ localStorage.setItem(STORAGE_KEY, "light");
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+ });
+
+ it("ignores invalid localStorage values and falls through to next source", () => {
+ localStorage.setItem(STORAGE_KEY, "purple");
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("reads 'dark' from data-theme attribute when localStorage is empty", () => {
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("reads 'dark' from prefers-color-scheme when localStorage and attribute are absent", () => {
+ mockMatchMedia(true);
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("prefers localStorage over data-theme attribute", () => {
+ localStorage.setItem(STORAGE_KEY, "light");
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+ });
+
+ it("prefers data-theme attribute over prefers-color-scheme", () => {
+ mockMatchMedia(true);
+ document.documentElement.setAttribute(ATTRIBUTE, "light");
+
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+ });
+ });
+
+ describe("setMode", () => {
+ it("updates the mode signal", () => {
+ const service = TestBed.inject(GoabThemeService);
+ service.setMode("dark");
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("syncs the data-theme attribute on ", () => {
+ const service = TestBed.inject(GoabThemeService);
+ service.setMode("dark");
+ flushEffects();
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+
+ service.setMode("light");
+ flushEffects();
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("light");
+ });
+
+ it("persists the mode to localStorage", () => {
+ const service = TestBed.inject(GoabThemeService);
+ service.setMode("dark");
+ flushEffects();
+ expect(localStorage.getItem(STORAGE_KEY)).toBe("dark");
+ });
+ });
+
+ describe("toggle", () => {
+ it("flips light to dark", () => {
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+
+ service.toggle();
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("flips dark to light", () => {
+ localStorage.setItem(STORAGE_KEY, "dark");
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+
+ service.toggle();
+ expect(service.mode()).toBe("light");
+ });
+
+ it("flips back and forth across multiple calls", () => {
+ const service = TestBed.inject(GoabThemeService);
+
+ service.toggle();
+ expect(service.mode()).toBe("dark");
+
+ service.toggle();
+ expect(service.mode()).toBe("light");
+
+ service.toggle();
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("syncs attribute and localStorage on toggle", () => {
+ const service = TestBed.inject(GoabThemeService);
+
+ service.toggle();
+ flushEffects();
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+ expect(localStorage.getItem(STORAGE_KEY)).toBe("dark");
+ });
+ });
+
+ describe("localStorage failures", () => {
+ it("does not throw when localStorage.setItem is blocked", () => {
+ const setItemSpy = jest
+ .spyOn(Storage.prototype, "setItem")
+ .mockImplementation(() => {
+ throw new Error("QuotaExceededError");
+ });
+
+ const service = TestBed.inject(GoabThemeService);
+
+ expect(() => {
+ service.setMode("dark");
+ flushEffects();
+ }).not.toThrow();
+
+ // Attribute should still update even if storage fails
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+
+ setItemSpy.mockRestore();
+ });
+
+ it("does not throw when localStorage.getItem is blocked at construction", () => {
+ const getItemSpy = jest
+ .spyOn(Storage.prototype, "getItem")
+ .mockImplementation(() => {
+ throw new Error("SecurityError");
+ });
+
+ expect(() => TestBed.inject(GoabThemeService)).not.toThrow();
+
+ getItemSpy.mockRestore();
+ });
+ });
+
+ describe("readonly mode signal", () => {
+ it("exposes mode as a read-only signal (no .set/.update)", () => {
+ const service = TestBed.inject(GoabThemeService);
+ const modeSignal = service.mode as unknown as Record;
+
+ expect(typeof modeSignal["set"]).toBe("undefined");
+ expect(typeof modeSignal["update"]).toBe("undefined");
+ });
+ });
+});
diff --git a/libs/angular-components/src/lib/theme/theme.service.ts b/libs/angular-components/src/lib/theme/theme.service.ts
new file mode 100644
index 0000000000..efe89b44a5
--- /dev/null
+++ b/libs/angular-components/src/lib/theme/theme.service.ts
@@ -0,0 +1,52 @@
+import { Injectable, effect, signal, type Signal } from "@angular/core";
+import type { GoabThemeMode } from "@abgov/ui-components-common";
+
+const STORAGE_KEY = "goab-theme";
+const ATTRIBUTE = "data-theme";
+
+@Injectable({ providedIn: "root" })
+export class GoabThemeService {
+ private readonly _mode = signal(this.readInitialMode());
+
+ /** Read-only signal for consumers. Use in templates: theme.mode() === 'dark'. */
+ readonly mode: Signal = this._mode.asReadonly();
+
+ constructor() {
+ effect(() => {
+ const current = this._mode();
+ if (typeof document === "undefined") return;
+ document.documentElement.setAttribute(ATTRIBUTE, current);
+ try {
+ window.localStorage.setItem(STORAGE_KEY, current);
+ } catch {
+ // localStorage blocked: fail silently.
+ }
+ });
+ }
+
+ setMode(next: GoabThemeMode): void {
+ this._mode.set(next);
+ }
+
+ toggle(): void {
+ this._mode.update((prev) => (prev === "light" ? "dark" : "light"));
+ }
+
+ private readInitialMode(): GoabThemeMode {
+ if (typeof window === "undefined") return "light";
+
+ try {
+ const stored = window.localStorage.getItem(STORAGE_KEY);
+ if (stored === "light" || stored === "dark") return stored;
+ } catch {
+ // fall through
+ }
+
+ const fromAttribute = document.documentElement.getAttribute(ATTRIBUTE);
+ if (fromAttribute === "light" || fromAttribute === "dark") return fromAttribute;
+
+ if (window.matchMedia("(prefers-color-scheme: dark)").matches) return "dark";
+
+ return "light";
+ }
+}
diff --git a/libs/common/src/lib/common.ts b/libs/common/src/lib/common.ts
index 6e104f1ad8..942333f31d 100644
--- a/libs/common/src/lib/common.ts
+++ b/libs/common/src/lib/common.ts
@@ -265,6 +265,7 @@ export type GoabButtonGroupGap = "relaxed" | "compact";
// Accordion
export type GoabAccordionHeadingSize = "small" | "medium";
export type GoabAccordionIconPosition = "left" | "right";
+export type GoabAccordionHeadingType = "normal" | "filled";
// Tooltip
@@ -1337,6 +1338,7 @@ export type GoabDrawerSizeUnit = "px" | "rem" | "ch" | "vh" | "vw" | "%";
export type GoabDrawerSize = `${number}${GoabDrawerSizeUnit}` | undefined;
// Work side menu
+/** @deprecated Use trailingContent with explicit badge components for indicator styling. */
export type GoabWorkSideMenuItemType = "normal" | "emergency" | "success";
// Work side notification
@@ -1378,3 +1380,5 @@ export type GoabRadioGroupSize = "default" | "compact";
export type GoabInputSize = "default" | "compact";
export type GoabTextAreaSize = "default" | "compact";
+
+export type GoabThemeMode = "light" | "dark";
diff --git a/libs/react-components/specs/accordion.browser.spec.tsx b/libs/react-components/specs/accordion.browser.spec.tsx
index a76495971b..135df672be 100644
--- a/libs/react-components/specs/accordion.browser.spec.tsx
+++ b/libs/react-components/specs/accordion.browser.spec.tsx
@@ -119,6 +119,59 @@ describe("Accordion", () => {
});
});
+ it("should not expand the accordion when a button in the actions slot is clicked", async () => {
+ const accordionChangeSpy = vi.fn();
+
+ const Component = () => {
+ return (
+ Action
+ }
+ onChange={accordionChangeSpy}
+ >
+ Accordion content
+
+ );
+ };
+
+ const result = render(Action
+ }
+ >
+ Accordion content
+
+ );
+ };
+
+ const result = render(
+ Download file
+
+
+
+ );
+ };
+
+ const result = render(
+ Open parent
+
+ }
+ >
+ Parent content
+
+ Open child
+
+ }
+ >
+ Child content
+
+ Close child
+
+
+
+ );
+ };
+
+ const result = render(Action}>
+ Content
+ ,
+ );
+ const el = baseElement.querySelector("goa-accordion");
+ const actions = el?.querySelector("[slot='actions']");
+ expect(actions).toBeTruthy();
+ });
+
it("should pass data-grid attributes", () => {
const { baseElement } = render(
-
+
Content
,
);
diff --git a/libs/react-components/src/lib/accordion/accordion.tsx b/libs/react-components/src/lib/accordion/accordion.tsx
index a577a18a35..986ace64b5 100644
--- a/libs/react-components/src/lib/accordion/accordion.tsx
+++ b/libs/react-components/src/lib/accordion/accordion.tsx
@@ -3,6 +3,7 @@ import { ReactNode, useEffect, useRef, type JSX } from "react";
import type {
GoabAccordionHeadingSize,
GoabAccordionIconPosition,
+ GoabAccordionHeadingType,
Margins,
DataAttributes,
} from "@abgov/ui-components-common";
@@ -17,6 +18,7 @@ interface WCProps extends Margins {
maxwidth?: string;
testid?: string;
iconposition?: GoabAccordionIconPosition;
+ headingType?: GoabAccordionHeadingType;
}
declare module "react" {
@@ -42,12 +44,16 @@ export interface GoabAccordionProps extends Margins, DataAttributes {
secondaryText?: string;
/** Sets content rendered within the accordion heading, alongside the heading text. */
headingContent?: ReactNode;
+ /** Sets content rendered in the accordion heading, right-aligned before the expand/collapse icon. */
+ actions?: ReactNode;
/** Sets the maximum width of the accordion. @default "none" */
maxWidth?: string;
/** Sets a data-testid attribute for automated testing. */
testId?: string;
/** Sets the position of the expand/collapse icon. @default "left" */
iconPosition?: GoabAccordionIconPosition;
+ /** Sets the accordion style variant. @default "normal" */
+ headingType?: GoabAccordionHeadingType;
/** Callback fired when the accordion is opened or closed. Receives the new open state as a boolean. */
onChange?: (open: boolean) => void;
/** Content rendered inside the accordion body. */
@@ -59,6 +65,8 @@ export function GoabAccordion({
open,
onChange,
headingContent,
+ headingType,
+ actions,
children,
...rest
}: GoabAccordionProps): JSX.Element {
@@ -81,8 +89,14 @@ export function GoabAccordion({
}, [onChange]);
return (
-
+
{headingContent && {headingContent}}
+ {actions && {actions}}
{children}
);
diff --git a/libs/react-components/src/lib/chip/chip.tsx b/libs/react-components/src/lib/chip/chip.tsx
index e02c58b08b..2ad7a678b7 100644
--- a/libs/react-components/src/lib/chip/chip.tsx
+++ b/libs/react-components/src/lib/chip/chip.tsx
@@ -30,19 +30,19 @@ declare module "react" {
}
export interface GoabChipProps extends Margins, DataAttributes {
- /** @required @deprecated Use GoAFilterChip instead. The text content displayed in the chip. */
+ /** @required @deprecated Use GoabFilterChip instead. The text content displayed in the chip. */
content: string;
- /** @deprecated Use GoAFilterChip instead. When true, shows a delete icon and makes chip clickable. */
+ /** @deprecated Use GoabFilterChip instead. When true, shows a delete icon and makes chip clickable. */
deletable?: boolean;
- /** @deprecated Use GoAFilterChip instead. Icon displayed at the start of the chip. */
+ /** @deprecated Use GoabFilterChip instead. Icon displayed at the start of the chip. */
leadingIcon?: string;
- /** @deprecated Use GoAFilterChip instead. The icon theme - outline or filled. */
+ /** @deprecated Use GoabFilterChip instead. The icon theme - outline or filled. */
iconTheme?: GoabChipTheme;
- /** @deprecated Use GoAFilterChip instead. Shows an error state on the chip. */
+ /** @deprecated Use GoabFilterChip instead. Shows an error state on the chip. */
error?: boolean;
- /** @deprecated Use GoAFilterChip instead. The chip variant style. */
+ /** @deprecated Use GoabFilterChip instead. The chip variant style. */
variant?: GoabChipVariant;
- /** @deprecated Use GoAFilterChip instead. Sets a data-testid attribute for automated testing. */
+ /** @deprecated Use GoabFilterChip instead. Sets a data-testid attribute for automated testing. */
testId?: string;
/** Callback fired when the chip is clicked or deleted. */
onClick?: () => void;
diff --git a/libs/react-components/src/lib/container/container.tsx b/libs/react-components/src/lib/container/container.tsx
index f630646802..5645aff2d0 100644
--- a/libs/react-components/src/lib/container/container.tsx
+++ b/libs/react-components/src/lib/container/container.tsx
@@ -46,9 +46,9 @@ export interface GoabContainerProps extends Margins, DataAttributes {
maxHeight?: string;
/** Sets a data-testid attribute for automated testing. */
testId?: string;
- /** Content rendered in the container's title/heading area. */
+ /** @deprecated Use title instead. Alias for the title prop. */
heading?: ReactNode;
- /** @deprecated Use heading instead. Alias for the heading prop. */
+ /** Content rendered in the container's title/heading area. */
title?: ReactNode;
/** Content rendered in the container's actions area, typically buttons or controls. */
actions?: ReactNode;
diff --git a/libs/react-components/src/lib/drawer/drawer.tsx b/libs/react-components/src/lib/drawer/drawer.tsx
index c1eda6568d..9c0fca7e34 100644
--- a/libs/react-components/src/lib/drawer/drawer.tsx
+++ b/libs/react-components/src/lib/drawer/drawer.tsx
@@ -56,9 +56,16 @@ export function GoabDrawer({
if (!el?.current || !onClose) {
return;
}
- el.current?.addEventListener("_close", onClose);
+ const current = el.current;
+ const listener = (e: Event) => {
+ if (e.target !== current) {
+ return;
+ }
+ onClose();
+ };
+ current.addEventListener("_close", listener);
return () => {
- el.current?.removeEventListener("_close", onClose);
+ current.removeEventListener("_close", listener);
};
}, [el, onClose]);
diff --git a/libs/react-components/src/lib/dropdown/dropdown.tsx b/libs/react-components/src/lib/dropdown/dropdown.tsx
index efe4819456..ced71d24a2 100644
--- a/libs/react-components/src/lib/dropdown/dropdown.tsx
+++ b/libs/react-components/src/lib/dropdown/dropdown.tsx
@@ -69,7 +69,7 @@ export interface GoabDropdownProps extends Margins, DataAttributes {
leadingIcon?: GoabIconType;
/** Maximum height of the dropdown menu. Non-native only. @default "276px" */
maxHeight?: string;
- /** When true, allows multiple items to be selected. */
+ /** When true, allows multiple items to be selected. @internal */
multiselect?: boolean;
/** When true, renders the native select HTML element. */
native?: boolean;
diff --git a/libs/react-components/src/lib/hero-banner/hero-banner.tsx b/libs/react-components/src/lib/hero-banner/hero-banner.tsx
index ee721a39a1..3347746c72 100644
--- a/libs/react-components/src/lib/hero-banner/hero-banner.tsx
+++ b/libs/react-components/src/lib/hero-banner/hero-banner.tsx
@@ -29,6 +29,8 @@ export interface GoabHeroBannerProps {
testId?: string;
/** Content rendered inside the hero banner body. */
children?: React.ReactNode;
+ /** Content rendered in the actions slot. */
+ actions?: React.ReactNode;
/** Maximum width of the content area. @default "100%" */
maxContentWidth?: string;
/** Hero Banner background color when no background image is provided. @default "#f8f8f8" */
@@ -46,6 +48,7 @@ export function GoabHeroBanner({
backgroundColor,
textColor,
children,
+ actions,
testId,
}: GoabHeroBannerProps): JSX.Element {
return (
@@ -59,6 +62,7 @@ export function GoabHeroBanner({
testid={testId}
>
{children}
+ {actions && {actions}}
);
}
diff --git a/libs/react-components/src/lib/input/input.tsx b/libs/react-components/src/lib/input/input.tsx
index 7e508a7285..d134194289 100644
--- a/libs/react-components/src/lib/input/input.tsx
+++ b/libs/react-components/src/lib/input/input.tsx
@@ -179,7 +179,10 @@ export function GoabInput({
onBlur,
onKeyPress,
...rest
-}: GoabInputProps & { type?: GoabInputType }): JSX.Element {
+}: GoabInputProps & {
+ /** Sets the type of the input field. @default "text" */
+ type?: GoabInputType;
+}): JSX.Element {
const ref = useRef(null);
const _props = transformProps(
diff --git a/libs/react-components/src/lib/microsite-header/microsite-header.tsx b/libs/react-components/src/lib/microsite-header/microsite-header.tsx
index 4132b6b9ce..106c6adfdf 100644
--- a/libs/react-components/src/lib/microsite-header/microsite-header.tsx
+++ b/libs/react-components/src/lib/microsite-header/microsite-header.tsx
@@ -26,7 +26,7 @@ interface WCProps {
export interface GoabHeaderProps {
/** @required The service type which determines the badge style. "live" shows official government site text, "alpha" and "beta" show development stage badges. */
type: GoabServiceLevel;
- /** App or service version displayed on the right side of the header. Accepts a string or custom ReactNode for rich content. */
+ /** App or service version displayed on the right side of the header. */
version?: string | React.ReactNode;
/** URL to a feedback page displayed when provided. */
feedbackUrl?: string;
diff --git a/libs/react-components/src/lib/modal/modal.tsx b/libs/react-components/src/lib/modal/modal.tsx
index 38604c5d83..4b97f47b13 100644
--- a/libs/react-components/src/lib/modal/modal.tsx
+++ b/libs/react-components/src/lib/modal/modal.tsx
@@ -76,7 +76,10 @@ export function GoabModal({
return;
}
const current = el.current;
- const listener = () => {
+ const listener = (e: Event) => {
+ if (e.target !== current) {
+ return;
+ }
onClose?.();
};
diff --git a/libs/react-components/src/lib/push-drawer/push-drawer.tsx b/libs/react-components/src/lib/push-drawer/push-drawer.tsx
index 681add6e08..ec3d4e7b96 100644
--- a/libs/react-components/src/lib/push-drawer/push-drawer.tsx
+++ b/libs/react-components/src/lib/push-drawer/push-drawer.tsx
@@ -51,9 +51,16 @@ export function GoabPushDrawer({
if (!el?.current || !onClose) {
return;
}
- el.current?.addEventListener("_close", onClose);
+ const current = el.current;
+ const listener = (e: Event) => {
+ if (e.target !== current) {
+ return;
+ }
+ onClose();
+ };
+ current.addEventListener("_close", listener);
return () => {
- el.current?.removeEventListener("_close", onClose);
+ current.removeEventListener("_close", listener);
};
}, [el, onClose]);
diff --git a/libs/react-components/src/lib/radio-group/radio.tsx b/libs/react-components/src/lib/radio-group/radio.tsx
index 9f100e6dc6..11b836f635 100644
--- a/libs/react-components/src/lib/radio-group/radio.tsx
+++ b/libs/react-components/src/lib/radio-group/radio.tsx
@@ -44,7 +44,7 @@ export interface GoabRadioItemProps extends Margins {
maxWidth?: string;
/** Disables this radio option. Also disabled if the parent RadioGroup is disabled. */
disabled?: boolean;
- /** Sets this radio option as checked/selected. */
+ /** @internal Sets this radio option as checked/selected. */
checked?: boolean;
/** Shows an error state on this radio option. */
error?: boolean;
diff --git a/libs/react-components/src/lib/tab/tab.tsx b/libs/react-components/src/lib/tab/tab.tsx
index 919289ed83..0064fb1643 100644
--- a/libs/react-components/src/lib/tab/tab.tsx
+++ b/libs/react-components/src/lib/tab/tab.tsx
@@ -1,7 +1,7 @@
import type { JSX } from "react";
interface WCProps {
- heading?: React.ReactNode;
+ heading?: string | React.ReactNode;
disabled?: string;
slug?: string;
}
@@ -17,7 +17,7 @@ declare module "react" {
export interface GoabTabItemProps {
/** The text label for this tab. Can also pass React nodes for custom heading content. */
- heading?: React.ReactNode;
+ heading?: string | React.ReactNode;
/** When true, disables the tab so it cannot be selected. */
disabled?: boolean;
/** Content rendered inside the tab panel. */
diff --git a/libs/react-components/src/lib/table/table-sort-header.tsx b/libs/react-components/src/lib/table/table-sort-header.tsx
index 0995dc319b..6be764bbe1 100644
--- a/libs/react-components/src/lib/table/table-sort-header.tsx
+++ b/libs/react-components/src/lib/table/table-sort-header.tsx
@@ -10,6 +10,7 @@ interface WCProps {
name?: string;
direction?: GoabTableSortDirection;
"sort-order"?: GoabTableSortOrder;
+ version?: "1" | "2";
}
declare module "react" {
@@ -46,6 +47,7 @@ export function GoabTableSortHeader({
name={name}
direction={direction}
sort-order={sortOrder}
+ version="2"
{...rest}
>
{children}
diff --git a/libs/react-components/src/lib/table/table.tsx b/libs/react-components/src/lib/table/table.tsx
index c07dc6bc17..b654243402 100644
--- a/libs/react-components/src/lib/table/table.tsx
+++ b/libs/react-components/src/lib/table/table.tsx
@@ -10,7 +10,6 @@ import { ReactNode, useEffect, useRef } from "react";
interface WCProps extends Margins {
ref?: React.RefObject;
width?: string;
- stickyheader?: string;
variant?: GoabTableVariant;
"sort-mode"?: GoabTableSortMode;
testid?: string;
@@ -37,7 +36,7 @@ export interface GoabTableProps extends Margins {
onMultiSort?: (detail: GoabTableOnMultiSortDetail) => void;
/** Sort mode: "single" allows one column, "multi" allows up to 2 columns. @default "single" */
sortMode?: GoabTableSortMode;
- // stickyHeader?: boolean; TODO: enable this later
+ // stickyHeader intentionally not exposed in wrapper yet.
/** A relaxed variant of the table with more vertical padding for the cells. @default "normal" */
variant?: GoabTableVariant;
/** When true, alternates row background colors for improved readability. */
diff --git a/libs/react-components/src/lib/theme/theme-context.spec.tsx b/libs/react-components/src/lib/theme/theme-context.spec.tsx
new file mode 100644
index 0000000000..9eec8e998e
--- /dev/null
+++ b/libs/react-components/src/lib/theme/theme-context.spec.tsx
@@ -0,0 +1,215 @@
+import { act, renderHook } from "@testing-library/react";
+import { type ReactNode } from "react";
+
+import { GoabThemeProvider, useTheme } from "./theme-context";
+
+const STORAGE_KEY = "goab-theme";
+const ATTRIBUTE = "data-theme";
+
+function mockMatchMedia(prefersDark: boolean) {
+ Object.defineProperty(window, "matchMedia", {
+ writable: true,
+ value: vi.fn().mockImplementation((query: string) => ({
+ matches: query === "(prefers-color-scheme: dark)" ? prefersDark : false,
+ media: query,
+ onchange: null,
+ addListener: vi.fn(),
+ removeListener: vi.fn(),
+ addEventListener: vi.fn(),
+ removeEventListener: vi.fn(),
+ dispatchEvent: vi.fn(),
+ })),
+ });
+}
+
+function wrapper(props: { children: ReactNode }) {
+ return {props.children} ;
+}
+
+describe("GoabThemeProvider / useTheme", () => {
+ beforeEach(() => {
+ localStorage.clear();
+ document.documentElement.removeAttribute(ATTRIBUTE);
+ mockMatchMedia(false);
+ });
+
+ describe("initial mode resolution", () => {
+ it("defaults to 'light' when localStorage, attribute, and system preference are absent", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("reads 'dark' from localStorage when present", () => {
+ localStorage.setItem(STORAGE_KEY, "dark");
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("reads 'light' from localStorage when present", () => {
+ localStorage.setItem(STORAGE_KEY, "light");
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("ignores invalid localStorage values and falls through to next source", () => {
+ localStorage.setItem(STORAGE_KEY, "purple");
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("reads 'dark' from data-theme attribute when localStorage is empty", () => {
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("reads 'dark' from prefers-color-scheme when localStorage and attribute are absent", () => {
+ mockMatchMedia(true);
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("prefers localStorage over data-theme attribute", () => {
+ localStorage.setItem(STORAGE_KEY, "light");
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("prefers data-theme attribute over prefers-color-scheme", () => {
+ mockMatchMedia(true);
+ document.documentElement.setAttribute(ATTRIBUTE, "light");
+
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("respects defaultMode prop when no other source is set", () => {
+ const customWrapper = (props: { children: ReactNode }) => (
+ {props.children}
+ );
+ const { result } = renderHook(() => useTheme(), { wrapper: customWrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+ });
+
+ describe("setMode", () => {
+ it("updates the mode value", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.setMode("dark"));
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("syncs the data-theme attribute on ", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.setMode("dark"));
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+
+ act(() => result.current.setMode("light"));
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("light");
+ });
+
+ it("persists the mode to localStorage", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.setMode("dark"));
+ expect(localStorage.getItem(STORAGE_KEY)).toBe("dark");
+ });
+ });
+
+ describe("toggle", () => {
+ it("flips light to dark", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("flips dark to light", () => {
+ localStorage.setItem(STORAGE_KEY, "dark");
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("flips back and forth across multiple calls", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("dark");
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("light");
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("syncs attribute and localStorage on toggle", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.toggle());
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+ expect(localStorage.getItem(STORAGE_KEY)).toBe("dark");
+ });
+
+ it("returns a stable toggle reference across renders", () => {
+ const { result, rerender } = renderHook(() => useTheme(), { wrapper });
+ const firstToggle = result.current.toggle;
+
+ rerender();
+ expect(result.current.toggle).toBe(firstToggle);
+ });
+ });
+
+ describe("useTheme outside provider", () => {
+ it("throws a descriptive error when used without GoabThemeProvider", () => {
+ // Suppress React's expected error log for this test
+ const noop = () => undefined;
+ const errorSpy = vi.spyOn(console, "error").mockImplementation(noop);
+
+ expect(() => renderHook(() => useTheme())).toThrow(
+ "useTheme must be used within a GoabThemeProvider",
+ );
+
+ errorSpy.mockRestore();
+ });
+ });
+
+ describe("localStorage failures", () => {
+ it("does not throw when localStorage.setItem is blocked", () => {
+ const setItemSpy = vi
+ .spyOn(Storage.prototype, "setItem")
+ .mockImplementation(() => {
+ throw new Error("QuotaExceededError");
+ });
+
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ expect(() => act(() => result.current.setMode("dark"))).not.toThrow();
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+
+ setItemSpy.mockRestore();
+ });
+
+ it("does not throw when localStorage.getItem is blocked at construction", () => {
+ const getItemSpy = vi
+ .spyOn(Storage.prototype, "getItem")
+ .mockImplementation(() => {
+ throw new Error("SecurityError");
+ });
+
+ expect(() => renderHook(() => useTheme(), { wrapper })).not.toThrow();
+
+ getItemSpy.mockRestore();
+ });
+ });
+});
diff --git a/libs/react-components/src/lib/theme/theme-context.tsx b/libs/react-components/src/lib/theme/theme-context.tsx
new file mode 100644
index 0000000000..2f02c14d1e
--- /dev/null
+++ b/libs/react-components/src/lib/theme/theme-context.tsx
@@ -0,0 +1,87 @@
+import {
+ createContext,
+ useCallback,
+ useContext,
+ useEffect,
+ useState,
+ type ReactNode,
+} from "react";
+import type { GoabThemeMode } from "@abgov/ui-components-common";
+
+interface GoabThemeContextValue {
+ mode: GoabThemeMode;
+ setMode: (mode: GoabThemeMode) => void;
+ toggle: () => void;
+}
+
+const STORAGE_KEY = "goab-theme";
+const ATTRIBUTE = "data-theme";
+
+const GoabThemeContext = createContext(null);
+
+function readInitialMode(defaultMode: GoabThemeMode): GoabThemeMode {
+ if (typeof window === "undefined") return defaultMode;
+
+ // Priority: localStorage > existing data-theme > system preference > defaultMode.
+ // Reading the attribute allows a blocking
diff --git a/libs/web-components/src/components/menu-button/MenuButton.svelte b/libs/web-components/src/components/menu-button/MenuButton.svelte
index 9af6007abb..e77f2634f1 100644
--- a/libs/web-components/src/components/menu-button/MenuButton.svelte
+++ b/libs/web-components/src/components/menu-button/MenuButton.svelte
@@ -139,7 +139,7 @@
}
function onAction(action: MenuActionProps) {
- dispatch(_rootEl, "_action", action, { bubbles: true });
+ dispatch(_rootEl, "_action", { action: action.action, size: action.size }, { bubbles: true });
close();
_buttonIndex = 0;
}
diff --git a/libs/web-components/src/components/microsite-header/MicrositeHeader.svelte b/libs/web-components/src/components/microsite-header/MicrositeHeader.svelte
index fe03dfbd97..ff19af50d9 100644
--- a/libs/web-components/src/components/microsite-header/MicrositeHeader.svelte
+++ b/libs/web-components/src/components/microsite-header/MicrositeHeader.svelte
@@ -161,7 +161,7 @@
color: var(--goa-microsite-header-color-links-hover);
}
- a:focus {
+ a:focus-visible {
outline: var(--goa-microsite-header-link-focus-border);
}
diff --git a/libs/web-components/src/components/notification/Notification.svelte b/libs/web-components/src/components/notification/Notification.svelte
index 28c0caf94e..efe9adb63c 100644
--- a/libs/web-components/src/components/notification/Notification.svelte
+++ b/libs/web-components/src/components/notification/Notification.svelte
@@ -191,11 +191,11 @@
color: unset !important;
outline: unset !important;
}
- :global(::slotted(a:focus)) {
+ :global(::slotted(a:focus-visible)) {
outline: auto !important;
border-radius: var(--goa-border-radius-xs);
}
- .notification.important :global(::slotted(a:focus)) {
+ .notification.important :global(::slotted(a:focus-visible)) {
outline: unset !important;
box-shadow: 0 0 0 3px var(--goa-color-greyscale-black);
border-radius: var(--goa-border-radius-xs);
@@ -423,27 +423,27 @@
}
/* V2 link focus states */
- .v2 .notification.important.high :global(::slotted(a:focus)) {
+ .v2 .notification.important.high :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-important-high-focus-border);
}
- .v2 .notification.important.low :global(::slotted(a:focus)) {
+ .v2 .notification.important.low :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-important-low-focus-border);
}
- .v2 .notification.information.high :global(::slotted(a:focus)) {
+ .v2 .notification.information.high :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-information-high-focus-border);
}
- .v2 .notification.information.low :global(::slotted(a:focus)) {
+ .v2 .notification.information.low :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-information-low-focus-border);
}
- .v2 .notification.emergency.high :global(::slotted(a:focus)) {
+ .v2 .notification.emergency.high :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-emergency-high-focus-border);
}
- .v2 .notification.emergency.low :global(::slotted(a:focus)) {
+ .v2 .notification.emergency.low :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-emergency-low-focus-border);
}
diff --git a/libs/web-components/src/components/popover/Popover.svelte b/libs/web-components/src/components/popover/Popover.svelte
index 0b9fa6d436..362349ec6a 100644
--- a/libs/web-components/src/components/popover/Popover.svelte
+++ b/libs/web-components/src/components/popover/Popover.svelte
@@ -54,13 +54,13 @@
/** Disables the popover interaction. Used by parent components like Dropdown. */
export let disabled: string = "false";
/** Additional vertical offset added to the popover's position. */
- export let voffset = "";
+ export let voffset: string = "";
/** Additional horizontal offset added to the popover's position. */
- export let hoffset = "";
+ export let hoffset: string = "";
/** Width of the focus outline border. */
- export let focusborderwidth = "var(--goa-border-width-l)";
+ export let focusborderwidth: string = "var(--goa-border-width-l)";
/** Border radius of the popover window. */
- export let borderradius = "var(--goa-border-radius-m)";
+ export let borderradius: string = "var(--goa-border-radius-m)";
/** Indicates the popover is used within a filterable context like a combobox. */
export let filterablecontext: string = "false";
@@ -200,6 +200,44 @@
}
}
+ function isInPopoverComposedTree(node: EventTarget | null): boolean {
+ if (!_popoverEl || !(node instanceof Node)) {
+ return false;
+ }
+
+ if (_popoverEl.contains(node)) {
+ return true;
+ }
+
+ // Walk across slot and shadow boundaries to detect nested/slotted descendants.
+ let current: Node | null = node;
+ while (current) {
+ if (current === _popoverEl) {
+ return true;
+ }
+
+ if (current instanceof Element && current.assignedSlot) {
+ current = current.assignedSlot;
+ continue;
+ }
+
+ if (current.parentNode) {
+ current = current.parentNode;
+ continue;
+ }
+
+ const rootNode = current.getRootNode?.();
+ if (rootNode instanceof ShadowRoot) {
+ current = rootNode.host;
+ continue;
+ }
+
+ current = null;
+ }
+
+ return false;
+ }
+
// When one popover is opened it dispatches a `goa:closePopover` to the document.body element, so adding a listener
// here will allow any other popover that is currently open to be closed
function addGlobalCloseListener() {
@@ -213,7 +251,10 @@
// the popover that is being opened will, at that time have the an open state, so we need to prevent
// that one that is being opened be immediately closed.
if (target !== _targetEl) {
- closePopover();
+ // Don't close if the target is a child popover (descendant of this popover's content)
+ if (target && !isInPopoverComposedTree(target)) {
+ closePopover();
+ }
}
});
}
@@ -404,7 +445,7 @@
class:use-anchor-based-positioning={!_needsManualPositioning}
class:align-right={_alignment === "right"}
style={styles(
- style("width", position !== "right" ? width : undefined),
+ position !== "right" && style("width", width),
style("min-width", minwidth),
style(
"max-width",
diff --git a/libs/web-components/src/components/push-drawer/PushDrawerInternal.svelte b/libs/web-components/src/components/push-drawer/PushDrawerInternal.svelte
index 5efc55ea69..192bfa1e9e 100644
--- a/libs/web-components/src/components/push-drawer/PushDrawerInternal.svelte
+++ b/libs/web-components/src/components/push-drawer/PushDrawerInternal.svelte
@@ -24,6 +24,7 @@
export let open: boolean = false;
export let heading: string = "";
export let width: string = "492px";
+ /** @internal Design system version for styling. */
export let version: VersionType = "1";
let _contentEl: HTMLElement | null = null;
diff --git a/libs/web-components/src/components/radio-item/RadioItem.svelte b/libs/web-components/src/components/radio-item/RadioItem.svelte
index bbf00546a5..678d8705a2 100644
--- a/libs/web-components/src/components/radio-item/RadioItem.svelte
+++ b/libs/web-components/src/components/radio-item/RadioItem.svelte
@@ -66,7 +66,7 @@
export let disabled: string = "false";
/** Shows an error state on this radio option. */
export let error: string = "false";
- /** Sets this radio option as checked/selected. */
+ /** @internal Sets this radio option as checked/selected. */
export let checked: string = "false";
/** Defines how this option will be announced by screen readers. */
export let arialabel: string = "";
@@ -209,7 +209,7 @@
checked = fromBoolean(data.checked);
description = data.description;
name = data.name;
- revealarialabel = data.revealAriaLabel;
+ revealarialabel = data.revealAriaLabel || "";
_version = data.version || "1";
_compact = data.compact || false;
});
diff --git a/libs/web-components/src/components/side-menu-group/SideMenuGroup.svelte b/libs/web-components/src/components/side-menu-group/SideMenuGroup.svelte
index ef495212c3..7002ab82d5 100644
--- a/libs/web-components/src/components/side-menu-group/SideMenuGroup.svelte
+++ b/libs/web-components/src/components/side-menu-group/SideMenuGroup.svelte
@@ -138,7 +138,7 @@
${calculateMargin(mt, mr, mb, ml)};
`}
>
-
+
{#if icon}
diff --git a/libs/web-components/src/components/temporary-notification/TemporaryNotificationCtrl.svelte b/libs/web-components/src/components/temporary-notification/TemporaryNotificationCtrl.svelte
index 5d63f8b7c4..fee9e12954 100644
--- a/libs/web-components/src/components/temporary-notification/TemporaryNotificationCtrl.svelte
+++ b/libs/web-components/src/components/temporary-notification/TemporaryNotificationCtrl.svelte
@@ -1,28 +1,35 @@
- | undefined;
// Use a unique id for each tooltip instance.
// So screen readers can identify the tooltip instance when
@@ -143,6 +143,16 @@
}, 500);
};
+ // Mouse click also fires on:focus on a tabindex=0 element, but we only want
+ // to reveal the tooltip on keyboard-driven focus so JS state stays aligned
+ // with the CSS :focus-visible rule that drives opacity.
+ function handleFocus(e: FocusEvent) {
+ const target = e.currentTarget as HTMLElement | null;
+ if (!target?.matches?.(":focus-visible")) return;
+ clearTimeout(_hideTooltipTimeout);
+ showTooltip();
+ }
+
async function checkAndAdjustPosition() {
// angular needs time to render the _tooltipEl
await tick();
@@ -227,10 +237,7 @@
showTooltip();
}}
on:mouseleave={hideTooltip}
- on:focus={() => {
- clearTimeout(_hideTooltipTimeout);
- showTooltip();
- }}
+ on:focus={handleFocus}
on:blur={hideTooltip}
data-testid={testid}
role="tooltip"
@@ -315,7 +322,7 @@
}
.tooltip:hover .tooltip-text,
- .tooltip:focus .tooltip-text {
+ .tooltip:focus-visible .tooltip-text {
opacity: 1;
}
diff --git a/libs/web-components/src/components/work-side-menu/WorkSideMenu.svelte b/libs/web-components/src/components/work-side-menu/WorkSideMenu.svelte
index 4aabdd4c56..a08757c4e7 100644
--- a/libs/web-components/src/components/work-side-menu/WorkSideMenu.svelte
+++ b/libs/web-components/src/components/work-side-menu/WorkSideMenu.svelte
@@ -32,7 +32,7 @@
// optional
/** Controls whether the side menu is expanded or collapsed. */
- export let open = false;
+ export let open: boolean = false;
/** Sets a data-testid attribute for automated testing. */
export let testid: string = "";
/** User's name displayed in the profile section. */
@@ -55,10 +55,10 @@
let _menuEl: HTMLElement;
let _menuLinks: HTMLElement[] = [];
- let _containerEl: HTMLElement;
+ let _containerEl: HTMLElement | undefined;
let _rootEl: HTMLElement;
let _scrollEl: HTMLElement;
- let _toggleButtonEl: HTMLElement;
+ let _toggleButtonEl: HTMLElement | undefined;
let _tooltipEl: HTMLElement;
let _tooltipLabel: string = "";
@@ -71,7 +71,7 @@
let _resizeObserver: ResizeObserver | null = null;
const _logo =
- "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32' fill='none'%3E%3Crect width='31.695' height='31.688' x='.028' fill='%2300B6ED' rx='4'/%3E%3Cg clip-path='url(%23a)'%3E%3Cmask id='b' width='47' height='39' x='-11' y='-2' maskUnits='userSpaceOnUse' style='mask-type:alpha'%3E%3Cpath fill='%23545860' d='M22.017 31.103a63.47 63.47 0 0 1-7.22-3.164 52.41 52.41 0 0 0 6.195-2.724 43.148 43.148 0 0 0 1.023 5.89m13.27-24.392c-1.034-.13-.497.348-.785 1.7-1.246 5.832-6.05 10.035-10.873 12.855-.506-6.678-.3-14.093.967-18.636 1.069-3.836 2.34-3.132.763-3.938-1.66-.848-3.44.273-4.882 3.13C19.033 4.68 12.393 20.19 1.78 30.664c-5.43 5.36-10.34 2.6-11.323 1.775-.8-.67-1.096.365-.103 1.426 4.39 4.7 10.805 2.003 13.141-.314 6.455-6.405 13.96-20.193 16.996-26.044a89.89 89.89 0 0 0 .243 15.294 44.69 44.69 0 0 1-7.619 2.885c-1.504.391-2.435 1-2.462 1.691-.03.758.98 1.397 2.44 2.085 2.6 1.226 10.216 4.798 12.093 5.878 1.606.925 2.39.204 2.866-.796.622-1.302-1.083-2.054-2.735-2.545a50.47 50.47 0 0 1-1.48-8.385c3.87-2.365 7.682-5.52 9.88-9.452a18.004 18.004 0 0 0 1.568-4.365c.23-.934.293-1.9.186-2.855 0 0-.03-.209-.186-.229'/%3E%3C/mask%3E%3Cg mask='url(%23b)'%3E%3Crect width='31.695' height='31.695' x='.028' fill='%23fff' rx='3.048'/%3E%3C/g%3E%3C/g%3E%3Cdefs%3E%3CclipPath id='a'%3E%3Crect width='32' height='31.992' y='.008' fill='%23fff' rx='4'/%3E%3C/clipPath%3E%3C/defs%3E%3C/svg%3E";
+ "data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHdpZHRoPSczMicgaGVpZ2h0PSczMicgZmlsbD0nbm9uZSc+PHJlY3Qgd2lkdGg9JzMxLjY5NScgaGVpZ2h0PSczMS42ODgnIHg9Jy4wMjgnIGZpbGw9JyMwMEI2RUQnIHJ4PSc0Jy8+PGcgY2xpcC1wYXRoPSd1cmwoI2EpJz48bWFzayBpZD0nYicgd2lkdGg9JzQ3JyBoZWlnaHQ9JzM5JyB4PSctMTEnIHk9Jy0yJyBtYXNrVW5pdHM9J3VzZXJTcGFjZU9uVXNlJyBzdHlsZT0nbWFzay10eXBlOmFscGhhJz48cGF0aCBmaWxsPScjNTQ1ODYwJyBkPSdNMjIuMDE3IDMxLjEwM2E2My40NyA2My40NyAwIDAgMS03LjIyLTMuMTY0IDUyLjQxIDUyLjQxIDAgMCAwIDYuMTk1LTIuNzI0IDQzLjE0OCA0My4xNDggMCAwIDAgMS4wMjMgNS44OW0xMy4yNy0yNC4zOTJjLTEuMDM0LS4xMy0uNDk3LjM0OC0uNzg1IDEuNy0xLjI0NiA1LjgzMi02LjA1IDEwLjAzNS0xMC44NzMgMTIuODU1LS41MDYtNi42NzgtLjMtMTQuMDkzLjk2Ny0xOC42MzYgMS4wNjktMy44MzYgMi4zNC0zLjEzMi43NjMtMy45MzgtMS42Ni0uODQ4LTMuNDQuMjczLTQuODgyIDMuMTNDMTkuMDMzIDQuNjggMTIuMzkzIDIwLjE5IDEuNzggMzAuNjY0Yy01LjQzIDUuMzYtMTAuMzQgMi42LTExLjMyMyAxLjc3NS0uOC0uNjctMS4wOTYuMzY1LS4xMDMgMS40MjYgNC4zOSA0LjcgMTAuODA1IDIuMDAzIDEzLjE0MS0uMzE0IDYuNDU1LTYuNDA1IDEzLjk2LTIwLjE5MyAxNi45OTYtMjYuMDQ0YTg5Ljg5IDg5Ljg5IDAgMCAwIC4yNDMgMTUuMjk0IDQ0LjY5IDQ0LjY5IDAgMCAxLTcuNjE5IDIuODg1Yy0xLjUwNC4zOTEtMi40MzUgMS0yLjQ2MiAxLjY5MS0uMDMuNzU4Ljk4IDEuMzk3IDIuNDQgMi4wODUgMi42IDEuMjI2IDEwLjIxNiA0Ljc5OCAxMi4wOTMgNS44NzggMS42MDYuOTI1IDIuMzkuMjA0IDIuODY2LS43OTYuNjIyLTEuMzAyLTEuMDgzLTIuMDU0LTIuNzM1LTIuNTQ1YTUwLjQ3IDUwLjQ3IDAgMCAxLTEuNDgtOC4zODVjMy44Ny0yLjM2NSA3LjY4Mi01LjUyIDkuODgtOS40NTJhMTguMDA0IDE4LjAwNCAwIDAgMCAxLjU2OC00LjM2NWMuMjMtLjkzNC4yOTMtMS45LjE4Ni0yLjg1NSAwIDAtLjAzLS4yMDktLjE4Ni0uMjI5Jy8+PC9tYXNrPjxnIG1hc2s9J3VybCgjYiknPjxyZWN0IHdpZHRoPSczMS42OTUnIGhlaWdodD0nMzEuNjk1JyB4PScuMDI4JyBmaWxsPScjZmZmJyByeD0nMy4wNDgnLz48L2c+PC9nPjxkZWZzPjxjbGlwUGF0aCBpZD0nYSc+PHJlY3Qgd2lkdGg9JzMyJyBoZWlnaHQ9JzMxLjk5MicgeT0nLjAwOCcgZmlsbD0nI2ZmZicgcng9JzQnLz48L2NsaXBQYXRoPjwvZGVmcz48L3N2Zz4=";
// *****
// Hooks
@@ -198,6 +198,7 @@
}
function setTooltipPos(label: string, el: HTMLElement) {
+ if (!_containerEl || !_tooltipEl) return;
const rect = el?.getBoundingClientRect();
const containerRect = _containerEl.getBoundingClientRect();
const top = rect.top - containerRect.top + rect.height / 2;
@@ -218,7 +219,7 @@
}
function handleToggleHover() {
- if (open) return;
+ if (open || !_toggleButtonEl) return;
setTooltipPos("Expand menu", _toggleButtonEl);
showTooltip();
@@ -378,12 +379,12 @@
{#if url}
- 
+
{heading}
{:else}
-
+
{heading}
{/if}
@@ -477,6 +478,13 @@
` uses `heading-l` (not the default `heading-xl`) to match the Figma spec for page-scale error states.
diff --git a/docs/src/content/examples/add-a-filter-chip/index.mdx b/docs/src/content/examples/add-a-filter-chip/index.mdx
index 77217bdd26..7e9173fb2b 100644
--- a/docs/src/content/examples/add-a-filter-chip/index.mdx
+++ b/docs/src/content/examples/add-a-filter-chip/index.mdx
@@ -1,10 +1,7 @@
---
id: add-a-filter-chip
title: Add a filter chip
-categories:
- - inputs-and-actions
-scale: interaction
-userType: both
+size: interaction
tags:
- filtering
- chips
diff --git a/docs/src/content/examples/add-a-record-using-a-drawer/index.mdx b/docs/src/content/examples/add-a-record-using-a-drawer/index.mdx
index cd07b09ac4..c9d2e654c5 100644
--- a/docs/src/content/examples/add-a-record-using-a-drawer/index.mdx
+++ b/docs/src/content/examples/add-a-record-using-a-drawer/index.mdx
@@ -1,10 +1,8 @@
---
id: add-a-record-using-a-drawer
title: Add a record using a drawer
-categories:
- - structure-and-navigation
-scale: task
-userType: worker
+size: section
+productType: workspace
tags:
- drawer
- forms
diff --git a/docs/src/content/examples/add-and-edit-lots-of-filters/index.mdx b/docs/src/content/examples/add-and-edit-lots-of-filters/index.mdx
index 615118ea61..df5951f2ca 100644
--- a/docs/src/content/examples/add-and-edit-lots-of-filters/index.mdx
+++ b/docs/src/content/examples/add-and-edit-lots-of-filters/index.mdx
@@ -1,10 +1,8 @@
---
id: add-and-edit-lots-of-filters
title: Add and edit lots of filters
-categories:
- - structure-and-navigation
-scale: task
-userType: worker
+size: section
+productType: workspace
tags:
- filtering
- drawer
diff --git a/docs/src/content/examples/add-another-item-in-a-modal/index.mdx b/docs/src/content/examples/add-another-item-in-a-modal/index.mdx
index 8e7232bf28..794c7611e1 100644
--- a/docs/src/content/examples/add-another-item-in-a-modal/index.mdx
+++ b/docs/src/content/examples/add-another-item-in-a-modal/index.mdx
@@ -1,10 +1,7 @@
---
id: add-another-item-in-a-modal
title: Add another item in a modal
-categories:
- - inputs-and-actions
-scale: task
-userType: both
+size: section
tags:
- modal
- forms
diff --git a/docs/src/content/examples/ask-a-long-answer-question-with-a-maximum-word-count/index.mdx b/docs/src/content/examples/ask-a-long-answer-question-with-a-maximum-word-count/index.mdx
index 0e507e54ad..4c9b078f35 100644
--- a/docs/src/content/examples/ask-a-long-answer-question-with-a-maximum-word-count/index.mdx
+++ b/docs/src/content/examples/ask-a-long-answer-question-with-a-maximum-word-count/index.mdx
@@ -1,10 +1,8 @@
---
id: ask-a-long-answer-question-with-a-maximum-word-count
title: Ask a long answer question with a maximum word count
-categories:
- - forms
-scale: task
-userType: citizen
+size: interaction
+productType: public-form
tags:
- forms
- text-area
diff --git a/docs/src/content/examples/ask-a-user-for-a-birthday/index.mdx b/docs/src/content/examples/ask-a-user-for-a-birthday/index.mdx
index c461ae3dea..5069834fa7 100644
--- a/docs/src/content/examples/ask-a-user-for-a-birthday/index.mdx
+++ b/docs/src/content/examples/ask-a-user-for-a-birthday/index.mdx
@@ -1,10 +1,8 @@
---
id: ask-a-user-for-a-birthday
title: Ask a user for a birthday
-categories:
- - forms
-scale: task
-userType: citizen
+size: interaction
+productType: public-form
tags:
- forms
- date-input
diff --git a/docs/src/content/examples/ask-a-user-for-an-address/index.mdx b/docs/src/content/examples/ask-a-user-for-an-address/index.mdx
index 5180a342cd..9f1959e1c0 100644
--- a/docs/src/content/examples/ask-a-user-for-an-address/index.mdx
+++ b/docs/src/content/examples/ask-a-user-for-an-address/index.mdx
@@ -1,10 +1,8 @@
---
id: ask-a-user-for-an-address
title: Ask a user for an address
-categories:
- - forms
-scale: task
-userType: citizen
+size: section
+productType: public-form
tags:
- forms
- address
diff --git a/docs/src/content/examples/ask-a-user-for-an-indian-registration-number/index.mdx b/docs/src/content/examples/ask-a-user-for-an-indian-registration-number/index.mdx
index 58b355be21..aa67ee504c 100644
--- a/docs/src/content/examples/ask-a-user-for-an-indian-registration-number/index.mdx
+++ b/docs/src/content/examples/ask-a-user-for-an-indian-registration-number/index.mdx
@@ -1,10 +1,8 @@
---
id: ask-a-user-for-an-indian-registration-number
title: Ask a user for an Indian registration number
-categories:
- - forms
-scale: task
-userType: citizen
+size: interaction
+productType: public-form
tags:
- forms
- identity
diff --git a/docs/src/content/examples/ask-a-user-for-direct-deposit-information/index.mdx b/docs/src/content/examples/ask-a-user-for-direct-deposit-information/index.mdx
index 2dc73560b1..79413ea5f7 100644
--- a/docs/src/content/examples/ask-a-user-for-direct-deposit-information/index.mdx
+++ b/docs/src/content/examples/ask-a-user-for-direct-deposit-information/index.mdx
@@ -1,10 +1,8 @@
---
id: ask-a-user-for-direct-deposit-information
title: Ask a user for direct deposit information
-categories:
- - forms
-scale: task
-userType: citizen
+size: section
+productType: public-form
tags:
- forms
- banking
diff --git a/docs/src/content/examples/ask-a-user-for-dollar-amounts/index.mdx b/docs/src/content/examples/ask-a-user-for-dollar-amounts/index.mdx
index 51eeae7f6c..9198b22e01 100644
--- a/docs/src/content/examples/ask-a-user-for-dollar-amounts/index.mdx
+++ b/docs/src/content/examples/ask-a-user-for-dollar-amounts/index.mdx
@@ -1,10 +1,8 @@
---
id: ask-a-user-for-dollar-amounts
title: Ask a user for dollar amounts
-categories:
- - forms
-scale: task
-userType: citizen
+size: interaction
+productType: public-form
tags:
- forms
- currency
diff --git a/docs/src/content/examples/ask-a-user-one-question-at-a-time/angular.html b/docs/src/content/examples/ask-a-user-one-question-at-a-time/angular.html
deleted file mode 100644
index 84c106cdae..0000000000
--- a/docs/src/content/examples/ask-a-user-one-question-at-a-time/angular.html
+++ /dev/null
@@ -1,19 +0,0 @@
-
- Back
-
-
-
-
-
- Save and continue
diff --git a/docs/src/content/examples/ask-a-user-one-question-at-a-time/angular.ts b/docs/src/content/examples/ask-a-user-one-question-at-a-time/angular.ts
deleted file mode 100644
index a46a1b448b..0000000000
--- a/docs/src/content/examples/ask-a-user-one-question-at-a-time/angular.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import { Component } from "@angular/core";
-import { GoabRadioGroupOnChangeDetail } from "@abgov/ui-components-common";
-
-@Component({
- selector: "app-ask-a-user-one-question-at-a-time",
- templateUrl: "./angular.html",
- styles: [
- `
- a.back-link::before {
- content: "";
- display: inline-block;
- width: 42px;
- height: 24px;
- vertical-align: middle;
- background: url('data:image/svg+xml,')
- center center no-repeat;
- }
-
- a.back-link:visited::before,
- a.back-link:hover::before {
- background: url('data:image/svg+xml,')
- center center no-repeat;
- }
-
- a.back-link {
- margin-top: var(--goa-space-m);
- }
- `,
- ],
-})
-export class AskAUserOneQuestionAtATimeComponent {
- selectedValue = "";
-
- onSchoolChange(event: GoabRadioGroupOnChangeDetail): void {
- this.selectedValue = event.value as string;
- }
-}
diff --git a/docs/src/content/examples/ask-a-user-one-question-at-a-time/index.mdx b/docs/src/content/examples/ask-a-user-one-question-at-a-time/index.mdx
deleted file mode 100644
index 16add605d0..0000000000
--- a/docs/src/content/examples/ask-a-user-one-question-at-a-time/index.mdx
+++ /dev/null
@@ -1,37 +0,0 @@
----
-id: ask-a-user-one-question-at-a-time
-title: Ask a user one question at a time
-categories:
- - forms
-scale: page
-userType: citizen
-tags:
- - forms
- - questions
- - public-form
-components:
- - form-item
- - radio-group
- - radio-item
- - button
-status: published
-previewImage: /images/examples/ask-a-user-one-question-at-a-time.webp
----
-
-Ask a user one question at a time.
-
-## When to use
-
-Use this pattern when:
-
-- Building a public-facing form for citizens
-- You want to reduce cognitive load by focusing on one question
-- The question requires careful consideration from the user
-- Following the one-question-per-page pattern for government services
-
-## Considerations
-
-- Include a back link to allow users to navigate to previous questions
-- Use a large label size to make the question prominent
-- Provide help text when the question may need clarification
-- Use a clear call-to-action button to progress
diff --git a/docs/src/content/examples/ask-a-user-one-question-at-a-time/react.tsx b/docs/src/content/examples/ask-a-user-one-question-at-a-time/react.tsx
deleted file mode 100644
index 0615ad3f04..0000000000
--- a/docs/src/content/examples/ask-a-user-one-question-at-a-time/react.tsx
+++ /dev/null
@@ -1,35 +0,0 @@
-import {
- GoabButton,
- GoabFormItem,
- GoabLink,
- GoabRadioGroup,
- GoabRadioItem,
-} from "@abgov/react-components";
-
-export function AskAUserOneQuestionAtATime() {
- return (
- <>
-
- Back
-
-
- {}}
- >
-
-
-
- Save and continue
-
-
- );
-}
diff --git a/docs/src/content/examples/ask-a-user-one-question-at-a-time/web-components.html b/docs/src/content/examples/ask-a-user-one-question-at-a-time/web-components.html
deleted file mode 100644
index b788d88fc4..0000000000
--- a/docs/src/content/examples/ask-a-user-one-question-at-a-time/web-components.html
+++ /dev/null
@@ -1,22 +0,0 @@
-
- Back
-
-
-
-
-
- Save and continue
-
-
diff --git a/docs/src/content/examples/basic-page-layout/index.mdx b/docs/src/content/examples/basic-page-layout/index.mdx
index 7c74326203..b7e2b019b6 100644
--- a/docs/src/content/examples/basic-page-layout/index.mdx
+++ b/docs/src/content/examples/basic-page-layout/index.mdx
@@ -1,10 +1,7 @@
---
id: basic-page-layout
title: Basic page layout
-categories:
- - content-layout
-scale: page
-userType: both
+size: page
tags:
- layout
- page-structure
@@ -19,6 +16,7 @@ status: published
fullWidth: true
previewStyle: "padding: 0; max-height: 600px"
previewImage: /images/examples/basic-page-layout.webp
+previewFullWidth: true
---
A basic page template to use as a starting point.
diff --git a/docs/src/content/examples/basic-page-layout/react.tsx b/docs/src/content/examples/basic-page-layout/react.tsx
index b91d797d11..1d7c1db36e 100644
--- a/docs/src/content/examples/basic-page-layout/react.tsx
+++ b/docs/src/content/examples/basic-page-layout/react.tsx
@@ -15,7 +15,7 @@ export function BasicPageLayout() {
Sign in
-
+
You have completed the application
-
-
- You will receive a copy of the confirmation to the email
- person@email.com
- Confirmation number: 1234ABC
-
-
-Go back to the dashboard, or direct your user somewhere else useful.
-Other information about what was just completed, other tertiary information, and/or
- contact information.
-
- Phone: 780 123 4567
-
- Email: information@gov.ab.ca
-
-
-
- Go to application
- Back to dashboard
-
diff --git a/docs/src/content/examples/confirm-that-an-application-was-submitted/angular.ts b/docs/src/content/examples/confirm-that-an-application-was-submitted/angular.ts
deleted file mode 100644
index 817bed0c4c..0000000000
--- a/docs/src/content/examples/confirm-that-an-application-was-submitted/angular.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-import { Component } from "@angular/core";
-
-@Component({
- selector: "app-confirm-that-an-application-was-submitted",
- templateUrl: "./angular.html",
-})
-export class ConfirmThatAnApplicationWasSubmittedComponent {}
diff --git a/docs/src/content/examples/confirm-that-an-application-was-submitted/index.mdx b/docs/src/content/examples/confirm-that-an-application-was-submitted/index.mdx
deleted file mode 100644
index 6aa9364d72..0000000000
--- a/docs/src/content/examples/confirm-that-an-application-was-submitted/index.mdx
+++ /dev/null
@@ -1,39 +0,0 @@
----
-id: confirm-that-an-application-was-submitted
-title: Confirm that an application was submitted
-categories:
- - feedback-and-alerts
-scale: page
-userType: citizen
-tags:
- - confirmation
- - success
- - callout
- - application
-components:
- - callout
- - button
- - button-group
-figmaUrl: https://www.figma.com/design/Jpy1Ea5qglwnp1SgGnagY9/%E2%9D%96-Component-library-%7C-DDD?node-id=63353-169579
-status: published
-previewImage: /images/examples/confirm-that-an-application-was-submitted.webp
----
-
-Display a confirmation screen to indicate successful application submission.
-
-## When to use
-
-Use this pattern when:
-
-- A user has successfully completed an application or form
-- You need to confirm the submission was received
-- Users need a confirmation number for their records
-- You want to provide next steps after submission
-
-## Considerations
-
-- Use a success callout to clearly indicate success
-- Include a confirmation number users can reference later
-- Mention where a confirmation email will be sent
-- Provide clear next steps and navigation options
-- Include contact information for questions
diff --git a/docs/src/content/examples/confirm-that-an-application-was-submitted/react.tsx b/docs/src/content/examples/confirm-that-an-application-was-submitted/react.tsx
deleted file mode 100644
index 5a6d308496..0000000000
--- a/docs/src/content/examples/confirm-that-an-application-was-submitted/react.tsx
+++ /dev/null
@@ -1,42 +0,0 @@
-import {
- GoabButton,
- GoabButtonGroup,
- GoabCallout,
- GoabText,
-} from "@abgov/react-components";
-
-export function ConfirmThatAnApplicationWasSubmitted() {
- return (
- <>
-
- You have completed the application
-
-
-
-
- You will receive a copy of the confirmation to the email person@email.com
-
-
- Confirmation number: 1234ABC
-
-
-
-
- Go back to the dashboard, or direct your user somewhere else useful.
-
-
- Other information about what was just completed, other tertiary information,
- and/or contact information.
-
- Phone: 780 123 4567
-
- Email: information@gov.ab.ca
-
-
-
- Go to application
- Back to dashboard
-
-
- );
-}
diff --git a/docs/src/content/examples/confirm-that-an-application-was-submitted/web-components.html b/docs/src/content/examples/confirm-that-an-application-was-submitted/web-components.html
deleted file mode 100644
index ccdbdb6f19..0000000000
--- a/docs/src/content/examples/confirm-that-an-application-was-submitted/web-components.html
+++ /dev/null
@@ -1,25 +0,0 @@
-You have completed the application
-
-
- You will receive a copy of the confirmation to the email person@email.com
- Confirmation number: 1234ABC
-
-
-Go back to the dashboard, or direct your user somewhere else useful.
-Other information about what was just completed, other tertiary information, and/or
- contact information.
-
- Phone: 780 123 4567
-
- Email: information@gov.ab.ca
-
-
-
- Go to application
- Back to dashboard
-
diff --git a/docs/src/content/examples/copy-to-clipboard/index.mdx b/docs/src/content/examples/copy-to-clipboard/index.mdx
index 439cc4a776..6b9f5dc34d 100644
--- a/docs/src/content/examples/copy-to-clipboard/index.mdx
+++ b/docs/src/content/examples/copy-to-clipboard/index.mdx
@@ -1,10 +1,7 @@
---
id: copy-to-clipboard
title: Copy to clipboard
-categories:
- - inputs-and-actions
-scale: interaction
-userType: both
+size: interaction
tags:
- clipboard
- copy
diff --git a/docs/src/content/examples/disabled-button-with-a-required-field/index.mdx b/docs/src/content/examples/disabled-button-with-a-required-field/index.mdx
index ee961c2bc4..db920cbfb7 100644
--- a/docs/src/content/examples/disabled-button-with-a-required-field/index.mdx
+++ b/docs/src/content/examples/disabled-button-with-a-required-field/index.mdx
@@ -1,10 +1,7 @@
---
id: disabled-button-with-a-required-field
title: Disabled button with a required field
-categories:
- - inputs-and-actions
-scale: interaction
-userType: both
+size: interaction
tags:
- button
- form
diff --git a/docs/src/content/examples/display-numbers-in-a-table-so-they-can-be-scanned-easily/index.mdx b/docs/src/content/examples/display-numbers-in-a-table-so-they-can-be-scanned-easily/index.mdx
index ba920ccf82..ab1bc725cb 100644
--- a/docs/src/content/examples/display-numbers-in-a-table-so-they-can-be-scanned-easily/index.mdx
+++ b/docs/src/content/examples/display-numbers-in-a-table-so-they-can-be-scanned-easily/index.mdx
@@ -1,10 +1,8 @@
---
id: display-numbers-in-a-table-so-they-can-be-scanned-easily
title: Display numbers in a table so they can be scanned easily
-categories:
- - content-layout
-scale: task
-userType: worker
+size: section
+productType: workspace
tags:
- table
- numbers
diff --git a/docs/src/content/examples/display-user-information/index.mdx b/docs/src/content/examples/display-user-information/index.mdx
index 6fc54f492b..ba97c6141a 100644
--- a/docs/src/content/examples/display-user-information/index.mdx
+++ b/docs/src/content/examples/display-user-information/index.mdx
@@ -1,10 +1,8 @@
---
id: display-user-information
title: Display user information
-categories:
- - content-layout
-scale: task
-userType: worker
+size: section
+productType: workspace
tags:
- container
- user-info
diff --git a/docs/src/content/examples/dynamically-add-an-item-to-a-dropdown-list/index.mdx b/docs/src/content/examples/dynamically-add-an-item-to-a-dropdown-list/index.mdx
index 00d5cb5551..96f1f8d3d2 100644
--- a/docs/src/content/examples/dynamically-add-an-item-to-a-dropdown-list/index.mdx
+++ b/docs/src/content/examples/dynamically-add-an-item-to-a-dropdown-list/index.mdx
@@ -1,10 +1,7 @@
---
id: dynamically-add-an-item-to-a-dropdown-list
title: Dynamically add an item to a dropdown list
-categories:
- - inputs-and-actions
-scale: interaction
-userType: both
+size: interaction
tags:
- dropdown
- dynamic
diff --git a/docs/src/content/examples/dynamically-change-items-in-a-dropdown-list/index.mdx b/docs/src/content/examples/dynamically-change-items-in-a-dropdown-list/index.mdx
index 2483250d66..faa2b79321 100644
--- a/docs/src/content/examples/dynamically-change-items-in-a-dropdown-list/index.mdx
+++ b/docs/src/content/examples/dynamically-change-items-in-a-dropdown-list/index.mdx
@@ -1,10 +1,7 @@
---
id: dynamically-change-items-in-a-dropdown-list
title: Dynamically change items in a dropdown list
-categories:
- - inputs-and-actions
-scale: interaction
-userType: both
+size: interaction
tags:
- dropdown
- dynamic
diff --git a/docs/src/content/examples/401-error-page/angular.html b/docs/src/content/examples/error-pages/401/angular.html
similarity index 100%
rename from docs/src/content/examples/401-error-page/angular.html
rename to docs/src/content/examples/error-pages/401/angular.html
diff --git a/docs/src/content/examples/401-error-page/angular.ts b/docs/src/content/examples/error-pages/401/angular.ts
similarity index 100%
rename from docs/src/content/examples/401-error-page/angular.ts
rename to docs/src/content/examples/error-pages/401/angular.ts
diff --git a/docs/src/content/examples/401-error-page/react.tsx b/docs/src/content/examples/error-pages/401/react.tsx
similarity index 100%
rename from docs/src/content/examples/401-error-page/react.tsx
rename to docs/src/content/examples/error-pages/401/react.tsx
diff --git a/docs/src/content/examples/401-error-page/web-components.html b/docs/src/content/examples/error-pages/401/web-components.html
similarity index 100%
rename from docs/src/content/examples/401-error-page/web-components.html
rename to docs/src/content/examples/error-pages/401/web-components.html
diff --git a/docs/src/content/examples/404-error-page/angular.html b/docs/src/content/examples/error-pages/404/angular.html
similarity index 100%
rename from docs/src/content/examples/404-error-page/angular.html
rename to docs/src/content/examples/error-pages/404/angular.html
diff --git a/docs/src/content/examples/404-error-page/angular.ts b/docs/src/content/examples/error-pages/404/angular.ts
similarity index 100%
rename from docs/src/content/examples/404-error-page/angular.ts
rename to docs/src/content/examples/error-pages/404/angular.ts
diff --git a/docs/src/content/examples/404-error-page/react.tsx b/docs/src/content/examples/error-pages/404/react.tsx
similarity index 100%
rename from docs/src/content/examples/404-error-page/react.tsx
rename to docs/src/content/examples/error-pages/404/react.tsx
diff --git a/docs/src/content/examples/404-error-page/web-components.html b/docs/src/content/examples/error-pages/404/web-components.html
similarity index 100%
rename from docs/src/content/examples/404-error-page/web-components.html
rename to docs/src/content/examples/error-pages/404/web-components.html
diff --git a/docs/src/content/examples/500-error-page/angular.html b/docs/src/content/examples/error-pages/500/angular.html
similarity index 100%
rename from docs/src/content/examples/500-error-page/angular.html
rename to docs/src/content/examples/error-pages/500/angular.html
diff --git a/docs/src/content/examples/500-error-page/angular.ts b/docs/src/content/examples/error-pages/500/angular.ts
similarity index 100%
rename from docs/src/content/examples/500-error-page/angular.ts
rename to docs/src/content/examples/error-pages/500/angular.ts
diff --git a/docs/src/content/examples/500-error-page/react.tsx b/docs/src/content/examples/error-pages/500/react.tsx
similarity index 100%
rename from docs/src/content/examples/500-error-page/react.tsx
rename to docs/src/content/examples/error-pages/500/react.tsx
diff --git a/docs/src/content/examples/500-error-page/web-components.html b/docs/src/content/examples/error-pages/500/web-components.html
similarity index 100%
rename from docs/src/content/examples/500-error-page/web-components.html
rename to docs/src/content/examples/error-pages/500/web-components.html
diff --git a/docs/src/content/examples/error-pages/index.mdx b/docs/src/content/examples/error-pages/index.mdx
new file mode 100644
index 0000000000..f63761dab3
--- /dev/null
+++ b/docs/src/content/examples/error-pages/index.mdx
@@ -0,0 +1,90 @@
+---
+id: error-pages
+title: Error pages
+size: page
+description: Standard error screens for Government of Alberta services. Use when a user lands somewhere that is missing, forbidden, or broken so they understand what happened and what to do next.
+previewImage: /thumbnails/error-pages-404.png
+hideHero: true
+components:
+ - page-block
+ - block
+ - text
+ - icon
+ - link
+ - button
+tags:
+ - error
+ - error page
+ - "401"
+ - "404"
+ - "500"
+ - page not found
+ - unauthorized
+ - restricted access
+ - server error
+ - server problem
+ - page-structure
+aliases:
+ - 401-error-page
+ - 404-error-page
+ - 500-error-page
+status: published
+---
+
+import PreviewContainer from "../../../components/PreviewContainer.astro";
+
+## Types of error pages
+
+### Restricted access (401)
+
+The user is not authorized, either because they need to sign in or because they lack the right permission.
+
+
-
- Primary users: citizens, public, external
- You are designing a public service for citizens. It should be designed to be as simple
- and intuitive as possible, while ensuring citizens can make complete and informed
- decisions for themselves using the service.
-
- There is an emphasis on an accessible experience with a low cognitive load for users
- who use the service infrequently.
-
-
-
-Pages
-
-
-
- 1. Start page
-
- This is the starting point for a citizen to begin your form from within your service
- or from Alberta.ca.
-
-
- 2. Task list page (optional)
-
- Outline the entire process for the user and help them through the process by
- breaking down an experience into individual tasks.
-
-
- 3. Question pages
-
- Ask a user a question or a small set of related questions.
-
-
- 4. Review page
-
- Let users check answers before submitting information to a service.
-
-
- 5. Results page
-
- Let users know that they've completed a form, application, or task and tell them
- what to do next.
-
-
-
diff --git a/docs/src/content/examples/public-form/angular.ts b/docs/src/content/examples/public-form/angular.ts
deleted file mode 100644
index fb2b7a40ae..0000000000
--- a/docs/src/content/examples/public-form/angular.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-import { Component } from "@angular/core";
-
-@Component({
- selector: "app-public-form",
- templateUrl: "./angular.html",
-})
-export class PublicFormComponent {}
diff --git a/docs/src/content/examples/public-form/index.mdx b/docs/src/content/examples/public-form/index.mdx
deleted file mode 100644
index 969e089442..0000000000
--- a/docs/src/content/examples/public-form/index.mdx
+++ /dev/null
@@ -1,35 +0,0 @@
----
-id: public-form
-title: Public form
-categories:
- - forms
-scale: product
-userType: citizen
-tags:
- - form
- - public
- - citizen
- - pattern
-components: []
-status: published
-previewImage: /images/examples/public-form.webp
----
-
-The public form pattern provides a structure for citizen-facing form experiences, emphasizing simplicity, accessibility, and low cognitive load.
-
-## When to use
-
-Use this pattern when:
-
-- Designing a public service for citizens
-- Building forms that should be simple and intuitive
-- Users need to make informed decisions while completing the form
-- The service should accommodate users who use it infrequently
-
-## Considerations
-
-- Follow the "one idea per page" principle to reduce cognitive load
-- Break complex forms into multiple pages with single questions
-- Use task list pages for longer processes with multiple sections
-- Consider using simple progress indicators rather than horizontal steppers
-- Ensure all form elements meet WCAG 2.2 AA accessibility standards
diff --git a/docs/src/content/examples/public-form/react.tsx b/docs/src/content/examples/public-form/react.tsx
deleted file mode 100644
index bc97714020..0000000000
--- a/docs/src/content/examples/public-form/react.tsx
+++ /dev/null
@@ -1,68 +0,0 @@
-import { GoabDetails, GoabGrid, GoabText } from "@abgov/react-components";
-
-export function PublicForm() {
- return (
- <>
-
-
- Primary users: citizens, public, external
-
-
- You are designing a public service for citizens. It should be designed to be as
- simple and intuitive as possible, while ensuring citizens can make complete and
- informed decisions for themselves using the service.
-
-
- There is an emphasis on an accessible experience with a low cognitive load for
- users who use the service infrequently.
-
-
-
-
- Pages
-
-
-
-
-
- 1. Start page
-
-
- This is the starting point for a citizen to begin your form from within your
- service or from Alberta.ca.
-
-
-
- 2. Task list page (optional)
-
-
- Outline the entire process for the user and help them through the process by
- breaking down an experience into individual tasks.
-
-
-
- 3. Question pages
-
-
- Ask a user a question or a small set of related questions.
-
-
-
- 4. Review page
-
-
- Let users check answers before submitting information to a service.
-
-
-
- 5. Results page
-
-
- Let users know that they've completed a form, application, or task and tell
- them what to do next.
-
-
-
-
- );
-}
diff --git a/docs/src/content/examples/public-form/web-components.html b/docs/src/content/examples/public-form/web-components.html
deleted file mode 100644
index fa147357d0..0000000000
--- a/docs/src/content/examples/public-form/web-components.html
+++ /dev/null
@@ -1,45 +0,0 @@
-
-
- Primary users: citizens, public, external
- You are designing a public service for citizens. It should be designed to be as simple
- and intuitive as possible, while ensuring citizens can make complete and informed
- decisions for themselves using the service.
-
- There is an emphasis on an accessible experience with a low cognitive load for users
- who use the service infrequently.
-
-
-
-Pages
-
-
-
- 1. Start page
-
- This is the starting point for a citizen to begin your form from within your service
- or from Alberta.ca.
-
-
- 2. Task list page (optional)
-
- Outline the entire process for the user and help them through the process by
- breaking down an experience into individual tasks.
-
-
- 3. Question pages
-
- Ask a user a question or a small set of related questions.
-
-
- 4. Review page
-
- Let users check answers before submitting information to a service.
-
-
- 5. Results page
-
- Let users know that they've completed a form, application, or task and tell them
- what to do next.
-
-
-
diff --git a/docs/src/content/examples/question-page/index.mdx b/docs/src/content/examples/question-page/index.mdx
index d23077989a..ab95516c23 100644
--- a/docs/src/content/examples/question-page/index.mdx
+++ b/docs/src/content/examples/question-page/index.mdx
@@ -1,39 +1,172 @@
---
id: question-page
title: Question page
-categories:
- - forms
-scale: page
-userType: citizen
+size: page
+productType: public-form
+description: "A question page presents one focused step in a multi-step form. Several variants adapt the shape: section titles, progress indicators, supporting context, expandable help, and grouped fields."
tags:
- forms
- question
- wizard
- one-thing-per-page
+ - public-form
+ - section-title
+ - progress
+ - context
+ - help
+ - details
+ - grouped-fields
+ - address
components:
- form-item
- input
+ - text-area
+ - radio-group
+ - radio-item
+ - dropdown
+ - dropdown-item
+ - details
+ - block
- button
- button-group
+aliases:
+ - ask-a-user-one-question-at-a-time
+ - give-more-information-before-asking-a-question-a
+ - give-more-information-before-asking-a-question-b
+ - show-more-information-to-help-answer-a-question
+ - show-a-list-to-help-answer-a-question
+ - show-a-section-title-on-a-question-page
+ - show-a-simple-progress-indicator-on-a-question-page
+ - show-a-simple-progress-indicator-on-a-question-page-with-multiple-questions
+ - group-related-questions-together-on-a-question-page
status: published
-previewImage: /images/examples/question-page.webp
+previewImage: /images/examples/question-page.png
+hideHero: true
---
-A question page pattern that presents one question at a time to help users focus, reduce cognitive load, and navigate complex forms more easily.
+import PreviewContainer from "../../../components/PreviewContainer.astro";
+
+## Types of question pages
+
+### Ask one question at a time
+
+The default question page. One idea per page reduces cognitive load and keeps users moving through the flow.
+
+
Workspaces should be adapted to fit each service's context and user needs. The reference example is a starting point to expand on, not a rigid template.
-categories: []
-scale: product
-userType: worker
-tags:
- - workspace
- - worker
- - service
- - case-management
- - dashboard
- - pattern
-components:
- - work-side-menu
- - table
- - badge
- - tabs
- - container
- - accordion
- - drawer
- - button
- - block
-previewImage: /thumbnails/workspace-preview.png
-status: published
----
-
-View demo
-
-import LinkCard from "../../../components/LinkCard.astro";
-
-
-
- Main workspace navigation
-
-
-
-
- Contextual case navigation
-
-
-
-View demo
-
----
-
-## Dashboard
-
-The dashboard gives staff an overview of their work.
-
-Include the information that helps them understand priorities and act quickly, such as:
-
-- counts or status summaries
-- trends or workload charts
-- links to assigned or high-priority work
-
-The layout uses [containers](/components/container) and [blocks](/components/block) to organize content into scannable sections.
-
-
-
-View demo
-
----
-
-## Data views
-
-Workers need different ways to view, scan, and act on records depending on the task. Choose the data view that best supports the task.
-
-- **Table view** — Dense, scannable rows with sortable columns. Best for users who need to compare fields across many records at once.
-- **Card view** — Each record as a card showing key details grouped into sections. Useful when records have more complex data that doesn't fit neatly into columns.
-- **Expandable list view** — Compact rows that expand inline to reveal detail. A middle ground between the density of a table and the richness of cards.
-
-Any view can be combined with grouping (for example, group by priority or status) to organize records into collapsible sections. Users can also search, filter by status using [tabs](/components/tabs), sort with multi-level sorting, and manage active filters with [filter chips](/components/filter-chip).
-
-
- Table view
-
-
-
-
- Card view
-
-
-
-
- Expandable list view
-
-
-
-View demo
-
----
-
-## Case detail
-
-Use the case detail view to help users review and act on a single record.
-
-Break long content into sections using [accordions](/components/accordion) to organize submitted data into collapsible sections. A table-of-contents sidebar helps users navigate long case content. [Badges](/components/badge) show case status, and action buttons in the header provide quick access to review, assign, and comment actions.
-
-
-
-View demo
-
----
-
-## Sticky action bar
-
-A scroll-aware header that pins to the top of the content area as the user scrolls. Use it to keep the most important tools visible.
-
-Set the content for each page based on the task:
-
-- On a cases list page, keep tools such as search and key actions visible.
-- On a detail page, keep the case name and key actions visible.
-
-Do not pin everything. Keep only the information and actions people need to continue their work without losing context.
-
-
-
-View demo
-
----
-
-## Push drawer
-
-Use a [push drawer](/components/drawer) for focused work that should happen without leaving the current page.
-
-This works well for actions such as:
-
-- approving or denying a record
-- requesting more information
-- completing a short decision form
-- reviewing supporting details while taking action
-
-Use it when users need to keep the main record in view while completing the task.
-
-
-
-View demo
-
----
-
-## Keyboard-accessible data views
-
-Workspace data views use the [data grid](/components/data-grid) to make table and card layouts fully keyboard navigable. Users can use arrow keys to move between cells and rows, making it possible to scan and act on records without a mouse. This is especially important in workspace contexts where staff are processing high volumes of cases and keyboard navigation is significantly faster than clicking. For assistive technology users, screen readers announce cell content and position as the user navigates.
-
----
-
-## Components built for workspace
-
-Workspace patterns are supported by component features designed for denser, more productive interfaces:
-
-- **Compact inputs** — Every input component now has a `compact` variant that reduces height and spacing. This lets you build tighter forms and toolbars without sacrificing usability.
-- **Compact badges and notifications** — [Badges](/components/badge) and [notification banners](/components/notification) also have compact sizing to fit within dense data views and action bars.
-- **Badge variants** — [Badges](/components/badge) now include `strong` and `subtle` emphasis options, giving you control over visual weight depending on context.
-- **Data grid** — The [data grid](/components/data-grid) works with the table component to support accessible, keyboard-navigable data views. Use them together when the user needs to move through records efficiently without relying on a mouse.
-- **Segmented tabs** — A new [tab](/components/tab) variant that works as a segmented toggle for switching between views or modes within a workspace, rather than navigating between pages.
-- **Enhanced filter chips** — [Filter chips](/components/filter-chip) now support secondary text and secondary icons, making them more useful for richer filtering in workspace data views.
-
----
-
-## Get started
-
-Use one of the workspace templates as a starting point for your service. Each template includes the sidebar navigation, dashboard, data views, and case detail patterns described above.
-
-
- Automated accessibility
+Automated accessibility testing tools help you identify potential accessibility issues. Use them as a starting point.
+
+
+ However, these tools are not a complete solution. They can produce:
+
+
+ - False positives – flagging issues that are not actual problems
+ - False negatives – missing real accessibility barriers
+
+
+ To ensure your digital product is accessible, combine automated testing with manual testing and apply
+ human judgment.
+
+Why automated tools alone are not enough
+
+False positives
+
+ Automated tools may flag elements as non-compliant even when they work correctly for users. For
+ example, a tool may report that an input is "missing an id" even though it is correctly associated with a
+ label using a valid method, such as wrapping the input inside a <label> element.
+
+
+False negatives
+
+ Automated tools cannot detect nuanced or context-specific issues. For example, all interactive
+ elements may be tabbable, but the order jumps around the page. Tools often don't judge whether the
+ tab order is logical for completing the task.
+
+
+Real user experience
+
+ Accessibility ensures real people can use a product effectively. Automated tools cannot fully simulate
+ how users interact with your product.
+
+Steps for effective accessibility testing
+
+
+ -
+ Run automated tools to get an initial assessment.
+
+ -
+ Manually verify flagged issues and review the element's intent and context.
+
+ -
+ Do additional manual testing for issues automated tools cannot detect:
+
+ - Test with a screen reader, such as VoiceOver (macOS) or NVDA (Windows)
+ - Test keyboard navigation by checking focus visibility and order
+
+
+ -
+ Report findings
+
+ - Record what you tested, what failed, and how to reproduce it
+ - If the issue relates to a design system component, submit it using the design system bug report form
+
+
+
+Why this process matters
+
+ Automated tools provide helpful insight. Relying only on automation can result in:
+
+
+ - Time spent fixing issues that are not real barriers
+ - Missed opportunities to address genuine accessibility issues
+ - A false sense of compliance without meaningful usability improvements
+
+
+ Combine automated and manual testing to identify real barriers. This approach improves accessibility
+ and overall product quality.
+
+Component lifecycle
+The component lifecycle defines the stages each Design System component moves through, from Experimental to Production to Legacy.
+
+
+ To request a new component or propose an enhancement, follow the
+ design contribution process.
+
+Experimental
+
+ Experimental components are new or significantly updated. They are available for testing and feedback
+ before public release.
+
+
+Characteristics
+
+ - Feedback is gathered from selected teams
+ - May be unstable or include breaking changes
+ - Limited documentation
+
+Production
+
+ Production components are stable and ready for broader adoption.
+
+
+Characteristics
+
+ - Fully documented, including design guidelines, properties, and examples
+ - Meet accessibility and design system standards
+ - Optimized for mobile use
+ - Actively maintained with updates and bug fixes
+ - Publicly available documentation
+
+Legacy
+
+ Legacy components are older components maintained primarily to support older implementations. If
+ possible, transition to production is recommended.
+
+
+Characteristics
+
+ - No active maintenance or updates
+ - Critical issues may remain unresolved
+ - Recommended alternative clearly identified
+ - Marked as "Legacy" in official documentation
+
+Contribute
+The Design System is a shared resource used and improved by service teams. All roles are encouraged to contribute.
+
+
+ Start by using existing Design System components and patterns. If a component or pattern does not
+ meet your needs, follow the contribution process below.
+
+Design contribution process
+
+ If a required component or example does not exist in production,
+ contact the Design System team. We will review the request together and determine next steps.
+
+
+1. Contact the team
+
+ Book a design system drop-in hours session.
+
+Be prepared to:
+
+ - Describe the component or pattern and its purpose
+ - Explain your user needs and service goals
+ - Share iterations explored with and without the Design System
+
+
+
+ There are open contribution files in Figma for every component and pattern in the design system, including unpublished ideas and experiments.
+
+
+2. Contribution criteria
+A proposed component or pattern must meet the following criteria.
+
+Proposal criteria
+Useful
+
+ Evidence shows it supports multiple teams or services. Provide screenshots or links to demonstrate usage.
+
+
+Unique
+
+ It does not duplicate an existing component or pattern. If replacing an existing component, provide
+ evidence that the new approach improves usability or accessibility.
+
+
+Publication standards
+To be published, the solution must be:
+
+Usable
+
+ Improves clarity, usability, and accessibility for users. Is informed by research and addresses a
+ validated user need.
+
+
+Universal
+
+ Inclusive and accessible. Meets or exceeds accessibility standards.
+ WCAG 2.2 AA is the minimum requirement.
+
+
+3. Backlog and collaboration
+
+ If approved, the item is added to the
+ Design System's backlog.
+
+
+ When development begins, the Design System team will collaborate with you to confirm detailed requirements.
+
+Code contribution process
+
+ The Design System supports multiple development frameworks through Web Components. Contributing full
+ components can be complex. Smaller contributions are encouraged.
+
+
+Recommended contribution types
+
+ - Bug fixes
+ - Documentation updates
+ - Enhancements to existing components
+
+
+ Start by contacting the team in the #design-system-support Slack channel.
+
+
+ Select an issue tagged ready-for-contribution from the
+ backlog.
+ Confirm which issue you will work on.
+
+
+
+ Since the repository is public, use a personal GitHub account instead of your Enterprise Managed User (EMU) account.
+
+
+Set up your contribution environment
+
+ - Clone the ui-components repository.
+ - Open the repository in your IDE.
+ - Create a branch named:
contributions/story-number
+ -
+ Run the following commands:
+
npm i
+npm run build
+
+ -
+ The playgrounds for local testing are located in:
+
/apps/dev/angular
+/apps/dev/react
+
+
+
+Run playground environments
+Angular
+npm run dev:watch
+npm run serve:dev:angular
+
+React
+npm run dev:watch
+npm run serve:dev:react
+
+Repository structure
+
+React wrappers
+/libs/react-components/src/lib
+Each folder represents a single component with its associated unit tests and wrapper code.
+
+Angular wrappers
+/libs/angular-components/src/lib/components
+Each folder represents a single component with its associated unit tests and wrapper code.
+
+Web Components
+/libs/web-components/src/components
+
+ - Unit tests as
{"*.spec.ts"}
+ - Component code as
{"*.svelte"}
+
+
+Testing requirements
+
+ - Write all unit tests in Svelte.
+ - If updating React or Angular wrappers, write unit tests in those respective frameworks.
+ -
+ Add browser testing using Jest for React wrappers and Svelte components when appropriate.
+ These can be found in:
libs/react-components/specs
+
+ - Manually test components in both React and Angular.
+ -
+ Create test files that others can use to manually test the PR. These can be created in:
+
/apps/prs/angular
+/apps/prs/react
+
+ - Follow the conventions already used in those files to create your test files.
+
+A Design System developer will also manually test the pull request.
+
+Submit your contribution
+Use the following commit message format:
+
+Bug fix
+fix(#storyNumber): short description (7 words max)
+
+Feature request
+feat(#storyNumber): short description (7 words max)
+
+
+ - Create a pull request from your branch to the
dev branch.
+ - Notify the design system team of the PR.
+
+Overview
+As a designer, you use the design system through Figma.
+In Figma, you can access:
+
+
+ - Design tokens
+ - Components
+ - Patterns
+
+
+
+ The design system library in Figma aligns with coded components used by developers. Start with
+ design system components for common parts of your service. This helps developers use the matching
+ coded components and reduces custom work.
+
+
+ Start with the design system. Validate your design through user testing. If usability issues arise,
+ or the problem cannot be solved within the system, consider creating a custom solution.
+
+Design with development in mind
+
+ When selecting components, prioritize those with a "goa-" prefix, such as
+ goa-input. These components exist in both design and development. Using them reduces
+ the need for custom development.
+
+Choose shared components whenever possible to maintain consistency and efficiency.
+
+Design tokens
+Design system components in Figma and code are built using design tokens.
+
+ Use tokens to communicate design decisions clearly. Developers can reference the same tokens in code.
+
+Instead of sharing hex values or pixel adjustments, reference semantic tokens.
+For example:
+
+ - Colour:
--goa-color-info-default
+ - Spacing:
--goa-spacing-m
+
+Using tokens reduces back-and-forth and keeps design and development aligned.
+
+Components
+All design system components are available in Figma and in code.
+
+ These components are designed to meet
+ WCAG 2.2 accessibility standards.
+
+Avoid detaching components. Instead:
+
+ - Use variants
+ - Show or hide layers within the component
+
+
+ Use #figma for Figma-related issues, including library updates, missing components,
+ broken instances, or component behaviour in Figma.
+
+
+ Use #design-system-support for design system guidance, component usage questions,
+ standards, and implementation support.
+
+Keep your components up to date. Figma will notify you when library updates are available.
+
+Figma file templates and helper components
+Each digital service project folder includes a starter Figma template.
+Use this template to:
+
+ - Organize your design file
+ - Support developer handoff
+ - Help team members navigate files
+
+
+ Helper components are also available. Use them to clearly communicate intent when sharing designs
+ with developers and other team members.
+
+Designing for dark mode
+
+ Dark mode is handled by the design system. Here's what that means for your designs.
+
+
+
+
+ Available in code now, not in Figma yet. Design in light mode and work with a developer to see your designs in dark mode.
+
+
+
+How it works
+
+ We have an experimental version of dark mode you can try out in your service. It's handled automatically in code, so designers don't need to do anything different. The Figma library doesn't have a dark mode yet, so keep designing in light mode like you always have. Your designs will translate to dark mode when developers add the dark mode theme to your service.
+
+
+Custom components and styles
+
+ If you're using design system components, they all work with dark mode automatically.
+
+
+ If you have custom components that use our design tokens, they'll switch to dark mode along with the rest of the system. Always worth testing to make sure things look right in both modes.
+
+
+ If your custom components don't use our design tokens, they won't switch on their own. You'll need to handle dark mode for those yourself. We recommend using design tokens where you can so most of this happens automatically.
+
+
+ Either way, you can extend dark mode for custom needs by working with developers to add custom dark mode styles to your service.
+
+
+ The same goes for illustrations and images with set colors. These look the same in both modes, so check whether they read well on a dark background or whether you need a dark version.
+
+
+Try it and share feedback
+
+ Dark mode is still being tested. Try it out in your service and let the design system team know what works, what doesn't, and what's missing.
+
+
+Ways to apply dark mode in your service
+
+ Two ways users end up in dark mode. Use either, or both:
+
+
+ - System settings. If their operating system is in dark mode, your service follows automatically.
+ - A toggle in your service. Let users switch modes themselves through a preferences or settings screen.
+
diff --git a/docs/src/content/get-started/designers/designing-with-ds.mdx b/docs/src/content/get-started/designers/designing-with-ds.mdx
new file mode 100644
index 0000000000..3be1641e5b
--- /dev/null
+++ b/docs/src/content/get-started/designers/designing-with-ds.mdx
@@ -0,0 +1,71 @@
+---
+id: designers/designing-with-ds
+title: Designing with Design System 2.0
+description: How to start new designs and update existing projects to Design System 2.0
+section: designers
+order: 2
+status: published
+---
+import DropInCallout from "../../../components/DropInCallout.astro";
+
+Designing with Design System 2.0
+What's new in DS 2.0 and how to start using it in your designs.
+
+ The Digital Design and Delivery (DDD) Design System has evolved to better support how service teams
+ design and build digital government services. Design System 2.0 includes an updated design
+ language, new tokens, refreshed components, and ready-to-use templates.
+
+Starting a new design
+
+ Use DS 2.0 templates as your starting point. Templates package layout, navigation, spacing, and
+ example content that you can adapt to your service. Some templates are built for specific service types
+ (for example, public-facing forms and workspace applications), and others are more general-purpose
+ starting points you can use across many kinds of pages and flows.
+
+
+Starting from an existing design
+
+Library swap
+
+ Use a library swap if
+ your goal is to convert most of the file to DS 2.0 in one pass.
+
+
+ - Make a copy of your file before you start.
+ - Expect mixed results. Some screens may need cleanup after the swap.
+
+
+Manual rebuild
+Use a manual rebuild if you need more control.
+
+ - Rebuild your highest value screens first.
+ - Consider using DS 2.0 templates as a base to speed things up.
+
+Update an existing project to the new design library
+
+Approach 1: Developer-first
+Use this approach in most cases.
+
+ - A developer creates a new branch and completes the upgrade steps.
+ - The team runs the upgraded application to see what changed.
+ - Designers review the upgraded screens and identify what needs design updates.
+
+When reviewing the upgraded branch, watch for:
+
+ - Spacing and layout rhythm
+ - Typography scale and weight usage
+ - Dense or constrained screens (these often have the highest risk during an update)
+
+
+Approach 2: Design-first
+Use this approach when you want design work to move ahead of development work.
+
+ - Identify custom elements that support your users' needs.
+ - Create an inventory and prioritize items by importance and effort.
+ - Redesign the highest priority items using the visual design values in the Styles library.
+
+
+
+ In most cases, start with the developer-first approach. It helps you quickly see what changed in your real product, so you can focus design effort where it matters most.
+
+User experience guidelines
+Digital products built for the Government of Alberta should comply with these guidelines to ensure a quality user experience for Albertans.
+
+
+ - User-centered: Designed with a clear understanding of users, their goals, tasks, environments, and context of use, using user-centered design methods.
+ - Usable: Interfaces will be easy to use, enabling users to find the information they need and complete tasks successfully.
+ - Accessible: Digital products will be inclusive, ensuring usability for everyone, regardless of physical or cognitive ability.
+ - Trustworthy: Experiences will feel familiar and recognizable as a Government of Alberta product, ensuring users' security and privacy.
+ - Modern: Digital experiences will meet present-day user expectations and preferences for aesthetics and interaction.
+
+
+
+ For more details on the process of assessing compliance to each guideline, refer to our
+ User Experience Guidelines and Design System Checklist.
+
+Usability testing
+
+ Usability testing is our preferred method to understand user needs as they relate to each guideline.
+
+Suitable usability testing includes:
+
+ - Diverse user group: Real users from different demographic, behavioural backgrounds, and geographical regions within Alberta that will experience the problem or benefit of the product.
+ - Inclusive testing: Users with various physical and/or cognitive abilities, literacy levels, and tech savviness.
+ - Device variety: A diverse range of devices that reflect users' preferred choice when interacting with government services.
+ - Tasks: Activities that cover tasks and service process from end-to-end.
+
+
+ Frequent usability testing should be conducted to maintain product usability, effectiveness and
+ alignment to the user needs as they evolve over time.
+
+
+ For guidance on the process of usability testing, refer to our
+ Understanding Usability documentation.
+
+Overview
+As a developer, you use the Design System through tokens, components, examples, and templates.
+
+
+ The DDD Design System is built using Web Components. Web Components are framework-agnostic.
+ You can use them with Angular, React, or other front-end frameworks.
+
+The Design System includes:
+
+ - Tokens
+ - Components
+ - Examples
+ - Templates
+
+
+ Designers use equivalent resources in Figma. When they design with Design System components, you
+ can build with the matching coded components. This reduces custom development and rework.
+
+
+ All Design System components are designed and built to meet
+ WCAG 2.2 accessibility standards.
+
+Tokens
+
+ Access the tokens as an
+ NPM package.
+
+
+ Import the SCSS or CSS file into your project. Replace hard-coded values with Design System token variables.
+
+
+ Designers reference the same tokens in their tools. This keeps design and development aligned during handoff.
+
+
+Components
+Components are reusable user interface elements built for use across services.
+You can:
+
+ - Use components individually
+ - Combine them into patterns
+ - Apply them in different contexts
+
+Components are available:
+
+ - As Web Components
+ - As Angular wrappers
+ - As React wrappers
+
+
+ Refer to the Design System technologies documentation
+ for implementation details.
+
+
+Examples
+
+ Examples are multiple components assembled in realistic service contexts. They help you understand
+ how to apply Design System guidance in a working interface.
+
+You can use examples to:
+
+ - Understand how components work together
+ - Use them as a starting point for building parts of your interface
+ - Use proven approaches to meet user needs
+
+
+ Examples help you build with more consistency and less rework. Use them to guide implementation,
+ then adjust them to meet the needs of your product.
+
+
+Templates
+
+ Templates are opinionated starting points for common service types. They package layout, navigation,
+ spacing, and example content so you can start with a proven structure instead of building from scratch.
+
+You can use templates to:
+
+ - Start a new product with a proven structure
+ - Learn how components work together in a real layout
+ - Adapt a proven starting point to fit your service needs
+
+
+ Templates help teams move faster, reduce rework, and stay aligned with Design System guidance.
+
+Supported browsers
+Design System components are tested across supported browsers and devices.
+
+
+ We support the latest version of each browser listed on this page. Support applies to the browser and
+ operating system combinations shown in the table below. On mobile, support is limited to the browser
+ and operating system combinations listed for Android and iOS.
+
+
+Browser and operating system support
+
+
+
+
+
+ Browser
+ Windows
+ Mac OS
+ Android
+ iOS
+
+
+
+
+ Google Chrome
+ Yes
+ Yes
+ Yes
+ Yes
+
+
+ Microsoft Edge
+ Yes
+ Yes
+
+
+ Mozilla Firefox
+ Yes
+ Yes
+ Yes
+
+
+ Apple Safari
+ N/A
+ Yes
+ N/A
+ Yes
+
+
+
+
+
+Representative mobile OS used in testing
+
+ - Android OS: 10+
+ - iOS: 15+
+
+Testing guidance
+
+ Use supported browsers and operating system versions when developing and testing services. If you
+ encounter a browser-specific issue, follow the
+ Verify a bug process.
+
+Verify a bug
+Follow this process when you encounter an issue with a Design System component.
+
+
+ These steps help confirm whether the issue is caused by the Design System, your product setup, or
+ custom code. This process applies to Angular and React implementations.
+
+
+1. Check versions
+Confirm you are using the latest version of:
+
+ - Web Components
+ - Angular or React
+
+
+ If you are not using the latest version, upgrade and retest. If the issue remains, continue to the next step.
+
+
+2. Test with product templates
+Use the official Angular or React product templates to isolate the issue.
+
+This helps determine whether the issue exists outside your project configuration.
+
+3. Recreate the issue
+Create a minimal test environment.
+
+ - Use only the code required for the example to function
+ - Include only the component experiencing the issue
+ - Remove unrelated dependencies or custom logic
+
+Confirm whether the issue can be replicated.
+
+4. Share and report
+If you can reproduce the issue:
+
+ - Share the template application link in the #design-system-support Slack channel
+ - Provide a link to your repository so the team can review and replicate the issue
+
+
+ Following these steps will help to ensure efficient investigation and quicker resolution of
+ design system component issues.
+
+Dark mode theme
+
+ Toggle light and dark mode using the React useTheme hook or the Angular
+ GoabThemeService. The user's choice persists across sessions.
+
+
+
+
+ Dark mode is still being tested. The CSS API and tokens may evolve as we iterate.
+
+
+
+
+
+ Theme switching requires @abgov/design-tokens version 2.8.0 or
+ higher with the dark theme stylesheet imported. See Setup
+ for installation steps.
+
+
+
+How it works
+
+ Both the React provider and the Angular service write a data-theme
+ attribute on the document root (<html>). Design tokens scoped
+ to :root[data-theme="dark"] activate via CSS cascade,
+ automatically applying dark colors to every component without re-rendering.
+
+
+Initial mode priority
+
+ On first load, the active mode is resolved in this order:
+
+
+ - The user's previously chosen mode, read from local storage
+ - The operating system preference (light or dark)
+ - The framework default (light)
+
+
+React
+
+ The React package exposes a context provider and a hook.
+
+
+1. Wrap your app with GoabThemeProvider
+
+ Place the provider near the top of your app, alongside other framework
+ providers such as BrowserRouter:
+
+{`// main.tsx
+import { GoabThemeProvider } from "@abgov/react-components";
+import { BrowserRouter } from "react-router-dom";
+import "@abgov/design-tokens/dist/tokens.css";
+import "@abgov/design-tokens/dist/dark-theme.css";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+
+
+
+ ,
+);`}
+
+2. Read and toggle theme with useTheme
+
+ Inside any component below the provider, call useTheme() to read
+ the current mode and switch theme:
+
+{`import { GoabButton, useTheme } from "@abgov/react-components";
+
+function ThemeToggle() {
+ const { mode, toggle } = useTheme();
+ const isDark = mode === "dark";
+
+ return (
+
+ {isDark ? "Light mode" : "Dark mode"}
+
+ );
+}`}
+
+API
+{`interface GoabThemeContextValue {
+ /** Current theme mode. */
+ mode: "light" | "dark";
+ /** Set theme to a specific mode. */
+ setMode: (next: "light" | "dark") => void;
+ /** Flip between light and dark. */
+ toggle: () => void;
+}
+
+interface GoabThemeProviderProps {
+ children: ReactNode;
+ /** Initial mode used when no stored or system preference is found. @default "light" */
+ defaultMode?: "light" | "dark";
+}`}
+
+
+
+ useTheme throws if called outside of GoabThemeProvider.
+
+
+
+Angular
+
+ The Angular package exposes a root-provided service backed by a Signal.
+
+
+1. Import the dark theme stylesheet
+
+ Add the import to your global stylesheet (typically src/styles.css):
+
+@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+@import "@abgov/design-tokens/dist/dark-theme.css";
+
+2. Inject GoabThemeService
+
+ The service is provided in root, so inject it from any component or service:
+
+{`// app.component.ts
+import { Component, inject } from "@angular/core";
+import { GoabThemeService } from "@abgov/angular-components";
+
+@Component({
+ selector: "app-root",
+ templateUrl: "./app.component.html",
+})
+export class AppComponent {
+ readonly theme = inject(GoabThemeService);
+
+ toggleTheme() {
+ this.theme.toggle();
+ }
+}`}
+
+3. Bind to the signal in templates
+
+ Read theme.mode() as a signal — Angular tracks the dependency
+ automatically and re-renders when the mode changes:
+
+{`
+
+ {{ theme.mode() === "dark" ? "Light mode" : "Dark mode" }}
+ `}
+
+API
+{`@Injectable({ providedIn: "root" })
+class GoabThemeService {
+ /** Read-only signal — use in templates: theme.mode() === "dark". */
+ readonly mode: Signal<"light" | "dark">;
+ /** Set theme to a specific mode. */
+ setMode(next: "light" | "dark"): void;
+ /** Flip between light and dark. */
+ toggle(): void;
+}`}
+
+Custom styling for dark mode
+
+ If you're using design system components, they handle dark mode automatically.
+
+
+ If your custom CSS uses design system tokens, dark mode is handled too. The tokens cascade to their dark values when data-theme="dark" is active.
+
+{`.my-card {
+ background-color: var(--goa-color-surface-card);
+}`}
+
+ Always verify in both modes.
+
+
+ If your custom CSS uses values that aren't from our design tokens (specific colors, backgrounds, hardcoded styles), those won't switch on their own. You can either swap them out for design tokens where possible, or extend dark mode by setting up your own custom property and overriding it under :root[data-theme="dark"]:
+
+{`/* Default (light) value */
+:root {
+ --my-card-background: #f9f9f9;
+}
+
+/* Dark mode value */
+:root[data-theme="dark"] {
+ --my-card-background: #1a1a1a;
+}
+
+/* Use it in your component */
+.my-card {
+ background-color: var(--my-card-background);
+}`}
+
+Using design tokens in SCSS
+
+
+
+ Dark theme support requires CSS custom properties. Sass variables
+ ({`$goa-*`}) are inlined at compile time and cannot flip when the
+ theme changes. Reference tokens via {`var(--goa-*)`} wherever a
+ value should respond to theme switching.
+
+
+
+
+ The simplest setup imports only tokens.css and uses
+ {`var(--goa-*)`} everywhere — every token automatically participates
+ in theme switching, and there is one syntax to remember.
+
+{`@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+@import "@abgov/design-tokens/dist/dark-theme.css";`}
+{`.my-card {
+ background: var(--goa-color-surface-card);
+ font-family: var(--goa-font-family-sans);
+ padding: var(--goa-space-m);
+ transition-duration: var(--goa-motion-duration-medium-2);
+}`}
+
+When you need Sass variables
+
+ Some workflows need Sass arithmetic, mixins, or functions over token values
+ (for example {`$goa-space-m * 2`}). In that case, import
+ tokens.scss alongside the CSS files and use {`$goa-*`}
+ for compile-time values only — never for colors, surfaces, or anything that
+ should flip with theme.
+
+{`@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+@import "@abgov/design-tokens/dist/dark-theme.css";
+@import "@abgov/design-tokens/dist/tokens.scss";`}
+{`.my-card {
+ // Theme-responsive — must use var()
+ background: var(--goa-color-surface-card);
+
+ // Compile-time only — Sass arithmetic OK
+ padding: $goa-space-m * 2;
+ border-radius: $goa-border-radius-m;
+}`}
diff --git a/docs/src/content/get-started/developers/setup.mdx b/docs/src/content/get-started/developers/setup.mdx
new file mode 100644
index 0000000000..3eda4feeca
--- /dev/null
+++ b/docs/src/content/get-started/developers/setup.mdx
@@ -0,0 +1,128 @@
+---
+id: developers/setup
+title: Developer setup
+navLabel: Setup
+description: Set up Angular, React, or Web Components to use the GoA Design System
+section: developers
+order: 2
+status: published
+---
+import DropInCallout from "../../../components/DropInCallout.astro";
+
+Developer setup
+Set up the Government of Alberta Design System in Angular, React, or directly with Web Components.
+
+Angular UI components
+
+ Supported versions: 18, 19, 20, 21
+
+
+ This is the web component library and utilizes Angular's web component
+ integration.
+
+
+1. Add dependencies
+npm i @abgov/web-components
+npm i @abgov/angular-components
+npm i @abgov/ui-components-common
+npm i @abgov/design-tokens
+
+2. Link ionicons in app/index.html
+
+ Add the following in the head element:
+
+{`
+`}
+
+3. Update src/app/app.module.ts
+
+ Update src/app/app.module.ts as per the four steps below:
+
+{`// 1. Import the CUSTOM_ELEMENTS_SCHEMA
+import { CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
+
+// 2. Import the libs
+import "@abgov/web-components";
+import { AngularComponentsModule } from "@abgov/angular-components";
+
+@NgModule({
+ declarations: [AppComponent],
+ imports: [
+ // 3. Add the needed imports
+ BrowserModule,
+ AngularComponentsModule,
+ ],
+ providers: [],
+ bootstrap: [AppComponent],
+ // 4. Add the CUSTOM_ELEMENTS_SCHEMA to the NgModule
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ })
+export class AppModule {}`}
+
+4. Add the styles link in src/styles.css
+@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+
+React UI components
+
+ Supported versions: 17, 18, 19
+
+
+ This library contains React components which wrap the Government of Alberta Web
+ Components.
+
+
+1. Add dependencies
+npm i @abgov/react-components
+npm i @abgov/web-components
+npm i @abgov/ui-components-common
+npm i @abgov/design-tokens
+
+2. Link ionicons in app/index.html
+
+ Add the following to the head element:
+
+{`
+`}
+
+3. Import the web components in src/main.tsx
+import "@abgov/web-components";
+
+4. Import the styles in src/index.css
+@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+
+Web components
+
+ This library contains web components from the Government of Alberta.
+
+
+1. Add dependencies
+npm i @abgov/web-components
+npm i @abgov/design-tokens
+
+2. Link ionicons in index.html
+
+ Add the following in the head element:
+
+{`
+`}
+
+3. Import the web components into src/main.js
+import "@abgov/web-components";
+
+4. Add the styles link in your main CSS file
+
+ Add the following in src/assets/main.css or wherever your main CSS file is
+ located:
+
+@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+
+Technologies
+An overview of the technologies used in the Design System.
+
+How the technologies fit together
+
+ The Design System is built on Web Components. Most component functionality lives in the core Web
+ Components layer. Angular and React wrappers sit on top of that layer to make the components easier
+ to use in those frameworks.
+
+
+ We use Svelte to author the components that are compiled to custom elements. You can use the Design
+ System through the core Web Components or through Angular and React wrappers.
+
+
+Web Components
+
+ Web Components
+ are a set of standard web technologies that allow you to create reusable custom elements. Each component
+ includes its own structure, styling, and behaviour. This keeps it independent from the rest of your code.
+
+
+ In the Design System, Web Components are the core library. They are framework-agnostic, so teams
+ can use them in different front-end environments.
+
+
+Benefits of using Web Components
+
+ - Reuse: Build once and use across pages, applications, and frameworks
+ - Browser support: Work in modern browsers without additional libraries
+ - Maintenance: Modular and self-contained structure simplifies updates
+ - Encapsulation: Structure, style, and behaviour remain isolated from other page elements
+ - Reliability: Code is not spread across HTML and JS files, thereby avoiding inconsistencies
+ - Flexibility: Use inline, import, or compile components as needed
+ - Composability: Combine components or integrate them with other components
+
+
+
+ Do not use Web Components directly unless there is a specific reason to do so. Using wrappers provides type checking and developer helpers that are not available when working with the core Web Components alone.
+
+Svelte
+
+ Svelte is the framework used to generate the
+ Design System Web Components. Svelte combines JavaScript (logic), HTML (structure), and CSS (style)
+ within a single file. It compiles these into efficient, reusable components.
+
+Why Svelte
+We use Svelte to:
+
+ - Build reusable Web Components
+ - Keep component logic, structure, and styling together
+ - Support integration with multiple front-end frameworks
+
+Angular
+
+
+ Supported versions: 18, 19, 20, 21
+
+
+
+ Angular is a TypeScript-based framework for building
+ web applications. The Design System supports Angular through Angular wrappers around the core Web Components.
+
+
+How Web Components and Angular work together
+Angular wrappers are created around the Web Components. These wrappers:
+
+ - Manage component properties and events
+ - Support form binding (Reactive and Template-driven)
+ - Allow integration within Angular applications
+
+The Angular application interacts with the wrapper, which renders the underlying Web Component.
+React
+
+
+ Supported versions: 17, 18, 19
+
+
+
+ React is an open-source JavaScript library used to
+ build user interfaces from reusable components.
+
+
+How Web Components and React work together
+React wrappers are created around the Web Components. These wrappers:
+
+ - Manage properties and events
+ - Enable integration within React applications
+
+The React application interacts with the wrapper, which renders the underlying Web Component.
+Updating your product
+The updated design system includes a new design language, updated design tokens and components, and new templates. For your product, updating means:
+
+ - Your service stays aligned with the current GoA standard as more services update and users move between them
+ - You get access to new component properties, examples, and templates that reduce build time for common service types
+ - Your product remains supported — the legacy design system stops receiving fixes after September 2026
+
+
+ Most of the update applies automatically. Most of the work will be reviewing what changed in
+ your product and deciding where design follow-up is needed. These steps help you work through
+ the process.
+
+
+Use the developer-first approach
+
+ The developer-first approach lets you see what actually changed in your product before
+ committing to design work.
+
+
+ When you run the update first, spacing, typography, and token changes apply automatically. You
+ can then review the result with your team and focus design and development effort on the screens
+ that need it most. This avoids redesigning screens based on assumptions about what will change
+ before you update.
+
+
+Migration walkthrough
+
+ The migration walkthrough steps through four stages — legacy design system, upgrade applied,
+ layout and styling fixes, and custom component updates — and shows the visual impact on your
+ interface at each stage. The walkthrough covers both public form and workspace product types.
+ Review it with your team before you start: it helps designers and developers see where changes
+ occur, and gives product owners a clearer picture of the scope for planning.
+
+
+ Explore the migration walkthrough
+
+
+Why we recommend updating all at once
+
+ Applying the update to some parts of your product but not others tends to cause the update to
+ stall. Teams focus on a few components then deprioritize the rest, leaving the product in a
+ mixed state that becomes harder to resolve over time. Reviewing your updated application
+ together in step 3 is designed to address this. Reviewing the full update in a branch before
+ committing gives your team a clear picture of the actual work involved. Use that branch to plan
+ your migration window — you are not committing to proceeding until you are ready.
+
+
+Migration steps
+
+Step 1: Create a branch
+
+ Create a dedicated branch for the update. Keeping it separate from your regular development
+ work lets your team review the changes before merging.
+
+git checkout -b ds-migration
+Use a branch name that works for your team — this is just an example.
+
+Step 2: Run the version update
+
+ Follow the steps in Setup to install the
+ updated packages. Run your application after installing the updates. Do this before making any
+ other changes.
+
+
+Step 3: Review the updated application as a team
+
+ Walk through your application with your product team. At this stage, the team will identify
+ what needs attention and decide what to prioritize.
+
+What to look for:
+
+
+
+
+
+ Area
+ What to look for
+
+
+
+
+ Spacing and layout
+ Screens that feel too tight or unbalanced
+
+
+ Typography
+ Headings or body text that look off in size or weight
+
+
+ Dense or data-heavy screens
+ These carry the most risk during an update and often need the most follow-up
+
+
+ Custom components
+ Anything built outside the design system that needs manual alignment
+
+
+
+
+
+
+ Record what you find. A list of screens and issues is enough at this stage. Your designers and
+ product owner can use that output to plan and prioritize work.
+
+
+Understanding the effort
+
+ There is no single estimate for how long a migration takes. It varies depending on your
+ product. The main factors are:
+
+
+
+
+
+
+ Factor
+ Impact on migration effort
+
+
+
+
+ App size
+ More screens means more to test and review after the update
+
+
+ Design system utilization
+ Products with more custom code need more manual alignment
+
+
+ Developer familiarity
+ Developers with more design system experience move faster through the migration steps
+
+
+
+
+
+
+ Use the team review of your updated application in step 3 to build a realistic estimate for
+ your own product before committing to a timeline.
+
+
+Getting help
+
+ - Bring what you find when reviewing your updated application to drop-in hours to get feedback on what to prioritize
+ - If you find a problem with the design system itself, reach out on the support channel rather than working around it
+
+
+Start with the design system
+Start with the design system to build on the research and experience of other service teams. This helps you avoid repeating work that has already been done.
+
+
+ The design system gives you a strong foundation for common service needs. It allows your team to focus on the specific challenges of your product.
+ Build on it. Do not start from scratch.
+
+
+Design system by role
+
+
+
+Why start with the design system?
+
+Streamline collaboration
+
+ Designers and developers work from shared components and guidance. This reduces rework and misalignment.
+
+
+Improve accessibility
+Accessibility is built into both the design and coded components.
+
+Reduce testing effort
+Components are tested across devices, browsers, and service contexts.
+
+Maintain consistency
+
+ Components align with the broader system to create a cohesive user experience across government services.
+
+
+Spend more time on high-value work
+Using existing components saves time. You can focus on work that improves service quality, including:
+
+ - Usability testing
+ - User research
+ - Content design
+ - Accessibility reviews
+ - Design quality checks
+ - Low-fidelity prototyping and testing
+
+This leads to better outcomes for users.
+How to use the design system in your service
+Follow these steps when designing and building your service.
+
+Use system components first
+Start with existing components and patterns. These meet most user needs.
+
+Identify gaps through user testing
+Test your service with users. Identify needs that are not covered by current components.
+
+Before you design something new
+
+ Check what's already available and what's in progress. The team can point you to existing components,
+ solutions other teams have built, and planned work that may meet your need.
+
+
+Design and test new solutions when you need them
+
+ If you still have a gap, design a new solution and test it with users. Move forward only when
+ testing shows clear user value.
+
+
+Share what you learn
+
+ Share your findings with the design system team. Your solution may become part of the design system.
+
+
+
+ Do not create custom components without a clear user need.
+ Unnecessary customization:
+
+ - Increases maintenance effort
+ - Slows delivery
+ - Reduces consistency
+
+ Always confirm the need through research and testing.
+
+
+
+ View the design system governance process
+
+Migration guide
+Design System 2.0 (DS 2.0) becomes the Government of Alberta standard in March 2026. New products starting after launch should use DS 2.0. Existing active products should plan their move to DS 2.0 during the recommended migration window, which runs from March 2026 to September 2026.
+
+Migration pathways
+The right migration path depends on your product's context, including team funding and capacity, other delivery obligations, product lifecycle, and the effort required to update. The three pathways are standard migration, late migration, and no migration.
+
+Starting a new product
+If your product starts after March 2026, start with DS 2.0. Migration pathways apply to existing products moving from DS 1.x to DS 2.0.
+
+Compare the pathways
+
+
+
+
+
+ Pathway
+ Use it when
+ Recommendation
+
+
+
+
+ Standard migration Your product has an active funded team and can migrate by September 2026 Recommended default
+
+ Late migration Your team cannot meet the standard window because of delivery timelines, dependencies, or capacity constraints Only when necessary
+
+ No migration Your product does not have an active funded team and/or is not in a position to upgrade Only in specific cases
+
+
+
+
+
+Standard migration
+Standard migration is the default pathway for active products.
+Choose this path if your product has an active funded team and can schedule migration work between March 2026 and September 2026. This is the recommended path for most teams because it keeps your product aligned with the current standard and gives you the best support.
+Use this pathway when:
+
+ - your product is actively maintained
+ - your team can reserve time to migrate by September 2026
+ - you want access to the latest templates, components, tokens, and guidance
+
+Plan for work across the product team. Typical upgrade tasks include the library updates, adjusting spacing and typography, and updating custom code to align with the DS 2.0 visual design. This is a significant update and will usually involve design, development, and testing.
+
+Late migration
+Late migration is a last-resort pathway for active products.
+Choose this path only when delivery deadlines, dependencies, or capacity constraints make the standard migration window unrealistic. This path gives your team more time, but it also increases risk and reduces your ongoing support.
+Use this pathway when:
+
+ - a major delivery deadline blocks migration work
+ - critical dependencies prevent the upgrade during the standard window
+ - capacity or funding makes the standard window unrealistic
+
+Delaying migration means your product will wait longer to benefit from DS 2.0 improvements. Over time, unresolved issues will accumulate and your product will be inconsistent with the new standard for longer.
+
+No migration
+No migration is an opt-out pathway for specific situations.
+Choose this path only when your product does not have an active funded team and/or is not in a position to upgrade. In these cases, the product may remain on DS 1.x.
+Teams on this path should understand that the product will not receive DS 2.0 improvements and will not align with the current standard. Support for DS 1.x is limited from March to September and ends after September 2026.
+
+What changes after launch
+After the DS 2.0 launch in March 2026:
+
+ - New products should use DS 2.0
+ - Active products should aim to migrate by September 2026
+ - After launch, web components will move to version 2.x. Although this is a major version update, it does not include breaking changes.
+ - Angular 4.x and React 6.x receive limited fixes or features from March to September
+ - Support for DS 1.0 ends after September 2026
+ - Web components will update to a new major version after September 2026
+
+
+How to choose a pathway
+Use these questions to guide your decision:
+
+ - Is this a new product starting after March 2026?
+ - Does the product have an active funded team?
+ - Can the team schedule migration work before September 2026?
+ - Are there delivery deadlines or dependencies that block the standard window?
+ - Is the team prepared to accept reduced support and higher maintenance risk if migration is delayed?
+
+
+Related guidance
+
+ Review the setup steps for developers
+
diff --git a/docs/src/content/get-started/out-of-support.mdx b/docs/src/content/get-started/out-of-support.mdx
new file mode 100644
index 0000000000..fa61fea200
--- /dev/null
+++ b/docs/src/content/get-started/out-of-support.mdx
@@ -0,0 +1,43 @@
+---
+id: out-of-support
+title: Out of support versions
+description: Design System versions that are no longer supported
+section: appendix
+order: 3
+status: published
+---
+import { withBase } from "@/lib/base-url";
+import DropInCallout from "../../components/DropInCallout.astro";
+
+Out-of-support versions
+With the launch of the new Design System, support for Angular v4 and lower, and React v6 and lower is significantly reduced.
+
+What this means
+
+Fewer fixes or patches
+Bug fixes and security updates are no longer prioritized for these versions.
+
+No new features
+All new features and enhancements are released only in the current major version.
+
+Use at your own risk
+Existing projects may continue to run. However:
+
+ - Compatibility with new browsers or operating systems is not guaranteed
+ - Compatibility with future framework updates is not guaranteed
+ - Issues discovered in these versions will not be resolved
+
+
+
+ Projects using Angular v4 and lower, and React v6 and lower will continue to function. New issues or defects identified in these versions may not be fixed.
+
+What to do next
+
+ Upgrade to the latest supported version. Refer to the
+ Developer setup page.
+
+
+ If you need support planning your upgrade,
+ book time in drop-in hours.
+
+QA testing
+This page outlines the testing process for the Design System. The process ensures components function correctly and integrate within products.
+
+Testing objectives
+QA testing ensures that:
+
+ - Coded components match the design specifications
+ - Components work in both React and Angular implementations
+ - Components are responsive across screen sizes
+ - Components meet accessibility requirements
+ - Mobile behaviour is validated
+ - Documentation on the Design System website is accurate
+
+Test cases
+
+Component testing
+
+ - Confirm the rendered component matches design and styling guidelines
+ - Confirm configured properties display correctly
+ - Confirm the expected event triggers when interacting with the component
+
+
+Responsiveness testing
+
+ - Test components on mobile, tablet, and desktop screen sizes
+ - Use browser developer tools to simulate devices
+
+
+Accessibility testing
+
+ - Run Lighthouse audits to review accessibility scores
+ - Confirm appropriate ARIA (Accessible Rich Internet Applications) roles and labels
+ - Test keyboard navigation
+ - Test with NVDA screen reader
+
+
+Cross-browser testing
+
+ - Test on the latest versions of Chrome, Firefox, Safari, and Edge
+ - Use Chrome device mode to simulate mobile environments
+ - Confirm consistent appearance and behaviour across browsers
+
+
+Bug testing
+When a bug is fixed:
+
+ - Reproduce the issue using the main branch.
+ - Verify the fix in the pull request branch.
+ - Retest the component across all relevant areas.
+
+Confirm the issue no longer occurs.
+Reporting
+
+ - Document updated test results, findings, and screenshots in the pull request comments
+ - Log newly discovered issues in GitHub
+
+Roadmap
+A high-level summary of the work the design system team plans to focus on in the 2026-27 Fiscal Year.
+
+The roadmap is subject to change as we gather new information. We will communicate updates to ensure product teams can align and plan their work accordingly.
+
+For more details on our priorities and day-to-day activities, see our design system backlog.
+
+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.
+
+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.
+Examples:
+
+ Create a mechanism to reliably collect and report adoption rate Track upgrade progress against the adoption schedule Capture qualitative signals from teams (developer and designer feedback themes) Capture end-user feedback where available (citizen or worker satisfaction, accessibility and usability feedback)
+
+Product acceleration enablement
+Objective: Provide prescriptive guidance and resources that help teams get to screens, prototypes, and working experiences faster using DS 2.0.
+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 Provide contextual starting points for teams using Public form and Workspace templates Pilot DS 2.0 with teams to generate strong examples to share Create and publish migration success stories
+
+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.
+Examples:
+
+ Define the initial MCP scope and supported design system resources Stand up the MCP server and validate the hosting and maintenance approach Test the MCP use in real product workflows and capture gaps to address 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.
+Examples:
+
+ Define what "official Vue support" means Outline the minimum supportable scope Identify implications for documentation, maintenance, testing, and support
+
+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:
+
+ Build the review, revise, resubmit feature
+
+Examples and pattern maturity
+Objective: Expand and refine examples and position them as adaptable reusable patterns that teams can apply with confidence.
+Benefit: Improves self-serve success and product consistency, reducing implementation variance and support demand over time.
+Examples:
+
+ Continue expanding and refining examples Show how components and examples combine into larger contexts and workflows
+
+Library packaging and tech stack upgrades
+Objective: Reduce friction in how design system assets are bundled and adopted across libraries and update important tech stacks.
+Benefit: Lowers setup and upgrade complexity, and keeps the design system up to date with the latest supported versions.
+Examples:
+
+ Improve how code libraries are bundled together (React, web components, tokens) 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.
+
+Documentation and communications improvements
+Objective: Improve how teams access and understand design system guidance, and communicate design system value areas like accessibility more clearly.
+Benefit: Increases trust, improves reuse, and supports self-serve adoption by making guidance easier to consume and share.
+Examples:
+
+ Add markdown file download to website documentation 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.
+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:
+
+
+ Focus migration support on late adopters facing systemic barriers to upgrading
diff --git a/docs/src/content/productTypes/public-form/index.mdx b/docs/src/content/productTypes/public-form/index.mdx
new file mode 100644
index 0000000000..d74d27da0b
--- /dev/null
+++ b/docs/src/content/productTypes/public-form/index.mdx
@@ -0,0 +1,166 @@
+---
+id: public-form
+title: Public form
+summary: For citizen-facing services where users apply for a benefit, request a service, or submit information. Designed around simplicity and low cognitive load, with plain-language questions, focused pages that ask one thing at a time, save-and-resume, and a clear confirmation of what happens next.
The reference example is a starting point to expand on, not a rigid template. Adapt it to fit each service's context.
+heroImage: /images/examples/my-applications-page.png
+demoUrl: https://digital-service-demo-v2.netlify.app/
+tags:
+ - form
+ - public
+ - citizen
+ - pattern
+components: []
+status: published
+---
+
+View demo
+
+import PreviewContainer from "../../../components/PreviewContainer.astro";
+
+Primary user: Citizens applying for a service, benefit, permit, or status update.
+
+## Pages
+
+A public form is built from a small set of page types. Combine and adapt them to fit the work the service supports.
+
+### Start page
+
+The starting point for a citizen to begin your form from within your service or from Alberta.ca.
+
+
Workspaces should be adapted to fit each service's context and user needs. The reference example is a starting point to expand on, not a rigid template.
+heroImage: /thumbnails/workspace-preview.png
+demoUrl: https://digital-service-demo-v2.netlify.app/workspace
+sourceUrl: https://github.com/GovAlta/goa-workspace-playground
+tags:
+ - workspace
+ - worker
+ - service
+ - case-management
+ - dashboard
+ - pattern
+components:
+ - work-side-menu
+ - table
+ - badge
+ - tabs
+ - container
+ - accordion
+ - drawer
+ - button
+ - block
+status: published
+---
+
+View demo
+
+import LinkCard from "../../../components/LinkCard.astro";
+import PreviewContainer from "../../../components/PreviewContainer.astro";
+
+
+ Primary user: Service delivery staff
+
+## Pages
+
+Combine and adapt these to fit the work your service supports.
+
+### Dashboard
+
+The landing view of a workspace, showing staff their counts, trends, and assigned work.
+
+
+
+
+
+
+
+
+
+
+
+
+
+### Sidebar navigation
+
+Use the [work side menu](/components/work-side-menu) as the primary navigation for a workspace.
+
+Keep top-level navigation focused on the main areas of work. When a user opens a record or case, switch to contextual navigation that supports that task. This puts the user into a focused mode with relevant navigation items (like sections of an application, comments, reminders) and a back link to return to the main view. The sidebar can adapt to what the user is doing, it doesn't have to show everything at once.
+
+
+
+
+ Main workspace navigation
+
+
+
+
+
+ Contextual case navigation
+
+
+
+
+
+### Sticky action bar
+
+A scroll-aware header that pins to the top of the content area as the user scrolls. Use it to keep the most important tools visible.
+
+Set the content for each page based on the task:
+
+- On a cases list page, keep tools such as search and key actions visible.
+- On a detail page, keep the case name and key actions visible.
+
+Do not pin everything. Keep only the information and actions people need to continue their work without losing context.
+
+
+
+### Push drawer
+
+Use a [push drawer](/components/push-drawer) for focused work that should happen without leaving the current page.
+
+This works well for actions such as:
+
+- approving or denying a record
+- requesting more information
+- completing a short decision form
+- reviewing supporting details while taking action
+
+Use it when users need to keep the main record in view while completing the task.
+
+
+
+---
+
+## Components built for workspace
+
+Workspace patterns are supported by component features designed for denser, more productive interfaces:
+
+- **Compact inputs.** Every input component now has a `compact` variant that reduces height and spacing. This lets you build tighter forms and toolbars without sacrificing usability.
+- **Compact badges and notifications.** [Badges](/components/badge) and [notification banners](/components/notification) also have compact sizing to fit within dense data views and action bars.
+- **Badge variants.** [Badges](/components/badge) now include `strong` and `subtle` emphasis options, giving you control over visual weight depending on context.
+- **Data grid.** The [data grid](/components/data-grid) works with the table component to support accessible, keyboard-navigable data views. Use them together when the user needs to move through records efficiently without relying on a mouse.
+- **Segmented tabs.** A new [tab](/components/tab) variant that works as a segmented toggle for switching between views or modes within a workspace, rather than navigating between pages.
+- **Enhanced filter chips.** [Filter chips](/components/filter-chip) now support secondary text and secondary icons, making them more useful for richer filtering in workspace data views.
+
+---
+
+## Keyboard-accessible data views
+
+Workspace data views use the [data grid](/components/data-grid) to make table and card layouts fully keyboard navigable. Users can use arrow keys to move between cells and rows, making it possible to scan and act on records without a mouse. This is especially important in workspace contexts where staff are processing high volumes of cases and keyboard navigation is significantly faster than clicking. For assistive technology users, screen readers announce cell content and position as the user navigates.
+
+---
+
+## When to use
+
+Use the workspace when your service needs to support regular, task-based work, such as:
+
+- Reviewing and processing submissions
+- Managing case files, applications, or requests
+- Moving between dashboards, lists, and detail views
+- Taking actions such as approve, deny, assign, or request more information
+
+## When not to use
+
+- Citizen-facing services. Use the [public form](/examples/public-form) pattern instead.
+- Content-only pages that do not involve case management.
+- Simple internal tools that do not need structured case processing.
+
+---
+
+## Get started
+
+Use one of the workspace templates as a starting point for your service. Each template includes the sidebar navigation, dashboard, data views, and case detail patterns described above.
+
+
+
Applications are typically processed within 10 business days.
+ `,
+ },
+ },
+ {
+ id: "filled",
+ name: "Filled accordion",
+ description: "Single accordion with filled type",
+ code: {
+ react: `
+ You will need to provide proof of identity, proof of address,
+ and any relevant supporting documentation.
+ `,
+ angular: `
+ You will need to provide proof of identity, proof of address,
+ and any relevant supporting documentation.
+ `,
+ webComponents: `
+ You will need to provide proof of identity, proof of address,
+ and any relevant supporting documentation.
+ `,
+ },
+ },
+ {
+ id: "actions",
+ name: "Accordion with actions",
+ description: "Accordion with actions slot content",
+ code: {
+ react: `
+
+ View all
+
+
+ }
+>
+
+ This example mixes badges and controls inside the actions slot.
+
+ `,
+ angular: `
+
+ This example mixes badges and controls inside the actions slot.
+
+
+
+
+
+ View all
+
+ `,
+ webComponents: `
+
+ This example mixes badges and controls inside the actions slot.
+
+
+
+ View all
+
+
`,
},
},
diff --git a/docs/src/data/configurations/index.ts b/docs/src/data/configurations/index.ts
index d01d86eaa0..cbfbe46429 100644
--- a/docs/src/data/configurations/index.ts
+++ b/docs/src/data/configurations/index.ts
@@ -54,6 +54,7 @@ export { sideMenuConfigurations } from "./side-menu";
export { sideMenuGroupConfigurations } from "./side-menu-group";
export { sideMenuHeadingConfigurations } from "./side-menu-heading";
export { workSideMenuConfigurations } from "./work-side-menu";
+export { workSideNotificationPanelConfigurations } from "./work-side-notification-panel";
export { menuButtonConfigurations } from "./menu-button";
export { appHeaderConfigurations } from "./app-header";
export { appHeaderMenuConfigurations } from "./app-header-menu";
@@ -122,6 +123,7 @@ import { sideMenuConfigurations } from "./side-menu";
import { sideMenuGroupConfigurations } from "./side-menu-group";
import { sideMenuHeadingConfigurations } from "./side-menu-heading";
import { workSideMenuConfigurations } from "./work-side-menu";
+import { workSideNotificationPanelConfigurations } from "./work-side-notification-panel";
import { menuButtonConfigurations } from "./menu-button";
import { appHeaderConfigurations } from "./app-header";
import { appHeaderMenuConfigurations } from "./app-header-menu";
@@ -196,6 +198,7 @@ export const configurationRegistry: ConfigurationRegistry = {
"side-menu-group": sideMenuGroupConfigurations,
"side-menu-heading": sideMenuHeadingConfigurations,
"work-side-menu": workSideMenuConfigurations,
+ "work-side-notification-panel": workSideNotificationPanelConfigurations,
"menu-button": menuButtonConfigurations,
"app-header": appHeaderConfigurations,
"app-header-menu": appHeaderMenuConfigurations,
diff --git a/docs/src/data/configurations/push-drawer.ts b/docs/src/data/configurations/push-drawer.ts
index f0d2a3ffb4..923e112b17 100644
--- a/docs/src/data/configurations/push-drawer.ts
+++ b/docs/src/data/configurations/push-drawer.ts
@@ -51,6 +51,7 @@ export const pushDrawerConfigurations: ComponentConfigurations = {
componentSlug: "push-drawer",
componentName: "Push Drawer",
defaultConfigurationId: "basic",
+ previewStyle: "padding: 0;",
configurations: [
{
diff --git a/docs/src/data/configurations/shared/shared-previews.ts b/docs/src/data/configurations/shared/shared-previews.ts
new file mode 100644
index 0000000000..7894d697e9
--- /dev/null
+++ b/docs/src/data/configurations/shared/shared-previews.ts
@@ -0,0 +1,22 @@
+/**
+ * Shared preview style/wrapper templates for ConfigurationPreview.
+ *
+ * Use these when a component is meant to be seen inside a larger product layout
+ * (e.g. work-side-menu and notification panel sit next to a workspace area).
+ *
+ * - previewStyle: CSS applied to the preview container (replaces inline cssText).
+ * - previewWrapper: HTML around the component. `{{slot}}` is replaced with the
+ * component code at render time. Only used in the preview, never in the code
+ * snippet shown to users.
+ */
+
+export const workspacePreviewStyle =
+ "background: var(--goa-color-greyscale-50, #f8f8f8); padding: 0; display: flex; min-height: 500px;";
+
+export const workspacePreviewWrapper = `{{slot}}
+
+
+ Dashboard
+ Welcome back.
+
+`;
diff --git a/docs/src/data/configurations/temporary-notification.ts b/docs/src/data/configurations/temporary-notification.ts
index 5c1bc5789e..23b64478c5 100644
--- a/docs/src/data/configurations/temporary-notification.ts
+++ b/docs/src/data/configurations/temporary-notification.ts
@@ -108,29 +108,40 @@ export class SomeOtherComponent {
{
id: "with-progress",
name: "Progress and indeterminate",
- description:
- "Notifications for loading states (note: progress and indeterminate types may have rendering issues)",
+ description: "Notifications for loading states",
code: {
react: ` {
- const uuid = TemporaryNotification.show("Uploading file...", { type: "progress" });
- TemporaryNotification.setProgress(uuid, 65);
+ const uuid = TemporaryNotification.show("Uploading file...", { type: "progress", duration: "long" });
+ // Simulate progress; in real usage, drive this from your operation's progress events.
+ let progress = 0;
+ const interval = setInterval(() => {
+ progress = Math.min(progress + 10, 100);
+ TemporaryNotification.setProgress(uuid, progress);
+ if (progress >= 100) clearInterval(interval);
+ }, 500);
}} mb="xs">Progress
{
- TemporaryNotification.show("Processing your request...", { type: "indeterminate" });
+ TemporaryNotification.show("Processing your request...", { type: "indeterminate", duration: "long" });
}}>Indeterminate `,
angular: {
ts: `import { TemporaryNotification } from "@abgov/ui-components-common";
export class SomeOtherComponent {
showProgress() {
- const uuid = TemporaryNotification.show("Uploading file...", { type: "progress" });
- TemporaryNotification.setProgress(uuid, 65);
+ const uuid = TemporaryNotification.show("Uploading file...", { type: "progress", duration: "long" });
+ // Simulate progress; in real usage, drive this from your operation's progress events.
+ let progress = 0;
+ const interval = setInterval(() => {
+ progress = Math.min(progress + 10, 100);
+ TemporaryNotification.setProgress(uuid, progress);
+ if (progress >= 100) clearInterval(interval);
+ }, 500);
}
showIndeterminate() {
- TemporaryNotification.show("Processing your request...", { type: "indeterminate" });
+ TemporaryNotification.show("Processing your request...", { type: "indeterminate", duration: "long" });
}
}`,
template: ` {
+ TemporaryNotification.show("Item moved to trash", {
+ type: "basic",
+ duration: "long",
+ actionText: "Undo",
+ action: () => {
+ console.log("Undo clicked");
+ },
+ });
+}}>Show notification `,
+ angular: {
+ ts: `import { TemporaryNotification } from "@abgov/ui-components-common";
+
+export class SomeOtherComponent {
+ showWithAction() {
+ TemporaryNotification.show("Item moved to trash", {
+ type: "basic",
+ duration: "long",
+ actionText: "Undo",
+ action: () => {
+ console.log("Undo clicked");
+ },
+ });
+ }
+}`,
+ template: `Show notification `,
+ },
+ webComponents: `Show notification
+
+`,
diff --git a/docs/src/data/configurations/types.ts b/docs/src/data/configurations/types.ts
index c73938b0e7..3bd0e0a7b9 100644
--- a/docs/src/data/configurations/types.ts
+++ b/docs/src/data/configurations/types.ts
@@ -94,6 +94,13 @@ export interface ComponentConfigurations {
/** Default configuration ID to show on page load */
defaultConfigurationId: string;
+ /** Optional inline CSS for the preview container (e.g. background color for workspace context) */
+ previewStyle?: string;
+
+ /** Optional HTML that wraps each config's webComponents code in the preview only (not shown in code snippet).
+ * Use {{slot}} as placeholder for the component code. */
+ previewWrapper?: string;
+
/** All available configurations */
configurations: ComponentConfiguration[];
}
diff --git a/docs/src/data/configurations/work-side-menu.ts b/docs/src/data/configurations/work-side-menu.ts
index bfb35371e1..bae643cbef 100644
--- a/docs/src/data/configurations/work-side-menu.ts
+++ b/docs/src/data/configurations/work-side-menu.ts
@@ -5,11 +5,14 @@
*/
import type { ComponentConfigurations } from "./types";
+import { workspacePreviewStyle, workspacePreviewWrapper } from "./shared/shared-previews";
export const workSideMenuConfigurations: ComponentConfigurations = {
componentSlug: "work-side-menu",
componentName: "Work side menu",
defaultConfigurationId: "basic",
+ previewStyle: workspacePreviewStyle,
+ previewWrapper: workspacePreviewWrapper,
configurations: [
{
@@ -49,7 +52,7 @@ export const workSideMenuConfigurations: ComponentConfigurations = {
{
id: "with-user-profile",
name: "With user profile",
- description: "Menu showing user name and role",
+ description: "Menu showing user name and role with an account menu",
code: {
react: `
-
-
- `,
+ angular: `
+
+
+
+ `,
webComponents: `
`,
},
},
diff --git a/docs/src/data/configurations/work-side-notification-panel.ts b/docs/src/data/configurations/work-side-notification-panel.ts
new file mode 100644
index 0000000000..ac467b5420
--- /dev/null
+++ b/docs/src/data/configurations/work-side-notification-panel.ts
@@ -0,0 +1,784 @@
+/**
+ * WorkSideNotificationPanel Component Configurations
+ *
+ * Notification center panel used within a work side menu item's popover.
+ */
+
+import type { ComponentConfigurations } from "./types";
+import { workspacePreviewStyle, workspacePreviewWrapper } from "./shared/shared-previews";
+
+export const workSideNotificationPanelConfigurations: ComponentConfigurations = {
+ componentSlug: "work-side-notification-panel",
+ componentName: "Notification panel",
+ defaultConfigurationId: "basic",
+ previewStyle: workspacePreviewStyle,
+ previewWrapper: workspacePreviewWrapper,
+
+ configurations: [
+ {
+ id: "basic",
+ name: "Basic notification panel",
+ description:
+ "Panel with a mix of read and unread notifications in a work side menu",
+ code: {
+ react: {
+ ts: `const initialItems: (GoabWorkSideNotificationItemProps & { id: string })[] = [
+ {
+ id: "1",
+ title: "New case assigned",
+ description: "Case #12345 has been assigned to you for review.",
+ timestamp: "2025-03-15T10:30:00Z",
+ type: "info",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "2",
+ title: "Document uploaded",
+ description: "A new document was uploaded to Case #12340.",
+ timestamp: "2025-03-15T09:15:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "3",
+ title: "Case resolved",
+ description: "Case #12330 has been marked as resolved.",
+ timestamp: "2025-03-14T16:00:00Z",
+ type: "success",
+ readStatus: "read",
+ priority: "normal",
+ },
+];
+
+const [items, setItems] = useState(initialItems);
+
+const handleMarkAllRead = () => {
+ setItems((items) => items.map((item) => ({ ...item, readStatus: "read" })));
+};
+
+const handleViewAll = () => {
+ console.log("view all");
+};
+
+const handleClick = (id: string) => {
+ setItems((items) =>
+ items.map((item) => (item.id === id ? { ...item, readStatus: "read" } : item)),
+ );
+};`,
+ jsx: ` navigate(path)}
+ primaryContent={
+ <>
+
+ {items.map(({ id, ...item }) => (
+ handleClick(id)}
+ />
+ ))}
+
+ }
+ />
+ }
+/>`,
+ },
+ angular: {
+ ts: `interface NotificationItem {
+ id: string;
+ title: string;
+ description: string;
+ timestamp: string;
+ type: GoabWorkSideNotificationItemType;
+ readStatus: GoabWorkSideNotificationReadStatus;
+ priority: GoabWorkSideNotificationPriority;
+}
+
+export class SomeOtherComponent {
+ items: NotificationItem[] = [
+ {
+ id: "1",
+ title: "New case assigned",
+ description: "Case #12345 has been assigned to you for review.",
+ timestamp: "2025-03-15T10:30:00Z",
+ type: "info",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "2",
+ title: "Document uploaded",
+ description: "A new document was uploaded to Case #12340.",
+ timestamp: "2025-03-15T09:15:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "3",
+ title: "Case resolved",
+ description: "Case #12330 has been marked as resolved.",
+ timestamp: "2025-03-14T16:00:00Z",
+ type: "success",
+ readStatus: "read",
+ priority: "normal",
+ },
+ ];
+
+ handleMarkAllRead() {
+ this.items = this.items.map((item) => ({ ...item, readStatus: "read" }));
+ }
+
+ handleViewAll() {
+ console.log("view all");
+ }
+
+ handleClick(id: string) {
+ this.items = this.items.map((item) =>
+ item.id === id ? { ...item, readStatus: "read" } : item,
+ );
+ }
+}`,
+ template: `
+
+
+
+
+
+
+
+ @for (item of items; track item.id) {
+
+ `,
+ },
+ webComponents: {
+ html: `
+
+
+
+
+ `,
+ js: `const panel = container.querySelector("goa-work-side-notification-panel");
+const items = container.querySelectorAll("goa-work-side-notification-item");
+
+items.forEach((item) => {
+ item.addEventListener("_click", () => {
+ item.setAttribute("read-status", "read");
+ });
+});
+
+panel.addEventListener("_markAllRead", () => {
+ items.forEach((item) => item.setAttribute("read-status", "read"));
+});
+
+panel.addEventListener("_viewAll", () => {
+ console.log("view all");
+});`,
+ },
+ },
+ },
+ {
+ id: "urgent-notifications",
+ name: "With urgent notifications",
+ description: "Menu with urgent priority notifications in the panel",
+ code: {
+ react: {
+ ts: `const initialItems: (GoabWorkSideNotificationItemProps & { id: string })[] = [
+ {
+ id: "1",
+ title: "System maintenance",
+ description: "Scheduled maintenance tonight at 11 PM. All services will be unavailable.",
+ timestamp: "2025-03-15T14:00:00Z",
+ type: "critical",
+ readStatus: "unread",
+ priority: "urgent",
+ },
+ {
+ id: "2",
+ title: "Deadline approaching",
+ description: "Case #12345 response is due in 2 hours.",
+ timestamp: "2025-03-15T12:00:00Z",
+ type: "warning",
+ readStatus: "unread",
+ priority: "urgent",
+ },
+ {
+ id: "3",
+ title: "New comment on case",
+ description: "A team member commented on Case #12340.",
+ timestamp: "2025-03-15T11:00:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+];
+
+const [items, setItems] = useState(initialItems);
+
+const handleMarkAllRead = () => {
+ setItems((items) => items.map((item) => ({ ...item, readStatus: "read" })));
+};
+
+const handleViewAll = () => {
+ console.log("view all");
+};
+
+const handleClick = (id: string) => {
+ setItems((items) =>
+ items.map((item) => (item.id === id ? { ...item, readStatus: "read" } : item)),
+ );
+};`,
+ jsx: ` navigate(path)}
+ primaryContent={
+ <>
+
+ {items.map(({ id, ...item }) => (
+ handleClick(id)}
+ />
+ ))}
+
+ }
+ />
+ }
+/>`,
+ },
+ angular: {
+ ts: `interface NotificationItem {
+ id: string;
+ title: string;
+ description: string;
+ timestamp: string;
+ type: GoabWorkSideNotificationItemType;
+ readStatus: GoabWorkSideNotificationReadStatus;
+ priority: GoabWorkSideNotificationPriority;
+}
+
+export class SomeOtherComponent {
+ items: NotificationItem[] = [
+ {
+ id: "1",
+ title: "System maintenance",
+ description: "Scheduled maintenance tonight at 11 PM. All services will be unavailable.",
+ timestamp: "2025-03-15T14:00:00Z",
+ type: "critical",
+ readStatus: "unread",
+ priority: "urgent",
+ },
+ {
+ id: "2",
+ title: "Deadline approaching",
+ description: "Case #12345 response is due in 2 hours.",
+ timestamp: "2025-03-15T12:00:00Z",
+ type: "warning",
+ readStatus: "unread",
+ priority: "urgent",
+ },
+ {
+ id: "3",
+ title: "New comment on case",
+ description: "A team member commented on Case #12340.",
+ timestamp: "2025-03-15T11:00:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ ];
+
+ handleMarkAllRead() {
+ this.items = this.items.map((item) => ({ ...item, readStatus: "read" }));
+ }
+
+ handleViewAll() {
+ console.log("view all");
+ }
+
+ handleClick(id: string) {
+ this.items = this.items.map((item) =>
+ item.id === id ? { ...item, readStatus: "read" } : item,
+ );
+ }
+}`,
+ template: `
+
+
+
+
+
+
+
+ @for (item of items; track item.id) {
+
+ `,
+ },
+ webComponents: {
+ html: `
+
+
+
+
+ `,
+ js: `const panel = container.querySelector("goa-work-side-notification-panel");
+const items = container.querySelectorAll("goa-work-side-notification-item");
+
+items.forEach((item) => {
+ item.addEventListener("_click", () => {
+ item.setAttribute("read-status", "read");
+ });
+});
+
+panel.addEventListener("_markAllRead", () => {
+ items.forEach((item) => item.setAttribute("read-status", "read"));
+});
+
+panel.addEventListener("_viewAll", () => {
+ console.log("view all");
+});`,
+ },
+ },
+ },
+ {
+ id: "notification-types",
+ name: "Notification type badges",
+ description: "All notification item type variants with their badge icons",
+ code: {
+ react: {
+ ts: `const initialItems: (GoabWorkSideNotificationItemProps & { id: string })[] = [
+ {
+ id: "1",
+ title: "New comment on case",
+ description: "A team member commented on Case #12340.",
+ timestamp: "2025-03-15T10:00:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "2",
+ title: "Case #12345 assigned",
+ description: "Case #12345 has been assigned to you for review.",
+ timestamp: "2025-03-15T09:00:00Z",
+ type: "info",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "3",
+ title: "Case resolved",
+ description: "Case #12330 has been marked as resolved.",
+ timestamp: "2025-03-15T08:00:00Z",
+ type: "success",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "4",
+ title: "Deadline approaching",
+ description: "Case #12345 response is due in 2 hours.",
+ timestamp: "2025-03-15T07:00:00Z",
+ type: "warning",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "5",
+ title: "System maintenance",
+ description: "Scheduled maintenance tonight at 11 PM. All services will be unavailable.",
+ timestamp: "2025-03-15T06:00:00Z",
+ type: "critical",
+ readStatus: "unread",
+ priority: "normal",
+ },
+];
+
+const [items, setItems] = useState(initialItems);
+
+const handleMarkAllRead = () => {
+ setItems((items) => items.map((item) => ({ ...item, readStatus: "read" })));
+};
+
+const handleViewAll = () => {
+ console.log("view all");
+};
+
+const handleClick = (id: string) => {
+ setItems((items) =>
+ items.map((item) => (item.id === id ? { ...item, readStatus: "read" } : item)),
+ );
+};`,
+ jsx: ` navigate(path)}
+ primaryContent={
+
+ {items.map(({ id, ...item }) => (
+ handleClick(id)}
+ />
+ ))}
+
+ }
+ />
+ }
+/>`,
+ },
+ angular: {
+ ts: `interface NotificationItem {
+ id: string;
+ title: string;
+ description: string;
+ timestamp: string;
+ type: GoabWorkSideNotificationItemType;
+ readStatus: GoabWorkSideNotificationReadStatus;
+ priority: GoabWorkSideNotificationPriority;
+}
+
+export class SomeOtherComponent {
+ items: NotificationItem[] = [
+ {
+ id: "1",
+ title: "New comment on case",
+ description: "A team member commented on Case #12340.",
+ timestamp: "2025-03-15T10:00:00Z",
+ type: "default",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "2",
+ title: "Case #12345 assigned",
+ description: "Case #12345 has been assigned to you for review.",
+ timestamp: "2025-03-15T09:00:00Z",
+ type: "info",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "3",
+ title: "Case resolved",
+ description: "Case #12330 has been marked as resolved.",
+ timestamp: "2025-03-15T08:00:00Z",
+ type: "success",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "4",
+ title: "Deadline approaching",
+ description: "Case #12345 response is due in 2 hours.",
+ timestamp: "2025-03-15T07:00:00Z",
+ type: "warning",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ {
+ id: "5",
+ title: "System maintenance",
+ description: "Scheduled maintenance tonight at 11 PM. All services will be unavailable.",
+ timestamp: "2025-03-15T06:00:00Z",
+ type: "critical",
+ readStatus: "unread",
+ priority: "normal",
+ },
+ ];
+
+ handleMarkAllRead() {
+ this.items = this.items.map((item) => ({ ...item, readStatus: "read" }));
+ }
+
+ handleViewAll() {
+ console.log("view all");
+ }
+
+ handleClick(id: string) {
+ this.items = this.items.map((item) =>
+ item.id === id ? { ...item, readStatus: "read" } : item,
+ );
+ }
+}`,
+ template: `
+
+
+
+
+
+
+
+ @for (item of items; track item.id) {
+
+ `,
+ },
+ webComponents: {
+ html: `
+
+
+
+
+ `,
+ js: `const panel = container.querySelector("goa-work-side-notification-panel");
+const items = container.querySelectorAll("goa-work-side-notification-item");
+
+items.forEach((item) => {
+ item.addEventListener("_click", () => {
+ item.setAttribute("read-status", "read");
+ });
+});
+
+panel.addEventListener("_markAllRead", () => {
+ items.forEach((item) => item.setAttribute("read-status", "read"));
+});
+
+panel.addEventListener("_viewAll", () => {
+ console.log("view all");
+});`,
+ },
+ },
+ },
+ ],
+};
diff --git a/docs/src/hooks/index.ts b/docs/src/hooks/index.ts
index 652c65f682..e61376a796 100644
--- a/docs/src/hooks/index.ts
+++ b/docs/src/hooks/index.ts
@@ -5,3 +5,4 @@
export { useTwoLevelSort, type SortConfig, type SortLevel } from './useTwoLevelSort';
export { useCompactToolbar, useMobile, COMPACT_TOOLBAR_BREAKPOINT, MOBILE_BREAKPOINT } from './useCompactToolbar';
export { useViewSettings, type ViewSettings, type LayoutType, type GroupByField } from './useViewSettings';
+export { useIsDarkMode } from './useIsDarkMode';
diff --git a/docs/src/hooks/useIsDarkMode.ts b/docs/src/hooks/useIsDarkMode.ts
new file mode 100644
index 0000000000..24afeb84cd
--- /dev/null
+++ b/docs/src/hooks/useIsDarkMode.ts
@@ -0,0 +1,42 @@
+/**
+ * useIsDarkMode.ts
+ *
+ * Watches the active theme via the `data-theme` attribute on .
+ * Returns true when in dark mode. Reacts to toggle changes via MutationObserver.
+ *
+ * Why read from the DOM attribute instead of localStorage:
+ * - The pre-paint script in BaseLayout.astro sets `data-theme` from
+ * localStorage > prefers-color-scheme > "light", so the attribute is
+ * the source of truth for what's currently rendered.
+ * - localStorage has no in-tab change event; MutationObserver on the
+ * attribute is the cleanest way to react to toggle in other islands.
+ * - localStorage may be blocked (private mode, sandboxed iframe); the
+ * DOM attribute is always set.
+ *
+ * Astro islands cannot share React context, so the DOM attribute is the
+ * cross-island sync channel for theme.
+ */
+
+import { useEffect, useState } from "react";
+
+export function useIsDarkMode(): boolean {
+ const [isDark, setIsDark] = useState(
+ () =>
+ typeof document !== "undefined" &&
+ document.documentElement.getAttribute("data-theme") === "dark",
+ );
+
+ useEffect(() => {
+ if (typeof document === "undefined") return;
+ const observer = new MutationObserver(() => {
+ setIsDark(document.documentElement.getAttribute("data-theme") === "dark");
+ });
+ observer.observe(document.documentElement, {
+ attributes: true,
+ attributeFilter: ["data-theme"],
+ });
+ return () => observer.disconnect();
+ }, []);
+
+ return isDark;
+}
diff --git a/docs/src/layouts/BaseLayout.astro b/docs/src/layouts/BaseLayout.astro
index b9f9d3fa4c..0f9905158d 100644
--- a/docs/src/layouts/BaseLayout.astro
+++ b/docs/src/layouts/BaseLayout.astro
@@ -2,6 +2,7 @@
// Import v2 design tokens and web component styles
import '@abgov/web-components/index.css';
import '@design-tokens/tokens.css';
+import '@design-tokens/dark-theme.css';
// Import search styles eagerly so inline search inputs don't flash unstyled
import '../components/search/search.css';
@@ -26,6 +27,24 @@ const ogUrl = new URL(withBase(Astro.url.pathname), Astro.site).href;
+
+
+
+
+
+
+
+
+
+
+ {backLabel}
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/src/layouts/TokensLayout.astro b/docs/src/layouts/TokensLayout.astro
index 6549a769aa..c7e73a8e36 100644
--- a/docs/src/layouts/TokensLayout.astro
+++ b/docs/src/layouts/TokensLayout.astro
@@ -16,6 +16,7 @@ import Breadcrumbs from '../components/Breadcrumbs.astro';
import { SiteNav } from '../components/SiteNav';
import { MobileHeader } from '../components/MobileHeader';
import { getNavCategories } from '../lib/nav-categories';
+import { getGetStartedNav } from '../lib/get-started-nav';
interface Props {
title: string;
@@ -24,6 +25,7 @@ interface Props {
const { title, description } = Astro.props;
const navCategories = await getNavCategories();
+const getStartedNav = await getGetStartedNav();
---
@@ -36,6 +38,7 @@ const navCategories = await getNavCategories();
client:only="react"
initialSection="tokens"
categories={navCategories}
+ getStartedNav={getStartedNav}
/>
diff --git a/docs/src/lib/base-url.ts b/docs/src/lib/base-url.ts
index 1ea988dbab..47e91e8df0 100644
--- a/docs/src/lib/base-url.ts
+++ b/docs/src/lib/base-url.ts
@@ -3,6 +3,8 @@ export const BASE_URL = import.meta.env.BASE_URL;
export function withBase(path: string): string {
if (!path) return BASE_URL;
if (path.startsWith("http://") || path.startsWith("https://")) return path;
+ // Idempotent: skip if path is already prefixed with BASE_URL.
+ if (BASE_URL !== "/" && path.startsWith(BASE_URL)) return path;
const clean = path.startsWith("/") ? path.slice(1) : path;
return `${BASE_URL}${clean}`;
}
diff --git a/docs/src/lib/content-queries.ts b/docs/src/lib/content-queries.ts
index 2be5abcf8e..c3a8ac8fdf 100644
--- a/docs/src/lib/content-queries.ts
+++ b/docs/src/lib/content-queries.ts
@@ -9,6 +9,7 @@ export interface PropDefinition {
required: boolean;
default: string | null;
description: string;
+ deprecated?: boolean;
}
export interface EventDefinition {
@@ -20,24 +21,34 @@ export interface EventDefinition {
export interface SlotDefinition {
name: string;
+ type?: string;
description: string;
+ required?: boolean;
+}
+
+export interface FrameworkApiData {
+ props: PropDefinition[];
+ events: EventDefinition[];
+ slots: SlotDefinition[];
+}
+
+export interface FrameworkApiMap {
+ react: FrameworkApiData;
+ angular: FrameworkApiData;
+ webComponents: FrameworkApiData;
}
export interface SubComponentApi {
name: string;
webComponentTag: string;
description: string;
- props: PropDefinition[];
- events: EventDefinition[];
- slots: SlotDefinition[];
+ frameworks: FrameworkApiMap;
}
export interface ComponentApi {
componentSlug: string;
extractedFrom: string;
- props: PropDefinition[];
- events: EventDefinition[];
- slots: SlotDefinition[];
+ frameworks: FrameworkApiMap;
subComponents?: SubComponentApi[];
}
@@ -89,7 +100,9 @@ export async function getExamplesForComponent(
): Promise[]> {
const allExamples = await getCollection("examples");
- return allExamples.filter((example) => example.data.components.includes(componentSlug));
+ return allExamples.filter(
+ (example) => !example.data.hidden && example.data.components.includes(componentSlug),
+ );
}
/**
@@ -165,7 +178,7 @@ export async function getContentByTag(tag: string) {
return {
components: components.filter((c) => c.data.tags?.includes(tag)),
guidance: guidance.filter((g) => g.data.tags?.includes(tag)),
- examples: examples.filter((e) => e.data.tags?.includes(tag)),
+ examples: examples.filter((e) => !e.data.hidden && e.data.tags?.includes(tag)),
};
}
diff --git a/docs/src/lib/example-size.ts b/docs/src/lib/example-size.ts
new file mode 100644
index 0000000000..133656c6d3
--- /dev/null
+++ b/docs/src/lib/example-size.ts
@@ -0,0 +1,13 @@
+/**
+ * Page-scale entries (page, task, product) render a PreviewContainer
+ * card linking to the entry's docs page rather than an inline sandbox,
+ * because their composition usually depends on app shell, mock data, or
+ * external sources that don't render usefully inline. Section and
+ * interaction snippets render inline with a sandbox plus framework code
+ * tabs.
+ */
+const PAGE_SCALES = ["page", "task", "product"] as const;
+
+export function isPageScale(size: string): boolean {
+ return (PAGE_SCALES as readonly string[]).includes(size);
+}
diff --git a/docs/src/lib/get-started-nav.ts b/docs/src/lib/get-started-nav.ts
new file mode 100644
index 0000000000..d73df4cb40
--- /dev/null
+++ b/docs/src/lib/get-started-nav.ts
@@ -0,0 +1,77 @@
+/**
+ * get-started-nav.ts
+ *
+ * Builds the Get Started submenu structure from the content collection.
+ * Used by layouts to pass nav data to SiteNav -> GetStartedSubMenu.
+ *
+ * Section convention:
+ * - "intro" => top-level pages above grouped sections
+ * - "designers" => Designers group
+ * - "developers" => Developers group
+ * - "appendix" => top-level pages below grouped sections
+ */
+
+import { getCollection } from "astro:content";
+
+export interface GetStartedNavItem {
+ label: string;
+ url: string;
+}
+
+export interface GetStartedNavGroup {
+ name: string;
+ slug: string;
+ pages: GetStartedNavItem[];
+}
+
+export interface GetStartedNav {
+ topPages: GetStartedNavItem[];
+ groups: GetStartedNavGroup[];
+ bottomPages: GetStartedNavItem[];
+}
+
+/** Display metadata for the grouped sections (not stored in content collection) */
+const GROUP_META: Record = {
+ designers: { name: "Designers" },
+ developers: { name: "Developers" },
+};
+
+/** Canonical display order for grouped sections in the submenu */
+const GROUP_ORDER = ["designers", "developers"];
+
+function entryToItem(entry: {
+ slug: string;
+ data: { title: string; navLabel?: string };
+}): GetStartedNavItem {
+ return {
+ label: entry.data.navLabel ?? entry.data.title,
+ url: entry.slug === "index" ? "/get-started" : `/get-started/${entry.slug}`,
+ };
+}
+
+function bySection(
+ entries: Awaited>>,
+ section: string,
+): typeof entries {
+ return entries
+ .filter((e) => e.data.section === section)
+ .sort((a, b) => a.data.order - b.data.order);
+}
+
+export async function getGetStartedNav(): Promise {
+ const entries = await getCollection("get-started");
+ const published = entries.filter((e) => e.data.status !== "deprecated");
+
+ const topPages = bySection(published, "intro").map(entryToItem);
+ const bottomPages = bySection(published, "appendix").map(entryToItem);
+
+ const groups = GROUP_ORDER.filter((slug) =>
+ published.some((e) => e.data.section === slug),
+ ).map((slug) => ({
+ name: GROUP_META[slug].name,
+ slug,
+ pages: bySection(published, slug).map(entryToItem),
+ }));
+
+ return { topPages, groups, bottomPages };
+}
diff --git a/docs/src/lib/tokens.ts b/docs/src/lib/tokens.ts
index e36d74171b..ce244064dd 100644
--- a/docs/src/lib/tokens.ts
+++ b/docs/src/lib/tokens.ts
@@ -29,6 +29,10 @@ export interface FlatToken {
isColor: boolean;
/** Description if available */
description?: string;
+ /** Dark mode "as defined" value (only set if token is themed). */
+ darkValue?: string;
+ /** Dark mode resolved value (only set if token is themed). */
+ darkResolvedValue?: string;
}
/**
@@ -98,15 +102,35 @@ function boxShadowToCss(shadow: {
}
/**
- * Format a token value for display
+ * Check if a value is a themed value (has `light` and `dark` keys).
+ * These are emitted by Style Dictionary for tokens that flip between modes.
+ * The inner values may be strings (e.g. colors) or objects (e.g. box shadows).
*/
-function formatValue(value: string | number | object): string {
+function isThemedValue(value: unknown): value is { light: unknown; dark: unknown } {
+ return (
+ typeof value === "object" &&
+ value !== null &&
+ "light" in value &&
+ "dark" in value
+ );
+}
+
+/**
+ * Format a token value for display. For themed `{ light, dark }` values,
+ * returns the light variant (recursively formatted, so themed box-shadow
+ * objects, themed strings, etc. all flatten correctly).
+ */
+function formatValue(value: unknown): string {
if (typeof value === "string") {
return value;
}
if (typeof value === "number") {
return String(value);
}
+ // Themed value: recurse on the light variant
+ if (isThemedValue(value)) {
+ return formatValue(value.light);
+ }
// Convert box-shadow objects to CSS syntax
if (isBoxShadowObject(value)) {
return boxShadowToCss(value);
@@ -213,7 +237,10 @@ function flattenTokensRecursive(
const tokenPath = currentPath.slice(1).join("/");
const tokenType = value.type || "unknown";
- // Keep original value, resolve for preview
+ // Detect themed { light, dark } shape, split into separate light + dark fields.
+ const themed = isThemedValue(value.value) ? value.value : null;
+
+ // Keep original value, resolve for preview (light by default for themed values)
const rawValue = formatValue(value.value);
let resolvedValue: string;
@@ -226,6 +253,18 @@ function flattenTokensRecursive(
typeof rawValue === "string" ? resolveTokenReference(rawValue, rootTokens) : rawValue;
}
+ // Resolve dark variant if the value is themed
+ let darkValue: string | undefined;
+ let darkResolvedValue: string | undefined;
+ if (themed) {
+ // Themed inner value may be a string, box-shadow object, etc.
+ // Formatting recursively lets it produce a CSS string for any shape.
+ darkValue = formatValue(themed.dark);
+ darkResolvedValue = isTokenReference(darkValue)
+ ? resolveTokenReference(darkValue, rootTokens)
+ : darkValue;
+ }
+
const isColor =
tokenType === "color" ||
(typeof resolvedValue === "string" && resolvedValue.startsWith("#"));
@@ -239,6 +278,8 @@ function flattenTokensRecursive(
type: tokenType,
isColor,
description: value.description,
+ darkValue,
+ darkResolvedValue,
});
} else if (typeof value === "object" && value !== null) {
// Recurse into nested object
diff --git a/docs/src/pages/components/[slug].astro b/docs/src/pages/components/[slug].astro
index 5929614b2c..3c3b3641dc 100644
--- a/docs/src/pages/components/[slug].astro
+++ b/docs/src/pages/components/[slug].astro
@@ -112,13 +112,13 @@ const v1DocsUrl = `https://v1.design.alberta.ca/components/${slug}`;
{api ? (
<>
- {sub.name}
{sub.description}
-
diff --git a/docs/src/pages/examples/[family]/[page]/index.astro b/docs/src/pages/examples/[family]/[page]/index.astro
new file mode 100644
index 0000000000..a5da1c88d6
--- /dev/null
+++ b/docs/src/pages/examples/[family]/[page]/index.astro
@@ -0,0 +1,134 @@
+---
+/**
+ * Template Detail Page
+ *
+ * Deep dive for a single template or sub-pattern.
+ * Hero with preview image plus a thin action bar (Live preview, Source, StackBlitz),
+ * followed by MDX body (when to use, considerations, components used, etc.).
+ * No framework code tabs at this scale. Source link goes to GitHub.
+ */
+import { getCollection, render } from 'astro:content';
+import ExamplesPageLayout from '../../../../layouts/ExamplesPageLayout.astro';
+import Breadcrumbs from '../../../../components/Breadcrumbs.astro';
+import PreviewContainer from '../../../../components/PreviewContainer.astro';
+
+export async function getStaticPaths() {
+ const examples = await getCollection('examples');
+ // Nested page-scale entries whose slug is "/". Today's
+ // set: workspace/dashboard, workspace/index-page, workspace/case-detail.
+ const nested = examples.filter((e) => e.slug.includes('/') && e.data.size === 'page');
+ return nested.map((entry) => {
+ const [family, page] = entry.slug.split('/');
+ return {
+ params: { family, page },
+ props: { entry },
+ };
+ });
+}
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+const { data } = entry;
+const { family, page } = Astro.params;
+// data is narrowed to the page-shape by the getStaticPaths filter
+const pageData = data as Extract;
+
+// Emit a Live preview URL so the action bar renders consistently with
+// the family overview. Whether the preview iframes an external demo
+// (workspace) or renders locally (page-scale templates) is decided
+// by the preview route itself.
+const internalPreviewUrl = `/examples/${family}/${page}/preview`;
+---
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/[family]/[page]/preview.astro b/docs/src/pages/examples/[family]/[page]/preview.astro
new file mode 100644
index 0000000000..4933cfec2d
--- /dev/null
+++ b/docs/src/pages/examples/[family]/[page]/preview.astro
@@ -0,0 +1,61 @@
+---
+/**
+ * Template Live Preview
+ *
+ * Standalone full-viewport preview of a template. Iframes the template's
+ * configured previewUrl (typically the workspace demo app) and wraps it
+ * with a minimal top bar so users can navigate back to the docs. This is
+ * the "isolated preview" distinct from the full working demo linked via
+ * the "View demo" CTA in the walkthrough.
+ */
+import { getCollection } from 'astro:content';
+import PreviewLayout from "../../../../layouts/PreviewLayout.astro";
+
+export async function getStaticPaths() {
+ const examples = await getCollection('examples');
+ // Nested examples with a previewUrl: the page-detail route wires the
+ // Live preview button here, and this route iframes the externally-hosted demo.
+ const nested = examples.filter(
+ (e) => e.slug.includes('/') && e.data.size === 'page' && e.data.previewUrl,
+ );
+ return nested.map((entry) => {
+ const [family, page] = entry.slug.split('/');
+ return {
+ params: { family, page },
+ props: { entry },
+ };
+ });
+}
+
+const { entry } = Astro.props;
+const { data } = entry;
+const { family, page } = Astro.params;
+const backUrl = `/examples/${family}/${page}`;
+const backLabel = `Back to ${data.title}`;
+const pageData = data as Extract;
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/[family]/index.astro b/docs/src/pages/examples/[family]/index.astro
new file mode 100644
index 0000000000..c7d45a0b16
--- /dev/null
+++ b/docs/src/pages/examples/[family]/index.astro
@@ -0,0 +1,150 @@
+---
+/**
+ * Service Type Overview Page
+ *
+ * Landing page for a service type. Renders the MDX body of the matching
+ * entry in the `productTypes` collection (workspace, public-form). Follows
+ * the flexible-doc-page pattern: prose walkthrough with inline demo CTAs,
+ * images, and links to nested example pages.
+ */
+import { getCollection, render } from 'astro:content';
+import ExamplesPageLayout from '../../../layouts/ExamplesPageLayout.astro';
+import Breadcrumbs from '../../../components/Breadcrumbs.astro';
+import { TableOfContents } from '../../../components/TableOfContents';
+
+export async function getStaticPaths() {
+ const productTypes = await getCollection('productTypes');
+ return productTypes.map((entry) => ({
+ params: { family: entry.data.id },
+ props: { entry },
+ }));
+}
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+const { data } = entry;
+
+// Family overview cover shows the whole demo app, not a single-page preview,
+// so no Live preview button. View demo alone covers the CTA.
+---
+
+
+
+
+
+ {data.title}
+ {data.summary && }
+
+
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/[family]/preview.astro b/docs/src/pages/examples/[family]/preview.astro
new file mode 100644
index 0000000000..73c3a161d2
--- /dev/null
+++ b/docs/src/pages/examples/[family]/preview.astro
@@ -0,0 +1,48 @@
+---
+/**
+ * Family Live Preview
+ *
+ * Standalone full-viewport preview of a template family's main demo route.
+ * Same chrome as [page]/preview.astro so the family overview's "Live preview"
+ * button lands on the same shape as the detail pages' buttons.
+ */
+import { getCollection } from 'astro:content';
+import PreviewLayout from "../../../layouts/PreviewLayout.astro";
+
+export async function getStaticPaths() {
+ const productTypes = await getCollection('productTypes');
+ const withDemo = productTypes.filter((entry) => entry.data.demoUrl);
+ return withDemo.map((entry) => ({
+ params: { family: entry.data.id },
+ props: { entry },
+ }));
+}
+
+const { entry } = Astro.props;
+const { data } = entry;
+const backUrl = `/examples/${data.id}`;
+const backLabel = `Back to ${data.title}`;
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/[slug].astro b/docs/src/pages/examples/[slug].astro
index 930c953abf..65618d4881 100644
--- a/docs/src/pages/examples/[slug].astro
+++ b/docs/src/pages/examples/[slug].astro
@@ -13,17 +13,21 @@ import { getCollection, render } from 'astro:content';
import ExamplesPageLayout from '../../layouts/ExamplesPageLayout.astro';
import Breadcrumbs from '../../components/Breadcrumbs.astro';
import ExampleDisplay from '../../components/ExampleDisplay.astro';
+import PreviewContainer from '../../components/PreviewContainer.astro';
import { TableOfContents } from '../../components/TableOfContents';
import { getExampleCode } from '../../lib/example-code';
+import { isPageScale } from '../../lib/example-size';
-
-// Generate static paths for all examples
+// Generate static paths for flat examples only. Nested entries
+// (workspace/dashboard, etc) are handled by [family]/[page]/index.astro.
export async function getStaticPaths() {
const examples = await getCollection('examples');
- return examples.map((example) => ({
- params: { slug: example.slug },
- props: { example },
- }));
+ return examples
+ .filter((example) => !example.slug.includes('/') && !example.data.hidden)
+ .map((example) => ({
+ params: { slug: example.slug },
+ props: { example },
+ }));
}
const { example } = Astro.props;
@@ -37,37 +41,48 @@ const { Content } = await render(example);
const code = await getExampleCode(example.slug);
const hasCode = !!(code.react || code.angular || code.webComponents);
+// Page-and-larger entries render with a PreviewContainer at the top instead
+// of framework code tabs, mirroring the workspace page detail shape. The
+// framework files still exist on disk and are linked via GitHub.
+// Section-sized entries keep the sandbox + framework tabs treatment.
+const pageScale = isPageScale(data.size);
+const showCodeTabs = !pageScale && hasCode;
+const useTopPreview = pageScale && data.previewImage && !data.hideHero;
+const githubBlobBase = 'https://github.com/GovAlta/ui-components/blob/dev/docs/src/content/examples';
+const githubTreeBase = 'https://github.com/GovAlta/ui-components/tree/dev/docs/src/content/examples';
+type WithSourceUrls = { reactSourceUrl?: string; angularSourceUrl?: string; previewUrl?: string };
+const pageData = data as typeof data & WithSourceUrls;
+const reactSourceUrl =
+ pageData.reactSourceUrl ?? (code.react ? `${githubBlobBase}/${slug}/react.tsx` : undefined);
+const angularSourceUrl =
+ pageData.angularSourceUrl ?? (code.angular ? `${githubTreeBase}/${slug}` : undefined);
+// /examples/[slug]/preview.astro auto-generates a Live preview route for
+// every flat-slug page-scale entry with a sibling react.tsx. So if this
+// entry has React code, link the PreviewContainer image to its preview.
+const previewUrl =
+ pageData.previewUrl ?? (pageScale && code.react ? `/examples/${slug}/preview` : undefined);
+
// Get related examples if defined
let relatedExamples: typeof example[] = [];
if (data.relatedExamples?.length) {
const allExamples = await getCollection('examples');
relatedExamples = allExamples.filter(e =>
+ !e.data.hidden &&
data.relatedExamples?.includes(e.data.id)
);
}
-// Format category for display
-function formatCategory(category: string): string {
- return category
+// Format size for display ("page" -> "Page", "component" -> "Component", "digital-service" -> "Digital service")
+function formatSize(size: string): string {
+ return size
.split('-')
- .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+ .map((word, i) => (i === 0 ? word.charAt(0).toUpperCase() + word.slice(1) : word))
.join(' ');
}
-// Format scale for display
-function formatScale(scale: string): string {
- return scale.charAt(0).toUpperCase() + scale.slice(1);
-}
-
-// Format user type for display
-function formatUserType(userType: string): string {
- if (userType === 'both') return 'Citizen & Worker';
- return userType.charAt(0).toUpperCase() + userType.slice(1);
-}
-
-// Format component name to sentence case (e.g., "form-item" → "Form item")
-function formatComponentName(component: string): string {
- return component
+// Format service type for display ("public-form" -> "Public form")
+function formatProductType(productType: string): string {
+ return productType
.split('-')
.map((word, i) => i === 0 ? word.charAt(0).toUpperCase() + word.slice(1) : word)
.join(' ');
@@ -82,37 +97,56 @@ const v1DocsUrl = `https://v1.design.alberta.ca/examples/${slug}`;
currentSlug={slug}
>
-
- {data.categories.map((cat: string) => (
-
-
- {hasCode ? (
+
+ {showCodeTabs ? (
- ) : data.previewImage ? (
+ ) : useTopPreview ? (
+
+ {data.title}
+ {data.description && (
+
+ )}
+
+ ) : (
{data.title}
{data.description && (
)}
-
-
-
- ) : null}
+ )}
- {!hasCode ? (
+ {!showCodeTabs ? (
)}
+ {/* end of code-tabs vs TOC switch */}
+
{relatedExamples.length > 0 && (
@@ -214,10 +250,11 @@ const v1DocsUrl = `https://v1.design.alberta.ca/examples/${slug}`;
margin-bottom: var(--goa-space-2xl, 2.5rem);
}
+ /* Use goa-text typography tokens so MDX headings match the design system's
+ heading scale without authors having to wrap each heading in . */
.example-content :global(h2) {
- font-size: 1.25rem;
- font-weight: 600;
- margin: var(--goa-space-xl, 2rem) 0 var(--goa-space-m, 1rem);
+ font: var(--goa-typography-heading-m);
+ margin: var(--goa-space-2xl, 2.5rem) 0 var(--goa-space-m, 1rem);
color: var(--goa-color-text-default, #333);
}
@@ -225,6 +262,12 @@ const v1DocsUrl = `https://v1.design.alberta.ca/examples/${slug}`;
margin-top: 0;
}
+ .example-content :global(h3) {
+ font: var(--goa-typography-heading-s);
+ margin: var(--goa-space-2xl, 2.5rem) 0 var(--goa-space-s, 0.5rem);
+ color: var(--goa-color-text-default, #333);
+ }
+
.example-content :global(p) {
margin-bottom: var(--goa-space-m, 1rem);
max-width: 65ch;
diff --git a/docs/src/pages/examples/[slug]/preview.astro b/docs/src/pages/examples/[slug]/preview.astro
new file mode 100644
index 0000000000..7098c794a8
--- /dev/null
+++ b/docs/src/pages/examples/[slug]/preview.astro
@@ -0,0 +1,87 @@
+---
+/**
+ * Generic preview route for flat-slug page-scale examples.
+ *
+ * Renders the page's React component full-screen wrapped in PreviewLayout.
+ * Astro hydration needs static imports so it can ship the right JS bundle
+ * to the client, hence the SLUG_TO_COMPONENT map below. Adding a new
+ * page-scale entry means one import + one map entry here.
+ *
+ * Workspace pages (nested slugs) use [family]/[page]/preview.astro which
+ * iframes an external demo. Error-page variants and question-page variants
+ * have their own routes.
+ */
+import { getCollection } from "astro:content";
+import PreviewLayout from "../../../layouts/PreviewLayout.astro";
+import { StartPage } from "../../../content/examples/start-page/react";
+import { TaskListPage } from "../../../content/examples/task-list-page/react";
+import { ReviewPage } from "../../../content/examples/review-page/react";
+import { ResultPage } from "../../../content/examples/result-page/react";
+import { BasicPageLayout } from "../../../content/examples/basic-page-layout/react";
+
+export async function getStaticPaths() {
+ // Inline list — Astro's getStaticPaths runs in an isolated module context
+ // and cannot see frontmatter top-level constants like SLUG_TO_COMPONENT.
+ // Keep this list in sync with the SLUG_TO_COMPONENT map above when adding
+ // page-scale entries that need a preview route.
+ const slugsWithPreview = new Set([
+ "start-page",
+ "task-list-page",
+ "review-page",
+ "result-page",
+ "basic-page-layout",
+ ]);
+ const examples = await getCollection("examples");
+ return examples
+ .filter(
+ (e) =>
+ !e.slug.includes("/") &&
+ e.data.size !== "section" &&
+ slugsWithPreview.has(e.slug),
+ )
+ .map((entry) => ({
+ params: { slug: entry.slug },
+ props: { entry },
+ }));
+}
+
+const { entry } = Astro.props;
+const { slug } = Astro.params;
+const { data } = entry;
+const fullWidth = data.previewFullWidth === true;
+
+const githubBlob = `https://github.com/GovAlta/ui-components/blob/dev/docs/src/content/examples/${slug}/react.tsx`;
+const githubFolder = `https://github.com/GovAlta/ui-components/tree/dev/docs/src/content/examples/${slug}`;
+---
+
+
+
+ {/* Each branch is its own statically-imported JSX element so Astro
+ can wire up client:load hydration. Add a new branch when adding
+ a page-scale entry that needs a preview route. */}
+ {slug === "start-page" &&
+
+
diff --git a/docs/src/pages/examples/error-pages/401/preview.astro b/docs/src/pages/examples/error-pages/401/preview.astro
new file mode 100644
index 0000000000..6c2dc91688
--- /dev/null
+++ b/docs/src/pages/examples/error-pages/401/preview.astro
@@ -0,0 +1,76 @@
+---
+/**
+ * Error pages: 401 live preview
+ *
+ * Render-local preview. Composition mirrors
+ * content/examples/error-pages/401/web-components.html so the rendered
+ * preview is visually identical to the source a consumer would paste.
+ */
+import PreviewLayout from "../../../../layouts/PreviewLayout.astro";
+import { withBase } from "@/lib/base-url";
+
+const homeUrl = withBase("/");
+---
+
+
+
+
+
+
+
+ Error 401
+
+
+
+
+ Restricted access
+
+ We cannot provide access to this page without valid credentials. Please sign in or
+ contact support at
+
+ cs.licensingsupport@gov.ab.ca
+
+ to request access.
+
+
+
+
+ Go to home page
+
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/error-pages/404/preview.astro b/docs/src/pages/examples/error-pages/404/preview.astro
new file mode 100644
index 0000000000..05343bdff1
--- /dev/null
+++ b/docs/src/pages/examples/error-pages/404/preview.astro
@@ -0,0 +1,71 @@
+---
+/**
+ * Error pages: 404 live preview
+ *
+ * Render-local preview. Composition mirrors
+ * content/examples/error-pages/404/web-components.html so the rendered
+ * preview is visually identical to the source a consumer would paste.
+ */
+import PreviewLayout from "../../../../layouts/PreviewLayout.astro";
+import { withBase } from "@/lib/base-url";
+
+const homeUrl = withBase("/");
+---
+
+
+
+
+
+
+
+ Error 404
+
+
+
+
+ Page not found
+
+ The page you're looking for doesn't exist or has been moved.
+
+
+
+
+ Go to home page
+
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/error-pages/500/preview.astro b/docs/src/pages/examples/error-pages/500/preview.astro
new file mode 100644
index 0000000000..9f8eb71b6a
--- /dev/null
+++ b/docs/src/pages/examples/error-pages/500/preview.astro
@@ -0,0 +1,72 @@
+---
+/**
+ * Error pages: 500 live preview
+ *
+ * Render-local preview. Composition mirrors
+ * content/examples/error-pages/500/web-components.html so the rendered
+ * preview is visually identical to the source a consumer would paste.
+ */
+import PreviewLayout from "../../../../layouts/PreviewLayout.astro";
+import { withBase } from "@/lib/base-url";
+
+const homeUrl = withBase("/");
+---
+
+
+
+
+
+
+
+ Error 500
+
+
+
+
+ We are experiencing a problem
+
+ We cannot load this page right now. Please try again in a few minutes. We apologize
+ for the inconvenience.
+
+
+
+
+ Go to home page
+
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/index.astro b/docs/src/pages/examples/index.astro
index 75692da9e2..990a81abef 100644
--- a/docs/src/pages/examples/index.astro
+++ b/docs/src/pages/examples/index.astro
@@ -16,21 +16,43 @@ import Breadcrumbs from '../../components/Breadcrumbs.astro';
import { ExamplesGrid } from '../../components/ExamplesGrid';
-// Get all examples
+// Pull both collections so the grid can surface product-type overviews
+// alongside their member examples. Synthesizing the productTypes entries
+// at render time avoids the stub-MDX duplication we used to have in the
+// examples collection.
const allExamples = await getCollection('examples');
+const allProductTypes = await getCollection('productTypes');
+
+// Transform examples to the shape ExamplesGrid expects, excluding hidden entries.
+const exampleEntries = allExamples
+ .filter((example) => !example.data.hidden)
+ .map(example => ({
+ slug: example.slug,
+ data: example.data,
+ body: example.data.description || example.body,
+ }));
+
+// Synthesize a size:product card per productType. The slug matches the
+// /examples/[productType]/ route the [family] page handler already serves.
+const productTypeEntries = allProductTypes.map(productType => ({
+ slug: productType.slug,
+ data: {
+ id: productType.data.id,
+ title: productType.data.title,
+ description: productType.data.summary.replace(/<[^>]+>/g, ''),
+ size: 'product' as const,
+ components: productType.data.components ?? [],
+ tags: productType.data.tags ?? [],
+ status: productType.data.status,
+ previewImage: productType.data.heroImage,
+ },
+ body: productType.data.summary,
+}));
-// Sort by title (default)
-const sortedExamples = allExamples.sort((a, b) =>
+const examples = [...exampleEntries, ...productTypeEntries].sort((a, b) =>
a.data.title.localeCompare(b.data.title)
);
-// Transform to the shape ExamplesGrid expects
-const examples = sortedExamples.map(example => ({
- slug: example.slug,
- data: example.data,
- body: example.data.description || example.body,
-}));
-
---
({
For citizens submitting applications and requests
-
-
-
- Digital service
- How workspace and public form connect end-to-end
-
+
+
+
+
diff --git a/docs/src/pages/examples/question-page/variants/grouped/preview.astro b/docs/src/pages/examples/question-page/variants/grouped/preview.astro
new file mode 100644
index 0000000000..79eb3f4bbd
--- /dev/null
+++ b/docs/src/pages/examples/question-page/variants/grouped/preview.astro
@@ -0,0 +1,24 @@
+---
+import PreviewLayout from "../../../../../layouts/PreviewLayout.astro";
+import { GroupRelatedQuestionsTogetherOnAQuestionPage } from "../../../../../content/examples/question-page/variants/grouped/react";
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/question-page/variants/help-details/preview.astro b/docs/src/pages/examples/question-page/variants/help-details/preview.astro
new file mode 100644
index 0000000000..18ffa1be51
--- /dev/null
+++ b/docs/src/pages/examples/question-page/variants/help-details/preview.astro
@@ -0,0 +1,24 @@
+---
+import PreviewLayout from "../../../../../layouts/PreviewLayout.astro";
+import { ShowMoreInformationToHelpAnswerAQuestion } from "../../../../../content/examples/question-page/variants/help-details/react";
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/question-page/variants/one-question/preview.astro b/docs/src/pages/examples/question-page/variants/one-question/preview.astro
new file mode 100644
index 0000000000..218f2534c3
--- /dev/null
+++ b/docs/src/pages/examples/question-page/variants/one-question/preview.astro
@@ -0,0 +1,24 @@
+---
+import PreviewLayout from "../../../../../layouts/PreviewLayout.astro";
+import { QuestionPage } from "../../../../../content/examples/question-page/variants/one-question/react";
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/question-page/variants/progress-indicator/preview.astro b/docs/src/pages/examples/question-page/variants/progress-indicator/preview.astro
new file mode 100644
index 0000000000..6761fdbc0f
--- /dev/null
+++ b/docs/src/pages/examples/question-page/variants/progress-indicator/preview.astro
@@ -0,0 +1,24 @@
+---
+import PreviewLayout from "../../../../../layouts/PreviewLayout.astro";
+import { ShowASimpleProgressIndicatorOnAQuestionPage } from "../../../../../content/examples/question-page/variants/progress-indicator/react";
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/examples/question-page/variants/section-title/preview.astro b/docs/src/pages/examples/question-page/variants/section-title/preview.astro
new file mode 100644
index 0000000000..50e13f7d3e
--- /dev/null
+++ b/docs/src/pages/examples/question-page/variants/section-title/preview.astro
@@ -0,0 +1,24 @@
+---
+import PreviewLayout from "../../../../../layouts/PreviewLayout.astro";
+import { ShowASectionTitleOnAQuestionPage } from "../../../../../content/examples/question-page/variants/section-title/react";
+---
+
+
+
+
+
+
diff --git a/docs/src/pages/foundations/content-guidelines/error-messages.astro b/docs/src/pages/foundations/content-guidelines/error-messages.astro
index d9a2e26e76..ad5f35f8f4 100644
--- a/docs/src/pages/foundations/content-guidelines/error-messages.astro
+++ b/docs/src/pages/foundations/content-guidelines/error-messages.astro
@@ -525,27 +525,27 @@ const formatPatterns: PatternGroup[] = [
}
:global(.explicit-example span.green) {
- background-color: #cde9b9;
+ background-color: var(--goa-color-extended-pasture-border);
}
:global(.explicit-example span.blue) {
- background-color: #bcdae7;
+ background-color: var(--goa-color-extended-sky-border);
}
:global(.explicit-example span.yellow) {
- background-color: #fadfb1;
+ background-color: var(--goa-color-extended-prairie-border);
}
:global(.explicit-example span.greenUnder) {
- text-decoration: underline solid #cde9b9 3px;
+ text-decoration: underline solid var(--goa-color-extended-pasture-border) 3px;
}
:global(.explicit-example span.blueUnder) {
- text-decoration: underline solid #bcdae7 3px;
+ text-decoration: underline solid var(--goa-color-extended-sky-border) 3px;
}
:global(.explicit-example span.yellowUnder) {
- text-decoration: underline solid #fadfb1 3px;
+ text-decoration: underline solid var(--goa-color-extended-prairie-border) 3px;
}
@media (min-width: 768px) {
diff --git a/docs/src/pages/get-started/[...slug].astro b/docs/src/pages/get-started/[...slug].astro
new file mode 100644
index 0000000000..263038105d
--- /dev/null
+++ b/docs/src/pages/get-started/[...slug].astro
@@ -0,0 +1,25 @@
+---
+import { getCollection, render } from "astro:content";
+import DocumentationPageLayout from "../../layouts/DocumentationPageLayout.astro";
+
+export async function getStaticPaths() {
+ const entries = await getCollection("get-started");
+ return entries.map((entry) => ({
+ // The "index" entry maps to the collection root URL (/get-started).
+ // Astro's [...slug] rest route accepts undefined for the parent path.
+ params: { slug: entry.slug === "index" ? undefined : entry.slug },
+ props: { entry },
+ }));
+}
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+---
+
+
+
diff --git a/docs/src/pages/get-started/automated-accessibility.astro b/docs/src/pages/get-started/automated-accessibility.astro
deleted file mode 100644
index 061b16c880..0000000000
--- a/docs/src/pages/get-started/automated-accessibility.astro
+++ /dev/null
@@ -1,92 +0,0 @@
----
-/**
- * Get Started - Automated Accessibility
- *
- * Guidance on combining automated and manual accessibility testing.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Automated accessibility
-
- Automated accessibility testing tools help you identify potential accessibility issues. Use them as a starting point.
-
-
-
- However, these tools are not a complete solution. They can produce:
-
-
- - False positives – flagging issues that are not actual problems
- - False negatives – missing real accessibility barriers
-
-
- To ensure your digital product is accessible, combine automated testing with manual testing and apply
- human judgment.
-
- Why automated tools alone are not enough
-
- False positives
-
- Automated tools may flag elements as non-compliant even when they work correctly for users. For
- example, a tool may report that an input is "missing an id" even though it is correctly associated with a
- label using a valid method, such as wrapping the input inside a <label> element.
-
-
- False negatives
-
- Automated tools cannot detect nuanced or context-specific issues. For example, all interactive
- elements may be tabbable, but the order jumps around the page. Tools often don't judge whether the
- tab order is logical for completing the task.
-
-
- Real user experience
-
- Accessibility ensures real people can use a product effectively. Automated tools cannot fully simulate
- how users interact with your product.
-
- Steps for effective accessibility testing
-
-
- -
- Run automated tools to get an initial assessment.
-
- -
- Manually verify flagged issues and review the element's intent and context.
-
- -
- Do additional manual testing for issues automated tools cannot detect:
-
- - Test with a screen reader, such as VoiceOver (macOS) or NVDA (Windows)
- - Test keyboard navigation by checking focus visibility and order
-
-
- -
- Report findings
-
- - Record what you tested, what failed, and how to reproduce it
- - If the issue relates to a design system component, submit it using the design system bug report form
-
-
-
- Why this process matters
-
- Automated tools provide helpful insight. Relying only on automation can result in:
-
-
- - Time spent fixing issues that are not real barriers
- - Missed opportunities to address genuine accessibility issues
- - A false sense of compliance without meaningful usability improvements
-
-
- Combine automated and manual testing to identify real barriers. This approach improves accessibility
- and overall product quality.
-
-
diff --git a/docs/src/pages/get-started/component-lifecycle.astro b/docs/src/pages/get-started/component-lifecycle.astro
deleted file mode 100644
index 42b0df0f4a..0000000000
--- a/docs/src/pages/get-started/component-lifecycle.astro
+++ /dev/null
@@ -1,67 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Component Lifecycle
- *
- * Defines the stages each Design System component moves through.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Component lifecycle
-
- The component lifecycle defines the stages each Design System component moves through, from
- Experimental to Production to Legacy.
-
-
-
- To request a new component or propose an enhancement, follow the
- design contribution process.
-
- Experimental
-
- Experimental components are new or significantly updated. They are available for testing and feedback
- before public release.
-
-
- Characteristics
-
- - Feedback is gathered from selected teams
- - May be unstable or include breaking changes
- - Limited documentation
-
- Production
-
- Production components are stable and ready for broader adoption.
-
-
- Characteristics
-
- - Fully documented, including design guidelines, properties, and examples
- - Meet accessibility and design system standards
- - Optimized for mobile use
- - Actively maintained with updates and bug fixes
- - Publicly available documentation
-
- Legacy
-
- Legacy components are older components maintained primarily to support older implementations. If
- possible, transition to production is recommended.
-
-
- Characteristics
-
- - No active maintenance or updates
- - Critical issues may remain unresolved
- - Recommended alternative clearly identified
- - Marked as "Legacy" in official documentation
-
-
diff --git a/docs/src/pages/get-started/contribute.astro b/docs/src/pages/get-started/contribute.astro
deleted file mode 100644
index 7a2ea6d675..0000000000
--- a/docs/src/pages/get-started/contribute.astro
+++ /dev/null
@@ -1,188 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Contribute
- *
- * How to contribute to the Design System (design and code).
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Contribute
-
- The Design System is a shared resource used and improved by service teams. All roles are encouraged
- to contribute.
-
-
-
- Start by using existing Design System components and patterns. If a component or pattern does not
- meet your needs, follow the contribution process below.
-
- Design contribution process
-
- If a required component or example does not exist in production,
- contact the Design System team. We will review the request together and determine next steps.
-
-
- 1. Contact the team
-
- Book a design system drop-in hours session.
-
- Be prepared to:
-
- - Describe the component or pattern and its purpose
- - Explain your user needs and service goals
- - Share iterations explored with and without the Design System
-
-
-
- There are open contribution files in Figma for every component and pattern in the design system,
- including unpublished ideas and experiments.
-
-
- 2. Contribution criteria
- A proposed component or pattern must meet the following criteria.
-
- Proposal criteria
- Useful
-
- Evidence shows it supports multiple teams or services. Provide screenshots or links to demonstrate usage.
-
-
- Unique
-
- It does not duplicate an existing component or pattern. If replacing an existing component, provide
- evidence that the new approach improves usability or accessibility.
-
-
- Publication standards
- To be published, the solution must be:
-
- Usable
-
- Improves clarity, usability, and accessibility for users. Is informed by research and addresses a
- validated user need.
-
-
- Universal
-
- Inclusive and accessible. Meets or exceeds accessibility standards.
- WCAG 2.2 AA is the minimum requirement.
-
-
- 3. Backlog and collaboration
-
- If approved, the item is added to the
- Design System's backlog.
-
-
- When development begins, the Design System team will collaborate with you to confirm detailed requirements.
-
- Code contribution process
-
- The Design System supports multiple development frameworks through Web Components. Contributing full
- components can be complex. Smaller contributions are encouraged.
-
-
- Recommended contribution types
-
- - Bug fixes
- - Documentation updates
- - Enhancements to existing components
-
-
- Start by contacting the team in the #design-system-support Slack channel.
-
-
- Select an issue tagged ready-for-contribution from the
- backlog.
- Confirm which issue you will work on.
-
-
-
- Since the repository is public, use a personal GitHub account instead of your Enterprise Managed User (EMU) account.
-
-
- Set up your contribution environment
-
- - Clone the ui-components repository.
- - Open the repository in your IDE.
- - Create a branch named:
contributions/story-number
- -
- Run the following commands:
-
npm i
-npm run build
-
- -
- The playgrounds for local testing are located in:
-
/apps/dev/angular
-/apps/dev/react
-
-
-
- Run playground environments
- Angular
- npm run dev:watch
-npm run serve:dev:angular
-
- React
- npm run dev:watch
-npm run serve:dev:react
-
- Repository structure
-
- React wrappers
- /libs/react-components/src/lib
- Each folder represents a single component with its associated unit tests and wrapper code.
-
- Angular wrappers
- /libs/angular-components/src/lib/components
- Each folder represents a single component with its associated unit tests and wrapper code.
-
- Web Components
- /libs/web-components/src/components
-
- - Unit tests as
*.spec.ts
- - Component code as
*.svelte
-
-
- Testing requirements
-
- - Write all unit tests in Svelte.
- - If updating React or Angular wrappers, write unit tests in those respective frameworks.
- -
- Add browser testing using Jest for React wrappers and Svelte components when appropriate.
- These can be found in:
libs/react-components/specs
-
- - Manually test components in both React and Angular.
- -
- Create test files that others can use to manually test the PR. These can be created in:
-
/apps/prs/angular
-/apps/prs/react
-
- - Follow the conventions already used in those files to create your test files.
-
- A Design System developer will also manually test the pull request.
-
- Submit your contribution
- Use the following commit message format:
-
- Bug fix
- fix(#storyNumber): short description (7 words max)
-
- Feature request
- feat(#storyNumber): short description (7 words max)
-
-
- - Create a pull request from your branch to the
dev branch.
- - Notify the design system team of the PR.
-
-
diff --git a/docs/src/pages/get-started/designers.astro b/docs/src/pages/get-started/designers.astro
deleted file mode 100644
index 2d8a3b163d..0000000000
--- a/docs/src/pages/get-started/designers.astro
+++ /dev/null
@@ -1,94 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Designers Overview
- *
- * Overview of design system resources for designers.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Overview
-
- As a designer, you use the design system through Figma.
-
- In Figma, you can access:
-
-
- - Design tokens
- - Components
- - Patterns
-
-
-
- The design system library in Figma aligns with coded components used by developers. Start with
- design system components for common parts of your service. This helps developers use the matching
- coded components and reduces custom work.
-
-
- Start with the design system. Validate your design through user testing. If usability issues arise,
- or the problem cannot be solved within the system, consider creating a custom solution.
-
- Design with development in mind
-
- When selecting components, prioritize those with a "goa-" prefix, such as
- goa-input. These components exist in both design and development. Using them reduces
- the need for custom development.
-
- Choose shared components whenever possible to maintain consistency and efficiency.
-
- Design tokens
- Design system components in Figma and code are built using design tokens.
-
- Use tokens to communicate design decisions clearly. Developers can reference the same tokens in code.
-
- Instead of sharing hex values or pixel adjustments, reference semantic tokens.
- For example:
-
- - Colour:
--goa-color-info-default
- - Spacing:
--goa-spacing-m
-
- Using tokens reduces back-and-forth and keeps design and development aligned.
-
- Components
- All design system components are available in Figma and in code.
-
- These components are designed to meet
- WCAG 2.2 accessibility standards.
-
- Avoid detaching components. Instead:
-
- - Use variants
- - Show or hide layers within the component
-
-
- Use #figma for Figma-related issues, including library updates, missing components,
- broken instances, or component behaviour in Figma.
-
-
- Use #design-system-support for design system guidance, component usage questions,
- standards, and implementation support.
-
- Keep your components up to date. Figma will notify you when library updates are available.
-
- Figma file templates and helper components
- Each digital service project folder includes a starter Figma template.
- Use this template to:
-
- - Organize your design file
- - Support developer handoff
- - Help team members navigate files
-
-
- Helper components are also available. Use them to clearly communicate intent when sharing designs
- with developers and other team members.
-
-
diff --git a/docs/src/pages/get-started/designers/designing-with-ds.astro b/docs/src/pages/get-started/designers/designing-with-ds.astro
deleted file mode 100644
index a875429941..0000000000
--- a/docs/src/pages/get-started/designers/designing-with-ds.astro
+++ /dev/null
@@ -1,81 +0,0 @@
----
-/**
- * Get Started - Designers - Designing with Design System 2.0
- *
- * How to start new designs and update existing projects to DS 2.0.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../../layouts/DocumentationPageLayout.astro';
----
-
-
- Designing with Design System 2.0
-
- What's new in DS 2.0 and how to start using it in your designs.
-
-
- The Digital Design and Delivery (DDD) Design System has evolved to better support how service teams
- design and build digital government services. Design System 2.0 includes an updated design
- language, new tokens, refreshed components, and ready-to-use templates.
-
- Starting a new design
-
- Use DS 2.0 templates as your starting point. Templates package layout, navigation, spacing, and
- example content that you can adapt to your service. Some templates are built for specific service types
- (for example, public-facing forms and workspace applications), and others are more general-purpose
- starting points you can use across many kinds of pages and flows.
-
-
- Starting from an existing design
-
- Library swap
-
- Use a library swap if
- your goal is to convert most of the file to DS 2.0 in one pass.
-
-
- - Make a copy of your file before you start.
- - Expect mixed results. Some screens may need cleanup after the swap.
-
-
- Manual rebuild
- Use a manual rebuild if you need more control.
-
- - Rebuild your highest value screens first.
- - Consider using DS 2.0 templates as a base to speed things up.
-
- Update an existing project to the new design library
-
- Approach 1: Developer-first
- Use this approach in most cases.
-
- - A developer creates a new branch and completes the upgrade steps.
- - The team runs the upgraded application to see what changed.
- - Designers review the upgraded screens and identify what needs design updates.
-
- When reviewing the upgraded branch, watch for:
-
- - Spacing and layout rhythm
- - Typography scale and weight usage
- - Dense or constrained screens (these often have the highest risk during an update)
-
-
- Approach 2: Design-first
- Use this approach when you want design work to move ahead of development work.
-
- - Identify custom elements that support your users' needs.
- - Create an inventory and prioritize items by importance and effort.
- - Redesign the highest priority items using the visual design values in the Styles library.
-
-
-
- In most cases, start with the developer-first approach. It helps you quickly see what changed in your
- real product, so you can focus design effort where it matters most.
-
-
diff --git a/docs/src/pages/get-started/designers/ux-guidelines.astro b/docs/src/pages/get-started/designers/ux-guidelines.astro
deleted file mode 100644
index b44c9c82e5..0000000000
--- a/docs/src/pages/get-started/designers/ux-guidelines.astro
+++ /dev/null
@@ -1,55 +0,0 @@
----
-/**
- * Get Started - Designers - User Experience Guidelines
- *
- * UX guidelines for Government of Alberta digital products.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../../layouts/DocumentationPageLayout.astro';
----
-
-
- User experience guidelines
-
- Digital products built for the Government of Alberta should comply with these guidelines to ensure a
- quality user experience for Albertans.
-
-
-
- - User-centered: Designed with a clear understanding of users, their goals, tasks, environments, and context of use, using user-centered design methods.
- - Usable: Interfaces will be easy to use, enabling users to find the information they need and complete tasks successfully.
- - Accessible: Digital products will be inclusive, ensuring usability for everyone, regardless of physical or cognitive ability.
- - Trustworthy: Experiences will feel familiar and recognizable as a Government of Alberta product, ensuring users' security and privacy.
- - Modern: Digital experiences will meet present-day user expectations and preferences for aesthetics and interaction.
-
-
-
- For more details on the process of assessing compliance to each guideline, refer to our
- User Experience Guidelines and Design System Checklist.
-
- Usability testing
-
- Usability testing is our preferred method to understand user needs as they relate to each guideline.
-
- Suitable usability testing includes:
-
- - Diverse user group: Real users from different demographic, behavioural backgrounds, and geographical regions within Alberta that will experience the problem or benefit of the product.
- - Inclusive testing: Users with various physical and/or cognitive abilities, literacy levels, and tech savviness.
- - Device variety: A diverse range of devices that reflect users' preferred choice when interacting with government services.
- - Tasks: Activities that cover tasks and service process from end-to-end.
-
-
- Frequent usability testing should be conducted to maintain product usability, effectiveness and
- alignment to the user needs as they evolve over time.
-
-
- For guidance on the process of usability testing, refer to our
- Understanding Usability documentation.
-
-
diff --git a/docs/src/pages/get-started/developers.astro b/docs/src/pages/get-started/developers.astro
deleted file mode 100644
index b34d1c3712..0000000000
--- a/docs/src/pages/get-started/developers.astro
+++ /dev/null
@@ -1,104 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Developers Overview
- *
- * Overview of design system resources for developers.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Overview
-
- As a developer, you use the Design System through tokens, components, examples, and templates.
-
-
-
- The DDD Design System is built using Web Components. Web Components are framework-agnostic.
- You can use them with Angular, React, or other front-end frameworks.
-
- The Design System includes:
-
- - Tokens
- - Components
- - Examples
- - Templates
-
-
- Designers use equivalent resources in Figma. When they design with Design System components, you
- can build with the matching coded components. This reduces custom development and rework.
-
-
- All Design System components are designed and built to meet
- WCAG 2.2 accessibility standards.
-
- Tokens
-
- Access the tokens as an
- NPM package.
-
-
- Import the SCSS or CSS file into your project. Replace hard-coded values with Design System token variables.
-
-
- Designers reference the same tokens in their tools. This keeps design and development aligned during handoff.
-
-
- Components
- Components are reusable user interface elements built for use across services.
- You can:
-
- - Use components individually
- - Combine them into patterns
- - Apply them in different contexts
-
- Components are available:
-
- - As Web Components
- - As Angular wrappers
- - As React wrappers
-
-
- Refer to the Design System technologies documentation
- for implementation details.
-
-
- Examples
-
- Examples are multiple components assembled in realistic service contexts. They help you understand
- how to apply Design System guidance in a working interface.
-
- You can use examples to:
-
- - Understand how components work together
- - Use them as a starting point for building parts of your interface
- - Use proven approaches to meet user needs
-
-
- Examples help you build with more consistency and less rework. Use them to guide implementation,
- then adjust them to meet the needs of your product.
-
-
- Templates
-
- Templates are opinionated starting points for common service types. They package layout, navigation,
- spacing, and example content so you can start with a proven structure instead of building from scratch.
-
- You can use templates to:
-
- - Start a new product with a proven structure
- - Learn how components work together in a real layout
- - Adapt a proven starting point to fit your service needs
-
-
- Templates help teams move faster, reduce rework, and stay aligned with Design System guidance.
-
-
diff --git a/docs/src/pages/get-started/developers/browsers.astro b/docs/src/pages/get-started/developers/browsers.astro
deleted file mode 100644
index 3ced88e5fc..0000000000
--- a/docs/src/pages/get-started/developers/browsers.astro
+++ /dev/null
@@ -1,87 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Developers - Supported browsers
- *
- * Browser and OS support matrix for Design System components.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../../layouts/DocumentationPageLayout.astro';
----
-
-
- Supported browsers
-
- Design System components are tested across supported browsers and devices.
-
-
-
- We support the latest version of each browser listed on this page. Support applies to the browser and
- operating system combinations shown in the table below. On mobile, support is limited to the browser
- and operating system combinations listed for Android and iOS.
-
-
- Browser and operating system support
-
-
-
-
-
- Browser
- Windows
- Mac OS
- Android
- iOS
-
-
-
-
- Google Chrome
- Yes
- Yes
- Yes
- Yes
-
-
- Microsoft Edge
- Yes
- Yes
-
-
- Mozilla Firefox
- Yes
- Yes
- Yes
-
-
- Apple Safari
- N/A
- Yes
- N/A
- Yes
-
-
-
-
-
- Representative mobile OS used in testing
-
- - Android OS: 10+
- - iOS: 15+
-
- Testing guidance
-
- Use supported browsers and operating system versions when developing and testing services. If you
- encounter a browser-specific issue, follow the
- Verify a bug process.
-
-
diff --git a/docs/src/pages/get-started/developers/bug.astro b/docs/src/pages/get-started/developers/bug.astro
deleted file mode 100644
index ffabd0fc5e..0000000000
--- a/docs/src/pages/get-started/developers/bug.astro
+++ /dev/null
@@ -1,65 +0,0 @@
----
-/**
- * Get Started - Developers - Verify a bug
- *
- * Process for verifying and reporting Design System component issues.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../../layouts/DocumentationPageLayout.astro';
----
-
-
- Verify a bug
-
- Follow this process when you encounter an issue with a Design System component.
-
-
-
- These steps help confirm whether the issue is caused by the Design System, your product setup, or
- custom code. This process applies to Angular and React implementations.
-
-
- 1. Check versions
- Confirm you are using the latest version of:
-
- - Web Components
- - Angular or React
-
-
- If you are not using the latest version, upgrade and retest. If the issue remains, continue to the next step.
-
-
- 2. Test with product templates
- Use the official Angular or React product templates to isolate the issue.
-
- This helps determine whether the issue exists outside your project configuration.
-
- 3. Recreate the issue
- Create a minimal test environment.
-
- - Use only the code required for the example to function
- - Include only the component experiencing the issue
- - Remove unrelated dependencies or custom logic
-
- Confirm whether the issue can be replicated.
-
- 4. Share and report
- If you can reproduce the issue:
-
- - Share the template application link in the #design-system-support Slack channel
- - Provide a link to your repository so the team can review and replicate the issue
-
-
- Following these steps will help to ensure efficient investigation and quicker resolution of
- design system component issues.
-
-
diff --git a/docs/src/pages/get-started/developers/setup.astro b/docs/src/pages/get-started/developers/setup.astro
deleted file mode 100644
index 326b964dfe..0000000000
--- a/docs/src/pages/get-started/developers/setup.astro
+++ /dev/null
@@ -1,141 +0,0 @@
----
-/**
- * Get Started - Developers - Setup
- *
- * Setup instructions for Angular, React, and Web Components.
- * Based on the current website content with DS 2.0 token updates.
- */
-import DocumentationPageLayout from "../../../layouts/DocumentationPageLayout.astro";
-import DropInCallout from "../../../components/DropInCallout.astro";
----
-
-
- Developer setup
-
- Set up the Government of Alberta Design System in Angular, React, or directly with Web
- Components.
-
-
- Angular UI components
-
- Supported versions: 18, 19, 20, 21
-
-
- This is the web component library and utilizes Angular's web component
- integration.
-
-
- 1. Add dependencies
- npm i @abgov/web-components
-npm i @abgov/angular-components
-npm i @abgov/ui-components-common
-npm i @abgov/design-tokens
-
- 2. Link ionicons in app/index.html
-
- Add the following in the head element:
-
- <script type="module" src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.esm.js"></script>
-<script nomodule src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.js"></script>
-
- 3. Update src/app/app.module.ts
-
- Update src/app/app.module.ts as per the four steps below:
-
- // 1. Import the CUSTOM_ELEMENTS_SCHEMA
-import { CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
-
-// 2. Import the libs
-import "@abgov/web-components";
-import { AngularComponentsModule } from "@abgov/angular-components";
-
-@NgModule({
- declarations: [AppComponent],
- imports: [
- // 3. Add the needed imports
- BrowserModule,
- AngularComponentsModule,
- ],
- providers: [],
- bootstrap: [AppComponent],
- // 4. Add the CUSTOM_ELEMENTS_SCHEMA to the NgModule
- schemas: [CUSTOM_ELEMENTS_SCHEMA],
- })
-export class AppModule {}
-
- 4. Add the styles link in src/styles.css
- @import "@abgov/web-components/index.css";
-@import "@abgov/design-tokens/dist/tokens.css";
-
- React UI components
-
- Supported versions: 17, 18, 19
-
-
- This library contains React components which wrap the Government of Alberta Web
- Components.
-
-
- 1. Add dependencies
- npm i @abgov/react-components
-npm i @abgov/web-components
-npm i @abgov/ui-components-common
-npm i @abgov/design-tokens
-
- 2. Link ionicons in app/index.html
-
- Add the following to the head element:
-
- <script type="module" src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.esm.js"></script>
-<script nomodule src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.js"></script>
-
- 3. Import the web components in src/main.tsx
- import "@abgov/web-components";
-
- 4. Import the styles in src/index.css
- @import "@abgov/web-components/index.css";
-@import "@abgov/design-tokens/dist/tokens.css";
-
- Web components
-
- This library contains web components from the Government of Alberta.
-
-
- 1. Add dependencies
- npm i @abgov/web-components
-npm i @abgov/design-tokens
-
- 2. Link ionicons in index.html
-
- Add the following in the head element:
-
- <script type="module" src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.esm.js"></script>
-<script nomodule src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.js"></script>
-
- 3. Import the web components into src/main.js
- import "@abgov/web-components";
-
- 4. Add the styles link in your main CSS file
-
- Add the following in src/assets/main.css or wherever your main CSS file is
- located:
-
- @import "@abgov/web-components/index.css";
-@import "@abgov/design-tokens/dist/tokens.css";
-
-
diff --git a/docs/src/pages/get-started/developers/technologies.astro b/docs/src/pages/get-started/developers/technologies.astro
deleted file mode 100644
index 272d9a8a12..0000000000
--- a/docs/src/pages/get-started/developers/technologies.astro
+++ /dev/null
@@ -1,111 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Developers - Technologies
- *
- * Overview of Design System technologies: Web Components, Svelte, Angular, React.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../../layouts/DocumentationPageLayout.astro';
----
-
-
- Technologies
-
- An overview of the technologies used in the Design System.
-
-
- How the technologies fit together
-
- The Design System is built on Web Components. Most component functionality lives in the core Web
- Components layer. Angular and React wrappers sit on top of that layer to make the components easier
- to use in those frameworks.
-
-
- We use Svelte to author the components that are compiled to custom elements. You can use the Design
- System through the core Web Components or through Angular and React wrappers.
-
-
- Web Components
-
- Web Components
- are a set of standard web technologies that allow you to create reusable custom elements. Each component
- includes its own structure, styling, and behaviour. This keeps it independent from the rest of your code.
-
-
- In the Design System, Web Components are the core library. They are framework-agnostic, so teams
- can use them in different front-end environments.
-
-
- Benefits of using Web Components
-
- - Reuse: Build once and use across pages, applications, and frameworks
- - Browser support: Work in modern browsers without additional libraries
- - Maintenance: Modular and self-contained structure simplifies updates
- - Encapsulation: Structure, style, and behaviour remain isolated from other page elements
- - Reliability: Code is not spread across HTML and JS files, thereby avoiding inconsistencies
- - Flexibility: Use inline, import, or compile components as needed
- - Composability: Combine components or integrate them with other components
-
-
-
- Do not use Web Components directly unless there is a specific reason to do so. Using wrappers provides
- type checking and developer helpers that are not available when working with the core Web Components alone.
-
- Svelte
-
- Svelte is the framework used to generate the
- Design System Web Components. Svelte combines JavaScript (logic), HTML (structure), and CSS (style)
- within a single file. It compiles these into efficient, reusable components.
-
- Why Svelte
- We use Svelte to:
-
- - Build reusable Web Components
- - Keep component logic, structure, and styling together
- - Support integration with multiple front-end frameworks
-
- Angular
-
-
- Supported versions: 18, 19, 20, 21
-
-
-
- Angular is a TypeScript-based framework for building
- web applications. The Design System supports Angular through Angular wrappers around the core Web Components.
-
-
- How Web Components and Angular work together
- Angular wrappers are created around the Web Components. These wrappers:
-
- - Manage component properties and events
- - Support form binding (Reactive and Template-driven)
- - Allow integration within Angular applications
-
- The Angular application interacts with the wrapper, which renders the underlying Web Component.
- React
-
-
- Supported versions: 17, 18, 19
-
-
-
- React is an open-source JavaScript library used to
- build user interfaces from reusable components.
-
-
- How Web Components and React work together
- React wrappers are created around the Web Components. These wrappers:
-
- - Manage properties and events
- - Enable integration within React applications
-
- The React application interacts with the wrapper, which renders the underlying Web Component.
-
diff --git a/docs/src/pages/get-started/index.astro b/docs/src/pages/get-started/index.astro
deleted file mode 100644
index 1b92e400aa..0000000000
--- a/docs/src/pages/get-started/index.astro
+++ /dev/null
@@ -1,108 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Landing Page
- *
- * Overview of the design system and how to use it in your service.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Start with the design system
-
- Start with the design system to build on the research and experience of other service teams.
- This helps you avoid repeating work that has already been done.
-
-
-
- The design system gives you a strong foundation for common service needs. It allows your team
- to focus on the specific challenges of your product.
- Build on it. Do not start from scratch.
-
-
- Design system by role
-
-
-
- Why start with the design system?
-
- Streamline collaboration
-
- Designers and developers work from shared components and guidance. This reduces rework and misalignment.
-
-
- Improve accessibility
- Accessibility is built into both the design and coded components.
-
- Reduce testing effort
- Components are tested across devices, browsers, and service contexts.
-
- Maintain consistency
-
- Components align with the broader system to create a cohesive user experience across government services.
-
-
- Spend more time on high-value work
- Using existing components saves time. You can focus on work that improves service quality, including:
-
- - Usability testing
- - User research
- - Content design
- - Accessibility reviews
- - Design quality checks
- - Low-fidelity prototyping and testing
-
- This leads to better outcomes for users.
- How to use the design system in your service
- Follow these steps when designing and building your service.
-
- Use system components first
- Start with existing components and patterns. These meet most user needs.
-
- Identify gaps through user testing
- Test your service with users. Identify needs that are not covered by current components.
-
- Before you design something new
-
- Check what's already available and what's in progress. The team can point you to existing components,
- solutions other teams have built, and planned work that may meet your need.
-
-
- Design and test new solutions when you need them
-
- If you still have a gap, design a new solution and test it with users. Move forward only when
- testing shows clear user value.
-
-
- Share what you learn
-
- Share your findings with the design system team. Your solution may become part of the design system.
-
-
-
- Do not create custom components without a clear user need.
- Unnecessary customization:
-
- - Increases maintenance effort
- - Slows delivery
- - Reduces consistency
-
- Always confirm the need through research and testing.
-
-
-
- View the design system governance process
-
-
diff --git a/docs/src/pages/get-started/migration-guide.astro b/docs/src/pages/get-started/migration-guide.astro
deleted file mode 100644
index b43c6678e3..0000000000
--- a/docs/src/pages/get-started/migration-guide.astro
+++ /dev/null
@@ -1,232 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Developers - Migration guide
- *
- * Migration pathways and guidance for moving products from DS 1.x to DS 2.0.
- * Content adapted from Confluence.
- */
-import DocumentationPageLayout from "../../layouts/DocumentationPageLayout.astro";
----
-
-
- Migration guide
-
- Design System 2.0 (DS 2.0) becomes the Government of Alberta standard in March 2026.
- New products starting after launch should use DS 2.0. Existing active products should
- plan their move to DS 2.0 during the recommended migration window, which runs from
- March 2026 to September 2026.
-
-
- Migration pathways
-
- The right migration path depends on your product's context, including team
- funding and capacity, other delivery obligations, product lifecycle, and the effort
- required to update. The three pathways are standard migration, late migration, and no
- migration.
-
-
- Starting a new product
-
- If your product starts after March 2026, start with DS 2.0. Migration pathways apply
- to existing products moving from DS 1.x to DS 2.0.
-
-
- Compare the pathways
-
-
-
-
-
- Pathway
- Use it when
- Recommendation
-
-
-
-
-
- Standard migration
-
-
-
- Your product has an active funded team and can migrate by September 2026
-
-
-
- Recommended default
-
-
-
-
- Late migration
-
-
-
- Your team cannot meet the standard window because of delivery timelines,
- dependencies, or capacity constraints
-
-
-
- Only when necessary
-
-
-
-
- No migration
-
-
-
- Your product does not have an active funded team and/or is not in a
- position to upgrade
-
-
-
- Only in specific cases
-
-
-
-
-
-
-
-
- Standard migration
-
-
- Standard migration is the default pathway for active products.
-
-
- Choose this path if your product has an active funded team and can schedule migration
- work between March 2026 and September 2026. This is the recommended path for most
- teams because it keeps your product aligned with the current standard and gives you
- the best support.
-
- Use this pathway when:
-
-
- - your product is actively maintained
- - your team can reserve time to migrate by September 2026
- - you want access to the latest templates, components, tokens, and guidance
-
-
-
- Plan for work across the product team. Typical upgrade tasks include the library
- updates, adjusting spacing and typography, and updating custom code to align with the
- DS 2.0 visual design. This is a significant update and will usually involve design,
- development, and testing.
-
-
- Late migration
-
- Late migration is a last-resort pathway for active products.
-
-
- Choose this path only when delivery deadlines, dependencies, or capacity constraints
- make the standard migration window unrealistic. This path gives your team more time,
- but it also increases risk and reduces your ongoing support.
-
- Use this pathway when:
-
-
- - a major delivery deadline blocks migration work
- - critical dependencies prevent the upgrade during the standard window
- - capacity or funding makes the standard window unrealistic
-
-
-
- Delaying migration means your product will wait longer to benefit from DS 2.0
- improvements. Over time, unresolved issues will accumulate and your product will be
- inconsistent with the new standard for longer.
-
-
- No migration
-
- No migration is an opt-out pathway for specific situations.
-
-
- Choose this path only when your product does not have an active funded team and/or is
- not in a position to upgrade. In these cases, the product may remain on DS 1.x.
-
-
- Teams on this path should understand that the product will not receive DS 2.0
- improvements and will not align with the current standard. Support for DS 1.x is
- limited from March to September and ends after September 2026.
-
-
- What changes after launch
-
- After the DS 2.0 launch in March 2026:
-
-
-
- - New products should use DS 2.0
- - Active products should aim to migrate by September 2026
- -
- After launch, web components will move to version 2.x. Although this is a major
- version update, it does not include breaking changes.
-
- -
- Angular 4.x and React 6.x receive limited fixes or features from March to
- September
-
- - Support for DS 1.0 ends after September 2026
- - Web components will update to a new major version after September 2026
-
-
-
- How to choose a pathway
-
- Use these questions to guide your decision:
-
-
-
- - Is this a new product starting after March 2026?
- - Does the product have an active funded team?
- - Can the team schedule migration work before September 2026?
- -
- Are there delivery deadlines or dependencies that block the standard window?
-
- -
- Is the team prepared to accept reduced support and higher maintenance risk if
- migration is delayed?
-
-
-
-
- Related guidance
-
- Review the setup steps for developers
-
-
diff --git a/docs/src/pages/get-started/out-of-support.astro b/docs/src/pages/get-started/out-of-support.astro
deleted file mode 100644
index 3944d67e3a..0000000000
--- a/docs/src/pages/get-started/out-of-support.astro
+++ /dev/null
@@ -1,54 +0,0 @@
----
-import { withBase } from '@/lib/base-url';
-/**
- * Get Started - Out of Support Versions
- *
- * Information about unsupported Design System versions.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- Out-of-support versions
-
- With the launch of the new Design System, support for Angular v4 and lower, and React v6 and lower
- is significantly reduced.
-
-
- What this means
-
- Fewer fixes or patches
- Bug fixes and security updates are no longer prioritized for these versions.
-
- No new features
- All new features and enhancements are released only in the current major version.
-
- Use at your own risk
- Existing projects may continue to run. However:
-
- - Compatibility with new browsers or operating systems is not guaranteed
- - Compatibility with future framework updates is not guaranteed
- - Issues discovered in these versions will not be resolved
-
-
-
- Projects using Angular v4 and lower, and React v6 and lower will continue to function.
- New issues or defects identified in these versions may not be fixed.
-
- What to do next
-
- Upgrade to the latest supported version. Refer to the
- version update guide.
-
-
- If you need support planning your upgrade,
- book time in drop-in hours.
-
-
diff --git a/docs/src/pages/get-started/qa-testing.astro b/docs/src/pages/get-started/qa-testing.astro
deleted file mode 100644
index 146cb12778..0000000000
--- a/docs/src/pages/get-started/qa-testing.astro
+++ /dev/null
@@ -1,77 +0,0 @@
----
-/**
- * Get Started - QA Testing
- *
- * Testing process for Design System components.
- * Content from Confluence (Brief 87).
- */
-import DropInCallout from '../../components/DropInCallout.astro';
-import DocumentationPageLayout from '../../layouts/DocumentationPageLayout.astro';
----
-
-
- QA testing
-
- This page outlines the testing process for the Design System. The process ensures components
- function correctly and integrate within products.
-
-
- Testing objectives
- QA testing ensures that:
-
- - Coded components match the design specifications
- - Components work in both React and Angular implementations
- - Components are responsive across screen sizes
- - Components meet accessibility requirements
- - Mobile behaviour is validated
- - Documentation on the Design System website is accurate
-
- Test cases
-
- Component testing
-
- - Confirm the rendered component matches design and styling guidelines
- - Confirm configured properties display correctly
- - Confirm the expected event triggers when interacting with the component
-
-
- Responsiveness testing
-
- - Test components on mobile, tablet, and desktop screen sizes
- - Use browser developer tools to simulate devices
-
-
- Accessibility testing
-
- - Run Lighthouse audits to review accessibility scores
- - Confirm appropriate ARIA (Accessible Rich Internet Applications) roles and labels
- - Test keyboard navigation
- - Test with NVDA screen reader
-
-
- Cross-browser testing
-
- - Test on the latest versions of Chrome, Firefox, Safari, and Edge
- - Use Chrome device mode to simulate mobile environments
- - Confirm consistent appearance and behaviour across browsers
-
-
- Bug testing
- When a bug is fixed:
-
- - Reproduce the issue using the main branch.
- - Verify the fix in the pull request branch.
- - Retest the component across all relevant areas.
-
- Confirm the issue no longer occurs.
- Reporting
-
- - Document updated test results, findings, and screenshots in the pull request comments
- - Log newly discovered issues in GitHub
-
-
diff --git a/docs/src/pages/get-started/roadmap.astro b/docs/src/pages/get-started/roadmap.astro
deleted file mode 100644
index 070656eab6..0000000000
--- a/docs/src/pages/get-started/roadmap.astro
+++ /dev/null
@@ -1,347 +0,0 @@
----
-/**
- * Get Started - Roadmap
- *
- * High-level roadmap for the design system team's 2026-27 fiscal year.
- * Content adapted from Confluence.
- */
-import DocumentationPageLayout from "../../layouts/DocumentationPageLayout.astro";
----
-
-
- Roadmap
-
- A high-level summary of the work the design system team plans to focus on in the
- 2026-27 Fiscal Year.
-
-
-
- The roadmap is subject to change as we gather new information. We will communicate
- updates to ensure product teams can align and plan their work accordingly.
-
-
-
- For more details on our priorities and day-to-day activities, see our
-
- design system backlog.
-
-
-
- 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.
-
-
- 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.
-
-
- Examples:
-
-
- -
-
Create a mechanism to reliably collect and report adoption rate
-
- -
-
Track upgrade progress against the adoption schedule
-
- -
-
Capture qualitative signals from teams (developer and designer feedback themes)
-
- -
-
Capture end-user feedback where available (citizen or worker satisfaction,
- accessibility and usability feedback)
-
-
-
- Product acceleration enablement
-
- Objective: Provide prescriptive guidance and resources that help teams
- get to screens, prototypes, and working experiences faster using DS 2.0.
-
-
- 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
-
- -
-
Provide contextual starting points for teams using Public form and Workspace
- templates
-
- -
-
Pilot DS 2.0 with teams to generate strong examples to share
-
- -
-
Create and publish migration success stories
-
-
-
- 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.
-
-
- Examples:
-
-
- -
-
Define the initial MCP scope and supported design system resources
-
- -
-
Stand up the MCP server and validate the hosting and maintenance approach
-
- -
-
Test the MCP use in real product workflows and capture gaps to address
-
- -
-
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.
-
-
- Examples:
-
-
- -
-
Define what "official Vue support" means
-
- -
-
Outline the minimum supportable scope
-
- -
-
Identify implications for documentation, maintenance, testing, and support
-
-
-
- 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:
-
-
- -
-
Build the review, revise, resubmit feature
-
-
-
- Examples and pattern maturity
-
- Objective: Expand and refine examples and position them as adaptable reusable
- patterns that teams can apply with confidence.
-
-
- Benefit: Improves self-serve success and product consistency, reducing
- implementation variance and support demand over time.
-
-
- Examples:
-
-
- -
-
Continue expanding and refining examples
-
- -
-
Show how components and examples combine into larger contexts and workflows
-
-
-
- Library packaging and tech stack upgrades
-
- Objective: Reduce friction in how design system assets are bundled and
- adopted across libraries and update important tech stacks.
-
-
- Benefit: Lowers setup and upgrade complexity, and keeps the design system
- up to date with the latest supported versions.
-
-
- Examples:
-
-
- -
-
Improve how code libraries are bundled together (React, web components, tokens)
-
- -
-
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.
-
-
- Documentation and communications improvements
-
- Objective: Improve how teams access and understand design system guidance,
- and communicate design system value areas like accessibility more clearly.
-
-
- Benefit: Increases trust, improves reuse, and supports self-serve adoption
- by making guidance easier to consume and share.
-
-
- Examples:
-
-
- -
-
Add markdown file download to website documentation
-
- -
-
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.
-
-
- 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:
-
-
-
- -
-
Focus migration support on late adopters facing systemic barriers to upgrading
-
-
-
diff --git a/docs/src/pages/index.astro b/docs/src/pages/index.astro
index 1c720ba5a7..d925a33b14 100644
--- a/docs/src/pages/index.astro
+++ b/docs/src/pages/index.astro
@@ -76,26 +76,6 @@ import CardLite from '../components/CardLite.astro';
/>
-
- Research tools
-
- Conduct research with your users to validate your design decisions. Test your assumptions, gather insights, and ensure your service meets real user needs.
-
-
- Understand your service
@@ -103,24 +83,44 @@ import CardLite from '../components/CardLite.astro';
Research tools
+
+ Conduct research with your users to validate your design decisions. Test your assumptions, gather insights, and ensure your service meets real user needs.
+
+
+
@@ -28,6 +30,7 @@ const navCategories = await getNavCategories();
client:only="react"
initialSection="components"
categories={navCategories}
+ getStartedNav={getStartedNav}
/>
diff --git a/docs/src/scripts/aliases-to-redirects.mjs b/docs/src/scripts/aliases-to-redirects.mjs
new file mode 100644
index 0000000000..b8cb3254f2
--- /dev/null
+++ b/docs/src/scripts/aliases-to-redirects.mjs
@@ -0,0 +1,114 @@
+/**
+ * Build a redirects map from `aliases` frontmatter on entries in the
+ * examples and productTypes content collections.
+ *
+ * Each alias on an entry becomes a redirect from `/examples/${alias}` to
+ * the entry's canonical URL. Both collections route under `/examples/`,
+ * so product-type aliases (none today, but supported) also redirect there
+ * via the [family] route.
+ *
+ * Imported from astro.config.mjs at config-load time. Sync fs reads keep
+ * the function callable before the content collection pipeline runs.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DOCS_ROOT = join(__dirname, "../..");
+
+const COLLECTION_ROOTS = [
+ join(DOCS_ROOT, "src/content/examples"),
+ join(DOCS_ROOT, "src/content/productTypes"),
+];
+
+/**
+ * Minimal YAML frontmatter parser. Mirrors the parser in
+ * build-search-index.ts. Only handles the subset our content uses:
+ * scalar values and list-of-strings for `aliases`.
+ */
+function parseFrontmatter(content) {
+ const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+ if (!match) return {};
+
+ const result = {};
+ let currentKey = null;
+ let currentArray = null;
+
+ for (const line of match[1].split("\n")) {
+ const arrayItem = line.match(/^\s+-\s+(.*)/);
+ if (arrayItem && currentArray) {
+ currentArray.push(arrayItem[1].trim());
+ continue;
+ }
+
+ const kv = line.match(/^(\w+):\s*(.*)/);
+ if (!kv) continue;
+
+ if (currentKey && currentArray) {
+ result[currentKey] = currentArray;
+ }
+ currentKey = kv[1];
+ const value = kv[2].trim();
+ if (value === "" || value === "|") {
+ currentArray = [];
+ } else {
+ currentArray = null;
+ result[currentKey] = value.replace(/^["']|["']$/g, "");
+ }
+ }
+
+ if (currentKey && currentArray) {
+ result[currentKey] = currentArray;
+ }
+ return result;
+}
+
+/**
+ * Recursively find every `index.mdx` under a collection root, including
+ * nested entries like `examples/workspace/dashboard/index.mdx`.
+ */
+function findIndexMdx(dir) {
+ const out = [];
+ for (const entry of readdirSync(dir)) {
+ const path = join(dir, entry);
+ if (!statSync(path).isDirectory()) continue;
+ const indexPath = join(path, "index.mdx");
+ try {
+ if (statSync(indexPath).isFile()) out.push(indexPath);
+ } catch {
+ // No index.mdx in this directory; keep recursing.
+ }
+ out.push(...findIndexMdx(path));
+ }
+ return out;
+}
+
+export function buildAliasRedirects() {
+ const redirects = {};
+
+ for (const root of COLLECTION_ROOTS) {
+ try {
+ statSync(root);
+ } catch {
+ continue;
+ }
+
+ for (const file of findIndexMdx(root)) {
+ const fm = parseFrontmatter(readFileSync(file, "utf-8"));
+ if (!Array.isArray(fm.aliases) || fm.aliases.length === 0) continue;
+
+ const slug = relative(root, dirname(file));
+ const target = `/examples/${slug}`;
+
+ for (const alias of fm.aliases) {
+ const from = `/examples/${alias}`;
+ if (from === target) continue;
+ redirects[from] = target;
+ }
+ }
+ }
+
+ return redirects;
+}
diff --git a/docs/src/scripts/build-search-index.ts b/docs/src/scripts/build-search-index.ts
index 3b2258ff69..e6c4137fa8 100644
--- a/docs/src/scripts/build-search-index.ts
+++ b/docs/src/scripts/build-search-index.ts
@@ -8,7 +8,7 @@
*/
import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdirSync } from 'node:fs';
-import { join, basename, dirname } from 'node:path';
+import { join, basename, dirname, relative, sep } from 'node:path';
import { fileURLToPath } from 'node:url';
// Get directory paths relative to this script
@@ -20,6 +20,8 @@ const ROOT = join(__dirname, '../..');
// Content directories
const COMPONENTS_DIR = join(ROOT, 'src/content/components');
const EXAMPLES_DIR = join(ROOT, 'src/content/examples');
+const GET_STARTED_DIR = join(ROOT, 'src/content/get-started');
+const PRODUCT_TYPES_DIR = join(ROOT, 'src/content/productTypes');
const OUTPUT_FILE = join(ROOT, 'public/search-index.json');
// ============================================================================
@@ -43,15 +45,26 @@ interface ExampleEntry {
title: string;
description?: string;
status: string;
- categories: string[];
+ size: string; // "interaction" | "section" | "page" | "task" | "product"
+ productType?: string; // "workspace" | "public-form"
tags: string[];
- components: string[]; // What components this example uses
- scale: string;
- userType: string;
+ components: string[]; // What components this example uses
+ aliases: string[]; // Secondary slugs that surface this entry in search
slug: string;
}
-type SearchEntry = ComponentEntry | ExampleEntry;
+interface PageEntry {
+ type: 'page';
+ id: string;
+ title: string;
+ description?: string;
+ status: string;
+ category: string; // High-level grouping for filter UI ("get started")
+ tags: string[]; // Synthesized from section so queries like "developer setup" hit
+ slug: string; // URL path without leading slash (e.g. "get-started/developers/setup")
+}
+
+type SearchEntry = ComponentEntry | ExampleEntry | PageEntry;
// ============================================================================
// Frontmatter Parsing
@@ -155,6 +168,20 @@ function extractFirstParagraph(body: string): string | undefined {
return paragraph || undefined;
}
+function isHidden(frontmatter: Record): boolean {
+ return String(frontmatter.hidden ?? '').toLowerCase() === 'true';
+}
+
+function normalizeDescription(value: string | undefined): string | undefined {
+ if (!value) return undefined;
+
+ const withoutHtml = value.replace(/<[^>]+>/g, ' ');
+ const withoutMarkdownLinks = withoutHtml.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '$1');
+ const normalized = withoutMarkdownLinks.replace(/\s+/g, ' ').trim();
+
+ return normalized || undefined;
+}
+
// ============================================================================
// File Processing
// ============================================================================
@@ -170,7 +197,7 @@ function processComponent(filePath: string): ComponentEntry | null {
const id = basename(filePath, '.mdx');
// Skip hidden components
- if (frontmatter.hidden === true || frontmatter.hidden === 'true') {
+ if (isHidden(frontmatter)) {
return null;
}
@@ -178,7 +205,9 @@ function processComponent(filePath: string): ComponentEntry | null {
type: 'component',
id,
name: String(frontmatter.name || id),
- description: frontmatter.description ? String(frontmatter.description) : undefined,
+ description: normalizeDescription(
+ frontmatter.description ? String(frontmatter.description) : undefined,
+ ),
status: String(frontmatter.status || 'stable'),
category: String(frontmatter.category || 'utilities'),
tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : [],
@@ -193,15 +222,27 @@ function processComponent(filePath: string): ComponentEntry | null {
/**
* Process an example MDX file into a search entry.
* Examples live in subdirectories: examples/[name]/index.mdx
+ * or nested: examples/[family]/[page]/index.mdx
+ *
+ * The slug is derived from the path relative to EXAMPLES_DIR so that nested
+ * entries (workspace/dashboard, etc.) get path-shaped slugs matching Astro's
+ * content-collection routing. Frontmatter `id` is kept for stable cross-
+ * references but no longer drives the URL.
*/
function processExample(filePath: string): ExampleEntry | null {
try {
const content = readFileSync(filePath, 'utf-8');
const { frontmatter, body } = parseFrontmatter(content);
- // Get ID from directory name
- const dirName = basename(dirname(filePath));
- const id = String(frontmatter.id || dirName);
+ // Skip hidden examples
+ if (isHidden(frontmatter)) {
+ return null;
+ }
+
+ // Slug = path within EXAMPLES_DIR (e.g., "workspace/dashboard", "start-page").
+ // Use forward slashes on every OS so URLs are consistent.
+ const slug = relative(EXAMPLES_DIR, dirname(filePath)).split(sep).join('/');
+ const id = String(frontmatter.id || basename(dirname(filePath)));
// Extract description from body if not in frontmatter
const description = frontmatter.description
@@ -212,18 +253,20 @@ function processExample(filePath: string): ExampleEntry | null {
type: 'example',
id,
title: String(frontmatter.title || id),
- description,
+ description: normalizeDescription(description),
status: String(frontmatter.status || 'published'),
- categories: Array.isArray(frontmatter.categories)
- ? frontmatter.categories.map(String)
- : [],
+ size: String(frontmatter.size || 'section'),
+ productType: frontmatter.productType
+ ? String(frontmatter.productType)
+ : undefined,
tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : [],
components: Array.isArray(frontmatter.components)
? frontmatter.components.map(String)
: [],
- scale: String(frontmatter.scale || 'interaction'),
- userType: String(frontmatter.userType || 'both'),
- slug: String(frontmatter.slug || id),
+ aliases: Array.isArray(frontmatter.aliases)
+ ? frontmatter.aliases.map(String)
+ : [],
+ slug,
};
} catch (error) {
console.error(`Error processing example ${filePath}:`, error);
@@ -231,6 +274,110 @@ function processExample(filePath: string): ExampleEntry | null {
}
}
+/**
+ * Synthesize search tags from a Get Started section.
+ * Includes the singular form so a query like "developer setup" matches
+ * a page whose section is "developers".
+ */
+function tagsForSection(section: string): string[] {
+ const singular: Record = {
+ designers: 'designer',
+ developers: 'developer',
+ };
+ const tags = [section];
+ if (singular[section]) tags.push(singular[section]);
+ return tags;
+}
+
+/**
+ * Process a Get Started MDX file into a search entry.
+ * The collection root holds the index page; nested folders are URL segments.
+ */
+function processGetStartedPage(filePath: string): PageEntry | null {
+ try {
+ const content = readFileSync(filePath, 'utf-8');
+ const { frontmatter } = parseFrontmatter(content);
+
+ // Derive ID from path relative to the collection root, minus the extension.
+ // e.g. "developers/setup.mdx" -> "developers/setup"
+ // Normalize backslashes to forward slashes so Windows-built indexes still produce valid URLs.
+ const relPath = filePath
+ .slice(GET_STARTED_DIR.length + 1)
+ .replace(/\.mdx$/, '')
+ .replace(/\\/g, '/');
+
+ // The index entry lives at /get-started, every other entry under /get-started/.
+ const slug = relPath === 'index' ? 'get-started' : `get-started/${relPath}`;
+
+ const section = String(frontmatter.section || '');
+
+ return {
+ type: 'page',
+ id: String(frontmatter.id || relPath),
+ title: String(frontmatter.title || relPath),
+ description: frontmatter.description ? String(frontmatter.description) : undefined,
+ status: String(frontmatter.status || 'published'),
+ category: 'get started',
+ tags: section ? tagsForSection(section) : [],
+ slug,
+ };
+ } catch (error) {
+ console.error(`Error processing get-started page ${filePath}:`, error);
+ return null;
+ }
+}
+
+/**
+ * Process a productType MDX file into a search entry.
+ *
+ * ProductTypes are the "starting points" for each kind of digital service
+ * (workspace, public-form). Their overview pages live at /examples/[slug]/
+ * via the [family]/index.astro route, so we synthesize them into the same
+ * search shape as page-scale examples with size="product". This replaces
+ * the hand-authored stub entries that previously lived in examples/.
+ */
+function processProductType(filePath: string): ExampleEntry | null {
+ try {
+ const content = readFileSync(filePath, 'utf-8');
+ const { frontmatter, body } = parseFrontmatter(content);
+
+ const slug = relative(PRODUCT_TYPES_DIR, dirname(filePath))
+ .split(sep)
+ .join('/');
+ const id = String(frontmatter.id || slug);
+
+ // Summary may contain inline HTML formatting (br, span) for the overview
+ // page. Take the prose before the first tag — enough for search results,
+ // which truncate to ~80 chars anyway, and safer than regex-stripping.
+ const description = frontmatter.summary
+ ? String(frontmatter.summary).split('<')[0].trim()
+ : frontmatter.description
+ ? String(frontmatter.description)
+ : extractFirstParagraph(body);
+
+ return {
+ type: 'example',
+ id,
+ title: String(frontmatter.title || id),
+ description,
+ status: String(frontmatter.status || 'published'),
+ size: 'product',
+ productType: undefined,
+ tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : [],
+ components: Array.isArray(frontmatter.components)
+ ? frontmatter.components.map(String)
+ : [],
+ aliases: Array.isArray(frontmatter.aliases)
+ ? frontmatter.aliases.map(String)
+ : [],
+ slug,
+ };
+ } catch (error) {
+ console.error(`Error processing productType ${filePath}:`, error);
+ return null;
+ }
+}
+
/**
* Recursively find all MDX files in a directory.
*/
@@ -288,6 +435,32 @@ function main() {
}
console.log(` Found ${exampleFiles.length} files, indexed ${entries.length - exampleCount} examples`);
+ // Process Get Started pages
+ console.log('Processing get-started pages...');
+ const getStartedFiles = findMdxFiles(GET_STARTED_DIR);
+ const getStartedCount = entries.length;
+ for (const file of getStartedFiles) {
+ const entry = processGetStartedPage(file);
+ if (entry) {
+ entries.push(entry);
+ }
+ }
+ console.log(` Found ${getStartedFiles.length} files, indexed ${entries.length - getStartedCount} pages`);
+
+ // Process productTypes (workspace, public-form, etc.) — surfaced as
+ // size:product overview entries so the same Cmd-K query that finds a
+ // page-scale entry also finds the introductory page for its product type.
+ console.log('Processing productTypes...');
+ const productTypeFiles = findMdxFiles(PRODUCT_TYPES_DIR);
+ const productTypeCountBefore = entries.length;
+ for (const file of productTypeFiles) {
+ const entry = processProductType(file);
+ if (entry) {
+ entries.push(entry);
+ }
+ }
+ console.log(` Found ${productTypeFiles.length} files, indexed ${entries.length - productTypeCountBefore} productTypes`);
+
// Ensure public directory exists
const publicDir = dirname(OUTPUT_FILE);
if (!existsSync(publicDir)) {
diff --git a/docs/src/scripts/extract-api.ts b/docs/src/scripts/extract-api.ts
index 2c7f7cadee..6eb01bdedc 100644
--- a/docs/src/scripts/extract-api.ts
+++ b/docs/src/scripts/extract-api.ts
@@ -15,6 +15,7 @@
import * as fs from "fs";
import * as path from "path";
import { fileURLToPath } from "url";
+import * as ts from "typescript";
// =============================================================================
// Configuration
@@ -31,6 +32,10 @@ const UI_COMPONENTS_PATH = path.join(
"libs/web-components/src/components",
);
const OUTPUT_PATH = path.join(WORKSPACE_ROOT, "docs/generated/component-apis");
+const DOCS_COMPONENT_CONTENT_PATH = path.join(
+ WORKSPACE_ROOT,
+ "docs/src/content/components",
+);
// =============================================================================
// Output Types (matching content model spec)
@@ -51,20 +56,36 @@ interface ExtractedEvent {
name: string;
type: string;
description: string; // Empty - filled by human content
- frameworks: ("react" | "angular" | "web-component")[];
+ frameworks: ("react" | "angular" | "webComponents")[];
}
interface ExtractedSlot {
name: string;
+ type?: string;
description: string; // Empty - filled by human content
+ required?: boolean;
}
interface ExtractedComponentAPI {
componentSlug: string;
extractedFrom: string;
- props: ExtractedProp[];
- events: ExtractedEvent[];
- slots: ExtractedSlot[];
+ frameworks: {
+ react: {
+ props: ExtractedProp[];
+ events: ExtractedEvent[];
+ slots: ExtractedSlot[];
+ };
+ angular: {
+ props: ExtractedProp[];
+ events: ExtractedEvent[];
+ slots: ExtractedSlot[];
+ };
+ webComponents: {
+ props: ExtractedProp[];
+ events: ExtractedEvent[];
+ slots: ExtractedSlot[];
+ };
+ };
}
// =============================================================================
@@ -90,6 +111,119 @@ interface ParsedPropRaw {
deprecated: boolean;
}
+interface WrapperExtraction {
+ found: boolean;
+ props: ExtractedProp[];
+ events: ExtractedEvent[];
+ slotDescriptions: Record;
+ slotNameAliases: Record;
+ slotRequired: Record;
+}
+
+const INTERNAL_PROP_NAMES = new Set(["publicformsummaryorder", "filterablecontext", "version"]);
+const INTERNAL_SLOT_NAMES = new Set(["version"]);
+const INTERNAL_EVENT_NAMES = new Set(["_revealChange", "_update"]);
+
+const DOCS_EXCLUDED_COMPONENTS = new Set(["focus-trap", "form-stepper", "scrollable"]);
+const DOCS_FORCED_COMPONENTS = new Set(["table-sort-header"]);
+const WRAPPER_COMPONENT_ALIASES: Record = {
+ "temporary-notification": "temporary-notification-ctrl",
+};
+const WEB_COMPONENT_INTERNAL_EVENT_OVERRIDES: Record> = {
+ "work-side-menu-group": new Set(["_hoverItem"]),
+ "work-side-menu-item": new Set([
+ "_blurItem",
+ "_desktopPopoverClose",
+ "_desktopPopoverOpen",
+ "_hoverItem",
+ "_itemCurrent",
+ "_mobilePopoverClose",
+ "_mobilePopoverOpen",
+ "_mountItem",
+ "_navigate",
+ ]),
+};
+const WEB_COMPONENT_EVENT_TYPE_OVERRIDES: Record> = {
+ dropdown: {
+ _change: "CustomEvent<{ name?: string; value?: string; event: Event }>",
+ },
+ "file-upload-input": {
+ _selectFile: "CustomEvent<{ file: File; event: Event }>",
+ },
+};
+const SLOT_TYPE_OVERRIDES: Record<
+ string,
+ Partial>>
+> = {
+ footer: {
+ react: {
+ nav: "GoabAppFooterNavSection",
+ meta: "GoabAppFooterMetaSection",
+ },
+ angular: {
+ nav: "GoabAppFooterNavSection",
+ meta: "GoabAppFooterMetaSection",
+ },
+ webComponents: {
+ nav: "goa-app-footer-nav-section",
+ meta: "goa-app-footer-meta-section",
+ },
+ },
+};
+const ALLOW_INTERNAL_PROP_BY_COMPONENT: Record> = {
+ "microsite-header": new Set(["version"]),
+};
+
+function shouldSkipInternalProp(componentName: string, propName: string): boolean {
+ const normalizedComponentName = toKebabCase(componentName);
+ const normalizedName = propName.toLowerCase();
+ if (ALLOW_INTERNAL_PROP_BY_COMPONENT[normalizedComponentName]?.has(normalizedName)) {
+ return false;
+ }
+ return INTERNAL_PROP_NAMES.has(normalizedName);
+}
+
+function shouldAllowInternalProp(componentName: string, propName: string): boolean {
+ const normalizedComponentName = toKebabCase(componentName);
+ return Boolean(
+ ALLOW_INTERNAL_PROP_BY_COMPONENT[normalizedComponentName]?.has(propName.toLowerCase()),
+ );
+}
+
+function isInternalPropName(propName: string): boolean {
+ return INTERNAL_PROP_NAMES.has(propName.toLowerCase());
+}
+
+function isStandardV1V2VersionProp(prop: ExtractedProp | undefined): boolean {
+ if (!prop || prop.name.toLowerCase() !== "version") return false;
+
+ const values = (prop.values || []).map((value) => String(value).replace(/['"]/g, "").trim());
+ if (values.length === 2 && values.includes("1") && values.includes("2")) {
+ return true;
+ }
+
+ const normalizedType = String(prop.type || "")
+ .replace(/['"]/g, "")
+ .replace(/\s+/g, "");
+
+ return normalizedType === "1|2";
+}
+
+function specializeAngularValuePropFromReact(
+ angularProps: ExtractedProp[],
+ reactProps: ExtractedProp[],
+): void {
+ const angularValueProp = angularProps.find((prop) => prop.name === "value");
+ const reactValueProp = reactProps.find((prop) => prop.name === "value");
+
+ if (!angularValueProp || !reactValueProp) return;
+ if (angularValueProp.type !== "unknown | null | undefined") return;
+ if (!reactValueProp.type || reactValueProp.type === "unknown") return;
+
+ angularValueProp.type = reactValueProp.type;
+ angularValueProp.values = reactValueProp.values;
+}
+
// =============================================================================
// JSDoc Parser
// =============================================================================
@@ -153,11 +287,35 @@ function parseJSDocContent(rawComment: string): {
const description = cleaned
.replace(/@required\s*/gi, "")
.replace(/@internal\s*/gi, "")
+ .replace(/@deprecated\s*/gi, "")
.trim();
return { description, required, internal, deprecated };
}
+function parseDescriptionFromJSDoc(rawComment: string | undefined): string {
+ if (!rawComment) return "";
+ const { description } = parseJSDocContent(rawComment);
+ return description;
+}
+
+function extractDefaultFromDescription(description: string): {
+ description: string;
+ defaultValue: string | null;
+} {
+ const defaultMatch = description.match(/@default\s+([^@]+)/i);
+ const defaultValue = defaultMatch ? defaultMatch[1].trim().replace(/^["']|["']$/g, "") : null;
+ const cleanDescription = description.replace(/@default\s+([^@]+)/gi, "").trim();
+ return {
+ description: cleanDescription,
+ defaultValue,
+ };
+}
+
+function isReadonlyDescription(description: string): boolean {
+ return /read[ -]?only\b|set by the component\b/i.test(description);
+}
+
// =============================================================================
// Svelte Parser
// =============================================================================
@@ -274,18 +432,11 @@ function extractProps(
typeAliases: Map,
): ParsedPropRaw[] {
const props: ParsedPropRaw[] = [];
+ const customElementPropAttributeMap = extractCustomElementPropAttributeMap(content);
// Build JSDoc map for descriptions
const jsDocMap = buildJSDocMap(content);
- // Internal props to skip (used by public forms system, not useful for devs)
- const internalProps = new Set([
- "publicformsummaryorder",
- "action",
- "actionarg",
- "actionargs",
- ]);
-
// Match: export let propName: Type = defaultValue;
const propMatches = content.matchAll(
/export\s+let\s+(\w+)(?:\s*:\s*([^=;]+?))?(?:\s*=\s*([^;]+?))?;/g,
@@ -293,16 +444,18 @@ function extractProps(
for (const match of propMatches) {
const rawName = match[1];
- let type = match[2]?.trim() || "any";
const defaultStr = match[3]?.trim();
+ let type = match[2]?.trim() || inferTypeFromDefault(defaultStr);
// Skip private props (starting with _)
if (rawName.startsWith("_")) continue;
- // Skip internal props
- if (internalProps.has(rawName.toLowerCase())) continue;
+ // Keep `version` on Web Component docs; wrappers are filtered later.
+ if (rawName.toLowerCase() !== "version" && shouldSkipInternalProp(componentName, rawName)) {
+ continue;
+ }
- const name = toReactPropName(rawName);
+ const name = customElementPropAttributeMap.get(rawName) || rawName.toLowerCase();
let typeLabel: string | undefined;
let values: string[] | undefined;
@@ -317,8 +470,8 @@ function extractProps(
// Handle special types
if (type.includes("GoAIconType") || type.includes("GoaIconType")) {
- typeLabel = "GoAIconType";
- type = "GoAIconType";
+ typeLabel = "GoabIconType";
+ type = "GoabIconType";
} else if (type === "Spacing" || type.includes("Spacing")) {
typeLabel = "Spacing";
type = "Spacing";
@@ -382,12 +535,23 @@ function extractProps(
// Get JSDoc info from map (description + required flag)
const jsDocInfo = jsDocMap.get(rawName);
- // Skip @internal props — not for public API docs
- if (jsDocInfo?.internal) continue;
+ // Keep Svelte `version` visible in Web Component docs.
+ if (
+ jsDocInfo?.internal &&
+ rawName.toLowerCase() !== "version" &&
+ !shouldAllowInternalProp(componentName, rawName)
+ ) {
+ continue;
+ }
+
+ // Skip @deprecated props — not for public API docs
+ if (jsDocInfo?.deprecated) continue;
const description = jsDocInfo?.description || "";
- // Use @required from JSDoc if present, otherwise fall back to checking if no default value
- const isRequired = jsDocInfo?.required || defaultStr === undefined;
+ const isReadonly = isReadonlyDescription(description);
+ // Use @required from JSDoc if present, otherwise fall back to checking if no default value.
+ // Read-only, component-managed values should not be presented as consumer-required props.
+ const isRequired = Boolean(jsDocInfo?.required) || (!isReadonly && defaultStr === undefined);
props.push({
name,
@@ -406,12 +570,28 @@ function extractProps(
return props;
}
+function extractCustomElementPropAttributeMap(content: string): Map {
+ const map = new Map();
+ const optionsTagMatch = content.match(/();
@@ -435,17 +615,6 @@ function extractEvents(content: string): string[] {
}
}
- // Pattern 3: _rootEl?.dispatchEvent(new CustomEvent("_eventName", ...))
- const rootElMatches = content.matchAll(
- /_rootEl\??\s*\.?\s*dispatchEvent\s*\(\s*new\s+CustomEvent\s*\(\s*["']([^"']+)["']/g,
- );
- for (const match of rootElMatches) {
- const eventName = match[1];
- if (!eventName.includes("::")) {
- eventNames.add(eventName);
- }
- }
-
return Array.from(eventNames);
}
@@ -463,13 +632,893 @@ function extractSlots(content: string): string[] {
}
}
- // Default slot: or |>[^<]*<\/slot>)/.test(content);
- if (hasDefaultSlot && !seenNames.has("default")) {
- slotNames.unshift("default");
+ return slotNames;
+}
+
+function parseWrapperPropValues(type: string): string[] | undefined {
+ if (!type.includes("|")) return undefined;
+ const values = type
+ .split("|")
+ .map((v) => v.trim().replace(/['"]/g, ""))
+ .filter((v) => v.length > 0 && v !== "undefined" && v !== "null");
+ return values.length > 0 ? values : undefined;
+}
+
+function inferTypeFromDefault(defaultValue: string | undefined): string {
+ if (!defaultValue) return "any";
+
+ const trimmed = defaultValue.trim();
+ if (trimmed === "true" || trimmed === "false") return "boolean";
+ if (!isNaN(Number(trimmed))) return "number";
+ if (/^["'`]/.test(trimmed)) return "string";
+ if (trimmed.startsWith("[")) return "unknown[]";
+ if (trimmed.startsWith("{")) return "Record";
+
+ return "any";
+}
+
+function normalizeName(value: string): string {
+ return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function getMatchingSlotName(propName: string, slotNames: string[]): string | null {
+ if (propName === "children") {
+ return "default";
}
- return slotNames;
+ const normalizedPropName = normalizeName(propName);
+ const directMatch =
+ slotNames.find((slotName) => normalizeName(slotName) === normalizedPropName) ?? null;
+ if (directMatch) return directMatch;
+
+ // Common wrapper naming pattern: slot "account" exposed as prop "accountContent".
+ const contentSuffixMatch = propName.match(/^(.+?)content$/i);
+ if (contentSuffixMatch?.[1]) {
+ const baseName = normalizeName(contentSuffixMatch[1]);
+ return slotNames.find((slotName) => normalizeName(slotName) === baseName) ?? null;
+ }
+
+ return null;
+}
+
+interface ReactCallbackAliasInfo {
+ typeParam?: string;
+ defaultTypeArg?: string;
+ detailType: string;
+}
+
+interface ReactInterfaceInfo {
+ name: string;
+ exported: boolean;
+ extendsNames: string[];
+ declaration: ts.InterfaceDeclaration;
+}
+
+function getTypeReferenceName(typeNode: ts.TypeReferenceNode, sourceFile: ts.SourceFile): string {
+ const typeName = typeNode.typeName.getText(sourceFile);
+ return typeName.split(".").pop() || typeName;
+}
+
+function createTsSourceFile(filePath: string, content: string): ts.SourceFile {
+ const scriptKind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+ return ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, scriptKind);
+}
+
+function getNodeDecorators(node: ts.Node): readonly ts.Decorator[] {
+ if (typeof ts.canHaveDecorators === "function" && ts.canHaveDecorators(node)) {
+ return ts.getDecorators(node) ?? [];
+ }
+
+ const legacyDecorators = (node as { decorators?: readonly ts.Decorator[] }).decorators;
+ return legacyDecorators ?? [];
+}
+
+function getDecoratorCall(node: ts.Node, decoratorName: string): ts.CallExpression | null {
+ for (const decorator of getNodeDecorators(node)) {
+ const expression = decorator.expression;
+ if (ts.isCallExpression(expression) && ts.isIdentifier(expression.expression)) {
+ if (expression.expression.text === decoratorName) {
+ return expression;
+ }
+ }
+
+ if (ts.isIdentifier(expression) && expression.text === decoratorName) {
+ return null;
+ }
+ }
+
+ return null;
+}
+
+function isAngularInputRequired(inputDecoratorCall: ts.CallExpression | null): boolean {
+ if (!inputDecoratorCall || inputDecoratorCall.arguments.length === 0) return false;
+
+ const firstArg = inputDecoratorCall.arguments[0];
+ if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return false;
+
+ const requiredProp = firstArg.properties.find((prop) => {
+ if (!ts.isPropertyAssignment(prop)) return false;
+ if (ts.isIdentifier(prop.name)) return prop.name.text === "required";
+ if (ts.isStringLiteral(prop.name)) return prop.name.text === "required";
+ return false;
+ });
+
+ if (!requiredProp || !ts.isPropertyAssignment(requiredProp)) return false;
+
+ return requiredProp.initializer.kind === ts.SyntaxKind.TrueKeyword;
+}
+
+function hasDecorator(node: ts.Node, decoratorName: string): boolean {
+ for (const decorator of getNodeDecorators(node)) {
+ const expression = decorator.expression;
+ if (ts.isCallExpression(expression) && ts.isIdentifier(expression.expression)) {
+ if (expression.expression.text === decoratorName) {
+ return true;
+ }
+ }
+
+ if (ts.isIdentifier(expression) && expression.text === decoratorName) {
+ return true;
+ }
+ }
+
+ return false;
+}
+
+function parseReactInterfaces(content: string, filePath: string): Map {
+ const interfaces = new Map();
+ const sourceFile = createTsSourceFile(filePath, content);
+
+ for (const statement of sourceFile.statements) {
+ if (!ts.isInterfaceDeclaration(statement)) continue;
+
+ const name = statement.name.text;
+ const exported = statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+ const extendsNames =
+ statement.heritageClauses
+ ?.filter((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword)
+ .flatMap((clause) =>
+ clause.types
+ .map((typeNode) => typeNode.expression.getText(sourceFile))
+ .map((value) => value.split(".").pop() || value)
+ .filter(Boolean),
+ ) ?? [];
+
+ interfaces.set(name, {
+ name,
+ exported,
+ extendsNames,
+ declaration: statement,
+ });
+ }
+
+ return interfaces;
+}
+
+function resolvePrimaryReactPropsInterface(
+ componentName: string,
+ interfaces: Map,
+): string | null {
+ const componentPart = capitalize(toCamelCase(componentName));
+ const candidates = [`Goab${componentPart}Props`, `GoA${componentPart}Props`];
+
+ for (const name of candidates) {
+ const match = interfaces.get(name);
+ if (match?.exported) return name;
+ }
+
+ for (const name of candidates) {
+ if (interfaces.has(name)) return name;
+ }
+
+ for (const info of interfaces.values()) {
+ if (info.exported && /^(?:Goab|GoA)\w+Props$/.test(info.name)) {
+ return info.name;
+ }
+ }
+
+ for (const info of interfaces.values()) {
+ if (/^(?:Goab|GoA)\w+Props$/.test(info.name)) {
+ return info.name;
+ }
+ }
+
+ return null;
+}
+
+function collectReactInterfaceMembers(
+ interfaceName: string,
+ interfaces: Map,
+ sourceFile: ts.SourceFile,
+ visited: Set = new Set(),
+): ts.TypeElement[] {
+ if (visited.has(interfaceName)) return [];
+ visited.add(interfaceName);
+
+ const info = interfaces.get(interfaceName);
+ if (!info) return [];
+
+ const inheritedMembers = info.extendsNames.flatMap((baseName) =>
+ collectReactInterfaceMembers(baseName, interfaces, sourceFile, visited),
+ );
+
+ return [...inheritedMembers, ...info.declaration.members];
+}
+
+function getFunctionLikeFirstParameterType(
+ fn: ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression,
+): ts.TypeNode | null {
+ return fn.parameters[0]?.type ?? null;
+}
+
+function resolvePrimaryReactComponentParameterType(
+ componentName: string,
+ sourceFile: ts.SourceFile,
+): ts.TypeNode | null {
+ const componentPart = capitalize(toCamelCase(componentName));
+ const candidates = [`Goab${componentPart}`, `GoA${componentPart}`];
+
+ for (const statement of sourceFile.statements) {
+ if (
+ ts.isFunctionDeclaration(statement) &&
+ statement.name &&
+ candidates.includes(statement.name.text) &&
+ statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+ ) {
+ return getFunctionLikeFirstParameterType(statement);
+ }
+
+ if (
+ ts.isVariableStatement(statement) &&
+ statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+ ) {
+ for (const declaration of statement.declarationList.declarations) {
+ if (!ts.isIdentifier(declaration.name) || !candidates.includes(declaration.name.text)) continue;
+ if (!declaration.initializer) continue;
+
+ if (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer)) {
+ return getFunctionLikeFirstParameterType(declaration.initializer);
+ }
+ }
+ }
+ }
+
+ return null;
+}
+
+function collectReactTypeNodeMembers(
+ typeNode: ts.TypeNode | null,
+ interfaces: Map,
+ sourceFile: ts.SourceFile,
+ visitedTypeRefs: Set = new Set(),
+): ts.TypeElement[] {
+ if (!typeNode) return [];
+
+ if (ts.isParenthesizedTypeNode(typeNode)) {
+ return collectReactTypeNodeMembers(typeNode.type, interfaces, sourceFile, visitedTypeRefs);
+ }
+
+ if (ts.isIntersectionTypeNode(typeNode)) {
+ return typeNode.types.flatMap((memberType) =>
+ collectReactTypeNodeMembers(memberType, interfaces, sourceFile, visitedTypeRefs),
+ );
+ }
+
+ if (ts.isTypeLiteralNode(typeNode)) {
+ return [...typeNode.members];
+ }
+
+ if (ts.isTypeReferenceNode(typeNode)) {
+ const typeName = getTypeReferenceName(typeNode, sourceFile);
+ if (visitedTypeRefs.has(typeName)) return [];
+ visitedTypeRefs.add(typeName);
+ return collectReactInterfaceMembers(typeName, interfaces, sourceFile);
+ }
+
+ return [];
+}
+
+function hasReactMarginsInHierarchy(
+ interfaceName: string,
+ interfaces: Map,
+ visited: Set = new Set(),
+): boolean {
+ if (visited.has(interfaceName)) return false;
+ visited.add(interfaceName);
+
+ const info = interfaces.get(interfaceName);
+ if (!info) return false;
+
+ if (info.extendsNames.includes("Margins")) {
+ return true;
+ }
+
+ return info.extendsNames.some((baseName) =>
+ hasReactMarginsInHierarchy(baseName, interfaces, visited),
+ );
+}
+
+function extractReactCallbackAliases(sourceFile: ts.SourceFile): Map {
+ const aliases = new Map();
+ for (const statement of sourceFile.statements) {
+ if (!ts.isTypeAliasDeclaration(statement)) continue;
+ if (!ts.isFunctionTypeNode(statement.type)) continue;
+
+ const aliasName = statement.name.text;
+ const typeParam = statement.typeParameters?.[0]?.name.text;
+ const defaultTypeArg = statement.typeParameters?.[0]?.default?.getText(sourceFile)?.trim();
+ const detailType = cleanType(
+ statement.type.parameters[0]?.type?.getText(sourceFile)?.trim() || "unknown",
+ );
+
+ aliases.set(aliasName, {
+ typeParam,
+ defaultTypeArg,
+ detailType,
+ });
+ }
+
+ return aliases;
+}
+
+function parseGenericAliasUsage(type: string): { alias: string; typeArg?: string } {
+ const aliasMatch = type.match(/^([A-Za-z_]\w*)(?:<\s*([^>]+)\s*>)?$/);
+ if (!aliasMatch) {
+ return { alias: type };
+ }
+
+ return {
+ alias: aliasMatch[1],
+ typeArg: aliasMatch[2]?.trim(),
+ };
+}
+
+function resolveReactCallbackEventType(
+ callbackType: string,
+ callbackAliases: Map,
+): string {
+ if (callbackType.includes("=>")) {
+ return callbackType;
+ }
+
+ const { alias, typeArg } = parseGenericAliasUsage(callbackType);
+ const aliasInfo = callbackAliases.get(alias);
+ if (!aliasInfo) {
+ return callbackType;
+ }
+
+ const toFunctionSignature = (detailType: string) => `(detail: ${detailType}) => void`;
+
+ if (!aliasInfo.typeParam) {
+ return toFunctionSignature(aliasInfo.detailType);
+ }
+
+ const resolvedTypeArg = typeArg || aliasInfo.defaultTypeArg;
+ if (!resolvedTypeArg) {
+ return toFunctionSignature(aliasInfo.detailType);
+ }
+
+ const typeParamPattern = new RegExp(`\\b${aliasInfo.typeParam}\\b`, "g");
+ let resolvedDetailType = aliasInfo.detailType.replace(typeParamPattern, resolvedTypeArg);
+
+ // Keep docs concise when the generic argument matches the alias default.
+ if (aliasInfo.defaultTypeArg && resolvedTypeArg === aliasInfo.defaultTypeArg) {
+ const defaultGenericPattern = new RegExp(`\\<\\s*${escapeRegExp(resolvedTypeArg)}\\s*\\>`, "g");
+ resolvedDetailType = resolvedDetailType.replace(defaultGenericPattern, "");
+ }
+
+ return toFunctionSignature(resolvedDetailType);
+}
+
+function isReactCallbackAliasType(
+ type: string,
+ callbackAliases: Map,
+): boolean {
+ if (type.includes("=>")) {
+ return true;
+ }
+
+ const { alias } = parseGenericAliasUsage(type);
+ return callbackAliases.has(alias);
+}
+
+function isFunctionType(type: string): boolean {
+ return /^\(\s*[^)]*\)\s*=>\s*.+$/.test(type.trim());
+}
+
+function isSlotCarrierType(type: string): boolean {
+ return /React(?:\.[A-Za-z]+)?(?:Node|Element)(?:<.+?>)?|JSX\.Element|TemplateRef\s*<.+?>/.test(type);
+}
+
+function isPureSlotCarrierType(type: string): boolean {
+ const members = type
+ .split("|")
+ .map((part) => part.trim())
+ .filter((part) => part.length > 0 && part !== "null" && part !== "undefined");
+
+ if (members.length === 0) return false;
+ return members.every((part) => isSlotCarrierType(part));
+}
+
+function toEventCallbackType(type: string): string {
+ if (type === "void") {
+ return "() => void";
+ }
+ return `(event: ${type}) => void`;
+}
+
+function dedupeByName(items: T[]): T[] {
+ const seen = new Set();
+ return items.filter((item) => {
+ if (seen.has(item.name)) return false;
+ seen.add(item.name);
+ return true;
+ });
+}
+
+function createEmptyWrapperExtraction(found: boolean = false): WrapperExtraction {
+ return {
+ found,
+ props: [],
+ events: [],
+ slotDescriptions: {},
+ slotNameAliases: {},
+ slotRequired: {},
+ };
+}
+
+function findImmediateJsDocBefore(content: string, markerIndex: number): string | undefined {
+ const beforeMarker = content.slice(0, markerIndex);
+ const start = beforeMarker.lastIndexOf("/**");
+ if (start === -1) return undefined;
+
+ const end = beforeMarker.indexOf("*/", start + 3);
+ if (end === -1) return undefined;
+
+ const tail = beforeMarker.slice(end + 2);
+ if (!/^\s*$/.test(tail)) return undefined;
+
+ return beforeMarker.slice(start + 3, end);
+}
+
+function extractAngularBaseComponentProps(): Map {
+ const baseFile = path.join(
+ WORKSPACE_ROOT,
+ "libs/angular-components/src/lib/components/base.component.ts",
+ );
+
+ if (!fs.existsSync(baseFile)) return new Map();
+
+ const content = fs.readFileSync(baseFile, "utf-8");
+ const sourceFile = createTsSourceFile(baseFile, content);
+ const props = new Map();
+
+ const classDecls = sourceFile.statements.filter(
+ (node): node is ts.ClassDeclaration => ts.isClassDeclaration(node),
+ );
+
+ for (const classDecl of classDecls) {
+ for (const member of classDecl.members) {
+ if (!ts.isPropertyDeclaration(member)) continue;
+ if (!hasDecorator(member, "Input")) continue;
+ if (!member.name || !ts.isIdentifier(member.name)) continue;
+
+ const rawComment = findImmediateJsDocBefore(content, member.getStart(sourceFile));
+ const propName = member.name.text;
+ const inputDecorator = getDecoratorCall(member, "Input");
+ const rawDefault = member.initializer?.getText(sourceFile)?.trim();
+ const rawType = cleanType(member.type?.getText(sourceFile)?.trim() || inferTypeFromDefault(rawDefault));
+ const fullDescription = parseDescriptionFromJSDoc(rawComment);
+ const { description, defaultValue: descriptionDefault } = extractDefaultFromDescription(fullDescription);
+ const defaultValue = descriptionDefault ?? parseDefaultValue(rawDefault);
+
+ props.set(propName, {
+ name: propName,
+ type: rawType,
+ values: parseWrapperPropValues(rawType),
+ required: isAngularInputRequired(inputDecorator),
+ default: defaultValue,
+ description,
+ });
+ }
+ }
+
+ return props;
+}
+
+function findFirstFileByName(root: string, targetName: string): string | null {
+ if (!fs.existsSync(root)) return null;
+ const stack = [root];
+
+ while (stack.length > 0) {
+ const current = stack.pop();
+ if (!current) continue;
+ const entries = fs.readdirSync(current, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(current, entry.name);
+ if (entry.isDirectory()) {
+ stack.push(fullPath);
+ } else if (entry.isFile() && entry.name === targetName) {
+ return fullPath;
+ }
+ }
+ }
+
+ return null;
+}
+
+function escapeRegExp(value: string): string {
+ return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function findFirstFileContaining(
+ root: string,
+ extensions: string[],
+ searchText: string,
+): string | null {
+ if (!fs.existsSync(root)) return null;
+ const stack = [root];
+ const searchPattern = new RegExp(
+ `(?:<\\s*${escapeRegExp(searchText)}(?=[\\s>/])|["']${escapeRegExp(searchText)}["'])`,
+ );
+
+ while (stack.length > 0) {
+ const current = stack.pop();
+ if (!current) continue;
+ const entries = fs.readdirSync(current, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(current, entry.name);
+ if (entry.isDirectory()) {
+ stack.push(fullPath);
+ } else if (
+ entry.isFile() &&
+ extensions.some((ext) => entry.name.endsWith(ext)) &&
+ !entry.name.includes(".spec.")
+ ) {
+ const content = fs.readFileSync(fullPath, "utf-8");
+ if (searchPattern.test(content)) {
+ return fullPath;
+ }
+ }
+ }
+ }
+
+ return null;
+}
+
+function findFirstFileMatchingPattern(
+ root: string,
+ extensions: string[],
+ pattern: RegExp,
+): string | null {
+ if (!fs.existsSync(root)) return null;
+ const stack = [root];
+
+ while (stack.length > 0) {
+ const current = stack.pop();
+ if (!current) continue;
+ const entries = fs.readdirSync(current, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(current, entry.name);
+ if (entry.isDirectory()) {
+ stack.push(fullPath);
+ } else if (
+ entry.isFile() &&
+ extensions.some((ext) => entry.name.endsWith(ext)) &&
+ !entry.name.includes(".spec.")
+ ) {
+ const content = fs.readFileSync(fullPath, "utf-8");
+ if (pattern.test(content)) {
+ return fullPath;
+ }
+ }
+ }
+ }
+
+ return null;
+}
+
+function extractReactWrapperApi(
+ componentName: string,
+ tagName: string,
+ slotNames: string[],
+ wrapperComponentName: string = componentName,
+): WrapperExtraction {
+ const reactRoot = path.join(WORKSPACE_ROOT, "libs/react-components/src/lib");
+ const reactFileNameCandidates = [
+ `${wrapperComponentName}.tsx`,
+ `${wrapperComponentName.replace(/-/g, "")}.tsx`,
+ ];
+ const reactTagPattern = new RegExp(`<\\s*${escapeRegExp(tagName)}(?=[\\s>/])`);
+
+ const reactFile =
+ reactFileNameCandidates.map((name) => findFirstFileByName(reactRoot, name)).find(Boolean) ??
+ findFirstFileMatchingPattern(reactRoot, [".tsx"], reactTagPattern) ??
+ findFirstFileContaining(reactRoot, [".tsx"], tagName);
+
+ if (!reactFile) return createEmptyWrapperExtraction();
+
+ const content = fs.readFileSync(reactFile, "utf-8");
+ const sourceFile = createTsSourceFile(reactFile, content);
+ const interfaces = parseReactInterfaces(content, reactFile);
+ const primaryInterfaceName = resolvePrimaryReactPropsInterface(wrapperComponentName, interfaces);
+ if (!primaryInterfaceName) return createEmptyWrapperExtraction(true);
+
+ const interfaceMembers = collectReactInterfaceMembers(primaryInterfaceName, interfaces, sourceFile);
+ const componentParameterType = resolvePrimaryReactComponentParameterType(
+ wrapperComponentName,
+ sourceFile,
+ );
+ const componentParameterMembers = collectReactTypeNodeMembers(
+ componentParameterType,
+ interfaces,
+ sourceFile,
+ new Set([primaryInterfaceName]),
+ );
+ const reactMembers = [...interfaceMembers, ...componentParameterMembers];
+ const callbackAliases = extractReactCallbackAliases(sourceFile);
+
+ const props: ExtractedProp[] = [];
+ const events: ExtractedEvent[] = [];
+ const slotDescriptions: Record = {};
+ const slotNameAliases: Record = {};
+ const slotRequired: Record = {};
+
+ for (const member of reactMembers) {
+ if (!ts.isPropertySignature(member)) continue;
+ if (!member.name || !ts.isIdentifier(member.name)) continue;
+
+ const rawComment = findImmediateJsDocBefore(content, member.getStart(sourceFile));
+ const propName = member.name.text;
+ const optional = Boolean(member.questionToken);
+ const rawType = cleanType(member.type?.getText(sourceFile)?.trim() || "any");
+ const { internal, deprecated } = parseJSDocContent(rawComment || "");
+
+ // Skip @deprecated props and internal-only props — not for public API docs
+ if (deprecated || (internal && !shouldAllowInternalProp(componentName, propName))) continue;
+
+ const fullDescription = parseDescriptionFromJSDoc(rawComment);
+ const { description, defaultValue } = extractDefaultFromDescription(fullDescription);
+ const isReadonly = isReadonlyDescription(description);
+ const isRequired = !optional && !isReadonly;
+
+ if (shouldSkipInternalProp(componentName, propName)) continue;
+
+ const values = parseWrapperPropValues(rawType);
+ const slotName = getMatchingSlotName(propName, slotNames);
+
+ if (slotName && isSlotCarrierType(rawType)) {
+ if (description) {
+ slotDescriptions[slotName] = description;
+ }
+ slotNameAliases[slotName] = propName;
+ slotRequired[slotName] = Boolean(slotRequired[slotName]) || isRequired;
+ if (isPureSlotCarrierType(rawType)) {
+ continue;
+ }
+ }
+
+ if (
+ propName.startsWith("on") &&
+ (isReactCallbackAliasType(rawType, callbackAliases) || isFunctionType(rawType))
+ ) {
+ events.push({
+ name: propName,
+ type: isReactCallbackAliasType(rawType, callbackAliases)
+ ? resolveReactCallbackEventType(rawType, callbackAliases)
+ : rawType,
+ description,
+ frameworks: ["react"],
+ });
+ continue;
+ }
+
+ props.push({
+ name: propName,
+ type: rawType,
+ values,
+ required: isRequired,
+ default: defaultValue,
+ description,
+ });
+ }
+
+ // Inject inherited margin props when the interface extends Margins
+ if (hasReactMarginsInHierarchy(primaryInterfaceName, interfaces)) {
+ const existingNames = new Set(props.map((p) => p.name));
+ const marginProps: ExtractedProp[] = ["mt", "mr", "mb", "ml"]
+ .filter((name) => !existingNames.has(name))
+ .map((name) => ({
+ name,
+ type: "Spacing",
+ required: false,
+ default: null,
+ description: "",
+ }));
+ props.push(...marginProps);
+ }
+
+ const dedupedProps = dedupeByName(props).sort((a, b) => a.name.localeCompare(b.name));
+ const dedupedEvents = dedupeByName(events).sort((a, b) => a.name.localeCompare(b.name));
+
+ return {
+ found: true,
+ props: dedupedProps,
+ events: dedupedEvents,
+ slotDescriptions,
+ slotNameAliases,
+ slotRequired,
+ };
+}
+
+function extractAngularWrapperApi(
+ componentName: string,
+ tagName: string,
+ slotNames: string[],
+ wrapperComponentName: string = componentName,
+): WrapperExtraction {
+ const angularRoot = path.join(WORKSPACE_ROOT, "libs/angular-components/src/lib/components");
+ const angularSelector = tagName.replace(/^goa-/, "goab-");
+ const angularFileNameCandidates = [
+ `${wrapperComponentName}.ts`,
+ `${wrapperComponentName.replace(/-/g, "")}.ts`,
+ ];
+ const angularSelectorPattern = new RegExp(`selector\\s*:\\s*["']${escapeRegExp(angularSelector)}["']`);
+ const angularTagPattern = new RegExp(`<\\s*${escapeRegExp(tagName)}(?=[\\s>/])`);
+
+ const angularFile =
+ angularFileNameCandidates
+ .map((name) => findFirstFileByName(angularRoot, name))
+ .find(Boolean) ??
+ findFirstFileMatchingPattern(angularRoot, [".ts"], angularSelectorPattern) ??
+ findFirstFileMatchingPattern(angularRoot, [".ts"], angularTagPattern) ??
+ findFirstFileContaining(angularRoot, [".ts"], tagName);
+
+ if (!angularFile) return createEmptyWrapperExtraction();
+
+ const content = fs.readFileSync(angularFile, "utf-8");
+ const sourceFile = createTsSourceFile(angularFile, content);
+
+ const props: ExtractedProp[] = [];
+ const events: ExtractedEvent[] = [];
+ const slotDescriptions: Record = {};
+ const slotNameAliases: Record = {};
+ const slotRequired: Record = {};
+
+ const classDecl = sourceFile.statements.find(
+ (node): node is ts.ClassDeclaration => ts.isClassDeclaration(node) && hasDecorator(node, "Component"),
+ );
+
+ if (!classDecl) return createEmptyWrapperExtraction(true);
+
+ for (const member of classDecl.members) {
+ if (!ts.isPropertyDeclaration(member)) continue;
+ if (!member.name || !ts.isIdentifier(member.name)) continue;
+
+ const inputDecorator = getDecoratorCall(member, "Input");
+ if (!inputDecorator && !hasDecorator(member, "Input")) continue;
+
+ const rawComment = findImmediateJsDocBefore(content, member.getStart(sourceFile));
+ const { internal, deprecated } = parseJSDocContent(rawComment || "");
+ const propName = member.name.text;
+ const rawDefault = member.initializer?.getText(sourceFile)?.trim();
+ const rawType = cleanType(member.type?.getText(sourceFile)?.trim() || inferTypeFromDefault(rawDefault));
+
+ const fullDescription = parseDescriptionFromJSDoc(rawComment);
+ const { description, defaultValue: descriptionDefault } = extractDefaultFromDescription(fullDescription);
+ const isReadonly = isReadonlyDescription(description);
+ const required = !isReadonly && isAngularInputRequired(inputDecorator);
+
+ // Skip @deprecated props and internal-only props — not for public API docs
+ if (deprecated || (internal && !shouldAllowInternalProp(componentName, propName))) continue;
+
+ if (shouldSkipInternalProp(componentName, propName)) continue;
+
+ const values = parseWrapperPropValues(rawType);
+ const slotName = getMatchingSlotName(propName, slotNames);
+
+ if (slotName && isSlotCarrierType(rawType)) {
+ if (description) {
+ slotDescriptions[slotName] = description;
+ }
+ slotNameAliases[slotName] = propName;
+ slotRequired[slotName] = Boolean(slotRequired[slotName]) || required;
+ if (isPureSlotCarrierType(rawType)) {
+ continue;
+ }
+ }
+
+ const defaultValue = descriptionDefault ?? parseDefaultValue(rawDefault);
+
+ props.push({
+ name: propName,
+ type: rawType,
+ values,
+ required,
+ default: defaultValue,
+ description,
+ });
+ }
+
+ for (const member of classDecl.members) {
+ if (!ts.isPropertyDeclaration(member)) continue;
+ if (!member.name || !ts.isIdentifier(member.name)) continue;
+ const outputDecorator = getDecoratorCall(member, "Output");
+ if (!outputDecorator && !hasDecorator(member, "Output")) continue;
+
+ const rawComment = findImmediateJsDocBefore(content, member.getStart(sourceFile));
+ const { deprecated: eventDeprecated } = parseJSDocContent(rawComment || "");
+ if (eventDeprecated) continue;
+
+ const eventName = member.name.text;
+ let eventType = "void";
+
+ if (member.type && ts.isTypeReferenceNode(member.type)) {
+ const typeName = member.type.typeName.getText(sourceFile);
+ if (typeName.endsWith("EventEmitter")) {
+ eventType = member.type.typeArguments?.[0]?.getText(sourceFile)?.trim() || "void";
+ }
+ }
+
+ if (
+ (eventType === "void" || eventType === "CustomEvent") &&
+ member.initializer &&
+ ts.isNewExpression(member.initializer)
+ ) {
+ const expr = member.initializer;
+ const ctorName = expr.expression.getText(sourceFile);
+ if (ctorName.endsWith("EventEmitter")) {
+ eventType = expr.typeArguments?.[0]?.getText(sourceFile)?.trim() || "void";
+ }
+ }
+
+ const description = parseDescriptionFromJSDoc(rawComment);
+
+ events.push({
+ name: eventName,
+ type: toEventCallbackType(eventType),
+ description,
+ frameworks: ["angular"],
+ });
+ }
+
+ // Inject inherited props when the class extends common Angular base wrappers.
+ const extendsName = classDecl.heritageClauses
+ ?.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword)
+ ?.types?.[0]
+ ?.expression
+ ?.getText(sourceFile);
+
+ if (extendsName && (extendsName === "GoabBaseComponent" || extendsName === "GoabControlValueAccessor")) {
+ const existingNames = new Set(props.map((p) => p.name));
+ const baseComponentProps = extractAngularBaseComponentProps();
+ const inheritedPropNames =
+ extendsName === "GoabControlValueAccessor"
+ ? ["id", "disabled", "error", "value", "mt", "mr", "mb", "ml", "testId"]
+ : ["mt", "mr", "mb", "ml", "testId"];
+
+ const baseProps = inheritedPropNames
+ .map((name) => baseComponentProps.get(name))
+ .filter((prop): prop is ExtractedProp => Boolean(prop))
+ .filter((prop) => !existingNames.has(prop.name));
+
+ props.push(...baseProps);
+ }
+
+ const dedupedProps = dedupeByName(props).sort((a, b) => a.name.localeCompare(b.name));
+ const dedupedEvents = dedupeByName(events).sort((a, b) => a.name.localeCompare(b.name));
+
+ return {
+ found: true,
+ props: dedupedProps,
+ events: dedupedEvents,
+ slotDescriptions,
+ slotNameAliases,
+ slotRequired,
+ };
}
// =============================================================================
@@ -502,37 +1551,284 @@ function generateTypeLabel(
// Event Transformation
// =============================================================================
-function transformEvents(rawEventNames: string[]): ExtractedEvent[] {
- const events: ExtractedEvent[] = [];
+function inferDetailPropertyType(key: string, expression: string): string {
+ const expr = expression.trim();
+ const lowerKey = key.toLowerCase();
+
+ if (lowerKey === "name") return "string";
+ if (lowerKey === "label") return "string";
+ if (lowerKey === "labels") return "string[]";
+ if (lowerKey === "sortby") return "string";
+ if (lowerKey === "sortdir") return "number";
+ if (lowerKey === "sorts") return '{ column: string; direction: "asc" | "desc" }[]';
+ if (lowerKey === "tab") return "number";
+ if (lowerKey === "page") return "number";
+ if (lowerKey === "url") return "string";
+ if (lowerKey === "values") return "string[]";
+
+ if (lowerKey === "value") {
+ if (/newselectedvalues|array\.from\s*\(/i.test(expr)) return "string[]";
+ if (/_date\.date/.test(expr)) return "Date | string | null";
+ if (/\binput\.value\b/.test(expr)) return "string";
+ if (/\.value\b/.test(expr) && !/\bdetail\.value\b/.test(expr)) return "string";
+ if (/\boutput\b/.test(expr)) return "string";
+ if (/^newvalue$/i.test(expr)) return "string";
+ if (/^_?value$/.test(expr)) return "string";
+ if (/detail\.value/.test(expr)) return "string | unknown[]";
+ }
- for (const rawName of rawEventNames) {
- // Skip internal events
- if (rawName.includes("::") || rawName.includes(":")) continue;
+ if (lowerKey === "valuestr") return "string";
+ if (lowerKey === "key") {
+ if (/\.key\b/.test(expr)) return "string";
+ }
+ if (lowerKey === "action") {
+ if (/\.action\b/.test(expr)) return "string";
+ }
+ if (lowerKey === "size") {
+ if (/\.size\b/.test(expr)) return '"normal" | "compact"';
+ }
- // Raw event name (e.g., "_click") -> base name (e.g., "click")
- const baseName = rawName.replace(/^_/, "");
+ if (expr === "true" || expr === "false") return "boolean";
+ if (/^[-+]?\d+(\.\d+)?$/.test(expr)) return "number";
+ if (/^["'`].*["'`]$/.test(expr)) return "string";
+ if (/^\{[\s\S]*\}$/.test(expr)) return "Record";
+ if (/^\[[\s\S]*\]$/.test(expr)) return "unknown[]";
+ if (/\b(open|checked|disabled|selected|expanded|collapsed|visible|active)\b/i.test(expr)) {
+ return "boolean";
+ }
+ if (/(open|checked|disabled|selected|expanded|collapsed|visible|active)/.test(lowerKey)) {
+ return "boolean";
+ }
+ if (/\b(event|e)\b/.test(expr)) return "Event";
- // React event name: onClick, onChange, etc.
- const reactName = `on${capitalize(baseName)}`;
+ return "unknown";
+}
- // Add React event
- events.push({
- name: reactName,
- type: "(event: Event) => void",
- description: "",
- frameworks: ["react"],
- });
+function inferDetailPropertyOptional(key: string, expression: string): boolean {
+ const expr = expression.trim();
+ const lowerKey = key.toLowerCase();
- // Add Angular event (uses the raw name with underscore)
- events.push({
- name: rawName,
- type: "CustomEvent",
- description: "",
- frameworks: ["angular"],
- });
+ if (
+ (lowerKey === "action" || lowerKey === "size") &&
+ /\baction\.(action|size)\b/.test(expr)
+ ) {
+ return true;
}
- return events;
+ return false;
+}
+
+function buildCustomEventTypeFromDetail(detailObjectLiteral: string): string {
+ const objectBody = detailObjectLiteral.replace(/^\{\s*|\s*\}$/g, "");
+ if (!objectBody) return "CustomEvent";
+
+ const parsedMembers = objectBody
+ .split(",")
+ .map((part) => part.trim())
+ .filter(Boolean)
+ .map((part) => {
+ const keyValueMatch = part.match(/^([A-Za-z_$][\w$]*)\s*:\s*([\s\S]+)$/);
+ if (keyValueMatch) {
+ const key = keyValueMatch[1];
+ const value = keyValueMatch[2].trim();
+ return {
+ key,
+ type: inferDetailPropertyType(key, value),
+ optional: inferDetailPropertyOptional(key, value),
+ };
+ }
+
+ const shorthandMatch = part.match(/^([A-Za-z_$][\w$]*)$/);
+ if (shorthandMatch) {
+ const key = shorthandMatch[1];
+ return { key, type: inferDetailPropertyType(key, key), optional: false };
+ }
+
+ return null;
+ })
+ .filter((member): member is { key: string; type: string; optional: boolean } =>
+ Boolean(member),
+ );
+
+ if (!parsedMembers.length) return "CustomEvent>";
+
+ // Cross-field heuristics for common patterns in component events.
+ const hasLabels = parsedMembers.some((m) => m.key.toLowerCase() === "labels");
+ const hasValueStr = parsedMembers.some((m) => m.key.toLowerCase() === "valuestr");
+
+ const members = parsedMembers.map((member) => {
+ if (member.key.toLowerCase() === "value") {
+ if (hasLabels) {
+ return `${member.key}${member.optional ? "?" : ""}: string[]`;
+ }
+ if (hasValueStr) {
+ return `${member.key}${member.optional ? "?" : ""}: Date | string | null`;
+ }
+ }
+ return `${member.key}${member.optional ? "?" : ""}: ${member.type}`;
+ });
+
+ return `CustomEvent<{ ${members.join("; ")} }>`;
+}
+
+function scoreCustomEventType(eventType: string): number {
+ if (eventType === "CustomEvent" || eventType === "CustomEvent>" || eventType === "CustomEvent") {
+ return 0;
+ }
+
+ const detailMatch = eventType.match(/CustomEvent<\{([\s\S]*)\}>/);
+ if (!detailMatch?.[1]) return 0;
+
+ const body = detailMatch[1];
+ const keyCount = body.split(";").filter((part) => part.trim().length > 0).length;
+ const unknownCount = (body.match(/\bunknown\b/g) || []).length;
+
+ return keyCount * 10 - unknownCount * 6;
+}
+
+function splitTopLevelArgs(argsSource: string): string[] {
+ const parts: string[] = [];
+ let current = "";
+ let parenDepth = 0;
+ let braceDepth = 0;
+ let bracketDepth = 0;
+ let inString = false;
+ let stringQuote = "";
+
+ for (let i = 0; i < argsSource.length; i++) {
+ const ch = argsSource[i];
+ const prev = i > 0 ? argsSource[i - 1] : "";
+
+ if (inString) {
+ current += ch;
+ if (ch === stringQuote && prev !== "\\") {
+ inString = false;
+ stringQuote = "";
+ }
+ continue;
+ }
+
+ if (ch === '"' || ch === "'" || ch === "`") {
+ inString = true;
+ stringQuote = ch;
+ current += ch;
+ continue;
+ }
+
+ if (ch === "(") parenDepth++;
+ else if (ch === ")") parenDepth--;
+ else if (ch === "{") braceDepth++;
+ else if (ch === "}") braceDepth--;
+ else if (ch === "[") bracketDepth++;
+ else if (ch === "]") bracketDepth--;
+
+ if (ch === "," && parenDepth === 0 && braceDepth === 0 && bracketDepth === 0) {
+ parts.push(current.trim());
+ current = "";
+ continue;
+ }
+
+ current += ch;
+ }
+
+ if (current.trim().length > 0) {
+ parts.push(current.trim());
+ }
+
+ return parts;
+}
+
+function getCustomEventType(eventName: string, content: string): string {
+ const escapedName = escapeRegExp(eventName);
+ const eventPattern = new RegExp(
+ `new\\s+CustomEvent\\s*\\(\\s*["']${escapedName}["']\\s*,\\s*\\{([\\s\\S]*?)\\}\\s*\\)`,
+ "g",
+ );
+
+ const dispatchCallStartPattern = /dispatch(?:<[^>]+>)?\s*\(/g;
+
+ const detailLiterals: string[] = [];
+
+ for (const match of content.matchAll(eventPattern)) {
+ const eventOptions = match[1];
+ const detailMatch = eventOptions.match(/detail\s*:\s*(\{[\s\S]*?\})/);
+ if (detailMatch?.[1]) {
+ detailLiterals.push(detailMatch[1]);
+ }
+ }
+
+ for (const match of content.matchAll(dispatchCallStartPattern)) {
+ const startIndex = match.index ?? -1;
+ if (startIndex < 0) continue;
+
+ const openParenIndex = startIndex + match[0].length - 1;
+ let depth = 0;
+ let endIndex = -1;
+
+ for (let i = openParenIndex; i < content.length; i++) {
+ const ch = content[i];
+ if (ch === "(") depth++;
+ if (ch === ")") {
+ depth--;
+ if (depth === 0) {
+ endIndex = i;
+ break;
+ }
+ }
+ }
+
+ if (endIndex === -1) continue;
+
+ const callArgsSource = content.slice(openParenIndex + 1, endIndex);
+ const args = splitTopLevelArgs(callArgsSource);
+ if (args.length < 3) continue;
+
+ const eventArg = args[1].trim();
+ const eventMatch = eventArg.match(/^["']([^"']+)["']$/);
+ if (!eventMatch || eventMatch[1] !== eventName) continue;
+
+ const detailLiteral = args[2].trim();
+ if (detailLiteral.startsWith("{") && detailLiteral.endsWith("}")) {
+ detailLiterals.push(detailLiteral);
+ }
+ }
+
+ let bestEventType = "CustomEvent>";
+ let bestScore = -1;
+
+ for (const literal of detailLiterals) {
+ const typed = buildCustomEventTypeFromDetail(literal);
+ const score = scoreCustomEventType(typed);
+ if (score > bestScore) {
+ bestScore = score;
+ bestEventType = typed;
+ }
+ }
+
+ if (detailLiterals.length > 0) {
+ return bestEventType;
+ }
+
+ return "CustomEvent";
+}
+
+function transformWebComponentEvents(
+ componentName: string,
+ rawEventNames: string[],
+ content: string,
+): ExtractedEvent[] {
+ const internalOverrides = WEB_COMPONENT_INTERNAL_EVENT_OVERRIDES[componentName] || new Set();
+ const typeOverrides = WEB_COMPONENT_EVENT_TYPE_OVERRIDES[componentName] || {};
+
+ return rawEventNames
+ .filter((rawName) => !INTERNAL_EVENT_NAMES.has(rawName) && !internalOverrides.has(rawName))
+ .filter((rawName) => !rawName.includes("::") && !rawName.includes(":"))
+ .map((rawName) => ({
+ name: rawName,
+ type: typeOverrides[rawName] || getCustomEventType(rawName, content),
+ description: "",
+ frameworks: ["webComponents"],
+ }));
}
// =============================================================================
@@ -611,30 +1907,88 @@ function parseDefaultValue(str: string | undefined): string | null {
return str;
}
+function getAllComponentNames(): string[] {
+ const componentNames = new Set();
+ const documentedComponentSlugs = new Set(
+ fs
+ .readdirSync(DOCS_COMPONENT_CONTENT_PATH, { withFileTypes: true })
+ .filter((entry) => entry.isFile() && entry.name.endsWith(".mdx"))
+ .map((entry) => entry.name.replace(/\.mdx$/, "")),
+ );
+ const stack = [UI_COMPONENTS_PATH];
+
+ while (stack.length > 0) {
+ const current = stack.pop();
+ if (!current) continue;
+
+ const entries = fs.readdirSync(current, { withFileTypes: true });
+ for (const entry of entries) {
+ const fullPath = path.join(current, entry.name);
+
+ if (entry.isDirectory()) {
+ stack.push(fullPath);
+ } else if (
+ entry.isFile() &&
+ entry.name.endsWith(".svelte") &&
+ !entry.name.includes(".test.")
+ ) {
+ const content = fs.readFileSync(fullPath, "utf-8");
+ const slug = toKebabCase(path.basename(entry.name, ".svelte"));
+ if (
+ extractTagName(content) &&
+ documentedComponentSlugs.has(slug) &&
+ !DOCS_EXCLUDED_COMPONENTS.has(slug)
+ ) {
+ componentNames.add(slug);
+ }
+ }
+ }
+ }
+
+ for (const forcedComponent of DOCS_FORCED_COMPONENTS) {
+ componentNames.add(forcedComponent);
+ }
+
+ return Array.from(componentNames).sort((a, b) => a.localeCompare(b));
+}
+
+function removeStaleApiFiles(validComponentNames: string[]): void {
+ if (!fs.existsSync(OUTPUT_PATH)) return;
+
+ const validFiles = new Set(validComponentNames.map((name) => `${name}.json`));
+ const entries = fs.readdirSync(OUTPUT_PATH, { withFileTypes: true });
+
+ for (const entry of entries) {
+ if (entry.isFile() && entry.name.endsWith(".json") && !validFiles.has(entry.name)) {
+ fs.unlinkSync(path.join(OUTPUT_PATH, entry.name));
+ console.log(` Removed stale file: ${entry.name}`);
+ }
+ }
+}
+
// =============================================================================
// Main Extraction
// =============================================================================
function extractComponentAPI(componentName: string): ExtractedComponentAPI | null {
const componentPath = path.join(UI_COMPONENTS_PATH, componentName);
- if (!fs.existsSync(componentPath) || !fs.statSync(componentPath).isDirectory()) {
- console.error(`Component directory not found: ${componentName}`);
- return null;
- }
- // Find the main Svelte file
+ // Find the Svelte file by the component's public name first, then fall back
+ // to any .svelte file inside a matching directory.
const svelteFileName = `${capitalize(toCamelCase(componentName))}.svelte`;
- let svelteFilePath = path.join(componentPath, svelteFileName);
+ let svelteFilePath = findFirstFileByName(UI_COMPONENTS_PATH, svelteFileName);
- if (!fs.existsSync(svelteFilePath)) {
- // Try to find any .svelte file
+ if (!svelteFilePath && fs.existsSync(componentPath) && fs.statSync(componentPath).isDirectory()) {
const files = fs.readdirSync(componentPath);
const svelteFile = files.find((f) => f.endsWith(".svelte"));
- if (!svelteFile) {
- console.error(`No Svelte file found in: ${componentName}`);
- return null;
+ if (svelteFile) {
+ svelteFilePath = path.join(componentPath, svelteFile);
}
- svelteFilePath = path.join(componentPath, svelteFile);
+ }
+
+ if (!svelteFilePath) {
+ console.error(`No Svelte file found for: ${componentName}`);
+ return null;
}
const content = fs.readFileSync(svelteFilePath, "utf-8");
@@ -650,11 +2004,49 @@ function extractComponentAPI(componentName: string): ExtractedComponentAPI | nul
const typeAliases = extractTypeAliases(content);
const validators = extractValidators(content);
const rawProps = extractProps(content, validators, componentName, typeAliases);
- const rawEventNames = extractEvents(content);
+ let eventContent = content;
+ let rawEventNames = extractEvents(content);
+ const explicitEventsByComponent: Record> = {
+ "file-upload-card": new Set(["_cancel", "_delete"]),
+ };
+ const explicitEvents = explicitEventsByComponent[componentName];
+ if (explicitEvents) {
+ rawEventNames = Array.from(new Set([...rawEventNames, ...explicitEvents]));
+ }
+ const companionEventsByComponent: Record> = {
+ "work-side-menu": new Set(["_navigate"]),
+ "push-drawer": new Set(["_close"]),
+ };
+ const companionEvents = companionEventsByComponent[componentName];
+
+ if (companionEvents) {
+ const componentDir = path.dirname(svelteFilePath);
+ const siblingFiles = fs
+ .readdirSync(componentDir)
+ .filter((name) => name.endsWith(".svelte") && path.join(componentDir, name) !== svelteFilePath);
+
+ for (const siblingFile of siblingFiles) {
+ const siblingPath = path.join(componentDir, siblingFile);
+ const siblingContent = fs.readFileSync(siblingPath, "utf-8");
+ const siblingEventNames = extractEvents(siblingContent).filter((eventName) => companionEvents.has(eventName));
+ if (siblingEventNames.length > 0) {
+ rawEventNames = [...rawEventNames, ...siblingEventNames];
+ eventContent += `\n${siblingContent}`;
+ }
+ }
+
+ rawEventNames = Array.from(new Set(rawEventNames));
+ }
const slotNames = extractSlots(content);
+ const wrapperComponentName = WRAPPER_COMPONENT_ALIASES[componentName] ?? componentName;
+ const reactWrapper = extractReactWrapperApi(componentName, tagName, slotNames, wrapperComponentName);
+ const angularWrapper = extractAngularWrapperApi(componentName, tagName, slotNames, wrapperComponentName);
+
+ // Default slot content is implied by usage examples and is intentionally omitted
+ // from the API docs to reduce noise.
// Transform to output format
- const props: ExtractedProp[] = rawProps.map((p) => ({
+ let webComponentProps: ExtractedProp[] = rawProps.map((p) => ({
name: p.name,
type: p.type,
typeLabel: p.typeLabel,
@@ -665,12 +2057,90 @@ function extractComponentAPI(componentName: string): ExtractedComponentAPI | nul
...(p.deprecated && { deprecated: true }),
}));
- const events = transformEvents(rawEventNames);
+ let webComponentEvents = transformWebComponentEvents(componentName, rawEventNames, eventContent);
+ if (componentName === "side-menu-group") {
+ webComponentEvents = webComponentEvents.filter((event) => event.name !== "_open");
+ }
+ const slotDescriptions = {
+ ...angularWrapper.slotDescriptions,
+ ...reactWrapper.slotDescriptions,
+ };
+ const slotNameAliases = {
+ ...angularWrapper.slotNameAliases,
+ ...reactWrapper.slotNameAliases,
+ };
+ const slotRequired = {
+ ...angularWrapper.slotRequired,
+ ...reactWrapper.slotRequired,
+ };
- const slots: ExtractedSlot[] = slotNames.map((name) => ({
- name,
- description: "", // Filled by human content
- }));
+ const hasWrapperSlotEvidence = (name: string): boolean =>
+ Boolean(slotNameAliases[name] || slotDescriptions[name]) ||
+ Object.prototype.hasOwnProperty.call(slotRequired, name);
+
+ const createSlots = (
+ framework: "react" | "angular" | "webComponents",
+ type?: string,
+ useAliasNames: boolean = true,
+ ): ExtractedSlot[] =>
+ slotNames
+ .filter(
+ (name) =>
+ !INTERNAL_SLOT_NAMES.has(name.toLowerCase()) &&
+ !(name === "content" && !slotNameAliases[name] && !slotDescriptions[name]),
+ )
+ .map((name) => {
+ const rawDescription = slotDescriptions[name] || "";
+ const description =
+ framework === "angular"
+ ? rawDescription.replace(/ReactNode/g, "ngTemplate")
+ : rawDescription;
+ return {
+ name: useAliasNames ? slotNameAliases[name] || name : name,
+ type:
+ SLOT_TYPE_OVERRIDES[componentName]?.[framework]?.[name] ||
+ (type && hasWrapperSlotEvidence(name) ? type : undefined),
+ description,
+ required: slotRequired[name] || false,
+ };
+ });
+
+ const reactSlots = createSlots("react", "ReactNode", true);
+ const angularSlots = createSlots("angular", "TemplateRef", true);
+ const webComponentSlots = createSlots("webComponents", undefined, false);
+
+ let reactProps: ExtractedProp[] = reactWrapper.found ? [...reactWrapper.props] : [];
+ let angularProps: ExtractedProp[] = angularWrapper.found ? [...angularWrapper.props] : [];
+
+ specializeAngularValuePropFromReact(angularProps, reactProps);
+
+ const webComponentVersionProp = webComponentProps.find(
+ (prop) => prop.name.toLowerCase() === "version",
+ );
+ const hideVersionOutsideWeb = isStandardV1V2VersionProp(webComponentVersionProp);
+
+ reactProps = reactProps.filter(
+ (prop) =>
+ !shouldSkipInternalProp(componentName, prop.name) &&
+ !(hideVersionOutsideWeb && prop.name.toLowerCase() === "version"),
+ );
+ angularProps = angularProps.filter(
+ (prop) =>
+ !shouldSkipInternalProp(componentName, prop.name) &&
+ !(hideVersionOutsideWeb && prop.name.toLowerCase() === "version"),
+ );
+ webComponentProps = webComponentProps.filter(
+ (prop) => prop.name.toLowerCase() === "version" || !shouldSkipInternalProp(componentName, prop.name),
+ );
+
+ reactProps = dedupeByName(reactProps).sort((a, b) => a.name.localeCompare(b.name));
+ angularProps = dedupeByName(angularProps).sort((a, b) => a.name.localeCompare(b.name));
+
+ webComponentProps.sort((a, b) => a.name.localeCompare(b.name));
+ webComponentEvents.sort((a, b) => a.name.localeCompare(b.name));
+ reactSlots.sort((a, b) => a.name.localeCompare(b.name));
+ angularSlots.sort((a, b) => a.name.localeCompare(b.name));
+ webComponentSlots.sort((a, b) => a.name.localeCompare(b.name));
// Relative path from workspace root
const relativePath = path.relative(WORKSPACE_ROOT, svelteFilePath);
@@ -678,9 +2148,83 @@ function extractComponentAPI(componentName: string): ExtractedComponentAPI | nul
return {
componentSlug: toKebabCase(componentName),
extractedFrom: relativePath,
- props,
- events,
- slots,
+ frameworks: {
+ react: {
+ props: reactWrapper.found ? reactProps : [],
+ events: reactWrapper.found ? reactWrapper.events : [],
+ slots: reactWrapper.found ? reactSlots : [],
+ },
+ angular: {
+ props: angularWrapper.found ? angularProps : [],
+ events: angularWrapper.found ? angularWrapper.events : [],
+ slots: angularWrapper.found ? angularSlots : [],
+ },
+ webComponents: {
+ props: webComponentProps,
+ events: webComponentEvents,
+ slots: webComponentSlots,
+ },
+ },
+ };
+}
+
+function mergeItemArray(
+ next: T[],
+ existing: T[],
+ context: string,
+): T[] {
+ const existingByName = new Map(existing.map((item) => [item.name, item]));
+ const nextNames = new Set(next.map((item) => item.name));
+
+ // Backfill non-empty descriptions from existing into new items that have empty ones
+ const merged: T[] = next.map((item) => {
+ const existingItem = existingByName.get(item.name);
+ if (existingItem && !item.description && existingItem.description) {
+ return { ...item, description: existingItem.description };
+ }
+ return item;
+ });
+
+ // Preserve items from existing that are absent in the new extraction
+ // (but skip deprecated entries — they are intentionally excluded)
+ for (const existingItem of existing) {
+ if (!nextNames.has(existingItem.name)) {
+ if ((existingItem as Record).deprecated) continue;
+ console.warn(
+ ` Preserved manually-added entry "${existingItem.name}" in ${context} (not found in extraction — check source)`,
+ );
+ merged.push(existingItem);
+ }
+ }
+
+ return merged.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function mergeWithExisting(
+ next: ExtractedComponentAPI,
+ existing: ExtractedComponentAPI,
+): ExtractedComponentAPI {
+ const fw = next.frameworks;
+ const ex = existing.frameworks;
+ return {
+ ...next,
+ frameworks: {
+ react: {
+ props: mergeItemArray(fw.react.props, ex.react.props, `${next.componentSlug}.json [react props]`),
+ events: mergeItemArray(fw.react.events, ex.react.events, `${next.componentSlug}.json [react events]`),
+ slots: mergeItemArray(fw.react.slots, ex.react.slots, `${next.componentSlug}.json [react slots]`),
+ },
+ angular: {
+ props: mergeItemArray(fw.angular.props, ex.angular.props, `${next.componentSlug}.json [angular props]`),
+ events: mergeItemArray(fw.angular.events, ex.angular.events, `${next.componentSlug}.json [angular events]`),
+ slots: mergeItemArray(fw.angular.slots, ex.angular.slots, `${next.componentSlug}.json [angular slots]`),
+ },
+ webComponents: {
+ props: mergeItemArray(fw.webComponents.props, ex.webComponents.props, `${next.componentSlug}.json [webComponents props]`),
+ events: mergeItemArray(fw.webComponents.events, ex.webComponents.events, `${next.componentSlug}.json [webComponents events]`),
+ slots: mergeItemArray(fw.webComponents.slots, ex.webComponents.slots, `${next.componentSlug}.json [webComponents slots]`),
+ },
+ },
};
}
@@ -691,7 +2235,20 @@ function saveComponentAPI(api: ExtractedComponentAPI): void {
}
const filePath = path.join(OUTPUT_PATH, `${api.componentSlug}.json`);
- fs.writeFileSync(filePath, JSON.stringify(api, null, 2));
+
+ // Merge with existing file to preserve manually-added entries that the extractor
+ // cannot see (e.g. props defined in function-level intersections, or wrapper gaps).
+ let merged = api;
+ if (fs.existsSync(filePath)) {
+ try {
+ const existing = JSON.parse(fs.readFileSync(filePath, "utf-8")) as ExtractedComponentAPI;
+ merged = mergeWithExisting(api, existing);
+ } catch {
+ // Malformed existing file — overwrite with fresh extraction
+ }
+ }
+
+ fs.writeFileSync(filePath, JSON.stringify(merged, null, 2));
console.log(` Created: ${filePath}`);
}
@@ -715,11 +2272,8 @@ function main() {
let componentNames: string[];
if (args.includes("--all")) {
- // Get all component directories
- componentNames = fs.readdirSync(UI_COMPONENTS_PATH).filter((name) => {
- const componentPath = path.join(UI_COMPONENTS_PATH, name);
- return fs.statSync(componentPath).isDirectory();
- });
+ componentNames = getAllComponentNames();
+ removeStaleApiFiles(componentNames);
} else {
componentNames = args;
}
diff --git a/libs/angular-components/src/index.ts b/libs/angular-components/src/index.ts
index 55aebfe4b6..10e50c69ad 100644
--- a/libs/angular-components/src/index.ts
+++ b/libs/angular-components/src/index.ts
@@ -1,3 +1,4 @@
export * from "./lib/angular-components.module";
export * from "./lib/components";
+export * from "./lib/theme/theme.service";
export * from "@abgov/ui-components-common";
diff --git a/libs/angular-components/src/lib/components/accordion/accordion.spec.ts b/libs/angular-components/src/lib/components/accordion/accordion.spec.ts
index d91a1205e1..0425266ea4 100644
--- a/libs/angular-components/src/lib/components/accordion/accordion.spec.ts
+++ b/libs/angular-components/src/lib/components/accordion/accordion.spec.ts
@@ -5,6 +5,7 @@ import { By } from "@angular/platform-browser";
import {
GoabAccordionHeadingSize,
GoabAccordionIconPosition,
+ GoabAccordionHeadingType,
} from "@abgov/ui-components-common";
@Component({
@@ -17,6 +18,7 @@ import {
[headingSize]="headingSize"
[headingContent]="headingContent"
[iconPosition]="iconPosition"
+ [headingType]="headingType"
maxWidth="480px"
>
test content
@@ -29,8 +31,21 @@ class TestAccordionComponent {
open?: boolean;
headingSize?: GoabAccordionHeadingSize;
iconPosition?: GoabAccordionIconPosition;
+ headingType?: GoabAccordionHeadingType;
}
+@Component({
+ standalone: true,
+ imports: [GoabAccordion],
+ template: `
+
+ test content
+ This is the actions content
+
+ `,
+})
+class TestAccordionWithActionsComponent {}
+
describe("GoabAccordion", () => {
let fixture: ComponentFixture;
let component: TestAccordionComponent;
@@ -48,6 +63,7 @@ describe("GoabAccordion", () => {
component.open = true;
component.headingSize = "large" as GoabAccordionHeadingSize;
component.iconPosition = "right" as GoabAccordionIconPosition;
+ component.headingType = "filled" as GoabAccordionHeadingType;
fixture.detectChanges();
tick();
@@ -64,7 +80,33 @@ describe("GoabAccordion", () => {
expect(accordionElement.getAttribute("headingsize")).toBe("large");
expect(accordionElement.getAttribute("maxwidth")).toBe("480px");
expect(accordionElement.getAttribute("iconposition")).toBe("right");
+ expect(accordionElement.getAttribute("heading-type")).toBe("filled");
const headingContent = accordionElement.querySelector("[slot='headingcontent']");
expect(headingContent.textContent).toContain("This is the headingcontent");
});
});
+
+describe("GoabAccordion actions slot", () => {
+ let fixture: ComponentFixture;
+
+ beforeEach(fakeAsync(() => {
+ TestBed.configureTestingModule({
+ imports: [GoabAccordion, TestAccordionWithActionsComponent],
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ }).compileComponents();
+
+ fixture = TestBed.createComponent(TestAccordionWithActionsComponent);
+ fixture.detectChanges();
+ tick();
+ fixture.detectChanges();
+ }));
+
+ it("should render the actions slot content", () => {
+ const accordionElement = fixture.debugElement.query(
+ By.css("goa-accordion"),
+ ).nativeElement;
+ const actionsSlot = accordionElement.querySelector("[slot='actions']");
+ expect(actionsSlot).toBeTruthy();
+ expect(actionsSlot.textContent).toContain("This is the actions content");
+ });
+});
diff --git a/libs/angular-components/src/lib/components/accordion/accordion.ts b/libs/angular-components/src/lib/components/accordion/accordion.ts
index d8d80f3202..1d93b78da5 100644
--- a/libs/angular-components/src/lib/components/accordion/accordion.ts
+++ b/libs/angular-components/src/lib/components/accordion/accordion.ts
@@ -1,6 +1,7 @@
import {
GoabAccordionHeadingSize,
GoabAccordionIconPosition,
+ GoabAccordionHeadingType,
} from "@abgov/ui-components-common";
import {
CUSTOM_ELEMENTS_SCHEMA,
@@ -28,9 +29,11 @@ import { GoabBaseComponent } from "../base.component";
[attr.secondarytext]="secondaryText"
[attr.open]="open"
[attr.headingsize]="headingSize"
+ [attr.heading-type]="headingType"
[attr.maxwidth]="maxWidth"
[attr.testid]="testId"
[attr.iconposition]="iconPosition"
+ [attr.heading-type]="headingType"
[attr.mt]="mt"
[attr.mb]="mb"
[attr.ml]="ml"
@@ -40,6 +43,11 @@ import { GoabBaseComponent } from "../base.component";
;
+ /** Sets the actions content template reference, rendered right-aligned in the heading before the expand/collapse icon. */
+ @Input() actions?: TemplateRef;
/** Sets the maximum width of the accordion. */
@Input() maxWidth?: string;
/** Sets the position of the expand/collapse icon. */
@Input() iconPosition?: GoabAccordionIconPosition;
+ /** Sets the accordion style variant. */
+ @Input() headingType?: GoabAccordionHeadingType;
/** Emits when the accordion opens or closes. Emits the new open state as a boolean. */
@Output() onChange = new EventEmitter();
diff --git a/libs/angular-components/src/lib/components/chip/chip.ts b/libs/angular-components/src/lib/components/chip/chip.ts
index 615c0411a8..99f4d97070 100644
--- a/libs/angular-components/src/lib/components/chip/chip.ts
+++ b/libs/angular-components/src/lib/components/chip/chip.ts
@@ -56,17 +56,17 @@ export class GoabChip extends GoabBaseComponent implements OnInit {
}, 0);
}
- /** @deprecated Use GoAFilterChip instead. Icon displayed at the start of the chip. */
+ /** @deprecated Use GoabFilterChip (goab-filter-chip) instead. Icon displayed at the start of the chip. */
@Input() leadingIcon?: GoabIconType | null;
- /** @deprecated Use GoAFilterChip instead. Shows an error state on the chip. */
+ /** @deprecated Use GoabFilterChip (goab-filter-chip) instead. Shows an error state on the chip. */
@Input({ transform: booleanAttribute }) error?: boolean;
- /** @deprecated Use GoAFilterChip instead. When true, shows a delete icon and makes chip clickable. */
+ /** @deprecated Use GoabFilterChip (goab-filter-chip) instead. When true, shows a delete icon and makes chip clickable. */
@Input({ transform: booleanAttribute }) deletable?: boolean;
- /** @deprecated Use GoAFilterChip instead. The text content displayed in the chip. */
+ /** @deprecated Use GoabFilterChip (goab-filter-chip) instead. The text content displayed in the chip. */
@Input() content?: string = "";
- /** @deprecated Use GoAFilterChip instead. The chip variant style. */
+ /** @deprecated Use GoabFilterChip (goab-filter-chip) instead. The chip variant style. */
@Input() variant?: GoabChipVariant;
- /** @deprecated Use GoAFilterChip instead. The icon theme - outline or filled. */
+ /** @deprecated Use GoabFilterChip (goab-filter-chip) instead. The icon theme - outline or filled. */
@Input() iconTheme?: GoabChipTheme;
/** Emits when the chip is clicked. */
diff --git a/libs/angular-components/src/lib/components/drawer/drawer.ts b/libs/angular-components/src/lib/components/drawer/drawer.ts
index 29ff92aff0..c6f5ae6541 100644
--- a/libs/angular-components/src/lib/components/drawer/drawer.ts
+++ b/libs/angular-components/src/lib/components/drawer/drawer.ts
@@ -25,7 +25,7 @@ import { GoabDrawerPosition, GoabDrawerSize } from "@abgov/ui-components-common"
[attr.maxsize]="maxSize"
[attr.testid]="testId"
[attr.version]="version"
- (_close)="_onClose()"
+ (_close)="_onClose($event)"
>
;
+ /** Content rendered in the actions slot. */
+ @Input() actions?: TemplateRef;
ngOnInit(): void {
setTimeout(() => {
diff --git a/libs/angular-components/src/lib/components/microsite-header/microsite-header.ts b/libs/angular-components/src/lib/components/microsite-header/microsite-header.ts
index ce0dbc6f73..5fe6393368 100644
--- a/libs/angular-components/src/lib/components/microsite-header/microsite-header.ts
+++ b/libs/angular-components/src/lib/components/microsite-header/microsite-header.ts
@@ -65,7 +65,7 @@ export class GoabMicrositeHeader implements OnInit {
}
/** Emits when the feedback link is clicked. */
- @Output() onFeedbackClick = new EventEmitter();
+ @Output() onFeedbackClick = new EventEmitter();
getVersionAsString(): string {
return typeof this.version === "string" ? this.version : "";
diff --git a/libs/angular-components/src/lib/components/modal/modal.ts b/libs/angular-components/src/lib/components/modal/modal.ts
index 6b5906f782..0562ad7391 100644
--- a/libs/angular-components/src/lib/components/modal/modal.ts
+++ b/libs/angular-components/src/lib/components/modal/modal.ts
@@ -32,7 +32,7 @@ import { NgTemplateOutlet } from "@angular/common";
[attr.closable]="closable"
[attr.transition]="transition"
[attr.heading]="getHeadingAsString()"
- (_close)="_onClose()"
+ (_close)="_onClose($event)"
>
@if (this.heading !== "" && getHeadingAsTemplate() !== null) {
@@ -91,7 +91,7 @@ export class GoabModal implements OnInit {
@Input() actions!: TemplateRef;
/** Emits when the modal is closed. */
- @Output() onClose = new EventEmitter();
+ @Output() onClose = new EventEmitter();
getHeadingAsString(): string {
return this.heading instanceof TemplateRef ? "" : this.heading;
@@ -102,7 +102,8 @@ export class GoabModal implements OnInit {
return this.heading instanceof TemplateRef ? this.heading : null;
}
- _onClose() {
+ _onClose(event: Event) {
+ if (event.target !== event.currentTarget) return;
this.onClose.emit();
}
}
diff --git a/libs/angular-components/src/lib/components/push-drawer/push-drawer.ts b/libs/angular-components/src/lib/components/push-drawer/push-drawer.ts
index 1adaeb09cf..db5ab60a4f 100644
--- a/libs/angular-components/src/lib/components/push-drawer/push-drawer.ts
+++ b/libs/angular-components/src/lib/components/push-drawer/push-drawer.ts
@@ -23,7 +23,7 @@ import {
[attr.testid]="testId"
[attr.width]="width"
[attr.version]="version"
- (_close)="_onClose()"
+ (_close)="_onClose($event)"
>
;
/** Emits when the push drawer closes. */
- @Output() onClose = new EventEmitter();
+ @Output() onClose = new EventEmitter();
isReady = false;
@@ -66,7 +66,8 @@ export class GoabPushDrawer implements OnInit {
}, 0);
}
- _onClose() {
+ _onClose(event: Event) {
+ if (event.target !== event.currentTarget) return;
this.onClose.emit();
}
diff --git a/libs/angular-components/src/lib/components/radio-group/radio-group.ts b/libs/angular-components/src/lib/components/radio-group/radio-group.ts
index d22518a691..1d25bf8ab5 100644
--- a/libs/angular-components/src/lib/components/radio-group/radio-group.ts
+++ b/libs/angular-components/src/lib/components/radio-group/radio-group.ts
@@ -63,6 +63,8 @@ export class GoabRadioGroup extends GoabControlValueAccessor implements OnInit {
version = "2";
/** The name for the radio group. Used for accessibility and change events. */
@Input() name?: string;
+ /** The currently selected value in the radio group. */
+ @Input() override value?: string;
/** Sets the layout direction. 'vertical' stacks items, 'horizontal' places them in a row. */
@Input() orientation?: GoabRadioGroupOrientation;
/** Defines how the radio group will be announced by screen readers. */
diff --git a/libs/angular-components/src/lib/components/radio-item/radio-item.ts b/libs/angular-components/src/lib/components/radio-item/radio-item.ts
index 1a88274803..cbccd7c354 100644
--- a/libs/angular-components/src/lib/components/radio-item/radio-item.ts
+++ b/libs/angular-components/src/lib/components/radio-item/radio-item.ts
@@ -69,7 +69,7 @@ export class GoabRadioItem extends GoabBaseComponent implements OnInit {
@Input() revealAriaLabel?: string;
/** Disables this radio option. Also disabled if the parent RadioGroup is disabled. */
@Input({ transform: booleanAttribute }) disabled?: boolean;
- /** Sets this radio option as checked/selected. */
+ /** @internal Sets this radio option as checked/selected. */
@Input({ transform: booleanAttribute }) checked?: boolean;
/** Shows an error state on this radio option. */
@Input({ transform: booleanAttribute }) error?: boolean;
diff --git a/libs/angular-components/src/lib/components/table-sort-header/table-sort-header.ts b/libs/angular-components/src/lib/components/table-sort-header/table-sort-header.ts
index 7ebffb98e5..16e99b20ae 100644
--- a/libs/angular-components/src/lib/components/table-sort-header/table-sort-header.ts
+++ b/libs/angular-components/src/lib/components/table-sort-header/table-sort-header.ts
@@ -17,6 +17,7 @@ import {
[attr.name]="name"
[attr.direction]="direction"
[attr.sort-order]="sortOrder"
+ [attr.version]="version"
>
+
+
+ 2
+
+ `,
+})
+class TestWorkSideMenuItemWithTrailingContentComponent {
+ label = "Trailing item";
+ url = "/trailing";
+}
+
describe("GoabWorkSideMenuItem", () => {
it("should render and set the props correctly", fakeAsync(() => {
TestBed.configureTestingModule({
@@ -96,4 +116,26 @@ describe("GoabWorkSideMenuItem", () => {
expect(popoverContent).toBeTruthy();
expect(popoverContent.nativeElement.textContent).toBe("Popover content here");
}));
+
+ it("should render trailing content into the trailingContent slot", fakeAsync(() => {
+ TestBed.configureTestingModule({
+ imports: [TestWorkSideMenuItemWithTrailingContentComponent],
+ }).compileComponents();
+
+ const fixture = TestBed.createComponent(TestWorkSideMenuItemWithTrailingContentComponent);
+ fixture.detectChanges();
+ tick();
+ fixture.detectChanges();
+
+ const slotDiv = fixture.debugElement.query(
+ By.css('[slot="trailingContent"]'),
+ );
+ expect(slotDiv).toBeTruthy();
+
+ const trailingContent = fixture.debugElement.query(
+ By.css(".trailing-test-content"),
+ );
+ expect(trailingContent).toBeTruthy();
+ expect(trailingContent.nativeElement.textContent).toBe("2");
+ }));
});
diff --git a/libs/angular-components/src/lib/components/work-side-menu-item/work-side-menu-item.ts b/libs/angular-components/src/lib/components/work-side-menu-item/work-side-menu-item.ts
index 527530fe87..493ddcd709 100644
--- a/libs/angular-components/src/lib/components/work-side-menu-item/work-side-menu-item.ts
+++ b/libs/angular-components/src/lib/components/work-side-menu-item/work-side-menu-item.ts
@@ -31,6 +31,11 @@ import { NgTemplateOutlet } from "@angular/common";
}
+ @if (trailingContent) {
+
+ ;
+ /** Template reference for the trailing content slot. */
+ @Input() trailingContent!: TemplateRef;
isReady = false;
diff --git a/libs/angular-components/src/lib/components/work-side-menu/work-side-menu.ts b/libs/angular-components/src/lib/components/work-side-menu/work-side-menu.ts
index ac1bce228e..7218e747ea 100644
--- a/libs/angular-components/src/lib/components/work-side-menu/work-side-menu.ts
+++ b/libs/angular-components/src/lib/components/work-side-menu/work-side-menu.ts
@@ -64,7 +64,7 @@ export class GoabWorkSideMenu implements OnInit {
/** Template reference for the account slot content. */
@Input() accountContent!: TemplateRef;
/** Emits when the side menu is toggled open or closed. */
- @Output() onToggle = new EventEmitter();
+ @Output() onToggle = new EventEmitter();
/** Emits when a navigation link is clicked. Emits the URL as a string. */
@Output() onNavigate = new EventEmitter();
diff --git a/libs/angular-components/src/lib/theme/theme.service.spec.ts b/libs/angular-components/src/lib/theme/theme.service.spec.ts
new file mode 100644
index 0000000000..f64c406512
--- /dev/null
+++ b/libs/angular-components/src/lib/theme/theme.service.spec.ts
@@ -0,0 +1,202 @@
+import { ApplicationRef } from "@angular/core";
+import { TestBed } from "@angular/core/testing";
+import { GoabThemeService } from "./theme.service";
+
+const STORAGE_KEY = "goab-theme";
+const ATTRIBUTE = "data-theme";
+
+function mockMatchMedia(prefersDark: boolean) {
+ Object.defineProperty(window, "matchMedia", {
+ writable: true,
+ value: jest.fn().mockImplementation((query: string) => ({
+ matches: query === "(prefers-color-scheme: dark)" ? prefersDark : false,
+ media: query,
+ onchange: null,
+ addListener: jest.fn(),
+ removeListener: jest.fn(),
+ addEventListener: jest.fn(),
+ removeEventListener: jest.fn(),
+ dispatchEvent: jest.fn(),
+ })),
+ });
+}
+
+function flushEffects() {
+ TestBed.inject(ApplicationRef).tick();
+}
+
+describe("GoabThemeService", () => {
+ beforeEach(() => {
+ localStorage.clear();
+ document.documentElement.removeAttribute(ATTRIBUTE);
+ mockMatchMedia(false);
+ TestBed.resetTestingModule();
+ TestBed.configureTestingModule({});
+ });
+
+ describe("initial mode resolution", () => {
+ it("defaults to 'light' when localStorage, attribute, and system preference are absent", () => {
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+ });
+
+ it("reads 'dark' from localStorage when present", () => {
+ localStorage.setItem(STORAGE_KEY, "dark");
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("reads 'light' from localStorage when present", () => {
+ localStorage.setItem(STORAGE_KEY, "light");
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+ });
+
+ it("ignores invalid localStorage values and falls through to next source", () => {
+ localStorage.setItem(STORAGE_KEY, "purple");
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("reads 'dark' from data-theme attribute when localStorage is empty", () => {
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("reads 'dark' from prefers-color-scheme when localStorage and attribute are absent", () => {
+ mockMatchMedia(true);
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("prefers localStorage over data-theme attribute", () => {
+ localStorage.setItem(STORAGE_KEY, "light");
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+ });
+
+ it("prefers data-theme attribute over prefers-color-scheme", () => {
+ mockMatchMedia(true);
+ document.documentElement.setAttribute(ATTRIBUTE, "light");
+
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+ });
+ });
+
+ describe("setMode", () => {
+ it("updates the mode signal", () => {
+ const service = TestBed.inject(GoabThemeService);
+ service.setMode("dark");
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("syncs the data-theme attribute on ", () => {
+ const service = TestBed.inject(GoabThemeService);
+ service.setMode("dark");
+ flushEffects();
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+
+ service.setMode("light");
+ flushEffects();
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("light");
+ });
+
+ it("persists the mode to localStorage", () => {
+ const service = TestBed.inject(GoabThemeService);
+ service.setMode("dark");
+ flushEffects();
+ expect(localStorage.getItem(STORAGE_KEY)).toBe("dark");
+ });
+ });
+
+ describe("toggle", () => {
+ it("flips light to dark", () => {
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+
+ service.toggle();
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("flips dark to light", () => {
+ localStorage.setItem(STORAGE_KEY, "dark");
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+
+ service.toggle();
+ expect(service.mode()).toBe("light");
+ });
+
+ it("flips back and forth across multiple calls", () => {
+ const service = TestBed.inject(GoabThemeService);
+
+ service.toggle();
+ expect(service.mode()).toBe("dark");
+
+ service.toggle();
+ expect(service.mode()).toBe("light");
+
+ service.toggle();
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("syncs attribute and localStorage on toggle", () => {
+ const service = TestBed.inject(GoabThemeService);
+
+ service.toggle();
+ flushEffects();
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+ expect(localStorage.getItem(STORAGE_KEY)).toBe("dark");
+ });
+ });
+
+ describe("localStorage failures", () => {
+ it("does not throw when localStorage.setItem is blocked", () => {
+ const setItemSpy = jest
+ .spyOn(Storage.prototype, "setItem")
+ .mockImplementation(() => {
+ throw new Error("QuotaExceededError");
+ });
+
+ const service = TestBed.inject(GoabThemeService);
+
+ expect(() => {
+ service.setMode("dark");
+ flushEffects();
+ }).not.toThrow();
+
+ // Attribute should still update even if storage fails
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+
+ setItemSpy.mockRestore();
+ });
+
+ it("does not throw when localStorage.getItem is blocked at construction", () => {
+ const getItemSpy = jest
+ .spyOn(Storage.prototype, "getItem")
+ .mockImplementation(() => {
+ throw new Error("SecurityError");
+ });
+
+ expect(() => TestBed.inject(GoabThemeService)).not.toThrow();
+
+ getItemSpy.mockRestore();
+ });
+ });
+
+ describe("readonly mode signal", () => {
+ it("exposes mode as a read-only signal (no .set/.update)", () => {
+ const service = TestBed.inject(GoabThemeService);
+ const modeSignal = service.mode as unknown as Record;
+
+ expect(typeof modeSignal["set"]).toBe("undefined");
+ expect(typeof modeSignal["update"]).toBe("undefined");
+ });
+ });
+});
diff --git a/libs/angular-components/src/lib/theme/theme.service.ts b/libs/angular-components/src/lib/theme/theme.service.ts
new file mode 100644
index 0000000000..efe89b44a5
--- /dev/null
+++ b/libs/angular-components/src/lib/theme/theme.service.ts
@@ -0,0 +1,52 @@
+import { Injectable, effect, signal, type Signal } from "@angular/core";
+import type { GoabThemeMode } from "@abgov/ui-components-common";
+
+const STORAGE_KEY = "goab-theme";
+const ATTRIBUTE = "data-theme";
+
+@Injectable({ providedIn: "root" })
+export class GoabThemeService {
+ private readonly _mode = signal(this.readInitialMode());
+
+ /** Read-only signal for consumers. Use in templates: theme.mode() === 'dark'. */
+ readonly mode: Signal = this._mode.asReadonly();
+
+ constructor() {
+ effect(() => {
+ const current = this._mode();
+ if (typeof document === "undefined") return;
+ document.documentElement.setAttribute(ATTRIBUTE, current);
+ try {
+ window.localStorage.setItem(STORAGE_KEY, current);
+ } catch {
+ // localStorage blocked: fail silently.
+ }
+ });
+ }
+
+ setMode(next: GoabThemeMode): void {
+ this._mode.set(next);
+ }
+
+ toggle(): void {
+ this._mode.update((prev) => (prev === "light" ? "dark" : "light"));
+ }
+
+ private readInitialMode(): GoabThemeMode {
+ if (typeof window === "undefined") return "light";
+
+ try {
+ const stored = window.localStorage.getItem(STORAGE_KEY);
+ if (stored === "light" || stored === "dark") return stored;
+ } catch {
+ // fall through
+ }
+
+ const fromAttribute = document.documentElement.getAttribute(ATTRIBUTE);
+ if (fromAttribute === "light" || fromAttribute === "dark") return fromAttribute;
+
+ if (window.matchMedia("(prefers-color-scheme: dark)").matches) return "dark";
+
+ return "light";
+ }
+}
diff --git a/libs/common/src/lib/common.ts b/libs/common/src/lib/common.ts
index 6e104f1ad8..942333f31d 100644
--- a/libs/common/src/lib/common.ts
+++ b/libs/common/src/lib/common.ts
@@ -265,6 +265,7 @@ export type GoabButtonGroupGap = "relaxed" | "compact";
// Accordion
export type GoabAccordionHeadingSize = "small" | "medium";
export type GoabAccordionIconPosition = "left" | "right";
+export type GoabAccordionHeadingType = "normal" | "filled";
// Tooltip
@@ -1337,6 +1338,7 @@ export type GoabDrawerSizeUnit = "px" | "rem" | "ch" | "vh" | "vw" | "%";
export type GoabDrawerSize = `${number}${GoabDrawerSizeUnit}` | undefined;
// Work side menu
+/** @deprecated Use trailingContent with explicit badge components for indicator styling. */
export type GoabWorkSideMenuItemType = "normal" | "emergency" | "success";
// Work side notification
@@ -1378,3 +1380,5 @@ export type GoabRadioGroupSize = "default" | "compact";
export type GoabInputSize = "default" | "compact";
export type GoabTextAreaSize = "default" | "compact";
+
+export type GoabThemeMode = "light" | "dark";
diff --git a/libs/react-components/specs/accordion.browser.spec.tsx b/libs/react-components/specs/accordion.browser.spec.tsx
index a76495971b..135df672be 100644
--- a/libs/react-components/specs/accordion.browser.spec.tsx
+++ b/libs/react-components/specs/accordion.browser.spec.tsx
@@ -119,6 +119,59 @@ describe("Accordion", () => {
});
});
+ it("should not expand the accordion when a button in the actions slot is clicked", async () => {
+ const accordionChangeSpy = vi.fn();
+
+ const Component = () => {
+ return (
+ Action
+ }
+ onChange={accordionChangeSpy}
+ >
+ Accordion content
+
+ );
+ };
+
+ const result = render(Action
+ }
+ >
+ Accordion content
+
+ );
+ };
+
+ const result = render(
+ Download file
+
+
+
+ );
+ };
+
+ const result = render(
+ Open parent
+
+ }
+ >
+ Parent content
+
+ Open child
+
+ }
+ >
+ Child content
+
+ Close child
+
+
+
+ );
+ };
+
+ const result = render(Action}>
+ Content
+ ,
+ );
+ const el = baseElement.querySelector("goa-accordion");
+ const actions = el?.querySelector("[slot='actions']");
+ expect(actions).toBeTruthy();
+ });
+
it("should pass data-grid attributes", () => {
const { baseElement } = render(
-
+
Content
,
);
diff --git a/libs/react-components/src/lib/accordion/accordion.tsx b/libs/react-components/src/lib/accordion/accordion.tsx
index a577a18a35..986ace64b5 100644
--- a/libs/react-components/src/lib/accordion/accordion.tsx
+++ b/libs/react-components/src/lib/accordion/accordion.tsx
@@ -3,6 +3,7 @@ import { ReactNode, useEffect, useRef, type JSX } from "react";
import type {
GoabAccordionHeadingSize,
GoabAccordionIconPosition,
+ GoabAccordionHeadingType,
Margins,
DataAttributes,
} from "@abgov/ui-components-common";
@@ -17,6 +18,7 @@ interface WCProps extends Margins {
maxwidth?: string;
testid?: string;
iconposition?: GoabAccordionIconPosition;
+ headingType?: GoabAccordionHeadingType;
}
declare module "react" {
@@ -42,12 +44,16 @@ export interface GoabAccordionProps extends Margins, DataAttributes {
secondaryText?: string;
/** Sets content rendered within the accordion heading, alongside the heading text. */
headingContent?: ReactNode;
+ /** Sets content rendered in the accordion heading, right-aligned before the expand/collapse icon. */
+ actions?: ReactNode;
/** Sets the maximum width of the accordion. @default "none" */
maxWidth?: string;
/** Sets a data-testid attribute for automated testing. */
testId?: string;
/** Sets the position of the expand/collapse icon. @default "left" */
iconPosition?: GoabAccordionIconPosition;
+ /** Sets the accordion style variant. @default "normal" */
+ headingType?: GoabAccordionHeadingType;
/** Callback fired when the accordion is opened or closed. Receives the new open state as a boolean. */
onChange?: (open: boolean) => void;
/** Content rendered inside the accordion body. */
@@ -59,6 +65,8 @@ export function GoabAccordion({
open,
onChange,
headingContent,
+ headingType,
+ actions,
children,
...rest
}: GoabAccordionProps): JSX.Element {
@@ -81,8 +89,14 @@ export function GoabAccordion({
}, [onChange]);
return (
-
+
{headingContent && {headingContent}}
+ {actions && {actions}}
{children}
);
diff --git a/libs/react-components/src/lib/chip/chip.tsx b/libs/react-components/src/lib/chip/chip.tsx
index e02c58b08b..2ad7a678b7 100644
--- a/libs/react-components/src/lib/chip/chip.tsx
+++ b/libs/react-components/src/lib/chip/chip.tsx
@@ -30,19 +30,19 @@ declare module "react" {
}
export interface GoabChipProps extends Margins, DataAttributes {
- /** @required @deprecated Use GoAFilterChip instead. The text content displayed in the chip. */
+ /** @required @deprecated Use GoabFilterChip instead. The text content displayed in the chip. */
content: string;
- /** @deprecated Use GoAFilterChip instead. When true, shows a delete icon and makes chip clickable. */
+ /** @deprecated Use GoabFilterChip instead. When true, shows a delete icon and makes chip clickable. */
deletable?: boolean;
- /** @deprecated Use GoAFilterChip instead. Icon displayed at the start of the chip. */
+ /** @deprecated Use GoabFilterChip instead. Icon displayed at the start of the chip. */
leadingIcon?: string;
- /** @deprecated Use GoAFilterChip instead. The icon theme - outline or filled. */
+ /** @deprecated Use GoabFilterChip instead. The icon theme - outline or filled. */
iconTheme?: GoabChipTheme;
- /** @deprecated Use GoAFilterChip instead. Shows an error state on the chip. */
+ /** @deprecated Use GoabFilterChip instead. Shows an error state on the chip. */
error?: boolean;
- /** @deprecated Use GoAFilterChip instead. The chip variant style. */
+ /** @deprecated Use GoabFilterChip instead. The chip variant style. */
variant?: GoabChipVariant;
- /** @deprecated Use GoAFilterChip instead. Sets a data-testid attribute for automated testing. */
+ /** @deprecated Use GoabFilterChip instead. Sets a data-testid attribute for automated testing. */
testId?: string;
/** Callback fired when the chip is clicked or deleted. */
onClick?: () => void;
diff --git a/libs/react-components/src/lib/container/container.tsx b/libs/react-components/src/lib/container/container.tsx
index f630646802..5645aff2d0 100644
--- a/libs/react-components/src/lib/container/container.tsx
+++ b/libs/react-components/src/lib/container/container.tsx
@@ -46,9 +46,9 @@ export interface GoabContainerProps extends Margins, DataAttributes {
maxHeight?: string;
/** Sets a data-testid attribute for automated testing. */
testId?: string;
- /** Content rendered in the container's title/heading area. */
+ /** @deprecated Use title instead. Alias for the title prop. */
heading?: ReactNode;
- /** @deprecated Use heading instead. Alias for the heading prop. */
+ /** Content rendered in the container's title/heading area. */
title?: ReactNode;
/** Content rendered in the container's actions area, typically buttons or controls. */
actions?: ReactNode;
diff --git a/libs/react-components/src/lib/drawer/drawer.tsx b/libs/react-components/src/lib/drawer/drawer.tsx
index c1eda6568d..9c0fca7e34 100644
--- a/libs/react-components/src/lib/drawer/drawer.tsx
+++ b/libs/react-components/src/lib/drawer/drawer.tsx
@@ -56,9 +56,16 @@ export function GoabDrawer({
if (!el?.current || !onClose) {
return;
}
- el.current?.addEventListener("_close", onClose);
+ const current = el.current;
+ const listener = (e: Event) => {
+ if (e.target !== current) {
+ return;
+ }
+ onClose();
+ };
+ current.addEventListener("_close", listener);
return () => {
- el.current?.removeEventListener("_close", onClose);
+ current.removeEventListener("_close", listener);
};
}, [el, onClose]);
diff --git a/libs/react-components/src/lib/dropdown/dropdown.tsx b/libs/react-components/src/lib/dropdown/dropdown.tsx
index efe4819456..ced71d24a2 100644
--- a/libs/react-components/src/lib/dropdown/dropdown.tsx
+++ b/libs/react-components/src/lib/dropdown/dropdown.tsx
@@ -69,7 +69,7 @@ export interface GoabDropdownProps extends Margins, DataAttributes {
leadingIcon?: GoabIconType;
/** Maximum height of the dropdown menu. Non-native only. @default "276px" */
maxHeight?: string;
- /** When true, allows multiple items to be selected. */
+ /** When true, allows multiple items to be selected. @internal */
multiselect?: boolean;
/** When true, renders the native select HTML element. */
native?: boolean;
diff --git a/libs/react-components/src/lib/hero-banner/hero-banner.tsx b/libs/react-components/src/lib/hero-banner/hero-banner.tsx
index ee721a39a1..3347746c72 100644
--- a/libs/react-components/src/lib/hero-banner/hero-banner.tsx
+++ b/libs/react-components/src/lib/hero-banner/hero-banner.tsx
@@ -29,6 +29,8 @@ export interface GoabHeroBannerProps {
testId?: string;
/** Content rendered inside the hero banner body. */
children?: React.ReactNode;
+ /** Content rendered in the actions slot. */
+ actions?: React.ReactNode;
/** Maximum width of the content area. @default "100%" */
maxContentWidth?: string;
/** Hero Banner background color when no background image is provided. @default "#f8f8f8" */
@@ -46,6 +48,7 @@ export function GoabHeroBanner({
backgroundColor,
textColor,
children,
+ actions,
testId,
}: GoabHeroBannerProps): JSX.Element {
return (
@@ -59,6 +62,7 @@ export function GoabHeroBanner({
testid={testId}
>
{children}
+ {actions && {actions}}
);
}
diff --git a/libs/react-components/src/lib/input/input.tsx b/libs/react-components/src/lib/input/input.tsx
index 7e508a7285..d134194289 100644
--- a/libs/react-components/src/lib/input/input.tsx
+++ b/libs/react-components/src/lib/input/input.tsx
@@ -179,7 +179,10 @@ export function GoabInput({
onBlur,
onKeyPress,
...rest
-}: GoabInputProps & { type?: GoabInputType }): JSX.Element {
+}: GoabInputProps & {
+ /** Sets the type of the input field. @default "text" */
+ type?: GoabInputType;
+}): JSX.Element {
const ref = useRef(null);
const _props = transformProps(
diff --git a/libs/react-components/src/lib/microsite-header/microsite-header.tsx b/libs/react-components/src/lib/microsite-header/microsite-header.tsx
index 4132b6b9ce..106c6adfdf 100644
--- a/libs/react-components/src/lib/microsite-header/microsite-header.tsx
+++ b/libs/react-components/src/lib/microsite-header/microsite-header.tsx
@@ -26,7 +26,7 @@ interface WCProps {
export interface GoabHeaderProps {
/** @required The service type which determines the badge style. "live" shows official government site text, "alpha" and "beta" show development stage badges. */
type: GoabServiceLevel;
- /** App or service version displayed on the right side of the header. Accepts a string or custom ReactNode for rich content. */
+ /** App or service version displayed on the right side of the header. */
version?: string | React.ReactNode;
/** URL to a feedback page displayed when provided. */
feedbackUrl?: string;
diff --git a/libs/react-components/src/lib/modal/modal.tsx b/libs/react-components/src/lib/modal/modal.tsx
index 38604c5d83..4b97f47b13 100644
--- a/libs/react-components/src/lib/modal/modal.tsx
+++ b/libs/react-components/src/lib/modal/modal.tsx
@@ -76,7 +76,10 @@ export function GoabModal({
return;
}
const current = el.current;
- const listener = () => {
+ const listener = (e: Event) => {
+ if (e.target !== current) {
+ return;
+ }
onClose?.();
};
diff --git a/libs/react-components/src/lib/push-drawer/push-drawer.tsx b/libs/react-components/src/lib/push-drawer/push-drawer.tsx
index 681add6e08..ec3d4e7b96 100644
--- a/libs/react-components/src/lib/push-drawer/push-drawer.tsx
+++ b/libs/react-components/src/lib/push-drawer/push-drawer.tsx
@@ -51,9 +51,16 @@ export function GoabPushDrawer({
if (!el?.current || !onClose) {
return;
}
- el.current?.addEventListener("_close", onClose);
+ const current = el.current;
+ const listener = (e: Event) => {
+ if (e.target !== current) {
+ return;
+ }
+ onClose();
+ };
+ current.addEventListener("_close", listener);
return () => {
- el.current?.removeEventListener("_close", onClose);
+ current.removeEventListener("_close", listener);
};
}, [el, onClose]);
diff --git a/libs/react-components/src/lib/radio-group/radio.tsx b/libs/react-components/src/lib/radio-group/radio.tsx
index 9f100e6dc6..11b836f635 100644
--- a/libs/react-components/src/lib/radio-group/radio.tsx
+++ b/libs/react-components/src/lib/radio-group/radio.tsx
@@ -44,7 +44,7 @@ export interface GoabRadioItemProps extends Margins {
maxWidth?: string;
/** Disables this radio option. Also disabled if the parent RadioGroup is disabled. */
disabled?: boolean;
- /** Sets this radio option as checked/selected. */
+ /** @internal Sets this radio option as checked/selected. */
checked?: boolean;
/** Shows an error state on this radio option. */
error?: boolean;
diff --git a/libs/react-components/src/lib/tab/tab.tsx b/libs/react-components/src/lib/tab/tab.tsx
index 919289ed83..0064fb1643 100644
--- a/libs/react-components/src/lib/tab/tab.tsx
+++ b/libs/react-components/src/lib/tab/tab.tsx
@@ -1,7 +1,7 @@
import type { JSX } from "react";
interface WCProps {
- heading?: React.ReactNode;
+ heading?: string | React.ReactNode;
disabled?: string;
slug?: string;
}
@@ -17,7 +17,7 @@ declare module "react" {
export interface GoabTabItemProps {
/** The text label for this tab. Can also pass React nodes for custom heading content. */
- heading?: React.ReactNode;
+ heading?: string | React.ReactNode;
/** When true, disables the tab so it cannot be selected. */
disabled?: boolean;
/** Content rendered inside the tab panel. */
diff --git a/libs/react-components/src/lib/table/table-sort-header.tsx b/libs/react-components/src/lib/table/table-sort-header.tsx
index 0995dc319b..6be764bbe1 100644
--- a/libs/react-components/src/lib/table/table-sort-header.tsx
+++ b/libs/react-components/src/lib/table/table-sort-header.tsx
@@ -10,6 +10,7 @@ interface WCProps {
name?: string;
direction?: GoabTableSortDirection;
"sort-order"?: GoabTableSortOrder;
+ version?: "1" | "2";
}
declare module "react" {
@@ -46,6 +47,7 @@ export function GoabTableSortHeader({
name={name}
direction={direction}
sort-order={sortOrder}
+ version="2"
{...rest}
>
{children}
diff --git a/libs/react-components/src/lib/table/table.tsx b/libs/react-components/src/lib/table/table.tsx
index c07dc6bc17..b654243402 100644
--- a/libs/react-components/src/lib/table/table.tsx
+++ b/libs/react-components/src/lib/table/table.tsx
@@ -10,7 +10,6 @@ import { ReactNode, useEffect, useRef } from "react";
interface WCProps extends Margins {
ref?: React.RefObject;
width?: string;
- stickyheader?: string;
variant?: GoabTableVariant;
"sort-mode"?: GoabTableSortMode;
testid?: string;
@@ -37,7 +36,7 @@ export interface GoabTableProps extends Margins {
onMultiSort?: (detail: GoabTableOnMultiSortDetail) => void;
/** Sort mode: "single" allows one column, "multi" allows up to 2 columns. @default "single" */
sortMode?: GoabTableSortMode;
- // stickyHeader?: boolean; TODO: enable this later
+ // stickyHeader intentionally not exposed in wrapper yet.
/** A relaxed variant of the table with more vertical padding for the cells. @default "normal" */
variant?: GoabTableVariant;
/** When true, alternates row background colors for improved readability. */
diff --git a/libs/react-components/src/lib/theme/theme-context.spec.tsx b/libs/react-components/src/lib/theme/theme-context.spec.tsx
new file mode 100644
index 0000000000..9eec8e998e
--- /dev/null
+++ b/libs/react-components/src/lib/theme/theme-context.spec.tsx
@@ -0,0 +1,215 @@
+import { act, renderHook } from "@testing-library/react";
+import { type ReactNode } from "react";
+
+import { GoabThemeProvider, useTheme } from "./theme-context";
+
+const STORAGE_KEY = "goab-theme";
+const ATTRIBUTE = "data-theme";
+
+function mockMatchMedia(prefersDark: boolean) {
+ Object.defineProperty(window, "matchMedia", {
+ writable: true,
+ value: vi.fn().mockImplementation((query: string) => ({
+ matches: query === "(prefers-color-scheme: dark)" ? prefersDark : false,
+ media: query,
+ onchange: null,
+ addListener: vi.fn(),
+ removeListener: vi.fn(),
+ addEventListener: vi.fn(),
+ removeEventListener: vi.fn(),
+ dispatchEvent: vi.fn(),
+ })),
+ });
+}
+
+function wrapper(props: { children: ReactNode }) {
+ return {props.children} ;
+}
+
+describe("GoabThemeProvider / useTheme", () => {
+ beforeEach(() => {
+ localStorage.clear();
+ document.documentElement.removeAttribute(ATTRIBUTE);
+ mockMatchMedia(false);
+ });
+
+ describe("initial mode resolution", () => {
+ it("defaults to 'light' when localStorage, attribute, and system preference are absent", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("reads 'dark' from localStorage when present", () => {
+ localStorage.setItem(STORAGE_KEY, "dark");
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("reads 'light' from localStorage when present", () => {
+ localStorage.setItem(STORAGE_KEY, "light");
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("ignores invalid localStorage values and falls through to next source", () => {
+ localStorage.setItem(STORAGE_KEY, "purple");
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("reads 'dark' from data-theme attribute when localStorage is empty", () => {
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("reads 'dark' from prefers-color-scheme when localStorage and attribute are absent", () => {
+ mockMatchMedia(true);
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("prefers localStorage over data-theme attribute", () => {
+ localStorage.setItem(STORAGE_KEY, "light");
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("prefers data-theme attribute over prefers-color-scheme", () => {
+ mockMatchMedia(true);
+ document.documentElement.setAttribute(ATTRIBUTE, "light");
+
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("respects defaultMode prop when no other source is set", () => {
+ const customWrapper = (props: { children: ReactNode }) => (
+ {props.children}
+ );
+ const { result } = renderHook(() => useTheme(), { wrapper: customWrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+ });
+
+ describe("setMode", () => {
+ it("updates the mode value", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.setMode("dark"));
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("syncs the data-theme attribute on ", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.setMode("dark"));
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+
+ act(() => result.current.setMode("light"));
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("light");
+ });
+
+ it("persists the mode to localStorage", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.setMode("dark"));
+ expect(localStorage.getItem(STORAGE_KEY)).toBe("dark");
+ });
+ });
+
+ describe("toggle", () => {
+ it("flips light to dark", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("flips dark to light", () => {
+ localStorage.setItem(STORAGE_KEY, "dark");
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("flips back and forth across multiple calls", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("dark");
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("light");
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("syncs attribute and localStorage on toggle", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.toggle());
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+ expect(localStorage.getItem(STORAGE_KEY)).toBe("dark");
+ });
+
+ it("returns a stable toggle reference across renders", () => {
+ const { result, rerender } = renderHook(() => useTheme(), { wrapper });
+ const firstToggle = result.current.toggle;
+
+ rerender();
+ expect(result.current.toggle).toBe(firstToggle);
+ });
+ });
+
+ describe("useTheme outside provider", () => {
+ it("throws a descriptive error when used without GoabThemeProvider", () => {
+ // Suppress React's expected error log for this test
+ const noop = () => undefined;
+ const errorSpy = vi.spyOn(console, "error").mockImplementation(noop);
+
+ expect(() => renderHook(() => useTheme())).toThrow(
+ "useTheme must be used within a GoabThemeProvider",
+ );
+
+ errorSpy.mockRestore();
+ });
+ });
+
+ describe("localStorage failures", () => {
+ it("does not throw when localStorage.setItem is blocked", () => {
+ const setItemSpy = vi
+ .spyOn(Storage.prototype, "setItem")
+ .mockImplementation(() => {
+ throw new Error("QuotaExceededError");
+ });
+
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ expect(() => act(() => result.current.setMode("dark"))).not.toThrow();
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+
+ setItemSpy.mockRestore();
+ });
+
+ it("does not throw when localStorage.getItem is blocked at construction", () => {
+ const getItemSpy = vi
+ .spyOn(Storage.prototype, "getItem")
+ .mockImplementation(() => {
+ throw new Error("SecurityError");
+ });
+
+ expect(() => renderHook(() => useTheme(), { wrapper })).not.toThrow();
+
+ getItemSpy.mockRestore();
+ });
+ });
+});
diff --git a/libs/react-components/src/lib/theme/theme-context.tsx b/libs/react-components/src/lib/theme/theme-context.tsx
new file mode 100644
index 0000000000..2f02c14d1e
--- /dev/null
+++ b/libs/react-components/src/lib/theme/theme-context.tsx
@@ -0,0 +1,87 @@
+import {
+ createContext,
+ useCallback,
+ useContext,
+ useEffect,
+ useState,
+ type ReactNode,
+} from "react";
+import type { GoabThemeMode } from "@abgov/ui-components-common";
+
+interface GoabThemeContextValue {
+ mode: GoabThemeMode;
+ setMode: (mode: GoabThemeMode) => void;
+ toggle: () => void;
+}
+
+const STORAGE_KEY = "goab-theme";
+const ATTRIBUTE = "data-theme";
+
+const GoabThemeContext = createContext(null);
+
+function readInitialMode(defaultMode: GoabThemeMode): GoabThemeMode {
+ if (typeof window === "undefined") return defaultMode;
+
+ // Priority: localStorage > existing data-theme > system preference > defaultMode.
+ // Reading the attribute allows a blocking
diff --git a/libs/web-components/src/components/menu-button/MenuButton.svelte b/libs/web-components/src/components/menu-button/MenuButton.svelte
index 9af6007abb..e77f2634f1 100644
--- a/libs/web-components/src/components/menu-button/MenuButton.svelte
+++ b/libs/web-components/src/components/menu-button/MenuButton.svelte
@@ -139,7 +139,7 @@
}
function onAction(action: MenuActionProps) {
- dispatch(_rootEl, "_action", action, { bubbles: true });
+ dispatch(_rootEl, "_action", { action: action.action, size: action.size }, { bubbles: true });
close();
_buttonIndex = 0;
}
diff --git a/libs/web-components/src/components/microsite-header/MicrositeHeader.svelte b/libs/web-components/src/components/microsite-header/MicrositeHeader.svelte
index fe03dfbd97..ff19af50d9 100644
--- a/libs/web-components/src/components/microsite-header/MicrositeHeader.svelte
+++ b/libs/web-components/src/components/microsite-header/MicrositeHeader.svelte
@@ -161,7 +161,7 @@
color: var(--goa-microsite-header-color-links-hover);
}
- a:focus {
+ a:focus-visible {
outline: var(--goa-microsite-header-link-focus-border);
}
diff --git a/libs/web-components/src/components/notification/Notification.svelte b/libs/web-components/src/components/notification/Notification.svelte
index 28c0caf94e..efe9adb63c 100644
--- a/libs/web-components/src/components/notification/Notification.svelte
+++ b/libs/web-components/src/components/notification/Notification.svelte
@@ -191,11 +191,11 @@
color: unset !important;
outline: unset !important;
}
- :global(::slotted(a:focus)) {
+ :global(::slotted(a:focus-visible)) {
outline: auto !important;
border-radius: var(--goa-border-radius-xs);
}
- .notification.important :global(::slotted(a:focus)) {
+ .notification.important :global(::slotted(a:focus-visible)) {
outline: unset !important;
box-shadow: 0 0 0 3px var(--goa-color-greyscale-black);
border-radius: var(--goa-border-radius-xs);
@@ -423,27 +423,27 @@
}
/* V2 link focus states */
- .v2 .notification.important.high :global(::slotted(a:focus)) {
+ .v2 .notification.important.high :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-important-high-focus-border);
}
- .v2 .notification.important.low :global(::slotted(a:focus)) {
+ .v2 .notification.important.low :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-important-low-focus-border);
}
- .v2 .notification.information.high :global(::slotted(a:focus)) {
+ .v2 .notification.information.high :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-information-high-focus-border);
}
- .v2 .notification.information.low :global(::slotted(a:focus)) {
+ .v2 .notification.information.low :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-information-low-focus-border);
}
- .v2 .notification.emergency.high :global(::slotted(a:focus)) {
+ .v2 .notification.emergency.high :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-emergency-high-focus-border);
}
- .v2 .notification.emergency.low :global(::slotted(a:focus)) {
+ .v2 .notification.emergency.low :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-emergency-low-focus-border);
}
diff --git a/libs/web-components/src/components/popover/Popover.svelte b/libs/web-components/src/components/popover/Popover.svelte
index 0b9fa6d436..362349ec6a 100644
--- a/libs/web-components/src/components/popover/Popover.svelte
+++ b/libs/web-components/src/components/popover/Popover.svelte
@@ -54,13 +54,13 @@
/** Disables the popover interaction. Used by parent components like Dropdown. */
export let disabled: string = "false";
/** Additional vertical offset added to the popover's position. */
- export let voffset = "";
+ export let voffset: string = "";
/** Additional horizontal offset added to the popover's position. */
- export let hoffset = "";
+ export let hoffset: string = "";
/** Width of the focus outline border. */
- export let focusborderwidth = "var(--goa-border-width-l)";
+ export let focusborderwidth: string = "var(--goa-border-width-l)";
/** Border radius of the popover window. */
- export let borderradius = "var(--goa-border-radius-m)";
+ export let borderradius: string = "var(--goa-border-radius-m)";
/** Indicates the popover is used within a filterable context like a combobox. */
export let filterablecontext: string = "false";
@@ -200,6 +200,44 @@
}
}
+ function isInPopoverComposedTree(node: EventTarget | null): boolean {
+ if (!_popoverEl || !(node instanceof Node)) {
+ return false;
+ }
+
+ if (_popoverEl.contains(node)) {
+ return true;
+ }
+
+ // Walk across slot and shadow boundaries to detect nested/slotted descendants.
+ let current: Node | null = node;
+ while (current) {
+ if (current === _popoverEl) {
+ return true;
+ }
+
+ if (current instanceof Element && current.assignedSlot) {
+ current = current.assignedSlot;
+ continue;
+ }
+
+ if (current.parentNode) {
+ current = current.parentNode;
+ continue;
+ }
+
+ const rootNode = current.getRootNode?.();
+ if (rootNode instanceof ShadowRoot) {
+ current = rootNode.host;
+ continue;
+ }
+
+ current = null;
+ }
+
+ return false;
+ }
+
// When one popover is opened it dispatches a `goa:closePopover` to the document.body element, so adding a listener
// here will allow any other popover that is currently open to be closed
function addGlobalCloseListener() {
@@ -213,7 +251,10 @@
// the popover that is being opened will, at that time have the an open state, so we need to prevent
// that one that is being opened be immediately closed.
if (target !== _targetEl) {
- closePopover();
+ // Don't close if the target is a child popover (descendant of this popover's content)
+ if (target && !isInPopoverComposedTree(target)) {
+ closePopover();
+ }
}
});
}
@@ -404,7 +445,7 @@
class:use-anchor-based-positioning={!_needsManualPositioning}
class:align-right={_alignment === "right"}
style={styles(
- style("width", position !== "right" ? width : undefined),
+ position !== "right" && style("width", width),
style("min-width", minwidth),
style(
"max-width",
diff --git a/libs/web-components/src/components/push-drawer/PushDrawerInternal.svelte b/libs/web-components/src/components/push-drawer/PushDrawerInternal.svelte
index 5efc55ea69..192bfa1e9e 100644
--- a/libs/web-components/src/components/push-drawer/PushDrawerInternal.svelte
+++ b/libs/web-components/src/components/push-drawer/PushDrawerInternal.svelte
@@ -24,6 +24,7 @@
export let open: boolean = false;
export let heading: string = "";
export let width: string = "492px";
+ /** @internal Design system version for styling. */
export let version: VersionType = "1";
let _contentEl: HTMLElement | null = null;
diff --git a/libs/web-components/src/components/radio-item/RadioItem.svelte b/libs/web-components/src/components/radio-item/RadioItem.svelte
index bbf00546a5..678d8705a2 100644
--- a/libs/web-components/src/components/radio-item/RadioItem.svelte
+++ b/libs/web-components/src/components/radio-item/RadioItem.svelte
@@ -66,7 +66,7 @@
export let disabled: string = "false";
/** Shows an error state on this radio option. */
export let error: string = "false";
- /** Sets this radio option as checked/selected. */
+ /** @internal Sets this radio option as checked/selected. */
export let checked: string = "false";
/** Defines how this option will be announced by screen readers. */
export let arialabel: string = "";
@@ -209,7 +209,7 @@
checked = fromBoolean(data.checked);
description = data.description;
name = data.name;
- revealarialabel = data.revealAriaLabel;
+ revealarialabel = data.revealAriaLabel || "";
_version = data.version || "1";
_compact = data.compact || false;
});
diff --git a/libs/web-components/src/components/side-menu-group/SideMenuGroup.svelte b/libs/web-components/src/components/side-menu-group/SideMenuGroup.svelte
index ef495212c3..7002ab82d5 100644
--- a/libs/web-components/src/components/side-menu-group/SideMenuGroup.svelte
+++ b/libs/web-components/src/components/side-menu-group/SideMenuGroup.svelte
@@ -138,7 +138,7 @@
${calculateMargin(mt, mr, mb, ml)};
`}
>
-
+
{#if icon}
diff --git a/libs/web-components/src/components/temporary-notification/TemporaryNotificationCtrl.svelte b/libs/web-components/src/components/temporary-notification/TemporaryNotificationCtrl.svelte
index 5d63f8b7c4..fee9e12954 100644
--- a/libs/web-components/src/components/temporary-notification/TemporaryNotificationCtrl.svelte
+++ b/libs/web-components/src/components/temporary-notification/TemporaryNotificationCtrl.svelte
@@ -1,28 +1,35 @@
- | undefined;
// Use a unique id for each tooltip instance.
// So screen readers can identify the tooltip instance when
@@ -143,6 +143,16 @@
}, 500);
};
+ // Mouse click also fires on:focus on a tabindex=0 element, but we only want
+ // to reveal the tooltip on keyboard-driven focus so JS state stays aligned
+ // with the CSS :focus-visible rule that drives opacity.
+ function handleFocus(e: FocusEvent) {
+ const target = e.currentTarget as HTMLElement | null;
+ if (!target?.matches?.(":focus-visible")) return;
+ clearTimeout(_hideTooltipTimeout);
+ showTooltip();
+ }
+
async function checkAndAdjustPosition() {
// angular needs time to render the _tooltipEl
await tick();
@@ -227,10 +237,7 @@
showTooltip();
}}
on:mouseleave={hideTooltip}
- on:focus={() => {
- clearTimeout(_hideTooltipTimeout);
- showTooltip();
- }}
+ on:focus={handleFocus}
on:blur={hideTooltip}
data-testid={testid}
role="tooltip"
@@ -315,7 +322,7 @@
}
.tooltip:hover .tooltip-text,
- .tooltip:focus .tooltip-text {
+ .tooltip:focus-visible .tooltip-text {
opacity: 1;
}
diff --git a/libs/web-components/src/components/work-side-menu/WorkSideMenu.svelte b/libs/web-components/src/components/work-side-menu/WorkSideMenu.svelte
index 4aabdd4c56..a08757c4e7 100644
--- a/libs/web-components/src/components/work-side-menu/WorkSideMenu.svelte
+++ b/libs/web-components/src/components/work-side-menu/WorkSideMenu.svelte
@@ -32,7 +32,7 @@
// optional
/** Controls whether the side menu is expanded or collapsed. */
- export let open = false;
+ export let open: boolean = false;
/** Sets a data-testid attribute for automated testing. */
export let testid: string = "";
/** User's name displayed in the profile section. */
@@ -55,10 +55,10 @@
let _menuEl: HTMLElement;
let _menuLinks: HTMLElement[] = [];
- let _containerEl: HTMLElement;
+ let _containerEl: HTMLElement | undefined;
let _rootEl: HTMLElement;
let _scrollEl: HTMLElement;
- let _toggleButtonEl: HTMLElement;
+ let _toggleButtonEl: HTMLElement | undefined;
let _tooltipEl: HTMLElement;
let _tooltipLabel: string = "";
@@ -71,7 +71,7 @@
let _resizeObserver: ResizeObserver | null = null;
const _logo =
- "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32' fill='none'%3E%3Crect width='31.695' height='31.688' x='.028' fill='%2300B6ED' rx='4'/%3E%3Cg clip-path='url(%23a)'%3E%3Cmask id='b' width='47' height='39' x='-11' y='-2' maskUnits='userSpaceOnUse' style='mask-type:alpha'%3E%3Cpath fill='%23545860' d='M22.017 31.103a63.47 63.47 0 0 1-7.22-3.164 52.41 52.41 0 0 0 6.195-2.724 43.148 43.148 0 0 0 1.023 5.89m13.27-24.392c-1.034-.13-.497.348-.785 1.7-1.246 5.832-6.05 10.035-10.873 12.855-.506-6.678-.3-14.093.967-18.636 1.069-3.836 2.34-3.132.763-3.938-1.66-.848-3.44.273-4.882 3.13C19.033 4.68 12.393 20.19 1.78 30.664c-5.43 5.36-10.34 2.6-11.323 1.775-.8-.67-1.096.365-.103 1.426 4.39 4.7 10.805 2.003 13.141-.314 6.455-6.405 13.96-20.193 16.996-26.044a89.89 89.89 0 0 0 .243 15.294 44.69 44.69 0 0 1-7.619 2.885c-1.504.391-2.435 1-2.462 1.691-.03.758.98 1.397 2.44 2.085 2.6 1.226 10.216 4.798 12.093 5.878 1.606.925 2.39.204 2.866-.796.622-1.302-1.083-2.054-2.735-2.545a50.47 50.47 0 0 1-1.48-8.385c3.87-2.365 7.682-5.52 9.88-9.452a18.004 18.004 0 0 0 1.568-4.365c.23-.934.293-1.9.186-2.855 0 0-.03-.209-.186-.229'/%3E%3C/mask%3E%3Cg mask='url(%23b)'%3E%3Crect width='31.695' height='31.695' x='.028' fill='%23fff' rx='3.048'/%3E%3C/g%3E%3C/g%3E%3Cdefs%3E%3CclipPath id='a'%3E%3Crect width='32' height='31.992' y='.008' fill='%23fff' rx='4'/%3E%3C/clipPath%3E%3C/defs%3E%3C/svg%3E";
+ "data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHdpZHRoPSczMicgaGVpZ2h0PSczMicgZmlsbD0nbm9uZSc+PHJlY3Qgd2lkdGg9JzMxLjY5NScgaGVpZ2h0PSczMS42ODgnIHg9Jy4wMjgnIGZpbGw9JyMwMEI2RUQnIHJ4PSc0Jy8+PGcgY2xpcC1wYXRoPSd1cmwoI2EpJz48bWFzayBpZD0nYicgd2lkdGg9JzQ3JyBoZWlnaHQ9JzM5JyB4PSctMTEnIHk9Jy0yJyBtYXNrVW5pdHM9J3VzZXJTcGFjZU9uVXNlJyBzdHlsZT0nbWFzay10eXBlOmFscGhhJz48cGF0aCBmaWxsPScjNTQ1ODYwJyBkPSdNMjIuMDE3IDMxLjEwM2E2My40NyA2My40NyAwIDAgMS03LjIyLTMuMTY0IDUyLjQxIDUyLjQxIDAgMCAwIDYuMTk1LTIuNzI0IDQzLjE0OCA0My4xNDggMCAwIDAgMS4wMjMgNS44OW0xMy4yNy0yNC4zOTJjLTEuMDM0LS4xMy0uNDk3LjM0OC0uNzg1IDEuNy0xLjI0NiA1LjgzMi02LjA1IDEwLjAzNS0xMC44NzMgMTIuODU1LS41MDYtNi42NzgtLjMtMTQuMDkzLjk2Ny0xOC42MzYgMS4wNjktMy44MzYgMi4zNC0zLjEzMi43NjMtMy45MzgtMS42Ni0uODQ4LTMuNDQuMjczLTQuODgyIDMuMTNDMTkuMDMzIDQuNjggMTIuMzkzIDIwLjE5IDEuNzggMzAuNjY0Yy01LjQzIDUuMzYtMTAuMzQgMi42LTExLjMyMyAxLjc3NS0uOC0uNjctMS4wOTYuMzY1LS4xMDMgMS40MjYgNC4zOSA0LjcgMTAuODA1IDIuMDAzIDEzLjE0MS0uMzE0IDYuNDU1LTYuNDA1IDEzLjk2LTIwLjE5MyAxNi45OTYtMjYuMDQ0YTg5Ljg5IDg5Ljg5IDAgMCAwIC4yNDMgMTUuMjk0IDQ0LjY5IDQ0LjY5IDAgMCAxLTcuNjE5IDIuODg1Yy0xLjUwNC4zOTEtMi40MzUgMS0yLjQ2MiAxLjY5MS0uMDMuNzU4Ljk4IDEuMzk3IDIuNDQgMi4wODUgMi42IDEuMjI2IDEwLjIxNiA0Ljc5OCAxMi4wOTMgNS44NzggMS42MDYuOTI1IDIuMzkuMjA0IDIuODY2LS43OTYuNjIyLTEuMzAyLTEuMDgzLTIuMDU0LTIuNzM1LTIuNTQ1YTUwLjQ3IDUwLjQ3IDAgMCAxLTEuNDgtOC4zODVjMy44Ny0yLjM2NSA3LjY4Mi01LjUyIDkuODgtOS40NTJhMTguMDA0IDE4LjAwNCAwIDAgMCAxLjU2OC00LjM2NWMuMjMtLjkzNC4yOTMtMS45LjE4Ni0yLjg1NSAwIDAtLjAzLS4yMDktLjE4Ni0uMjI5Jy8+PC9tYXNrPjxnIG1hc2s9J3VybCgjYiknPjxyZWN0IHdpZHRoPSczMS42OTUnIGhlaWdodD0nMzEuNjk1JyB4PScuMDI4JyBmaWxsPScjZmZmJyByeD0nMy4wNDgnLz48L2c+PC9nPjxkZWZzPjxjbGlwUGF0aCBpZD0nYSc+PHJlY3Qgd2lkdGg9JzMyJyBoZWlnaHQ9JzMxLjk5MicgeT0nLjAwOCcgZmlsbD0nI2ZmZicgcng9JzQnLz48L2NsaXBQYXRoPjwvZGVmcz48L3N2Zz4=";
// *****
// Hooks
@@ -198,6 +198,7 @@
}
function setTooltipPos(label: string, el: HTMLElement) {
+ if (!_containerEl || !_tooltipEl) return;
const rect = el?.getBoundingClientRect();
const containerRect = _containerEl.getBoundingClientRect();
const top = rect.top - containerRect.top + rect.height / 2;
@@ -218,7 +219,7 @@
}
function handleToggleHover() {
- if (open) return;
+ if (open || !_toggleButtonEl) return;
setTooltipPos("Expand menu", _toggleButtonEl);
showTooltip();
@@ -378,12 +379,12 @@
{#if url}
-
+
{heading}
{:else}
-
+
{heading}
{/if}
@@ -477,6 +478,13 @@
- Phone: 780 123 4567
-
- Email: information@gov.ab.ca
-
- Phone: 780 123 4567
-
- Email: information@gov.ab.ca
-
- Phone: 780 123 4567
-
- Email: information@gov.ab.ca
-
- You are designing a public service for citizens. It should be designed to be as simple
- and intuitive as possible, while ensuring citizens can make complete and informed
- decisions for themselves using the service.
-
- There is an emphasis on an accessible experience with a low cognitive load for users
- who use the service infrequently.
-
-
-
-
- You are designing a public service for citizens. It should be designed to be as
- simple and intuitive as possible, while ensuring citizens can make complete and
- informed decisions for themselves using the service.
-
-
- There is an emphasis on an accessible experience with a low cognitive load for
- users who use the service infrequently.
-
-
-
- You are designing a public service for citizens. It should be designed to be as simple
- and intuitive as possible, while ensuring citizens can make complete and informed
- decisions for themselves using the service.
-
- There is an emphasis on an accessible experience with a low cognitive load for users
- who use the service infrequently.
-
-
-
Workspaces should be adapted to fit each service's context and user needs. The reference example is a starting point to expand on, not a rigid template.
-categories: []
-scale: product
-userType: worker
-tags:
- - workspace
- - worker
- - service
- - case-management
- - dashboard
- - pattern
-components:
- - work-side-menu
- - table
- - badge
- - tabs
- - container
- - accordion
- - drawer
- - button
- - block
-previewImage: /thumbnails/workspace-preview.png
-status: published
----
-
-
-
-
-**Primary user:** Service delivery staff
-
-## When to use
-
-Use the workspace when your service needs to support regular, task-based work, such as:
-
-- Reviewing and processing submissions
-- Managing case files, applications, or requests
-- Moving between dashboards, lists, and detail views
-- Taking actions such as approve, deny, assign, or request more information
-
-## When not to use
-
-- Citizen-facing services — use the [public form](/examples/public-form) pattern instead
-- Content-only pages that don't involve case management
-- Simple internal tools that don't need structured case processing
-
----
-
-## Sidebar navigation
-
-Use the [work side menu](/components/work-side-menu) as the primary navigation for a workspace.
-
-Keep top-level navigation focused on the main areas of work. When a user opens a record or case, switch to contextual navigation that supports that task. This puts the user into a focused mode with relevant navigation items (like sections of an application, comments, reminders) and a back link to return to the main view. The sidebar can adapt to what the user is doing, it doesn't have to show everything at once.
-
-- Main workspace navigation -
-
-
-- Contextual case navigation -
-
-
-
-
-- Table view -
-
-
-- Card view -
-
-
-- Expandable list view -
-
-
-
-
-
-
-
-
-
-
-
----
-
-## Considerations
-
-- The reference demo is a spike — component customizations haven't gone through the production pipeline yet
-- There should be significant variability within a workspace to meet each service's specific context and user needs
-- The demo is a starting point to expand on and adapt, not a rigid template to copy exactly
-- Desktop uses a card container pattern for the main content area; this is removed on mobile for space
diff --git a/docs/src/content/get-started/automated-accessibility.mdx b/docs/src/content/get-started/automated-accessibility.mdx
new file mode 100644
index 0000000000..07bae83e0b
--- /dev/null
+++ b/docs/src/content/get-started/automated-accessibility.mdx
@@ -0,0 +1,83 @@
+---
+id: automated-accessibility
+title: Automated accessibility
+description: Guidance on using automated accessibility testing tools effectively
+section: intro
+order: 2
+status: published
+---
+import DropInCallout from "../../components/DropInCallout.astro";
+
++ However, these tools are not a complete solution. They can produce: +
+-
+
- False positives – flagging issues that are not actual problems +
- False negatives – missing real accessibility barriers +
+ To ensure your digital product is accessible, combine automated testing with manual testing and apply + human judgment. +
+
+ Automated tools may flag elements as non-compliant even when they work correctly for users. For
+ example, a tool may report that an input is "missing an id" even though it is correctly associated with a
+ label using a valid method, such as wrapping the input inside a <label> element.
+
+ Automated tools cannot detect nuanced or context-specific issues. For example, all interactive + elements may be tabbable, but the order jumps around the page. Tools often don't judge whether the + tab order is logical for completing the task. +
+ ++ Accessibility ensures real people can use a product effectively. Automated tools cannot fully simulate + how users interact with your product. +
+-
+
- + Run automated tools to get an initial assessment. + +
- + Manually verify flagged issues and review the element's intent and context. + +
-
+ Do additional manual testing for issues automated tools cannot detect:
+
-
+
- Test with a screen reader, such as VoiceOver (macOS) or NVDA (Windows) +
- Test keyboard navigation by checking focus visibility and order +
+ -
+ Report findings
+
-
+
- Record what you tested, what failed, and how to reproduce it +
- If the issue relates to a design system component, submit it using the design system bug report form +
+
+ Automated tools provide helpful insight. Relying only on automation can result in: +
+-
+
- Time spent fixing issues that are not real barriers +
- Missed opportunities to address genuine accessibility issues +
- A false sense of compliance without meaningful usability improvements +
+ Combine automated and manual testing to identify real barriers. This approach improves accessibility + and overall product quality. +
++ To request a new component or propose an enhancement, follow the + design contribution process. +
++ Experimental components are new or significantly updated. They are available for testing and feedback + before public release. +
+ +-
+
- Feedback is gathered from selected teams +
- May be unstable or include breaking changes +
- Limited documentation +
+ Production components are stable and ready for broader adoption. +
+ +-
+
- Fully documented, including design guidelines, properties, and examples +
- Meet accessibility and design system standards +
- Optimized for mobile use +
- Actively maintained with updates and bug fixes +
- Publicly available documentation +
+ Legacy components are older components maintained primarily to support older implementations. If + possible, transition to production is recommended. +
+ +-
+
- No active maintenance or updates +
- Critical issues may remain unresolved +
- Recommended alternative clearly identified +
- Marked as "Legacy" in official documentation +
+ Start by using existing Design System components and patterns. If a component or pattern does not + meet your needs, follow the contribution process below. +
++ If a required component or example does not exist in production, + contact the Design System team. We will review the request together and determine next steps. +
+ ++ Book a design system drop-in hours session. +
+Be prepared to:
+-
+
- Describe the component or pattern and its purpose +
- Explain your user needs and service goals +
- Share iterations explored with and without the Design System +
A proposed component or pattern must meet the following criteria.
+ +Useful
++ Evidence shows it supports multiple teams or services. Provide screenshots or links to demonstrate usage. +
+ +Unique
++ It does not duplicate an existing component or pattern. If replacing an existing component, provide + evidence that the new approach improves usability or accessibility. +
+ +To be published, the solution must be:
+ +Usable
++ Improves clarity, usability, and accessibility for users. Is informed by research and addresses a + validated user need. +
+ +Universal
++ Inclusive and accessible. Meets or exceeds accessibility standards. + WCAG 2.2 AA is the minimum requirement. +
+ ++ If approved, the item is added to the + Design System's backlog. +
++ When development begins, the Design System team will collaborate with you to confirm detailed requirements. +
++ The Design System supports multiple development frameworks through Web Components. Contributing full + components can be complex. Smaller contributions are encouraged. +
+ +-
+
- Bug fixes +
- Documentation updates +
- Enhancements to existing components +
+ Start by contacting the team in the #design-system-support Slack channel. +
++ Select an issue tagged ready-for-contribution from the + backlog. + Confirm which issue you will work on. +
+ +-
+
- Clone the ui-components repository. +
- Open the repository in your IDE. +
- Create a branch named:
contributions/story-number
+ -
+ Run the following commands:
+
+npm i +npm run build
+ -
+ The playgrounds for local testing are located in:
+
+/apps/dev/angular +/apps/dev/react
+
Angular
+npm run dev:watch
+npm run serve:dev:angularReact
+npm run dev:watch
+npm run serve:dev:reactReact wrappers
+/libs/react-components/src/lib
Each folder represents a single component with its associated unit tests and wrapper code.
+ +Angular wrappers
+/libs/angular-components/src/lib/components
Each folder represents a single component with its associated unit tests and wrapper code.
+ +Web Components
+/libs/web-components/src/components
-
+
- Unit tests as
{"*.spec.ts"}
+ - Component code as
{"*.svelte"}
+
-
+
- Write all unit tests in Svelte. +
- If updating React or Angular wrappers, write unit tests in those respective frameworks. +
-
+ Add browser testing using Jest for React wrappers and Svelte components when appropriate.
+ These can be found in:
libs/react-components/specs+
+ - Manually test components in both React and Angular. +
-
+ Create test files that others can use to manually test the PR. These can be created in:
+
+/apps/prs/angular +/apps/prs/react
+ - Follow the conventions already used in those files to create your test files. +
A Design System developer will also manually test the pull request.
+ +Use the following commit message format:
+ +Bug fix
+fix(#storyNumber): short description (7 words max)Feature request
+feat(#storyNumber): short description (7 words max)-
+
- Create a pull request from your branch to the
devbranch.
+ - Notify the design system team of the PR. +
In Figma, you can access:
+ +-
+
- Design tokens +
- Components +
- Patterns +
+ The design system library in Figma aligns with coded components used by developers. Start with + design system components for common parts of your service. This helps developers use the matching + coded components and reduces custom work. +
++ Start with the design system. Validate your design through user testing. If usability issues arise, + or the problem cannot be solved within the system, consider creating a custom solution. +
+
+ When selecting components, prioritize those with a "goa-" prefix, such as
+ goa-input. These components exist in both design and development. Using them reduces
+ the need for custom development.
+
Choose shared components whenever possible to maintain consistency and efficiency.
+ +Design system components in Figma and code are built using design tokens.
++ Use tokens to communicate design decisions clearly. Developers can reference the same tokens in code. +
+Instead of sharing hex values or pixel adjustments, reference semantic tokens.
+For example:
+-
+
- Colour:
--goa-color-info-default
+ - Spacing:
--goa-spacing-m
+
Using tokens reduces back-and-forth and keeps design and development aligned.
+ +All design system components are available in Figma and in code.
++ These components are designed to meet + WCAG 2.2 accessibility standards. +
+Avoid detaching components. Instead:
+-
+
- Use variants +
- Show or hide layers within the component +
+ Use #figma for Figma-related issues, including library updates, missing components, + broken instances, or component behaviour in Figma. +
++ Use #design-system-support for design system guidance, component usage questions, + standards, and implementation support. +
+Keep your components up to date. Figma will notify you when library updates are available.
+ +Each digital service project folder includes a starter Figma template.
+Use this template to:
+-
+
- Organize your design file +
- Support developer handoff +
- Help team members navigate files +
+ Helper components are also available. Use them to clearly communicate intent when sharing designs + with developers and other team members. +
++ We have an experimental version of dark mode you can try out in your service. It's handled automatically in code, so designers don't need to do anything different. The Figma library doesn't have a dark mode yet, so keep designing in light mode like you always have. Your designs will translate to dark mode when developers add the dark mode theme to your service. +
+ ++ If you're using design system components, they all work with dark mode automatically. +
++ If you have custom components that use our design tokens, they'll switch to dark mode along with the rest of the system. Always worth testing to make sure things look right in both modes. +
++ If your custom components don't use our design tokens, they won't switch on their own. You'll need to handle dark mode for those yourself. We recommend using design tokens where you can so most of this happens automatically. +
++ Either way, you can extend dark mode for custom needs by working with developers to add custom dark mode styles to your service. +
++ The same goes for illustrations and images with set colors. These look the same in both modes, so check whether they read well on a dark background or whether you need a dark version. +
+ ++ Dark mode is still being tested. Try it out in your service and let the design system team know what works, what doesn't, and what's missing. +
+ ++ Two ways users end up in dark mode. Use either, or both: +
+-
+
- System settings. If their operating system is in dark mode, your service follows automatically. +
- A toggle in your service. Let users switch modes themselves through a preferences or settings screen. +
+ The Digital Design and Delivery (DDD) Design System has evolved to better support how service teams + design and build digital government services. Design System 2.0 includes an updated design + language, new tokens, refreshed components, and ready-to-use templates. +
++ Use DS 2.0 templates as your starting point. Templates package layout, navigation, spacing, and + example content that you can adapt to your service. Some templates are built for specific service types + (for example, public-facing forms and workspace applications), and others are more general-purpose + starting points you can use across many kinds of pages and flows. +
+ ++ Use a library swap if + your goal is to convert most of the file to DS 2.0 in one pass. +
+-
+
- Make a copy of your file before you start. +
- Expect mixed results. Some screens may need cleanup after the swap. +
Use a manual rebuild if you need more control.
+-
+
- Rebuild your highest value screens first. +
- Consider using DS 2.0 templates as a base to speed things up. +
Use this approach in most cases.
+-
+
- A developer creates a new branch and completes the upgrade steps. +
- The team runs the upgraded application to see what changed. +
- Designers review the upgraded screens and identify what needs design updates. +
When reviewing the upgraded branch, watch for:
+-
+
- Spacing and layout rhythm +
- Typography scale and weight usage +
- Dense or constrained screens (these often have the highest risk during an update) +
Use this approach when you want design work to move ahead of development work.
+-
+
- Identify custom elements that support your users' needs. +
- Create an inventory and prioritize items by importance and effort. +
- Redesign the highest priority items using the visual design values in the Styles library. +
-
+
- User-centered: Designed with a clear understanding of users, their goals, tasks, environments, and context of use, using user-centered design methods. +
- Usable: Interfaces will be easy to use, enabling users to find the information they need and complete tasks successfully. +
- Accessible: Digital products will be inclusive, ensuring usability for everyone, regardless of physical or cognitive ability. +
- Trustworthy: Experiences will feel familiar and recognizable as a Government of Alberta product, ensuring users' security and privacy. +
- Modern: Digital experiences will meet present-day user expectations and preferences for aesthetics and interaction. +
+ For more details on the process of assessing compliance to each guideline, refer to our + User Experience Guidelines and Design System Checklist. +
++ Usability testing is our preferred method to understand user needs as they relate to each guideline. +
+Suitable usability testing includes:
+-
+
- Diverse user group: Real users from different demographic, behavioural backgrounds, and geographical regions within Alberta that will experience the problem or benefit of the product. +
- Inclusive testing: Users with various physical and/or cognitive abilities, literacy levels, and tech savviness. +
- Device variety: A diverse range of devices that reflect users' preferred choice when interacting with government services. +
- Tasks: Activities that cover tasks and service process from end-to-end. +
+ Frequent usability testing should be conducted to maintain product usability, effectiveness and + alignment to the user needs as they evolve over time. +
++ For guidance on the process of usability testing, refer to our + Understanding Usability documentation. +
++ The DDD Design System is built using Web Components. Web Components are framework-agnostic. + You can use them with Angular, React, or other front-end frameworks. +
+The Design System includes:
+-
+
- Tokens +
- Components +
- Examples +
- Templates +
+ Designers use equivalent resources in Figma. When they design with Design System components, you + can build with the matching coded components. This reduces custom development and rework. +
++ All Design System components are designed and built to meet + WCAG 2.2 accessibility standards. +
++ Access the tokens as an + NPM package. +
++ Import the SCSS or CSS file into your project. Replace hard-coded values with Design System token variables. +
++ Designers reference the same tokens in their tools. This keeps design and development aligned during handoff. +
+ +Components are reusable user interface elements built for use across services.
+You can:
+-
+
- Use components individually +
- Combine them into patterns +
- Apply them in different contexts +
Components are available:
+-
+
- As Web Components +
- As Angular wrappers +
- As React wrappers +
+ Refer to the Design System technologies documentation + for implementation details. +
+ ++ Examples are multiple components assembled in realistic service contexts. They help you understand + how to apply Design System guidance in a working interface. +
+You can use examples to:
+-
+
- Understand how components work together +
- Use them as a starting point for building parts of your interface +
- Use proven approaches to meet user needs +
+ Examples help you build with more consistency and less rework. Use them to guide implementation, + then adjust them to meet the needs of your product. +
+ ++ Templates are opinionated starting points for common service types. They package layout, navigation, + spacing, and example content so you can start with a proven structure instead of building from scratch. +
+You can use templates to:
+-
+
- Start a new product with a proven structure +
- Learn how components work together in a real layout +
- Adapt a proven starting point to fit your service needs +
+ Templates help teams move faster, reduce rework, and stay aligned with Design System guidance. +
++ We support the latest version of each browser listed on this page. Support applies to the browser and + operating system combinations shown in the table below. On mobile, support is limited to the browser + and operating system combinations listed for Android and iOS. +
+ +| Browser | +Windows | +Mac OS | +Android | +iOS | +
|---|---|---|---|---|
| Google Chrome | +Yes | +Yes | +Yes | +Yes | +
| Microsoft Edge | +Yes | +Yes | ++ | + |
| Mozilla Firefox | +Yes | +Yes | +Yes | ++ |
| Apple Safari | +N/A | +Yes | +N/A | +Yes | +
-
+
- Android OS: 10+ +
- iOS: 15+ +
+ Use supported browsers and operating system versions when developing and testing services. If you + encounter a browser-specific issue, follow the + Verify a bug process. +
++ These steps help confirm whether the issue is caused by the Design System, your product setup, or + custom code. This process applies to Angular and React implementations. +
+ +Confirm you are using the latest version of:
+-
+
- Web Components +
- Angular or React +
+ If you are not using the latest version, upgrade and retest. If the issue remains, continue to the next step. +
+ +Use the official Angular or React product templates to isolate the issue.
+ +This helps determine whether the issue exists outside your project configuration.
+ +Create a minimal test environment.
+-
+
- Use only the code required for the example to function +
- Include only the component experiencing the issue +
- Remove unrelated dependencies or custom logic +
Confirm whether the issue can be replicated.
+ +If you can reproduce the issue:
+-
+
- Share the template application link in the #design-system-support Slack channel +
- Provide a link to your repository so the team can review and replicate the issue +
+ Following these steps will help to ensure efficient investigation and quicker resolution of + design system component issues. +
+@abgov/design-tokens version 2.8.0 or
+ higher with the dark theme stylesheet imported. See Setup
+ for installation steps.
+
+How it works
+data-theme
+ attribute on the document root (<html>). Design tokens scoped
+ to :root[data-theme="dark"] activate via CSS cascade,
+ automatically applying dark colors to every component without re-rendering.
+Initial mode priority
+-
+
- The user's previously chosen mode, read from local storage +
- The operating system preference (light or dark) +
- The framework default (light) +
React
+1. Wrap your app with GoabThemeProvider
+BrowserRouter:
+{`// main.tsx
+import { GoabThemeProvider } from "@abgov/react-components";
+import { BrowserRouter } from "react-router-dom";
+import "@abgov/design-tokens/dist/tokens.css";
+import "@abgov/design-tokens/dist/dark-theme.css";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+
+
+
+ ,
+);`}2. Read and toggle theme with useTheme
+useTheme() to read
+ the current mode and switch theme:
+{`import { GoabButton, useTheme } from "@abgov/react-components";
+
+function ThemeToggle() {
+ const { mode, toggle } = useTheme();
+ const isDark = mode === "dark";
+
+ return (
+
+ {isDark ? "Light mode" : "Dark mode"}
+
+ );
+}`}API
+{`interface GoabThemeContextValue {
+ /** Current theme mode. */
+ mode: "light" | "dark";
+ /** Set theme to a specific mode. */
+ setMode: (next: "light" | "dark") => void;
+ /** Flip between light and dark. */
+ toggle: () => void;
+}
+
+interface GoabThemeProviderProps {
+ children: ReactNode;
+ /** Initial mode used when no stored or system preference is found. @default "light" */
+ defaultMode?: "light" | "dark";
+}`}useTheme throws if called outside of GoabThemeProvider.
+
+Angular
+1. Import the dark theme stylesheet
+src/styles.css):
+@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+@import "@abgov/design-tokens/dist/dark-theme.css";2. Inject GoabThemeService
+{`// app.component.ts
+import { Component, inject } from "@angular/core";
+import { GoabThemeService } from "@abgov/angular-components";
+
+@Component({
+ selector: "app-root",
+ templateUrl: "./app.component.html",
+})
+export class AppComponent {
+ readonly theme = inject(GoabThemeService);
+
+ toggleTheme() {
+ this.theme.toggle();
+ }
+}`}3. Bind to the signal in templates
+theme.mode() as a signal — Angular tracks the dependency
+ automatically and re-renders when the mode changes:
+{`
+
+ {{ theme.mode() === "dark" ? "Light mode" : "Dark mode" }}
+ `}API
+{`@Injectable({ providedIn: "root" })
+class GoabThemeService {
+ /** Read-only signal — use in templates: theme.mode() === "dark". */
+ readonly mode: Signal<"light" | "dark">;
+ /** Set theme to a specific mode. */
+ setMode(next: "light" | "dark"): void;
+ /** Flip between light and dark. */
+ toggle(): void;
+}`}Custom styling for dark mode
+data-theme="dark" is active.
+{`.my-card {
+ background-color: var(--goa-color-surface-card);
+}`}:root[data-theme="dark"]:
+{`/* Default (light) value */
+:root {
+ --my-card-background: #f9f9f9;
+}
+
+/* Dark mode value */
+:root[data-theme="dark"] {
+ --my-card-background: #1a1a1a;
+}
+
+/* Use it in your component */
+.my-card {
+ background-color: var(--my-card-background);
+}`}Using design tokens in SCSS
+ +{`$goa-*`}) are inlined at compile time and cannot flip when the
+ theme changes. Reference tokens via {`var(--goa-*)`} wherever a
+ value should respond to theme switching.
+
+tokens.css and uses
+ {`var(--goa-*)`} everywhere — every token automatically participates
+ in theme switching, and there is one syntax to remember.
+{`@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+@import "@abgov/design-tokens/dist/dark-theme.css";`}{`.my-card {
+ background: var(--goa-color-surface-card);
+ font-family: var(--goa-font-family-sans);
+ padding: var(--goa-space-m);
+ transition-duration: var(--goa-motion-duration-medium-2);
+}`}When you need Sass variables
+{`$goa-space-m * 2`}). In that case, import
+ tokens.scss alongside the CSS files and use {`$goa-*`}
+ for compile-time values only — never for colors, surfaces, or anything that
+ should flip with theme.
+{`@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";
+@import "@abgov/design-tokens/dist/dark-theme.css";
+@import "@abgov/design-tokens/dist/tokens.scss";`}{`.my-card {
+ // Theme-responsive — must use var()
+ background: var(--goa-color-surface-card);
+
+ // Compile-time only — Sass arithmetic OK
+ padding: $goa-space-m * 2;
+ border-radius: $goa-border-radius-m;
+}`}Angular UI components
+1. Add dependencies
+npm i @abgov/web-components
+npm i @abgov/angular-components
+npm i @abgov/ui-components-common
+npm i @abgov/design-tokens2. Link ionicons in app/index.html
+head element:
+{`
+`}3. Update src/app/app.module.ts
+src/app/app.module.ts as per the four steps below:
+{`// 1. Import the CUSTOM_ELEMENTS_SCHEMA
+import { CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
+
+// 2. Import the libs
+import "@abgov/web-components";
+import { AngularComponentsModule } from "@abgov/angular-components";
+
+@NgModule({
+ declarations: [AppComponent],
+ imports: [
+ // 3. Add the needed imports
+ BrowserModule,
+ AngularComponentsModule,
+ ],
+ providers: [],
+ bootstrap: [AppComponent],
+ // 4. Add the CUSTOM_ELEMENTS_SCHEMA to the NgModule
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ })
+export class AppModule {}`}4. Add the styles link in src/styles.css
+@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";React UI components
+1. Add dependencies
+npm i @abgov/react-components
+npm i @abgov/web-components
+npm i @abgov/ui-components-common
+npm i @abgov/design-tokens2. Link ionicons in app/index.html
+head element:
+{`
+`}3. Import the web components in src/main.tsx
+import "@abgov/web-components";4. Import the styles in src/index.css
+@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";Web components
+1. Add dependencies
+npm i @abgov/web-components
+npm i @abgov/design-tokens2. Link ionicons in index.html
+head element:
+{`
+`}3. Import the web components into src/main.js
+import "@abgov/web-components";4. Add the styles link in your main CSS file
+src/assets/main.css or wherever your main CSS file is
+ located:
+@import "@abgov/web-components/index.css";
+@import "@abgov/design-tokens/dist/tokens.css";+ The Design System is built on Web Components. Most component functionality lives in the core Web + Components layer. Angular and React wrappers sit on top of that layer to make the components easier + to use in those frameworks. +
++ We use Svelte to author the components that are compiled to custom elements. You can use the Design + System through the core Web Components or through Angular and React wrappers. +
+
++ Web Components + are a set of standard web technologies that allow you to create reusable custom elements. Each component + includes its own structure, styling, and behaviour. This keeps it independent from the rest of your code. +
++ In the Design System, Web Components are the core library. They are framework-agnostic, so teams + can use them in different front-end environments. +
+ +-
+
- Reuse: Build once and use across pages, applications, and frameworks +
- Browser support: Work in modern browsers without additional libraries +
- Maintenance: Modular and self-contained structure simplifies updates +
- Encapsulation: Structure, style, and behaviour remain isolated from other page elements +
- Reliability: Code is not spread across HTML and JS files, thereby avoiding inconsistencies +
- Flexibility: Use inline, import, or compile components as needed +
- Composability: Combine components or integrate them with other components +
+ Svelte is the framework used to generate the + Design System Web Components. Svelte combines JavaScript (logic), HTML (structure), and CSS (style) + within a single file. It compiles these into efficient, reusable components. +
+We use Svelte to:
+-
+
- Build reusable Web Components +
- Keep component logic, structure, and styling together +
- Support integration with multiple front-end frameworks +
+ Angular is a TypeScript-based framework for building + web applications. The Design System supports Angular through Angular wrappers around the core Web Components. +
+ +Angular wrappers are created around the Web Components. These wrappers:
+-
+
- Manage component properties and events +
- Support form binding (Reactive and Template-driven) +
- Allow integration within Angular applications +
The Angular application interacts with the wrapper, which renders the underlying Web Component.
++ React is an open-source JavaScript library used to + build user interfaces from reusable components. +
+ +React wrappers are created around the Web Components. These wrappers:
+-
+
- Manage properties and events +
- Enable integration within React applications +
The React application interacts with the wrapper, which renders the underlying Web Component.
+-
+
- Your service stays aligned with the current GoA standard as more services update and users move between them +
- You get access to new component properties, examples, and templates that reduce build time for common service types +
- Your product remains supported — the legacy design system stops receiving fixes after September 2026 +
+ Most of the update applies automatically. Most of the work will be reviewing what changed in + your product and deciding where design follow-up is needed. These steps help you work through + the process. +
+ ++ The developer-first approach lets you see what actually changed in your product before + committing to design work. +
++ When you run the update first, spacing, typography, and token changes apply automatically. You + can then review the result with your team and focus design and development effort on the screens + that need it most. This avoids redesigning screens based on assumptions about what will change + before you update. +
+ ++ The migration walkthrough steps through four stages — legacy design system, upgrade applied, + layout and styling fixes, and custom component updates — and shows the visual impact on your + interface at each stage. The walkthrough covers both public form and workspace product types. + Review it with your team before you start: it helps designers and developers see where changes + occur, and gives product owners a clearer picture of the scope for planning. +
++ Applying the update to some parts of your product but not others tends to cause the update to + stall. Teams focus on a few components then deprioritize the rest, leaving the product in a + mixed state that becomes harder to resolve over time. Reviewing your updated application + together in step 3 is designed to address this. Reviewing the full update in a branch before + committing gives your team a clear picture of the actual work involved. Use that branch to plan + your migration window — you are not committing to proceeding until you are ready. +
+ ++ Create a dedicated branch for the update. Keeping it separate from your regular development + work lets your team review the changes before merging. +
+git checkout -b ds-migrationUse a branch name that works for your team — this is just an example.
+ ++ Follow the steps in Setup to install the + updated packages. Run your application after installing the updates. Do this before making any + other changes. +
+ ++ Walk through your application with your product team. At this stage, the team will identify + what needs attention and decide what to prioritize. +
+What to look for:
+ +| Area | +What to look for | +
|---|---|
| Spacing and layout | +Screens that feel too tight or unbalanced | +
| Typography | +Headings or body text that look off in size or weight | +
| Dense or data-heavy screens | +These carry the most risk during an update and often need the most follow-up | +
| Custom components | +Anything built outside the design system that needs manual alignment | +
+ Record what you find. A list of screens and issues is enough at this stage. Your designers and + product owner can use that output to plan and prioritize work. +
+ ++ There is no single estimate for how long a migration takes. It varies depending on your + product. The main factors are: +
+ +| Factor | +Impact on migration effort | +
|---|---|
| App size | +More screens means more to test and review after the update | +
| Design system utilization | +Products with more custom code need more manual alignment | +
| Developer familiarity | +Developers with more design system experience move faster through the migration steps | +
+ Use the team review of your updated application in step 3 to build a realistic estimate for + your own product before committing to a timeline. +
+ +-
+
- Bring what you find when reviewing your updated application to drop-in hours to get feedback on what to prioritize +
- If you find a problem with the design system itself, reach out on the support channel rather than working around it +
+ Designers and developers work from shared components and guidance. This reduces rework and misalignment. +
+ +Accessibility is built into both the design and coded components.
+ +Components are tested across devices, browsers, and service contexts.
+ ++ Components align with the broader system to create a cohesive user experience across government services. +
+ +Using existing components saves time. You can focus on work that improves service quality, including:
+-
+
- Usability testing +
- User research +
- Content design +
- Accessibility reviews +
- Design quality checks +
- Low-fidelity prototyping and testing +
This leads to better outcomes for users.
+Follow these steps when designing and building your service.
+ +Start with existing components and patterns. These meet most user needs.
+ +Test your service with users. Identify needs that are not covered by current components.
+ ++ Check what's already available and what's in progress. The team can point you to existing components, + solutions other teams have built, and planned work that may meet your need. +
+ ++ If you still have a gap, design a new solution and test it with users. Move forward only when + testing shows clear user value. +
+ ++ Share your findings with the design system team. Your solution may become part of the design system. +
+ +-
+
- Increases maintenance effort +
- Slows delivery +
- Reduces consistency +
Migration pathways
+Starting a new product
+Compare the pathways
+
+
+
+
+
+
+
+
+| Pathway | +Use it when | +Recommendation | +
|---|---|---|
Standard migration
+-
+
- your product is actively maintained +
- your team can reserve time to migrate by September 2026 +
- you want access to the latest templates, components, tokens, and guidance +
Late migration
+-
+
- a major delivery deadline blocks migration work +
- critical dependencies prevent the upgrade during the standard window +
- capacity or funding makes the standard window unrealistic +
No migration
+What changes after launch
+-
+
- New products should use DS 2.0 +
- Active products should aim to migrate by September 2026 +
- After launch, web components will move to version 2.x. Although this is a major version update, it does not include breaking changes. +
- Angular 4.x and React 6.x receive limited fixes or features from March to September +
- Support for DS 1.0 ends after September 2026 +
- Web components will update to a new major version after September 2026 +
How to choose a pathway
+-
+
- Is this a new product starting after March 2026? +
- Does the product have an active funded team? +
- Can the team schedule migration work before September 2026? +
- Are there delivery deadlines or dependencies that block the standard window? +
- Is the team prepared to accept reduced support and higher maintenance risk if migration is delayed? +
Related guidance
+Bug fixes and security updates are no longer prioritized for these versions.
+ +All new features and enhancements are released only in the current major version.
+ +Existing projects may continue to run. However:
+-
+
- Compatibility with new browsers or operating systems is not guaranteed +
- Compatibility with future framework updates is not guaranteed +
- Issues discovered in these versions will not be resolved +
+ Upgrade to the latest supported version. Refer to the + Developer setup page. +
++ If you need support planning your upgrade, + book time in drop-in hours. +
+QA testing ensures that:
+-
+
- Coded components match the design specifications +
- Components work in both React and Angular implementations +
- Components are responsive across screen sizes +
- Components meet accessibility requirements +
- Mobile behaviour is validated +
- Documentation on the Design System website is accurate +
-
+
- Confirm the rendered component matches design and styling guidelines +
- Confirm configured properties display correctly +
- Confirm the expected event triggers when interacting with the component +
-
+
- Test components on mobile, tablet, and desktop screen sizes +
- Use browser developer tools to simulate devices +
-
+
- Run Lighthouse audits to review accessibility scores +
- Confirm appropriate ARIA (Accessible Rich Internet Applications) roles and labels +
- Test keyboard navigation +
- Test with NVDA screen reader +
-
+
- Test on the latest versions of Chrome, Firefox, Safari, and Edge +
- Use Chrome device mode to simulate mobile environments +
- Confirm consistent appearance and behaviour across browsers +
When a bug is fixed:
+-
+
- Reproduce the issue using the main branch. +
- Verify the fix in the pull request branch. +
- Retest the component across all relevant areas. +
Confirm the issue no longer occurs.
+-
+
- Document updated test results, findings, and screenshots in the pull request comments +
- Log newly discovered issues in GitHub +
Now
+DS 2.0 adoption and satisfaction measurement
+-
+
Create a mechanism to reliably collect and report adoption rate
+ Track upgrade progress against the adoption schedule
+ Capture qualitative signals from teams (developer and designer feedback themes)
+ Capture end-user feedback where available (citizen or worker satisfaction, accessibility and usability feedback)
+
Product acceleration enablement
+-
+
Create resources that show how to quickly prototype with DS 2.0 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
+ Create and publish migration success stories
+
Design system MCP
+-
+
Define the initial MCP scope and supported design system resources
+ Stand up the MCP server and validate the hosting and maintenance approach
+ Test the MCP use in real product workflows and capture gaps to address
+ Document recommended workflows for teams
+
Vue support decision
+-
+
Define what "official Vue support" means
+ Outline the minimum supportable scope
+ Identify implications for documentation, maintenance, testing, and support
+
Next
+Public form and Workspace capability improvements
+-
+
Build the review, revise, resubmit feature
+
Examples and pattern maturity
+-
+
Continue expanding and refining examples
+ Show how components and examples combine into larger contexts and workflows
+
Library packaging and tech stack upgrades
+-
+
Improve how code libraries are bundled together (React, web components, tokens)
+ Update to Svelte 5
+
Vue follow-through
+-
+
Publish Vue support guidance and expectations
+ Implement agreed scope if approved
+ Publish recommended alternatives if Vue support is not pursued
+
Later
+Documentation and communications improvements
+-
+
Add markdown file download to website documentation
+ Articulate accessibility work more clearly (what is covered and how it supports teams)
+
Targeted capacity support for DS 2.0 version updates
+-
+
Focus migration support on late adopters facing systemic barriers to upgrading
+
The reference example is a starting point to expand on, not a rigid template. Adapt it to fit each service's context. +heroImage: /images/examples/my-applications-page.png +demoUrl: https://digital-service-demo-v2.netlify.app/ +tags: + - form + - public + - citizen + - pattern +components: [] +status: published +--- + +
Workspaces should be adapted to fit each service's context and user needs. The reference example is a starting point to expand on, not a rigid template. +heroImage: /thumbnails/workspace-preview.png +demoUrl: https://digital-service-demo-v2.netlify.app/workspace +sourceUrl: https://github.com/GovAlta/goa-workspace-playground +tags: + - workspace + - worker + - service + - case-management + - dashboard + - pattern +components: + - work-side-menu + - table + - badge + - tabs + - container + - accordion + - drawer + - button + - block +status: published +--- + +
+
+
+
+
+
+
+
+
+### Sticky action bar
+
+A scroll-aware header that pins to the top of the content area as the user scrolls. Use it to keep the most important tools visible.
+
+Set the content for each page based on the task:
+
+- On a cases list page, keep tools such as search and key actions visible.
+- On a detail page, keep the case name and key actions visible.
+
+Do not pin everything. Keep only the information and actions people need to continue their work without losing context.
+
+
+
+
+ + Main workspace navigation +
+
+
+
+
++ Contextual case navigation +
+
+
+
+### Push drawer
+
+Use a [push drawer](/components/push-drawer) for focused work that should happen without leaving the current page.
+
+This works well for actions such as:
+
+- approving or denying a record
+- requesting more information
+- completing a short decision form
+- reviewing supporting details while taking action
+
+Use it when users need to keep the main record in view while completing the task.
+
+
+
+---
+
+## Components built for workspace
+
+Workspace patterns are supported by component features designed for denser, more productive interfaces:
+
+- **Compact inputs.** Every input component now has a `compact` variant that reduces height and spacing. This lets you build tighter forms and toolbars without sacrificing usability.
+- **Compact badges and notifications.** [Badges](/components/badge) and [notification banners](/components/notification) also have compact sizing to fit within dense data views and action bars.
+- **Badge variants.** [Badges](/components/badge) now include `strong` and `subtle` emphasis options, giving you control over visual weight depending on context.
+- **Data grid.** The [data grid](/components/data-grid) works with the table component to support accessible, keyboard-navigable data views. Use them together when the user needs to move through records efficiently without relying on a mouse.
+- **Segmented tabs.** A new [tab](/components/tab) variant that works as a segmented toggle for switching between views or modes within a workspace, rather than navigating between pages.
+- **Enhanced filter chips.** [Filter chips](/components/filter-chip) now support secondary text and secondary icons, making them more useful for richer filtering in workspace data views.
+
+---
+
+## Keyboard-accessible data views
+
+Workspace data views use the [data grid](/components/data-grid) to make table and card layouts fully keyboard navigable. Users can use arrow keys to move between cells and rows, making it possible to scan and act on records without a mouse. This is especially important in workspace contexts where staff are processing high volumes of cases and keyboard navigation is significantly faster than clicking. For assistive technology users, screen readers announce cell content and position as the user navigates.
+
+---
+
+## When to use
+
+Use the workspace when your service needs to support regular, task-based work, such as:
+
+- Reviewing and processing submissions
+- Managing case files, applications, or requests
+- Moving between dashboards, lists, and detail views
+- Taking actions such as approve, deny, assign, or request more information
+
+## When not to use
+
+- Citizen-facing services. Use the [public form](/examples/public-form) pattern instead.
+- Content-only pages that do not involve case management.
+- Simple internal tools that do not need structured case processing.
+
+---
+
+## Get started
+
+Use one of the workspace templates as a starting point for your service. Each template includes the sidebar navigation, dashboard, data views, and case detail patterns described above.
+
+
+
+
+---
+
+## Considerations
+
+- The reference demo is a spike. Component customizations have not gone through the production pipeline yet.
+- There should be significant variability within a workspace to meet each service's specific context and user needs.
+- The demo is a starting point to expand on and adapt, not a rigid template to copy exactly.
+- Desktop uses a card container pattern for the main content area. This is removed on mobile for space.
diff --git a/docs/src/data/configurations/accordion.ts b/docs/src/data/configurations/accordion.ts
index 2ce87e20f7..79a8d21b3e 100644
--- a/docs/src/data/configurations/accordion.ts
+++ b/docs/src/data/configurations/accordion.ts
@@ -144,6 +144,78 @@ export const accordionConfigurations: ComponentConfigurations = {
+ View all
+
+
+
+ View all
+
+ {{slot}}
+
+
`;
diff --git a/docs/src/data/configurations/temporary-notification.ts b/docs/src/data/configurations/temporary-notification.ts
index 5c1bc5789e..23b64478c5 100644
--- a/docs/src/data/configurations/temporary-notification.ts
+++ b/docs/src/data/configurations/temporary-notification.ts
@@ -108,29 +108,40 @@ export class SomeOtherComponent {
{
id: "with-progress",
name: "Progress and indeterminate",
- description:
- "Notifications for loading states (note: progress and indeterminate types may have rendering issues)",
+ description: "Notifications for loading states",
code: {
react: `
+
+Dashboard
+Welcome back.
+{sub.name}
{sub.description}
-
-
))}
+
+
+
+
+
+
+ {data.title}
+ {data.summary && } +
- {data.categories.map((cat: string) => (
-
{data.title}
+ {data.description && ( + + )} +{data.title}
{data.description && ( )} -
-
-
+ {/* Each branch is its own statically-imported JSX element so Astro
+ can wire up client:load hydration. Add a new branch when adding
+ a page-scale entry that needs a preview route. */}
+ {slug === "start-page" &&
+
+
+
+
+ Error 401
+
+
+
+
+ Restricted access
+
+ We cannot provide access to this page without valid credentials. Please sign in or
+ contact support at
+
+ cs.licensingsupport@gov.ab.ca
+
+ to request access.
+
+
+
+
+ Go to home page
+
+
+
+
+
+
+
+ Error 404
+
+
+
+
+ Page not found
+
+ The page you're looking for doesn't exist or has been moved.
+
+
+
+
+ Go to home page
+
+
+
+
+
+
+
+ Error 500
+
+
+
+
+ We are experiencing a problem
+
+ We cannot load this page right now. Please try again in a few minutes. We apologize
+ for the inconvenience.
+
+
+
+
+ Go to home page
+
+
+
+
-
-
diff --git a/docs/src/pages/examples/question-page/variants/background-radio/preview.astro b/docs/src/pages/examples/question-page/variants/background-radio/preview.astro
new file mode 100644
index 0000000000..c93a5abb56
--- /dev/null
+++ b/docs/src/pages/examples/question-page/variants/background-radio/preview.astro
@@ -0,0 +1,24 @@
+---
+import PreviewLayout from "../../../../../layouts/PreviewLayout.astro";
+import { GiveBackgroundInformationBeforeAskingAQuestion } from "../../../../../content/examples/question-page/variants/background-radio/react";
+---
+
+
- Digital service
- How workspace and public form connect end-to-end
-
-
+
+
+
+
+
+
+
+
+
+
+
+- However, these tools are not a complete solution. They can produce: -
--
-
- False positives – flagging issues that are not actual problems -
- False negatives – missing real accessibility barriers -
- To ensure your digital product is accessible, combine automated testing with manual testing and apply - human judgment. -
-
- Automated tools may flag elements as non-compliant even when they work correctly for users. For
- example, a tool may report that an input is "missing an id" even though it is correctly associated with a
- label using a valid method, such as wrapping the input inside a <label> element.
-
- Automated tools cannot detect nuanced or context-specific issues. For example, all interactive - elements may be tabbable, but the order jumps around the page. Tools often don't judge whether the - tab order is logical for completing the task. -
- -- Accessibility ensures real people can use a product effectively. Automated tools cannot fully simulate - how users interact with your product. -
--
-
- - Run automated tools to get an initial assessment. - -
- - Manually verify flagged issues and review the element's intent and context. - -
-
- Do additional manual testing for issues automated tools cannot detect:
-
-
-
- Test with a screen reader, such as VoiceOver (macOS) or NVDA (Windows) -
- Test keyboard navigation by checking focus visibility and order -
- -
- Report findings
-
-
-
- Record what you tested, what failed, and how to reproduce it -
- If the issue relates to a design system component, submit it using the design system bug report form -
-
- Automated tools provide helpful insight. Relying only on automation can result in: -
--
-
- Time spent fixing issues that are not real barriers -
- Missed opportunities to address genuine accessibility issues -
- A false sense of compliance without meaningful usability improvements -
- Combine automated and manual testing to identify real barriers. This approach improves accessibility - and overall product quality. -
-- To request a new component or propose an enhancement, follow the - design contribution process. -
-- Experimental components are new or significantly updated. They are available for testing and feedback - before public release. -
- --
-
- Feedback is gathered from selected teams -
- May be unstable or include breaking changes -
- Limited documentation -
- Production components are stable and ready for broader adoption. -
- --
-
- Fully documented, including design guidelines, properties, and examples -
- Meet accessibility and design system standards -
- Optimized for mobile use -
- Actively maintained with updates and bug fixes -
- Publicly available documentation -
- Legacy components are older components maintained primarily to support older implementations. If - possible, transition to production is recommended. -
- --
-
- No active maintenance or updates -
- Critical issues may remain unresolved -
- Recommended alternative clearly identified -
- Marked as "Legacy" in official documentation -
- Start by using existing Design System components and patterns. If a component or pattern does not - meet your needs, follow the contribution process below. -
-- If a required component or example does not exist in production, - contact the Design System team. We will review the request together and determine next steps. -
- -- Book a design system drop-in hours session. -
-Be prepared to:
--
-
- Describe the component or pattern and its purpose -
- Explain your user needs and service goals -
- Share iterations explored with and without the Design System -
A proposed component or pattern must meet the following criteria.
- -Useful
-- Evidence shows it supports multiple teams or services. Provide screenshots or links to demonstrate usage. -
- -Unique
-- It does not duplicate an existing component or pattern. If replacing an existing component, provide - evidence that the new approach improves usability or accessibility. -
- -To be published, the solution must be:
- -Usable
-- Improves clarity, usability, and accessibility for users. Is informed by research and addresses a - validated user need. -
- -Universal
-- Inclusive and accessible. Meets or exceeds accessibility standards. - WCAG 2.2 AA is the minimum requirement. -
- -- If approved, the item is added to the - Design System's backlog. -
-- When development begins, the Design System team will collaborate with you to confirm detailed requirements. -
-- The Design System supports multiple development frameworks through Web Components. Contributing full - components can be complex. Smaller contributions are encouraged. -
- --
-
- Bug fixes -
- Documentation updates -
- Enhancements to existing components -
- Start by contacting the team in the #design-system-support Slack channel. -
-- Select an issue tagged ready-for-contribution from the - backlog. - Confirm which issue you will work on. -
- --
-
- Clone the ui-components repository. -
- Open the repository in your IDE. -
- Create a branch named:
contributions/story-number
- -
- Run the following commands:
-
-npm i -npm run build
- -
- The playgrounds for local testing are located in:
-
-/apps/dev/angular -/apps/dev/react
-
Angular
-npm run dev:watch
-npm run serve:dev:angularReact
-npm run dev:watch
-npm run serve:dev:reactReact wrappers
-/libs/react-components/src/lib
Each folder represents a single component with its associated unit tests and wrapper code.
- -Angular wrappers
-/libs/angular-components/src/lib/components
Each folder represents a single component with its associated unit tests and wrapper code.
- -Web Components
-/libs/web-components/src/components
-
-
- Unit tests as
*.spec.ts
- - Component code as
*.svelte
-
-
-
- Write all unit tests in Svelte. -
- If updating React or Angular wrappers, write unit tests in those respective frameworks. -
-
- Add browser testing using Jest for React wrappers and Svelte components when appropriate.
- These can be found in:
libs/react-components/specs-
- - Manually test components in both React and Angular. -
-
- Create test files that others can use to manually test the PR. These can be created in:
-
-/apps/prs/angular -/apps/prs/react
- - Follow the conventions already used in those files to create your test files. -
A Design System developer will also manually test the pull request.
- -Use the following commit message format:
- -Bug fix
-fix(#storyNumber): short description (7 words max)Feature request
-feat(#storyNumber): short description (7 words max)-
-
- Create a pull request from your branch to the
devbranch.
- - Notify the design system team of the PR. -
In Figma, you can access:
- --
-
- Design tokens -
- Components -
- Patterns -
- The design system library in Figma aligns with coded components used by developers. Start with - design system components for common parts of your service. This helps developers use the matching - coded components and reduces custom work. -
-- Start with the design system. Validate your design through user testing. If usability issues arise, - or the problem cannot be solved within the system, consider creating a custom solution. -
-
- When selecting components, prioritize those with a "goa-" prefix, such as
- goa-input. These components exist in both design and development. Using them reduces
- the need for custom development.
-
Choose shared components whenever possible to maintain consistency and efficiency.
- -Design system components in Figma and code are built using design tokens.
-- Use tokens to communicate design decisions clearly. Developers can reference the same tokens in code. -
-Instead of sharing hex values or pixel adjustments, reference semantic tokens.
-For example:
--
-
- Colour:
--goa-color-info-default
- - Spacing:
--goa-spacing-m
-
Using tokens reduces back-and-forth and keeps design and development aligned.
- -All design system components are available in Figma and in code.
-- These components are designed to meet - WCAG 2.2 accessibility standards. -
-Avoid detaching components. Instead:
--
-
- Use variants -
- Show or hide layers within the component -
- Use #figma for Figma-related issues, including library updates, missing components, - broken instances, or component behaviour in Figma. -
-- Use #design-system-support for design system guidance, component usage questions, - standards, and implementation support. -
-Keep your components up to date. Figma will notify you when library updates are available.
- -Each digital service project folder includes a starter Figma template.
-Use this template to:
--
-
- Organize your design file -
- Support developer handoff -
- Help team members navigate files -
- Helper components are also available. Use them to clearly communicate intent when sharing designs - with developers and other team members. -
-- The Digital Design and Delivery (DDD) Design System has evolved to better support how service teams - design and build digital government services. Design System 2.0 includes an updated design - language, new tokens, refreshed components, and ready-to-use templates. -
-- Use DS 2.0 templates as your starting point. Templates package layout, navigation, spacing, and - example content that you can adapt to your service. Some templates are built for specific service types - (for example, public-facing forms and workspace applications), and others are more general-purpose - starting points you can use across many kinds of pages and flows. -
- -- Use a library swap if - your goal is to convert most of the file to DS 2.0 in one pass. -
--
-
- Make a copy of your file before you start. -
- Expect mixed results. Some screens may need cleanup after the swap. -
Use a manual rebuild if you need more control.
--
-
- Rebuild your highest value screens first. -
- Consider using DS 2.0 templates as a base to speed things up. -
Use this approach in most cases.
--
-
- A developer creates a new branch and completes the upgrade steps. -
- The team runs the upgraded application to see what changed. -
- Designers review the upgraded screens and identify what needs design updates. -
When reviewing the upgraded branch, watch for:
--
-
- Spacing and layout rhythm -
- Typography scale and weight usage -
- Dense or constrained screens (these often have the highest risk during an update) -
Use this approach when you want design work to move ahead of development work.
--
-
- Identify custom elements that support your users' needs. -
- Create an inventory and prioritize items by importance and effort. -
- Redesign the highest priority items using the visual design values in the Styles library. -
-
-
- User-centered: Designed with a clear understanding of users, their goals, tasks, environments, and context of use, using user-centered design methods. -
- Usable: Interfaces will be easy to use, enabling users to find the information they need and complete tasks successfully. -
- Accessible: Digital products will be inclusive, ensuring usability for everyone, regardless of physical or cognitive ability. -
- Trustworthy: Experiences will feel familiar and recognizable as a Government of Alberta product, ensuring users' security and privacy. -
- Modern: Digital experiences will meet present-day user expectations and preferences for aesthetics and interaction. -
- For more details on the process of assessing compliance to each guideline, refer to our - User Experience Guidelines and Design System Checklist. -
-- Usability testing is our preferred method to understand user needs as they relate to each guideline. -
-Suitable usability testing includes:
--
-
- Diverse user group: Real users from different demographic, behavioural backgrounds, and geographical regions within Alberta that will experience the problem or benefit of the product. -
- Inclusive testing: Users with various physical and/or cognitive abilities, literacy levels, and tech savviness. -
- Device variety: A diverse range of devices that reflect users' preferred choice when interacting with government services. -
- Tasks: Activities that cover tasks and service process from end-to-end. -
- Frequent usability testing should be conducted to maintain product usability, effectiveness and - alignment to the user needs as they evolve over time. -
-- For guidance on the process of usability testing, refer to our - Understanding Usability documentation. -
-- The DDD Design System is built using Web Components. Web Components are framework-agnostic. - You can use them with Angular, React, or other front-end frameworks. -
-The Design System includes:
--
-
- Tokens -
- Components -
- Examples -
- Templates -
- Designers use equivalent resources in Figma. When they design with Design System components, you - can build with the matching coded components. This reduces custom development and rework. -
-- All Design System components are designed and built to meet - WCAG 2.2 accessibility standards. -
-- Access the tokens as an - NPM package. -
-- Import the SCSS or CSS file into your project. Replace hard-coded values with Design System token variables. -
-- Designers reference the same tokens in their tools. This keeps design and development aligned during handoff. -
- -Components are reusable user interface elements built for use across services.
-You can:
--
-
- Use components individually -
- Combine them into patterns -
- Apply them in different contexts -
Components are available:
--
-
- As Web Components -
- As Angular wrappers -
- As React wrappers -
- Refer to the Design System technologies documentation - for implementation details. -
- -- Examples are multiple components assembled in realistic service contexts. They help you understand - how to apply Design System guidance in a working interface. -
-You can use examples to:
--
-
- Understand how components work together -
- Use them as a starting point for building parts of your interface -
- Use proven approaches to meet user needs -
- Examples help you build with more consistency and less rework. Use them to guide implementation, - then adjust them to meet the needs of your product. -
- -- Templates are opinionated starting points for common service types. They package layout, navigation, - spacing, and example content so you can start with a proven structure instead of building from scratch. -
-You can use templates to:
--
-
- Start a new product with a proven structure -
- Learn how components work together in a real layout -
- Adapt a proven starting point to fit your service needs -
- Templates help teams move faster, reduce rework, and stay aligned with Design System guidance. -
-- We support the latest version of each browser listed on this page. Support applies to the browser and - operating system combinations shown in the table below. On mobile, support is limited to the browser - and operating system combinations listed for Android and iOS. -
- -| Browser | -Windows | -Mac OS | -Android | -iOS | -
|---|---|---|---|---|
| Google Chrome | -Yes | -Yes | -Yes | -Yes | -
| Microsoft Edge | -Yes | -Yes | -- | - |
| Mozilla Firefox | -Yes | -Yes | -Yes | -- |
| Apple Safari | -N/A | -Yes | -N/A | -Yes | -
-
-
- Android OS: 10+ -
- iOS: 15+ -
- Use supported browsers and operating system versions when developing and testing services. If you - encounter a browser-specific issue, follow the - Verify a bug process. -
-- These steps help confirm whether the issue is caused by the Design System, your product setup, or - custom code. This process applies to Angular and React implementations. -
- -Confirm you are using the latest version of:
--
-
- Web Components -
- Angular or React -
- If you are not using the latest version, upgrade and retest. If the issue remains, continue to the next step. -
- -Use the official Angular or React product templates to isolate the issue.
- -This helps determine whether the issue exists outside your project configuration.
- -Create a minimal test environment.
--
-
- Use only the code required for the example to function -
- Include only the component experiencing the issue -
- Remove unrelated dependencies or custom logic -
Confirm whether the issue can be replicated.
- -If you can reproduce the issue:
--
-
- Share the template application link in the #design-system-support Slack channel -
- Provide a link to your repository so the team can review and replicate the issue -
- Following these steps will help to ensure efficient investigation and quicker resolution of - design system component issues. -
-Angular UI components
-1. Add dependencies
-npm i @abgov/web-components
-npm i @abgov/angular-components
-npm i @abgov/ui-components-common
-npm i @abgov/design-tokens2. Link ionicons in app/index.html
-head element:
- <script type="module" src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.esm.js"></script>
-<script nomodule src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.js"></script>3. Update src/app/app.module.ts
-src/app/app.module.ts as per the four steps below:
- // 1. Import the CUSTOM_ELEMENTS_SCHEMA
-import { CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
-
-// 2. Import the libs
-import "@abgov/web-components";
-import { AngularComponentsModule } from "@abgov/angular-components";
-
-@NgModule({
- declarations: [AppComponent],
- imports: [
- // 3. Add the needed imports
- BrowserModule,
- AngularComponentsModule,
- ],
- providers: [],
- bootstrap: [AppComponent],
- // 4. Add the CUSTOM_ELEMENTS_SCHEMA to the NgModule
- schemas: [CUSTOM_ELEMENTS_SCHEMA],
- })
-export class AppModule {}4. Add the styles link in src/styles.css
-@import "@abgov/web-components/index.css";
-@import "@abgov/design-tokens/dist/tokens.css";React UI components
-1. Add dependencies
-npm i @abgov/react-components
-npm i @abgov/web-components
-npm i @abgov/ui-components-common
-npm i @abgov/design-tokens2. Link ionicons in app/index.html
-head element:
- <script type="module" src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.esm.js"></script>
-<script nomodule src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.js"></script>3. Import the web components in src/main.tsx
-import "@abgov/web-components";4. Import the styles in src/index.css
-@import "@abgov/web-components/index.css";
-@import "@abgov/design-tokens/dist/tokens.css";Web components
-1. Add dependencies
-npm i @abgov/web-components
-npm i @abgov/design-tokens2. Link ionicons in index.html
-head element:
- <script type="module" src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.esm.js"></script>
-<script nomodule src="https://cdn.jsdelivr.net/npm/ionicons@latest/dist/ionicons/ionicons.js"></script>3. Import the web components into src/main.js
-import "@abgov/web-components";4. Add the styles link in your main CSS file
-src/assets/main.css or wherever your main CSS file is
- located:
- @import "@abgov/web-components/index.css";
-@import "@abgov/design-tokens/dist/tokens.css";- The Design System is built on Web Components. Most component functionality lives in the core Web - Components layer. Angular and React wrappers sit on top of that layer to make the components easier - to use in those frameworks. -
-- We use Svelte to author the components that are compiled to custom elements. You can use the Design - System through the core Web Components or through Angular and React wrappers. -
-
- - Web Components - are a set of standard web technologies that allow you to create reusable custom elements. Each component - includes its own structure, styling, and behaviour. This keeps it independent from the rest of your code. -
-- In the Design System, Web Components are the core library. They are framework-agnostic, so teams - can use them in different front-end environments. -
- --
-
- Reuse: Build once and use across pages, applications, and frameworks -
- Browser support: Work in modern browsers without additional libraries -
- Maintenance: Modular and self-contained structure simplifies updates -
- Encapsulation: Structure, style, and behaviour remain isolated from other page elements -
- Reliability: Code is not spread across HTML and JS files, thereby avoiding inconsistencies -
- Flexibility: Use inline, import, or compile components as needed -
- Composability: Combine components or integrate them with other components -
- Svelte is the framework used to generate the - Design System Web Components. Svelte combines JavaScript (logic), HTML (structure), and CSS (style) - within a single file. It compiles these into efficient, reusable components. -
-We use Svelte to:
--
-
- Build reusable Web Components -
- Keep component logic, structure, and styling together -
- Support integration with multiple front-end frameworks -
- Angular is a TypeScript-based framework for building - web applications. The Design System supports Angular through Angular wrappers around the core Web Components. -
- -Angular wrappers are created around the Web Components. These wrappers:
--
-
- Manage component properties and events -
- Support form binding (Reactive and Template-driven) -
- Allow integration within Angular applications -
The Angular application interacts with the wrapper, which renders the underlying Web Component.
-- React is an open-source JavaScript library used to - build user interfaces from reusable components. -
- -React wrappers are created around the Web Components. These wrappers:
--
-
- Manage properties and events -
- Enable integration within React applications -
The React application interacts with the wrapper, which renders the underlying Web Component.
-- Designers and developers work from shared components and guidance. This reduces rework and misalignment. -
- -Accessibility is built into both the design and coded components.
- -Components are tested across devices, browsers, and service contexts.
- -- Components align with the broader system to create a cohesive user experience across government services. -
- -Using existing components saves time. You can focus on work that improves service quality, including:
--
-
- Usability testing -
- User research -
- Content design -
- Accessibility reviews -
- Design quality checks -
- Low-fidelity prototyping and testing -
This leads to better outcomes for users.
-Follow these steps when designing and building your service.
- -Start with existing components and patterns. These meet most user needs.
- -Test your service with users. Identify needs that are not covered by current components.
- -- Check what's already available and what's in progress. The team can point you to existing components, - solutions other teams have built, and planned work that may meet your need. -
- -- If you still have a gap, design a new solution and test it with users. Move forward only when - testing shows clear user value. -
- -- Share your findings with the design system team. Your solution may become part of the design system. -
- --
-
- Increases maintenance effort -
- Slows delivery -
- Reduces consistency -
Migration pathways
-Starting a new product
-Compare the pathways
-
-
-
-
-
-
-
-
- | Pathway | -Use it when | -Recommendation | -
|---|---|---|
|
- |
-
- |
-
- |
-
|
- |
-
- |
-
- |
-
|
- |
-
- |
-
- |
-
- Standard migration
-
- -
-
- your product is actively maintained -
- your team can reserve time to migrate by September 2026 -
- you want access to the latest templates, components, tokens, and guidance -
Late migration
--
-
- a major delivery deadline blocks migration work -
- critical dependencies prevent the upgrade during the standard window -
- capacity or funding makes the standard window unrealistic -
No migration
-What changes after launch
--
-
- New products should use DS 2.0 -
- Active products should aim to migrate by September 2026 -
- - After launch, web components will move to version 2.x. Although this is a major - version update, it does not include breaking changes. - -
- - Angular 4.x and React 6.x receive limited fixes or features from March to - September - -
- Support for DS 1.0 ends after September 2026 -
- Web components will update to a new major version after September 2026 -
How to choose a pathway
--
-
- Is this a new product starting after March 2026? -
- Does the product have an active funded team? -
- Can the team schedule migration work before September 2026? -
- - Are there delivery deadlines or dependencies that block the standard window? - -
- - Is the team prepared to accept reduced support and higher maintenance risk if - migration is delayed? - -
Related guidance
-Bug fixes and security updates are no longer prioritized for these versions.
- -All new features and enhancements are released only in the current major version.
- -Existing projects may continue to run. However:
--
-
- Compatibility with new browsers or operating systems is not guaranteed -
- Compatibility with future framework updates is not guaranteed -
- Issues discovered in these versions will not be resolved -
- Upgrade to the latest supported version. Refer to the - version update guide. -
-- If you need support planning your upgrade, - book time in drop-in hours. -
-QA testing ensures that:
--
-
- Coded components match the design specifications -
- Components work in both React and Angular implementations -
- Components are responsive across screen sizes -
- Components meet accessibility requirements -
- Mobile behaviour is validated -
- Documentation on the Design System website is accurate -
-
-
- Confirm the rendered component matches design and styling guidelines -
- Confirm configured properties display correctly -
- Confirm the expected event triggers when interacting with the component -
-
-
- Test components on mobile, tablet, and desktop screen sizes -
- Use browser developer tools to simulate devices -
-
-
- Run Lighthouse audits to review accessibility scores -
- Confirm appropriate ARIA (Accessible Rich Internet Applications) roles and labels -
- Test keyboard navigation -
- Test with NVDA screen reader -
-
-
- Test on the latest versions of Chrome, Firefox, Safari, and Edge -
- Use Chrome device mode to simulate mobile environments -
- Confirm consistent appearance and behaviour across browsers -
When a bug is fixed:
--
-
- Reproduce the issue using the main branch. -
- Verify the fix in the pull request branch. -
- Retest the component across all relevant areas. -
Confirm the issue no longer occurs.
--
-
- Document updated test results, findings, and screenshots in the pull request comments -
- Log newly discovered issues in GitHub -
Now
-DS 2.0 adoption and satisfaction measurement
--
-
-
-
Create a mechanism to reliably collect and report adoption rate -
- -
-
Track upgrade progress against the adoption schedule -
- -
-
Capture qualitative signals from teams (developer and designer feedback themes) -
- -
-
Capture end-user feedback where available (citizen or worker satisfaction, - accessibility and usability feedback) -
-
Product acceleration enablement
--
-
-
-
Create resources that show how to quickly prototype with DS 2.0 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 -
- -
-
Create and publish migration success stories -
-
Design system MCP
--
-
-
-
Define the initial MCP scope and supported design system resources -
- -
-
Stand up the MCP server and validate the hosting and maintenance approach -
- -
-
Test the MCP use in real product workflows and capture gaps to address -
- -
-
Document recommended workflows for teams -
-
Vue support decision
--
-
-
-
Define what "official Vue support" means -
- -
-
Outline the minimum supportable scope -
- -
-
Identify implications for documentation, maintenance, testing, and support -
-
Next
-Public form and Workspace capability improvements
--
-
-
-
Build the review, revise, resubmit feature -
-
Examples and pattern maturity
--
-
-
-
Continue expanding and refining examples -
- -
-
Show how components and examples combine into larger contexts and workflows -
-
Library packaging and tech stack upgrades
--
-
-
-
Improve how code libraries are bundled together (React, web components, tokens) -
- -
-
Update to Svelte 5 -
-
Vue follow-through
--
-
-
-
Publish Vue support guidance and expectations -
- -
-
Implement agreed scope if approved -
- -
-
Publish recommended alternatives if Vue support is not pursued -
-
Later
-Documentation and communications improvements
--
-
-
-
Add markdown file download to website documentation -
- -
-
Articulate accessibility work more clearly (what is covered and how it supports - teams) -
-
Targeted capacity support for DS 2.0 version updates
--
-
-
-
Focus migration support on late adopters facing systemic barriers to upgrading -
-
Research tools
-- Conduct research with your users to validate your design decisions. Test your assumptions, gather insights, and ensure your service meets real user needs. -
-
-
-
Understand your service
@@ -103,24 +83,44 @@ import CardLite from '../components/CardLite.astro';
Research tools
++ Conduct research with your users to validate your design decisions. Test your assumptions, gather insights, and ensure your service meets real user needs. +
+
+
@@ -138,6 +138,12 @@ import CardLite from '../components/CardLite.astro';
padding: var(--goa-space-2xl) var(--goa-space-2xl);
}
+ :root[data-theme="dark"] .ds-hero-banner {
+ background: transparent url('/images/home/hero-banner-gradient-dark.svg')
+ center center no-repeat;
+ background-size: cover;
+ }
+
.hero-content {
display: flex;
gap: var(--goa-space-2xl);
@@ -204,6 +210,14 @@ import CardLite from '../components/CardLite.astro';
outline-offset: 2px;
}
+ :root[data-theme="dark"] .hero-search-trigger {
+ background: rgba(38, 38, 38, 0.85);
+ }
+
+ :root[data-theme="dark"] .hero-search-trigger:hover {
+ background: rgba(38, 38, 38, 0.95);
+ }
+
.hero-search-icon {
flex-shrink: 0;
color: var(--goa-color-text-secondary);
@@ -311,6 +325,24 @@ import CardLite from '../components/CardLite.astro';
grid-template-columns: repeat(3, 1fr);
}
+ /* "Understand your service" thumbnails are smaller than card width;
+ constrain to a uniform 240×112 frame, illustration left-aligned within. */
+ .card-grid.three-col :global(.card-image) {
+ width: 100%;
+ max-width: 240px;
+ aspect-ratio: 240 / 112;
+ display: flex;
+ align-items: center;
+ justify-content: flex-start;
+ }
+
+ .card-grid.three-col :global(.card-image img) {
+ max-width: 100%;
+ max-height: 100%;
+ width: auto;
+ height: auto;
+ }
+
/* Tablet breakpoint - 1199px */
@media screen and (max-width: 1199px) {
.ds-hero-banner {
diff --git a/docs/src/pages/search.astro b/docs/src/pages/search.astro
index 8e52c4b6c2..6ec5447dd2 100644
--- a/docs/src/pages/search.astro
+++ b/docs/src/pages/search.astro
@@ -12,11 +12,13 @@ import { SiteNav } from '../components/SiteNav';
import { MobileHeader } from '../components/MobileHeader';
import { SearchPage } from '../components/search';
import { getNavCategories } from '../lib/nav-categories';
+import { getGetStartedNav } from '../lib/get-started-nav';
// Get query from URL parameters
const url = new URL(Astro.request.url);
const initialQuery = url.searchParams.get('q') || '';
const navCategories = await getNavCategories();
+const getStartedNav = await getGetStartedNav();
---
+
+ }
@@ -70,7 +70,8 @@ export class GoabDrawer implements OnInit {
}, 0);
}
- _onClose() {
+ _onClose(event: Event) {
+ if (event.target !== event.currentTarget) return;
this.onClose.emit();
}
diff --git a/libs/angular-components/src/lib/components/dropdown/dropdown.ts b/libs/angular-components/src/lib/components/dropdown/dropdown.ts
index 92f6a25625..3306dcc334 100644
--- a/libs/angular-components/src/lib/components/dropdown/dropdown.ts
+++ b/libs/angular-components/src/lib/components/dropdown/dropdown.ts
@@ -83,7 +83,7 @@ export class GoabDropdown extends GoabControlValueAccessor implements OnInit {
@Input() leadingIcon?: GoabIconType;
/** Maximum height of the dropdown menu. Non-native only. */
@Input() maxHeight?: string;
- /** When true, allows multiple items to be selected. Not currently exposed. */
+ /** When true, allows multiple items to be selected. @internal */
@Input({ transform: booleanAttribute }) multiselect?: boolean;
/** When true will render the native select HTML element. */
@Input({ transform: booleanAttribute }) native?: boolean;
diff --git a/libs/angular-components/src/lib/components/header-menu/header-menu.ts b/libs/angular-components/src/lib/components/header-menu/header-menu.ts
index a89deb5324..d0e00a86db 100644
--- a/libs/angular-components/src/lib/components/header-menu/header-menu.ts
+++ b/libs/angular-components/src/lib/components/header-menu/header-menu.ts
@@ -9,8 +9,6 @@ import {
inject,
} from "@angular/core";
-import { GoabBaseComponent } from "../base.component";
-
@Component({
standalone: true,
selector: "goab-app-header-menu",
@@ -26,13 +24,15 @@ import { GoabBaseComponent } from "../base.component";
schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
/** Menu items within the app header. */
-export class GoabAppHeaderMenu extends GoabBaseComponent implements OnInit {
+export class GoabAppHeaderMenu implements OnInit {
private cdr = inject(ChangeDetectorRef);
/** Icon displayed before the heading text. */
@Input() leadingIcon?: GoabIconType;
/** The menu heading text displayed as the dropdown trigger. */
@Input() heading?: string;
+ /** Sets a data-testid attribute for automated testing. */
+ @Input() testId?: string;
/** Sets the slot name for the component. */
@Input() slotName?: string;
diff --git a/libs/angular-components/src/lib/components/header/header.ts b/libs/angular-components/src/lib/components/header/header.ts
index a04e04b9d4..94f9bfae93 100644
--- a/libs/angular-components/src/lib/components/header/header.ts
+++ b/libs/angular-components/src/lib/components/header/header.ts
@@ -10,8 +10,6 @@ import {
inject,
} from "@angular/core";
-import { GoabBaseComponent } from "../base.component";
-
@Component({
standalone: true,
selector: "goab-app-header",
@@ -33,7 +31,7 @@ import { GoabBaseComponent } from "../base.component";
schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
/** Provide structure to help users find their way around the service. */
-export class GoabAppHeader extends GoabBaseComponent implements OnInit {
+export class GoabAppHeader implements OnInit {
private cdr = inject(ChangeDetectorRef);
/** Sets the URL to link from the alberta.ca logo. A full url is required. */
@@ -46,6 +44,8 @@ export class GoabAppHeader extends GoabBaseComponent implements OnInit {
@Input() maxContentWidth?: string;
/** Sets the breakpoint in px for the full menu to display. */
@Input({ transform: numberAttribute }) fullMenuBreakpoint?: number;
+ /** Sets a data-testid attribute for automated testing. */
+ @Input() testId?: string;
isReady = false;
version = "2";
diff --git a/libs/angular-components/src/lib/components/hero-banner/hero-banner.ts b/libs/angular-components/src/lib/components/hero-banner/hero-banner.ts
index c4d6dcb83f..92ce6d5abc 100644
--- a/libs/angular-components/src/lib/components/hero-banner/hero-banner.ts
+++ b/libs/angular-components/src/lib/components/hero-banner/hero-banner.ts
@@ -52,8 +52,8 @@ export class GoabHeroBanner implements OnInit {
@Input() backgroundColor?: string;
/** Text color within the hero banner. */
@Input() textColor?: string;
- /** Angular template reference for the actions slot content. */
- @Input() actions!: TemplateRef;
+ /** Content rendered in the actions slot. */
+ @Input() actions?: TemplateRef;
ngOnInit(): void {
setTimeout(() => {
diff --git a/libs/angular-components/src/lib/components/microsite-header/microsite-header.ts b/libs/angular-components/src/lib/components/microsite-header/microsite-header.ts
index ce0dbc6f73..5fe6393368 100644
--- a/libs/angular-components/src/lib/components/microsite-header/microsite-header.ts
+++ b/libs/angular-components/src/lib/components/microsite-header/microsite-header.ts
@@ -65,7 +65,7 @@ export class GoabMicrositeHeader implements OnInit {
}
/** Emits when the feedback link is clicked. */
- @Output() onFeedbackClick = new EventEmitter();
+ @Output() onFeedbackClick = new EventEmitter();
getVersionAsString(): string {
return typeof this.version === "string" ? this.version : "";
diff --git a/libs/angular-components/src/lib/components/modal/modal.ts b/libs/angular-components/src/lib/components/modal/modal.ts
index 6b5906f782..0562ad7391 100644
--- a/libs/angular-components/src/lib/components/modal/modal.ts
+++ b/libs/angular-components/src/lib/components/modal/modal.ts
@@ -32,7 +32,7 @@ import { NgTemplateOutlet } from "@angular/common";
[attr.closable]="closable"
[attr.transition]="transition"
[attr.heading]="getHeadingAsString()"
- (_close)="_onClose()"
+ (_close)="_onClose($event)"
>
@if (this.heading !== "" && getHeadingAsTemplate() !== null) {
@@ -91,7 +91,7 @@ export class GoabModal implements OnInit {
@Input() actions!: TemplateRef;
/** Emits when the modal is closed. */
- @Output() onClose = new EventEmitter();
+ @Output() onClose = new EventEmitter();
getHeadingAsString(): string {
return this.heading instanceof TemplateRef ? "" : this.heading;
@@ -102,7 +102,8 @@ export class GoabModal implements OnInit {
return this.heading instanceof TemplateRef ? this.heading : null;
}
- _onClose() {
+ _onClose(event: Event) {
+ if (event.target !== event.currentTarget) return;
this.onClose.emit();
}
}
diff --git a/libs/angular-components/src/lib/components/push-drawer/push-drawer.ts b/libs/angular-components/src/lib/components/push-drawer/push-drawer.ts
index 1adaeb09cf..db5ab60a4f 100644
--- a/libs/angular-components/src/lib/components/push-drawer/push-drawer.ts
+++ b/libs/angular-components/src/lib/components/push-drawer/push-drawer.ts
@@ -23,7 +23,7 @@ import {
[attr.testid]="testId"
[attr.width]="width"
[attr.version]="version"
- (_close)="_onClose()"
+ (_close)="_onClose($event)"
>
;
+ /** Template reference for the trailing content slot. */
+ @Input() trailingContent!: TemplateRef;
isReady = false;
diff --git a/libs/angular-components/src/lib/components/work-side-menu/work-side-menu.ts b/libs/angular-components/src/lib/components/work-side-menu/work-side-menu.ts
index ac1bce228e..7218e747ea 100644
--- a/libs/angular-components/src/lib/components/work-side-menu/work-side-menu.ts
+++ b/libs/angular-components/src/lib/components/work-side-menu/work-side-menu.ts
@@ -64,7 +64,7 @@ export class GoabWorkSideMenu implements OnInit {
/** Template reference for the account slot content. */
@Input() accountContent!: TemplateRef;
/** Emits when the side menu is toggled open or closed. */
- @Output() onToggle = new EventEmitter();
+ @Output() onToggle = new EventEmitter();
/** Emits when a navigation link is clicked. Emits the URL as a string. */
@Output() onNavigate = new EventEmitter();
diff --git a/libs/angular-components/src/lib/theme/theme.service.spec.ts b/libs/angular-components/src/lib/theme/theme.service.spec.ts
new file mode 100644
index 0000000000..f64c406512
--- /dev/null
+++ b/libs/angular-components/src/lib/theme/theme.service.spec.ts
@@ -0,0 +1,202 @@
+import { ApplicationRef } from "@angular/core";
+import { TestBed } from "@angular/core/testing";
+import { GoabThemeService } from "./theme.service";
+
+const STORAGE_KEY = "goab-theme";
+const ATTRIBUTE = "data-theme";
+
+function mockMatchMedia(prefersDark: boolean) {
+ Object.defineProperty(window, "matchMedia", {
+ writable: true,
+ value: jest.fn().mockImplementation((query: string) => ({
+ matches: query === "(prefers-color-scheme: dark)" ? prefersDark : false,
+ media: query,
+ onchange: null,
+ addListener: jest.fn(),
+ removeListener: jest.fn(),
+ addEventListener: jest.fn(),
+ removeEventListener: jest.fn(),
+ dispatchEvent: jest.fn(),
+ })),
+ });
+}
+
+function flushEffects() {
+ TestBed.inject(ApplicationRef).tick();
+}
+
+describe("GoabThemeService", () => {
+ beforeEach(() => {
+ localStorage.clear();
+ document.documentElement.removeAttribute(ATTRIBUTE);
+ mockMatchMedia(false);
+ TestBed.resetTestingModule();
+ TestBed.configureTestingModule({});
+ });
+
+ describe("initial mode resolution", () => {
+ it("defaults to 'light' when localStorage, attribute, and system preference are absent", () => {
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+ });
+
+ it("reads 'dark' from localStorage when present", () => {
+ localStorage.setItem(STORAGE_KEY, "dark");
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("reads 'light' from localStorage when present", () => {
+ localStorage.setItem(STORAGE_KEY, "light");
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+ });
+
+ it("ignores invalid localStorage values and falls through to next source", () => {
+ localStorage.setItem(STORAGE_KEY, "purple");
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("reads 'dark' from data-theme attribute when localStorage is empty", () => {
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("reads 'dark' from prefers-color-scheme when localStorage and attribute are absent", () => {
+ mockMatchMedia(true);
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("prefers localStorage over data-theme attribute", () => {
+ localStorage.setItem(STORAGE_KEY, "light");
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+ });
+
+ it("prefers data-theme attribute over prefers-color-scheme", () => {
+ mockMatchMedia(true);
+ document.documentElement.setAttribute(ATTRIBUTE, "light");
+
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+ });
+ });
+
+ describe("setMode", () => {
+ it("updates the mode signal", () => {
+ const service = TestBed.inject(GoabThemeService);
+ service.setMode("dark");
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("syncs the data-theme attribute on ", () => {
+ const service = TestBed.inject(GoabThemeService);
+ service.setMode("dark");
+ flushEffects();
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+
+ service.setMode("light");
+ flushEffects();
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("light");
+ });
+
+ it("persists the mode to localStorage", () => {
+ const service = TestBed.inject(GoabThemeService);
+ service.setMode("dark");
+ flushEffects();
+ expect(localStorage.getItem(STORAGE_KEY)).toBe("dark");
+ });
+ });
+
+ describe("toggle", () => {
+ it("flips light to dark", () => {
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("light");
+
+ service.toggle();
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("flips dark to light", () => {
+ localStorage.setItem(STORAGE_KEY, "dark");
+ const service = TestBed.inject(GoabThemeService);
+ expect(service.mode()).toBe("dark");
+
+ service.toggle();
+ expect(service.mode()).toBe("light");
+ });
+
+ it("flips back and forth across multiple calls", () => {
+ const service = TestBed.inject(GoabThemeService);
+
+ service.toggle();
+ expect(service.mode()).toBe("dark");
+
+ service.toggle();
+ expect(service.mode()).toBe("light");
+
+ service.toggle();
+ expect(service.mode()).toBe("dark");
+ });
+
+ it("syncs attribute and localStorage on toggle", () => {
+ const service = TestBed.inject(GoabThemeService);
+
+ service.toggle();
+ flushEffects();
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+ expect(localStorage.getItem(STORAGE_KEY)).toBe("dark");
+ });
+ });
+
+ describe("localStorage failures", () => {
+ it("does not throw when localStorage.setItem is blocked", () => {
+ const setItemSpy = jest
+ .spyOn(Storage.prototype, "setItem")
+ .mockImplementation(() => {
+ throw new Error("QuotaExceededError");
+ });
+
+ const service = TestBed.inject(GoabThemeService);
+
+ expect(() => {
+ service.setMode("dark");
+ flushEffects();
+ }).not.toThrow();
+
+ // Attribute should still update even if storage fails
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+
+ setItemSpy.mockRestore();
+ });
+
+ it("does not throw when localStorage.getItem is blocked at construction", () => {
+ const getItemSpy = jest
+ .spyOn(Storage.prototype, "getItem")
+ .mockImplementation(() => {
+ throw new Error("SecurityError");
+ });
+
+ expect(() => TestBed.inject(GoabThemeService)).not.toThrow();
+
+ getItemSpy.mockRestore();
+ });
+ });
+
+ describe("readonly mode signal", () => {
+ it("exposes mode as a read-only signal (no .set/.update)", () => {
+ const service = TestBed.inject(GoabThemeService);
+ const modeSignal = service.mode as unknown as Record;
+
+ expect(typeof modeSignal["set"]).toBe("undefined");
+ expect(typeof modeSignal["update"]).toBe("undefined");
+ });
+ });
+});
diff --git a/libs/angular-components/src/lib/theme/theme.service.ts b/libs/angular-components/src/lib/theme/theme.service.ts
new file mode 100644
index 0000000000..efe89b44a5
--- /dev/null
+++ b/libs/angular-components/src/lib/theme/theme.service.ts
@@ -0,0 +1,52 @@
+import { Injectable, effect, signal, type Signal } from "@angular/core";
+import type { GoabThemeMode } from "@abgov/ui-components-common";
+
+const STORAGE_KEY = "goab-theme";
+const ATTRIBUTE = "data-theme";
+
+@Injectable({ providedIn: "root" })
+export class GoabThemeService {
+ private readonly _mode = signal(this.readInitialMode());
+
+ /** Read-only signal for consumers. Use in templates: theme.mode() === 'dark'. */
+ readonly mode: Signal = this._mode.asReadonly();
+
+ constructor() {
+ effect(() => {
+ const current = this._mode();
+ if (typeof document === "undefined") return;
+ document.documentElement.setAttribute(ATTRIBUTE, current);
+ try {
+ window.localStorage.setItem(STORAGE_KEY, current);
+ } catch {
+ // localStorage blocked: fail silently.
+ }
+ });
+ }
+
+ setMode(next: GoabThemeMode): void {
+ this._mode.set(next);
+ }
+
+ toggle(): void {
+ this._mode.update((prev) => (prev === "light" ? "dark" : "light"));
+ }
+
+ private readInitialMode(): GoabThemeMode {
+ if (typeof window === "undefined") return "light";
+
+ try {
+ const stored = window.localStorage.getItem(STORAGE_KEY);
+ if (stored === "light" || stored === "dark") return stored;
+ } catch {
+ // fall through
+ }
+
+ const fromAttribute = document.documentElement.getAttribute(ATTRIBUTE);
+ if (fromAttribute === "light" || fromAttribute === "dark") return fromAttribute;
+
+ if (window.matchMedia("(prefers-color-scheme: dark)").matches) return "dark";
+
+ return "light";
+ }
+}
diff --git a/libs/common/src/lib/common.ts b/libs/common/src/lib/common.ts
index 6e104f1ad8..942333f31d 100644
--- a/libs/common/src/lib/common.ts
+++ b/libs/common/src/lib/common.ts
@@ -265,6 +265,7 @@ export type GoabButtonGroupGap = "relaxed" | "compact";
// Accordion
export type GoabAccordionHeadingSize = "small" | "medium";
export type GoabAccordionIconPosition = "left" | "right";
+export type GoabAccordionHeadingType = "normal" | "filled";
// Tooltip
@@ -1337,6 +1338,7 @@ export type GoabDrawerSizeUnit = "px" | "rem" | "ch" | "vh" | "vw" | "%";
export type GoabDrawerSize = `${number}${GoabDrawerSizeUnit}` | undefined;
// Work side menu
+/** @deprecated Use trailingContent with explicit badge components for indicator styling. */
export type GoabWorkSideMenuItemType = "normal" | "emergency" | "success";
// Work side notification
@@ -1378,3 +1380,5 @@ export type GoabRadioGroupSize = "default" | "compact";
export type GoabInputSize = "default" | "compact";
export type GoabTextAreaSize = "default" | "compact";
+
+export type GoabThemeMode = "light" | "dark";
diff --git a/libs/react-components/specs/accordion.browser.spec.tsx b/libs/react-components/specs/accordion.browser.spec.tsx
index a76495971b..135df672be 100644
--- a/libs/react-components/specs/accordion.browser.spec.tsx
+++ b/libs/react-components/specs/accordion.browser.spec.tsx
@@ -119,6 +119,59 @@ describe("Accordion", () => {
});
});
+ it("should not expand the accordion when a button in the actions slot is clicked", async () => {
+ const accordionChangeSpy = vi.fn();
+
+ const Component = () => {
+ return (
+ Action
+ }
+ onChange={accordionChangeSpy}
+ >
+ Accordion content
+
+ );
+ };
+
+ const result = render(Action
+ }
+ >
+ Accordion content
+
+ );
+ };
+
+ const result = render(
+ Open parent
+
+ }
+ >
+
+ Open child
+
+ }
+ >
+
+ Close child
+
+
+
+ );
+ };
+
+ const result = render(Action}>
+ Content
+ ,
+ );
+ const el = baseElement.querySelector("goa-accordion");
+ const actions = el?.querySelector("[slot='actions']");
+ expect(actions).toBeTruthy();
+ });
+
it("should pass data-grid attributes", () => {
const { baseElement } = render(
-
+
Content
,
);
diff --git a/libs/react-components/src/lib/accordion/accordion.tsx b/libs/react-components/src/lib/accordion/accordion.tsx
index a577a18a35..986ace64b5 100644
--- a/libs/react-components/src/lib/accordion/accordion.tsx
+++ b/libs/react-components/src/lib/accordion/accordion.tsx
@@ -3,6 +3,7 @@ import { ReactNode, useEffect, useRef, type JSX } from "react";
import type {
GoabAccordionHeadingSize,
GoabAccordionIconPosition,
+ GoabAccordionHeadingType,
Margins,
DataAttributes,
} from "@abgov/ui-components-common";
@@ -17,6 +18,7 @@ interface WCProps extends Margins {
maxwidth?: string;
testid?: string;
iconposition?: GoabAccordionIconPosition;
+ headingType?: GoabAccordionHeadingType;
}
declare module "react" {
@@ -42,12 +44,16 @@ export interface GoabAccordionProps extends Margins, DataAttributes {
secondaryText?: string;
/** Sets content rendered within the accordion heading, alongside the heading text. */
headingContent?: ReactNode;
+ /** Sets content rendered in the accordion heading, right-aligned before the expand/collapse icon. */
+ actions?: ReactNode;
/** Sets the maximum width of the accordion. @default "none" */
maxWidth?: string;
/** Sets a data-testid attribute for automated testing. */
testId?: string;
/** Sets the position of the expand/collapse icon. @default "left" */
iconPosition?: GoabAccordionIconPosition;
+ /** Sets the accordion style variant. @default "normal" */
+ headingType?: GoabAccordionHeadingType;
/** Callback fired when the accordion is opened or closed. Receives the new open state as a boolean. */
onChange?: (open: boolean) => void;
/** Content rendered inside the accordion body. */
@@ -59,6 +65,8 @@ export function GoabAccordion({
open,
onChange,
headingContent,
+ headingType,
+ actions,
children,
...rest
}: GoabAccordionProps): JSX.Element {
@@ -81,8 +89,14 @@ export function GoabAccordion({
}, [onChange]);
return (
-
+
{headingContent &&
);
diff --git a/libs/react-components/src/lib/chip/chip.tsx b/libs/react-components/src/lib/chip/chip.tsx
index e02c58b08b..2ad7a678b7 100644
--- a/libs/react-components/src/lib/chip/chip.tsx
+++ b/libs/react-components/src/lib/chip/chip.tsx
@@ -30,19 +30,19 @@ declare module "react" {
}
export interface GoabChipProps extends Margins, DataAttributes {
- /** @required @deprecated Use GoAFilterChip instead. The text content displayed in the chip. */
+ /** @required @deprecated Use GoabFilterChip instead. The text content displayed in the chip. */
content: string;
- /** @deprecated Use GoAFilterChip instead. When true, shows a delete icon and makes chip clickable. */
+ /** @deprecated Use GoabFilterChip instead. When true, shows a delete icon and makes chip clickable. */
deletable?: boolean;
- /** @deprecated Use GoAFilterChip instead. Icon displayed at the start of the chip. */
+ /** @deprecated Use GoabFilterChip instead. Icon displayed at the start of the chip. */
leadingIcon?: string;
- /** @deprecated Use GoAFilterChip instead. The icon theme - outline or filled. */
+ /** @deprecated Use GoabFilterChip instead. The icon theme - outline or filled. */
iconTheme?: GoabChipTheme;
- /** @deprecated Use GoAFilterChip instead. Shows an error state on the chip. */
+ /** @deprecated Use GoabFilterChip instead. Shows an error state on the chip. */
error?: boolean;
- /** @deprecated Use GoAFilterChip instead. The chip variant style. */
+ /** @deprecated Use GoabFilterChip instead. The chip variant style. */
variant?: GoabChipVariant;
- /** @deprecated Use GoAFilterChip instead. Sets a data-testid attribute for automated testing. */
+ /** @deprecated Use GoabFilterChip instead. Sets a data-testid attribute for automated testing. */
testId?: string;
/** Callback fired when the chip is clicked or deleted. */
onClick?: () => void;
diff --git a/libs/react-components/src/lib/container/container.tsx b/libs/react-components/src/lib/container/container.tsx
index f630646802..5645aff2d0 100644
--- a/libs/react-components/src/lib/container/container.tsx
+++ b/libs/react-components/src/lib/container/container.tsx
@@ -46,9 +46,9 @@ export interface GoabContainerProps extends Margins, DataAttributes {
maxHeight?: string;
/** Sets a data-testid attribute for automated testing. */
testId?: string;
- /** Content rendered in the container's title/heading area. */
+ /** @deprecated Use title instead. Alias for the title prop. */
heading?: ReactNode;
- /** @deprecated Use heading instead. Alias for the heading prop. */
+ /** Content rendered in the container's title/heading area. */
title?: ReactNode;
/** Content rendered in the container's actions area, typically buttons or controls. */
actions?: ReactNode;
diff --git a/libs/react-components/src/lib/drawer/drawer.tsx b/libs/react-components/src/lib/drawer/drawer.tsx
index c1eda6568d..9c0fca7e34 100644
--- a/libs/react-components/src/lib/drawer/drawer.tsx
+++ b/libs/react-components/src/lib/drawer/drawer.tsx
@@ -56,9 +56,16 @@ export function GoabDrawer({
if (!el?.current || !onClose) {
return;
}
- el.current?.addEventListener("_close", onClose);
+ const current = el.current;
+ const listener = (e: Event) => {
+ if (e.target !== current) {
+ return;
+ }
+ onClose();
+ };
+ current.addEventListener("_close", listener);
return () => {
- el.current?.removeEventListener("_close", onClose);
+ current.removeEventListener("_close", listener);
};
}, [el, onClose]);
diff --git a/libs/react-components/src/lib/dropdown/dropdown.tsx b/libs/react-components/src/lib/dropdown/dropdown.tsx
index efe4819456..ced71d24a2 100644
--- a/libs/react-components/src/lib/dropdown/dropdown.tsx
+++ b/libs/react-components/src/lib/dropdown/dropdown.tsx
@@ -69,7 +69,7 @@ export interface GoabDropdownProps extends Margins, DataAttributes {
leadingIcon?: GoabIconType;
/** Maximum height of the dropdown menu. Non-native only. @default "276px" */
maxHeight?: string;
- /** When true, allows multiple items to be selected. */
+ /** When true, allows multiple items to be selected. @internal */
multiselect?: boolean;
/** When true, renders the native select HTML element. */
native?: boolean;
diff --git a/libs/react-components/src/lib/hero-banner/hero-banner.tsx b/libs/react-components/src/lib/hero-banner/hero-banner.tsx
index ee721a39a1..3347746c72 100644
--- a/libs/react-components/src/lib/hero-banner/hero-banner.tsx
+++ b/libs/react-components/src/lib/hero-banner/hero-banner.tsx
@@ -29,6 +29,8 @@ export interface GoabHeroBannerProps {
testId?: string;
/** Content rendered inside the hero banner body. */
children?: React.ReactNode;
+ /** Content rendered in the actions slot. */
+ actions?: React.ReactNode;
/** Maximum width of the content area. @default "100%" */
maxContentWidth?: string;
/** Hero Banner background color when no background image is provided. @default "#f8f8f8" */
@@ -46,6 +48,7 @@ export function GoabHeroBanner({
backgroundColor,
textColor,
children,
+ actions,
testId,
}: GoabHeroBannerProps): JSX.Element {
return (
@@ -59,6 +62,7 @@ export function GoabHeroBanner({
testid={testId}
>
{children}
+ {actions && (null);
const _props = transformProps(
diff --git a/libs/react-components/src/lib/microsite-header/microsite-header.tsx b/libs/react-components/src/lib/microsite-header/microsite-header.tsx
index 4132b6b9ce..106c6adfdf 100644
--- a/libs/react-components/src/lib/microsite-header/microsite-header.tsx
+++ b/libs/react-components/src/lib/microsite-header/microsite-header.tsx
@@ -26,7 +26,7 @@ interface WCProps {
export interface GoabHeaderProps {
/** @required The service type which determines the badge style. "live" shows official government site text, "alpha" and "beta" show development stage badges. */
type: GoabServiceLevel;
- /** App or service version displayed on the right side of the header. Accepts a string or custom ReactNode for rich content. */
+ /** App or service version displayed on the right side of the header. */
version?: string | React.ReactNode;
/** URL to a feedback page displayed when provided. */
feedbackUrl?: string;
diff --git a/libs/react-components/src/lib/modal/modal.tsx b/libs/react-components/src/lib/modal/modal.tsx
index 38604c5d83..4b97f47b13 100644
--- a/libs/react-components/src/lib/modal/modal.tsx
+++ b/libs/react-components/src/lib/modal/modal.tsx
@@ -76,7 +76,10 @@ export function GoabModal({
return;
}
const current = el.current;
- const listener = () => {
+ const listener = (e: Event) => {
+ if (e.target !== current) {
+ return;
+ }
onClose?.();
};
diff --git a/libs/react-components/src/lib/push-drawer/push-drawer.tsx b/libs/react-components/src/lib/push-drawer/push-drawer.tsx
index 681add6e08..ec3d4e7b96 100644
--- a/libs/react-components/src/lib/push-drawer/push-drawer.tsx
+++ b/libs/react-components/src/lib/push-drawer/push-drawer.tsx
@@ -51,9 +51,16 @@ export function GoabPushDrawer({
if (!el?.current || !onClose) {
return;
}
- el.current?.addEventListener("_close", onClose);
+ const current = el.current;
+ const listener = (e: Event) => {
+ if (e.target !== current) {
+ return;
+ }
+ onClose();
+ };
+ current.addEventListener("_close", listener);
return () => {
- el.current?.removeEventListener("_close", onClose);
+ current.removeEventListener("_close", listener);
};
}, [el, onClose]);
diff --git a/libs/react-components/src/lib/radio-group/radio.tsx b/libs/react-components/src/lib/radio-group/radio.tsx
index 9f100e6dc6..11b836f635 100644
--- a/libs/react-components/src/lib/radio-group/radio.tsx
+++ b/libs/react-components/src/lib/radio-group/radio.tsx
@@ -44,7 +44,7 @@ export interface GoabRadioItemProps extends Margins {
maxWidth?: string;
/** Disables this radio option. Also disabled if the parent RadioGroup is disabled. */
disabled?: boolean;
- /** Sets this radio option as checked/selected. */
+ /** @internal Sets this radio option as checked/selected. */
checked?: boolean;
/** Shows an error state on this radio option. */
error?: boolean;
diff --git a/libs/react-components/src/lib/tab/tab.tsx b/libs/react-components/src/lib/tab/tab.tsx
index 919289ed83..0064fb1643 100644
--- a/libs/react-components/src/lib/tab/tab.tsx
+++ b/libs/react-components/src/lib/tab/tab.tsx
@@ -1,7 +1,7 @@
import type { JSX } from "react";
interface WCProps {
- heading?: React.ReactNode;
+ heading?: string | React.ReactNode;
disabled?: string;
slug?: string;
}
@@ -17,7 +17,7 @@ declare module "react" {
export interface GoabTabItemProps {
/** The text label for this tab. Can also pass React nodes for custom heading content. */
- heading?: React.ReactNode;
+ heading?: string | React.ReactNode;
/** When true, disables the tab so it cannot be selected. */
disabled?: boolean;
/** Content rendered inside the tab panel. */
diff --git a/libs/react-components/src/lib/table/table-sort-header.tsx b/libs/react-components/src/lib/table/table-sort-header.tsx
index 0995dc319b..6be764bbe1 100644
--- a/libs/react-components/src/lib/table/table-sort-header.tsx
+++ b/libs/react-components/src/lib/table/table-sort-header.tsx
@@ -10,6 +10,7 @@ interface WCProps {
name?: string;
direction?: GoabTableSortDirection;
"sort-order"?: GoabTableSortOrder;
+ version?: "1" | "2";
}
declare module "react" {
@@ -46,6 +47,7 @@ export function GoabTableSortHeader({
name={name}
direction={direction}
sort-order={sortOrder}
+ version="2"
{...rest}
>
{children}
diff --git a/libs/react-components/src/lib/table/table.tsx b/libs/react-components/src/lib/table/table.tsx
index c07dc6bc17..b654243402 100644
--- a/libs/react-components/src/lib/table/table.tsx
+++ b/libs/react-components/src/lib/table/table.tsx
@@ -10,7 +10,6 @@ import { ReactNode, useEffect, useRef } from "react";
interface WCProps extends Margins {
ref?: React.RefObject;
width?: string;
- stickyheader?: string;
variant?: GoabTableVariant;
"sort-mode"?: GoabTableSortMode;
testid?: string;
@@ -37,7 +36,7 @@ export interface GoabTableProps extends Margins {
onMultiSort?: (detail: GoabTableOnMultiSortDetail) => void;
/** Sort mode: "single" allows one column, "multi" allows up to 2 columns. @default "single" */
sortMode?: GoabTableSortMode;
- // stickyHeader?: boolean; TODO: enable this later
+ // stickyHeader intentionally not exposed in wrapper yet.
/** A relaxed variant of the table with more vertical padding for the cells. @default "normal" */
variant?: GoabTableVariant;
/** When true, alternates row background colors for improved readability. */
diff --git a/libs/react-components/src/lib/theme/theme-context.spec.tsx b/libs/react-components/src/lib/theme/theme-context.spec.tsx
new file mode 100644
index 0000000000..9eec8e998e
--- /dev/null
+++ b/libs/react-components/src/lib/theme/theme-context.spec.tsx
@@ -0,0 +1,215 @@
+import { act, renderHook } from "@testing-library/react";
+import { type ReactNode } from "react";
+
+import { GoabThemeProvider, useTheme } from "./theme-context";
+
+const STORAGE_KEY = "goab-theme";
+const ATTRIBUTE = "data-theme";
+
+function mockMatchMedia(prefersDark: boolean) {
+ Object.defineProperty(window, "matchMedia", {
+ writable: true,
+ value: vi.fn().mockImplementation((query: string) => ({
+ matches: query === "(prefers-color-scheme: dark)" ? prefersDark : false,
+ media: query,
+ onchange: null,
+ addListener: vi.fn(),
+ removeListener: vi.fn(),
+ addEventListener: vi.fn(),
+ removeEventListener: vi.fn(),
+ dispatchEvent: vi.fn(),
+ })),
+ });
+}
+
+function wrapper(props: { children: ReactNode }) {
+ return {props.children} ;
+}
+
+describe("GoabThemeProvider / useTheme", () => {
+ beforeEach(() => {
+ localStorage.clear();
+ document.documentElement.removeAttribute(ATTRIBUTE);
+ mockMatchMedia(false);
+ });
+
+ describe("initial mode resolution", () => {
+ it("defaults to 'light' when localStorage, attribute, and system preference are absent", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("reads 'dark' from localStorage when present", () => {
+ localStorage.setItem(STORAGE_KEY, "dark");
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("reads 'light' from localStorage when present", () => {
+ localStorage.setItem(STORAGE_KEY, "light");
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("ignores invalid localStorage values and falls through to next source", () => {
+ localStorage.setItem(STORAGE_KEY, "purple");
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("reads 'dark' from data-theme attribute when localStorage is empty", () => {
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("reads 'dark' from prefers-color-scheme when localStorage and attribute are absent", () => {
+ mockMatchMedia(true);
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("prefers localStorage over data-theme attribute", () => {
+ localStorage.setItem(STORAGE_KEY, "light");
+ document.documentElement.setAttribute(ATTRIBUTE, "dark");
+
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("prefers data-theme attribute over prefers-color-scheme", () => {
+ mockMatchMedia(true);
+ document.documentElement.setAttribute(ATTRIBUTE, "light");
+
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("respects defaultMode prop when no other source is set", () => {
+ const customWrapper = (props: { children: ReactNode }) => (
+ {props.children}
+ );
+ const { result } = renderHook(() => useTheme(), { wrapper: customWrapper });
+ expect(result.current.mode).toBe("dark");
+ });
+ });
+
+ describe("setMode", () => {
+ it("updates the mode value", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.setMode("dark"));
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("syncs the data-theme attribute on ", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.setMode("dark"));
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+
+ act(() => result.current.setMode("light"));
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("light");
+ });
+
+ it("persists the mode to localStorage", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.setMode("dark"));
+ expect(localStorage.getItem(STORAGE_KEY)).toBe("dark");
+ });
+ });
+
+ describe("toggle", () => {
+ it("flips light to dark", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("light");
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("flips dark to light", () => {
+ localStorage.setItem(STORAGE_KEY, "dark");
+ const { result } = renderHook(() => useTheme(), { wrapper });
+ expect(result.current.mode).toBe("dark");
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("light");
+ });
+
+ it("flips back and forth across multiple calls", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("dark");
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("light");
+
+ act(() => result.current.toggle());
+ expect(result.current.mode).toBe("dark");
+ });
+
+ it("syncs attribute and localStorage on toggle", () => {
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ act(() => result.current.toggle());
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+ expect(localStorage.getItem(STORAGE_KEY)).toBe("dark");
+ });
+
+ it("returns a stable toggle reference across renders", () => {
+ const { result, rerender } = renderHook(() => useTheme(), { wrapper });
+ const firstToggle = result.current.toggle;
+
+ rerender();
+ expect(result.current.toggle).toBe(firstToggle);
+ });
+ });
+
+ describe("useTheme outside provider", () => {
+ it("throws a descriptive error when used without GoabThemeProvider", () => {
+ // Suppress React's expected error log for this test
+ const noop = () => undefined;
+ const errorSpy = vi.spyOn(console, "error").mockImplementation(noop);
+
+ expect(() => renderHook(() => useTheme())).toThrow(
+ "useTheme must be used within a GoabThemeProvider",
+ );
+
+ errorSpy.mockRestore();
+ });
+ });
+
+ describe("localStorage failures", () => {
+ it("does not throw when localStorage.setItem is blocked", () => {
+ const setItemSpy = vi
+ .spyOn(Storage.prototype, "setItem")
+ .mockImplementation(() => {
+ throw new Error("QuotaExceededError");
+ });
+
+ const { result } = renderHook(() => useTheme(), { wrapper });
+
+ expect(() => act(() => result.current.setMode("dark"))).not.toThrow();
+ expect(document.documentElement.getAttribute(ATTRIBUTE)).toBe("dark");
+
+ setItemSpy.mockRestore();
+ });
+
+ it("does not throw when localStorage.getItem is blocked at construction", () => {
+ const getItemSpy = vi
+ .spyOn(Storage.prototype, "getItem")
+ .mockImplementation(() => {
+ throw new Error("SecurityError");
+ });
+
+ expect(() => renderHook(() => useTheme(), { wrapper })).not.toThrow();
+
+ getItemSpy.mockRestore();
+ });
+ });
+});
diff --git a/libs/react-components/src/lib/theme/theme-context.tsx b/libs/react-components/src/lib/theme/theme-context.tsx
new file mode 100644
index 0000000000..2f02c14d1e
--- /dev/null
+++ b/libs/react-components/src/lib/theme/theme-context.tsx
@@ -0,0 +1,87 @@
+import {
+ createContext,
+ useCallback,
+ useContext,
+ useEffect,
+ useState,
+ type ReactNode,
+} from "react";
+import type { GoabThemeMode } from "@abgov/ui-components-common";
+
+interface GoabThemeContextValue {
+ mode: GoabThemeMode;
+ setMode: (mode: GoabThemeMode) => void;
+ toggle: () => void;
+}
+
+const STORAGE_KEY = "goab-theme";
+const ATTRIBUTE = "data-theme";
+
+const GoabThemeContext = createContext(null);
+
+function readInitialMode(defaultMode: GoabThemeMode): GoabThemeMode {
+ if (typeof window === "undefined") return defaultMode;
+
+ // Priority: localStorage > existing data-theme > system preference > defaultMode.
+ // Reading the attribute allows a blocking
@@ -55,7 +55,7 @@ export class GoabPushDrawer implements OnInit {
/** Sets the template reference for the actions slot content. */
@Input() actions!: TemplateRef;
/** Emits when the push drawer closes. */
- @Output() onClose = new EventEmitter();
+ @Output() onClose = new EventEmitter();
isReady = false;
@@ -66,7 +66,8 @@ export class GoabPushDrawer implements OnInit {
}, 0);
}
- _onClose() {
+ _onClose(event: Event) {
+ if (event.target !== event.currentTarget) return;
this.onClose.emit();
}
diff --git a/libs/angular-components/src/lib/components/radio-group/radio-group.ts b/libs/angular-components/src/lib/components/radio-group/radio-group.ts
index d22518a691..1d25bf8ab5 100644
--- a/libs/angular-components/src/lib/components/radio-group/radio-group.ts
+++ b/libs/angular-components/src/lib/components/radio-group/radio-group.ts
@@ -63,6 +63,8 @@ export class GoabRadioGroup extends GoabControlValueAccessor implements OnInit {
version = "2";
/** The name for the radio group. Used for accessibility and change events. */
@Input() name?: string;
+ /** The currently selected value in the radio group. */
+ @Input() override value?: string;
/** Sets the layout direction. 'vertical' stacks items, 'horizontal' places them in a row. */
@Input() orientation?: GoabRadioGroupOrientation;
/** Defines how the radio group will be announced by screen readers. */
diff --git a/libs/angular-components/src/lib/components/radio-item/radio-item.ts b/libs/angular-components/src/lib/components/radio-item/radio-item.ts
index 1a88274803..cbccd7c354 100644
--- a/libs/angular-components/src/lib/components/radio-item/radio-item.ts
+++ b/libs/angular-components/src/lib/components/radio-item/radio-item.ts
@@ -69,7 +69,7 @@ export class GoabRadioItem extends GoabBaseComponent implements OnInit {
@Input() revealAriaLabel?: string;
/** Disables this radio option. Also disabled if the parent RadioGroup is disabled. */
@Input({ transform: booleanAttribute }) disabled?: boolean;
- /** Sets this radio option as checked/selected. */
+ /** @internal Sets this radio option as checked/selected. */
@Input({ transform: booleanAttribute }) checked?: boolean;
/** Shows an error state on this radio option. */
@Input({ transform: booleanAttribute }) error?: boolean;
diff --git a/libs/angular-components/src/lib/components/table-sort-header/table-sort-header.ts b/libs/angular-components/src/lib/components/table-sort-header/table-sort-header.ts
index 7ebffb98e5..16e99b20ae 100644
--- a/libs/angular-components/src/lib/components/table-sort-header/table-sort-header.ts
+++ b/libs/angular-components/src/lib/components/table-sort-header/table-sort-header.ts
@@ -17,6 +17,7 @@ import {
[attr.name]="name"
[attr.direction]="direction"
[attr.sort-order]="sortOrder"
+ [attr.version]="version"
>
+
+
+
+ `,
+})
+class TestWorkSideMenuItemWithTrailingContentComponent {
+ label = "Trailing item";
+ url = "/trailing";
+}
+
describe("GoabWorkSideMenuItem", () => {
it("should render and set the props correctly", fakeAsync(() => {
TestBed.configureTestingModule({
@@ -96,4 +116,26 @@ describe("GoabWorkSideMenuItem", () => {
expect(popoverContent).toBeTruthy();
expect(popoverContent.nativeElement.textContent).toBe("Popover content here");
}));
+
+ it("should render trailing content into the trailingContent slot", fakeAsync(() => {
+ TestBed.configureTestingModule({
+ imports: [TestWorkSideMenuItemWithTrailingContentComponent],
+ }).compileComponents();
+
+ const fixture = TestBed.createComponent(TestWorkSideMenuItemWithTrailingContentComponent);
+ fixture.detectChanges();
+ tick();
+ fixture.detectChanges();
+
+ const slotDiv = fixture.debugElement.query(
+ By.css('[slot="trailingContent"]'),
+ );
+ expect(slotDiv).toBeTruthy();
+
+ const trailingContent = fixture.debugElement.query(
+ By.css(".trailing-test-content"),
+ );
+ expect(trailingContent).toBeTruthy();
+ expect(trailingContent.nativeElement.textContent).toBe("2");
+ }));
});
diff --git a/libs/angular-components/src/lib/components/work-side-menu-item/work-side-menu-item.ts b/libs/angular-components/src/lib/components/work-side-menu-item/work-side-menu-item.ts
index 527530fe87..493ddcd709 100644
--- a/libs/angular-components/src/lib/components/work-side-menu-item/work-side-menu-item.ts
+++ b/libs/angular-components/src/lib/components/work-side-menu-item/work-side-menu-item.ts
@@ -31,6 +31,11 @@ import { NgTemplateOutlet } from "@angular/common";
}
+ @if (trailingContent) {
+ 2
+
+
+ }
{{message}}
which will update message when we press Open button => "Open user 1" for example
- // Verify the message to test if Open is triggered
- const openMessage = result.container.querySelector('[data-testid="open-user"]') as HTMLElement;
- expect(openMessage?.textContent).toBe("Open user 1");
+ // Wait for the Open handler to fire and React to render the message div.
+ // Enter activates the focused button via setTimeout(0) inside DataGrid.focusCell;
+ // a fixed sleep races the macrotask queue under CI load, so poll the assertion.
+ await vi.waitFor(() => {
+ const openMessage = result.container.querySelector('[data-testid="open-user"]') as HTMLElement;
+ expect(openMessage?.textContent).toBe("Open user 1");
+ });
// Arrow Right
await userEvent.keyboard("{ArrowRight}");
await new Promise(resolve => setTimeout(resolve, 100));
// Verify data-grid="cell-4" highlighted
const cell4 = result.container.querySelector('[data-grid="cell-4"]') as HTMLElement;
- expect(cell4?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
+ expect(cell4?.hasAttribute('data-focused')).toBe(true);
// Arrow Right
await userEvent.keyboard("{ArrowRight}");
@@ -513,7 +517,7 @@ describe("DataGrid", () => {
// Verify data-grid="cell-5" highlighted
const cell5 = result.container.querySelector('[data-grid="cell-5"]') as HTMLElement;
- expect(cell5?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
+ expect(cell5?.hasAttribute('data-focused')).toBe(true);
// Arrow Right
await userEvent.keyboard("{ArrowRight}");
@@ -521,7 +525,7 @@ describe("DataGrid", () => {
// Verify data-grid="cell-6" highlighted
const cell6 = result.container.querySelector('[data-grid="cell-6"]') as HTMLElement;
- expect(cell6?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
+ expect(cell6?.hasAttribute('data-focused')).toBe(true);
// Arrow Right
await userEvent.keyboard("{ArrowRight}");
@@ -529,7 +533,7 @@ describe("DataGrid", () => {
// Verify data-grid="cell-7" highlighted
const cell7 = result.container.querySelector('[data-grid="cell-7"]') as HTMLElement;
- expect(cell7?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
+ expect(cell7?.hasAttribute('data-focused')).toBe(true);
// Arrow Right
await userEvent.keyboard("{ArrowRight}");
@@ -537,7 +541,7 @@ describe("DataGrid", () => {
// Verify data-grid="cell-8" highlighted
const cell8 = result.container.querySelector('[data-grid="cell-8"]') as HTMLElement;
- expect(cell8?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
+ expect(cell8?.hasAttribute('data-focused')).toBe(true);
// Arrow right
await userEvent.keyboard("{ArrowRight}");
await new Promise(resolve => setTimeout(resolve, 100));
@@ -552,11 +556,12 @@ describe("DataGrid", () => {
// Press Enter
await userEvent.keyboard("{Enter}");
- await new Promise(resolve => setTimeout(resolve, 100));
- // Verify div data-testid="approver-1" has text content = John Doe
- const approver1 = result.container.querySelector('[data-testid="approver-1"]') as HTMLElement;
- expect(approver1?.textContent).toBe("John Doe");
+ // Wait for the dropdown selection to flow through to the rendered approver text.
+ await vi.waitFor(() => {
+ const approver1 = result.container.querySelector('[data-testid="approver-1"]') as HTMLElement;
+ expect(approver1?.textContent).toBe("John Doe");
+ });
})
it("Using with Container (Layout mode) - arrow right from last cell wraps to next row", async () => {
@@ -703,21 +708,20 @@ describe("DataGrid", () => {
const initialRows = result.container.querySelectorAll('[data-grid="row"]');
expect(initialRows.length).toBe(2);
- // Click on the first row's name cell to establish focus
+ // Click on the first row's name cell to establish focus position.
+ // Per issue #3605, mouse click establishes focus but does NOT apply the
+ // cell outline — the outline only shows for keyboard-driven focus.
const firstRowName = result.container.querySelector('[data-testid="name-1"]') as HTMLElement;
await userEvent.click(firstRowName);
await new Promise(resolve => setTimeout(resolve, 100));
- // Verify first row name is highlighted
- expect(firstRowName?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
-
- // Navigate to the second row using Arrow Down
+ // Navigate to the second row using Arrow Down — keyboard nav applies the outline.
await userEvent.keyboard("{ArrowDown}");
await new Promise(resolve => setTimeout(resolve, 100));
// Verify second row name is highlighted
const secondRowName = result.container.querySelector('[data-testid="name-2"]') as HTMLElement;
- expect(secondRowName?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
+ expect(secondRowName?.hasAttribute('data-focused')).toBe(true);
// Add new rows by clicking the button
const addRowsBtn = result.container.querySelector('[data-testid="add-rows-btn"]') as HTMLElement;
@@ -731,20 +735,17 @@ describe("DataGrid", () => {
const updatedRows = result.container.querySelectorAll('[data-grid="row"]');
expect(updatedRows.length).toBe(4);
- // Click on first row's name to re-establish focus
+ // Click on first row's name to re-establish focus position (no outline per #3605).
await userEvent.click(firstRowName);
await new Promise(resolve => setTimeout(resolve, 100));
- // Verify first row name is highlighted after re-click
- expect(firstRowName?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
-
- // Navigate down through all rows including newly added ones
+ // Navigate down through all rows including newly added ones — keyboard applies outline.
// Row 1 -> Row 2
await userEvent.keyboard("{ArrowDown}");
await new Promise(resolve => setTimeout(resolve, 100));
// Verify second row name is highlighted
- expect(secondRowName?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
+ expect(secondRowName?.hasAttribute('data-focused')).toBe(true);
// Row 2 -> Row 3 (newly added)
await userEvent.keyboard("{ArrowDown}");
@@ -754,7 +755,7 @@ describe("DataGrid", () => {
const thirdRowName = result.container.querySelector('[data-testid="name-3"]') as HTMLElement;
expect(thirdRowName).toBeTruthy();
expect(thirdRowName?.textContent).toBe("New User 3");
- expect(thirdRowName?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
+ expect(thirdRowName?.hasAttribute('data-focused')).toBe(true);
// Row 3 -> Row 4 (newly added)
await userEvent.keyboard("{ArrowDown}");
@@ -764,20 +765,20 @@ describe("DataGrid", () => {
const fourthRowName = result.container.querySelector('[data-testid="name-4"]') as HTMLElement;
expect(fourthRowName).toBeTruthy();
expect(fourthRowName?.textContent).toBe("New User 4");
- expect(fourthRowName?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
+ expect(fourthRowName?.hasAttribute('data-focused')).toBe(true);
// Navigate back up to verify bidirectional navigation works
await userEvent.keyboard("{ArrowUp}"); // Row 4 -> Row 3
await new Promise(resolve => setTimeout(resolve, 100));
- expect(thirdRowName?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
+ expect(thirdRowName?.hasAttribute('data-focused')).toBe(true);
await userEvent.keyboard("{ArrowUp}"); // Row 3 -> Row 2
await new Promise(resolve => setTimeout(resolve, 100));
- expect(secondRowName?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
+ expect(secondRowName?.hasAttribute('data-focused')).toBe(true);
await userEvent.keyboard("{ArrowUp}"); // Row 2 -> Row 1
await new Promise(resolve => setTimeout(resolve, 100));
- expect(firstRowName?.style.outline).toContain('3px solid var(--goa-color-interactive-focus)');
+ expect(firstRowName?.hasAttribute('data-focused')).toBe(true);
});
});
diff --git a/libs/react-components/specs/link.browser.spec.tsx b/libs/react-components/specs/link.browser.spec.tsx
index 621b0ebf76..64e2217dd3 100644
--- a/libs/react-components/specs/link.browser.spec.tsx
+++ b/libs/react-components/specs/link.browser.spec.tsx
@@ -2,6 +2,7 @@ import { render } from "vitest-browser-react";
import { GoabLink } from "../src";
import { expect, describe, it, vi } from "vitest";
+import { userEvent } from "@vitest/browser/context";
describe("Link", () => {
it("should trigger the action with an arg", async () => {
@@ -118,4 +119,48 @@ describe("Link", () => {
expect(spy).toHaveBeenCalled();
});
});
+
+ it("should apply the focus ring on keyboard focus but not on mouse click (#3605)", async () => {
+ const Component = () => {
+ return (
+
+
+
+ Download file
+
+
+
+ );
+ };
+
+ const result = render(Parent content
+Child content
+Trailing
}
/>
}
secondaryContent={
@@ -51,12 +52,16 @@ describe("WorkSideMenu", () => {
const primarySlot = result.baseElement.querySelector("[slot='primary']");
const primaryMenuItem = result.getByTestId("primary-menu-item");
const primaryLink = primaryMenuItem.element().querySelector("a");
+ const primaryTrailing = result.getByTestId("trailing-content");
expect(primarySlot).toBeTruthy();
expect(primaryLink?.getAttribute("href")).toBe("#item1");
expect(primaryLink?.textContent).toContain("Item 1");
expect(primaryLink?.role).toBe("menuitem");
+ expect(primaryTrailing).toBeTruthy();
+ expect(primaryTrailing.element().textContent).toBe("Trailing");
+
const secondarySlot = result.baseElement.querySelector("[slot='secondary']");
const secondaryMenuItem = result.getByTestId("secondary-menu-item");
const secondaryLink = secondaryMenuItem.element().querySelector("a");
diff --git a/libs/react-components/src/index.ts b/libs/react-components/src/index.ts
index f51ac6b0b9..9131e5d6a3 100644
--- a/libs/react-components/src/index.ts
+++ b/libs/react-components/src/index.ts
@@ -80,3 +80,4 @@ export * from "./lib/work-side-menu-group/work-side-menu-group";
export * from "./lib/work-side-menu-item/work-side-menu-item";
export * from "./lib/work-side-notification-item/work-side-notification-item";
export * from "./lib/work-side-notification-panel/work-side-notification-panel";
+export * from "./lib/theme/theme-context";
diff --git a/libs/react-components/src/lib/accordion/accordion.spec.tsx b/libs/react-components/src/lib/accordion/accordion.spec.tsx
index 2331e6bfe2..6cf5f3586a 100644
--- a/libs/react-components/src/lib/accordion/accordion.spec.tsx
+++ b/libs/react-components/src/lib/accordion/accordion.spec.tsx
@@ -1,5 +1,6 @@
import { render } from "@testing-library/react";
import { GoabBadge } from "../badge/badge";
+import { GoabButton } from "../button/button";
import { GoabAccordion } from "./accordion";
@@ -20,6 +21,7 @@ describe("Accordion", () => {
heading="The heading"
secondaryText="Secondary Text"
open
+ headingType="filled"
headingContent={{headingContent}
}
+ {actions && {actions}
}
{children}
{actions}
}
);
}
diff --git a/libs/react-components/src/lib/input/input.tsx b/libs/react-components/src/lib/input/input.tsx
index 7e508a7285..d134194289 100644
--- a/libs/react-components/src/lib/input/input.tsx
+++ b/libs/react-components/src/lib/input/input.tsx
@@ -179,7 +179,10 @@ export function GoabInput({
onBlur,
onKeyPress,
...rest
-}: GoabInputProps & { type?: GoabInputType }): JSX.Element {
+}: GoabInputProps & {
+ /** Sets the type of the input field. @default "text" */
+ type?: GoabInputType;
+}): JSX.Element {
const ref = useRef
diff --git a/libs/web-components/src/components/menu-button/MenuButton.svelte b/libs/web-components/src/components/menu-button/MenuButton.svelte
index 9af6007abb..e77f2634f1 100644
--- a/libs/web-components/src/components/menu-button/MenuButton.svelte
+++ b/libs/web-components/src/components/menu-button/MenuButton.svelte
@@ -139,7 +139,7 @@
}
function onAction(action: MenuActionProps) {
- dispatch(_rootEl, "_action", action, { bubbles: true });
+ dispatch(_rootEl, "_action", { action: action.action, size: action.size }, { bubbles: true });
close();
_buttonIndex = 0;
}
diff --git a/libs/web-components/src/components/microsite-header/MicrositeHeader.svelte b/libs/web-components/src/components/microsite-header/MicrositeHeader.svelte
index fe03dfbd97..ff19af50d9 100644
--- a/libs/web-components/src/components/microsite-header/MicrositeHeader.svelte
+++ b/libs/web-components/src/components/microsite-header/MicrositeHeader.svelte
@@ -161,7 +161,7 @@
color: var(--goa-microsite-header-color-links-hover);
}
- a:focus {
+ a:focus-visible {
outline: var(--goa-microsite-header-link-focus-border);
}
diff --git a/libs/web-components/src/components/notification/Notification.svelte b/libs/web-components/src/components/notification/Notification.svelte
index 28c0caf94e..efe9adb63c 100644
--- a/libs/web-components/src/components/notification/Notification.svelte
+++ b/libs/web-components/src/components/notification/Notification.svelte
@@ -191,11 +191,11 @@
color: unset !important;
outline: unset !important;
}
- :global(::slotted(a:focus)) {
+ :global(::slotted(a:focus-visible)) {
outline: auto !important;
border-radius: var(--goa-border-radius-xs);
}
- .notification.important :global(::slotted(a:focus)) {
+ .notification.important :global(::slotted(a:focus-visible)) {
outline: unset !important;
box-shadow: 0 0 0 3px var(--goa-color-greyscale-black);
border-radius: var(--goa-border-radius-xs);
@@ -423,27 +423,27 @@
}
/* V2 link focus states */
- .v2 .notification.important.high :global(::slotted(a:focus)) {
+ .v2 .notification.important.high :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-important-high-focus-border);
}
- .v2 .notification.important.low :global(::slotted(a:focus)) {
+ .v2 .notification.important.low :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-important-low-focus-border);
}
- .v2 .notification.information.high :global(::slotted(a:focus)) {
+ .v2 .notification.information.high :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-information-high-focus-border);
}
- .v2 .notification.information.low :global(::slotted(a:focus)) {
+ .v2 .notification.information.low :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-information-low-focus-border);
}
- .v2 .notification.emergency.high :global(::slotted(a:focus)) {
+ .v2 .notification.emergency.high :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-emergency-high-focus-border);
}
- .v2 .notification.emergency.low :global(::slotted(a:focus)) {
+ .v2 .notification.emergency.low :global(::slotted(a:focus-visible)) {
box-shadow: var(--goa-notification-banner-emergency-low-focus-border);
}
diff --git a/libs/web-components/src/components/popover/Popover.svelte b/libs/web-components/src/components/popover/Popover.svelte
index 0b9fa6d436..362349ec6a 100644
--- a/libs/web-components/src/components/popover/Popover.svelte
+++ b/libs/web-components/src/components/popover/Popover.svelte
@@ -54,13 +54,13 @@
/** Disables the popover interaction. Used by parent components like Dropdown. */
export let disabled: string = "false";
/** Additional vertical offset added to the popover's position. */
- export let voffset = "";
+ export let voffset: string = "";
/** Additional horizontal offset added to the popover's position. */
- export let hoffset = "";
+ export let hoffset: string = "";
/** Width of the focus outline border. */
- export let focusborderwidth = "var(--goa-border-width-l)";
+ export let focusborderwidth: string = "var(--goa-border-width-l)";
/** Border radius of the popover window. */
- export let borderradius = "var(--goa-border-radius-m)";
+ export let borderradius: string = "var(--goa-border-radius-m)";
/** Indicates the popover is used within a filterable context like a combobox. */
export let filterablecontext: string = "false";
@@ -200,6 +200,44 @@
}
}
+ function isInPopoverComposedTree(node: EventTarget | null): boolean {
+ if (!_popoverEl || !(node instanceof Node)) {
+ return false;
+ }
+
+ if (_popoverEl.contains(node)) {
+ return true;
+ }
+
+ // Walk across slot and shadow boundaries to detect nested/slotted descendants.
+ let current: Node | null = node;
+ while (current) {
+ if (current === _popoverEl) {
+ return true;
+ }
+
+ if (current instanceof Element && current.assignedSlot) {
+ current = current.assignedSlot;
+ continue;
+ }
+
+ if (current.parentNode) {
+ current = current.parentNode;
+ continue;
+ }
+
+ const rootNode = current.getRootNode?.();
+ if (rootNode instanceof ShadowRoot) {
+ current = rootNode.host;
+ continue;
+ }
+
+ current = null;
+ }
+
+ return false;
+ }
+
// When one popover is opened it dispatches a `goa:closePopover` to the document.body element, so adding a listener
// here will allow any other popover that is currently open to be closed
function addGlobalCloseListener() {
@@ -213,7 +251,10 @@
// the popover that is being opened will, at that time have the an open state, so we need to prevent
// that one that is being opened be immediately closed.
if (target !== _targetEl) {
- closePopover();
+ // Don't close if the target is a child popover (descendant of this popover's content)
+ if (target && !isInPopoverComposedTree(target)) {
+ closePopover();
+ }
}
});
}
@@ -404,7 +445,7 @@
class:use-anchor-based-positioning={!_needsManualPositioning}
class:align-right={_alignment === "right"}
style={styles(
- style("width", position !== "right" ? width : undefined),
+ position !== "right" && style("width", width),
style("min-width", minwidth),
style(
"max-width",
diff --git a/libs/web-components/src/components/push-drawer/PushDrawerInternal.svelte b/libs/web-components/src/components/push-drawer/PushDrawerInternal.svelte
index 5efc55ea69..192bfa1e9e 100644
--- a/libs/web-components/src/components/push-drawer/PushDrawerInternal.svelte
+++ b/libs/web-components/src/components/push-drawer/PushDrawerInternal.svelte
@@ -24,6 +24,7 @@
export let open: boolean = false;
export let heading: string = "";
export let width: string = "492px";
+ /** @internal Design system version for styling. */
export let version: VersionType = "1";
let _contentEl: HTMLElement | null = null;
diff --git a/libs/web-components/src/components/radio-item/RadioItem.svelte b/libs/web-components/src/components/radio-item/RadioItem.svelte
index bbf00546a5..678d8705a2 100644
--- a/libs/web-components/src/components/radio-item/RadioItem.svelte
+++ b/libs/web-components/src/components/radio-item/RadioItem.svelte
@@ -66,7 +66,7 @@
export let disabled: string = "false";
/** Shows an error state on this radio option. */
export let error: string = "false";
- /** Sets this radio option as checked/selected. */
+ /** @internal Sets this radio option as checked/selected. */
export let checked: string = "false";
/** Defines how this option will be announced by screen readers. */
export let arialabel: string = "";
@@ -209,7 +209,7 @@
checked = fromBoolean(data.checked);
description = data.description;
name = data.name;
- revealarialabel = data.revealAriaLabel;
+ revealarialabel = data.revealAriaLabel || "";
_version = data.version || "1";
_compact = data.compact || false;
});
diff --git a/libs/web-components/src/components/side-menu-group/SideMenuGroup.svelte b/libs/web-components/src/components/side-menu-group/SideMenuGroup.svelte
index ef495212c3..7002ab82d5 100644
--- a/libs/web-components/src/components/side-menu-group/SideMenuGroup.svelte
+++ b/libs/web-components/src/components/side-menu-group/SideMenuGroup.svelte
@@ -138,7 +138,7 @@
${calculateMargin(mt, mr, mb, ml)};
`}
>
-
+
{#if icon}
diff --git a/libs/web-components/src/components/temporary-notification/TemporaryNotificationCtrl.svelte b/libs/web-components/src/components/temporary-notification/TemporaryNotificationCtrl.svelte
index 5d63f8b7c4..fee9e12954 100644
--- a/libs/web-components/src/components/temporary-notification/TemporaryNotificationCtrl.svelte
+++ b/libs/web-components/src/components/temporary-notification/TemporaryNotificationCtrl.svelte
@@ -1,28 +1,35 @@
-
| undefined;
+ let _hideTooltipTimeout: ReturnType | undefined;
// Use a unique id for each tooltip instance.
// So screen readers can identify the tooltip instance when
@@ -143,6 +143,16 @@
}, 500);
};
+ // Mouse click also fires on:focus on a tabindex=0 element, but we only want
+ // to reveal the tooltip on keyboard-driven focus so JS state stays aligned
+ // with the CSS :focus-visible rule that drives opacity.
+ function handleFocus(e: FocusEvent) {
+ const target = e.currentTarget as HTMLElement | null;
+ if (!target?.matches?.(":focus-visible")) return;
+ clearTimeout(_hideTooltipTimeout);
+ showTooltip();
+ }
+
async function checkAndAdjustPosition() {
// angular needs time to render the _tooltipEl
await tick();
@@ -227,10 +237,7 @@
showTooltip();
}}
on:mouseleave={hideTooltip}
- on:focus={() => {
- clearTimeout(_hideTooltipTimeout);
- showTooltip();
- }}
+ on:focus={handleFocus}
on:blur={hideTooltip}
data-testid={testid}
role="tooltip"
@@ -315,7 +322,7 @@
}
.tooltip:hover .tooltip-text,
- .tooltip:focus .tooltip-text {
+ .tooltip:focus-visible .tooltip-text {
opacity: 1;
}
diff --git a/libs/web-components/src/components/work-side-menu/WorkSideMenu.svelte b/libs/web-components/src/components/work-side-menu/WorkSideMenu.svelte
index 4aabdd4c56..a08757c4e7 100644
--- a/libs/web-components/src/components/work-side-menu/WorkSideMenu.svelte
+++ b/libs/web-components/src/components/work-side-menu/WorkSideMenu.svelte
@@ -32,7 +32,7 @@
// optional
/** Controls whether the side menu is expanded or collapsed. */
- export let open = false;
+ export let open: boolean = false;
/** Sets a data-testid attribute for automated testing. */
export let testid: string = "";
/** User's name displayed in the profile section. */
@@ -55,10 +55,10 @@
let _menuEl: HTMLElement;
let _menuLinks: HTMLElement[] = [];
- let _containerEl: HTMLElement;
+ let _containerEl: HTMLElement | undefined;
let _rootEl: HTMLElement;
let _scrollEl: HTMLElement;
- let _toggleButtonEl: HTMLElement;
+ let _toggleButtonEl: HTMLElement | undefined;
let _tooltipEl: HTMLElement;
let _tooltipLabel: string = "";
@@ -71,7 +71,7 @@
let _resizeObserver: ResizeObserver | null = null;
const _logo =
- "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32' fill='none'%3E%3Crect width='31.695' height='31.688' x='.028' fill='%2300B6ED' rx='4'/%3E%3Cg clip-path='url(%23a)'%3E%3Cmask id='b' width='47' height='39' x='-11' y='-2' maskUnits='userSpaceOnUse' style='mask-type:alpha'%3E%3Cpath fill='%23545860' d='M22.017 31.103a63.47 63.47 0 0 1-7.22-3.164 52.41 52.41 0 0 0 6.195-2.724 43.148 43.148 0 0 0 1.023 5.89m13.27-24.392c-1.034-.13-.497.348-.785 1.7-1.246 5.832-6.05 10.035-10.873 12.855-.506-6.678-.3-14.093.967-18.636 1.069-3.836 2.34-3.132.763-3.938-1.66-.848-3.44.273-4.882 3.13C19.033 4.68 12.393 20.19 1.78 30.664c-5.43 5.36-10.34 2.6-11.323 1.775-.8-.67-1.096.365-.103 1.426 4.39 4.7 10.805 2.003 13.141-.314 6.455-6.405 13.96-20.193 16.996-26.044a89.89 89.89 0 0 0 .243 15.294 44.69 44.69 0 0 1-7.619 2.885c-1.504.391-2.435 1-2.462 1.691-.03.758.98 1.397 2.44 2.085 2.6 1.226 10.216 4.798 12.093 5.878 1.606.925 2.39.204 2.866-.796.622-1.302-1.083-2.054-2.735-2.545a50.47 50.47 0 0 1-1.48-8.385c3.87-2.365 7.682-5.52 9.88-9.452a18.004 18.004 0 0 0 1.568-4.365c.23-.934.293-1.9.186-2.855 0 0-.03-.209-.186-.229'/%3E%3C/mask%3E%3Cg mask='url(%23b)'%3E%3Crect width='31.695' height='31.695' x='.028' fill='%23fff' rx='3.048'/%3E%3C/g%3E%3C/g%3E%3Cdefs%3E%3CclipPath id='a'%3E%3Crect width='32' height='31.992' y='.008' fill='%23fff' rx='4'/%3E%3C/clipPath%3E%3C/defs%3E%3C/svg%3E";
+ "data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHdpZHRoPSczMicgaGVpZ2h0PSczMicgZmlsbD0nbm9uZSc+PHJlY3Qgd2lkdGg9JzMxLjY5NScgaGVpZ2h0PSczMS42ODgnIHg9Jy4wMjgnIGZpbGw9JyMwMEI2RUQnIHJ4PSc0Jy8+PGcgY2xpcC1wYXRoPSd1cmwoI2EpJz48bWFzayBpZD0nYicgd2lkdGg9JzQ3JyBoZWlnaHQ9JzM5JyB4PSctMTEnIHk9Jy0yJyBtYXNrVW5pdHM9J3VzZXJTcGFjZU9uVXNlJyBzdHlsZT0nbWFzay10eXBlOmFscGhhJz48cGF0aCBmaWxsPScjNTQ1ODYwJyBkPSdNMjIuMDE3IDMxLjEwM2E2My40NyA2My40NyAwIDAgMS03LjIyLTMuMTY0IDUyLjQxIDUyLjQxIDAgMCAwIDYuMTk1LTIuNzI0IDQzLjE0OCA0My4xNDggMCAwIDAgMS4wMjMgNS44OW0xMy4yNy0yNC4zOTJjLTEuMDM0LS4xMy0uNDk3LjM0OC0uNzg1IDEuNy0xLjI0NiA1LjgzMi02LjA1IDEwLjAzNS0xMC44NzMgMTIuODU1LS41MDYtNi42NzgtLjMtMTQuMDkzLjk2Ny0xOC42MzYgMS4wNjktMy44MzYgMi4zNC0zLjEzMi43NjMtMy45MzgtMS42Ni0uODQ4LTMuNDQuMjczLTQuODgyIDMuMTNDMTkuMDMzIDQuNjggMTIuMzkzIDIwLjE5IDEuNzggMzAuNjY0Yy01LjQzIDUuMzYtMTAuMzQgMi42LTExLjMyMyAxLjc3NS0uOC0uNjctMS4wOTYuMzY1LS4xMDMgMS40MjYgNC4zOSA0LjcgMTAuODA1IDIuMDAzIDEzLjE0MS0uMzE0IDYuNDU1LTYuNDA1IDEzLjk2LTIwLjE5MyAxNi45OTYtMjYuMDQ0YTg5Ljg5IDg5Ljg5IDAgMCAwIC4yNDMgMTUuMjk0IDQ0LjY5IDQ0LjY5IDAgMCAxLTcuNjE5IDIuODg1Yy0xLjUwNC4zOTEtMi40MzUgMS0yLjQ2MiAxLjY5MS0uMDMuNzU4Ljk4IDEuMzk3IDIuNDQgMi4wODUgMi42IDEuMjI2IDEwLjIxNiA0Ljc5OCAxMi4wOTMgNS44NzggMS42MDYuOTI1IDIuMzkuMjA0IDIuODY2LS43OTYuNjIyLTEuMzAyLTEuMDgzLTIuMDU0LTIuNzM1LTIuNTQ1YTUwLjQ3IDUwLjQ3IDAgMCAxLTEuNDgtOC4zODVjMy44Ny0yLjM2NSA3LjY4Mi01LjUyIDkuODgtOS40NTJhMTguMDA0IDE4LjAwNCAwIDAgMCAxLjU2OC00LjM2NWMuMjMtLjkzNC4yOTMtMS45LjE4Ni0yLjg1NSAwIDAtLjAzLS4yMDktLjE4Ni0uMjI5Jy8+PC9tYXNrPjxnIG1hc2s9J3VybCgjYiknPjxyZWN0IHdpZHRoPSczMS42OTUnIGhlaWdodD0nMzEuNjk1JyB4PScuMDI4JyBmaWxsPScjZmZmJyByeD0nMy4wNDgnLz48L2c+PC9nPjxkZWZzPjxjbGlwUGF0aCBpZD0nYSc+PHJlY3Qgd2lkdGg9JzMyJyBoZWlnaHQ9JzMxLjk5MicgeT0nLjAwOCcgZmlsbD0nI2ZmZicgcng9JzQnLz48L2NsaXBQYXRoPjwvZGVmcz48L3N2Zz4=";
// *****
// Hooks
@@ -198,6 +198,7 @@
}
function setTooltipPos(label: string, el: HTMLElement) {
+ if (!_containerEl || !_tooltipEl) return;
const rect = el?.getBoundingClientRect();
const containerRect = _containerEl.getBoundingClientRect();
const top = rect.top - containerRect.top + rect.height / 2;
@@ -218,7 +219,7 @@
}
function handleToggleHover() {
- if (open) return;
+ if (open || !_toggleButtonEl) return;
setTooltipPos("Expand menu", _toggleButtonEl);
showTooltip();
@@ -378,12 +379,12 @@
{#if url}
-
+
{heading}
{:else}
-
+
{heading}
{/if}
@@ -477,6 +478,13 @@