+
+```
+
+## Update Process for Protected Components
+
+If you absolutely need to update protected components, follow these steps:
+
+1. Create an issue describing why the update is necessary
+2. Get approval from the tech lead
+3. Make the changes following the approved process (e.g., using the shadcn CLI)
+4. Document the changes thoroughly
+5. Add tests to verify functionality hasn't been broken
diff --git a/packages/ui-kit/docs/accessibility-testing.md b/packages/ui-kit/docs/accessibility-testing.md
new file mode 100644
index 0000000..9c04f25
--- /dev/null
+++ b/packages/ui-kit/docs/accessibility-testing.md
@@ -0,0 +1,132 @@
+# Accessibility Testing with axe-core
+
+This document provides guidance on interpreting and fixing accessibility issues found by axe-core in our UI components.
+
+## Accessibility Testing in CI
+
+Our CI pipeline automatically runs accessibility tests on all Storybook stories using axe-core. If any accessibility violations are found, the CI build will fail. This helps us catch accessibility issues early in the development process.
+
+## How To Run Accessibility Tests Locally
+
+To run accessibility tests locally:
+
+```bash
+# Navigate to the ui-kit package
+cd packages/ui-kit
+
+# Build Storybook
+pnpm build-storybook
+
+# Run accessibility tests on all stories
+pnpm test-storybook
+```
+
+## Understanding Accessibility Violations
+
+When axe-core finds an accessibility violation, it will provide the following information:
+
+- **Impact**: The severity of the violation (critical, serious, moderate, minor)
+- **Rule ID**: A unique identifier for the rule that was violated
+- **Description**: A description of the violation
+- **Help URL**: A link to more information about the rule
+- **Elements**: The HTML elements that violated the rule
+
+## Common Issues and How to Fix Them
+
+### Missing Alternative Text (image-alt)
+
+**Issue**: Images must have alternative text for screen readers.
+
+**Fix**: Add an `alt` attribute to all `
+
+// Good
+
+
+// For decorative images
+
+```
+
+### Insufficient Color Contrast (color-contrast)
+
+**Issue**: Text must have sufficient contrast against its background.
+
+**Fix**:
+
+- Adjust text or background colors to meet WCAG 2.1 AA contrast requirements
+- Use the DaisyUI/Tailwind color system which has been designed with contrast in mind
+- For text elements, ensure a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text
+
+### Missing Form Labels (label)
+
+**Issue**: Form inputs must have associated labels.
+
+**Fix**:
+
+```jsx
+// Bad
+
+
+// Good
+
+
+
+// Or using our FormField components which handle this automatically
+Page Title
+Section Title
+Subsection Title
+ +``` + +### ARIA Attributes (aria-\*) + +**Issue**: Improper use of ARIA attributes. + +**Fix**: Only use ARIA attributes when necessary and ensure they are used correctly. Our component library handles many ARIA attributes for you. + +## Resources + +- [axe-core Rules](https://github.com/dequelabs/axe-core/blob/master/doc/rule-descriptions.md) +- [WCAG 2.1 Guidelines](https://www.w3.org/TR/WCAG21/) +- [Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/) + +## Handling False Positives + +In rare cases, you may encounter false positives. If you believe a violation is a false positive, you can: + +1. Document why the violation is a false positive +2. Disable specific rules for a component in the story parameters: + +```jsx +export const MyStory = { + parameters: { + a11y: { + config: { + rules: [ + { + id: "rule-id-to-disable", + enabled: false, + }, + ], + }, + }, + }, +}; +``` + +Always provide a comment explaining why the rule is disabled. diff --git a/packages/ui-kit/package.json b/packages/ui-kit/package.json index 6ac0c4b..82841ed 100644 --- a/packages/ui-kit/package.json +++ b/packages/ui-kit/package.json @@ -25,6 +25,10 @@ "test:coverage": "vitest run --coverage", "storybook": "storybook dev -p 6006", "build-storybook": "storybook build", + "test-storybook": "test-storybook", + "test-storybook:ci": "node scripts/run-storybook-test.js", + "test-component": "node scripts/test-single-component.js", + "test:component": "scripts/test-component.sh", "cy:open": "cypress open", "cy:run": "cypress run", "theme-screenshots": "cypress run --spec \"cypress/e2e/theme.cy.ts\"", @@ -36,6 +40,7 @@ "dependencies": { "@hookform/resolvers": "^5.0.1", "@radix-ui/react-checkbox": "^1.3.1", + "@radix-ui/react-label": "^2.1.7", "@radix-ui/react-radio-group": "^1.3.6", "@radix-ui/react-select": "^2.2.4", "@radix-ui/react-slot": "^1.2.2", @@ -68,6 +73,7 @@ "@storybook/react": "^8.6.14", "@storybook/react-vite": "^8.6.14", "@storybook/test": "^8.6.14", + "@storybook/test-runner": "^0.22.0", "@storybook/theming": "^8.6.14", "@storybook/types": "^8.6.14", "@testing-library/dom": "^10.0.0", @@ -79,6 +85,8 @@ "@types/testing-library__react": "^10.2.0", "@vitejs/plugin-react": "^4.4.1", "autoprefixer": "^10.4.21", + "axe-playwright": "^2.1.0", + "concurrently": "^9.1.2", "cypress": "^14.3.3", "cypress-visual-regression": "^5.3.0", "daisyui": "^5.0.35", @@ -93,6 +101,7 @@ "tailwindcss": "^3.4.17", "typescript-eslint": "^8.32.1", "vite": "^5.4.19", - "vitest": "^1.6.1" + "vitest": "^1.6.1", + "wait-on": "^8.0.3" } } diff --git a/packages/ui-kit/scripts/run-storybook-test.js b/packages/ui-kit/scripts/run-storybook-test.js new file mode 100755 index 0000000..46134a4 --- /dev/null +++ b/packages/ui-kit/scripts/run-storybook-test.js @@ -0,0 +1,303 @@ +#!/usr/bin/env node +/* eslint-disable no-console, no-undef */ + +import { spawn, exec } from 'child_process'; +import { promisify } from 'util'; +import { createServer } from 'net'; + +const execAsync = promisify(exec); + +// Script automatically detects the port Storybook is running on + +// Configuration +const STORYBOOK_TIMEOUT_MS = 180000; // 3 minutes +const TEST_TIMEOUT_MS = 120000; // 2 minutes +const READY_WAIT_MS = 15000; // Additional wait time after port detection + +// Find an available port +async function findAvailablePort(startPort = 60000, endPort = 65000) { + let port = Math.floor(Math.random() * (endPort - startPort)) + startPort; + + return new Promise((resolve) => { + const server = createServer(); + + server.once('error', () => { + // Port is in use, try another one + resolve(findAvailablePort(startPort, endPort)); + }); + + server.once('listening', () => { + // Found an available port + const foundPort = server.address().port; + server.close(() => { + resolve(foundPort); + }); + }); + + server.listen(port); + }); +} + +/** + * Start Storybook and detect the port it's running on + */ +async function startStorybook() { + console.log('Starting Storybook...'); + + // Find an available port + const availablePort = await findAvailablePort(); + console.log(`Using available port: ${availablePort}`); + + // Start Storybook with --ci flag and specify port range + const storybookProcess = spawn('storybook', ['dev', '--ci', '--port', availablePort.toString()], { + shell: true, + stdio: ['pipe', 'pipe', 'pipe'], + env: { ...process.env, FORCE_COLOR: 'true' } + }); + + let port = null; + let portDetected = false; + let logBuffer = ''; + + // Set up timeout for port detection + const timeoutPromise = new Promise((_, reject) => { + setTimeout(() => { + // Before failing, try to detect the port from lsof + tryDetectPortFromLsof(reject); + }, STORYBOOK_TIMEOUT_MS); + }); + + // Try to detect the port from lsof as a fallback + async function tryDetectPortFromLsof(rejectFn) { + try { + console.log('Attempting to detect Storybook port from system...'); + // Check for listening Node.js processes + const { stdout } = await execAsync('lsof -i -P -n | grep LISTEN | grep node'); + console.log('Found Node.js listening ports:'); + console.log(stdout); + + // Log the whole buffer for debugging + console.log('---- Storybook Output Log ----'); + console.log(logBuffer); + console.log('---- End Storybook Output Log ----'); + + rejectFn(new Error(`Timeout waiting for Storybook to start (${STORYBOOK_TIMEOUT_MS / 1000} seconds)`)); + } catch (err) { + rejectFn(new Error(`Timeout waiting for Storybook to start. Failed to detect from lsof: ${err.message}`)); + } + } + + // Create a promise that resolves when we detect the port + const portDetectionPromise = new Promise((resolve) => { + // Function to check output against all known Storybook port patterns + const checkForPort = (output) => { + // Add to cumulative log buffer for debugging if detection fails + logBuffer += output; + + // Various patterns Storybook might use to report its port + const patterns = [ + // Normal patterns + /Local:\s*http:\/\/localhost:(\d+)/, + /http:\/\/127\.0\.0\.1:(\d+)/, + /http:\/\/0\.0\.0\.0:(\d+)/, + // CLI output format + /╭.*╮.*Local:\s*http:\/\/localhost:(\d+)/s, + /╭.*╮.*On your network:\s*http:\/\/[^:]+:(\d+)/s, + // Alternative pattern seen in some CI environments + /Storybook.*started.*localhost:(\d+)/i, + // Direct port mentions + /port\s+(\d+)/i, + /PORT=(\d+)/i + ]; + + for (const pattern of patterns) { + const match = output.match(pattern); + if (match && match[1]) { + const detectedPort = parseInt(match[1], 10); + if (detectedPort > 0) { + console.log(`Detected Storybook running on port: ${detectedPort} (matched pattern: ${pattern})`); + port = detectedPort; + portDetected = true; + resolve(port); + return true; + } + } + } + + // If the requested port is available and no port detection yet + if (output.includes(`${availablePort}`) && !portDetected) { + console.log(`Detected Storybook likely running on requested port: ${availablePort}`); + port = availablePort; + portDetected = true; + resolve(port); + return true; + } + + return false; + }; + + storybookProcess.stdout.on('data', (data) => { + const output = data.toString(); + console.log(`Storybook: ${output}`); + + if (!portDetected) { + checkForPort(output); + } + }); + + storybookProcess.stderr.on('data', (data) => { + const output = data.toString(); + console.error(`Storybook stderr: ${output}`); + + // Also check stderr for port information + if (!portDetected) { + checkForPort(output); + } + }); + + storybookProcess.on('error', (error) => { + console.error(`Storybook process error: ${error.message}`); + }); + + storybookProcess.on('exit', (code) => { + if (code !== null && code !== 0) { + console.error(`Storybook process exited with code ${code}`); + } + }); + + // As a fallback, assume the port we provided worked if Storybook doesn't exit + setTimeout(() => { + if (!portDetected) { + console.log(`No port detected after 30s. Assuming port ${availablePort} is being used...`); + port = availablePort; + portDetected = true; + resolve(port); + } + }, 30000); + }); + + // Wait for port detection or timeout + try { + port = await Promise.race([portDetectionPromise, timeoutPromise]); + } catch (error) { + console.error('Error detecting Storybook port:', error); + + // Log the current system state + console.log('Checking system state...'); + try { + const { stdout: psOutput } = await execAsync('ps aux | grep storybook'); + console.log('Running storybook processes:'); + console.log(psOutput); + + const { stdout: netstatOutput } = await execAsync('netstat -tulpn 2>/dev/null | grep node'); + console.log('Node ports in use:'); + console.log(netstatOutput); + } catch { + console.error('Failed to check system state'); + } + + // Kill any orphaned storybook processes + try { + await execAsync('pkill -f "storybook dev"'); + } catch { + // Ignore errors if no processes found + } + + process.exit(1); + } + + // Give extra time for Storybook to fully initialize + console.log(`Waiting additional ${READY_WAIT_MS / 1000} seconds for Storybook to fully initialize...`); + await new Promise(resolve => setTimeout(resolve, READY_WAIT_MS)); + + return { storybookProcess, port }; +} + +/** + * Run the test-storybook command with the detected port + */ +async function runTests(port) { + console.log(`Running tests on Storybook at port ${port}...`); + + try { + // Wait for Storybook server to be ready + await execAsync(`wait-on http://localhost:${port} -t ${TEST_TIMEOUT_MS}`); + console.log('Storybook is ready. Running accessibility tests...'); + + // List available story IDs for debugging + try { + console.log('Fetching available stories...'); + const { stdout } = await execAsync(`curl -s http://localhost:${port}/index.json`); + const storyData = JSON.parse(stdout); + console.log(`Found ${Object.keys(storyData.entries).length} stories`); + Object.keys(storyData.entries).slice(0, 10).forEach(id => { + console.log(`- Story ID: ${id}`); + }); + } catch (err) { + console.warn('Failed to fetch story list:', err.message); + } + + // Run the tests against the detected port with additional flags + const testProcess = spawn('test-storybook', [ + `--url=http://localhost:${port}`, + '--maxWorkers=2', + '--ci' + ], { + shell: true, + stdio: 'inherit' + }); + + return new Promise((resolve, reject) => { + testProcess.on('close', (code) => { + if (code !== 0) { + reject(new Error(`test-storybook exited with code ${code}`)); + } else { + resolve(); + } + }); + }); + } catch (error) { + console.error('Error running tests:', error); + throw error; + } +} + +/** + * Main function to orchestrate the process + */ +async function main() { + let storybookProcess = null; + + try { + // Start Storybook and detect port + const storybook = await startStorybook(); + storybookProcess = storybook.storybookProcess; + + // Run tests against the detected port + await runTests(storybook.port); + + console.log('All tests completed successfully'); + process.exit(0); + } catch (error) { + console.error('Error in test process:', error); + process.exit(1); + } finally { + // Ensure Storybook is terminated + if (storybookProcess) { + console.log('Terminating Storybook process...'); + storybookProcess.kill('SIGTERM'); + + // Force kill if needed + setTimeout(() => { + try { + storybookProcess.kill('SIGKILL'); + } catch { + // Ignore errors if process already gone + } + }, 5000); + } + } +} + +// Run the main function +main(); \ No newline at end of file diff --git a/packages/ui-kit/scripts/test-a11y-violation.js b/packages/ui-kit/scripts/test-a11y-violation.js new file mode 100644 index 0000000..59bed6f --- /dev/null +++ b/packages/ui-kit/scripts/test-a11y-violation.js @@ -0,0 +1,70 @@ +// Simple script to test that axe-core detects accessibility violations +// Run with: node scripts/test-a11y-violation.js +/* eslint-disable no-console, no-undef */ + +import { chromium } from '@playwright/test'; +import { injectAxe, checkA11y } from 'axe-playwright'; + +async function runA11yTest() { + console.log('Starting accessibility test...'); + + // Launch a browser + const browser = await chromium.launch(); + const page = await browser.newPage(); + + // Create a simple HTML page with an accessibility violation + await page.setContent(` + + +Accessibility Test
+ +
+
+
+ `);
+
+ // Inject axe
+ await injectAxe(page);
+
+ // Try/catch to show the violations
+ try {
+ console.log('Running axe-core tests...');
+ // This should fail due to accessibility violations
+ await checkA11y(page, 'body', {
+ detailedReport: true,
+ detailedReportOptions: {
+ html: true,
+ },
+ });
+ console.log('✅ No violations found (this should not happen)');
+ } catch (error) {
+ console.log('❌ Accessibility violations detected (expected)');
+ console.log('\nViolation details:');
+
+ // Extract and display violation information
+ if (error.message.includes('Found')) {
+ const violations = error.message.split('Found ')[1].split(' accessibility violations')[0];
+ console.log(`Found ${violations} accessibility violations`);
+
+ // Extract specific violations if possible
+ const violationMatches = error.message.match(/Impact: (critical|serious|moderate|minor).*?Rule: ([a-z-]+)/gs);
+ if (violationMatches) {
+ violationMatches.forEach(match => {
+ console.log(`\n${match.trim()}`);
+ });
+ }
+ } else {
+ console.log(error.message);
+ }
+ }
+
+ // Close the browser
+ await browser.close();
+}
+
+runA11yTest().catch(error => {
+ console.error('Test failed unexpectedly:', error);
+ process.exit(1);
+});
\ No newline at end of file
diff --git a/packages/ui-kit/scripts/test-component.sh b/packages/ui-kit/scripts/test-component.sh
new file mode 100755
index 0000000..dd17bc7
--- /dev/null
+++ b/packages/ui-kit/scripts/test-component.sh
@@ -0,0 +1,48 @@
+#!/bin/bash
+# A simple script to test a single component using Storybook and test-runner
+
+# Display usage if no pattern is provided
+if [ -z "$1" ]; then
+ echo "Usage: $0
+
+ Delete Item
+
+
+ ),
+};
\ No newline at end of file
diff --git a/packages/ui-kit/src/components/examples/A11yButton.tsx b/packages/ui-kit/src/components/examples/A11yButton.tsx
new file mode 100644
index 0000000..93929c9
--- /dev/null
+++ b/packages/ui-kit/src/components/examples/A11yButton.tsx
@@ -0,0 +1,89 @@
+import React from 'react';
+import { Button, ButtonProps } from '../ui/button';
+import { cn } from '@/lib/utils';
+
+type A11yButtonProps = ButtonProps & {
+ /**
+ * Aria label for better accessibility - use this when button only contains icons
+ * or when the button text is not descriptive enough
+ */
+ ariaLabel?: string;
+
+ /**
+ * ID of an element that describes this button for accessibility
+ */
+ ariaDescribedBy?: string;
+
+ /**
+ * ID of an element that labels this button for accessibility
+ */
+ ariaLabelledBy?: string;
+
+ /**
+ * Button is expanded (for use with dropdowns, modals, etc.)
+ */
+ ariaExpanded?: boolean;
+
+ /**
+ * Controls element ID (for use with dropdowns, modals, etc.)
+ */
+ ariaControls?: string;
+
+ /**
+ * Optional icon to display before the button text
+ */
+ startIcon?: React.ReactNode;
+
+ /**
+ * Optional icon to display after the button text
+ */
+ endIcon?: React.ReactNode;
+
+ /**
+ * Whether the button is being used as a toggle
+ */
+ isToggle?: boolean;
+
+ /**
+ * Whether the button is in "pressed" state (for toggles)
+ */
+ isPressed?: boolean;
+};
+
+/**
+ * A11yButton is a wrapper around the core Button component
+ * that adds additional accessibility features without modifying
+ * the core component.
+ */
+export function A11yButton({
+ children,
+ className,
+ ariaLabel,
+ ariaDescribedBy,
+ ariaLabelledBy,
+ ariaExpanded,
+ ariaControls,
+ startIcon,
+ endIcon,
+ isToggle,
+ isPressed,
+ ...props
+}: A11yButtonProps) {
+ return (
+
+ );
+}
\ No newline at end of file
diff --git a/packages/ui-kit/src/components/examples/AccessibleComponentsExample.tsx b/packages/ui-kit/src/components/examples/AccessibleComponentsExample.tsx
new file mode 100644
index 0000000..42942db
--- /dev/null
+++ b/packages/ui-kit/src/components/examples/AccessibleComponentsExample.tsx
@@ -0,0 +1,93 @@
+import { Checkbox } from '../ui/checkbox';
+import { Label } from '../ui/label';
+import { RadioGroup, RadioGroupItem } from '../ui/radio-group';
+import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '../ui/select';
+
+/**
+ * AccessibleComponentsExample demonstrates how to use shadcn components with proper
+ * accessibility attributes without modifying the base components.
+ *
+ * Key accessibility patterns:
+ * 1. Associate labels with form controls using htmlFor/id
+ * 2. Group related form elements
+ * 3. Provide descriptive text for controls
+ * 4. Use semantic HTML elements
+ */
+export function AccessibleComponentsExample() {
+ return (
+ + This action permanently removes the item and cannot be undone. +
+
+
+ );
+}
\ No newline at end of file
diff --git a/packages/ui-kit/src/components/form/A11yFormExamples.stories.tsx b/packages/ui-kit/src/components/form/A11yFormExamples.stories.tsx
new file mode 100644
index 0000000..4b10021
--- /dev/null
+++ b/packages/ui-kit/src/components/form/A11yFormExamples.stories.tsx
@@ -0,0 +1,37 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { A11yFormExamples } from './A11yFormExamples';
+
+const meta = {
+ title: 'Form/AccessibleExamples',
+ component: A11yFormExamples,
+ parameters: {
+ layout: 'centered',
+ // Run thorough accessibility tests on this component
+ a11y: {
+ config: {
+ rules: [
+ // Ensure these critical rules are enabled
+ { id: 'button-name', enabled: true },
+ { id: 'label', enabled: true },
+ { id: 'aria-valid-attr-value', enabled: true },
+ { id: 'color-contrast', enabled: true },
+ ],
+ },
+ },
+ },
+} satisfies MetaAccessible Component Examples
+ + {/* Checkbox with associated label */} +
+
+
+ {/* Radio group with proper labeling */}
+ Checkbox
+
+
+
+ The key to accessible checkboxes is using a proper id attribute and
+ associating it with a Label using htmlFor.
+
+
+
+
+
+ {/* Select with proper labeling */}
+ Radio Group
+Select your preferred contact method:
+
+
+
+
+
+
+
+ For radio groups, each radio item needs its own unique id and
+ associated Label.
+
+
+
+ Select
+
+
+
+
+
+ For select components, the SelectTrigger needs an id
+ that matches the htmlFor of the Label.
+
+
+ Accessibility Best Practices:
+-
+
- Always associate labels with form controls using proper IDs +
- Use semantic HTML elements when possible +
- Ensure keyboard navigation works for all interactive elements +
- Provide enough color contrast for text and interactive elements +
- Use proper heading hierarchy (h1, h2, h3, etc.) +
- Add descriptive text for complex form controls +
{description}
++ {description} +
)} {error && ( -{error}
++ {error} +
)}
{label && (
-