@a11ypros/a11y-ui-components 1.0.5 → 2.0.0

package/.storybook/custom.css

@@ -0,0 +1,85 @@
+/* Custom Storybook styles */
+
+/* Theme backgrounds for docs view */
+[data-theme="dark"] .docs-story,
+[data-theme="dark"] .sbdocs-preview {
+  background-color: #171717 !important;
+}
+
+[data-theme="light"] .docs-story,
+[data-theme="light"] .sbdocs-preview {
+  background-color: #ffffff !important;
+}
+
+/* Override Storybook's default bright blue link color */
+.sbdocs a,
+.sbdocs a:link,
+.docs-story a,
+.docs-story a:link {
+  color: #0e8168 !important;
+}
+
+.sbdocs a:hover,
+.docs-story a:hover {
+  color: #075985 !important;
+}
+
+.sbdocs a:visited,
+.docs-story a:visited {
+  color: #0369a1 !important;
+}
+
+/* Fix controls pane button hover states - ensure text is visible */
+.sb-controls button:hover,
+.sb-controls button:focus,
+[data-testid="control-buttons-container"] button:hover,
+[data-testid="control-buttons-container"] button:focus,
+button[aria-label*="Set"]:hover,
+button[aria-label*="Set"]:focus,
+button[aria-label*="Reset"]:hover,
+button[aria-label*="Reset"]:focus,
+[id*="storybook-panel"] button:hover,
+[id*="storybook-panel"] button:focus {
+  color: #171717 !important;
+  background-color: #f5f5f5 !important;
+}
+
+/* Ensure button text is visible in all states */
+.sb-controls button,
+[data-testid="control-buttons-container"] button,
+button[aria-label*="Set"],
+button[aria-label*="Reset"],
+[id*="storybook-panel"] button {
+  color: #171717 !important;
+}
+
+/* Override left sidebar navigation hover colors to match color scheme */
+.sidebar-container [role="menuitem"]:hover,
+.sidebar-container [role="menuitem"]:focus,
+.sidebar-container a:hover,
+.sidebar-container a:focus,
+[data-nodetype="story"]:hover,
+[data-nodetype="story"]:focus,
+[data-nodetype="component"]:hover,
+[data-nodetype="component"]:focus,
+[data-nodetype="group"]:hover,
+[data-nodetype="group"]:focus {
+  background-color: #f5f5f5 !important;
+  color: #0e8168 !important;
+}
+
+/* Override selected state to use primary color */
+.sidebar-container [role="menuitem"][aria-selected="true"],
+.sidebar-container [role="menuitem"][aria-current="true"],
+[data-nodetype="story"][aria-selected="true"],
+[data-nodetype="component"][aria-selected="true"] {
+  background-color: #f0f9ff !important;
+  color: #0e8168 !important;
+  border-left-color: #0e8168 !important;
+}
+
+.sb-bar button:hover {
+  color: #000000 !important;
+  background-color: #f5f5f5;;
+}
+

package/.storybook/main.ts

@@ -0,0 +1,51 @@
+import type { StorybookConfig } from '@storybook/react-vite'
+
+const config: StorybookConfig = {
+  stories: [
+    '../.storybook/welcome.mdx',
+    '../packages/design-system/src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
+  addons: [
+    '@storybook/addon-links',
+    '@storybook/addon-a11y',
+    '@storybook/addon-docs',
+  ],
+  framework: {
+    name: '@storybook/react-vite',
+    options: {
+      viteConfigPath: '.storybook/vite.config.ts',
+    },
+  },
+  viteFinal: async (config) => {
+    config.define = {
+      ...config.define,
+      'process.env': {},
+      'process': { env: {} },
+    }
+    return config
+  },
+  docs: {
+    autodocs: 'tag',
+  },
+  typescript: {
+    check: false,
+    reactDocgen: 'react-docgen-typescript',
+    reactDocgenTypescriptOptions: {
+      shouldExtractLiteralValuesFromEnum: true,
+      propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true),
+    },
+  },
+  core: {
+    disableTelemetry: true,
+  },
+  staticDirs: ['../public'],
+  managerHead: (head) => `
+    ${head}
+    <title>A11Y Pros Accessible Design System</title>
+    <meta name="description" content="Accessibility-first React UI component library - WCAG 2.1/2.2 compliant components" />
+  `,
+  // Base path is configured in vite.config.ts to use /storybook-static/
+  // This ensures assets use absolute paths that match where files are located
+}
+
+export default config
+

package/.storybook/manager-head.html

@@ -0,0 +1,2 @@
+<title>A11Y Pros Accessible Design System - Storybook</title>
+<meta name="description" content="Accessibility-first React UI component library - WCAG 2.1/2.2 compliant components" />

package/.storybook/manager.ts

@@ -0,0 +1,31 @@
+import { addons } from 'storybook/internal/manager-api'
+import { create } from 'storybook/internal/theming'
+import './custom.css'
+
+const theme = create({
+  base: 'light',
+  brandTitle: 'A11y Pros Design System',
+  brandUrl: '/storybook',
+  brandImage: '/storybook-static/logo.png', // Path to your logo file (served from staticDirs)
+  brandTarget: '_self',
+  
+  colorPrimary: '#0e8168',
+  colorSecondary: '#001d2f',
+  
+  // Toolbar colors
+  barTextColor: '#171717',
+  barSelectedColor: '#0e8168', // Selected nav item color (matches colorPrimary)
+  barHoverColor: '#f5f5f5', // Hover color for nav items in left sidebar
+  barBg: '#ffffff',
+ 
+})
+
+addons.setConfig({
+  theme,
+})
+
+// Explicitly set document title
+if (typeof window !== 'undefined') {
+  window.document.title = 'A11Y Pros Accessible Design System'
+}
+

package/.storybook/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "storybook-config",
+  "version": "1.0.0",
+  "private": true
+}
+

package/.storybook/preview.tsx

@@ -0,0 +1,74 @@
+import type { Preview } from '@storybook/react'
+import React, { useEffect } from 'react'
+import '../packages/design-system/src/styles/global.css'
+import './custom.css'
+
+const withTheme = (Story, context) => {
+  const theme = context.globals.theme || 'light'
+  
+  useEffect(() => {
+    document.documentElement.setAttribute('data-theme', theme)
+    // Also update Storybook's docs background
+    const docsStory = document.querySelector('.docs-story')
+    if (docsStory) {
+      docsStory.setAttribute('data-theme', theme)
+    }
+  }, [theme])
+  
+  return (
+    <div data-theme={theme} style={{ 
+      backgroundColor: theme === 'dark' ? '#171717' : '#ffffff',
+      minHeight: '100%',
+      padding: '1rem'
+    }}>
+      <Story />
+    </div>
+  )
+}
+
+const preview: Preview = {
+  decorators: [withTheme],
+  globalTypes: {
+    theme: {
+      description: 'Global theme for components',
+      defaultValue: 'light',
+      toolbar: {
+        title: 'Theme',
+        icon: 'circlehollow',
+        items: [
+          { value: 'light', title: 'Light', icon: 'sun' },
+          { value: 'dark', title: 'Dark', icon: 'moon' },
+        ],
+        dynamicTitle: true,
+      },
+    },
+  },
+  parameters: {
+    actions: { argTypesRegex: '^on[A-Z].*' },
+    backgrounds: {
+      disable: true, // Disable since we're handling it with theme
+    },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    a11y: {
+      config: {
+        rules: [
+          {
+            id: 'color-contrast',
+            enabled: true,
+          },
+        ],
+      },
+    },
+    docs: {
+      toc: false,
+    },
+  },
+}
+
+export default preview
+

package/.storybook/vite.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  base: '/storybook-static/',
+  define: {
+    'process.env': {},
+    'process': {
+      env: {},
+    },
+  },
+  build: {
+    // Ensure assets use absolute paths
+    assetsDir: 'assets',
+    // Disable source maps in production to avoid eval issues
+    sourcemap: false,
+    // Ensure proper minification
+    minify: 'esbuild',
+  },
+  // Ensure proper module resolution
+  resolve: {
+    preserveSymlinks: false,
+  },
+})
+

package/.storybook/welcome.mdx

@@ -0,0 +1,265 @@
+export const meta = {
+  title: 'Welcome',
+};
+
+# Welcome to the A11y Pros Accessible Design System
+
+Welcome to our **accessibility-first React UI component library**. This design system provides a comprehensive collection of fully accessible components built with React, TypeScript, and modern web standards.
+
+[View on GitHub](https://github.com/ryan0122/a11ypros-components) • [Npm Package](https://www.npmjs.com/package/@a11ypros/a11y-ui-components)
+
+## About This Design System
+
+This design system is **authored with accessibility in mind by a certified WAS (Web Accessibility Specialist)**. Every component has been carefully crafted to meet WCAG 2.1/2.2 Level AA standards, ensuring that your applications are usable by everyone, regardless of their abilities or the assistive technologies they use.
+
+**Note**: Currently, English is the only supported language for screen reader text and ARIA labels. Internationalization (i18n) support is coming soon.
+
+### Exploring Components
+
+Browse the component stories in the sidebar to explore each component's:
+
+### Key Features
+
+- **React 18+ Support**: Compatible with React 18.2.0 and React 19.0.0+
+- **Light & Dark Mode**: Built-in theming support with semantic color tokens for light and dark modes
+- **Fully Accessible Components**: All React UI components are fully accessible, featuring proper ARIA attributes, keyboard navigation, and screen reader support
+- **WCAG 2.1/2.2 Compliant**: Components follow accessibility best practices and meet WCAG Level AA standards
+- **Keyboard Navigation**: Complete keyboard support for all interactive elements
+- **Focus Management**: Proper focus trapping and return focus patterns for modals and dialogs
+- **Semantic HTML**: Components use semantic HTML with ARIA enhancements where needed
+- **Reduced Motion Support**: Respects `prefers-reduced-motion` media query
+- **High Contrast Support**: Supports `prefers-contrast` for better visibility
+- **Design Token System**: Consistent spacing, colors, typography, and motion tokens
+
+## Available Components
+
+Our component library includes:
+
+- **Button**: Accessible button with variants, sizes, and loading states
+- **Link**: Semantic link component with external link detection
+- **Modal**: Focus-trapped modal dialog with ARIA support
+- **DataTable**: Accessible table with keyboard navigation and sorting
+- **Tabs**: Tab component with arrow key navigation
+- **Form Components**: Input, Textarea, Select, Checkbox, Radio, Fieldset, Label
+
+## Coming Soon
+
+The following components are currently in development and will be available soon:
+
+- **DatePicker**: Accessible date selection component with keyboard navigation
+- **Banner**: Alert banner component with ARIA live region support
+- **Phone Text Field**: Specialized input field for phone numbers with formatting
+- **Combobox**: Accessible autocomplete/combobox component with ARIA 1.2 patterns
+
+## Getting Started
+
+### Installation
+
+Install the component library via npm:
+
+```bash
+npm i @a11ypros/a11y-ui-components
+```
+
+Or using yarn:
+
+```bash
+yarn add @a11ypros/a11y-ui-components
+```
+
+Or using pnpm:
+
+```bash
+pnpm add @a11ypros/a11y-ui-components
+```
+
+### Usage
+
+Once installed, you can import and use components in your React application:
+
+```tsx
+import { Button, Modal, DataTable } from '@a11ypros/a11y-ui-components';
+
+function App() {
+  return (
+    <Button variant="primary" size="medium">
+      Click me
+    </Button>
+  );
+}
+```
+
+Browse the component stories in the sidebar to explore each component's:
+- Usage examples
+- Accessibility features
+- Keyboard interaction patterns
+- WCAG compliance information
+- Props and API documentation
+
+### Customization with Design Tokens
+
+The library exports design tokens and utility functions for customizing your theme:
+
+```tsx
+import { colors, spacing, typography, breakpoints, motion } from '@a11ypros/a11y-ui-components';
+import { generateFocusRing, trapFocus, announceToScreenReader } from '@a11ypros/a11y-ui-components';
+
+// Use design tokens in your custom components
+const MyComponent = () => (
+  <div style={{ 
+    color: colors.primary[600], 
+    padding: spacing[4],
+    fontSize: typography.size.base 
+  }}>
+    Custom styled component with design tokens
+  </div>
+);
+
+// Use accessibility utilities
+const MyModal = () => {
+  const modalRef = useRef(null);
+  
+  useEffect(() => {
+    if (modalRef.current) {
+      trapFocus(modalRef.current);
+      announceToScreenReader('Modal opened');
+    }
+  }, []);
+  
+  return <div ref={modalRef}>...</div>;
+};
+```
+
+**Available Tokens:**
+- **Colors**: WCAG AA compliant color palettes (primary, neutral, success, warning, error)
+- **Spacing**: Consistent spacing scale based on 4px/8px grid
+- **Typography**: Font sizes, weights, and line heights
+- **Breakpoints**: Responsive design breakpoints
+- **Motion**: Animation durations respecting `prefers-reduced-motion`
+
+**Utility Functions:**
+- **ARIA helpers**: `announceToScreenReader`, `generateAriaLabel`
+- **Focus management**: `trapFocus`, `restoreFocus`, `generateFocusRing`
+- **Keyboard**: `handleEscape`, `handleArrowKeys`
+
+All tokens maintain WCAG 2.1/2.2 Level AA compliance for color contrast and spacing.
+
+### Overriding Design Tokens
+
+You can override the default design tokens by customizing CSS custom properties in your application:
+
+```css
+/* In your global CSS file */
+:root {
+  /* Override primary color */
+  --color-primary-500: #your-brand-color;
+  --color-primary-600: #your-darker-shade;
+  --color-primary-700: #your-darkest-shade;
+  
+  /* Override spacing */
+  --spacing-4: 1.5rem; /* default is 1rem */
+  
+  /* Override typography */
+  --font-size-base: 1.125rem; /* default is 1rem */
+  --font-weight-bold: 600; /* default is 700 */
+  
+  /* Override motion */
+  --duration-normal: 250ms; /* default is 200ms */
+}
+```
+
+### Light & Dark Mode Theming
+
+The design system includes built-in support for light and dark modes using semantic color tokens. Toggle between themes by setting the `data-theme` attribute:
+
+```html
+<!-- Light mode (default) -->
+<html data-theme="light">
+
+<!-- Dark mode -->
+<html data-theme="dark">
+```
+
+Implement a theme toggle in your application:
+
+```tsx
+const ThemeToggle = () => {
+  const [theme, setTheme] = useState('light');
+  
+  const toggleTheme = () => {
+    const newTheme = theme === 'light' ? 'dark' : 'light';
+    setTheme(newTheme);
+    document.documentElement.setAttribute('data-theme', newTheme);
+  };
+  
+  return (
+    <button onClick={toggleTheme}>
+      Switch to {theme === 'light' ? 'dark' : 'light'} mode
+    </button>
+  );
+};
+```
+
+**Theme-Aware Semantic Colors:**
+
+The system uses semantic color variables that automatically adapt to the current theme:
+- `--color-text-primary`: Main text color (dark in light mode, light in dark mode)
+- `--color-text-secondary`: Secondary text color
+- `--color-background-default`: Primary background
+- `--color-background-secondary`: Secondary background (cards, hover states)
+- `--color-link`: Link color (maintains WCAG AA contrast in both themes)
+- `--color-border-default`: Border colors
+
+All color combinations are tested to meet WCAG AA contrast requirements (4.5:1) in both light and dark modes.
+
+**Important**: When overriding colors, ensure your custom colors maintain WCAG AA contrast ratios:
+- **4.5:1** minimum for normal text
+- **3:1** minimum for large text (18pt+) and UI components
+
+**Available CSS Custom Properties:**
+- Semantic Colors (theme-aware): `--color-text-primary`, `--color-text-secondary`, `--color-background-default`, `--color-background-secondary`, `--color-link`, `--color-border-default`, `--color-border-hover`, `--color-border-focus`
+- Base Colors: `--color-primary-[50-900]`, `--color-neutral-[50-900]`, `--color-success-[500-700]`, etc.
+- Spacing: `--spacing-[0,1,2,3,4,5,6,8,10,12,16,20,24,32]`
+- Typography: `--font-size-[xs,sm,base,lg,xl,2xl,3xl,4xl]`, `--font-weight-[normal,medium,semibold,bold]`
+- Motion: `--duration-[fast,normal,slow]`
+
+## Accessibility First
+
+As a **certified WAS web accessibility specialist**, I've ensured that every component in this library:
+
+- Uses semantic HTML elements
+- Implements proper ARIA attributes
+- Supports full keyboard navigation
+- Provides visible focus indicators
+- Meets WCAG contrast requirements
+- Works seamlessly with screen readers
+- Handles focus management appropriately
+
+Each component story includes detailed accessibility documentation, so you can understand how to use these components in an accessible way.
+
+## Important Note on Accessibility
+
+> **Note**: While these components are built with accessibility in mind and meet WCAG 2.1/2.2 Level AA standards, **simply using these components does not guarantee an accessible application**. These components are foundational building blocks that must be used properly within the larger consuming application with accessibility in mind.
+
+To ensure your application is truly accessible, consider:
+
+- **Proper Implementation**: Use components according to their documented patterns and accessibility guidelines
+- **Application-Level Considerations**: Ensure proper page structure, heading hierarchy, and landmark regions
+- **Content Accessibility**: Write clear, descriptive text and provide alternative text for images
+- **Testing**: Regularly test your application with keyboard navigation and screen readers
+- **User Experience**: Consider the full user journey and how components work together
+
+These components provide a solid foundation, but accessibility is achieved through thoughtful implementation across your entire application.
+
+## Design Tokens
+
+The design system uses CSS custom properties for theming, ensuring consistency across your application while maintaining accessibility standards for color contrast and spacing.
+
+## Need Help?
+
+Explore the component stories to see examples, accessibility notes, and implementation details. Each component is documented with its WCAG compliance information and keyboard interaction patterns.
+
+---
+
+**Built with accessibility in mind by a certified WAS web accessibility specialist.**
+

package/DEPLOYMENT.md

@@ -0,0 +1,154 @@
+# Deployment Guide for ui.a11ypros.com
+
+This guide covers deploying the component library and Storybook to Netlify at `ui.a11ypros.com`.
+
+## What's Configured
+
+✅ **Netlify Configuration** (`netlify.toml`)
+- Builds Storybook and Next.js app
+- Serves Storybook at `/storybook`
+- Routes API calls to Netlify Functions
+
+✅ **Next.js Static Export**
+- Configured for static site generation
+- Outputs to `apps/web/out`
+
+✅ **Storybook Build**
+- Builds to `apps/web/public/storybook-static`
+- Accessible at `ui.a11ypros.com/storybook`
+
+✅ **Netlify Function**
+- Audit API converted to serverless function
+- Located at `netlify/functions/audit.ts`
+- Accessible via `/api/audit` (auto-redirected)
+
+## Deployment Steps
+
+### 1. Connect Repository to Netlify
+
+1. Go to [Netlify Dashboard](https://app.netlify.com)
+2. Click "Add new site" → "Import an existing project"
+3. Connect your Git provider and select this repository
+
+### 2. Configure Build Settings
+
+Netlify should auto-detect `netlify.toml`, but verify:
+- **Base directory:** `.` (root)
+- **Build command:** `npm install && npm run build-storybook && npm run build --workspace=apps/web`
+- **Publish directory:** `apps/web/out`
+
+### 3. Set Environment Variables
+
+Go to **Site settings → Environment variables** and add:
+- `ANTHROPIC_API_KEY` - Your Anthropic API key for the audit function
+
+### 4. Configure Custom Domain
+
+1. Go to **Site settings → Domain management**
+2. Click "Add custom domain"
+3. Enter `ui.a11ypros.com`
+4. Follow Netlify's DNS instructions:
+   - Add a **CNAME** record at your domain provider:
+     ```
+     Type: CNAME
+     Name: ui
+     Value: [your-netlify-site-name].netlify.app
+     ```
+5. Wait for DNS propagation (5-60 minutes)
+
+### 5. Deploy
+
+- Netlify will automatically deploy on every push to your main branch
+- Or click "Deploy site" to deploy manually
+
+## URLs After Deployment
+
+- **Main App:** `https://ui.a11ypros.com`
+- **Storybook:** `https://ui.a11ypros.com/storybook`
+- **Audit API:** `https://ui.a11ypros.com/api/audit` (POST)
+
+## How It Works
+
+1. **Build Process:**
+   - Installs dependencies
+   - Builds Storybook → `apps/web/public/storybook-static`
+   - Builds Next.js app → `apps/web/out` (includes Storybook from public/)
+
+2. **Routing:**
+   - `/storybook/*` → Served from `/storybook-static/*`
+   - `/api/audit` → Redirected to `/.netlify/functions/audit`
+   - `/*` → Next.js SPA routes
+
+3. **Netlify Function:**
+   - Serverless function handles the audit API
+   - Uses `ANTHROPIC_API_KEY` environment variable
+   - Supports CORS for cross-origin requests
+
+## Troubleshooting
+
+### Build Fails
+
+- Check Node.js version (should be 18+)
+- Verify all dependencies are in `package.json`
+- Check build logs in Netlify dashboard
+
+### Storybook Not Loading
+
+- Verify Storybook build completed successfully
+- Check that `apps/web/public/storybook-static` exists
+- Verify redirect rules in `netlify.toml`
+
+### API Not Working
+
+- Ensure `ANTHROPIC_API_KEY` is set in Netlify environment variables
+- Check Netlify Function logs in dashboard
+- Verify the function is deployed (check Functions tab)
+
+### DNS Issues
+
+- Wait for DNS propagation (can take up to 48 hours, usually 5-60 minutes)
+- Verify CNAME record is correct
+- Check DNS propagation with `dig ui.a11ypros.com`
+
+## Local Testing
+
+Test the build locally before deploying:
+
+```bash
+# Install dependencies
+npm install
+
+# Build Storybook
+npm run build-storybook
+
+# Build Next.js app
+npm run build --workspace=apps/web
+
+# Test locally (optional)
+npx serve apps/web/out
+```
+
+Visit `http://localhost:3000` for the app and `http://localhost:3000/storybook` for Storybook.
+
+## File Structure
+
+```
+├── netlify.toml              # Netlify configuration
+├── netlify/
+│   └── functions/
+│       └── audit.ts          # Netlify Function for audit API
+├── apps/
+│   └── web/
+│       ├── public/
+│       │   └── storybook-static/  # Storybook build output
+│       └── out/                  # Next.js build output
+└── package.json              # Root dependencies
+```
+
+## Notes
+
+- The Next.js app uses static export, so no server-side features
+- API routes are converted to Netlify Functions
+- Storybook is served as static files alongside the app
+- All routes are client-side (SPA mode)
+