@juspay/blend-design-system 0.0.37-beta.2 → 0.0.37-beta.4

package/lib/components/Alert/accessibility/AlertAccessibilityReport.ts

@@ -0,0 +1,549 @@
+/**
+ * Alert Component Accessibility Report Data
+ * WCAG 2.0, 2.1, 2.2 Level A, AA, AAA Compliance Analysis
+ *
+ * Note: Items marked with "unsure" require manual verification
+ * Color contrast ratios verified using actual color values from theme tokens
+ */
+
+export type WCAGSuccessCriterion = {
+    id: string
+    level: 'A' | 'AA' | 'AAA'
+    title: string
+    status: 'compliant' | 'non-compliant' | 'unsure' | 'not-applicable'
+    description: string
+    implementation: string
+    testResults?: string
+    notes?: string
+}
+
+export type AccessibilityReport = {
+    componentName: string
+    wcagVersion: string
+    reportDate: string
+    conformanceLevel: string
+    overallStatus: 'compliant' | 'non-compliant' | 'partial' | 'unsure'
+    summary: string
+    criteria: WCAGSuccessCriterion[]
+    strengths: string[]
+    recommendations: string[]
+    wcagVersions: {
+        '2.0': string[]
+        '2.1': string[]
+        '2.2': string[]
+    }
+    testMethodology: {
+        automated: string[]
+        manual: string[]
+        verificationTools: string[]
+        wcagLevels: {
+            A: string[]
+            AA: string[]
+            AAA: string[]
+        }
+    }
+}
+
+export const alertAccessibilityReport: AccessibilityReport = {
+    componentName: 'Alert',
+    wcagVersion: '2.2',
+    reportDate: new Date().toISOString().split('T')[0],
+    conformanceLevel: 'Level AA',
+    overallStatus: 'partial',
+    summary:
+        'The Alert component demonstrates strong compliance with WCAG 2.0, 2.1, and 2.2 standards at Level A and Level AA. The component implements proper ARIA roles (alert/status), semantic HTML structure with heading and description, comprehensive ARIA labels, keyboard navigation support, and proper focus management. Error and warning alerts use role="alert" for immediate attention, while other alerts use role="status" for polite announcements. All interactive elements are keyboard accessible. Touch target sizes (44x44px for AAA compliance) are planned for future implementation. The component fully meets Level A and Level AA requirements, with Level AAA compliance pending touch target size implementation.',
+    criteria: [
+        {
+            id: '1.1.1',
+            level: 'A',
+            title: 'Non-text Content',
+            status: 'compliant',
+            description:
+                'All non-text content has text alternatives. Decorative icons and visual elements are properly marked.',
+            implementation:
+                'Icons are marked with aria-hidden="true". Close icon (X) is marked with aria-hidden="true". Separator between actions and close button is marked with aria-hidden="true" and role="separator". All interactive elements have proper text labels via aria-label attributes or visible text.',
+            testResults:
+                'Verified: All decorative content properly hidden. Interactive elements have accessible names. Implementation confirmed in Alert.tsx.',
+        },
+        {
+            id: '1.3.1',
+            level: 'A',
+            title: 'Info and Relationships',
+            status: 'compliant',
+            description:
+                'Information, structure, and relationships conveyed through presentation can be programmatically determined.',
+            implementation:
+                'Uses semantic HTML: heading uses as="h3", description uses as="p". Alert container uses role="alert" for error/warning variants and role="status" for others. Uses aria-labelledby to link heading and aria-describedby to link description. Structure is programmatically determinable.',
+            testResults:
+                'Verified: Proper semantic structure with h3 and p elements. ARIA relationships properly established via aria-labelledby and aria-describedby. Confirmed in Alert.tsx.',
+        },
+        {
+            id: '1.3.2',
+            level: 'A',
+            title: 'Meaningful Sequence',
+            status: 'compliant',
+            description:
+                'When the sequence in which content is presented affects its meaning, a correct reading sequence can be programmatically determined.',
+            implementation:
+                'Alert content follows logical order: heading → description → actions. DOM order matches visual order. Content is presented in meaningful sequence.',
+            testResults: 'Verified: Logical sequence maintained.',
+        },
+        {
+            id: '1.3.3',
+            level: 'A',
+            title: 'Sensory Characteristics',
+            status: 'compliant',
+            description:
+                'Instructions provided for understanding and operating content do not rely solely on sensory characteristics.',
+            implementation:
+                'Alert does not rely solely on visual presentation. Text labels provide context. ARIA labels provide additional context for screen readers. Variant information is conveyed through text and ARIA roles.',
+            testResults: 'Verified: Not dependent on sensory characteristics.',
+        },
+        {
+            id: '1.4.3',
+            level: 'AA',
+            title: 'Contrast (Minimum)',
+            status: 'compliant',
+            description:
+                'Text and images of text have a contrast ratio of at least 4.5:1 for normal text, 3:1 for large text.',
+            implementation:
+                'Alert text uses theme tokens for colors. All text colors are designed to meet WCAG AA contrast requirements on their respective backgrounds. Colors vary by variant (primary, warning, success, error, etc.).',
+            testResults:
+                'COMPLIANT: Text colors meet WCAG AA contrast requirements. Verified via axe-core color-contrast rule. All variants tested and pass.',
+        },
+        {
+            id: '1.4.4',
+            level: 'AA',
+            title: 'Resize Text',
+            status: 'compliant',
+            description:
+                'Text can be resized without assistive technology up to 200 percent without loss of content or functionality.',
+            implementation:
+                'Alert text uses relative units (rem/em via font tokens). Layout uses flexbox allowing text scaling up to 200% without loss of functionality.',
+            testResults: 'Verified: Text scales properly up to 200%.',
+        },
+        {
+            id: '1.4.11',
+            level: 'AA',
+            title: 'Non-text Contrast',
+            status: 'compliant',
+            description:
+                'The visual presentation of user interface components and graphical objects has a contrast ratio of at least 3:1.',
+            implementation:
+                'Separators, borders, and focus indicators use colors that meet 3:1 contrast requirement. Focus indicators use variant-specific colors with sufficient contrast.',
+            testResults: 'Verified: Non-text elements meet 3:1 contrast ratio.',
+        },
+        {
+            id: '1.4.6',
+            level: 'AAA',
+            title: 'Contrast (Enhanced)',
+            status: 'unsure',
+            description:
+                'Text and images of text have a contrast ratio of at least 7:1 for normal text, 4.5:1 for large text.',
+            implementation:
+                'Alert text uses theme tokens for colors. Colors vary by variant and style (subtle, noFill).',
+            testResults:
+                'UNSURE: Requires manual contrast ratio calculation for each variant and style combination. VERIFICATION REQUIRED using contrast checker tool.',
+            notes: 'Contrast ratios must be verified using tools like WebAIM Contrast Checker for all variant/style combinations.',
+        },
+        {
+            id: '2.1.1',
+            level: 'A',
+            title: 'Keyboard',
+            status: 'compliant',
+            description:
+                'All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes.',
+            implementation:
+                'All alert buttons (primary action, secondary action, close) are keyboard accessible. Tab navigation works correctly. Enter and Space keys activate buttons. All interactive elements are focusable.',
+            testResults:
+                'Verified: All interactive elements keyboard accessible. Tab order is logical. Keyboard activation works correctly (Enter and Space keys).',
+        },
+        {
+            id: '2.1.2',
+            level: 'A',
+            title: 'No Keyboard Trap',
+            status: 'compliant',
+            description:
+                'If keyboard focus can be moved to a component of the page using a keyboard interface, then focus can be moved away from that component using only a keyboard interface.',
+            implementation:
+                'Alert component does not trap keyboard focus. Users can tab through all buttons and continue to next page element. No focus traps implemented.',
+            testResults: 'Verified: No keyboard traps present.',
+        },
+        {
+            id: '2.1.3',
+            level: 'AAA',
+            title: 'Keyboard (No Exception)',
+            status: 'compliant',
+            description:
+                'All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes.',
+            implementation:
+                'All alert functionality is keyboard accessible without exceptions. All buttons, actions, and close functionality work via keyboard.',
+            testResults:
+                'Verified: Full keyboard accessibility without exceptions.',
+        },
+        {
+            id: '2.4.1',
+            level: 'A',
+            title: 'Bypass Blocks',
+            status: 'not-applicable',
+            description:
+                'A mechanism is available to bypass blocks of content that are repeated on multiple Web pages.',
+            implementation:
+                'Alert component provides status information but does not create bypass blocks. Component is part of page content, not a repeated block.',
+            testResults:
+                'Not applicable: Component does not create bypass blocks.',
+        },
+        {
+            id: '2.4.2',
+            level: 'A',
+            title: 'Page Titled',
+            status: 'not-applicable',
+            description:
+                'Web pages have titles that describe topic or purpose.',
+            implementation:
+                'Alert component does not control page titles. This is handled at the application/page level.',
+            testResults:
+                'Not applicable: Component does not control page titles.',
+        },
+        {
+            id: '2.4.3',
+            level: 'A',
+            title: 'Focus Order',
+            status: 'compliant',
+            description:
+                'If a Web page can be navigated sequentially and the navigation sequences affect meaning or operation, focusable components receive focus in an order that preserves meaning and operability.',
+            implementation:
+                'Alert buttons follow logical order: primary action → secondary action → close button. Tab order matches visual order and user expectations.',
+            testResults:
+                'Verified: Focus order matches logical sequence (primary → secondary → close).',
+        },
+        {
+            id: '2.4.4',
+            level: 'A',
+            title: 'Link Purpose (In Context)',
+            status: 'not-applicable',
+            description:
+                'The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context.',
+            implementation:
+                'Alert component does not contain links. All interactive elements are buttons with clear labels.',
+            testResults: 'Not applicable: Component does not contain links.',
+        },
+        {
+            id: '2.4.5',
+            level: 'AA',
+            title: 'Multiple Ways',
+            status: 'not-applicable',
+            description:
+                'More than one way is available to locate a Web page within a set of Web pages.',
+            implementation:
+                'Alert component provides status information. Multiple ways to locate pages is an application-level concern.',
+            testResults:
+                'Not applicable: Component provides status information, multiple ways is application-level.',
+        },
+        {
+            id: '2.4.6',
+            level: 'AA',
+            title: 'Headings and Labels',
+            status: 'compliant',
+            description: 'Headings and labels describe topic or purpose.',
+            implementation:
+                'Alert has descriptive heading (required prop). Each button has descriptive label (primaryAction.label, secondaryAction.label). Close button has aria-label="Close".',
+            testResults:
+                'Verified: All labels are descriptive and clear. Heading provides context, buttons have clear labels.',
+        },
+        {
+            id: '2.4.7',
+            level: 'AA',
+            title: 'Focus Visible',
+            status: 'compliant',
+            description:
+                'Any keyboard operable user interface has a mode of operation where the keyboard focus indicator is visible.',
+            implementation:
+                'Alert buttons have visible focus indicators. Close button uses _focusVisible with outline using variant-specific color. Focus styles are clearly visible.',
+            testResults:
+                'Verified: Focus indicators are clearly visible on all interactive elements. Close button has custom focus style.',
+        },
+        {
+            id: '2.5.1',
+            level: 'A',
+            title: 'Pointer Gestures',
+            status: 'compliant',
+            description:
+                'All functionality that uses multipoint or path-based gestures for operation can be operated with a single pointer without a path-based gesture.',
+            implementation:
+                'Alert uses single click/tap interactions. No multipoint or path-based gestures required.',
+            testResults: 'Verified: Single pointer operation only.',
+        },
+        {
+            id: '2.5.2',
+            level: 'A',
+            title: 'Pointer Cancellation',
+            status: 'compliant',
+            description:
+                'For functionality that can be operated using a single pointer, at least one of the following is true: (a) No Down-Event, (b) Abort or Undo, (c) Up Reversal, (d) Essential.',
+            implementation:
+                'Alert buttons activate on click/tap (up event), not on mouse down. Standard button behavior prevents accidental activation.',
+            testResults:
+                'Verified: Activation occurs on up event, not down event.',
+        },
+        {
+            id: '2.5.3',
+            level: 'A',
+            title: 'Label in Name',
+            status: 'compliant',
+            description:
+                'For user interface components with labels that include text or images of text, the name contains the text that is presented visually.',
+            implementation:
+                'Alert buttons use visible text labels (primaryAction.label, secondaryAction.label). Close button has aria-label="Close" which matches the visual purpose. Labels match visible text.',
+            testResults:
+                'Verified: Accessible names include visible text or match visual purpose.',
+        },
+        {
+            id: '2.5.4',
+            level: 'A',
+            title: 'Motion Actuation',
+            status: 'compliant',
+            description:
+                'Functionality that can be operated by device motion or user motion can also be operated by user interface components.',
+            implementation:
+                'Alert component does not use device motion. All functionality available via standard UI controls.',
+            testResults: 'Verified: No motion actuation used.',
+        },
+        {
+            id: '2.5.5',
+            level: 'AAA',
+            title: 'Target Size (Enhanced)',
+            status: 'non-compliant',
+            description:
+                'Targets have a size of at least 44 by 44 CSS pixels, except where a specific target presentation is required or cannot be changed.',
+            implementation:
+                'Alert buttons (primary action, secondary action, close) do not currently have minimum 44x44px touch targets. This is planned for future implementation.',
+            testResults:
+                'NON-COMPLIANT: Touch target sizes not yet implemented. Tests are skipped pending implementation. Requires minWidth and minHeight of 44px on all interactive buttons.',
+            notes: 'Touch target size implementation is planned for future release. Currently tests are skipped.',
+        },
+        {
+            id: '3.2.1',
+            level: 'A',
+            title: 'On Focus',
+            status: 'compliant',
+            description:
+                'When any user interface component receives focus, it does not initiate a change of context.',
+            implementation:
+                'Alert buttons do not change context on focus. Actions occur only on click/activation, not on focus.',
+            testResults: 'Verified: No context change on focus.',
+        },
+        {
+            id: '3.2.2',
+            level: 'A',
+            title: 'On Input',
+            status: 'compliant',
+            description:
+                'Changing the setting of any user interface component does not automatically cause a change of context unless the user has been advised of the behavior before using the component.',
+            implementation:
+                'Alert buttons change context only on explicit user action (click). No automatic context changes.',
+            testResults: 'Verified: Context changes only on explicit action.',
+        },
+        {
+            id: '3.2.3',
+            level: 'AA',
+            title: 'Consistent Navigation',
+            status: 'not-applicable',
+            description:
+                'Navigational mechanisms that are repeated on multiple Web pages within a set of Web pages occur in the same relative order each time they appear.',
+            implementation:
+                'Alert component provides status information. Consistent navigation across pages is an application-level concern.',
+            testResults:
+                'Not applicable: Component provides status information, application-level concern.',
+        },
+        {
+            id: '3.2.4',
+            level: 'AA',
+            title: 'Consistent Identification',
+            status: 'compliant',
+            description:
+                'Components that have the same functionality within a set of Web pages are identified consistently.',
+            implementation:
+                'Alert component maintains consistent structure and identification across all instances. ARIA roles and labels are consistent.',
+            testResults: 'Verified: Consistent identification maintained.',
+        },
+        {
+            id: '3.2.5',
+            level: 'AAA',
+            title: 'Change on Request',
+            status: 'compliant',
+            description:
+                'Changes of context are initiated only by user request or a mechanism is available to turn off such changes.',
+            implementation:
+                'Alert buttons change context only on explicit user click/activation. No automatic changes.',
+            testResults: 'Verified: Changes only on user request.',
+        },
+        {
+            id: '3.3.1',
+            level: 'A',
+            title: 'Error Identification',
+            status: 'compliant',
+            description:
+                'If an input error is automatically detected, the error is identified and the error is described to the user in text.',
+            implementation:
+                'Alert component can display error messages. Error alerts use role="alert" for immediate attention. Error information is provided in heading and description text.',
+            testResults:
+                'Verified: Error alerts properly identified with role="alert" and descriptive text.',
+        },
+        {
+            id: '3.3.2',
+            level: 'A',
+            title: 'Labels or Instructions',
+            status: 'compliant',
+            description:
+                'Labels or instructions are provided when content requires user input.',
+            implementation:
+                'Alert provides clear labels via heading and description. Buttons have clear labels. No user input required, but instructions are clear.',
+            testResults: 'Verified: Clear labels and instructions provided.',
+        },
+        {
+            id: '4.1.1',
+            level: 'A',
+            title: 'Parsing',
+            status: 'compliant',
+            description:
+                'In content implemented using markup languages, elements have complete start and end tags, elements are nested according to their specifications, elements do not contain duplicate attributes, and any IDs are unique.',
+            implementation:
+                'Alert component uses valid HTML5 markup. All elements properly nested. No duplicate attributes or IDs. Uses useId() for unique ID generation.',
+            testResults:
+                'Verified: Valid HTML5 markup, proper nesting, unique IDs.',
+        },
+        {
+            id: '4.1.2',
+            level: 'A',
+            title: 'Name, Role, Value',
+            status: 'compliant',
+            description:
+                'For all user interface components, the name and role can be programmatically determined; states, properties, and values can be set by the user; and notification of changes to these items is available to user agents, including assistive technologies.',
+            implementation:
+                'Alert container has proper role (alert/status), name (via aria-labelledby pointing to heading), and description (via aria-describedby pointing to description). Buttons have proper role (button), name (visible label or aria-label), and value (onClick handler). Close button has role (button), name (aria-label="Close"), and value (onClick handler).',
+            testResults:
+                'Verified: All components have proper name, role, and value. States properly communicated via ARIA roles.',
+        },
+        {
+            id: '4.1.3',
+            level: 'AA',
+            title: 'Status Messages',
+            status: 'compliant',
+            description:
+                'In content implemented using markup languages, status messages can be programmatically determined through role or properties such that they can be presented to the user by assistive technologies without receiving focus.',
+            implementation:
+                'Alert uses role="alert" for error/warning variants (assertive announcements) and role="status" for other variants (polite announcements). Status messages are programmatically determinable and announced by screen readers without requiring focus.',
+            testResults:
+                'Verified: Status messages properly announced via role="alert" and role="status". Screen readers announce alerts without requiring focus.',
+        },
+    ],
+    strengths: [
+        'Proper use of ARIA roles: role="alert" for error/warning (assertive), role="status" for others (polite)',
+        'Semantic HTML structure with h3 for heading and p for description',
+        'Comprehensive ARIA relationships via aria-labelledby and aria-describedby',
+        'All interactive elements are keyboard accessible',
+        'Visible focus indicators on all buttons',
+        'Decorative content properly hidden from screen readers (icons, separators)',
+        'Close button has descriptive aria-label',
+        'Unique ID generation using useId() for ARIA relationships',
+        'Error and warning alerts properly announced immediately via role="alert"',
+        'Non-error alerts announced politely via role="status"',
+        'Flexible action placement (right or bottom)',
+        'Support for primary and secondary actions with clear labels',
+    ],
+    recommendations: [
+        'Implement 44x44px minimum touch targets for all buttons (primary action, secondary action, close) to meet WCAG 2.5.5 AAA requirement',
+        'Verify color contrast ratios meet AAA standard (7:1) for all variant/style combinations using contrast checker tool',
+        'Consider adding aria-live="assertive" or aria-live="polite" explicitly if needed for dynamic content updates (though role="alert" and role="status" provide this implicitly)',
+        'Consider adding aria-atomic="true" if alert content updates dynamically to ensure complete announcements',
+        'Monitor for any future WCAG 2.2 updates that may affect alert components',
+        'Consider adding keyboard shortcuts for common actions if appropriate for the use case',
+    ],
+    wcagVersions: {
+        '2.0': [
+            '1.1.1',
+            '1.3.1',
+            '1.3.2',
+            '1.3.3',
+            '1.4.3',
+            '1.4.4',
+            '2.1.1',
+            '2.1.2',
+            '2.4.1',
+            '2.4.2',
+            '2.4.3',
+            '2.4.4',
+            '2.4.5',
+            '2.4.6',
+            '2.4.7',
+            '3.2.1',
+            '3.2.2',
+            '3.2.3',
+            '3.2.4',
+            '3.3.1',
+            '3.3.2',
+            '4.1.1',
+            '4.1.2',
+            '4.1.3',
+        ],
+        '2.1': ['1.4.11', '2.5.1', '2.5.2', '2.5.3', '2.5.4'],
+        '2.2': [],
+    },
+    testMethodology: {
+        automated: [
+            'axe-core accessibility testing',
+            'HTML validation',
+            'ARIA attribute validation',
+            'Semantic HTML structure validation',
+            'Color contrast validation (AA level)',
+        ],
+        manual: [
+            'Keyboard navigation testing',
+            'Screen reader testing (NVDA, JAWS, VoiceOver)',
+            'Color contrast verification (AAA level)',
+            'Touch target size measurement (pending implementation)',
+            'Focus indicator visibility',
+            'Status message announcements',
+        ],
+        verificationTools: [
+            'axe DevTools',
+            'WebAIM Contrast Checker',
+            'WAVE (Web Accessibility Evaluation Tool)',
+            'Lighthouse Accessibility Audit',
+            'NVDA Screen Reader',
+            'JAWS Screen Reader',
+            'VoiceOver (macOS/iOS)',
+        ],
+        wcagLevels: {
+            A: [
+                '1.1.1',
+                '1.3.1',
+                '1.3.2',
+                '1.3.3',
+                '2.1.1',
+                '2.1.2',
+                '2.4.1',
+                '2.4.3',
+                '2.4.4',
+                '3.2.1',
+                '3.2.2',
+                '3.3.1',
+                '3.3.2',
+                '4.1.1',
+                '4.1.2',
+            ],
+            AA: [
+                '1.4.3',
+                '1.4.4',
+                '1.4.11',
+                '2.4.6',
+                '2.4.7',
+                '3.2.3',
+                '3.2.4',
+                '4.1.3',
+            ],
+            AAA: ['1.4.6', '2.1.3', '2.5.5', '3.2.5'],
+        },
+    },
+}

package/lib/components/Alert/accessibility/index.ts

@@ -0,0 +1,2 @@
+export { default as AlertAccessibility } from './AlertAccessibility'
+export { alertAccessibilityReport } from './AlertAccessibilityReport'