@dta-au/civictheme-twig 1.13.5 → 1.13.6

package/components/00-base/about-civictheme/about-civictheme.stories.js

@@ -4,6 +4,7 @@ import Constants from '../../../dist/constants.json';
 const meta = {
   title: 'About CivicTheme',
   component: Component,
+  tags: ['!autodocs'],
   argTypes: {
     logos: {
       table: {

package/components/00-base/collapsible/collapsible.stories.js

@@ -3,6 +3,7 @@ import Component from './collapsible.stories.twig';
 const meta = {
   title: 'Base/Utilities/Collapsible',
   component: Component,
+  tags: ['!autodocs'],
 };
 
 export default meta;

package/components/00-base/elevation/elevation.stories.js

@@ -3,6 +3,7 @@ import Component from './elevation.stories.twig';
 const meta = {
   title: 'Base/Elevation',
   component: Component,
+  tags: ['!autodocs'],
 };
 
 export default meta;

package/components/00-base/layout/__snapshots__/layout.test.js.snap

@@ -9,9 +9,8 @@ exports[`Layout Component hides sidebars when specified - contained 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-sidebar-left ct-layout--no-sidebar-right ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right"
-    role="main"
   >
     
               
@@ -36,7 +35,7 @@ exports[`Layout Component hides sidebars when specified - contained 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -51,9 +50,8 @@ exports[`Layout Component hides sidebars when specified 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-sidebar-left ct-layout--no-sidebar-right ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right"
-    role="main"
   >
     
               
@@ -78,7 +76,7 @@ exports[`Layout Component hides sidebars when specified 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -93,9 +91,8 @@ exports[`Layout Component only main - contained 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right"
-    role="main"
   >
     
               
@@ -120,7 +117,7 @@ exports[`Layout Component only main - contained 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -135,9 +132,8 @@ exports[`Layout Component only main - not contained 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right"
-    role="main"
   >
     
               
@@ -162,7 +158,7 @@ exports[`Layout Component only main - not contained 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -177,9 +173,8 @@ exports[`Layout Component renders with all sidebars and content sections 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-vertical-spacing--top"
-    role="main"
   >
     
           Top content    
@@ -232,7 +227,7 @@ exports[`Layout Component renders with all sidebars and content sections 1`] = `
     
 
           Bottom content      
-  </main>
+  </div>
   
 
 </div>
@@ -247,10 +242,9 @@ exports[`Layout Component renders with custom attributes and classes 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right  custom-modifier"
     data-test="true"
-    role="main"
   >
     
               
@@ -275,7 +269,7 @@ exports[`Layout Component renders with custom attributes and classes 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -290,9 +284,8 @@ exports[`Layout Component renders with default values 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right"
-    role="main"
   >
     
               
@@ -317,7 +310,7 @@ exports[`Layout Component renders with default values 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -332,9 +325,8 @@ exports[`Layout Component renders with sidebar bottom left 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left ct-layout--no-top-right  ct-layout--no-bottom-right ct-vertical-spacing--top"
-    role="main"
   >
     
               
@@ -366,7 +358,7 @@ exports[`Layout Component renders with sidebar bottom left 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -381,9 +373,8 @@ exports[`Layout Component renders with sidebar bottom right 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left ct-layout--no-top-right ct-layout--no-bottom-left  ct-vertical-spacing--top"
-    role="main"
   >
     
               
@@ -415,7 +406,7 @@ exports[`Layout Component renders with sidebar bottom right 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -430,9 +421,8 @@ exports[`Layout Component renders with sidebar top left 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-right ct-layout--no-bottom-left ct-layout--no-bottom-right ct-vertical-spacing--top"
-    role="main"
   >
     
               
@@ -464,7 +454,7 @@ exports[`Layout Component renders with sidebar top left 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>
@@ -479,9 +469,8 @@ exports[`Layout Component renders with sidebar top right 1`] = `
 
 
   
-  <main
+  <div
     class="ct-layout ct-layout--no-top-left  ct-layout--no-bottom-left ct-layout--no-bottom-right ct-vertical-spacing--top"
-    role="main"
   >
     
               
@@ -513,7 +502,7 @@ exports[`Layout Component renders with sidebar top right 1`] = `
     
 
                 
-  </main>
+  </div>
   
 
 </div>

package/components/00-base/layout/layout.twig

@@ -57,7 +57,7 @@
 {% set modifier_class = modifier_class|trim %}
 
 {% if content %}
-  <main class="ct-layout {{ modifier_class -}}" role="main" {% if attributes is defined and attributes is not null %}{{- attributes -}}{% endif %}>
+  <div class="ct-layout {{ modifier_class -}}" {% if attributes is defined and attributes is not null %}{{- attributes -}}{% endif %}>
     {% block content_top_block %}
       {% if content_top is not empty %}
         {{- content_top -}}
@@ -111,5 +111,5 @@
         {{- content_bottom -}}
       {% endif %}
     {% endblock %}
-  </main>
+  </div>
 {% endif %}

package/components/00-base/responsive/responsive.stories.js

@@ -3,6 +3,7 @@ import Component from './responsive.stories.twig';
 const meta = {
   title: 'Base/Utilities/Responsive',
   component: Component,
+  tags: ['!autodocs'],
 };
 
 export default meta;

package/components/00-base/scrollspy/scrollspy.stories.js

@@ -3,6 +3,7 @@ import Component from './scrollspy.stories.twig';
 const meta = {
   title: 'Base/Utilities/Scrollspy',
   component: Component,
+  tags: ['!autodocs'],
 };
 
 export default meta;

package/components/00-base/spacing/spacing.stories.js

@@ -3,6 +3,7 @@ import Component from './spacing.stories.twig';
 const meta = {
   title: 'Base/Spacing',
   component: Component,
+  tags: ['!autodocs'],
 };
 
 export default meta;

package/components/00-base/typography/typography.stories.js

@@ -3,6 +3,7 @@ import Component from './typography.stories.twig';
 const meta = {
   title: 'Base/Typography',
   component: Component,
+  tags: ['!autodocs'],
 };
 
 export default meta;

package/components/00-base/welcome/welcome.stories.js

@@ -4,6 +4,7 @@ import Constants from '../../../dist/constants.json';
 const meta = {
   title: 'Welcome',
   component: Component,
+  tags: ['!autodocs'],
   argTypes: {
     logos: {
       table: {

package/components/01-atoms/iframe/iframe.mdx

@@ -0,0 +1,56 @@
+{/* Editorial guidance ported from the digital.gov.au design library (dga-dl /src/content). */}
+{/* Internal /patterns and /templates links demoted to plain text – they do not resolve in Storybook. */}
+
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as Stories from './iframe.stories';
+
+<Meta of={Stories} />
+
+# iFrame
+
+A callout draws attention to important or interesting information.
+
+<Canvas of={Stories.Iframe} />
+
+<Controls of={Stories.Iframe} />
+
+<div style="box-sizing: border-box;
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    border-width: 0;
+    border-left-width: 1px;
+    border-right-width: 1px;
+    border-top-width: 1px;
+    border-bottom-width: 1px;
+    border-color: var(--ct-color-light-border-light);
+    border-style: solid;
+    border-radius: 4px;">
+<Canvas of={Stories.Iframe} />
+</div>
+
+
+Use callout to draw a user's attention to important snippets of static information.
+
+## Do
+
+- use sparingly as they are intrusive
+- use to help users quickly scan to find essential information in a long text page
+- use to reiterate important content
+- use to format content not included in the main text such as support and contact details, checklists, definitions and 'Did you know?' content.
+
+## Don't
+- use for primary content, as it may be missed
+- use for quotes in long-form content - use a **Quote** instead
+- make them the focus of content; they are a supporting tool
+- use for errors and alerts – use an alert or message instead
+- embed form inputs in Callouts
+- use in conditionally revealed checkbox or radio groups
+- mix colour palettes.
+
+## Related components
+- Global alert – Global alerts display prominent service or system wide messages at the top of the screen.
+- Message – A message is a colour-coded, non-disruptive notification that provides Success, Error, Warning or Information messages within a page at relevant times during the user journey. They should not be confused with Callouts.
+
+## Related patterns
+- Messaging – Messaging conveys contextual information to the user, provides information in relation to a service or interaction, and provides feedback in response to their actions or the current system status.

package/components/01-atoms/summary-list/summary-list.mdx

@@ -1,8 +1,7 @@
-{/* Generated by packages/sdc/scripts/import-dga-dl-docs.js — re-run to refresh. */}
-{/* Source: digital.gov.au design library (dga-dl /src/content). */}
-{/* Cross-link rewrites deferred to beads ui-kit-dev-space-r0f — links may be broken. */}
+{/* Editorial guidance ported from the digital.gov.au design library (dga-dl /src/content). */}
+{/* Internal /patterns and /templates links demoted to plain text – they do not resolve in Storybook. */}
 
-import { Meta, Canvas } from '@storybook/addon-docs/blocks';
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
 import * as Stories from './summary-list.stories';
 
 <Meta of={Stories} />
@@ -13,6 +12,8 @@ A structured list of name–value pairs for displaying record summaries and meta
 
 <Canvas of={Stories.Default} />
 
+<Controls of={Stories.Default} />
+
 Use a summary list to display structured information as labelled name–value pairs. Typical uses include review and confirm screens before form submission, metadata panels on record or profile pages, and read-only summaries of collected data.
 
 The component renders as a styled `<dl>` element with `<dt>` (term) and `<dd>` (description) pairs.
@@ -27,11 +28,11 @@ The component renders as a styled `<dl>` element with `<dt>` (term) and `<dd>` (
 ## When not to use
 
 - for content that needs running prose – use a rich text body instead
-- when the data is tabular with multiple columns of comparable items – use a [Table](/components/table/) instead
-- for navigational lists – use [Manual list](/components/manual-list/) or [Feature link list](/components/feature-link-list/) instead
+- when the data is tabular with multiple columns of comparable items – use a **Table** instead
+- for navigational lists – use **Manual list** or **Feature link list** instead
 - when there are only one or two pairs – a simple paragraph is sufficient
 
 ## Related components
 
-- [Table](/components/table/) – use when data has multiple comparable rows and columns.
-- [Content](/components/content/) – use for free-form body text and formatted content.
+- **Table** – use when data has multiple comparable rows and columns.
+- **Content** – use for free-form body text and formatted content.

package/components/01-atoms/table/table.mdx

@@ -0,0 +1,65 @@
+{/* Editorial guidance ported from the digital.gov.au design library (dga-dl /src/content). */}
+{/* Internal /patterns and /templates links demoted to plain text – they do not resolve in Storybook. */}
+
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as Stories from './table.stories';
+
+<Meta of={Stories} />
+
+# Table
+
+A structured display of data in rows and columns.
+
+<Canvas of={Stories.Table} />
+
+<Controls of={Stories.Table} />
+
+Use tables to present data that users need to scan, compare, or look up. Tables work well when information has a clear row-and-column structure and relationships between cells matter.
+
+## When to use
+
+- data has a meaningful row-and-column structure
+- users need to compare values across rows or columns
+- the data cannot be adequately expressed as a list or prose
+
+## When not to use
+
+- for layout purposes – tables are for data, not for arranging page elements
+- when the data has only one column – a list is more appropriate
+- when all rows contain the same value in most columns – reconsider the data structure
+
+## Variants
+
+### Standard
+
+A basic table with column headers, an optional caption, and optional zebra striping for readability.
+
+### Sortable
+
+Column headers become interactive sort controls. Clicking a header sorts that column ascending; clicking again sorts descending. Only one column sorts at a time. Sort direction is indicated with an icon.
+
+### Filterable
+
+Connects to the search-filters pattern. Three filter configurations apply depending on the number of filters:
+
+- **Small (1–2 filters):** filters appear inline above the table; no applied filter tags are needed.
+- **Medium (3–6 filters):** primary filters appear inline; remaining filters appear in an accordion triggered by 'Show filters'; applied filters are shown as dismissible tags.
+- **Large (6+ filters):** primary filters appear inline; remaining filters appear in a drawer triggered by 'Show filters'; the drawer has Apply, Clear, Close, and Cancel actions; applied filters are shown as dismissible tags.
+
+### Wide tables
+
+When table content overflows its container, a custom horizontal scrollbar renders at the bottom of the table. The scrollbar sticks to the bottom of the viewport when the bottom of the table is off-screen, so users can scroll horizontally from any row.
+
+### Spanning cells
+
+Cells can span multiple columns (`colSpan`) or rows (`rowSpan`) to represent data with genuinely hierarchical relationships. Use spanning cells only when the data relationship is inherently multi-dimensional. Do not use them to create visual layout effects.
+
+## Related components
+
+- **Filter sidebar** – use when filters should be persistently visible in a sidebar alongside the table.
+- **Summary list** – use for structured name–value pairs rather than rows-and-columns data.
+
+## Related patterns
+
+- Search filters – use to connect filter controls to a filterable table.
+- Pagination – use to limit the number of rows displayed at once in large datasets.

package/components/01-atoms/table-sort/table-sort.stories.js

@@ -8,19 +8,16 @@
  * Pre-sorted columns: add aria-sort="ascending|descending" to a <th>.
  * Custom sort values: add data-sort-value="..." to a <td>.
  *
- * CSS and JS are imported explicitly here because the sdc-plugin auto-discovers
- * assets via Twig imports — this component has no Twig template, so they must
- * be declared manually.
+ * In the twig package, CSS is bundled globally via civictheme.storybook.css,
+ * so no per-component CSS imports are needed — only the behaviour JS.
+ *
+ * @sync-ignore
+ * This file intentionally drifts from the SDC source: the SDC version imports
+ * per-component .css files so sdc-plugin can discover them; the twig Storybook
+ * build has no such files and resolves them globally.
  */
 
-import './table-sort.css';
 import './table-sort.js';
-// table.js sets data-title attrs on tbody cells so mobile pseudo-element labels
-// render; table.css carries the matching `content: attr(data-title)` rule. The
-// sdc-plugin only auto-loads sibling assets via Twig imports — this atom has no
-// Twig template, so the table assets must be pulled in explicitly.
-import '../table/table.js';
-import '../table/table.css';
 
 const meta = {
   title: 'Content/Tables/Table sort',

package/components/01-atoms/tag/tag.mdx

@@ -0,0 +1,51 @@
+{/* Editorial guidance ported from the digital.gov.au design library (dga-dl /src/content). */}
+{/* Internal /patterns and /templates links demoted to plain text – they do not resolve in Storybook. */}
+
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as Stories from './tag.stories';
+
+<Meta of={Stories} />
+
+# Tag
+
+A short label that signals status, audience, document type, or another classification axis.
+
+<Canvas of={Stories.Tag} />
+
+<Controls of={Stories.Tag} />
+
+A tag is a short label – usually one to three words – that classifies a page along an axis other than its title. Tags appear most often in page banners, where they signal status ('Mandatory', 'Draft'), audience or scope ('Whole-of-government'), document type ('Plan', 'Communique', 'Case study'), or a temporal horizon ('2025–2027').
+
+Tags carry information that travels with screenshots and search-result snippets. A reader who sees only the banner of a rule page should still know whether the rule is mandatory.
+
+## When to use
+
+Use a tag in a page banner when:
+
+- the page is a rule and its mandatory status needs to be visible
+- the page is one of a numbered set and its position in a second classification axis matters (for example, a statement's lifecycle stage)
+- the page is a published artefact whose document type is not obvious from the title (a case study, a communique, a plan)
+- the page is dated or versioned and that information is part of the page's identity
+
+A single page may carry one tag or a tag-list of two to four. More than four tags in a banner is a sign that the page's identity is unclear and the tags are doing the work the title should do.
+
+## When not to use
+
+Do not use a tag for:
+
+- topical taxonomy ('AI', 'investment') – that belongs in the site's content tagging system, not the page banner
+- the section the page lives in – breadcrumb covers that
+- a call to action – that belongs in a **callout** or **next step**
+
+Section landing pages do not typically carry banner tags – they are navigation surfaces, not classified artefacts.
+
+## Tag-list
+
+A tag-list is a horizontal group of two or more tags shown together. Use a tag-list when a page sits at the intersection of two or more classification axes – for example, a statement that is both 'Mandatory' and 'Lifecycle: Design'.
+
+Order the tags in the list from most general to most specific: status before audience before topic before date.
+
+## Related components
+
+- **Callout** – for the page's most important sentence; not a substitute for a tag.
+- **Banner** – the page header that hosts tags.

package/components/02-molecules/accordion/accordion.mdx

@@ -0,0 +1,70 @@
+{/* Editorial guidance ported from the digital.gov.au design library (dga-dl /src/content). */}
+{/* Internal /patterns and /templates links demoted to plain text – they don't resolve in Storybook. */}
+
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as Stories from './accordion.stories';
+
+<Meta of={Stories} />
+
+# Accordion
+
+An accordion lets users show and hide sections of related content.
+
+<Canvas of={Stories.Accordion} />
+
+<Controls of={Stories.Accordion} />
+
+## When to use this component
+
+Only use an accordion if there's evidence it's helpful for the user to:
+
+- see an overview of multiple, related sections of content
+- choose to show and hide sections that are relevant to them
+- look across information that might otherwise be on different pages
+
+For example, an accordion can work well if the user needs to reveal and compare information that's relevant to them.
+
+Accordions can also work well for people who use a service regularly. For example, users of caseworking systems who need to do familiar tasks quickly.
+
+Test with users to decide if using an accordion outweighs the potential problems with hiding content.
+
+## When not to use this component
+
+Accordions hide content from the user. Not all users will notice them or understand how they work. For this reason, you should only use them in specific situations and if user research supports it.
+
+Do not use an accordion for content that all users need to see.
+
+Test your content without an accordion first. Well-written and structured content can remove the need to use an accordion.
+
+It's usually better to:
+
+- simplify and reduce the amount of content
+- split the content across multiple pages
+- keep the content on a single page, separated by headings
+- use a list of links at the start of the page (known as 'anchor links') to take the user to particular sections of a page
+
+Accordions work best for simple content and links. Do not use accordions to split up a series of questions. Use separate pages instead.
+
+Do not put accordions within accordions, as it will make content difficult to find.
+
+Do not use the accordion component if the amount of content inside will make the page slow to load.
+
+## Canonical anti-patterns
+
+These are the recurring misuses of the accordion on digital.gov.au. Each one destroys something the page was trying to do.
+
+**Standards or criteria collapsed into accordion panels.** Each criterion has its own URL, its own deep-link target, and is referenced individually from compliance reviews, search results, and JSON-LD `hasPart` relationships. Hiding criteria inside accordion panels destroys those references. Use a card grid of **navigation cards** instead, with each criterion linking to its own **rule page**.
+
+**Glossary terms collapsed into accordion panels.** Glossaries are skimmed, not browsed. An accordion forces a click per lookup, and the [DefinedTermSet](https://schema.org/DefinedTermSet) JSON-LD shape is lost when the term and definition are not co-located in the rendered DOM. Use semantic `<dl>`/`<dt>`/`<dd>` markup instead.
+
+**Checklist items collapsed into accordion panels.** Checklists must be readable end-to-end and printable. An accordion breaks both. Use a real ordered or unordered list.
+
+**Inputs and outputs of a framework step collapsed into accordion panels.** A reader on step 7 of a framework often needs to cross-check step 4's outputs. Hiding step structure behind accordions makes the framework harder to use, not easier.
+
+**'FAQ-style' accordion on an explainer page.** If the questions are real and the answers are useful, write them as `<h3>` body sections – they then appear in search results and an in-page table of contents. Accordion-FAQ on an explainer hides the answers from readers who skim.
+
+## Canonical right uses
+
+The right place for an accordion is a **reference FAQ** – each question is independently a lookup key, the page is long, and the user usually wants only one answer.
+
+Even there, apply callout discipline: if a single question accounts for the bulk of reader traffic, lift its answer into a callout above the accordion. The accordion handles the long tail.

package/components/02-molecules/attachment/attachment.mdx

@@ -0,0 +1,40 @@
+{/* Editorial guidance ported from the digital.gov.au design library (dga-dl /src/content). */}
+{/* Internal /patterns and /templates links demoted to plain text – they do not resolve in Storybook. */}
+
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as Stories from './attachment.stories';
+
+<Meta of={Stories} />
+
+# Attachment
+
+An attachment block draws attention to files which can be downloaded.
+
+<Canvas of={Stories.Attachment} />
+
+<Controls of={Stories.Attachment} />
+
+Use callout to draw a user's attention to important snippets of static information.
+
+## Do
+
+- use sparingly as they are intrusive
+- use to help users quickly scan to find essential information in a long text page
+- use to reiterate important content
+- use to format content not included in the main text such as support and contact details, checklists, definitions and 'Did you know?' content.
+
+## Don't
+- use for primary content, as it may be missed
+- use for quotes in long-form content - use a **Quote** instead
+- make them the focus of content; they are a supporting tool
+- use for errors and alerts – use an alert or message instead
+- embed form inputs in Callouts
+- use in conditionally revealed checkbox or radio groups
+- mix colour palettes.
+
+## Related components
+- Global alert – Global alerts display prominent service or system wide messages at the top of the screen.
+- Message – A message is a colour-coded, non-disruptive notification that provides Success, Error, Warning or Information messages within a page at relevant times during the user journey. They should not be confused with Callouts.
+
+## Related patterns
+- Messaging – Messaging conveys contextual information to the user, provides information in relation to a service or interaction, and provides feedback in response to their actions or the current system status.