| name | accessibility-audit |
| description | Audits WCAG 2.1 AA compliance across photography e-commerce pages — validates image alt text for photographs, color contrast, heading hierarchy, ARIA labels, keyboard-accessible purchase flows, and screen reader compatibility |
| version | 1.0.0 |
Accessibility Audit — Photography E-Commerce
Purpose
Audit and enforce WCAG 2.1 AA compliance across all flickersofmajesty pages. This skill validates image alt text (critical for a photography site where images are the product), color contrast ratios, heading hierarchy, ARIA labeling, keyboard-accessible purchase flows, form accessibility, and screen reader compatibility.
When to Fire
- When creating or editing any HTML page or template
- When adding or modifying product images, gallery pages, or print option forms
- When building or updating purchase flows, cart, or checkout components
- When reviewing pages for accessibility compliance
- When prompted with
/accessibility-audit or asked to check accessibility
- Before any page goes live or is merged to production
- When editing CSS that affects color, font size, or focus styles
Instructions
1. Image Alt Text Validation
On a photography e-commerce site, images ARE the product. Alt text must describe what the photograph actually depicts so that a screen reader user can make an informed purchase decision.
Rules:
- Every
<img> MUST have an alt attribute — missing alt is a WCAG failure
- Product photography alt text must describe the actual photograph content: subject, setting, mood, and key visual elements (e.g., "Golden hour light filtering through oak trees along a forest path in autumn, warm amber and deep green tones" not "nature photo" or "print-017")
- Alt text must serve as a purchase-worthy description — a customer who cannot see the image should understand what they are buying
- Alt text should not begin with "Image of" or "Photo of" — screen readers already announce it as an image
- Gallery thumbnails must have alt text that distinguishes each photograph from its neighbors
- Decorative UI elements (borders, spacing images, background textures) must use
alt=""
- For photographs with text overlays, the alt text must include the overlay text content
Product page specifics:
- Hero/featured photograph: detailed description including subject, composition, lighting, and color palette (40-120 characters)
- Thumbnail variants (if showing the same print in different sizes/frames): alt text should indicate the variant (e.g., "Forest path photograph displayed in 16x20 white matte frame")
- Lifestyle/mockup images showing prints in room settings: describe the room context and the print placement
- If a photograph is available in multiple crops or orientations, each variant needs distinct alt text
Flag these violations:
<img> with no alt attribute — Critical- Product image with generic alt text ("photo", "print", "image-1") — Critical
- Product image with filename as alt text ("DSC_4829.jpg", "IMG_0372.png") — Critical
- Alt text that does not describe the photograph's visual content — Critical (this is a purchase-blocking accessibility failure)
- Alt text exceeding 150 characters without an
aria-describedby companion for extended description — Warning
2. Color Contrast Ratio Validation
Validate that all text meets WCAG 2.1 AA contrast requirements against its background.
Minimum ratios:
- Normal text (below 18pt / 14pt bold): 4.5:1 contrast ratio
- Large text (18pt+ or 14pt+ bold): 3:1 contrast ratio
- UI components and graphical objects: 3:1 contrast ratio against adjacent colors
What to check in CSS:
color against background-color on the same element or nearest ancestor with a background- Text over background images or gradients — ensure sufficient contrast across all areas where text appears
- Hover, focus, and active states — contrast must be maintained in all interactive states
- Disabled states are exempt but should still be distinguishable
Photography e-commerce specific checks:
- Product titles and prices overlaid on or adjacent to photographs — contrast must be maintained regardless of the photograph's tonal range
- If text overlays a photograph directly, ensure a semi-transparent background or text shadow provides reliable contrast
- Print option labels (size, frame, matte) against their container backgrounds
- Cart item names and prices
- Checkout form labels and input text
- Sale/discount badges and promotional text
- Gallery navigation controls against their backgrounds
- "Add to cart" and "Buy now" button text against button backgrounds
Flag these violations:
- Any normal text below 4.5:1 ratio — Critical
- Any large text below 3:1 ratio — Critical
- Text overlaid on photographs without a contrast-ensuring background layer — Critical
- Placeholder text with insufficient contrast — Warning
- Focus indicators that do not meet 3:1 against adjacent colors — Critical
3. Heading Hierarchy Validation
Verify that heading levels follow a logical, sequential order with no skipped levels.
Rules:
- Each page must have exactly one
<h1>
- Headings must not skip levels:
h1 → h2 → h3 is valid; h1 → h3 is a violation
- Heading levels can decrease by more than one at section boundaries but must not skip going deeper
- Headings must not be used solely for visual styling — if text looks like a heading but is a
<p> with large font, flag it
- If text is styled as a heading visually but uses
<div> or <span>, flag as a violation
Product page heading structure:
h1 = photograph title or collection nameh2 = major sections (Print Options, About This Photograph, Shipping, Reviews)h3 = subsections within those areas (Size Options, Frame Options, Matte Options under Print Options)- Print option groups must not use
h4 or h5 directly under h1 — maintain the hierarchy through h2 → h3
- Gallery/collection pages:
h1 = collection name, h2 = individual photograph titles within the gallery
Flag these violations:
- Multiple
<h1> elements on a single page — Critical
- Skipped heading level (e.g.,
h1 → h3, h2 → h4) — Critical
- Heading used purely for styling without semantic meaning — Warning
- Print options section lacking proper heading structure — Warning
4. ARIA Labels on Interactive Elements
Validate that all interactive components have proper ARIA labeling for assistive technology.
Rules for all interactive elements:
- Every interactive element must have an accessible name via
aria-label, aria-labelledby, or visible <label>
aria-label must describe the action, not the element typearia-labelledby must reference an existing element id on the pagerole attributes must be used correctly per WAI-ARIA spec- Custom widgets must declare
role, aria-label, and relevant states
Purchase flow — mandatory checks:
- Print size selector: must use proper
role="radiogroup" or role="listbox" with aria-label="Select print size"
- Frame option selector: must have
aria-label and proper selection state (aria-selected or aria-checked)
- Quantity controls: increment/decrement buttons must have
aria-label ("Increase quantity", "Decrease quantity") and the quantity value must be announced
- "Add to cart" button: must have clear accessible name; if it updates dynamically, use
aria-live to announce the update
- Cart: item list must be structured for screen readers; removal buttons must identify which item they remove (e.g.,
aria-label="Remove Forest Path print from cart")
- Checkout form: all steps must be labeled; progress indicators must use
aria-current="step"
Image gallery interactions:
- Gallery navigation (next/previous) must have
aria-label ("Next photograph", "Previous photograph")
- Lightbox/modal must use
role="dialog" and aria-modal="true" with aria-label
- Zoom controls must have accessible names
- Gallery filter/sort controls must have labels and announce results
Flag these violations:
- Interactive element with no accessible name — Critical
aria-labelledby referencing a nonexistent id — Critical- Cart/checkout dynamic updates without
aria-live — Critical
- Incorrect
role usage — Warning
5. Keyboard Navigation Paths
Verify that the entire purchase flow and all gallery interactions are fully operable via keyboard alone.
Rules:
- Every interactive element must be reachable via
Tab key (or Arrow keys within widget groups)
- Focus order must follow a logical reading sequence
- No keyboard traps: the user must be able to
Tab away from every element
Escape must close modals, lightboxes, and overlay panels- Custom interactive elements must handle
Enter and Space for activation
tabindex usage:
tabindex="0" to add to natural tab order — acceptabletabindex="-1" for programmatic focus management — acceptable- Positive
tabindex values — always a violation
Purchase flow keyboard path (must work end-to-end):
- Browse gallery →
Tab to photograph → Enter to open product page
- Select print size →
Arrow keys within size group, Space/Enter to select
- Select frame option → same pattern
- Set quantity →
Tab to quantity, Arrow or type a number
- Add to cart →
Tab to button, Enter to add → confirmation must be announced
- Open cart →
Tab to cart icon/link, Enter to open
- Review cart →
Tab through items, modify quantities, remove items
- Checkout →
Tab through form fields, submit order
Image gallery keyboard specifics:
- Gallery grid: arrow keys to navigate between thumbnails,
Enter to open lightbox
- Lightbox:
Arrow keys for next/previous, Escape to close, focus trapped within lightbox while open
- Zoom: keyboard shortcut or focusable control
Flag these violations:
- Element with
onclick but no keyboard equivalent and no native keyboard behavior — Critical
- Positive
tabindex values — Critical
- Lightbox or modal without focus trapping — Critical
- Purchase flow step unreachable via keyboard — Critical
- Missing focus management after dynamic updates — Warning
6. Form Labels and Error States
Validate that all forms — especially the purchase and checkout forms — are accessible.
Rules:
- Every
<input>, <select>, and <textarea> must have an associated <label> or aria-label
- Labels must be visible —
aria-label alone only when visual design makes purpose obvious
- Required fields must use
aria-required="true" and a visible indicator
- Error messages must be:
- Programmatically associated with the field via
aria-describedby or aria-errormessage
- Announced to screen readers (via
aria-live or role="alert")
- Specific about the problem ("Enter a valid email address" not "Invalid input")
- Form submission errors must move focus to the first error or an error summary
E-commerce form checks:
- Checkout fields: name, email, shipping address, payment — all must have proper labels and autocomplete attributes
- Shipping address: use
autocomplete attributes (autocomplete="shipping street-address", autocomplete="shipping postal-code", etc.)
- Payment fields: properly labeled, errors specific (e.g., "Card number must be 16 digits")
- Print option forms: size/frame selectors must communicate their current selection and any constraints
- Contact form: all fields labeled, error handling accessible
- Email signup: proper label, error handling, success confirmation announced
Flag these violations:
- Input with no associated label or
aria-label — Critical
- Error message not programmatically linked to its field — Critical
- Checkout field missing
autocomplete attribute — Warning
- Required field with no accessible indication — Warning
- Error message that lacks specificity — Warning
7. Skip-to-Content Links and Focus Indicators
Skip navigation:
- Every page must have a "Skip to main content" link as the first focusable element
- The link may be visually hidden but must become visible on focus
- The link must target a valid
id on the <main> element or primary content area
- On gallery pages with extensive navigation, a skip link is critical
Focus indicators:
- Every focusable element must have a visible focus indicator
- The default browser outline is acceptable, but if overridden (
outline: none), a custom focus style must be provided
- Focus indicators must have at least 3:1 contrast against adjacent backgrounds
:focus-visible is preferred over :focus to avoid showing focus rings on mouse clicks- On dark-themed gallery pages, ensure focus indicators are visible against dark backgrounds
Flag these violations:
- No skip-to-content link — Critical
outline: none or outline: 0 without a replacement focus style — Critical- Skip link targeting a nonexistent
id — Critical
- Focus indicator with insufficient contrast — Warning
8. Screen Reader Compatibility
Landmark regions:
- Page must use semantic landmarks:
<header>, <nav>, <main>, <footer>, <aside>
- If multiple
<nav> elements exist, each must have a distinguishing aria-label (e.g., "Main navigation", "Gallery filters", "Footer links")
<main> must be present exactly once per page
Content structure:
- Product option tables must use
<th> with scope — do not use tables for layout
- Lists of photographs, sizes, or frames must use
<ul> or <ol> — not styled <div> sequences
- Links must have descriptive text — no bare "click here" or "view" without context
- Icons used as links/buttons (cart icon, zoom icon, favorite/heart icon) must have screen reader text via
aria-label or visually hidden <span>
Photography e-commerce specific checks:
- Product pages: screen reader should encounter photograph description, then title, then price, then options in a logical order
- Gallery pages: each photograph card should announce the photograph title and price (if shown)
- Cart: each item must be identifiable by product name, selected options, and price
- Checkout progress: current step must be identifiable via
aria-current
- Order confirmation: all order details must be accessible in reading order
9. WCAG 2.1 AA Specific Checks
These additional WCAG 2.1 criteria often get overlooked:
- 1.3.4 Orientation: Content must not be locked to portrait or landscape — photograph viewing especially must work in both orientations
- 1.3.5 Identify Input Purpose: Checkout form fields must use
autocomplete attributes for personal data
- 1.4.10 Reflow: Content must reflow at 320px width without horizontal scrolling — gallery grid must reflow to single column; product pages must stack vertically
- 1.4.11 Non-text Contrast: UI components (add-to-cart button borders, form field borders, gallery nav arrows) must have 3:1 contrast
- 1.4.12 Text Spacing: Content must remain functional when text spacing is increased (line-height 1.5x, paragraph spacing 2x, letter spacing 0.12em, word spacing 0.16em) — print option labels must not overlap or truncate
- 1.4.13 Content on Hover or Focus: Tooltips showing print details or shipping info must be dismissible, hoverable, and persistent
- 4.1.3 Status Messages: "Added to cart" confirmations, cart count updates, and checkout step completions must be announced to screen readers without receiving focus
10. Reporting Format
For each page or component audited, produce a report structured as:
## Accessibility Audit: [Page Title or Component Name]
### WCAG 2.1 AA Compliance Summary
- **Critical Violations**: [count]
- **Warnings**: [count]
- **Passed Checks**: [count]
### Critical Violations (must fix)
- [ ] [WCAG criterion number] [Description] — [Specific fix suggestion]
### Warnings (should fix)
- [ ] [WCAG criterion number] [Description] — [Recommendation]
### Passed Checks
- [x] [Check description]
### Purchase Flow Accessibility Status
| Step | Keyboard Nav | ARIA Labels | Focus Mgmt | Error Handling |
|------|-------------|-------------|------------|----------------|
| Gallery Browse | Pass/Fail | Pass/Fail | Pass/Fail | N/A |
| Product Page | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail |
| Cart | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail |
| Checkout | Pass/Fail | Pass/Fail | Pass/Fail | Pass/Fail |
Prioritize critical violations. Always provide the specific WCAG criterion number (e.g., 1.1.1, 1.4.3) and a concrete fix suggestion — not just "fix contrast" but "Change .product-price color from #aaa to #767676 to achieve 4.54:1 against white background."
Soli Deo Gloria
