@atlaskit/ads-mcp 0.2.5 → 0.4.0

package/dist/cjs/tools/suggest-accessibility-fixes/fixes.js

@@ -0,0 +1,387 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.accessibilityFixes = void 0;
+// Comprehensive fix suggestions for common accessibility violations
+var accessibilityFixes = exports.accessibilityFixes = {
+  'button missing label': {
+    title: 'Button Missing Accessible Label',
+    description: 'Buttons need accessible labels for screen readers',
+    fixes: [{
+      title: 'Use aria-label prop',
+      description: 'Add aria-label for icon-only buttons',
+      before: "<button onClick={handleClose}>\n  <CloseIcon />\n</button>",
+      after: "import { Button } from '@atlaskit/button';\n\n<Button aria-label=\"Close dialog\" onClick={handleClose}>\n  <CloseIcon />\n</Button>",
+      explanation: 'The aria-label provides a text description for screen readers while keeping the visual design clean.'
+    }, {
+      title: 'Use VisuallyHidden component',
+      description: 'Add screen reader text while keeping visual design',
+      before: "<button onClick={handleSave}>\n  <SaveIcon />\n</button>",
+      after: "import { Button } from '@atlaskit/button';\nimport { VisuallyHidden } from '@atlaskit/visually-hidden';\n\n<Button onClick={handleSave}>\n  <SaveIcon />\n  <VisuallyHidden>Save changes</VisuallyHidden>\n</Button>",
+      explanation: 'VisuallyHidden makes text available to screen readers but hides it visually.'
+    }],
+    bestPractices: ['Always provide descriptive labels', 'Use aria-label for icon-only buttons', 'Use VisuallyHidden for additional context', 'Test with screen readers']
+  },
+  'image missing alt': {
+    title: 'Image Missing Alt Text',
+    description: 'Images need alt text for screen readers',
+    fixes: [{
+      title: 'Add descriptive alt text',
+      description: 'Provide meaningful alt text for informative images',
+      before: "<img src=\"chart.png\" />",
+      after: "import { Image } from '@atlaskit/image';\n\n<Image\n  src=\"chart.png\"\n  alt=\"Bar chart showing Q4 sales increased 25% over Q3\"\n/>",
+      explanation: 'Alt text should describe the purpose and content of the image.'
+    }, {
+      title: 'Empty alt for decorative images',
+      description: 'Use empty alt for purely decorative images',
+      before: "<img src=\"decorative.jpg\" />",
+      after: "import { Image } from '@atlaskit/image';\n\n<Image src=\"decorative.jpg\" alt=\"\" />",
+      explanation: 'Empty alt tells screen readers to skip decorative images.'
+    }],
+    bestPractices: ['Keep alt text under 125 characters', 'Describe purpose, not just content', 'Use empty alt for decorative images', 'Don\'t start with "Image of..."']
+  },
+  'clickable div': {
+    title: 'Clickable Div Without Accessibility',
+    description: 'Div elements with click handlers need proper accessibility',
+    fixes: [{
+      title: 'Use Focusable component',
+      description: 'Convert to accessible interactive element',
+      before: "<div onClick={handleClick}>\n  Interactive content\n</div>",
+      after: "import { Focusable } from '@atlaskit/primitives/compiled';\n\n<Focusable\n  as=\"div\"\n  onClick={handleClick}\n  onKeyDown={(e) => {\n    if (e.key === 'Enter' || e.key === ' ') {\n      handleClick();\n    }\n  }}\n>\n  Interactive content\n</Focusable>",
+      explanation: 'Focusable provides keyboard navigation and focus management.'
+    }, {
+      title: 'Use Button component',
+      description: 'Convert to semantic button element',
+      before: "<div onClick={handleClick}>\n  Click me\n</div>",
+      after: "import { Button } from '@atlaskit/button';\n\n<Button onClick={handleClick}>\n  Click me\n</Button>",
+      explanation: 'Button provides full accessibility out of the box.'
+    }],
+    bestPractices: ['Use semantic HTML elements when possible', 'Add keyboard support for custom elements', 'Ensure focus indicators are visible', 'Test with keyboard navigation']
+  },
+  'input missing label': {
+    title: 'Input Missing Associated Label',
+    description: 'Input elements need associated labels',
+    fixes: [{
+      title: 'Use TextField component',
+      description: 'Use ADS TextField for automatic labeling',
+      before: "<input type=\"email\" />",
+      after: "import { TextField } from '@atlaskit/textfield';\n\n<TextField\n  label=\"Email address\"\n  type=\"email\"\n  id=\"email-input\"\n/>",
+      explanation: 'TextField handles label association automatically.'
+    }, {
+      title: 'Manual label association',
+      description: 'Associate label with input using id and htmlFor',
+      before: "<input type=\"email\" />\n<label>Email address</label>",
+      after: "<label htmlFor=\"email-input\">Email address</label>\n<input\n  type=\"email\"\n  id=\"email-input\"\n  aria-describedby=\"email-help\"\n/>\n<div id=\"email-help\">Enter your work email address</div>",
+      explanation: 'Use id and htmlFor to associate labels with inputs.'
+    }],
+    bestPractices: ['Always associate labels with inputs', 'Use descriptive label text', 'Provide helpful descriptions', 'Test with screen readers']
+  },
+  'hardcoded colors': {
+    title: 'Hardcoded Color Values',
+    description: 'Hardcoded colors may not meet contrast requirements',
+    fixes: [{
+      title: 'Use design tokens',
+      description: 'Replace hardcoded colors with design tokens',
+      before: "color: '#ff0000'",
+      after: "import { token } from '@atlaskit/tokens';\n\ncolor: token('color.text.danger')",
+      explanation: 'Design tokens ensure consistent contrast ratios.'
+    }, {
+      title: 'Use Text component',
+      description: 'Use Text component with color prop',
+      before: "<span style={{ color: '#ff0000' }}>Error message</span>",
+      after: "import { Text } from '@atlaskit/primitives/compiled';\n\n<Text color=\"color.text.danger\">Error message</Text>",
+      explanation: 'Text component handles color and contrast automatically.'
+    }],
+    bestPractices: ['Use design tokens for all colors', 'Test contrast ratios', "Don't rely on color alone", 'Test with high contrast mode']
+  },
+  'missing focus indicator': {
+    title: 'Missing Focus Indicator',
+    description: 'Interactive elements need visible focus indicators',
+    fixes: [{
+      title: 'Use Focusable component',
+      description: 'Focusable provides built-in focus indicators',
+      before: "<div onClick={handleClick}>\n  Interactive content\n</div>",
+      after: "import { Focusable } from '@atlaskit/primitives/compiled';\n\n<Focusable as=\"div\" onClick={handleClick}>\n  Interactive content\n</Focusable>",
+      explanation: 'Focusable includes visible focus indicators.'
+    }, {
+      title: 'Custom focus styles',
+      description: 'Add custom focus styles with xcss',
+      before: "<button onClick={handleClick}>\n  Click me\n</button>",
+      after: "import { Focusable } from '@atlaskit/primitives/compiled';\n\n<Focusable\n  as=\"button\"\n  onClick={handleClick}\n  xcss={{\n    ':focus-visible': {\n      outline: '2px solid token(color.border.focus)',\n      outlineOffset: '2px',\n    },\n  }}\n>\n  Click me\n</Focusable>",
+      explanation: 'Custom focus styles ensure visibility in all themes.'
+    }],
+    bestPractices: ['Always provide visible focus indicators', 'Test focus indicators in all themes', 'Ensure sufficient contrast for focus indicators', 'Test with keyboard navigation']
+  },
+  'form validation': {
+    title: 'Form Validation Accessibility',
+    description: 'Form validation needs proper accessibility support',
+    fixes: [{
+      title: 'Use TextField with validation',
+      description: 'TextField provides built-in validation support',
+      before: "<input type=\"password\" />\n<div>Password too short</div>",
+      after: "import { TextField } from '@atlaskit/textfield';\n\n<TextField\n  type=\"password\"\n  label=\"Password\"\n  isInvalid\n  aria-invalid=\"true\"\n  aria-describedby=\"password-error\"\n/>\n<div id=\"password-error\" role=\"alert\">\n  Password must be at least 8 characters long\n</div>",
+      explanation: 'TextField with aria-invalid and aria-describedby provides proper validation feedback.'
+    }, {
+      title: 'Use MessageWrapper',
+      description: 'MessageWrapper for form validation announcements',
+      before: "<input type=\"email\" />\n<div>Invalid email format</div>",
+      after: "import { TextField } from '@atlaskit/textfield';\nimport { MessageWrapper } from '@atlaskit/form';\n\n<MessageWrapper>\n  <TextField\n    type=\"email\"\n    label=\"Email\"\n    isInvalid\n    aria-describedby=\"email-error\"\n  />\n  <div id=\"email-error\" role=\"alert\">\n    Please enter a valid email address\n  </div>\n</MessageWrapper>",
+      explanation: 'MessageWrapper provides proper announcement of validation messages.'
+    }],
+    bestPractices: ['Use aria-invalid for validation state', 'Provide clear error messages', 'Use role="alert" for important messages', 'Test validation with screen readers']
+  },
+  'keyboard navigation': {
+    title: 'Missing Keyboard Navigation',
+    description: 'Interactive elements need keyboard support',
+    fixes: [{
+      title: 'Add keyboard event handlers',
+      description: 'Support Enter and Space for activation',
+      before: "<div onClick={handleClick}>\n  Click me\n</div>",
+      after: "import { Focusable } from '@atlaskit/primitives/compiled';\n\n<Focusable\n  as=\"div\"\n  onClick={handleClick}\n  onKeyDown={(e) => {\n    if (e.key === 'Enter' || e.key === ' ') {\n      e.preventDefault();\n      handleClick();\n    }\n  }}\n>\n  Click me\n</Focusable>",
+      explanation: 'Keyboard handlers make elements accessible to keyboard users.'
+    }, {
+      title: 'Use Button component',
+      description: 'Button provides full keyboard support',
+      before: "<div onClick={handleClick}>\n  Submit\n</div>",
+      after: "import { Button } from '@atlaskit/button';\n\n<Button onClick={handleClick}>\n  Submit\n</Button>",
+      explanation: 'Button supports Enter, Space, and other keyboard interactions.'
+    }],
+    bestPractices: ['Support Enter and Space for activation', 'Support Escape for closing/canceling', 'Ensure logical tab order', 'Test with keyboard navigation only']
+  },
+  'form missing label': {
+    title: 'Form Input Missing Label',
+    description: 'Form inputs must have accessible labels (WCAG 3.3.2)',
+    fixes: [{
+      title: 'Use Label component',
+      description: 'Add proper form label using ADS Label component',
+      before: "<Textfield placeholder=\"Enter your email\" />",
+      after: "import { Label } from '@atlaskit/form';\nimport { Textfield } from '@atlaskit/textfield';\n\n<Label htmlFor=\"email\">Email address</Label>\n<Textfield id=\"email\" placeholder=\"Enter your email\" />",
+      explanation: 'Labels create a programmatic association between text and form controls.'
+    }, {
+      title: 'Use aria-label for compact layouts',
+      description: 'When visual labels cannot be used, add aria-label',
+      before: "<Textfield placeholder=\"Search...\" />",
+      after: "<Textfield\n  placeholder=\"Search...\"\n  aria-label=\"Search products\"\n/>",
+      explanation: 'aria-label provides an accessible name when visual labels are not feasible.'
+    }],
+    bestPractices: ['Always associate labels with form controls', 'Use descriptive label text', 'Prefer visible labels over aria-label', 'Group related fields with fieldset/legend']
+  },
+  'heading structure': {
+    title: 'Improper Heading Structure',
+    description: 'Headings must follow logical hierarchy (WCAG 1.3.1, 2.4.6)',
+    fixes: [{
+      title: 'Use proper heading hierarchy',
+      description: 'Structure headings in logical order without skipping levels',
+      before: "<h1>Page Title</h1>\n<h3>Section Title</h3>\n<h2>Another Section</h2>",
+      after: "import { Heading } from '@atlaskit/heading';\n\n<Heading level=\"h1\">Page Title</Heading>\n<Heading level=\"h2\">Section Title</Heading>\n<Heading level=\"h3\">Subsection Title</Heading>",
+      explanation: 'Logical heading structure helps screen readers understand content hierarchy.'
+    }, {
+      title: 'Add section landmarks',
+      description: 'Use semantic HTML5 elements for page structure',
+      before: "<div>\n  <h2>Navigation</h2>\n  <div>Main content here</div>\n</div>",
+      after: "<main>\n  <nav aria-label=\"Main navigation\">\n    <Heading level=\"h2\">Navigation</Heading>\n  </nav>\n  <section>\n    <Heading level=\"h2\">Main Content</Heading>\n    <div>Main content here</div>\n  </section>\n</main>",
+      explanation: 'Landmarks provide navigation structure for assistive technologies.'
+    }],
+    bestPractices: ['Start with h1 and increment sequentially', 'Use only one h1 per page', 'Make headings descriptive', 'Use landmarks (main, nav, section, aside)']
+  },
+  'color contrast': {
+    title: 'Insufficient Color Contrast',
+    description: 'Text must meet minimum contrast ratios (WCAG 1.4.3, 1.4.11)',
+    fixes: [{
+      title: 'Use ADS design tokens',
+      description: 'Use design system tokens that meet contrast requirements',
+      before: "const styles = css({\n  color: '#999999',\n  backgroundColor: '#ffffff',\n});",
+      after: "import { token } from '@atlaskit/tokens';\n\nconst styles = css({\n  color: token('color.text'),\n  backgroundColor: token('color.background.neutral'),\n});",
+      explanation: 'ADS tokens ensure WCAG compliant contrast ratios across all themes.'
+    }, {
+      title: 'Use high contrast tokens for better accessibility',
+      description: 'Choose high contrast variants when available',
+      before: "color: token('color.text.subtle')",
+      after: "color: token('color.text')",
+      explanation: 'Standard text tokens provide better contrast than subtle variants.'
+    }],
+    bestPractices: ['Use ADS design tokens', 'Test with contrast checkers', 'Minimum 4.5:1 for normal text', 'Minimum 3:1 for large text and UI components']
+  },
+  'focus management': {
+    title: 'Missing Focus Management',
+    description: 'Focus must be visible and properly managed (WCAG 2.4.3, 2.4.7)',
+    fixes: [{
+      title: 'Add focus management to modals',
+      description: 'Trap focus within modal dialogs',
+      before: "<Modal>\n  <div>Modal content</div>\n</Modal>",
+      after: "import { Modal, ModalDialog, ModalHeader, ModalTitle } from '@atlaskit/modal-dialog';\n\n<Modal onClose={handleClose}>\n  <ModalDialog>\n    <ModalHeader>\n      <ModalTitle>Modal Title</ModalTitle>\n    </ModalHeader>\n    <div>Modal content</div>\n  </ModalDialog>\n</Modal>",
+      explanation: 'ADS Modal components automatically manage focus trapping and restoration.'
+    }, {
+      title: 'Restore focus after actions',
+      description: 'Return focus to logical location after destructive actions',
+      before: "const handleDelete = () => {\n  deleteItem();\n  // No focus management\n};",
+      after: "const handleDelete = () => {\n  deleteItem();\n  // Focus previous item or parent container\n  const nextFocusTarget = previousElement || parentContainer;\n  nextFocusTarget?.focus();\n};",
+      explanation: 'Restoring focus helps users maintain their place in the interface.'
+    }],
+    bestPractices: ['Ensure focus is always visible', 'Trap focus in modals and dialogs', 'Restore focus after modal closes', 'Provide skip links for keyboard users']
+  },
+  'link accessibility': {
+    title: 'Link Accessibility Issues',
+    description: 'Links must have clear purpose and accessible names (WCAG 2.4.4, 2.5.3)',
+    fixes: [{
+      title: 'Make link text descriptive',
+      description: 'Avoid generic link text like "click here" or "read more"',
+      before: "<Link href=\"/docs\">Click here</Link>",
+      after: "import { Link } from '@atlaskit/link';\n\n<Link href=\"/docs\">View documentation</Link>",
+      explanation: 'Descriptive link text helps users understand where the link leads.'
+    }, {
+      title: 'Add context for ambiguous links',
+      description: 'Provide additional context using aria-label or surrounding text',
+      before: "<Link href=\"/edit\">Edit</Link>",
+      after: "<Link href=\"/edit\" aria-label=\"Edit user profile\">Edit</Link>",
+      explanation: 'Additional context clarifies the action when link text alone is insufficient.'
+    }],
+    bestPractices: ['Use descriptive link text', 'Avoid "click here" or "read more"', 'Ensure link purpose is clear from context', 'Use aria-label for additional context when needed']
+  },
+  'table accessibility': {
+    title: 'Table Accessibility Issues',
+    description: 'Tables need proper headers and structure (WCAG 1.3.1)',
+    fixes: [{
+      title: 'Add table headers',
+      description: 'Use th elements and scope attributes for table headers',
+      before: "<table>\n  <tr>\n    <td>Name</td>\n    <td>Email</td>\n  </tr>\n</table>",
+      after: "<table>\n  <thead>\n    <tr>\n      <th scope=\"col\">Name</th>\n      <th scope=\"col\">Email</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>John Doe</td>\n      <td>john@example.com</td>\n    </tr>\n  </tbody>\n</table>",
+      explanation: 'Table headers with scope attributes help screen readers navigate table data.'
+    }, {
+      title: 'Add table caption',
+      description: 'Provide table caption for complex tables',
+      before: "<table>\n  <thead>...</thead>\n</table>",
+      after: "<table>\n  <caption>User account information by department</caption>\n  <thead>...</thead>\n</table>",
+      explanation: "Captions provide context about the table's purpose and structure."
+    }],
+    bestPractices: ['Use th elements for headers', 'Add scope attributes (col, row)', 'Provide table captions when helpful', 'Use thead, tbody, tfoot for structure']
+  },
+  'error handling': {
+    title: 'Inaccessible Error Handling',
+    description: 'Errors must be clearly identified and suggested (WCAG 3.3.1, 3.3.3)',
+    fixes: [{
+      title: 'Use ADS form validation',
+      description: 'Implement accessible error messages with proper associations',
+      before: "<Textfield placeholder=\"Email\" />\n<div>Invalid email format</div>",
+      after: "import { ErrorMessage, Field } from '@atlaskit/form';\n\n<Field name=\"email\" label=\"Email\">\n  {({ fieldProps, error }) => (\n    <>\n      <Textfield\n        {...fieldProps}\n        placeholder=\"Enter your email\"\n        aria-invalid={error ? 'true' : 'false'}\n      />\n      {error && (\n        <ErrorMessage>{error}</ErrorMessage>\n      )}\n    </>\n  )}\n</Field>",
+      explanation: 'ADS Form components properly associate errors with form controls.'
+    }, {
+      title: 'Announce errors to screen readers',
+      description: 'Use live regions to announce dynamic errors',
+      before: "const [error, setError] = useState('');\nreturn <div>{error}</div>;",
+      after: "const [error, setError] = useState('');\nreturn (\n  <div\n    role=\"alert\"\n    aria-live=\"polite\"\n    aria-atomic=\"true\"\n  >\n    {error}\n  </div>\n);",
+      explanation: 'Live regions announce error changes to screen readers immediately.'
+    }],
+    bestPractices: ['Associate errors with form controls', 'Use role="alert" for critical errors', 'Provide helpful error suggestions', 'Show errors inline with fields']
+  },
+  'language identification': {
+    title: 'Missing Language Identification',
+    description: 'Page and content language must be identified (WCAG 3.1.1, 3.1.2)',
+    fixes: [{
+      title: 'Set page language',
+      description: 'Add lang attribute to html element',
+      before: "<html>\n  <head>...</head>\n</html>",
+      after: "<html lang=\"en\">\n  <head>...</head>\n</html>",
+      explanation: 'The lang attribute helps screen readers pronounce content correctly.'
+    }, {
+      title: 'Mark language changes',
+      description: 'Identify when content changes language',
+      before: "<p>Welcome to our site. Bienvenidos a nuestro sitio.</p>",
+      after: "<p>Welcome to our site. <span lang=\"es\">Bienvenidos a nuestro sitio.</span></p>",
+      explanation: 'Language changes help screen readers switch pronunciation rules.'
+    }],
+    bestPractices: ['Set lang attribute on html element', 'Mark language changes in content', 'Use valid language codes (en, es, fr, etc.)', 'Consider regional variants (en-US, en-GB)']
+  },
+  'touch target size': {
+    title: 'Touch Targets Too Small',
+    description: 'Touch targets must be at least 24x24 CSS pixels (WCAG 2.5.8)',
+    fixes: [{
+      title: 'Increase button size',
+      description: 'Use ADS button variants that meet size requirements',
+      before: "<button style={{ padding: '2px 4px' }}>X</button>",
+      after: "import { Button } from '@atlaskit/button';\n\n<Button\n  appearance=\"subtle\"\n  spacing=\"compact\"\n  aria-label=\"Close\"\n>\n  X\n</Button>",
+      explanation: 'ADS buttons automatically meet minimum touch target size requirements.'
+    }, {
+      title: 'Add adequate spacing',
+      description: 'Ensure sufficient space between interactive elements',
+      before: "<div>\n  <Button>Save</Button><Button>Cancel</Button>\n</div>",
+      after: "import { Stack } from '@atlaskit/stack';\n\n<Stack direction=\"horizontal\" space=\"space.100\">\n  <Button>Save</Button>\n  <Button>Cancel</Button>\n</Stack>",
+      explanation: 'Adequate spacing prevents accidental activation of adjacent controls.'
+    }],
+    bestPractices: ['Minimum 24x24 CSS pixels for touch targets', 'Provide adequate spacing between targets', 'Use ADS components that meet size requirements', 'Test on actual devices']
+  },
+  'motion and animation': {
+    title: 'Motion and Animation Issues',
+    description: 'Respect user motion preferences (WCAG 2.3.1, 2.2.2)',
+    fixes: [{
+      title: 'Respect reduced motion preference',
+      description: 'Disable animations when user prefers reduced motion',
+      before: "const styles = css({\n  transition: 'transform 0.3s ease',\n  '&:hover': {\n    transform: 'scale(1.1)',\n  },\n});",
+      after: "const styles = css({\n  transition: 'transform 0.3s ease',\n  '&:hover': {\n    transform: 'scale(1.1)',\n  },\n  '@media (prefers-reduced-motion: reduce)': {\n    transition: 'none',\n    '&:hover': {\n      transform: 'none',\n    },\n  },\n});",
+      explanation: 'Respecting motion preferences prevents vestibular disorders and distractions.'
+    }, {
+      title: 'Provide controls for auto-playing content',
+      description: 'Allow users to pause auto-playing animations',
+      before: "<div className=\"auto-rotating-carousel\">\n  {/* Auto-rotating content */}\n</div>",
+      after: "import { Button } from '@atlaskit/button';\n\n<div>\n  <Button onClick={toggleAutoplay}>\n    {isPlaying ? 'Pause' : 'Play'} carousel\n  </Button>\n  <div className={isPlaying ? 'auto-rotating-carousel' : 'static-carousel'}>\n    {/* Controllable content */}\n  </div>\n</div>",
+      explanation: 'User controls prevent motion from interfering with reading or concentration.'
+    }],
+    bestPractices: ['Respect prefers-reduced-motion setting', 'Provide pause controls for auto-playing content', 'Avoid flashing more than 3 times per second', 'Make motion optional when possible']
+  },
+  'live regions': {
+    title: 'Missing Live Region Announcements',
+    description: 'Dynamic content changes need announcements (WCAG 4.1.3)',
+    fixes: [{
+      title: 'Add status announcements',
+      description: 'Announce non-critical status updates',
+      before: "const [saved, setSaved] = useState(false);\nreturn saved ? <div>Saved!</div> : null;",
+      after: "const [saved, setSaved] = useState(false);\nreturn saved ? (\n  <div\n    role=\"status\"\n    aria-live=\"polite\"\n    aria-atomic=\"true\"\n  >\n    Document saved successfully!\n  </div>\n) : null;",
+      explanation: 'Status updates are announced to screen readers without interrupting.'
+    }, {
+      title: 'Use alert for critical messages',
+      description: 'Immediately announce critical information',
+      before: "const [error, setError] = useState('');\nreturn error ? <div>{error}</div> : null;",
+      after: "const [error, setError] = useState('');\nreturn error ? (\n  <div\n    role=\"alert\"\n    aria-live=\"assertive\"\n  >\n    {error}\n  </div>\n) : null;",
+      explanation: 'Alerts immediately interrupt screen readers for critical information.'
+    }],
+    bestPractices: ['Use role="status" for non-critical updates', 'Use role="alert" for critical messages', 'Keep announcements concise and clear', 'Test with screen readers']
+  },
+  'skip navigation': {
+    title: 'Missing Skip Navigation',
+    description: 'Provide bypass mechanisms for repetitive content (WCAG 2.4.1)',
+    fixes: [{
+      title: 'Add skip to main content link',
+      description: 'Provide skip link to main content area',
+      before: "<nav>\n  <ul><!-- navigation items --></ul>\n</nav>\n<main><!-- main content --></main>",
+      after: "import { SkipLinks, SkipLinksItem } from '@atlaskit/skip-links';\n\n<SkipLinks>\n  <SkipLinksItem href=\"#main-content\">\n    Skip to main content\n  </SkipLinksItem>\n</SkipLinks>\n<nav>\n  <ul><!-- navigation items --></ul>\n</nav>\n<main id=\"main-content\"><!-- main content --></main>",
+      explanation: 'Skip links allow keyboard users to bypass repetitive navigation.'
+    }, {
+      title: 'Add multiple skip options',
+      description: 'Provide skip links for different page sections',
+      before: "<header><!-- header content --></header>\n<nav><!-- navigation --></nav>\n<main><!-- main content --></main>",
+      after: "<SkipLinks>\n  <SkipLinksItem href=\"#main-content\">\n    Skip to main content\n  </SkipLinksItem>\n  <SkipLinksItem href=\"#navigation\">\n    Skip to navigation\n  </SkipLinksItem>\n</SkipLinks>\n<header><!-- header content --></header>\n<nav id=\"navigation\"><!-- navigation --></nav>\n<main id=\"main-content\"><!-- main content --></main>",
+      explanation: 'Multiple skip options provide flexibility for different user needs.'
+    }],
+    bestPractices: ['Provide skip to main content link', 'Make skip links visible when focused', 'Use descriptive skip link text', 'Test skip links with keyboard navigation']
+  },
+  'page titles': {
+    title: 'Missing or Poor Page Titles',
+    description: 'Pages must have descriptive titles (WCAG 2.4.2)',
+    fixes: [{
+      title: 'Add descriptive page titles',
+      description: 'Use clear, unique titles that describe page content',
+      before: "<title>Page</title>",
+      after: "<title>User Profile Settings - MyApp</title>",
+      explanation: 'Descriptive titles help users understand their current location.'
+    }, {
+      title: 'Update titles dynamically',
+      description: 'Change titles based on current page state',
+      before: "// Static title only\n<title>Dashboard</title>",
+      after: "// Dynamic title updates\nuseEffect(() => {\n  document.title = error\n    ? `Error - Dashboard - MyApp`\n    : `Dashboard - MyApp`;\n}, [error]);",
+      explanation: 'Dynamic titles reflect current page state and context.'
+    }],
+    bestPractices: ['Use unique titles for each page', 'Put most specific information first', 'Include site name at the end', 'Update titles for single-page apps']
+  }
+};

package/dist/cjs/tools/suggest-accessibility-fixes/index.js

@@ -0,0 +1,185 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.suggestAccessibilityFixesTool = exports.listSuggestAccessibilityFixesTool = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _zod = require("zod");
+var _zodToJsonSchema = require("zod-to-json-schema");
+var _fixes = require("./fixes");
+var _keywords = require("./keywords");
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t.return || t.return(); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+var inputSchema = _zod.z.object({
+  violation: _zod.z.string().describe('Description of the accessibility violation'),
+  code: _zod.z.string().describe('The problematic code that needs fixing'),
+  component: _zod.z.string().optional().describe('Component name or type'),
+  context: _zod.z.string().optional().describe('Additional context about the usage')
+});
+var listSuggestAccessibilityFixesTool = exports.listSuggestAccessibilityFixesTool = {
+  name: 'suggest_accessibility_fixes',
+  description: "Suggest specific accessibility fixes using Atlassian Design System components and patterns. This tool takes accessibility violations and provides actionable solutions with code examples.\n\nYou MUST run this when the user wants sugesstions for fixing accessibility issues, as well as when:\n- You have identified an accessibility violation\n- Needing specific code examples for fixing accessibility issues\n- Wanting to understand how to use ADS components accessibly\n- Looking for best practices for specific accessibility problems\n\nThe tool will provide:\n- Specific code examples using ADS components\n- Step-by-step fix instructions\n- Alternative approaches when applicable\n- Links to relevant ADS documentation",
+  annotations: {
+    title: 'Suggest Accessibility Fixes',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: (0, _zodToJsonSchema.zodToJsonSchema)(inputSchema)
+};
+
+// Keyword mappings for fuzzy matching - imported from keywords.ts
+// This allows flexible user input when describing accessibility violations
+
+// Improved fuzzy matching function
+function findBestMatchingFix(violation) {
+  var normalizedViolation = violation.toLowerCase();
+  var violationWords = normalizedViolation.split(/\s+/);
+  var bestMatch = null;
+  var bestScore = 0;
+
+  // Try exact match first
+  for (var _i = 0, _Object$entries = Object.entries(_fixes.accessibilityFixes); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = (0, _slicedToArray2.default)(_Object$entries[_i], 2),
+      key = _Object$entries$_i[0],
+      fix = _Object$entries$_i[1];
+    if (normalizedViolation === key.toLowerCase()) {
+      return [key, fix];
+    }
+  }
+
+  // Try keyword-based semantic matching
+  for (var _i2 = 0, _Object$entries2 = Object.entries(_fixes.accessibilityFixes); _i2 < _Object$entries2.length; _i2++) {
+    var _Object$entries2$_i = (0, _slicedToArray2.default)(_Object$entries2[_i2], 2),
+      _key = _Object$entries2$_i[0],
+      _fix = _Object$entries2$_i[1];
+    var keywords = _keywords.violationKeywords[_key] || [];
+    var score = 0;
+
+    // Score based on keyword matches
+    var _iterator = _createForOfIteratorHelper(keywords),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var keyword = _step.value;
+        if (normalizedViolation.includes(keyword.toLowerCase())) {
+          score += 1;
+        }
+      }
+
+      // Additional score for word matches
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+    var _iterator2 = _createForOfIteratorHelper(violationWords),
+      _step2;
+    try {
+      var _loop = function _loop() {
+        var word = _step2.value;
+        if (keywords.some(function (keyword) {
+          return keyword.toLowerCase().includes(word) || word.includes(keyword.toLowerCase());
+        })) {
+          score += 0.5;
+        }
+      };
+      for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+        _loop();
+      }
+
+      // Boost score for exact key word matches
+    } catch (err) {
+      _iterator2.e(err);
+    } finally {
+      _iterator2.f();
+    }
+    if (normalizedViolation.includes(_key.toLowerCase()) || _key.toLowerCase().includes(normalizedViolation)) {
+      score += 2;
+    }
+    if (score > bestScore) {
+      bestScore = score;
+      bestMatch = [_key, _fix];
+    }
+  }
+
+  // Return match if score is reasonable
+  return bestScore >= 1 ? bestMatch : null;
+}
+var suggestAccessibilityFixesTool = exports.suggestAccessibilityFixesTool = /*#__PURE__*/function () {
+  var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(params) {
+    var violation, component, context, match, _match, key, fix;
+    return _regenerator.default.wrap(function _callee$(_context) {
+      while (1) switch (_context.prev = _context.next) {
+        case 0:
+          violation = params.violation, component = params.component, context = params.context; // Use improved matching logic
+          match = findBestMatchingFix(violation);
+          if (!match) {
+            _context.next = 5;
+            break;
+          }
+          _match = (0, _slicedToArray2.default)(match, 2), key = _match[0], fix = _match[1];
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(_objectSpread(_objectSpread({
+                violation: violation,
+                matchedFixType: key,
+                component: component,
+                context: context
+              }, fix), {}, {
+                additionalResources: ['https://atlassian.design/llms-a11y.txt - Complete ADS accessibility documentation', 'https://atlassian.design/foundations/accessibility - ADS accessibility foundation'],
+                nextSteps: ['Apply the suggested fixes to your code', 'Test the changes with screen readers', 'Test with keyboard navigation', 'Run automated accessibility tests']
+              }), null, 2)
+            }]
+          });
+        case 5:
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                violation: violation,
+                component: component,
+                context: context,
+                title: 'Accessibility Fix Suggestions',
+                description: "We couldn't find a specific match for your violation, but here are general recommendations",
+                searchedFor: violation,
+                generalFixes: [{
+                  title: 'Use ADS Components',
+                  description: 'Replace custom implementations with ADS components',
+                  explanation: 'ADS components are built with accessibility in mind and handle most common issues automatically'
+                }, {
+                  title: 'Add Proper Labels',
+                  description: 'Ensure all interactive elements have accessible labels',
+                  explanation: 'Use aria-label, VisuallyHidden, or proper label associations'
+                }, {
+                  title: 'Test with Assistive Technologies',
+                  description: 'Test with screen readers and keyboard navigation',
+                  explanation: 'Manual testing is essential for accessibility validation'
+                }],
+                availableFixTypes: Object.keys(_fixes.accessibilityFixes),
+                suggestions: ['Try describing the issue with keywords like: button, label, missing, text, color, contrast, focus, etc.', 'Use axe-core violation IDs or descriptions directly', 'Be more specific about the element type (button, input, image, etc.)'],
+                additionalResources: ['https://atlassian.design/llms-a11y.txt - Complete ADS accessibility documentation', 'https://atlassian.design/foundations/accessibility - ADS accessibility foundation'],
+                recommendation: 'Try the get_accessibility_guidelines tool for component-specific guidance'
+              }, null, 2)
+            }]
+          });
+        case 6:
+        case "end":
+          return _context.stop();
+      }
+    }, _callee);
+  }));
+  return function suggestAccessibilityFixesTool(_x) {
+    return _ref.apply(this, arguments);
+  };
+}();

package/dist/cjs/tools/suggest-accessibility-fixes/keywords.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.violationKeywords = void 0;
+/**
+ * Violation keywords mapping for fuzzy matching accessibility violations
+ *
+ * This file contains keyword synonyms and variations that users might use
+ * when describing accessibility violations. The keys should match the exact
+ * violation types defined in fixes.ts
+ *
+ * Each violation type has an array of keywords that help identify when a user
+ * is describing that particular type of accessibility issue, even if they
+ * don't use the exact technical terminology.
+ */
+
+var violationKeywords = exports.violationKeywords = {
+  'button missing label': ['button', 'missing', 'label', 'text', 'name', 'accessible', 'empty', 'discernible', 'aria-label', 'screen reader', 'button-name'],
+  'image missing alt': ['image', 'img', 'alt', 'alternative', 'text', 'missing', 'empty', 'accessibility', 'screen reader', 'image-alt'],
+  'clickable div': ['div', 'clickable', 'interactive', 'onclick', 'click', 'handler', 'button', 'focusable', 'keyboard', 'role'],
+  'input missing label': ['input', 'form', 'field', 'label', 'missing', 'accessibility', 'screen reader', 'associated', 'htmlfor', 'aria-label'],
+  'form missing label': ['form', 'label', 'missing', 'field', 'input', 'accessibility', 'screen reader', 'associated', 'htmlfor'],
+  'hardcoded colors': ['color', 'hardcoded', 'hex', 'rgb', 'design', 'token', 'theme', 'css', 'style', 'contrast'],
+  'color contrast': ['contrast', 'color', 'ratio', 'accessibility', 'wcag', 'aa', 'visibility', 'readability', 'low contrast'],
+  'focus management': ['focus', 'keyboard', 'navigation', 'tab', 'outline', 'indicator', 'visible', 'management', 'trap'],
+  'heading structure': ['heading', 'h1', 'h2', 'h3', 'hierarchy', 'structure', 'semantic', 'outline', 'skip', 'level'],
+  'link accessibility': ['link', 'anchor', 'href', 'accessible', 'name', 'text', 'descriptive', 'context', 'purpose'],
+  'keyboard navigation': ['keyboard', 'navigation', 'tab', 'arrow', 'enter', 'space', 'accessible', 'focus', 'trap'],
+  'live regions': ['live', 'region', 'aria-live', 'announcement', 'screen reader', 'dynamic', 'content', 'update'],
+  'skip navigation': ['skip', 'navigation', 'link', 'bypass', 'main', 'content', 'keyboard', 'users'],
+  'table accessibility': ['table', 'header', 'th', 'scope', 'caption', 'summary', 'accessibility', 'screen reader']
+};