@a11ypros/a11y-ui-components 1.0.0 → 1.0.1

package/.storybook/custom.css

@@ -0,0 +1,69 @@
+/* Custom Storybook styles */
+
+/* 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;
+}
+

package/.storybook/main.ts

@@ -0,0 +1,46 @@
+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'],
+  // 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.ts

@@ -0,0 +1,26 @@
+import { addons } from '@storybook/manager-api'
+import { create } from '@storybook/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,
+})
+

package/.storybook/package.json

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

package/.storybook/preview.tsx

@@ -0,0 +1,31 @@
+import type { Preview } from '@storybook/react'
+import '../packages/design-system/src/styles/global.css'
+import './custom.css'
+
+const preview: Preview = {
+  parameters: {
+    actions: { argTypesRegex: '^on[A-Z].*' },
+    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,97 @@
+import { Meta } from '@storybook/blocks';
+
+<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) • [Live Documentation](https://ui.a11ypros.com)
+
+## 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.
+
+### Key Features
+
+- **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
+- **Toast**: Notification system with ARIA live regions
+- **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
+
+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
+
+## 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)
+

package/README.md

@@ -0,0 +1,227 @@
+# Accessible Design System + AI Audit Assistant
+
+An opinionated, accessibility-first design system built with React, TypeScript, and Next.js, featuring an AI-powered accessibility audit assistant powered by Anthropic's Claude API.
+
+## Features
+
+- **WCAG 2.1/2.2 Compliant Components**: All components follow accessibility best practices
+- **Design Token System**: Consistent spacing, colors, typography, and motion tokens
+- **Keyboard Navigation**: Full keyboard support for all interactive elements
+- **Focus Management**: Proper focus trapping and return focus patterns
+- **ARIA Support**: Semantic HTML with ARIA enhancements where needed
+- **Reduced Motion**: Respects `prefers-reduced-motion` media query
+- **High Contrast**: Supports `prefers-contrast` for better visibility
+- **AI Audit Assistant**: Paste JSX code and get WCAG compliance reviews with code suggestions
+
+## Project Structure
+
+```
+├── packages/
+│   └── design-system/     # Component library
+│       ├── src/
+│       │   ├── components/ # React components
+│       │   ├── tokens/     # Design tokens
+│       │   ├── hooks/      # Custom hooks
+│       │   ├── utils/      # Utility functions
+│       │   └── styles/     # Global styles
+│       └── package.json
+├── apps/
+│   └── web/               # Next.js app
+│       ├── app/
+│       │   ├── (docs)/    # Documentation pages
+│       │   └── api/       # API routes
+│       └── package.json
+├── .storybook/            # Storybook configuration
+└── package.json           # Root workspace config
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+ 
+- npm or pnpm
+
+### Installation
+
+1. Clone the repository:
+```bash
+git clone <repository-url>
+cd PORTFOLIO
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Set up environment variables:
+Create a `.env.local` file in `apps/web/`:
+```bash
+ANTHROPIC_API_KEY=your_api_key_here
+```
+
+### Development
+
+1. Start the Next.js development server:
+```bash
+npm run dev
+```
+
+2. Start Storybook (in a separate terminal):
+```bash
+npm run storybook
+```
+
+The Next.js app will be available at `http://localhost:3000` and Storybook at `http://localhost:6006`.
+
+## Component Library
+
+### Available Components
+
+- **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
+- **Toast**: Notification system with ARIA live regions
+- **Tabs**: Tab component with arrow key navigation
+- **Form Components**: Input, Textarea, Select, Checkbox, Radio, Fieldset, Label
+
+### Usage Example
+
+```tsx
+import { Button, Input, Modal } from '@a11ypros/a11y-ui-components'
+
+function MyComponent() {
+  const [isOpen, setIsOpen] = useState(false)
+  
+  return (
+    <>
+      <Button variant="primary" onClick={() => setIsOpen(true)}>
+        Open Modal
+      </Button>
+      
+      <Modal
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        title="Example Modal"
+      >
+        <Input label="Email" type="email" required />
+      </Modal>
+    </>
+  )
+}
+```
+
+## WCAG Compliance
+
+Each component documents its WCAG 2.1/2.2 compliance:
+
+- **1.3.1** Info and Relationships (semantic HTML)
+- **1.4.3** Contrast (Minimum) - via design tokens
+- **2.1.1** Keyboard (all interactive elements)
+- **2.4.7** Focus Visible
+- **2.5.3** Label in Name
+- **4.1.2** Name, Role, Value (ARIA)
+- **4.1.3** Status Messages (for Toast)
+
+## AI Audit Assistant
+
+The AI Audit Assistant analyzes JSX code snippets for accessibility issues:
+
+1. Navigate to `/audit` in the Next.js app
+2. Paste your JSX code
+3. Click "Run Accessibility Audit"
+4. Review issues grouped by WCAG Success Criteria
+5. See code suggestions for each issue
+
+### API Setup
+
+The audit assistant requires an Anthropic API key:
+
+1. Get your API key from [Anthropic](https://console.anthropic.com/)
+2. Add it to `apps/web/.env.local`:
+   ```
+   ANTHROPIC_API_KEY=your_key_here
+   ```
+
+## Design Tokens
+
+The design system uses CSS custom properties for theming:
+
+```css
+/* Colors */
+--color-primary-500: #0ea5e9;
+--color-text-primary: #171717;
+
+/* Spacing */
+--spacing-4: 1rem;
+
+/* Typography */
+--font-size-base: 1rem;
+--font-weight-semibold: 600;
+
+/* Motion */
+--motion-duration-normal: 200ms;
+```
+
+## Storybook
+
+View all components and their documentation in Storybook:
+
+```bash
+npm run storybook
+```
+
+Each component story includes:
+- Usage examples
+- Accessibility notes
+- Keyboard interaction tables
+- WCAG compliance information
+
+## Building
+
+Build the Next.js app:
+```bash
+npm run build
+```
+
+Build Storybook:
+```bash
+npm run build-storybook
+```
+
+## Testing Accessibility
+
+### Automated Testing
+
+Storybook includes the `@storybook/addon-a11y` addon for automated accessibility checks.
+
+### Manual Testing
+
+1. **Keyboard Navigation**: Test all components with keyboard only (Tab, Arrow keys, Enter/Space)
+2. **Screen Reader**: Test with NVDA (Windows), VoiceOver (macOS), or JAWS
+3. **Focus Indicators**: Ensure all interactive elements have visible focus styles
+4. **Color Contrast**: Verify text meets WCAG AA contrast ratios (4.5:1)
+
+## Contributing
+
+When adding new components:
+
+1. Follow the existing component structure
+2. Include proper ARIA attributes
+3. Add keyboard navigation support
+4. Include focus management
+5. Add Storybook stories with accessibility documentation
+6. Test with keyboard and screen readers
+
+## License
+
+MIT
+
+## Resources
+
+- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+