mantra_starter audit: fix inconsistencies, unused code, responsive and accessibility issues

Context

Audit of web/themes/custom/mantra_starter made on 2026-11-11. Paths below are relative to the theme. Line numbers are from the day of the audit and may have moved since.

What was checked

• Every CSS, JS, Twig, component and PHP file in the theme was read.
• A fresh vite build was compared with the committed dist/.
• Stylelint and ESLint were run over the theme.
• 13 pages on theme, retrograde and contrib were loaded at 320, 375, 768, 1024 and 1440px, logged out and logged in, and scanned with axe-core (WCAG 2.2 AA plus best practice).

Results in brief

• No page tested overflowed horizontally at any width.
• Axe reported:
  • target-size (serious, 96 nodes)
  • listitem and list on admin pages
  • landmark-unique on pages with sidebars
  • page-has-heading-one on front pages
  • heading-order (the pager's <h4>)
  • label-title-only
• Axe found no color-contrast failures on the pages it scanned. The contrast problems listed below are in states and modules it didn't reach.

The full report, with about 250 findings, is in the local checkout at scratchpad/theme-audit/REPORT.md, with screenshots and the raw axe output beside it.

TODO

Fix first

• Restore a focus outline on links: libraries/global/variables.css:66 sets --link-focus-outline-style: none, so the only focus cue is a 1px underline change.
• Fix the tokens that refer to themselves in variables.css:46,48,83,88,113,115,125,139, such as --link-color: var(--link-color) and --border-color: var(--border-color). They are invalid at :root, and so is every token built from them (--link-*-color, --table-border-color, --input-border, --button-border).
• Give the root font-size clamp in base/typography.css:16 rem bounds instead of px, so it respects the browser's font-size setting (WCAG 1.4.4). Body text is 12px on phones.
• Status messages (templates/misc/status-messages.html.twig:42,49): title_ids is never set, so the output is aria-labelledby="" and <h2 id="">. role="contentinfo" adds a second contentinfo landmark, and status and warning messages have no role="status".
• Swiper (components/swiper/swiper.js, swiper.twig):
  • Add once() and use context; today every AJAX or BigPipe attach creates a new instance.
  • Make the arrows real buttons (they are <div>s, the bullets <span>s) and import the A11y module.
  • Import Scrollbar, which is configured but never imported.
• Mobile menu (responsive_menu_toggle.js:46-64): close on Escape, move focus into the panel and back to the toggle, and make the page behind it inert.
• Flyout menus (menu/menu.js:169-173, menu.css:161-165): Escape can't close one held open by :hover or :focus-within, and focus is never returned (WCAG 1.4.13).
• libraries/drupal/node.css:10,12 reads --unpublished-color, which doesn't exist (the token is --color-unpublished), so unpublished nodes aren't highlighted.
• libraries/modules/calendar.css:25 puts white text on #f3faef, a contrast of 1.05:1.
• libraries/drupal/field-ui-add-field_module.component.css reads var(--color-focus), which is commented out, so the field-type cards have no focus ring.
• libraries/modules/chosen.theme.css:
  • The highlighted option is white on #0a0 (3.1:1), and lines 157 and 264 remove the outline.
  • Drop the copy of chosen.css bundled in the file (~400 lines); chosen_lib loads it already.
• Border colors set with @apply (base/elements.css:48,77, component/details.css:38) compile to var(--un-border-opacity), which isn't registered on most pages, so --table-border-color and --details-border-color have no effect. Write plain border-color.
• Broken component markup:
  • The gallery and content_w_sidebar slots are empty {% block %}s, so include() renders nothing in them.
  • heading with no tag outputs < …></>; add |default.
  • card_grid.twig:10 has a stray ".
• components/table/table.component.yml:41-42: the column header has no type, which makes Canvas throw a TypeError.
• The project .stylelintignore rule **/libraries/**, meant for web/libraries, also excludes the theme's libraries/ folder. Linting those files shows 911 problems. Also teach the config about @apply, which triggers at-rule-prelude-no-invalid.
• components/layout/page/page.twig:
  • Label the two sidebar <aside role="complementary"> elements and move them out of <main>.
  • Drop role="main".
  • Move the empty <a id="main-content"> skip target into <main>.
• block--local-actions-block.html.twig prints <li> inside <nav> with no <ul> (axe listitem on every admin listing).

@apply

• Convert the safe 1:1 spacing, flex and grid declarations to @apply (see Done).
• Convert zero resets to @apply (see Done).
• Use the d-block, d-inline and d-table shortcuts for blocklisted display values (see Done).
• menu.css:93,164 use the deprecated display-block; now d-block.
• component/form.css:29: @apply text-smaller compiles to nothing; use font-size: smaller. The same goes for text-md (system.admin.theme.css:35) and bg-base (chosen.theme.css:411).
• Replace with plain CSS the @apply uses that ISSUES.md lists as fragile (bg-*, text-white, leading-*, border colors):
  • hero.css, card.css:25, branding.css, elements.css, links.css, typography.css
  • drd.css, reference.css, formtips.component.css, chosen.theme.css, ckeditor-code.css
  • page_header.css, page_footer.css, page.css, menu.css, responsive_menu.css, views.css:86-89

  The @property descriptors these leak still sit in 8 dist/ files.

• media-library.css:208: @apply container adds page gutters and a max-width to every media item.
• responsive_menu_toggle.css:2 applies w-8 and w-[1.5em] together.
• smart_date.css:109: display: inline is still plain CSS, because @apply in that nested rule reaches dist/ unexpanded (comment in the file). Find out why the transformer skips it.
• Decide on the hand-written .display-block, .display-inline-block and .display-none classes in utilities/layout.css (!important, used by no template).

Build and tokens

• Use one gap scale. .gap-sm and .gap-lg ship twice: from the UnoCSS safelist (0.875rem) and hand-written in utilities/space.css (0.5rem and 2rem).
• Delete or rename .gap-x-0…4 and .gap-y-0…4 in utilities/space.css. They reuse UnoCSS names at four times UnoCSS's values.
• Remove the hand-written copies of UnoCSS utilities: .flex… (layout-flex.css), .grid, .h-full, .border.
• Remove the safelist.txt entries that generate nothing (gap-md, text-smaller, prose, …).
• Make the build reproducible: a rebuild reorders the variable list in dist/unocss.css.
• Remove unused build output and packages:
  • Build output: ckeditor-code.css, the empty details.js, swiper2.css.
  • npm packages: browser-sync, vite-plugin-browser-sync, vite-plugin-live-reload, concurrently, @julr/unocss-preset-forms, unocss-preset-fluid.
  • bs.config.js.
• Add engines: node >= 20 to package.json.
• Fix component/button.css:14: var(--button-border) should be --button-border-radius. Also, --button-hover-text-decoration cancels the hover underline.
• Fix the --link-*-text-decoration-style: underline values, which are invalid (variables.css:55,59).
• Use fallbacks at the point of use for combined link tokens, so a component that overrides --link-color also reaches a:visited.
• Fix or define the variables that are read but never set:
  • --background-color-lighter, --background-color, --text-color, --font-family-monospace, --link-decoration
  • --ck-fucus-ring (typo)
• Delete the ~25 variables that are set but never read.
• Replace hard-coded colors with tokens, and add a z-index scale.
• Use logical properties where RTL breaks today: elements.input.css:140, table.css:326, file.css:12.

Unused code

• Fix the attach_library() calls to libraries that don't exist: menu-local-tasks.html.twig:14 (mantra_starter/tabs) and views-exposed-form.html.twig:12 (exposed-filters; the library is named exposed_filters).
• Attach or delete the coffee and image_widget libraries, which are never attached.
• Remove overrides and extends that target files or libraries that no longer exist: ckeditor_details, item-list.module.css, system-status-report-general-info.css, node/drupal.node, node/form, views_ui/admin.
• Remove the CSS for modules that aren't in the codebase: field-ui-extras, cl-editorial, disclosure-menu, extlink, sdc_tags, ajax_loader.
• Print or remove the four declared regions that are never printed: drawer_first, drawer_second, sidebar_outer_first, sidebar_outer_second.
• Delete the unused files base/styles.css, component/collapse-processed.css, component/media.css, and the unused selectors in utilities/space.css.
• Decide on the 10 components that nothing references: button, buttons_demo, card_grid, hero, container, link, tabs, reference, tag, field. Also decide on primary_nav.
• Remove the templates that are identical to core or never used: input--submit--remove-button, the two links.html.twig, logo-1.svg.twig, and ~11 more.
• Merge the duplicated logic: two near-identical dropdown CSS and JS stacks, three disclosure systems, three pager implementations, and identical field--node--created/title/uid templates.
• Remove unused assets: the Lobster font (5 files), unreferenced icons and PNGs, and the 0-byte drupalicon.svg.
• Move COLOR-AUDIT.html out of the theme; it is publicly served.

Responsive

• Align breakpoints.yml (384/576/768/1024/1600/1920, with three identical entries) with UnoCSS (384/640/768/1024/1280/1536), and remove raw 600px, 769px and similar values from the CSS.
• Sidebars stack under the content until 1280px (page.css). At xl they get a permanent scrollbar; use overflow-y: auto.
• views-view-grid.html.twig keeps fixed percentage columns at every width.
• Wrap tables in formatted text in a scroll container.
• card_grid is fixed at 3 columns, container.css has a fixed 36rem width, and the password fields in user.css are 55% wide at every size.
• layout-sidebar: the meta region comes before the content in the DOM, and overflow-hidden above 768px clips focus rings and dropbuttons.
• responsive_menu_toggle.js hard-codes 768 on the header width; use matchMedia('(min-width: 48rem)').
• Touch targets smaller than 24px: menu expand buttons (16px), the breadcrumb dropdown, tabledrag handles, Swiper bullets.

Accessibility

• Use :focus-visible instead of :focus (elements.link.css, button.css, navigation-theme.css, formtips), and fix the weak dropbutton and toolbar focus styles.
• Make .table-scroll wrappers keyboard-reachable: tabindex="0", role="region" and an aria-label.
• Give dropbutton.js aria-expanded and an Escape handler.
• Give menu expand buttons distinct names (all are "Expand"), aria-controls, and an aria-expanded that stays in step with hover and focus.
• Restore the headings that templates drop: dataset/item-list.html.twig, the views grouping titles, the comment title, the card title.
• Show the maintenance page title.
• Respect display_submitted in node.html.twig.
• Pager:
  • Use pagination_heading_level instead of the hard-coded <h4>.
  • Add aria-current.
• Breadcrumb:
  • Add aria-current.
  • Replace the hard-coded id.
• Remove redundant landmark roles.
• Add role="search" to search_box.
• Hide the toggle SVGs with aria-hidden.
• Contrast: the #0a0 accent is 3.1:1 as text (.marker, required asterisk); the Layout Builder remove icon is 1.9:1.
• Add @media (forced-colors: active) rules. Today table borders, hr, selected rows, mask icons and selected tabs disappear in Windows high-contrast mode.
• Respect reduced motion in loading.svg, the transitions in drd.css and user.css, and Swiper.

PHP, templates, components

• Change core_version_requirement to ^11.3.
• Replace the deprecated theme_get_setting() call, which runs twice on every page.
• Favicons:
  • Respect the base path in the favicon URLs.
  • Add a root favicon.ico; pages now carry two favicons.
  • Fill in manifest.webmanifest.
• Move site-specific code out of the starter theme: taxonomy_term_location_form and the DRD menu retitling.
• Move all hooks into src/Hook with dependency injection.
• Replace the deprecated {% apply spaceless %}.
• Templates that drop attributes or content: node--card, media--image--screenshot, paragraph--gallery. Also, views-view.html.twig renders the header twice.
• JS: add detach handlers, declare core/jquery in tableHeader.js, and fix dialogNoScroll.js, which treats a native listener as a jQuery one.
• Component schemas:
  • Empty enum values in drupal_logo.
  • Twig reading variables the schema doesn't declare.
  • Declared props that are never used.
  • Stories that don't match their schemas.
  • Story images that 404.
  • Components missing $schema.

Docs

• Update README.md and ISSUES.md, which point at files that have moved or no longer exist, and the stale libraries/global/component/TODO.md.
• Fix British spellings (centred, colour, behaviour, focussed, …) and the pa=dding typo in paragraphs_widget.css.

Done

How each step was checked: after every step the theme was rebuilt, and the final value of every margin, padding, gap and display property in the built CSS was compared, rule by rule, with the build from before any of this work. Stylelint was run on the changed files before and after each step. Caches were cleared on theme, retrograde and contrib.

• Converted safe spacing, flex and grid declarations to @apply, in 17 files:
  • tabs, form, todo-list, breadcrumbs, field, details
  • views, system-admin.component, system.admin.theme, dialog, field-ui-add-field_module.component, views_ui.admin.theme, media-library
  • facets, card, screenshot, content_w_sidebar

  The built CSS has the same values as before. The only differences:

  • margin-inline: 0 was dropped on nav.tabs, .breadcrumb, .comment-wrapper and .table-filter, which have no default side margins.
  • .views-row now gets 1rem directly. Its theme('spacing.DEFAULT') call is gone.

  @apply lines are placed where the project's stylelint ordering rules want them.

• Removed the warning at utilities/layout.css:41. .table-scroll now uses @apply overflow-x-auto max-w-full min-w-0.
• Converted 74 zero resets (margin: 0, padding: 0, margin-block-end: 0, …) to @apply in the same files plus list_items.css. Where a rule already had an @apply, the zero joined it. None of them moved past a non-zero setting of an overlapping property, and the built CSS values are unchanged.
• Used the d-block, d-inline and d-table shortcuts in place of 34 plain display: block|inline|table declarations, and replaced @apply display-block in menu.css:93,164. The built CSS is byte-identical. Files:
  • form, breadcrumbs, field, views_ui.admin.theme, media-library, system-admin.component, screenshot
  • menu_link, block-admin.theme, ckeditor, dropbutton, layout-builder.theme, autocomplete, button, icons, item-list, tablesort
  • chosen.theme, drd, fullcalendar
• Removed the deprecated display-block, display-table and container-layout shortcuts from uno.config.js. Nothing used them.

Not committed yet. Commit the source files together with the rebuilt dist/*.css.