Rule Mapping and Descriptions

/**
 * Gets user-friendly title for an axe accessibility test result
 * @param axeResult - Enhanced result from accessibility testing
 * @returns Human-readable title for the rule or rule ID if no mapping exists
 */
function getTitleForAxeResult(axeResult: EnhancedResult): string;

import { getTitleForAxeResult } from '@storybook/addon-a11y';

// Get a friendly title for a violation
const title = getTitleForAxeResult(violationResult);
console.log(title); // "Color contrast" instead of "color-contrast"

/**
 * Gets user-friendly summary for an axe accessibility test result
 * @param axeResult - Enhanced result from accessibility testing
 * @returns Friendly remediation summary or description fallback
 */
function getFriendlySummaryForAxeResult(
  axeResult: EnhancedResult
): string | undefined;

import { getFriendlySummaryForAxeResult } from '@storybook/addon-a11y';

// Get friendly remediation guidance for a violation
const guidance = getFriendlySummaryForAxeResult(violationResult);
console.log(guidance); // "The color contrast between text and its background meets WCAG AA contrast ratio."

type AxeRuleMap = {
  [axeId: string]: {
    /** The simple name of the rule */
    title: string;
    /** The summary of the rule from axe-core */
    axeSummary: string;
    /** The UX-friendly summary of the rule */
    friendlySummary: string;
  };
};

const combinedRulesMap: AxeRuleMap;

// Color contrast requirements
'color-contrast': {
  title: 'Color contrast',
  axeSummary: 'Ensure the contrast between foreground and background text meets WCAG 2 AA minimum thresholds',
  friendlySummary: 'The color contrast between text and its background meets WCAG AA contrast ratio.'
}

// Button accessibility
'button-name': {
  title: 'Button name',
  axeSummary: 'Ensure buttons have discernible text',
  friendlySummary: 'Every <button> needs a visible label or accessible name.'
}

// Image alt text
'image-alt': {
  title: 'Image alt text', 
  axeSummary: 'Ensure <img> elements have alternative text or a role of none/presentation',
  friendlySummary: 'Give every image alt text or mark it as decorative with alt="".'
}

// Autocomplete attributes
'autocomplete-valid': {
  title: 'autocomplete attribute valid',
  axeSummary: 'Ensure the autocomplete attribute is correct and suitable for the form field',
  friendlySummary: "Use valid autocomplete values that match the form field's purpose."
}

// Text spacing
'avoid-inline-spacing': {
  title: 'Forced inline spacing',
  axeSummary: 'Ensure that text spacing set via inline styles can be adjusted with custom CSS',
  friendlySummary: "Don't lock in text spacing with forced (!important) inline styles—allow user CSS to adjust text spacing."
}

// Touch target sizing
'target-size': {
  title: 'Touch target size',
  axeSummary: 'Ensure touch targets have sufficient size and space',
  friendlySummary: 'Make sure interactive elements are big enough and not too close together for touch.'
}

// Heading order
'heading-order': {
  title: 'Heading order',
  axeSummary: 'Ensure the order of headings is semantically correct (no skipping levels)',
  friendlySummary: "Use proper heading order (don't skip heading levels)."
}

// Landmark structure
'region': {
  title: 'Landmark regions',
  axeSummary: 'Ensure all page content is contained by landmarks',
  friendlySummary: 'Wrap all page content in appropriate landmark regions (<header>, <main>, <footer>, etc.).'
}

// Skip links
'skip-link': {
  title: 'Skip link',
  axeSummary: 'Ensure all "skip" links have a focusable target',
  friendlySummary: 'Make sure any "skip to content" link targets an existing, focusable element.'
}

// ARIA roles
'aria-roles': {
  title: 'ARIA role value',
  axeSummary: 'Ensure all elements with a role attribute use a valid value',
  friendlySummary: 'Use only valid values in the role attribute (no typos or invalid roles).'
}

// ARIA attributes
'aria-valid-attr': {
  title: 'ARIA attribute valid',
  axeSummary: 'Ensure attributes that begin with aria- are valid ARIA attributes',
  friendlySummary: 'Use only valid aria-* attributes (make sure the attribute name is correct).'
}

// ARIA required attributes
'aria-required-attr': {
  title: 'ARIA required attributes',
  axeSummary: 'Ensure elements with ARIA roles have all required ARIA attributes',
  friendlySummary: 'Include all required ARIA attributes for elements with that ARIA role.'
}

// Used in A11YPanel to show friendly titles
const violationTitle = getTitleForAxeResult(violation);
const violationSummary = getFriendlySummaryForAxeResult(violation);

// Used in Report component for detailed violation information
violations.forEach(violation => {
  const title = getTitleForAxeResult(violation);
  const guidance = getFriendlySummaryForAxeResult(violation);
  
  // Display title and guidance in the UI
  renderViolation({ title, guidance, ...violation });
});

// Used for contextual help and tooltips
const helpText = getFriendlySummaryForAxeResult(result);
showTooltip(helpText);