From ce646b7607f7e9aa71c34f97dd54a1b1d707eaca Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Wed, 3 Dec 2025 10:07:54 -0500 Subject: [PATCH 1/7] docs: trying out storybook doc blocks --- 2nd-gen/packages/swc/.storybook/main.ts | 9 ++++ 2nd-gen/packages/swc/.storybook/preview.ts | 2 +- .../progress-circle/docs/1_usage.mdx | 43 +++++++++++++++++++ .../stories/progress-circle.stories.ts | 1 + 4 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 2nd-gen/packages/swc/components/progress-circle/docs/1_usage.mdx diff --git a/2nd-gen/packages/swc/.storybook/main.ts b/2nd-gen/packages/swc/.storybook/main.ts index 0584d96a736..f0e890b2e18 100644 --- a/2nd-gen/packages/swc/.storybook/main.ts +++ b/2nd-gen/packages/swc/.storybook/main.ts @@ -6,6 +6,10 @@ const __dirname = dirname(fileURLToPath(import.meta.url)); /** @type { import('@storybook/web-components-vite').StorybookConfig } */ const config = { + docs: { + autodocs: 'tag', // or true + defaultName: 'Usage', // Change 'Docs' to 'Component Documentation' + }, stories: [ { directory: 'get-started', @@ -17,6 +21,11 @@ const config = { files: '*/stories/*.stories.ts', titlePrefix: 'Components', }, + { + directory: '../components', + files: '*/docs/*.mdx', + titlePrefix: 'Components', + }, { directory: 'guides', files: '*.mdx', diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts index 530a0f6ea8c..67fc82dae33 100644 --- a/2nd-gen/packages/swc/.storybook/preview.ts +++ b/2nd-gen/packages/swc/.storybook/preview.ts @@ -89,7 +89,7 @@ const preview = { }, }, }, - tags: ['autodocs'], + //tags: ['autodocs'], }; export default preview; diff --git a/2nd-gen/packages/swc/components/progress-circle/docs/1_usage.mdx b/2nd-gen/packages/swc/components/progress-circle/docs/1_usage.mdx new file mode 100644 index 00000000000..3978079d0ee --- /dev/null +++ b/2nd-gen/packages/swc/components/progress-circle/docs/1_usage.mdx @@ -0,0 +1,43 @@ +import { + Meta, + Title, + Primary, + Canvas, + Controls, + Source, + Markdown, + ArgTypes, + Description, +} from '@storybook/addon-docs/blocks'; +import '@spectrum-web-components/tabs/sp-tabs.js'; +import '@spectrum-web-components/tabs/sp-tab.js'; +import '@spectrum-web-components/tabs/sp-tab-panel.js'; +import { * as ProgressCircleStories} from '../stories/progress-circle.stories.js'; + + + +# Progress circle usage + +```zsh +yarn add @spectrum-web-components/progress-circle +``` + +Import the side effectful registration of `` via: + +```ts +import '@spectrum-web-components/progress-circle/sp-progress-circle.js'; +``` + +When looking to leverage the `ProgressCircle` base class as a type and/or for extension purposes, do so via: + +```ts +import { ProgressCircle } from '@spectrum-web-components/progress-circle'; +``` + +### Anatomy + +A progress circle consists of several key parts: + +- A label (via `slot="label"`) +- A progress value (via `progress` attribute) +- An optional indeterminate state (via `indeterminate` attribute) diff --git a/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts b/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts index e8985065668..a93f243029d 100644 --- a/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts +++ b/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts @@ -82,6 +82,7 @@ export const Default: Story = { label: 'Loading progress', }, render: (args) => template(args), + tags: ['!dev'], }; export const Sizes: Story = { From c1ed77129e81e8f1595e9511eb4e433475028628 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Wed, 3 Dec 2025 10:29:17 -0500 Subject: [PATCH 2/7] docs: debuggin doc block --- .../swc/components/progress-circle/docs/1_usage.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/2nd-gen/packages/swc/components/progress-circle/docs/1_usage.mdx b/2nd-gen/packages/swc/components/progress-circle/docs/1_usage.mdx index 3978079d0ee..a4386032203 100644 --- a/2nd-gen/packages/swc/components/progress-circle/docs/1_usage.mdx +++ b/2nd-gen/packages/swc/components/progress-circle/docs/1_usage.mdx @@ -5,6 +5,7 @@ import { Canvas, Controls, Source, + Story, Markdown, ArgTypes, Description, @@ -12,9 +13,9 @@ import { import '@spectrum-web-components/tabs/sp-tabs.js'; import '@spectrum-web-components/tabs/sp-tab.js'; import '@spectrum-web-components/tabs/sp-tab-panel.js'; -import { * as ProgressCircleStories} from '../stories/progress-circle.stories.js'; +import * as ProgressCircleStories from '../stories/progress-circle.stories.js'; - + # Progress circle usage @@ -41,3 +42,8 @@ A progress circle consists of several key parts: - A label (via `slot="label"`) - A progress value (via `progress` attribute) - An optional indeterminate state (via `indeterminate` attribute) + + + + + From 2a0e7e62e692af85aebcb7b821d86e78dfd842b6 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Wed, 3 Dec 2025 11:47:22 -0500 Subject: [PATCH 3/7] docs: progress circle proof-of-concept docs for storybook --- 2nd-gen/packages/swc/.storybook/preview.ts | 2 +- .../progress-circle/docs/accessbility.mdx | 42 +++++++++++++++++ .../components/progress-circle/docs/api.mdx | 27 +++++++++++ .../docs/{1_usage.mdx => overview.mdx} | 47 ++++++++++++++++--- .../stories/progress-circle.stories.ts | 38 +++++++++++---- 5 files changed, 140 insertions(+), 16 deletions(-) create mode 100644 2nd-gen/packages/swc/components/progress-circle/docs/accessbility.mdx create mode 100644 2nd-gen/packages/swc/components/progress-circle/docs/api.mdx rename 2nd-gen/packages/swc/components/progress-circle/docs/{1_usage.mdx => overview.mdx} (50%) diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts index 67fc82dae33..d940a9a4d3c 100644 --- a/2nd-gen/packages/swc/.storybook/preview.ts +++ b/2nd-gen/packages/swc/.storybook/preview.ts @@ -55,7 +55,7 @@ const preview = { page: DocumentTemplate, toc: { contentsSelector: '.sbdocs-content', - headingSelector: 'h2, h3', + headingSelector: 'h2, h3, h4', ignoreSelector: '#primary', disable: false, unsafeTocbotOptions: { diff --git a/2nd-gen/packages/swc/components/progress-circle/docs/accessbility.mdx b/2nd-gen/packages/swc/components/progress-circle/docs/accessbility.mdx new file mode 100644 index 00000000000..a3e2aa15068 --- /dev/null +++ b/2nd-gen/packages/swc/components/progress-circle/docs/accessbility.mdx @@ -0,0 +1,42 @@ +import { + Meta, + Title, + Primary, + Canvas, + Controls, + Source, + Story, + Markdown, + ArgTypes, + Description, +} from '@storybook/addon-docs/blocks'; +import '@spectrum-web-components/tabs/sp-tabs.js'; +import '@spectrum-web-components/tabs/sp-tab.js'; +import '@spectrum-web-components/tabs/sp-tab-panel.js'; +import * as ProgressCircleA11y from '../stories/progress-circle.stories.ts'; + + + +# Progress circle accessibility + +### Features + +The `` element implements several accessibility features: + +1. **ARIA Role**: Automatically sets `role="progressbar"` for proper semantic meaning +2. **Labeling**: + - Uses the `label` attribute value as `aria-label` + - When determinate, adds `aria-valuenow` with the current progress + - Includes `aria-valuemin="0"` and `aria-valuemax="100"` for the progress range +3. **Status Communication**: + - Screen readers announce progress updates + - Indeterminate state is properly conveyed to assistive technologies + +### Best Practices + +- Always provide a descriptive `label` that explains what the progress represents +- Use determinate progress when possible to give users a clear sense of completion +- For determinate progress, ensure the `progress` value accurately reflects the actual progress +- Consider using size="l" for primary loading states to improve visibility + + diff --git a/2nd-gen/packages/swc/components/progress-circle/docs/api.mdx b/2nd-gen/packages/swc/components/progress-circle/docs/api.mdx new file mode 100644 index 00000000000..17d19571c56 --- /dev/null +++ b/2nd-gen/packages/swc/components/progress-circle/docs/api.mdx @@ -0,0 +1,27 @@ +import { + Meta, + Title, + Primary, + Canvas, + Controls, + Source, + Story, + Markdown, + ArgTypes, + Description, +} from '@storybook/addon-docs/blocks'; +import '@spectrum-web-components/tabs/sp-tabs.js'; +import '@spectrum-web-components/tabs/sp-tab.js'; +import '@spectrum-web-components/tabs/sp-tab-panel.js'; +import * as ProgressCircleApi from '../stories/progress-circle.stories.ts'; + + + +# Progress API + + + diff --git a/2nd-gen/packages/swc/components/progress-circle/docs/1_usage.mdx b/2nd-gen/packages/swc/components/progress-circle/docs/overview.mdx similarity index 50% rename from 2nd-gen/packages/swc/components/progress-circle/docs/1_usage.mdx rename to 2nd-gen/packages/swc/components/progress-circle/docs/overview.mdx index a4386032203..ac98b0f1d62 100644 --- a/2nd-gen/packages/swc/components/progress-circle/docs/1_usage.mdx +++ b/2nd-gen/packages/swc/components/progress-circle/docs/overview.mdx @@ -13,9 +13,9 @@ import { import '@spectrum-web-components/tabs/sp-tabs.js'; import '@spectrum-web-components/tabs/sp-tab.js'; import '@spectrum-web-components/tabs/sp-tab-panel.js'; -import * as ProgressCircleStories from '../stories/progress-circle.stories.js'; +import * as ProgressCircleOverview from '../stories/progress-circle.stories.ts'; - + # Progress circle usage @@ -43,7 +43,42 @@ A progress circle consists of several key parts: - A progress value (via `progress` attribute) - An optional indeterminate state (via `indeterminate` attribute) - - - - + + +### Options + +#### Sizes + +Progress circles come in three sizes to fit various contexts: + + + +#### Static Colors + +When displaying over images or colored backgrounds, use the `static-color` attribute for better contrast, e.g. `static-color="white"` on a dark background or `static-color="black"` on a light background: + + + +### States + +#### Indeterminate + +Use indeterminate progress when the duration cannot be calculated: + + diff --git a/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts b/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts index a93f243029d..cac2d1af288 100644 --- a/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts +++ b/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts @@ -85,6 +85,16 @@ export const Default: Story = { tags: ['!dev'], }; +export const ApiDefault: Story = { + args: { + progress: 50, + size: 'm', + label: 'Loading progress', + }, + render: (args) => template(args), + tags: ['!dev'], +}; + export const Sizes: Story = { render: () => html`
@@ -155,10 +165,10 @@ export const Indeterminate: Story = { tags: ['!dev'], }; -export const StaticWhite: Story = { +export const StaticColors: Story = { render: () => html`
- `, - tags: ['!dev'], -}; - -export const StaticBlack: Story = { - render: () => html`
html` +
+ +
+ `, + tags: ['!dev'], +}; From 68c9ed5958d12a9da44ad30350efe5fb0bbe6207 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Wed, 3 Dec 2025 12:02:31 -0500 Subject: [PATCH 4/7] docs(progress-circle): added toc --- 2nd-gen/packages/swc/.storybook/preview.ts | 5 +++++ .../{accessbility.mdx => accessibility.mdx} | 18 ++++++++++++++- .../components/progress-circle/docs/api.mdx | 16 +++++++++++++- .../progress-circle/docs/overview.mdx | 22 +++++++++++++++---- 4 files changed, 55 insertions(+), 6 deletions(-) rename 2nd-gen/packages/swc/components/progress-circle/docs/{accessbility.mdx => accessibility.mdx} (68%) diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts index d940a9a4d3c..8c1409e969b 100644 --- a/2nd-gen/packages/swc/.storybook/preview.ts +++ b/2nd-gen/packages/swc/.storybook/preview.ts @@ -53,6 +53,11 @@ const preview = { docs: { codePanel: true, page: DocumentTemplate, + options: { + storySort: { + order: ['Overview', 'API', 'Accessibility'], + }, + }, toc: { contentsSelector: '.sbdocs-content', headingSelector: 'h2, h3, h4', diff --git a/2nd-gen/packages/swc/components/progress-circle/docs/accessbility.mdx b/2nd-gen/packages/swc/components/progress-circle/docs/accessibility.mdx similarity index 68% rename from 2nd-gen/packages/swc/components/progress-circle/docs/accessbility.mdx rename to 2nd-gen/packages/swc/components/progress-circle/docs/accessibility.mdx index a3e2aa15068..548790924c0 100644 --- a/2nd-gen/packages/swc/components/progress-circle/docs/accessbility.mdx +++ b/2nd-gen/packages/swc/components/progress-circle/docs/accessibility.mdx @@ -13,11 +13,27 @@ import { import '@spectrum-web-components/tabs/sp-tabs.js'; import '@spectrum-web-components/tabs/sp-tab.js'; import '@spectrum-web-components/tabs/sp-tab-panel.js'; +import '@spectrum-web-components/top-nav/sp-top-nav.js'; +import '@spectrum-web-components/top-nav/sp-top-nav-item.js'; import * as ProgressCircleA11y from '../stories/progress-circle.stories.ts'; +import '@spectrum-web-components/top-nav/sp-top-nav.js'; +import '@spectrum-web-components/top-nav/sp-top-nav-item.js'; -# Progress circle accessibility +# Progress circle: Accessibility + + + + Overview + + + Accessibility + + + API + + ### Features diff --git a/2nd-gen/packages/swc/components/progress-circle/docs/api.mdx b/2nd-gen/packages/swc/components/progress-circle/docs/api.mdx index 17d19571c56..fc6d7bc8cde 100644 --- a/2nd-gen/packages/swc/components/progress-circle/docs/api.mdx +++ b/2nd-gen/packages/swc/components/progress-circle/docs/api.mdx @@ -14,10 +14,24 @@ import '@spectrum-web-components/tabs/sp-tabs.js'; import '@spectrum-web-components/tabs/sp-tab.js'; import '@spectrum-web-components/tabs/sp-tab-panel.js'; import * as ProgressCircleApi from '../stories/progress-circle.stories.ts'; +import '@spectrum-web-components/top-nav/sp-top-nav.js'; +import '@spectrum-web-components/top-nav/sp-top-nav-item.js'; -# Progress API +# Progress circle: API + + + + Overview + + + Accessibility + + + API + + - -# Progress circle usage +import '@spectrum-web-components/top-nav/sp-top-nav.js'; +import '@spectrum-web-components/top-nav/sp-top-nav-item.js'; + + + +# Progress circle: Overview + + + + Overview + + + Accessibility + + + API + + ```zsh yarn add @spectrum-web-components/progress-circle From 497feac87e26cbd872568234e6f5e8572f09bf75 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Wed, 3 Dec 2025 16:08:25 -0500 Subject: [PATCH 5/7] docs: updated progress circle and a11y guides --- .../accessibility-guides/00_overview.mdx | 162 ++++++++++++++++++ .../01_semantic_html_aria.mdx | 5 + .../02_accessible_pattern_libraries.mdx | 5 + .../03_keyboard_testing.mdx | 5 + .../04_screen_reader_testing.mdx | 5 + .../05_wave_toolbar_testing.mdx | 5 + .../06_accessibility_resources.mdx | 5 + .../accessibility-guides.mdx | 15 -- 2nd-gen/packages/swc/.storybook/main.ts | 7 +- 2nd-gen/packages/swc/.storybook/preview.ts | 14 +- .../docs/{overview.mdx => 01_overview.mdx} | 14 +- ...accessibility.mdx => 02_accessibility.mdx} | 14 +- .../progress-circle/docs/03_api.mdx | 25 +++ .../components/progress-circle/docs/api.mdx | 41 ----- .../stories/progress-circle.stories.ts | 12 +- 15 files changed, 236 insertions(+), 98 deletions(-) create mode 100644 2nd-gen/packages/swc/.storybook/guides/accessibility-guides/00_overview.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/accessibility-guides/01_semantic_html_aria.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/accessibility-guides/02_accessible_pattern_libraries.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/accessibility-guides/03_keyboard_testing.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/accessibility-guides/04_screen_reader_testing.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/accessibility-guides/05_wave_toolbar_testing.mdx create mode 100644 2nd-gen/packages/swc/.storybook/guides/accessibility-guides/06_accessibility_resources.mdx delete mode 100644 2nd-gen/packages/swc/.storybook/guides/accessibility-guides/accessibility-guides.mdx rename 2nd-gen/packages/swc/components/progress-circle/docs/{overview.mdx => 01_overview.mdx} (82%) rename 2nd-gen/packages/swc/components/progress-circle/docs/{accessibility.mdx => 02_accessibility.mdx} (79%) create mode 100644 2nd-gen/packages/swc/components/progress-circle/docs/03_api.mdx delete mode 100644 2nd-gen/packages/swc/components/progress-circle/docs/api.mdx diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/00_overview.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/00_overview.mdx new file mode 100644 index 00000000000..a75854e2b9d --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/00_overview.mdx @@ -0,0 +1,162 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Accessibility guides + +This guide provides essential accessibility knowledge and practices for customers and contributors to Spectrum Web Components. Building and using accessible components ensures that all users, regardless of ability, can effectively interact with web applications. + +## What is accessibility? + +**Accessibility** (often abbreviated as **a11y**) is the practice of making web content and applications usable by as many people as possible. This means designing and developing in ways that remove barriers preventing people with disabilities from perceiving, understanding, navigating, and interacting with digital content. + +In the context of web components, accessibility ensures that custom elements work seamlessly with assistive technologies and follow established patterns that users have come to expect. + +## Why accessibility matters + +### User inclusion + +Accordiing to the [World Health Organization](https://www.who.int/news-room/fact-sheets/detail/disability-and-health), approximately one in six people, or 16%% of the world's population, lives with some form of disability. Building accessible components ensures your applications serve the widest possible audience. + +### Ethical considerations + +Building accessible software is simply the right thing to do. Digital content has become essential to modern life, and excluding people with disabilities from accessing it perpetuates inequality. + +### Business benefits + +- **Larger market reach**: More users can access your applications +- **Better SEO**: Accessible HTML often improves search engine optimization +- **Improved usability for everyone**: Accessibility features benefit all users (e.g., captions help in noisy environments) +- **Reduced legal risk**: Proactive accessibility reduces litigation exposure +- **Increased compatibility**: with more web-enabled devices and assistive technologies being adopted by users + +### Legal requirements + +Many jurisdictions have legal requirements for digital accessibility: + +- **[Americans with Disabilities Act (ADA)](hhttps://www.ada.gov/topics/intro-to-ada/)** requires federal and state government entities as well as private entities that own, operate, lease, or lease to places of public accommodation must be accessible to people with disabilities +- **[Section 508](https://www.section508.gov/)** applies to US federal government entities but impacts any entity that does buisness with the US federal government +- **[European Accessibility Act](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=COM%3A2015%3A0615%3AFINa)** establishes accessbility standards for the EU; applies to "applies to any business’s product or service that is sold or in use within the Eurozone, not just EU member state businesses" [deque blog post](https://www.deque.com/blog/eu-web-accessibility-compliance-and-legislation/) +- **[Accessibility for Ontarians with Disabilities Act (AODA)](https://www.ontario.ca/laws/statute/05a11a)** "applies to every person or organization in the public and private sectors of the Province of Ontario, including the Legislative Assembly of Ontario" to comply with defined accessbility guidelines for EU member states + +## Types of disabilities + +When building accessible components, consider these categories of disabilities: + +### Visual disabilities + +- Blindness: Complete inability to see +- Low vision: Reduced visual acuity that cannot be corrected with glasses +- Color blindness: Difficulty distinguishing between certain colors +- Light sensitivity: Difficulty with bright lights or certain color contrasts + +### Auditory disabilities + +- Deafness: Complete inability to hear +- Hard of hearing: Partial hearing loss +- Audio processing disorders: Difficulty processing auditory information + +### Motor disabilities + +- Limited fine motor control: Difficulty with precise movements like clicking small targets +- Tremors or spasms: Involuntary movements affecting interaction +- Paralysis: Inability to move certain body parts +- Repetitive stress injuries: Pain or difficulty from repeated motions + +### Cognitive, learning, and neurological disabilities + +- Learning disabilities: Dyslexia, dyscalculia, and other processing differences +- Memory impairments: Difficulty retaining or recalling information +- Attention disorders: Difficulty maintaining focus +- Autism spectrum disorders: Different sensory processing and communication patterns +- Seizure disorders: Different types of epilepsy and migraines, often triggered by visual or auditory stimuli + +### Temporary and situational disabilities + +- Temporary: Broken arm, eye surgery recovery, ear infection +- Situational: Bright sunlight affecting screen visibility, noisy environment, holding a baby while trying to navigate with one hand + +## Assistive technologies + +Users interact with web components using various assistive technologies: + +### Screen readers + +- **[JAWS](https://www.freedomscientific.com/products/software/jaws/)**: Popular Windows screen reader, often used with Chrome or Edge browsers +- **[NVDA](https://www.nvaccess.org/about-nvda/)**: Free, open-source Windows screen reader, often used with Firefox browsers +- **[VoiceOver](hhttps://support.apple.com/guide/voiceover/turn-voiceover-on-or-off-vo2682/mac)**: Built-in screen reader for macOS and iOS, often used with Safari browsers +- **[TalkBack](https://support.google.com/accessibility/android/answer/6007100?hl=en)**: Built-in screen reader for Android, often used with Chrome browsers +- **[Narrator](https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1)**: Built-in Windows screen reader, often used with Edge browsers + +### Alternative input methods + +- **Keyboard navigation**: Users navigate without a mouse using Tab, arrow keys, Enter, Space, and Escape +- **Voice control**: Software like Dragon NaturallySpeaking allows voice commands +- **Switch devices**: Single or dual-switch systems for users with limited mobility +- **Eye tracking**: Systems that track eye movement for navigation + +### Visual assistance tools + +- **Screen magnification**: Software that enlarges portions of the screen +- **High contrast modes**: Operating system settings that increase contrast +- **Custom stylesheets**: User-defined CSS to override default styles + +## Web Content Accessibility Guidelines (WCAG) + +The **[Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/glance/)** are the international standard for web accessibility, developed by the World Wide Web Consortium (W3C). + +### Purpose + +WCAG provides a single shared standard for web content accessibility that meets the needs of individuals, organizations, and governments internationally. + +### Organization + +WCAG is organized around four principles (often remembered as **POUR**): + +1. **Perceivable**: Information and user interface components must be presentable to users in ways they can perceive +2. **Operable**: User interface components and navigation must be operable +3. **Understandable**: Information and the operation of user interface must be understandable +4. **Robust**: Content must be robust enough to be interpreted by a wide variety of user agents, including assistive technologies and future tools + +### Conformance levels + +WCAG defines three conformance levels: + +- **Level A**: The minimum level of accessibility. Addresses the most basic web accessibility features +- **Level AA**: The commonly targeted level. Addresses the biggest and most common barriers for disabled users +- **Level AAA**: The highest level. Provides the greatest level of accessibility but is not always achievable for all content + +**Target for Spectrum Web Components**: Level AA conformance is the standard we aim to achieve, as it represents best practices for most web content. + +## Authoring Tool Accessibility Guidelines (ATAG) + +The **[Authoring Tool Accessibility Guidelines (ATAG)](https://www.w3.org/WAI/standards-guidelines/atag/)** provide standards for tools used to create web content, including component libraries, content management systems, and development frameworks. + +### Why ATAG matters for component libraries + +Spectrum Web Components is an authoring tool in the sense that it provides building blocks for creating web content and applications. ATAG is relevant because: + +1. **Accessible by default**: Components should make it easy to create accessible content without requiring deep accessibility expertise. (Our components should handle as much semantic HTML and ARIA internally as much as possible.) +2. **Support accessible content creation**: Components should not create barriers to producing accessible applications. (It should be possible to use our components in and accessible way.) +3. **Promote accessibility**: Documentation and APIs should encourage accessible patterns. (Our documentation and APIs should encourage accessible patterns.) + +### ATAG principles + +ATAG has two main parts: + +- **Part A**: Make the authoring tool user interface accessible (the component library itself must be usable by developers with disabilities) +- **Part B**: Support the production of accessible content (components should facilitate creating accessible applications) + +## Resources + +For deeper understanding and ongoing reference, consult these authoritative sources: + +- [W3C Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/) - The main hub for web accessibility standards and resources +- [WCAG 2.1 Guidelines](https://www.w3.org/TR/WCAG21/) - The complete specification for web content accessibility +- [ATAG 2.0 Overview](https://www.w3.org/WAI/standards-guidelines/atag/) - Understanding authoring tool accessibility +- [WebAIM Introduction to Web Accessibility](https://webaim.org/intro/) - Practical introduction to accessibility concepts +- [The A11y Project Checklist](https://www.a11yproject.com/checklist/) - A beginner-friendly accessibility checklist + +## Next steps + +Explore the guides in this section to learn specific accessibility practices. diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/01_semantic_html_aria.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/01_semantic_html_aria.mdx new file mode 100644 index 00000000000..085af273cfc --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/01_semantic_html_aria.mdx @@ -0,0 +1,5 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Semantic HTML and ARIA diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/02_accessible_pattern_libraries.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/02_accessible_pattern_libraries.mdx new file mode 100644 index 00000000000..859dc603db4 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/02_accessible_pattern_libraries.mdx @@ -0,0 +1,5 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Accessible pattern libraries diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/03_keyboard_testing.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/03_keyboard_testing.mdx new file mode 100644 index 00000000000..e6051b3d8e6 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/03_keyboard_testing.mdx @@ -0,0 +1,5 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Keyboard testing diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/04_screen_reader_testing.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/04_screen_reader_testing.mdx new file mode 100644 index 00000000000..05409554b4b --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/04_screen_reader_testing.mdx @@ -0,0 +1,5 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Screen reader testing diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/05_wave_toolbar_testing.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/05_wave_toolbar_testing.mdx new file mode 100644 index 00000000000..65086dc3215 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/05_wave_toolbar_testing.mdx @@ -0,0 +1,5 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Wave toolbar testing diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/06_accessibility_resources.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/06_accessibility_resources.mdx new file mode 100644 index 00000000000..20ddd6a847f --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/06_accessibility_resources.mdx @@ -0,0 +1,5 @@ +import { Meta } from '@storybook/addon-docs/blocks'; + + + +# Accessibility resources diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/accessibility-guides.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/accessibility-guides.mdx deleted file mode 100644 index 9ed5375f2ee..00000000000 --- a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/accessibility-guides.mdx +++ /dev/null @@ -1,15 +0,0 @@ -import { Meta } from '@storybook/addon-docs/blocks'; - - - -# Accessibility guides - -This guide will help you understand the accessibility guides for SWC. - -## What is the accessibility guides? - -The accessibility guides are a set of rules that help you write code that is accessible. - -## What are the rules? - -The rules are: diff --git a/2nd-gen/packages/swc/.storybook/main.ts b/2nd-gen/packages/swc/.storybook/main.ts index f0e890b2e18..7797f9ca0d4 100644 --- a/2nd-gen/packages/swc/.storybook/main.ts +++ b/2nd-gen/packages/swc/.storybook/main.ts @@ -7,8 +7,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url)); /** @type { import('@storybook/web-components-vite').StorybookConfig } */ const config = { docs: { - autodocs: 'tag', // or true - defaultName: 'Usage', // Change 'Docs' to 'Component Documentation' + defaultName: 'Example', // Change 'Docs' to 'Component Documentation' }, stories: [ { @@ -18,12 +17,12 @@ const config = { }, { directory: '../components', - files: '*/stories/*.stories.ts', + files: '*/docs/*.mdx', titlePrefix: 'Components', }, { directory: '../components', - files: '*/docs/*.mdx', + files: '*/stories/*.stories.ts', titlePrefix: 'Components', }, { diff --git a/2nd-gen/packages/swc/.storybook/preview.ts b/2nd-gen/packages/swc/.storybook/preview.ts index 8c1409e969b..bc579cbd8e1 100644 --- a/2nd-gen/packages/swc/.storybook/preview.ts +++ b/2nd-gen/packages/swc/.storybook/preview.ts @@ -55,7 +55,8 @@ const preview = { page: DocumentTemplate, options: { storySort: { - order: ['Overview', 'API', 'Accessibility'], + method: 'alphabetical', + order: ['Overview', 'API', 'Accessibility', 'Playground'], }, }, toc: { @@ -70,7 +71,7 @@ const preview = { }, options: { storySort: { - method: 'alphabetical-by-kind', + method: 'alphabetical', order: [ 'Get Started', [ @@ -87,6 +88,15 @@ const preview = { 'Style guide', 'Project planning', 'Accessibility guides', + [ + 'Overview', + 'Semantic HTML and ARIA', + 'Accessible pattern libraries', + 'Keyboard testing', + 'Screen reader testing', + 'Wave toolbar testing', + 'Accessibility resources' + ], 'React wrappers', ], 'Resources', diff --git a/2nd-gen/packages/swc/components/progress-circle/docs/overview.mdx b/2nd-gen/packages/swc/components/progress-circle/docs/01_overview.mdx similarity index 82% rename from 2nd-gen/packages/swc/components/progress-circle/docs/overview.mdx rename to 2nd-gen/packages/swc/components/progress-circle/docs/01_overview.mdx index 3a6de9d7ec1..adeb3dc51c7 100644 --- a/2nd-gen/packages/swc/components/progress-circle/docs/overview.mdx +++ b/2nd-gen/packages/swc/components/progress-circle/docs/01_overview.mdx @@ -17,21 +17,11 @@ import * as ProgressCircleOverview from '../stories/progress-circle.stories.ts'; import '@spectrum-web-components/top-nav/sp-top-nav.js'; import '@spectrum-web-components/top-nav/sp-top-nav-item.js'; - + # Progress circle: Overview - - - Overview - - - Accessibility - - - API - - + ```zsh yarn add @spectrum-web-components/progress-circle diff --git a/2nd-gen/packages/swc/components/progress-circle/docs/accessibility.mdx b/2nd-gen/packages/swc/components/progress-circle/docs/02_accessibility.mdx similarity index 79% rename from 2nd-gen/packages/swc/components/progress-circle/docs/accessibility.mdx rename to 2nd-gen/packages/swc/components/progress-circle/docs/02_accessibility.mdx index 548790924c0..560e209f5cf 100644 --- a/2nd-gen/packages/swc/components/progress-circle/docs/accessibility.mdx +++ b/2nd-gen/packages/swc/components/progress-circle/docs/02_accessibility.mdx @@ -19,22 +19,10 @@ import * as ProgressCircleA11y from '../stories/progress-circle.stories.ts'; import '@spectrum-web-components/top-nav/sp-top-nav.js'; import '@spectrum-web-components/top-nav/sp-top-nav-item.js'; - + # Progress circle: Accessibility - - - Overview - - - Accessibility - - - API - - - ### Features The `` element implements several accessibility features: diff --git a/2nd-gen/packages/swc/components/progress-circle/docs/03_api.mdx b/2nd-gen/packages/swc/components/progress-circle/docs/03_api.mdx new file mode 100644 index 00000000000..6e263eaa1fc --- /dev/null +++ b/2nd-gen/packages/swc/components/progress-circle/docs/03_api.mdx @@ -0,0 +1,25 @@ +import { + Meta, + Title, + Primary, + Canvas, + Controls, + Source, + Story, + Markdown, + ArgTypes, + Description, +} from '@storybook/addon-docs/blocks'; +import '@spectrum-web-components/tabs/sp-tabs.js'; +import '@spectrum-web-components/tabs/sp-tab.js'; +import '@spectrum-web-components/tabs/sp-tab-panel.js'; +import * as ProgressCircleApi from '../stories/progress-circle.stories.ts'; +import '@spectrum-web-components/top-nav/sp-top-nav.js'; +import '@spectrum-web-components/top-nav/sp-top-nav-item.js'; + + + +# Progress circle: API + + + diff --git a/2nd-gen/packages/swc/components/progress-circle/docs/api.mdx b/2nd-gen/packages/swc/components/progress-circle/docs/api.mdx deleted file mode 100644 index fc6d7bc8cde..00000000000 --- a/2nd-gen/packages/swc/components/progress-circle/docs/api.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import { - Meta, - Title, - Primary, - Canvas, - Controls, - Source, - Story, - Markdown, - ArgTypes, - Description, -} from '@storybook/addon-docs/blocks'; -import '@spectrum-web-components/tabs/sp-tabs.js'; -import '@spectrum-web-components/tabs/sp-tab.js'; -import '@spectrum-web-components/tabs/sp-tab-panel.js'; -import * as ProgressCircleApi from '../stories/progress-circle.stories.ts'; -import '@spectrum-web-components/top-nav/sp-top-nav.js'; -import '@spectrum-web-components/top-nav/sp-top-nav-item.js'; - - - -# Progress circle: API - - - - Overview - - - Accessibility - - - API - - - - - diff --git a/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts b/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts index cac2d1af288..f750693eff1 100644 --- a/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts +++ b/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts @@ -76,23 +76,13 @@ export default meta; // ─────────────── export const Default: Story = { + name: 'Playground', args: { progress: 50, size: 'm', label: 'Loading progress', }, render: (args) => template(args), - tags: ['!dev'], -}; - -export const ApiDefault: Story = { - args: { - progress: 50, - size: 'm', - label: 'Loading progress', - }, - render: (args) => template(args), - tags: ['!dev'], }; export const Sizes: Story = { From f2013188b4f1dab6cedb84ba85ea5010b1bbb478 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Wed, 3 Dec 2025 16:46:08 -0500 Subject: [PATCH 6/7] docs(progress-circle): modified controls --- .../stories/progress-circle.stories.ts | 35 +++++++++---------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts b/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts index f750693eff1..2edde8a3983 100644 --- a/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts +++ b/2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts @@ -26,24 +26,16 @@ const { events, args, argTypes, template } = getStorybookHelpers( 'swc-progress-circle' ); -/* - * @todo Blurring the range control seems to cause a catastrophic Storybook - * render failure, so disabling for now. - */ -// argTypes.progress = { -// ...argTypes.progress, -// control: { type: 'range', min: 0, max: 100, step: 1 }, -// }; - -/* - * @todo This is properly configuring the Select, but the control doesn't - * seem to work; need to investigate. - */ -// argTypes.size = { -// ...argTypes.size, -// control: { type: 'select' }, -// options: ProgressCircle.VALID_SIZES, -// }; +argTypes.progress = { + ...argTypes.progress, + control: { type: 'number', min: 0, max: 100, step: 1 }, +}; + +argTypes.size = { + ...argTypes.size, + control: { type: 'select' }, + options: ProgressCircle.VALID_SIZES, +}; argTypes['static-color'] = { ...argTypes['static-color'], @@ -51,6 +43,13 @@ argTypes['static-color'] = { options: [undefined, ...ProgressCircle.STATIC_COLORS], }; +argTypes['label'] = { + ...argTypes['label'], + control: { type: 'text', required: true }, +}; + +// there is no default slot in the progress circle, so we need to remove the control + /** * A progress circle component that visually represents the completion progress of a task. * Can be used in both determinate (with specific progress value) and indeterminate (loading) states. From 60b75355d7c547b9b46a8d9664e5725183ad86c8 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Thu, 4 Dec 2025 15:18:47 -0500 Subject: [PATCH 7/7] docs(a11y): fixed typo --- .../.storybook/guides/accessibility-guides/00_overview.mdx | 6 +++--- .../guides/accessibility-guides/01_semantic_html_aria.mdx | 2 +- .../02_accessible_pattern_libraries.mdx | 2 +- .../guides/accessibility-guides/03_keyboard_testing.mdx | 2 +- .../accessibility-guides/04_screen_reader_testing.mdx | 2 +- .../guides/accessibility-guides/05_wave_toolbar_testing.mdx | 2 +- .../accessibility-guides/06_accessibility_resources.mdx | 2 +- .../04_accessibility_guides/06_accessibility_resources.md | 2 +- 8 files changed, 10 insertions(+), 10 deletions(-) diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/00_overview.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/00_overview.mdx index a75854e2b9d..a36a5ef926b 100644 --- a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/00_overview.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/00_overview.mdx @@ -1,6 +1,6 @@ import { Meta } from '@storybook/addon-docs/blocks'; - + # Accessibility guides @@ -36,8 +36,8 @@ Many jurisdictions have legal requirements for digital accessibility: - **[Americans with Disabilities Act (ADA)](hhttps://www.ada.gov/topics/intro-to-ada/)** requires federal and state government entities as well as private entities that own, operate, lease, or lease to places of public accommodation must be accessible to people with disabilities - **[Section 508](https://www.section508.gov/)** applies to US federal government entities but impacts any entity that does buisness with the US federal government -- **[European Accessibility Act](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=COM%3A2015%3A0615%3AFINa)** establishes accessbility standards for the EU; applies to "applies to any business’s product or service that is sold or in use within the Eurozone, not just EU member state businesses" [deque blog post](https://www.deque.com/blog/eu-web-accessibility-compliance-and-legislation/) -- **[Accessibility for Ontarians with Disabilities Act (AODA)](https://www.ontario.ca/laws/statute/05a11a)** "applies to every person or organization in the public and private sectors of the Province of Ontario, including the Legislative Assembly of Ontario" to comply with defined accessbility guidelines for EU member states +- **[European Accessibility Act](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=COM%3A2015%3A0615%3AFINa)** establishes Accessibility standards for the EU; applies to "applies to any business’s product or service that is sold or in use within the Eurozone, not just EU member state businesses" [deque blog post](https://www.deque.com/blog/eu-web-accessibility-compliance-and-legislation/) +- **[Accessibility for Ontarians with Disabilities Act (AODA)](https://www.ontario.ca/laws/statute/05a11a)** "applies to every person or organization in the public and private sectors of the Province of Ontario, including the Legislative Assembly of Ontario" to comply with defined Accessibility guidelines for EU member states ## Types of disabilities diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/01_semantic_html_aria.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/01_semantic_html_aria.mdx index 085af273cfc..db829e9cae1 100644 --- a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/01_semantic_html_aria.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/01_semantic_html_aria.mdx @@ -1,5 +1,5 @@ import { Meta } from '@storybook/addon-docs/blocks'; - + # Semantic HTML and ARIA diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/02_accessible_pattern_libraries.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/02_accessible_pattern_libraries.mdx index 859dc603db4..8bb1b264225 100644 --- a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/02_accessible_pattern_libraries.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/02_accessible_pattern_libraries.mdx @@ -1,5 +1,5 @@ import { Meta } from '@storybook/addon-docs/blocks'; - + # Accessible pattern libraries diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/03_keyboard_testing.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/03_keyboard_testing.mdx index e6051b3d8e6..5a37b291c7b 100644 --- a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/03_keyboard_testing.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/03_keyboard_testing.mdx @@ -1,5 +1,5 @@ import { Meta } from '@storybook/addon-docs/blocks'; - + # Keyboard testing diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/04_screen_reader_testing.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/04_screen_reader_testing.mdx index 05409554b4b..85439fdd4ad 100644 --- a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/04_screen_reader_testing.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/04_screen_reader_testing.mdx @@ -1,5 +1,5 @@ import { Meta } from '@storybook/addon-docs/blocks'; - + # Screen reader testing diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/05_wave_toolbar_testing.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/05_wave_toolbar_testing.mdx index 65086dc3215..79489e92261 100644 --- a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/05_wave_toolbar_testing.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/05_wave_toolbar_testing.mdx @@ -1,5 +1,5 @@ import { Meta } from '@storybook/addon-docs/blocks'; - + # Wave toolbar testing diff --git a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/06_accessibility_resources.mdx b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/06_accessibility_resources.mdx index 20ddd6a847f..46e7c47276e 100644 --- a/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/06_accessibility_resources.mdx +++ b/2nd-gen/packages/swc/.storybook/guides/accessibility-guides/06_accessibility_resources.mdx @@ -1,5 +1,5 @@ import { Meta } from '@storybook/addon-docs/blocks'; - + # Accessibility resources diff --git a/CONTRIBUTOR-DOCS/04_accessibility_guides/06_accessibility_resources.md b/CONTRIBUTOR-DOCS/04_accessibility_guides/06_accessibility_resources.md index 72e08d72e1b..85826415e54 100644 --- a/CONTRIBUTOR-DOCS/04_accessibility_guides/06_accessibility_resources.md +++ b/CONTRIBUTOR-DOCS/04_accessibility_guides/06_accessibility_resources.md @@ -4,6 +4,6 @@ -# Accessibility resources +# accessibility resources