From 48e9aed4f71387984e84eca479ffa5b514607823 Mon Sep 17 00:00:00 2001 From: Anthony Vitacco Date: Fri, 21 Aug 2026 21:28:31 -0400 Subject: [PATCH 1/2] Initial a11y pass This a first pass sweep of both the components and documentation site pages to improve overall accessibility. I intend to have another pass in the future to improve things further for people with colorblindness and dyslexia. Signed-off-by: Anthony Vitacco --- docs/_layouts/default.html | 3 +- docs/_layouts/home.html | 1 + docs/index.md | 4 ++ docs/src/site.css | 55 +++++++++++++++++-- src/components/accordion/vox-accordion.ts | 7 ++- src/components/alert/vox-alert.ts | 6 +- src/components/avatar/vox-avatar.ts | 11 +++- src/components/card/vox-card.ts | 2 +- src/components/checkbox/vox-checkbox.ts | 7 ++- src/components/dialog/vox-dialog.ts | 4 +- src/components/disclosure/vox-disclosure.ts | 7 ++- src/components/dropdown/vox-dropdown.ts | 40 +++++++++++--- src/components/empty-state/vox-empty-state.ts | 2 +- src/components/file-input/vox-file-input.ts | 5 +- src/components/header/vox-header.ts | 10 ++++ src/components/input/vox-input.ts | 2 + src/components/link-hub/vox-link-hub.ts | 2 +- .../pagination/vox-pagination.stories.ts | 8 +-- src/components/pagination/vox-pagination.ts | 15 +++-- src/components/radio/vox-radio-group.ts | 23 ++++++-- src/components/select/vox-select.ts | 3 + src/components/sidenav/vox-sidenav.ts | 17 +++++- .../step-indicator/vox-step-indicator.ts | 18 +++++- src/components/tabs/vox-tabs.ts | 28 +++++++++- src/components/textarea/vox-textarea.ts | 2 + src/internal/field.ts | 22 +++++++- src/tokens/tokens.css | 14 ++--- 27 files changed, 260 insertions(+), 58 deletions(-) diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 7f39ebc..a6caf63 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -2,6 +2,7 @@ {% include head.html %} + Skip to main content {% include nav.html %} {% assign sidebar_groups = site.data.sidebar[page.section] %}
@@ -10,7 +11,7 @@ {% include sidebar.html groups=sidebar_groups %}
{% endif %} -
+
{{ content }}
diff --git a/docs/_layouts/home.html b/docs/_layouts/home.html index 2084886..d6b9d1c 100644 --- a/docs/_layouts/home.html +++ b/docs/_layouts/home.html @@ -2,6 +2,7 @@ {% include head.html %} + Skip to main content {% include nav.html %} {{ content }} diff --git a/docs/index.md b/docs/index.md index b87ce84..c83bb20 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,6 +3,8 @@ title: VoxBlocks — Web components for the OpenVox community layout: home --- +
+
Framework-agnostic building blocks in the style of the OpenVox docs — drop them into any site, from plain HTML to Vue. @@ -28,6 +30,8 @@ layout: home
+
+ Getting Started diff --git a/docs/src/site.css b/docs/src/site.css index e6f5f15..f62169a 100644 --- a/docs/src/site.css +++ b/docs/src/site.css @@ -17,6 +17,34 @@ body { font-family: var(--vox-font-family-base); } +/* Bypass block (WCAG 2.4.1): every page tabs through the full header nav, + and doc pages through the full sidebar nav too, before reaching content — + this jumps a keyboard/screen-reader user straight past both. Off-screen + positioning (not display/visibility) keeps it in the accessibility tree + and focusable; it only becomes visible once it receives focus. */ +.vox-skip-link { + position: absolute; + top: -3rem; + left: var(--vox-space-3); + z-index: 100; + padding: var(--vox-space-2) var(--vox-space-4); + background-color: var(--vox-color-bg-elv); + color: var(--vox-color-brand-1); + border-radius: var(--vox-radius-md); + box-shadow: var(--vox-shadow-2); + font-weight: 600; + text-decoration: none; + transition: top var(--vox-transition-fast); +} + +.vox-skip-link:focus { + top: var(--vox-space-3); +} + +main:focus-visible { + outline: none; +} + /* Pages that render a real (currently just the home page) get it pinned to the viewport bottom instead of trailing short content. */ vox-footer { @@ -204,12 +232,29 @@ vox-footer { color: var(--vox-color-text-2); } -/* Rouge syntax highlighting ---------------------------------------------- */ - +/* Rouge syntax highlighting ---------------------------------------------- + * These three tokens are docs-only and have no equivalent in tokens.css, + * so (unlike everything else on this page) they were hardcoded hex values + * with no dark-mode counterpart — meaning the light-mode value was reused + * verbatim against the dark `--vox-color-bg-soft` code background, where + * two of them measured under 3.5:1 (dark) and the entity/number colors were + * already sub-4.5:1 even in light mode. Now real CSS custom properties, so + * each theme gets a value that clears 4.5:1 against its own + * `--vox-color-bg-soft`. + */ .highlight { + --vox-color-code-string: #0e7267; + --vox-color-code-entity: #6d4dad; + --vox-color-code-number: #a54b08; color: var(--vox-color-text-1); } +[data-vox-theme='dark'] .highlight { + --vox-color-code-string: #3daa9c; + --vox-color-code-entity: #9d84d6; + --vox-color-code-number: #e08a3d; +} + .highlight .c, .highlight .c1, .highlight .cm { @@ -228,7 +273,7 @@ vox-footer { .highlight .s1, .highlight .s2, .highlight .sb { - color: #0e7267; + color: var(--vox-color-code-string); } .highlight .n, @@ -244,13 +289,13 @@ vox-footer { .highlight .nb, .highlight .nc, .highlight .nf { - color: #7c5cbf; + color: var(--vox-color-code-entity); } .highlight .m, .highlight .mi, .highlight .mf { - color: #b45309; + color: var(--vox-color-code-number); } .highlight .o, diff --git a/src/components/accordion/vox-accordion.ts b/src/components/accordion/vox-accordion.ts index 3e957e5..4fa474d 100644 --- a/src/components/accordion/vox-accordion.ts +++ b/src/components/accordion/vox-accordion.ts @@ -48,9 +48,13 @@ export class VoxAccordion extends LitElement { */ @customElement('vox-accordion-item') export class VoxAccordionItem extends LitElement { + private static nextId = 0; + @property() heading = ''; @property({ type: Boolean, reflect: true }) open = false; + private readonly panelId = `vox-accordion-panel-${VoxAccordionItem.nextId++}`; + static styles = css` :host { display: block; @@ -127,6 +131,7 @@ export class VoxAccordionItem extends LitElement { -
+
`; diff --git a/src/components/alert/vox-alert.ts b/src/components/alert/vox-alert.ts index c126c96..a0b08f4 100644 --- a/src/components/alert/vox-alert.ts +++ b/src/components/alert/vox-alert.ts @@ -154,8 +154,12 @@ export class VoxAlert extends LitElement { } render() { + const isUrgent = this.variant === 'danger' || this.variant === 'warning'; return html` -