Cline

# Angular Guidelines Use this guidelines when working with Angular related code. ## 1. Core Architecture - **Standalone Components:** Components, directives, and pipes are standalone by default. The `standalone: true` flag is no longer required and should be omitted in new code (Angular v17+ and above). - **Strong Typing:** TypeScript types, interfaces, and models provide type safety throughout the codebase - **Single Responsibility:** Each component and service has a single, well-defined responsibility - **Rule of One:** Files focus on a single concept or functionality - **Reactive State:** Signals provide reactive and efficient state management - **Dependency Injection:** Angular's DI system manages service instances - **Function-Based DI:** Use function-based dependency injection with the `inject()` function instead of constructor-based injection in all new code. Example: ```typescript import { inject } from "@angular/core"; import { HttpClient } from "@angular/common/http"; export class MyService { private readonly http = inject(HttpClient); // ... } ``` - **Lazy Loading:** Deferrable Views and route-level lazy loading with `loadComponent` improve performance - **Directive Composition:** The Directive Composition API enables reusable component behavior - **Standalone APIs Only:** Do not use NgModules, CommonModule, or RouterModule. Import only required standalone features/components. - **No Legacy Modules:** Do not use or generate NgModules for new features. Migrate existing modules to standalone APIs when possible. ## 2. Angular Style Guide Patterns - **Code Size:** Files are limited to 400 lines of code - **Single Purpose Files:** Each file defines one entity (component, service, etc.) - **Naming Conventions:** Symbols have consistent, descriptive names - **Folder Structure:** Code is organized by feature-based folders - **File Separation:** Templates and styles exist in their own files for components - **Property Decoration:** Input and output properties have proper decoration - **Component Selectors:** Component selectors use custom prefixes and kebab-case (e.g., `app-feature-name`) - **No CommonModule or RouterModule Imports:** Do not import CommonModule or RouterModule in standalone components. Import only the required standalone components, directives, or pipes. ## 3. Input Signal Patterns - **Signal-Based Inputs:** The `input()` function creates InputSignals: ```typescript // Current pattern readonly value = input(0); // Creates InputSignal // Legacy pattern @Input() value = 0; ``` - **Required Inputs:** The `input.required()` function marks inputs as mandatory: ```typescript readonly value = input.required<number>(); ``` - **Input Transformations:** Transformations convert input values: ```typescript readonly disabled = input(false, { transform: booleanAttribute }); readonly value = input(0, { transform: numberAttribute }); ``` - **Two-Way Binding:** Model inputs enable two-way binding: ```typescript readonly value = model(0); // Creates a model input with change propagation // Model values update with .set() or .update() increment(): void { this.value.update(v => v + 1); } ``` - **Input Aliases:** Aliases provide alternative input names: ```typescript readonly value = input(0, { alias: "sliderValue" }); ``` ## 3a. Typed Reactive Forms - **Typed Forms:** Always use strictly typed reactive forms by defining an interface for the form values and using `FormGroup<MyFormType>`, `FormBuilder.group<MyFormType>()`, and `FormControl<T>()`. - **Non-Nullable Controls:** Prefer `nonNullable: true` for controls to avoid null issues and improve type safety. - **Patch and Get Values:** Use `patchValue` and `getRawValue()` to work with typed form values. - **Reference:** See the [Angular Typed Forms documentation](https://angular.dev/guide/forms/typed-forms) for details and examples. ## 4. Component Patterns - **Naming Pattern:** Components follow consistent naming - `feature.type.ts` (e.g., `hero-list.component.ts`) - **Template Extraction:** Non-trivial templates exist in separate `.html` files - **Style Extraction:** Styles exist in separate `.css/.scss` files - **Signal-Based Inputs:** Components use the `input()` function for inputs - **Two-Way Binding:** Components use the `model()` function for two-way binding - **Lifecycle Hooks:** Components implement appropriate lifecycle hook interfaces (OnInit, OnDestroy, etc.) - **Element Selectors:** Components use element selectors (`selector: 'app-hero-detail'`) - **Logic Delegation:** Services contain complex logic - **Input Initialization:** Inputs have default values or are marked as required - **Lazy Loading:** The `@defer` directive loads heavy components or features - **Error Handling:** Try-catch blocks handle errors - **Modern Control Flow:** Templates use `@if`, `@for`, `@switch` instead of structural directives - **State Representation:** Components implement loading and error states - **Derived State:** The `computed()` function calculates derived state - **No NgModules:** Do not use or reference NgModules in new code. ## 5. Styling Patterns - **Component Encapsulation:** Components use scoped styles with proper encapsulation - **CSS Methodology:** BEM methodology guides CSS class naming when not using Angular Material - **Component Libraries:** Angular Material or other component libraries provide consistent UI elements - **Theming:** Color systems and theming enable consistent visual design - **Accessibility:** Components follow a11y standards - **Dark Mode:** Components support dark mode where appropriate ## 5a. Angular Material and Angular CDK Usage - **Standard UI Library:** Use Angular Material v3 for all standard UI components (buttons, forms, navigation, dialogs, etc.) to ensure consistency, accessibility, and alignment with Angular best practices. - **Component Development:** Build new UI components and features using Angular Material components as the foundation. Only create custom components when Material does not provide a suitable solution. - **Behavioral Primitives:** Use Angular CDK for advanced behaviors (drag-and-drop, overlays, accessibility, virtual scrolling, etc.) and for building custom components that require low-level primitives. - **Theming:** Leverage Angular Material's theming system for consistent color schemes, dark mode support, and branding. Define and use custom themes in `styles.scss` or feature-level styles as needed. - **Accessibility:** All UI components must meet accessibility (a11y) standards. Prefer Material components for built-in a11y support. When using CDK or custom components, follow WCAG and ARIA guidelines. - **Best Practices:** - Prefer Material's layout and typography utilities for spacing and text. - Use Material icons and fonts for visual consistency. - Avoid mixing multiple UI libraries in the same project. - Reference the [Angular Material documentation](https://material.angular.io) for usage patterns and updates. - **CDK Utilities:** Use Angular CDK utilities for custom behaviors, overlays, accessibility, and testing harnesses. - **Migration:** For legacy or custom components, migrate to Angular Material/CDK where feasible. ## 5b. Template Patterns - **Modern Control Flow:** Use the new Angular control flow syntax: `@if`, `@for`, `@switch` in templates. Do not use legacy structural directives such as `*ngIf`, `*ngFor`, or `*ngSwitch`. - **No Legacy Structural Directives:** Remove or migrate any usage of `*ngIf`, `*ngFor`, or `*ngSwitch` to the new control flow syntax in all new code. Legacy code should be migrated when touched. - **Referencing Conditional Results:** When using `@if`, reference the result using the `as` keyword, e.g. `@if (user(); as u) { ... }`. This is the recommended pattern for accessing the value inside the block. See the [Angular documentation](https://angular.dev/guide/templates/control-flow#referencing-the-conditional-expressions-result) for details. ## 6. Service and DI Patterns - **Service Declaration:** Services use the `@Injectable()` decorator with `providedIn: 'root'` for singletons - **Data Services:** Data services handle API calls and data operations - **Error Handling:** Services include error handling - **DI Hierarchy:** Services follow the Angular DI hierarchy - **Service Contracts:** Interfaces define service contracts - **Focused Responsibilities:** Services focus on specific tasks - **Function-Based DI:** Use function-based dependency injection with the `inject()` function instead of constructor-based injection in all new code. Example: ```typescript import { inject } from "@angular/core"; import { HttpClient } from "@angular/common/http"; export class MyService { private readonly http = inject(HttpClient); // ... } ``` ## 7. Directive and Pipe Patterns - **Attribute Directives:** Directives handle presentation logic without templates - **Host Property:** The `host` property manages bindings and listeners: ```typescript @Directive({ selector: '[appHighlight]', host: { // Host bindings '[class.highlighted]': 'isHighlighted', '[style.color]': 'highlightColor', // Host listeners '(click)': 'onClick($event)', '(mouseenter)': 'onMouseEnter()', '(mouseleave)': 'onMouseLeave()', // Static properties 'role': 'button', '[attr.aria-label]': 'ariaLabel' } }) ``` - **Selector Prefixes:** Directive selectors use custom prefixes - **Pure Pipes:** Pipes are pure when possible for better performance - **Pipe Naming:** Pipes follow camelCase naming conventions ## 8. State Management Patterns - **Signals:** Signals serve as the primary state management solution - **Component Inputs:** Signal inputs with `input()` handle component inputs - **Two-Way Binding:** Model inputs with `model()` enable two-way binding - **Local State:** Writable signals with `signal()` manage local component state - **Derived State:** Computed signals with `computed()` calculate derived state - **Side Effects:** The `effect()` function handles side effects - **Error Handling:** Signal computations include error handling - **Signal Conversion:** The `toSignal()` and `toObservable()` functions enable interoperability with RxJS ## 9. Testing Patterns - **Test Coverage:** Tests cover components and services - **Unit Tests:** Focused unit tests verify services, pipes, and components - **Component Testing:** TestBed and component harnesses test components - **Mocking:** Tests use mocking techniques for dependencies - **Test Organization:** Tests follow the AAA pattern (Arrange, Act, Assert) - **Test Naming:** Tests have descriptive names that explain the expected behavior - **Playwright Usage:** Playwright handles E2E testing with fixtures and test isolation - **Test Environment:** Test environments match production as closely as possible ## 10. Performance Patterns - **Change Detection:** Components use OnPush change detection strategy - **Lazy Loading:** Routes and components load lazily - **Virtual Scrolling:** Virtual scrolling renders long lists efficiently - **Memoization:** Memoization optimizes expensive computations - **Bundle Size:** Bundle size monitoring and optimization reduce load times - **Server-Side Rendering:** SSR improves initial load performance - **Web Workers:** Web workers handle intensive operations ## 11. Security Patterns - **XSS Prevention:** User input undergoes sanitization - **CSRF Protection:** CSRF tokens secure forms - **Content Security Policy:** CSP headers restrict content sources - **Authentication:** Secure authentication protects user accounts - **Authorization:** Authorization checks control access - **Sensitive Data:** Client-side code excludes sensitive data ## 12. Accessibility Patterns - **ARIA Attributes:** ARIA attributes enhance accessibility - **Keyboard Navigation:** Interactive elements support keyboard access - **Color Contrast:** UI elements maintain proper color contrast ratios - **Screen Readers:** Components work with screen readers - **Focus Management:** Focus management guides user interaction - **Alternative Text:** Images include alt text

# Core Architecture Standards for Accessibility This document outlines core architectural standards for developing accessible applications. It focuses on fundamental patterns, project structure, and organizational principles, emphasizing the importance of accessibility considerations from the outset. ## 1. Overall Architectural Principles Accessibility is not a feature to be added as an afterthought; it's a core requirement that must be baked into the application's very architecture. The following principles should guide every architectural decision: * **Semantic HTML:** Utilize semantic HTML elements to structure content effectively, providing native accessibility features. * **Progressive Enhancement:** Build a basic, functional experience with semantic HTML, and then enhance it with JavaScript and CSS, ensuring accessibility even with those elements disabled. * **ARIA When Necessary:** Use ARIA (Accessible Rich Internet Applications) attributes to enhance accessibility only when semantic HTML cannot express the necessary roles, states, and properties. ARIA is a powerful tool but should be used judiciously to augment, not replace, semantic HTML. * **Keyboard Navigation:** Ensure all interactive elements are accessible via keyboard, in a logical and predictable order. * **Focus Management:** Implement robust focus management to provide clear visual cues for keyboard users and prevent focus traps. * **Color Contrast:** Adhere to WCAG (Web Content Accessibility Guidelines) AA (or AAA) color contrast requirements for all text and interactive elements. * **Testability:** Design the architecture to be easily tested for accessibility using automated tools and manual testing methodologies. **Why?** These principles ensure that applications are inherently more accessible, reducing the need for extensive remediation later in the development cycle. An accessibility-first mindset saves time and resources while creating a better experience for *all* users. ## 2. Project Structure and Organization A well-organized project structure greatly simplifies accessibility efforts for development teams. The project code should be modular and easy to understand, and that extends to how accessibility considerations are organized into the project. ### 2.1. Component-Based Architecture * **Do This:** Adopt a component-based architecture, such as React, Angular, Vue.js, or Web Components. Each component should be responsible for its accessibility. * **Don't Do This:** Avoid monolithic codebases with tightly coupled components, making it difficult to isolate and address accessibility issues. **Why?** Component-based architectures promote reusability and allow for the encapsulation of accessibility concerns within each component. When accessibility is built into a component from the start, it's more likely to be maintained and propagated consistently across the application. **Example (React):** """jsx // AccessibleButton.jsx import React from 'react'; const AccessibleButton = ({ onClick, children, ariaLabel }) => { return ( <button onClick={onClick} aria-label={ariaLabel}> {children} </button> ); }; export default AccessibleButton; """ ### 2.2. Dedicated Accessibility Modules/Utilities * **Do This:** Create dedicated modules or utility functions for common accessibility tasks, such as focus management, ARIA attribute handling, and color contrast validation. * **Don't Do This:** Scatter accessibility-related code throughout the application, leading to inconsistency and code duplication. **Why?** Centralizing accessibility logic simplifies maintenance and ensures consistent implementation across the application. These modules can be reused across multiple components, ensuring uniform accessibility. **Example (JavaScript):** """javascript // accessibility-utils.js export function setFocus(elementId) { const element = document.getElementById(elementId); if (element) { element.focus(); } } export function isValidColorContrast(color1, color2, ratio = 4.5) { // Implement color contrast ratio calculation logic here // Refer to WCAG 2.1 spec for formula // Returns true if the contrast ratio meets the specified level return true; // Placeholder for the actual logic } """ ### 2.3. Directory Structure & Naming Conventions * **Do This:** Follow a consistent directory structure. Organize accessibility files within logical folders, like "accessibility," "utils," or adjacent to the components they support. Use clear and descriptive filenames, such as "AccessibleButton.jsx" or "accessibility-utils.js". These should be explicitly named, not abbreviated beyond recognition. * **Don't Do This:** Use arbitrary or inconsistent naming conventions that don’t represent the contents of the files. **Why?** A clearly defined directory structure and consistent naming conventions enhances code navigability and allows developers to quickly locate the required files. Example Folder Structure: """ src/ ├── components/ │ ├── Button/ │ │ ├── Button.jsx // Main component file │ │ ├── Button.module.css // Component styles │ │ ├── Button.test.js // Unit tests │ │ ├── Button.accessibility.js // Accessibility-specific logic (if needed) │ ├── Input/ │ │ └── ... ├── accessibility/ // Central Accessibility files │ ├── focus-management.js │ ├── aria-utils.js │ └── color-contrast.js └── ... """ ## 3. Fundamental Architectural Patterns for Accessibility Certain architectural patterns can significantly improve the accessibility of your application. ### 3.1. WAI-ARIA Design Patterns * **Do This:** Familiarize yourself with the WAI-ARIA Authoring Practices (APG). Implement common ARIA design patterns, such as "Dialog (Modal)", "Tabs", "Accordion", and "Alert", correctly, following the documented best practices for roles, states, properties, and keyboard interactions. * **Don't Do This:** Reinvent the wheel. Avoid creating custom UI components with complex interactions from scratch without understanding existing ARIA patterns. **Why?** WAI-ARIA patterns provide tested and proven approaches for creating accessible interactive components. Adhering to these patterns ensures that assistive technologies can correctly interpret and interact with your UI, providing a consistent experience for users. **Example (ARIA Dialog):** """jsx // AccessibleDialog.jsx import React, { useState, useRef, useEffect } from 'react'; const AccessibleDialog = ({ isOpen, onClose, children, ariaLabelledBy }) => { const dialogRef = useRef(null); useEffect(() => { if (isOpen && dialogRef.current) { dialogRef.current.focus(); // Set focus to the dialog } }, [isOpen]); return ( {isOpen && ( <div className="overlay"> {/* Style this for modal backdrop */} <div className="dialog" role="dialog" aria-labelledby={ariaLabelledBy} aria-modal="true" ref={dialogRef} > <button onClick={onClose} aria-label="Close"> X </button> {children} </div> </div> )} ); }; export default AccessibleDialog; """ ### 3.2. "Skip to Content" Links * **Do This:** Implement "Skip to Content" (or other relevant name like "Skip Navigation") links at the beginning of the page, allowing keyboard users to bypass repetitive navigation menus and jump directly to the primary content area. * **Don't Do This:** Rely solely on the natural tab order. Keyboard users will have to tab through all the navigation options before reaching your content. **Why?** Skip links greatly improve keyboard navigation efficiency, enabling users to quickly access the information they need. **Example (HTML):** """html <a href="#main-content" class="skip-link">Skip to main content</a> <nav> <!-- Navigation menu --> </nav> <main id="main-content"> <!-- Main content --> </main> """ (CSS: Ensure ".skip-link" is visually hidden until focused, then reveal it.) ### 3.3. Live Regions (ARIA "aria-live") * **Do This:** Use ARIA live regions ("aria-live") to announce dynamic content updates to assistive technologies, such as screen readers, without requiring the user to move focus. * **Don't Do This:** Rely solely on visual cues for updates. Users who can't see the updates will miss critical information. **Why?** Live regions provide a mechanism for asynchronously communicating updates to assistive technology users, allowing your application to be more dynamic and responsive. **Example (React):** """jsx import React, { useState, useEffect } from 'react'; const LiveAnnouncer = () => { const [message, setMessage] = useState(''); useEffect(() => { // Simulate an update after 2 seconds setTimeout(() => { setMessage('New message received!'); }, 2000); }, []); return ( <div aria-live="polite" aria-atomic="true"> {message} </div> ); }; export default LiveAnnouncer; """ ### 3.4. Managing Focus Effectively * **Do This:** Explicitly control the focus flow using techniques like automatically setting the focus to newly opened dialogs or error messages. Use the "tabindex" attribute judiciously, only when necessary to alter the natural tab order (e.g., "tabindex="0"" to make non-interactive elements focusable, or "tabindex="-1"" to make an element focusable programmatically). * **Don't Do This:** Rely on the browser's default focus behavior, which may not align with the user's expectations in complex interactions. Do not use "tabindex" except for the specific cases identified in "Do This". **Why?** Predictable and logical focus management is crucial for keyboard navigation and screen reader users. Incorrect focus management leads to frustration and confusion. Poorly managed focus can even trap a user with assistive technology. **Example (JavaScript - setting focus to a modal):** """javascript function openModal(modalId) { const modal = document.getElementById(modalId); modal.style.display = 'block'; // Or whatever makes the modal visible. modal.setAttribute('aria-hidden', 'false'); const focusableElements = modal.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'); const firstFocusableElement = focusableElements[0]; if (firstFocusableElement) { firstFocusableElement.focus(); // Sets focus to the first focusable element in the modal. } //Trap focus inside the modal modal.addEventListener('keydown', function (e) { const isTabPressed = e.key === 'Tab' || e.keyCode === 9; if (!isTabPressed) { return; } if (e.shiftKey) { //If shift + tab if (document.activeElement === firstFocusableElement) { focusableElements[focusableElements.length - 1].focus(); e.preventDefault(); } } else { //If tab if (document.activeElement === focusableElements[focusableElements.length - 1]) { firstFocusableElement.focus(); e.preventDefault(); } } }); } """ ## 4. Technology-Specific Considerations While the principles remain the same, implementation details will vary depending on the technologies used. ### 4.1. React * **Use JSX Semantically:** Leverage JSX to write semantic HTML. Ensure that dynamic content is rendered correctly and that ARIA attributes are used appropriately. * **Use "aria-label" instead of Placeholder:** For form elements, prefer "aria-label" for labels instead of placeholders, as placeholders disappear when the user starts typing. * **Avoid Anti-Patterns:** Be wary of using inline styles that might override important CSS declarations for high contrast themes. * **Lifecycle Methods:** Utilize "componentDidMount" and "componentDidUpdate" to manage focus, announce live region updates, or make other asynchronous accessibility adjustments. ### 4.2. Angular * **Templates for Semantic HTML:** Ensure semantic markup in component templates. Angular's structural directives ("*ngIf", "*ngFor") must produce accessible HTML. * **Accessibility Directives:** Create custom directives to encapsulate accessibility logic, promoting reusability and consistency. * **"@HostListener" for Keyboard Events:** Utilize "@HostListener" to listen for keyboard events and implement custom application focus logic. * **Forms accessibility:** Leverage Angular's form controls in an accessible manner, using descriptive labels and clear error messages. ### 4.3. Vue.js * **Template Syntax:** Use Vue.js's template syntax to create semantic HTML. Use"v-bind:aria-label" and its shorthand ":aria-label" to bind ARIA attributes dynamically. * **Accessibility Mixins:** Develop Vue.js mixins to encapsulate accessibility logic and apply it to multiple components. * **"$nextTick()" for DOM Updates:** Use "$nextTick()" to ensure that the DOM has been updated before performing accessibility-related actions, such as setting focus. * **VueUse Library:** The VueUse library contains many accessibility-related composables. ## 5. Common Anti-Patterns and Mistakes * **Ignoring Semantic HTML:** Relying heavily on "<div>" and "<span>" elements without using appropriate semantic tags. * **Overusing ARIA:** Using ARIA attributes unnecessarily or incorrectly, leading to conflicts with native HTML semantics. * **Poor Keyboard Navigation:** Failing to provide clear and logical keyboard navigation, resulting in focus traps and inaccessible interactions. * **Insufficient Color Contrast:** Using color combinations that do not meet WCAG contrast requirements, making it difficult for users with low vision or color blindness to perceive content. * **Inadequate Testing:** Neglecting thorough accessibility testing with automated tools and manual review. * **Lack of Documentation:** Failing to document the accessibility considerations when creating components or architectural patterns. * **Assuming Assistive Technology Compatibility:** Developing without testing with real assistive technologies like screen readers. Just because the code *looks* right doesn't mean a screen reader is interpreting it correctly. * **Only Testing at the End of the Process:** Waiting until the end of the development cycle to test can be cost prohibitive. Aim for 'shift left' in your testing, bringing it earlier in the cycle. * **Skipping the Accessibility Tree:** For any changes to the DOM, ensure the accessibility tree updates accordingly. * **Using "role="presentation"" incorrectly**: Overusing "role="presentation"" without fully understanding its effect. It removes the semantic meaning from elements, potentially hindering accessibility. ## 6. Performance Optimization for Accessibility Accessibility features, while essential, can impact performance if not implemented carefully: * **Avoid Excessive ARIA Updates:** Minimize the number of updates to ARIA attributes. Too many updates can overwhelm assistive technologies and degrade performance. * **Lazy Load Content:** Load content asynchronously and only when needed, improving initial page load time. Ensure announcements are made to screen readers when new content is loaded. * **Virtualization:** For large lists or tables, use virtualization techniques to render only the visible items, improving performance and reducing the amount of DOM that assistive technologies need to process. * **Optimize Image Alt Text:** Craft concise and descriptive alternative text for images to reduce the amount of information that screen readers need to convey. Avoid redundant phrases like "Image of..." * **Debounce or Throttle Events:** Reduce the frequency of event listeners that trigger accessibility-related actions, such as focus changes or live region updates. * **Use CSS "content:attr()" judiciously:** While convenient for dynamically inserting text for screen readers, excessive use of "content:attr()" can impact rendering performance if not optimized. ## 7. Security Considerations for Accessibility Be cautious that accessibility features and metadata do not inadvertently expose sensitive information or create security vulnerabilities. * **Sanitize ARIA attributes:** When dynamically setting or updating ARIA attributes, sanitize the input to prevent Cross-Site Scripting (XSS) attacks. Never trust third-party or user-supplied data. * **Avoid exposing sensitive data in "alt" attributes:** Carefully review the alternative text of images to ensure they do not contain sensitive or confidential information. * **Secure Focus Management:** Ensure that focus management techniques do not create opportunities for malicious actors to inject code or manipulate the user interface. * **Review live region content:** ensure live regions that dynamically update do not inadvertently disclose PII or other sensitive data. * **Keep dependencies updated:** Regularly update accessibility libraries and tools to patch security vulnerabilities. ## 8. Testing and Validation * **Automated Testing:** Integrate automated accessibility testing tools (e.g., axe DevTools, WAVE) into your build process to identify common accessibility issues early. * **Manual Testing:** Perform manual accessibility testing with assistive technologies (e.g., screen readers, keyboard) to evaluate the user experience and identify issues that automated tools may miss. * **User Testing:** Conduct user testing with people with disabilities to gather feedback on the accessibility of your application and identify areas for improvement. ## 9. Documentation * **Document Accessibility Decisions:** Document all accessibility-related decisions, including the rationale behind the choices and any trade-offs made. * **Component Documentation:** Include accessibility information in component documentation, explaining how to use the component accessibly and any accessibility considerations for developers or content authors. * **Code Comments:** Add comments to the code to explain complex accessibility implementations, especially ARIA attributes and focus management techniques. * **Maintain up-to-date documentation:** Keep the documentation up-to-date with the latest accessibility standards and technology changes. By adhering to these core architecture standards, development teams can build accessible applications that provide a seamless and inclusive user experience for all.

# Component Design Standards for Accessibility This document outlines coding standards for designing accessible components. It focuses on creating reusable, maintainable, and accessible UI elements, adhering to the latest accessibility best practices and standards, including WCAG (Web Content Accessibility Guidelines). These standards aim to improve the user experience for people with disabilities and ensure that the resulting code is robust, scalable, and easy to maintain. ## 1. General Principles ### 1.1. Semantic HTML **Do This:** Use semantic HTML elements appropriately. Semantic HTML provides meaning to the content, making it easier for assistive technologies to understand and interact with the page. **Don't Do This:** Avoid using generic elements like "<div>" and "<span>" when more appropriate semantic elements are available. **Why:** Semantic HTML elements like "<article>", "<nav>", "<aside>", "<header>", "<footer>", "<form>", "<button>", "<input>", "<select>", "<table>" convey structure and purpose, enhancing accessibility by default. **Example:** """html <!-- Correct: Using semantic elements --> <nav aria-label="Main Navigation"> <ul> <li><a href="/">Home</a></li> <li><a href="/about">About</a></li> <li><a href="/contact">Contact</a></li> </ul> </nav> <!-- Incorrect: Using divs for navigation --> <div role="navigation" aria-label="Main Navigation"> <ul> <li><a href="/">Home</a></li> <li><a href="/about">About</a></li> <li><a href="/contact">Contact</a></li> </ul> </div> """ ### 1.2. ARIA Attributes **Do This:** Use ARIA (Accessible Rich Internet Applications) attributes to enhance accessibility when semantic HTML is insufficient. **Don't Do This:** Overuse ARIA attributes or use them incorrectly. ARIA should be used to supplement, not replace, semantic HTML. Avoid ARIA if native HTML provides the same accessibility features. **Why:** ARIA attributes provide additional information to assistive technologies about the role, state, and properties of an element. Incorrect use can lead to contradicting information and a degraded user experience. **Example:** """html <!-- Correct: Using ARIA to enhance a custom component --> <div role="alert" aria-live="assertive"> This is an important message. </div> <!-- Incorrect: Replacing semantic HTML with ARIA --> <div role="button" aria-pressed="false">Click Me</div> <button>Click Me</button> <!-- Preferred: Semantic HTML is better --> """ ### 1.3. Focus Management **Do This:** Ensure that all interactive elements are focusable and that the focus order is logical. Use "tabindex" judiciously for custom components that require keyboard navigation. **Don't Do This:** Create "keyboard traps" where users cannot navigate out of a component using the keyboard. Never remove the browser's default focus styles without providing alternatives that meet color contrast requirements. **Why:** Keyboard users rely on focus to navigate and interact with content. A logical focus order ensures a smooth and understandable user experience. **Example:** """html <!-- Correct: Managing focus for a custom dropdown --> <div id="dropdown-button" tabindex="0" aria-haspopup="true" aria-expanded="false"> Options </div> <ul id="dropdown-menu" role="menu" aria-labelledby="dropdown-button" hidden> <li><a href="#" role="menuitem" tabindex="-1">Option 1</a></li> <li><a href="#" role="menuitem" tabindex="-1">Option 2</a></li> <li><a href="#" role="menuitem" tabindex="-1">Option 3</a></li> </ul> <script> const dropdownButton = document.getElementById('dropdown-button'); const dropdownMenu = document.getElementById('dropdown-menu'); dropdownButton.addEventListener('click', () => { const expanded = dropdownButton.getAttribute('aria-expanded') === 'true'; dropdownButton.setAttribute('aria-expanded', !expanded); dropdownMenu.hidden = expanded; if (!expanded) { dropdownMenu.querySelector('a').focus(); // Focus first item in menu } }); // Handle keyboard navigation within the dropdown menu (Example) dropdownMenu.addEventListener('keydown', (event) => { const menuItems = Array.from(dropdownMenu.querySelectorAll('a')); const currentIndex = menuItems.indexOf(document.activeElement); let nextIndex; if (event.key === 'ArrowDown') { nextIndex = (currentIndex + 1) % menuItems.length; } else if (event.key === 'ArrowUp') { nextIndex = (currentIndex - 1 + menuItems.length) % menuItems.length; } else if (event.key === 'Escape') { dropdownButton.focus(); // Return focus to button on ESC dropdownButton.setAttribute('aria-expanded', 'false'); dropdownMenu.hidden = true; return; } else { return; // Ignore other keys } if (nextIndex !== undefined) { menuItems[nextIndex].focus(); event.preventDefault(); // Prevent scrolling } }); </script> """ ### 1.4. Color and Contrast **Do This:** Ensure sufficient color contrast between text and background, meeting WCAG 2.1 Level AA standards (4.5:1 for normal text, 3:1 for large text). Also, provide alternative ways to distinguish elements besides color. **Don't Do This:** Rely solely on color to convey information. Users who are colorblind or have low vision may miss the information. **Why:** Adequate color contrast is crucial for readability. Providing alternative cues ensures that information is accessible to all users. **Example:** """css /* Correct: Meeting color contrast requirements */ .text { color: #fff; background-color: #333; /* Contrast ratio exceeds 4.5:1 */ } /* Incorrect: Insufficient color contrast */ .text { color: #ccc; background-color: #fff; /* Contrast ratio is too low */ } .required::after { content: " *"; //Adds an asterisk for those who can't differentiate color. color: red; // Still maintains visual cue. } """ ### 1.5. Text Alternatives **Do This:** Provide alternative text ("alt" attribute) for images that convey meaningful information. Ensure that "alt" text is concise and accurately describes the image's content and function. For decorative images, use an empty "alt" attribute ("alt="""). Use "aria-label" or "aria-labelledby" to label controls and regions where a visible label is not practical. **Don't Do This:** Use generic "alt" text like "image" or "logo". Omit "alt" attributes for meaningful images. Use "title" attributes as a replacement for proper labels. Overly verbose descriptions in "alt" text. **Why:** Alt text provides a textual description of images for users who cannot see them. Proper labels are essential for screen reader users to understand the purpose of form elements and other interactive controls. **Example:** """html <!-- Correct: Meaningful alt text --> <img src="logo.png" alt="Company Logo - Navigating Accessibility" /> <!-- Correct: Decorative image --> <img src="decorative-border.png" alt="" aria-hidden="true"/> <!-- Correct: labeling icon button --> <button aria-label="Close"> <svg aria-hidden="true"><!-- ... --></svg> </button> <!-- Incorrect: Missing alt text --> <img src="chart.png" /> <!-- Incorrect: Generic alt text --> <img src="chart.png" alt="image" /> """ ### 1.6. Keyboard Accessibility **Do This:** Ensure all interactive elements are reachable and operable using the keyboard alone. Implement focus indicators for keyboard navigation. Verify keyboard functionality during component development. **Don't Do This:** Rely solely on mouse-driven interactions for essential features. Disable or obscure the browser's default focus outline without providing an alternative. **Why:** Many users depend on keyboard navigation due to motor impairments or preferences. Keyboard accessibility is a core requirement for inclusive design. **Example:** """css /* Correct: Providing a custom focus indicator */ :focus { outline: 2px solid blue; outline-offset: 2px; /* Avoids content overlapping */ } /* Correct: Remove default outline with a focus replacement*/ button:focus { outline: none; box-shadow: 0 0 0 2px blue; } /* Incorrect: Removing focus indicator without providing an alternative */ :focus { outline: none; /* This is an accessibility violation! */ } """ ### 1.7. Forms and Labels **Do This:** Associate form controls with labels using the "<label>" element and the "for" attribute. Group related form controls using "<fieldset>" and "<legend>". Provide clear instructions and error messages regarding form completion. **Don't Do This:** Rely on placeholder text as a replacement for labels. Leave form controls unlabeled. Present error messages only through color changes. **Why:** Labels provide context for form controls, making them understandable for all users, especially screen reader users. Grouping related controls improves the form structure. Clear instructions and error messages prevent user frustration. **Example:** """html <!-- Correct: Associating labels with form controls --> <label for="name">Name:</label> <input type="text" id="name" name="name" /> <fieldset> <legend>Contact Preferences</legend> <input type="checkbox" id="email" name="contact" value="email" /> <label for="email">Email</label> <input type="checkbox" id="phone" name="contact" value="phone" /> <label for="phone">Phone</label> </fieldset> <!-- Incorrect: Using placeholder text as a label --> <input type="text" placeholder="Name" /> """ ### 1.8. Dynamic Content **Do This:** Use ARIA live regions ("aria-live") to announce updates to dynamic content (e.g., notifications, chat messages) to assistive technologies. Ensure that the announced content is meaningful and concise. Use "aria-atomic" and "aria-relevant" appropriately to control the verbosity of announcements. **Don't Do This:** Overuse live regions, which can create a noisy and disruptive user experience. Announce irrelevant or redundant information. **Why:** Live regions allow assistive technologies to inform users about changes in content without requiring a page refresh or focus change. **Example:** """html <!-- Correct: Announcing a new notification --> <div aria-live="polite" aria-atomic="true"> <p>New notification: Your order has shipped.</p> </div> <button onclick="updateNotification()">Update Notification</button> <script> function updateNotification() { const notificationDiv = document.querySelector('[aria-live]'); notificationDiv.innerHTML = '<p>New Notification: Item delivered!</p>'; } </script> """ ### 1.9. Modals and Dialogs **Do This:** Ensure that modals and dialogs are keyboard accessible and that focus is trapped within the dialog when it is open. Provide a clear focus state within the modal. Implement a mechanism to close the dialog (e.g., a close button or the Escape key). Use "aria-modal="true"" and "role="dialog"" to properly identify the container to screen readers. **Don't Do This:** Allow the user to interact with content behind the modal. Fail to trap focus within the modal, making keyboard navigation outside the modal possible. Forget to provide a accessible close button. **Why:** Modals should provide a focused and controlled user experience. Focus management is critical for keyboard users to navigate and interact with the dialog content. **Example:** """html <!-- Modal structure --> <div id="myModal" class="modal" role="dialog" aria-modal="true" aria-labelledby="modalTitle" hidden> <div class="modal-content"> <div class="modal-header"> <h2 id="modalTitle">Modal Title</h2> <button id="closeModalBtn" aria-label="Close">Close</button> </div> <div class="modal-body"> <p>Modal content goes here.</p> <input type="text" /> <button>Submit</button> </div> </div> </div> <button id="openModalBtn">Open Modal</button> <script> const modal = document.getElementById('myModal'); const openModalBtn = document.getElementById('openModalBtn'); const closeModalBtn = document.getElementById('closeModalBtn'); function openModal() { modal.hidden = false; closeModalBtn.focus(); // Set initial focus trapFocus(modal); // Function to trap focus within the modal, explained below. } function closeModal() { modal.hidden = true; openModalBtn.focus(); // Return focus to the button that opened it. } openModalBtn.addEventListener('click', openModal); closeModalBtn.addEventListener('click', closeModal); //Trap focus inside the modal: function trapFocus(element) { const focusableElements = element.querySelectorAll('a[href]:not([disabled]), button:not([disabled]), textarea:not([disabled]), input[type="text"]:not([disabled]), input[type="radio"]:not([disabled]), input[type="checkbox"]:not([disabled]), select:not([disabled])'); const firstFocusableElement = focusableElements[0]; const lastFocusableElement = focusableElements[focusableElements.length - 1]; element.addEventListener('keydown', function(e) { if (e.key === 'Tab') { if (e.shiftKey) { if (document.activeElement === firstFocusableElement) { lastFocusableElement.focus(); e.preventDefault(); } } else { if (document.activeElement === lastFocusableElement) { firstFocusableElement.focus(); e.preventDefault(); } } } else if (e.key === 'Escape') { closeModal(); //Close the modal on escape key press } }); } </script> <!--Basic CSS (expand as needed) --> <style> .modal { position: fixed; top: 0; left: 0; width: 100%; height: 100%; background-color: rgba(0, 0, 0, 0.5); /* Semi-transparent background */ display: flex; align-items: center; justify-content: center; } .modal-content { background-color: white; padding: 20px; border-radius: 5px; width: 500px; /* Adjust width as needed */ max-width: 90%; /* Ensure it fits on smaller screens */ } </style> """ ## 2. Component-Specific Accessibility ### 2.1. Accordions * **Structure:** Use "<details>" and "<summary>" elements for creating accordions. * **ARIA:** Enhance with "aria-expanded" to indicate the expanded/collapsed state. * **Keyboard Navigation:** Ensure keyboard users can open and close accordion sections. * **Example:** """html <details> <summary aria-expanded="false">Section 1</summary> <div> Content for Section 1 </div> </details> <details> <summary aria-expanded="false">Section 2</summary> <div> Content for Section 2 </div> </details> <script> const detailsElements = document.querySelectorAll('details'); detailsElements.forEach(detail => { detail.addEventListener('toggle', () => { const expanded = detail.open; detail.querySelector('summary').setAttribute('aria-expanded', expanded); }); }); </script> """ ### 2.2. Tabs * **Structure:** Use "role="tablist"", "role="tab"", and "role="tabpanel"" to define tab structures. * **ARIA:** Use "aria-selected", "aria-controls", and "aria-labelledby". * **Keyboard Navigation:** Support Left/Right arrow keys for tab navigation. * **Example:** """html <div role="tablist" aria-label="Sample Tabs"> <button role="tab" aria-selected="true" aria-controls="panel1" id="tab1">Tab 1</button> <button role="tab" aria-selected="false" aria-controls="panel2" id="tab2">Tab 2</button> <div role="tabpanel" id="panel1" aria-labelledby="tab1"> Content for Tab 1 </div> <div role="tabpanel" id="panel2" aria-labelledby="tab2" hidden> Content for Tab 2 </div> </div> <script> const tabs = document.querySelectorAll('[role="tab"]'); const tabPanels = document.querySelectorAll('[role="tabpanel"]'); tabs.forEach(tab => { tab.addEventListener('click', () => { // Deselect all tabs and hide all panels tabs.forEach(t => t.setAttribute('aria-selected', false)); tabPanels.forEach(p => p.setAttribute('hidden', '')); // Select the clicked tab and show the corresponding panel tab.setAttribute('aria-selected', true); const panelId = tab.getAttribute('aria-controls'); document.getElementById(panelId).removeAttribute('hidden'); }); }); </script> """ ### 2.3. Carousels * **ARIA:** Use "role="region"" to identify the carousel. Optionally, provide controls with "aria-label" for navigation. * **Keyboard Navigation:** Allow keyboard users to navigate carousel items. * **Pause/Play:** Provide a mechanism to pause and play the automatic sliding of carousel items. * **Implementation:** Focus management is crucial to avoid focus traps. Consider using well-tested libraries for complex carousels. """html <div id="myCarousel" role="region" aria-label="Image Carousel"> <div> <img src="image1.jpg" alt="Description of image 1"> </div> <div> <img src="image2.jpg" alt="Description of image 2"> </div> <button aria-label="Previous Image">Previous</button> <button aria-label="Next Image">Next</button> <button aria-label="Pause Slideshow">Pause</button> </div> """ ## 3. Code Maintainability and Reusability ### 3.1. Component-Based Architecture **Do This:** Develop UIs using a component-based architecture (e.g., React, Angular, Vue.js, or Web Components). Properly encapsulate components to manage their states and behaviors. **Don't Do This:** Create monolithic codebases. This is hard to maintain, test, and reuse. Write inline styles directly in HTML as this violates separation of concerns. **Why:** Component-based architectures promote modularity, reusability, and testability, which simplifies accessibility implementation and maintenance. ### 3.2. Design Patterns **Do This:** Use established design patterns for accessibility, such as the ARIA Design Patterns (formerly known as the WAI-ARIA Authoring Practices). **Don't Do This:** Reinvent the wheel. This can introduce inconsistencies and accessibility issues. **Why:** Following well-established patterns ensures consistency and predictability, which simplifies accessibility testing and implementation. ### 3.3. Documentation **Do This:** Document the accessibility features of each component, including ARIA attributes, keyboard interactions, and expected behavior. Use tools like Storybook to showcase interactive components. **Don't Do This:** Skip accessibility documentation, leaving maintainers unsure of accessibility considerations. **Why:** Documentation is crucial for ensuring that accessibility is maintained over time. ## 4. Testing and Validation ### 4.1. Automated Testing **Do This:** Implement automated accessibility tests using tools like axe-core (available for various testing frameworks). Integrate these tests into the CI/CD pipeline. **Don't Do This:** Rely solely on manual testing as it's prone to human error. **Why:** Automated testing helps catch common accessibility issues early in the development process. ### 4.2. Manual Testing **Do This:** Perform manual accessibility testing using screen readers (e.g., NVDA, VoiceOver) and keyboard navigation. **Don't Do This:** Skip manual testing, particularly with screen readers. **Why:** Manual testing uncovers issues that automated tests may miss and provides a more holistic understanding of the user experience. ### 4.3. Validation **Do This:** Validate code against accessibility standards using tools like the WAVE browser extension or the Accessibility Insights browser extension. **Don't Do This:** Ignore validation errors. **Why:** Validation helps ensure compliance with accessibility standards such as WCAG. ## 5. Advanced Considerations ### 5.1. Performance Optimization **Do This:** Optimize components for performance to ensure a smooth experience for users of assistive technologies. Use techniques like lazy loading and code splitting. **Don't Do This:** Ignore performance considerations which impact the responsiveness of assistive tech. **Why:** Poor performance can degrade the user experience for all users, especially those using assistive technologies. ### 5.2. Internationalization (i18n) & Localization (l10n) **Do This:** Ensure that components are designed to support internationalization and localization, including proper handling of text direction (e.g., RTL languages) and date/time formats. **Don't Do This:** Hardcode text or assume a specific language or locale. **Why:** i18n and l10n ensure that the component is accessible to users from different regions and languages. ### 5.3. Security **Do This:** Sanitize user input to prevent cross-site scripting (XSS) attacks, which could compromise accessibility. Validate server-side rendering for accessibility and security. **Don't Do This:** Trust user input or neglect security testing. **Why:** Security vulnerabilities can negatively impact accessibility and pose a threat to users. This comprehensive guide provides a solid foundation for building accessible components. Consistent adherence to these coding standards will ensure a more inclusive and usable experience for all users, while improving code quality and maintainability. Remember to stay updated on the latest accessibility advancements and adapt these standards accordingly.

# State Management Standards for Accessibility This document outlines coding standards for state management in Accessibility, focusing on data flow, reactivity, and how these principles impact accessibility. It provides actionable guidelines, best practices, and code examples for developers to build accessible and maintainable applications. ## 1. Introduction to State Management and Accessibility State management is critical for creating dynamic and interactive user interfaces. When building accessible applications, managing state correctly is essential to ensure assistive technologies can accurately interpret and convey changes in the UI. This document covers patterns and standards that address these needs. **Key Considerations:** * **Assistive Technology Awareness:** State changes must be communicated effectively to assistive technologies like screen readers. * **Predictable Behavior:** The UI should behave predictably based on state changes, enabling users to understand and interact with the application consistently. * **Modularity and Maintainability:** Well-structured state management simplifies maintenance and scalability. ## 2. Patterns for Accessible State Management ### 2.1. Centralized State Management **Definition:** Storing all application state in a single, centralized location. This central store acts as the "single source of truth" and promotes predictable updates. **Why:** Centralized state simplifies debugging and provides a clear overview of all application data. It also allows for easier integration of accessibility features since all state changes can be monitored from one location. **Do This:** * Use a dedicated state management library (e.g., stores, Redux, Vuex) for complex applications. * Structure your state in a way that reflects the application's overall architecture. * Implement actions or mutations to handle state updates consistently. **Don't Do This:** * Rely on deeply nested component state, as it becomes difficult to track and update. * Modify state directly without using defined actions/mutations. **Code Example (stores):** """javascript // store.js import { writable } from 'stores'; export const counter = writable(0); export const increment = () => { counter.update(n => n + 1); }; export const decrement = () => { counter.update(n => n - 1); }; // Component using the store: // MyComponent.jsx import { counter, increment, decrement } from './store.js'; import { get } from 'stores'; const MyComponent = () => { const currentCount = get(counter); const handleIncrement = () => { increment(); }; const handleDecrement = () => { decrement(); }; return ( Current Count: {currentCount} Increment Decrement ); }; export default MyComponent; """ **Accessibility Considerations:** Screen readers should be notified when the "counter" value changes. While basic numeric output is usually read, providing context is better: """javascript import { counter, increment, decrement } from './store.js'; import { get } from 'stores'; const MyComponent = () => { const currentCount = get(counter); const handleIncrement = () => { increment(); }; const handleDecrement = () => { decrement(); }; return ( Current Count: {currentCount} Increment Decrement ); }; export default MyComponent; // Use aria-live to notify screen readers of changes // In store: export const counter = writable(0); counter.subscribe(newCount => { const ariaLiveElement = document.getElementById('counter-value'); if (ariaLiveElement) { ariaLiveElement.textContent = "Current count: ${newCount}"; } }); """ ### 2.2. Context API **Definition:** A way to pass data through the component tree without manually passing props at every level. It enables sharing values like theme, language, or user authentication across multiple components. **Why:** Reduces prop drilling and makes it easier to manage global configurations and access settings across the application. **Do This:** * Use Context when you need to share data between a moderate number of deeply nested components. * Create a provider component to manage the shared state and provide it to child components. * Use "useContext" hook to consume the context value in functional components. **Don't Do This:** * Overuse Context for every small state variable, as it can lead to performance issues and unnecessary re-renders. * Mutate Context values directly within consumer components. Instead, provide update functions in the provider. **Code Example:** """javascript // ThemeContext.js import { createContext, useState } from 'react'; export const ThemeContext = createContext(); export const ThemeProvider = ({ children }) => { const [theme, setTheme] = useState('light'); const toggleTheme = () => { setTheme(prevTheme => (prevTheme === 'light' ? 'dark' : 'light')); }; const value = { theme, toggleTheme, }; return ( {children} ); }; // Usage in a component: import { useContext } from 'react'; import { ThemeContext } from './ThemeContext'; const ThemedComponent = () => { const { theme, toggleTheme } = useContext(ThemeContext); return ( Current Theme: {theme} Toggle Theme ); }; export default ThemedComponent; """ **Accessibility Considerations:** Themes often involve color contrast. The state should be used to set CSS classes that control contrast and announce the change to screen readers via ARIA attributes. """javascript // ThemeContext.js import { createContext, useState, useEffect } from 'react'; export const ThemeContext = createContext(); export const ThemeProvider = ({ children }) => { const [theme, setTheme] = useState('light'); useEffect(() => { document.body.classList.toggle('dark-theme', theme === 'dark'); const ariaLiveMessage = (theme === 'dark') ? "Switched to dark theme" : "Switched to light theme"; const themeAnnouncement = document.getElementById("theme-announcement"); if(themeAnnouncement){ themeAnnouncement.textContent = ariaLiveMessage; } }, [theme]); const toggleTheme = () => { setTheme(prevTheme => (prevTheme === 'light' ? 'dark' : 'light')); }; const value = { theme, toggleTheme, }; return ( <span id="theme-announcement" aria-live="polite" className="visually-hidden"></span> {children} ); }; """ """css /*Global Styles*/ .dark-theme { background-color: #333; color: #fff; } .dark-theme button { background-color: #555; color: #fff; } .visually-hidden { position: absolute !important; width: 1px !important; height: 1px !important; padding: 0 !important; margin: -1px !important; overflow: hidden !important; clip: rect(0, 0, 0, 0) !important; white-space: nowrap !important; border: 0 !important; } """ ### 2.3. Lifting State Up **Definition:** Moving the state to the closest common ancestor component. This pattern ensures that all components that need to access or modify the state have a single source of truth. **Why:** Simplifies state synchronization between components and avoids inconsistencies. **Do This:** * Identify the components that share state. * Move the state to their nearest common ancestor. * Pass down the state and update functions as props to the child components. **Don't Do This:** * Lift state up unnecessarily high in the component tree, as it can make components harder to reuse. * Modify the state directly within child components. **Code Example:** """javascript // Parent component import React, { useState } from 'react'; import ChildA from './ChildA'; import ChildB from './ChildB'; const Parent = () => { const [message, setMessage] = useState(''); const handleMessageChange = (newMessage) => { setMessage(newMessage); }; return ( <ChildA onMessageChange={handleMessageChange} /> <ChildB message={message} /> ); }; export default Parent; // ChildA component import React from 'react'; const ChildA = ({ onMessageChange }) => { const handleChange = (event) => { onMessageChange(event.target.value); }; return ( Enter Message: <input type="text" onChange={handleChange} /> ); }; export default ChildA; // ChildB component import React from 'react'; const ChildB = ({ message }) => { return ( Message from ChildA: {message} ); }; export default ChildB; """ **Accessibility Considerations:** When "message" changes, ChildB should update its display and announce this change via an "aria-live" region, especially if it's important for the user to know immediately. """javascript // ChildB component import React from 'react'; import { useEffect, useRef } from 'react'; const ChildB = ({ message }) => { const messageRef = useRef(null); useEffect(() => { messageRef.current.textContent = "Message from ChildA: ${message}"; //Update the content //Announce the changes using aria-live const announcement = document.getElementById("message-announcement"); if (announcement) { announcement.textContent = "New message received: ${message}"; } }, [message]); return ( <span id="message-announcement" aria-live="polite" className="visually-hidden"></span> <div ref={messageRef}>Message from ChildA: {message}</div> ); }; export default ChildB; """ ### 2.4. Reactive Programming with signals **Definition:** Use signals to manage state. Reactive programming allows you to define data streams and automatically propagate changes throughout your application. **Why:** Reactive programming simplifies asynchronous operations and enhances UI responsiveness. Signals can encapsulate complex logic and ensure that UI components are updated automatically when underlying data changes. **Do This:** * Explore reactive libraries optimized for store updates (e.g., stores). * Use signals to manage asynchronous data streams and side effects, simplifying complex code. * Ensure that reactive updates are batched efficiently to minimize unnecessary re-renders. **Don't Do This:** * Overuse signals for simple state variables, as it can introduce unnecessary complexity. * Create circular dependencies between signals, which can lead to infinite loops and performance issues. **Code Example (stores):** """javascript // Store import { writable } from 'stores'; export const inputValue = writable(""); export const setInputValue = (newValue) => { inputValue.set(newValue); } // Component import { inputValue, setInputValue } from './store'; import { get } from 'stores'; const InputComponent = () => { const updateValue = (event) => { setInputValue(event.target.value); }; return ( Input Value: <input type="text" onChange={updateValue} /> <p>Current input Value: {get(inputValue)}</p> ); }; export default InputComponent; """ **Accessibility Considerations:** Whenever "inputValue" changes, any associated accessible elements (e.g., live regions) need to reflect that change. """javascript import { inputValue, setInputValue } from './store'; import { get } from 'stores'; import { useEffect, useRef } from 'react'; const InputComponent = () => { const updateValue = (event) => { setInputValue(event.target.value); }; const inputValueRef = useRef(null); useEffect(() => { //Update the content and aria-live region inputValueRef.current.textContent = "Current input Value: ${get(inputValue)}"; const announcement = document.getElementById("input-announcement"); if (announcement) { announcement.textContent = "Input has changed to ${get(inputValue)}"; } }, [get(inputValue)]); return ( Input Value: <input type="text" onChange={updateValue} /> <div ref={inputValueRef}>Current input Value: {get(inputValue)}</div> ); }; export default InputComponent; """ ## 3. Accessibility-Specific Considerations ### 3.1. Announcing State Changes Assistive technologies rely on appropriate ARIA attributes to understand the current state of the UI. **Do This:** * Use "aria-live" regions to announce dynamic changes in the UI. * Use "aria-atomic" to indicate whether the entire region should be read when a change occurs. * Use "aria-relevant" to specify the types of changes that should be announced ("additions", "removals", "text", "all"). Example: """html <div aria-live="polite">The current status is: <span id="status-text">Idle</span></div> """ **Don't Do This:** * Overuse "aria-live", as it can overwhelm users with unnecessary announcements. * Update "aria-live" regions too frequently, as it can disrupt the user experience. **Code Example:** """javascript import React, { useState, useEffect } from 'react'; const StatusComponent = () => { const [status, setStatus] = useState('Idle'); useEffect(() => { // Simulate status updates every 2 seconds const intervalId = setInterval(() => { setStatus(prevStatus => (prevStatus === 'Idle' ? 'Loading' : 'Idle')); }, 2000); return () => clearInterval(intervalId); // Clear interval on unmount }, []); return ( The current status is: <span id="status-text">{status}</span> ); }; export default StatusComponent; """ ### 3.2. Focus Management Properly managing focus is crucial for keyboard navigation and screen reader users. **Do This:** * Use "tabIndex" to control the focus order of elements. * Use "focus" and "blur" events to handle focus changes. * Use "aria-activedescendant" to manage focus within composite widgets. **Don't Do This:** * Use "tabIndex" indiscriminately, as it can disrupt the natural focus order. * Remove focus from elements unexpectedly, as it can disorient users. **Code Example:** """javascript import React, { useRef, useEffect } from 'react'; const FocusComponent = () => { const buttonRef = useRef(null); useEffect(() => { // Automatically set focus on the button when the component mounts buttonRef.current.focus(); }, []); return ( Focusable Button ); }; export default FocusComponent; """ ### 3.3. Semantic HTML Using semantic HTML elements provides built-in accessibility features and simplifies UI structure. **Do This:** * Use appropriate HTML elements for each UI component ("<button>", "<nav>", "<article>", etc.). * Use ARIA roles, states, and properties to enhance the semantic meaning of non-semantic elements. * Ensure that interactive elements are focusable and can be operated with keyboard. **Don't Do This:** * Use "<div>" and "<span>" elements for everything, as it reduces semantic meaning. * Rely solely on ARIA attributes without using semantic HTML elements. **Code Example:** """html <nav aria-label="Main Navigation"> <ul> <li><a href="/">Home</a></li> <li><a href="/about">About</a></li> <li><a href="/contact">Contact</a></li> </ul> </nav> """ ## 4. Modern Accessibility Tools and Libraries ### 4.1. Accessibility Linters and Analyzers Tools like "@axe-core/react" can automatically identify accessibility issues during development. **Do This:** * Integrate accessibility linters into your build process. * Run accessibility tests regularly to catch issues early. * Use automated tools to complement manual testing and code reviews. **Code Example:** """javascript // Example usage with @axe-core/react import { Axe } from '@axe-core/react'; if (process.env.NODE_ENV === 'development') { Axe(React, ReactDOM, 1000); // Delay of 1 second } """ ### 4.2. Testing Libraries Libraries like "react-testing-library" encourage writing tests that focus on user behavior, making it easier to test accessibility. **Do This:** * Write tests from the user's perspective, focusing on interactions rather than implementation details. * Use ARIA roles and labels in your tests to emulate assistive technology behavior. **Code Example:** """javascript import { render, screen } from '@testing-library/react'; import userEvent from '@testing-library/user-event'; import MyComponent from './MyComponent'; test('renders a button and fires a click event', () => { render(<MyComponent />); const button = screen.getByRole('button', { name: 'Click Me' }); userEvent.click(button); expect(screen.getByText('Button Clicked')).toBeInTheDocument(); }); """ ## 5. Anti-Patterns to Avoid ### 5.1. Over-Reliance on Visual Cues **Problem:** Relying solely on visual cues to convey information can exclude users who are visually impaired. **Solution:** Provide alternative text descriptions, use ARIA attributes, and ensure sufficient color contrast. ### 5.2. Ignoring Keyboard Accessibility **Problem:** Many interactive components are not accessible via keyboard, making them unusable for users who cannot use a mouse. **Solution:** Ensure that all interactive elements are focusable and can be operated with the keyboard. Use "tabIndex" to manage focus order. ### 5.3. Insufficient Contrast **Problem:** Low contrast between text and background can make it difficult for users with low vision to read content. **Solution:** Ensure sufficient color contrast (WCAG 2.1 level AA requires a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text). ## 6. Security Considerations When managing state, ensure that sensitive data is handled securely to prevent unauthorized access or modification. **Do This:** * Encrypt sensitive data stored in the state. * Validate user inputs to prevent injection attacks. * Implement proper authorization checks to restrict access to state data. **Don't Do This:** * Store sensitive data in plain text in the state. * Expose state data directly to unauthorized users. ## 7. Performance Optimization Efficient state management is essential for maintaining optimal application performance. **Do This:** * Use memoization techniques to prevent unnecessary re-renders. * Batch state updates to minimize the number of UI updates. * Optimize data structures to reduce memory consumption. **Don't Do This:** * Update state unnecessarily, as it can trigger costly re-renders. * Use inefficient data structures that consume excessive memory. ## 8. Conclusion Effective state management is fundamental to building accessible and maintainable applications. By following these coding standards, developers can ensure that their applications are usable by everyone, regardless of ability. These guidelines help to build robust applications that are both highly accessible and performant by focusing on semantic HTML, ARIA attributes, and modern Accessibility libraries.

# Performance Optimization Standards for Accessibility This document outlines coding standards for optimizing accessibility performance in applications. Adhering to these standards will help create responsive, efficient, and inclusive user experiences. ## 1. General Principles ### 1.1. Minimize DOM Manipulation **Standard:** Reduce the number of DOM manipulations, especially during user interactions or animations. **Why:** Frequent DOM manipulation can cause significant performance overhead, leading to stuttering or unresponsive interfaces for all users, but disproportionately impacting users with assistive technologies (AT) who may require larger processing power. **Do This:** * Use efficient methods for updating the DOM. * Batch updates to reduce the number of reflows and repaints. * Consider using virtual DOM techniques where appropriate. **Don't Do This:** * Directly manipulate the DOM in loops or during frequently occurring events. * Use inefficient selectors that cause unnecessary re-evaluation of the DOM. **Code Example (JavaScript):** """javascript // Efficient DOM update function updateList(items) { const list = document.getElementById('myList'); const fragment = document.createDocumentFragment(); // Create a fragment for batch updates items.forEach(item => { const listItem = document.createElement('li'); listItem.textContent = item; fragment.appendChild(listItem); }); list.appendChild(fragment); // Append the entire fragment at once } // Inefficient DOM update function updateListInefficient(items) { const list = document.getElementById('myList'); items.forEach(item => { const listItem = document.createElement('li'); listItem.textContent = item; list.appendChild(listItem); // Repeated DOM manipulation in a loop }); } """ ### 1.2. Optimize Resource Loading **Standard:** Load only necessary resources, and defer loading non-critical resources. **Why:** Loading unnecessary resources can slow down the initial page load and overall application performance. This is crucial for accessibility, as it directly impacts the responsiveness of AT and the speed at which users navigate content. **Do This:** * Use lazy loading for images and other media. * Minify and compress CSS and JavaScript files. * Use a Content Delivery Network (CDN) to serve static assets. **Don't Do This:** * Load large, unoptimized images or videos. * Include unused CSS or JavaScript code. **Code Example (HTML - Lazy Loading):** """html <img src="low-res.jpg" data-src="high-res.jpg" alt="Descriptive alt text" loading="lazy"> <script> // Use a polyfill for older browsers if needed if ('loading' in HTMLImageElement.prototype) { const images = document.querySelectorAll('img[loading="lazy"]'); images.forEach(img => { img.src = img.dataset.src; }); } else { // Dynamically import the lazySizes library const script = document.createElement('script'); script.src = "https://cdnjs.cloudflare.com/ajax/libs/lazysizes/5.3.2/lazysizes.min.js"; document.body.appendChild(script); } </script> """ ### 1.3. Efficient Event Handling **Standard:** Use event delegation to reduce the number of event listeners. **Why:** Attaching numerous event listeners to individual elements can degrade performance. Event delegation allows you to attach a single listener to a parent element, improving efficiency. This helps keep ATs responsive. **Do This:** * Attach event listeners to a common parent element. * Use the event target to identify the source of the event. **Don't Do This:** * Attach event listeners to individual elements within a large list or table. **Code Example (JavaScript - Event Delegation):** """javascript // Event Delegation document.getElementById('myList').addEventListener('click', function(event) { if (event.target && event.target.nodeName == 'LI') { console.log('List item clicked:', event.target.textContent); } }); // Inefficient - attaching to each list item directly /* const listItems = document.querySelectorAll('#myList li'); listItems.forEach(item => { item.addEventListener('click', function() { console.log('List item clicked:', this.textContent); }); }); */ """ ### 1.4. Debouncing and Throttling **Standard:** Implement debouncing and throttling for frequently occurring events. **Why:** For events like window resizing, scrolling, or key presses, execute code only after a delay or at a limited rate. This is crucial for optimizing AT tools performance. **Do This:** * Use debouncing to delay execution until the user stops triggering the event. * Use throttling to limit execution to a specific rate. **Don't Do This:** * Execute computationally expensive operations directly within frequently occurring event handlers. **Code Example (JavaScript - Debouncing):** """javascript function debounce(func, delay) { let timeout; return function(...args) { const context = this; clearTimeout(timeout); timeout = setTimeout(() => func.apply(context, args), delay); }; } function handleResize() { console.log('Resizing window...'); // Perform some expensive operation } const debouncedResizeHandler = debounce(handleResize, 250); // Delay of 250ms window.addEventListener('resize', debouncedResizeHandler); """ ### 1.5. Asynchronous Operations **Standard:** Perform long-running tasks asynchronously. **Why:** Blocking the main thread with synchronous operations can freeze the UI. Accessibility tools and applications benefit from smooth, uninterrupted operation, which asynchronous tasks support. **Do This:** * Use "async/await" or Promises for asynchronous operations. * Use Web Workers for CPU-intensive tasks. **Don't Do This:** * Perform synchronous operations within event handlers. **Code Example (JavaScript - Async/Await):** """javascript async function fetchData() { try { const response = await fetch('https://example.com/data'); const data = await response.json(); console.log('Data:', data); } catch (error) { console.error('Error fetching data:', error); } } fetchData(); """ ## 2. Accessibility-Specific Optimization ### 2.1. ARIA Attribute Optimization **Standard:** Use ARIA attributes efficiently and sparingly. **Why:** ARIA attributes add semantic information but can also introduce overhead if not used correctly. Screen readers process ARIA attributes, so optimizing their use is vital for performance. **Do This:** * Only use ARIA attributes when native HTML elements are not sufficient. * Avoid redundant ARIA attributes. * Update ARIA attributes judiciously based on user interactions. **Don't Do This:** * Overuse ARIA attributes. * Use ARIA attributes that duplicate native HTML semantics. * Update ARIA attributes excessively, especially during animations. **Code Example (HTML):** """html <!-- Correct Usage: ARIA only when necessary --> <button onclick="toggleMenu()" aria-expanded="false">Toggle Menu</button> <div id="menu" role="menu" aria-hidden="true"> <a href="#" role="menuitem">Item 1</a> <a href="#" role="menuitem">Item 2</a> </div> <script> function toggleMenu() { const menu = document.getElementById('menu'); const button = document.querySelector('button[aria-expanded]'); const expanded = button.getAttribute('aria-expanded') === 'true'; button.setAttribute('aria-expanded', String(!expanded)); menu.setAttribute('aria-hidden', String(expanded)); } </script> <!-- Incorrect Usage: Redundant ARIA --> <!-- <button role="button" aria-label="Click me" onclick="doSomething()">Click me</button> --> """ ### 2.2. Focus Management **Standard:** Implement proper focus management. **Why:** Poor focus management can make web applications difficult to navigate for keyboard users and screen reader users. Optimized focus management improves speed and context understanding. **Do This:** * Ensure focus is always visible. * Programmatically move focus to appropriate elements after user actions. * Use "tabindex" attribute judiciously. **Don't Do This:** * Remove focus outlines. * Trap focus within a specific section of the page. **Code Example (JavaScript - Moving Focus):** """javascript function openModal() { const modal = document.getElementById('myModal'); modal.style.display = 'block'; const closeButton = modal.querySelector('.close-button'); closeButton.focus(); // Move focus to the close button } function closeModal() { const modal = document.getElementById('myModal'); modal.style.display = 'none'; const openButton = document.getElementById('openModalButton'); openButton.focus(); // Return focus to the button that opened the modal } """ ### 2.3. Live Regions **Standard:** Use ARIA live regions appropriately to announce dynamic content updates. **Why:** Live regions provide screen readers with notifications about dynamic content changes, but overuse can lead to excessive chatter and a poor user experience. **Do This:** * Use "aria-live="polite"" for non-critical updates. * Use "aria-live="assertive"" sparingly, only for critical updates. * Keep live region content concise. **Don't Do This:** * Overuse live regions. * Use "aria-live="assertive"" for trivial updates. **Code Example (HTML - Live Region):** """html <div id="status" aria-live="polite"></div> <script> function updateStatus(message) { const statusDiv = document.getElementById('status'); statusDiv.textContent = message; } // Example usage: setTimeout(() => { updateStatus('Data loaded successfully.'); }, 2000); </script> """ ### 2.4. Semantic HTML **Standard:** Use semantic HTML elements to provide structural meaning to content. **Why:** Semantic HTML elements enhance accessibility by providing inherent meaning to web content, allowing AT to better interpret and present information to users. This helps users focus on content, not navigating the site. **Do This:** * Use "<header>", "<nav>", "<main>", "<article>", "<aside>", "<footer>" elements to structure content. * Use appropriate heading levels ("<h1>" to "<h6>") to define content hierarchy. * Use "<p>", "<ul>", "<ol>", "<li>" elements to structure text and lists. **Don't Do This:** * Use "<div>" and "<span>" elements excessively without semantic meaning. * Use heading elements for styling purposes only. * Skip heading levels in the content hierarchy. **Code Example (HTML - Semantic Structure):** """html <header> <h1>My Website</h1> <nav> <ul> <li><a href="#">Home</a></li> <li><a href="#">About</a></li> <li><a href="#">Contact</a></li> </ul> </nav> </header> <main> <article> <h2>Article Title</h2> <p>Article content goes here.</p> </article> </main> <footer> <p>© 2024 My Website</p> </footer> """ ### 2.5. Text Alternatives **Standard:** Provide meaningful text alternatives for non-text content. **Why:** Text alternatives, such as "alt" attributes for images and transcripts for audio/video content, ensure that information is accessible to users who cannot see or hear the content. **Do This:** * Provide descriptive "alt" attributes for images. * Provide transcripts for audio and video content. * Use "aria-label" or "aria-labelledby" to provide labels for form elements and interactive components. **Don't Do This:** * Use generic or missing "alt" attributes. * Fail to provide transcripts or captions for multimedia content. **Code Example (HTML - Image Alt Text):** """html <img src="my-image.jpg" alt="A scenic view of a mountain range at sunset"> <video controls> <source src="my-video.mp4" type="video/mp4"> <track src="captions.vtt" kind="captions" label="English" srclang="en"> </video> """ ## 3. Technology-Specific Guidance ### 3.1. React **Standard:** Follow accessibility best practices when building React components. **Why:** React's component-based architecture allows for creating reusable and accessible UI elements, but neglecting accessibility can lead to significant issues. **Do This:** * Use libraries like "eslint-plugin-jsx-a11y" to catch accessibility issues during development. * Use semantic HTML elements and ARIA attributes correctly. * Manage focus appropriately. * Optimize re-renders of components that contain accessibility-related attributes. * Use "React.memo" to prevent unnecessary re-renders of pure components * Use "useCallback" and "useMemo" to memoize functions and values passed as props **Don't Do This:** * Use "dangerouslySetInnerHTML" without careful consideration. * Ignore accessibility warnings from linting tools. **Code Example (React - Accessible Component):** """jsx import React, { useState } from 'react'; function AccessibleButton({ onClick, children }) { const [isPressed, setIsPressed] = useState(false); const handleClick = () => { setIsPressed(!isPressed); onClick(); }; return ( <button onClick={handleClick} aria-pressed={isPressed} aria-label="Toggle Button" > {children} </button> ); } export default AccessibleButton; """ ### 3.2. Angular **Standard:** Implement accessibility best practices when building Angular components. **Why:** Angular's framework provides tools for building accessible applications, but requires developers to actively use them. **Do This:** * Use the Angular CLI to scaffold accessible components. * Use "@angular/cdk/a11y" for accessibility utilities. * Ensure that templates are accessible. * Use Angular's change detection strategies effectively to minimize unnecessary DOM updates. * Use the "trackBy" function with "*ngFor" to optimize rendering of lists. **Don't Do This:** * Disable Angular's change detection without careful consideration. * Ignore accessibility warnings from linting tools and template checks. **Code Example (Angular - Accessible Form):** """typescript import { Component } from '@angular/core'; import { FormControl, FormGroup, Validators } from '@angular/forms'; @Component({ selector: 'app-accessible-form', template: " <form [formGroup]="myForm" (ngSubmit)="onSubmit()"> <label for="name">Name:</label> <input type="text" id="name" formControlName="name" aria-required="true"> <div *ngIf="myForm.get('name')?.invalid && myForm.get('name')?.touched"> Name is required. </div> <label for="email">Email:</label> <input type="email" id="email" formControlName="email" aria-required="true"> <div *ngIf="myForm.get('email')?.invalid && myForm.get('email')?.touched"> Email is invalid. </div> <button type="submit" [disabled]="myForm.invalid">Submit</button> </form> ", }) export class AccessibleFormComponent { myForm = new FormGroup({ name: new FormControl('', Validators.required), email: new FormControl('', [Validators.required, Validators.email]), }); onSubmit() { if (this.myForm.valid) { console.log('Form submitted:', this.myForm.value); } } } """ ### 3.3. Vue.js **Standard:** Follow accessibility guidelines when building Vue.js components. **Why:** Vue.js's progressive framework allows you to create accessible UI elements, but accessibility must be a primary concern. **Do This:** * Use "eslint-plugin-vue-a11y" to catch accessibility issues during development. * Use semantic HTML elements and ARIA attributes correctly. * Use Vue's reactivity system efficiently to update ARIA attributes. * Optimize rendering of large lists using the "key" attribute and "v-for". **Don't Do This:** * Use "v-html" without careful consideration. * Ignore accessibility warnings from linting tools. **Code Example (Vue.js - Accessible List):** """vue <template> <ul> <li v-for="item in items" :key="item.id" role="menuitem"> <a :href="item.url">{{ item.name }}</a> </li> </ul> </template> <script> export default { name: 'AccessibleList', data() { return { items: [ { id: 1, name: 'Item 1', url: '#' }, { id: 2, name: 'Item 2', url: '#' }, { id: 3, name: 'Item 3', url: '#' }, ], }; }, }; </script> """ ## 4. Testing and Monitoring ### 4.1. Automated Testing **Standard:** Implement automated accessibility tests. **Why:** Automated tests can catch common accessibility issues early in the development process, allowing for quicker remediation and preventing regressions. **Do This:** * Use tools like Axe, WAVE, or Lighthouse for automated accessibility testing. * Integrate accessibility tests into your CI/CD pipeline. **Don't Do This:** * Rely solely on manual testing. * Ignore accessibility testing results. ### 4.2. Manual Testing **Standard:** Conduct manual accessibility testing with assistive technologies. **Why:** Manual testing with AT provides valuable insights into the user experience that automated tests cannot capture. **Do This:** * Test your application with screen readers like NVDA, JAWS, or VoiceOver. * Test with keyboard navigation. * Test with speech recognition software. **Don't Do This:** * Assume that your application is accessible based solely on automated testing. ### 4.3. Performance Monitoring **Standard:** Monitor the performance of your application, especially in relation to accessibility. **Why:** Poor performance can disproportionately impact users with disabilities. Monitoring performance allows you to identify and address issues that may affect accessibility. **Do This:** * Use performance monitoring tools to track page load times, rendering performance, and resource usage. * Pay particular attention to the performance of features that are heavily used by AT. **Don't Do This:** * Ignore performance metrics. * Prioritize features over performance and accessibility. By following these performance optimization standards, developers can create applications that are not only fast and efficient but also accessible to all users.