@atlaskit/ads-mcp 0.2.5 → 0.3.0

package/dist/cjs/tools/get-accessibility-guidelines/index.js

@@ -0,0 +1,204 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.listGetAccessibilityGuidelinesTool = exports.getAccessibilityGuidelinesTool = 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 _zod = require("zod");
+var _zodToJsonSchema = require("zod-to-json-schema");
+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; }
+var inputSchema = _zod.z.object({
+  topic: _zod.z.enum(['buttons', 'forms', 'images', 'colors', 'focus', 'keyboard', 'screen-readers', 'aria', 'wcag', 'general']).optional().describe('Specific accessibility topic to get guidelines for'),
+  component: _zod.z.string().optional().describe('Component name to get specific accessibility guidance for')
+});
+var listGetAccessibilityGuidelinesTool = exports.listGetAccessibilityGuidelinesTool = {
+  name: 'get_accessibility_guidelines',
+  description: "Get accessibility guidelines and best practices from the Atlassian Design System. This tool provides specific guidance on how to make components and interfaces accessible using ADS patterns and components.\n\nYou MUST run this when the user wants their code to be accessible, as well as when:\n- Needing specific accessibility guidance for a component\n- Looking for ADS-specific accessibility patterns\n- Understanding how to implement accessible features\n- Getting code examples for accessibility improvements\n\nTopics available:\n- buttons: Button and interactive element accessibility\n- forms: Form and input accessibility\n- images: Image and media accessibility\n- colors: Color and contrast accessibility\n- focus: Focus management and keyboard navigation\n- keyboard: Keyboard accessibility patterns\n- screen-readers: Screen reader support and announcements\n- aria: ARIA usage and patterns\n- wcag: WCAG compliance guidelines\n- general: General accessibility principles",
+  annotations: {
+    title: 'Get Accessibility Guidelines',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: (0, _zodToJsonSchema.zodToJsonSchema)(inputSchema)
+};
+
+// Comprehensive accessibility guidelines based on llms-a11y.txt
+var accessibilityGuidelines = {
+  buttons: {
+    title: 'Button and Interactive Element Accessibility',
+    description: 'Guidelines for making buttons and interactive elements accessible',
+    guidelines: ['Always provide accessible labels for buttons', 'Use Button component for standard interactions', 'Use Focusable component for custom interactive elements', 'Avoid disabled buttons with tooltips', 'Ensure focus indicators are visible', 'Support keyboard navigation (Enter, Space)', 'Use descriptive labels that explain the action'],
+    codeExamples: [{
+      title: 'Accessible Button with Icon',
+      code: "import { Button } from '@atlaskit/button';\nimport { VisuallyHidden } from '@atlaskit/visually-hidden';\n\n<Button aria-label=\"Close dialog\" onClick={handleClose}>\n  <CloseIcon />\n</Button>"
+    }, {
+      title: 'Custom Interactive Element',
+      code: "import { Focusable } from '@atlaskit/primitives/compiled';\n\n<Focusable as=\"div\" onClick={handleClick} onKeyDown={handleKeyDown}>\n  Interactive content\n</Focusable>"
+    }],
+    bestPractices: ['Never disable buttons without providing alternatives', 'Use VisuallyHidden for screen reader text', 'Test with keyboard navigation only', 'Ensure focus indicators meet contrast requirements']
+  },
+  forms: {
+    title: 'Form and Input Accessibility',
+    description: 'Guidelines for making forms and inputs accessible',
+    guidelines: ['Use TextField component for consistent labeling', 'Associate labels with inputs using id and htmlFor', 'Provide clear error messages with aria-describedby', 'Use MessageWrapper for form validation announcements', 'Use aria-required for required fields', 'Group related form elements with fieldset and legend'],
+    codeExamples: [{
+      title: 'Accessible Text Field',
+      code: "import { TextField } from '@atlaskit/textfield';\n\n<TextField\n  label=\"Email address\"\n  isRequired\n  aria-describedby=\"email-help\"\n  id=\"email-input\"\n/>\n<div id=\"email-help\">Enter your work email address</div>"
+    }, {
+      title: 'Form Validation with Error Messages',
+      code: "import { TextField } from '@atlaskit/textfield';\n\n<TextField\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>"
+    }],
+    bestPractices: ['Never rely on placeholder text for critical information', 'Provide helpful error messages and descriptions', 'Use proper form validation with aria-invalid', 'Test form completion with screen readers']
+  },
+  images: {
+    title: 'Image and Media Accessibility',
+    description: 'Guidelines for making images and media accessible',
+    guidelines: ['Use Image component with proper alt text', 'Keep alt text under 125 characters', 'Leave alt="" for decorative images', 'Describe the purpose, not just the content', 'Don\'t start with "Image of..." or "Picture of..."', 'Provide detailed descriptions for complex images'],
+    codeExamples: [{
+      title: 'Decorative Image',
+      code: "import { Image } from '@atlaskit/image';\n\n<Image src=\"decorative.jpg\" alt=\"\" />"
+    }, {
+      title: 'Informative Image',
+      code: "import { Image } from '@atlaskit/image';\n\n<Image\n  src=\"chart.png\"\n  alt=\"Bar chart showing Q4 sales increased 25% over Q3\"\n/>"
+    }, {
+      title: 'Complex Image with Description',
+      code: "import { Image } from '@atlaskit/image';\n\n<Image\n  src=\"complex-diagram.png\"\n  alt=\"\"\n  aria-describedby=\"diagram-description\"\n/>\n<div id=\"diagram-description\">\n  Detailed description of the diagram content...\n</div>"
+    }],
+    bestPractices: ['For important information, use text instead of images', 'Avoid images of text', 'Provide alternative formats for complex visual content', 'Test with screen readers to ensure proper announcement']
+  },
+  colors: {
+    title: 'Color and Contrast Accessibility',
+    description: 'Guidelines for using colors accessibly',
+    guidelines: ['Use design tokens for consistent contrast ratios', 'Never rely on color alone for information', 'Use color.text tokens for proper contrast', 'Test with high contrast mode', 'Ensure 4.5:1 contrast ratio for normal text', 'Ensure 3:1 contrast ratio for large text'],
+    codeExamples: [{
+      title: 'Using Design Tokens for Colors',
+      code: "import { token } from '@atlaskit/tokens';\n\nconst styles = css({\n  color: token('color.text'),\n  backgroundColor: token('color.background.neutral'),\n});"
+    }, {
+      title: 'Text Component with Color',
+      code: "import { Text } from '@atlaskit/primitives/compiled';\n\n<Text color=\"color.text.danger\">Error message</Text>\n<Text color=\"color.text.success\">Success message</Text>"
+    }],
+    bestPractices: ['Use color.text tokens for primary text', 'Use color.text.subtle sparingly for secondary text', 'Avoid color.text.disabled for critical information', 'Test with different color vision types']
+  },
+  focus: {
+    title: 'Focus Management',
+    description: 'Guidelines for proper focus management',
+    guidelines: ['Ensure logical tab order', 'Provide visible focus indicators', 'Handle focus trapping in modals', 'Return focus when dialogs close', 'Use Focusable component for custom elements', 'Manage focus in dynamic content'],
+    codeExamples: [{
+      title: 'Focus Management in Modal',
+      code: "import { useRef, useEffect } from 'react';\n\nconst modalRef = useRef<HTMLDivElement>(null);\n\nuseEffect(() => {\n  if (isOpen && modalRef.current) {\n    modalRef.current.focus();\n  }\n}, [isOpen]);"
+    }, {
+      title: 'Custom Focusable Element',
+      code: "import { Focusable } from '@atlaskit/primitives/compiled';\n\n<Focusable\n  as=\"div\"\n  tabIndex={0}\n  onKeyDown={(e) => {\n    if (e.key === 'Enter' || e.key === ' ') {\n      handleActivate();\n    }\n  }}\n>\n  Custom focusable element\n</Focusable>"
+    }],
+    bestPractices: ['Test focus order with keyboard navigation', 'Ensure focus indicators are visible in all themes', 'Handle focus restoration when components unmount', 'Use focus trapping for modal dialogs']
+  },
+  keyboard: {
+    title: 'Keyboard Accessibility',
+    description: 'Guidelines for keyboard accessibility',
+    guidelines: ['Support standard keyboard interactions', 'Use Enter and Space for activation', 'Use Escape for closing/canceling', 'Support arrow keys for navigation', 'Provide keyboard shortcuts for power users', 'Ensure all interactive elements are keyboard accessible'],
+    codeExamples: [{
+      title: 'Keyboard Event Handling',
+      code: "const handleKeyDown = (event: KeyboardEvent) => {\n  switch (event.key) {\n    case 'Enter':\n    case ' ':\n      handleActivate();\n      break;\n    case 'Escape':\n      handleClose();\n      break;\n    case 'Tab':\n      // Handle focus management\n      break;\n  }\n};"
+    }],
+    bestPractices: ['Test with keyboard navigation only', 'Ensure logical tab order', 'Provide keyboard alternatives for mouse interactions', 'Support both Enter and Space for activation']
+  },
+  screenReaders: {
+    title: 'Screen Reader Support',
+    description: 'Guidelines for screen reader accessibility',
+    guidelines: ['Use Announcer component for dynamic content', 'Provide skip links for keyboard users', 'Use proper heading hierarchy', 'Use semantic HTML elements', 'Provide live regions for status updates', 'Use VisuallyHidden for screen reader text'],
+    codeExamples: [{
+      title: 'Screen Reader Announcements',
+      code: "import { Announcer } from '@atlaskit/announcer';\n\n<Announcer\n  message={`${count} items selected`}\n  liveMode=\"polite\"\n  shouldAnnounce={true}\n/>"
+    }, {
+      title: 'Skip Links',
+      code: "<a href=\"#main-content\" className=\"skip-link\">\n  Skip to main content\n</a>"
+    }],
+    bestPractices: ['Test with multiple screen readers (NVDA, JAWS, VoiceOver)', 'Use aria-live="polite" for status updates', 'Use aria-live="assertive" for critical alerts', 'Avoid announcing the same message repeatedly']
+  },
+  aria: {
+    title: 'ARIA Usage Guidelines',
+    description: 'Guidelines for using ARIA attributes',
+    guidelines: ['Use ARIA sparingly - prefer semantic HTML', 'Use proper ARIA roles and states', 'Provide live regions for dynamic content', 'Use landmarks for page structure', 'Ensure ARIA attributes are supported', 'Test ARIA implementations with screen readers'],
+    codeExamples: [{
+      title: 'Live Region for Status Updates',
+      code: "<div aria-live=\"polite\" role=\"status\">\n  {statusMessage}\n</div>"
+    }, {
+      title: 'Landmark Navigation',
+      code: "<nav role=\"navigation\" aria-label=\"Main navigation\">\n  Navigation content\n</nav>"
+    }],
+    bestPractices: ['Use semantic HTML elements when possible', 'Test ARIA implementations thoroughly', 'Keep ARIA usage simple and clear', 'Document custom ARIA patterns']
+  },
+  wcag: {
+    title: 'WCAG Compliance',
+    description: 'WCAG 2.1 AA compliance guidelines',
+    guidelines: ['Ensure information is perceivable', 'Make interface components operable', 'Ensure information is understandable', 'Make content robust and compatible', 'Test with multiple assistive technologies', 'Follow WCAG 2.1 AA success criteria'],
+    codeExamples: [{
+      title: 'WCAG Compliant Component',
+      code: "// Example of a WCAG compliant button\n<Focusable\n  as=\"button\"\n  aria-label=\"Save changes\"\n  onClick={handleSave}\n  onKeyDown={handleKeyDown}\n>\n  <SaveIcon />\n  <VisuallyHidden>Save changes</VisuallyHidden>\n</Focusable>"
+    }],
+    bestPractices: ['Test with automated accessibility tools', 'Conduct manual accessibility testing', 'Test with users who have disabilities', 'Document accessibility compliance']
+  },
+  general: {
+    title: 'General Accessibility Principles',
+    description: 'General accessibility principles and best practices',
+    guidelines: ['Design for people, not just compliance', 'Consider accessibility from the start', 'Test with real users and assistive technologies', 'Provide multiple ways to accomplish tasks', 'Use inclusive design principles', 'Test with different abilities and technologies'],
+    codeExamples: [{
+      title: 'Inclusive Design Example',
+      code: "// Component that works for everyone\n<Focusable\n  as=\"button\"\n  onClick={handleAction}\n  aria-label=\"Clear form data\"\n  onKeyDown={handleKeyDown}\n>\n  <TrashIcon />\n  <VisuallyHidden>Clear all form data</VisuallyHidden>\n</Focusable>"
+    }],
+    bestPractices: ['Start with semantic HTML', 'Add ARIA when necessary', 'Test early and often', 'Involve users with disabilities in testing', 'Keep accessibility in mind throughout development']
+  }
+};
+var getAccessibilityGuidelinesTool = exports.getAccessibilityGuidelinesTool = /*#__PURE__*/function () {
+  var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(params) {
+    var topic, component, guidelines;
+    return _regenerator.default.wrap(function _callee$(_context) {
+      while (1) switch (_context.prev = _context.next) {
+        case 0:
+          topic = params.topic, component = params.component;
+          if (!(topic && accessibilityGuidelines[topic])) {
+            _context.next = 4;
+            break;
+          }
+          guidelines = accessibilityGuidelines[topic];
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(_objectSpread(_objectSpread({
+                topic: topic,
+                component: component
+              }, guidelines), {}, {
+                additionalResources: ['https://atlassian.design/llms-a11y.txt - Complete ADS accessibility documentation', 'https://atlassian.design/foundations/accessibility - ADS accessibility foundation', 'https://www.w3.org/WAI/WCAG21/quickref/ - WCAG 2.1 guidelines']
+              }), null, 2)
+            }]
+          });
+        case 4:
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                availableTopics: Object.keys(accessibilityGuidelines),
+                component: component,
+                message: 'Specify a topic to get detailed guidelines, or use "general" for overview',
+                guidelines: accessibilityGuidelines,
+                additionalResources: ['https://atlassian.design/llms-a11y.txt - Complete ADS accessibility documentation', 'https://atlassian.design/foundations/accessibility - ADS accessibility foundation']
+              }, null, 2)
+            }]
+          });
+        case 5:
+        case "end":
+          return _context.stop();
+      }
+    }, _callee);
+  }));
+  return function getAccessibilityGuidelinesTool(_x) {
+    return _ref.apply(this, arguments);
+  };
+}();

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']
+  }
+};