Accessibility Metadata & Validation

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/accessibility-metadata-validation/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A core feature for storing and validating structured accessibility metadata (alt text, descriptions, ARIA labels, JSON-LD markup) on products and pages, helping merchants meet EU Accessibility Act (WCAG 2.1 AA) requirements without depending on external tools.

The problem

A Greek merchant has a product catalog of 500 items. The EU Accessibility Act (EAA) was enforced in June 2025, and she needs WCAG 2.1 AA compliance. She has no fields for alt text or structured metadata. Her frontend dev says ‘just add alt text to images’—but WCAG also requires longdesc, ARIA labels, and JSON-LD. She doesn’t know what she’s missing or how to prove compliance.

What it does

• Product-level fields: alt text, long description, ARIA label, image role (decorative/meaningful)
• Page/collection fields: heading structure validation (h1/h2/h3 sequence), alt text for all images
• Validation rules: alt text is ≥10 characters and ≤125 characters (not too vague, not too long)
• JSON-LD schema generation: product, image, breadcrumb markup auto-generated from metadata
• Admin checklist: per-product accessibility score (% of WCAG A checks passed)
• Bulk action: auto-fill alt text from product name for images (merchant edits as needed)
• Audit log: when alt text was added/edited, by whom
• Export: CSV of product accessibility scores, missing alt text
• Integration with Next.js storefront: JSON API returns structured metadata for theme consumption
• Admin UI: product card shows green checkmark if all accessibility fields are filled

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Storefront rendering accessibility (contrast, focus states, keyboard navigation)—that’s the theme/frontend dev’s job, not the CMS
• Automated image description generation (using ML/AI)—complexity & cost too high; merchant must write or use theme’s AI integration
• Color-blind simulation or screen-reader testing within the admin UI—external tools handle this (AXE DevTools, etc.)
• ARIA widget attributes for custom components (tablist, combobox)—storefront theme owns this
• ATAG (authoring-tool accessibility) compliance for the admin panel itself—covered in a separate pass, not here

Data model

Extend Product: alt_text, long_description, aria_label, image_role; extend Page: heading_structure_json. New: A11yAuditLog(id, shopId, productId, field, old_value, new_value, changedAt, changedBy). No migration to existing shops; fields are nullable and added in a schema migration.

API

• GET /products/:id/accessibility — returns alt_text, long_description, aria_label, A11y score
• PUT /products/:id/accessibility — update any accessibility field
• POST /products/accessibility-audit — generate report of missing alt text
• POST /products/:id/generate-alt-text — populate alt from product name (merchant edits after)
• GET /products/accessibility-scores — list all products with A11y score, sorted by incomplete
• GET /pages/:id/accessibility — heading structure, alt text coverage
• GET /json-ld/:productId — returns Schema.org JSON-LD for product + images

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Accessibility panel: per-product card showing A11y score (green/yellow/red); fields for alt text, long description, ARIA label; ‘auto-fill alt from name’ button; audit export (which products need alt text); changelog (who edited what, when)

The seam — why this is core

Core owns: metadata fields, validation rules, scoring, admin UI, audit trail, JSON-LD generation. Paid pack owns: AI-assisted image description, quarterly WCAG audit by humans, theme certification program, regulatory filing support.

core owns the interface + an honest hand-modelled implementation — structured accessibility fields (alt text, longdesc, ARIA labels), JSON-LD schema, and admin validation are foundational. Storefront rendering accessibility is the theme’s responsibility.

Dependencies

• product schema (alt_text, long_description fields must be added)
• audit log infrastructure (must support product-level changes)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A product with alt_text=‘Leather handbag’, long_description filled, aria_label filled shows 100% A11y score (all 3 fields required)
• A product with only alt_text filled shows 33% A11y score
• Alt text <10 characters fails validation; >125 characters fails validation
• Exporting audit report shows exactly which products are missing which fields
• Auto-filling alt text from product name ‘Red Winter Boot’ creates alt_text=‘Red Winter Boot’ (merchant can edit)
• JSON-LD output includes Product, Image, and Breadcrumb schema for a product with full metadata
• Deleting a product’s alt_text creates an audit log entry showing old value → null
• A theme API call to GET /json-ld/prod123 returns valid JSON-LD (can be pasted into schema validator and pass)

Risks

Merchants might fill alt text with keyword spam (‘red boots red boots best red boots’) instead of descriptive text—validation only checks length, not quality. JSON-LD generation bug: if structured data is invalid, search engines and ATs ignore it silently. If scoring is too strict (100% never reachable), merchants give up. If too lenient, merchants don’t invest in quality.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.