About this Session: Accessibility is often treated as a "final coat of paint," leading to fragmented user experiences across platforms. Vanessa Johnson (Android Engineer at The New York Times) proposes a radical shift: embedding accessibility metadata directly into GraphQL schemas. Using custom directives and code generation, this approach enables mobile and web clients to receive accessible defaults—such as content descriptions and roles—directly from the API contract. This session provides a technical blueprint for making inclusivity a core part of the developer experience (DevEx) rather than an afterthought. Key Takeaways: • API-First Accessibility: Learn to encode accessibility requirements directly into your API contract using GraphQL custom directives. • Automated Metadata Delivery: See how code generation can deliver accessibility defaults to clients (Android, iOS, Web) automatically from day one. • Cross-Platform Consistency: Strategies to ensure a unified accessible experience across Jetpack Compose and SwiftUI. • Actionable Blueprints: Get access to schema snippets and a repository with working code examples to implement these strategies immediately. ------------------------------------ Conference Details: Conference: apidays Paris 2025 | part of FOST 2025 Theme: The APIs meet AI conference: Innovation, Security, Sovereignty, Sustainability Date: 9 - 11 December 2025 • CNIT Forest, Paris -------------------------- Resources from apidays: Join our upcoming conferences: https://www.apidays.global/ Read the latest API news: https://www.apiscene.io Explore the API Landscape: https://apilandscape.apiscene.io/

1. What if GraphQL Knew
Accessibility?
Dynamic Accessibility Summaries with Directives
apidays Paris 2025 December 911, 2025
Vanessa Johnson

2. Impact
Why This Work
Vanessa Johnson
Android Engineer
The New York Times
Make accessibility a first class citizen in API design.
Can work across Android, iOS, and Web teams.
Believe that programmatic accessibility metadata
can bridge the gap between API design and
inclusive user experiences, making the user
experience better for everyone.
About Me

3. Why Accessibility Matters
The invisible user base we can't afford to ignore
1.3B
People with
disabilities globally
16% of world
population
71%
Leave inaccessible
sites immediately
Lost customers due
to poor UX
3%
Of the web is
fully accessible
WebAIM Million 2025
report

4. The Accessibility Gap in APIs
How APIs shape user experience long before UI code is written
APIs Shape UX First
Data structure determines user
flow
APIs define what
information is available and
how it's organized, and
influence UI decisions
before designers even
start.
Accessibility Added
Last
An afterthought in development
Accessibility is typically
addressed during UI
implementation, long after
API contracts are finalized.
Inconsistent
Implementation
No standard approach
Each team implements
accessibility differently,
leading to inconsistent
experiences across
platforms.

5. APIs Today: What We Get
Standard GraphQL query without accessibility metadata
GraphQL Query
query Movie {
movie(id: "1") {
title
releaseYear
rating
}
}

6. Pain Points
The challenges of retrofitting accessibility
Leaving components without a11y labels
“Unlabeledˮ
Missing information that will be needed by
screen readers to help users use your product.
Inconsistent Across Platforms
Android ≠ iOS  Web
Each platform team implements accessibility
differently, creating divergent experiences for
the same data.
The Result: Fragile, Inconsistent Accessibility
Every platform reinvents accessibility labels, leading to drift, bugs, and inconsistent screen reader
experiences.
This creates a maintenance nightmare as APIs evolve and teams scale.

7. The Client Info Flow Problem
Developers handcraft fragile accessibility phrases
Kotlin Example
val summary = "${movie.title},
${movie.releaseYear}, rated
${movie.rating}/10"
String Building is Fragile
Hardcoded templates break when data changes,
localization needed, or edge cases emerge.
Duplicated Logic
Same pattern repeated across Android, iOS,
Web teams with slight variations.
Inconsistent Results
Screen readers hear different summaries for the
same content depending on platform.

8. The Cost of Doing Nothing
Why accessibility is a business imperative, not just a compliance checkbox
Abandonment
Disabled users leave
difficult sites
immediately
Lost customers &
revenue
Monetary Settlements
Per accessibility lawsuit
Legal risk &
compliance
SEO Traffic Gain
From accessible,
structured content
Discoverability &
reach
The Business Case is Clear
Accessibility isn't just about compliance, it's about market expansion, brand reputation, and
reducing risk.
Companies that invest in accessibility see measurable returns across customer satisfaction,
conversion rates, and operational efficiency.

9. Initial Schema Without A11y)
Basic Movie type with no accessibility metadata
GraphQL Schema
type Movie {
title: String!
releaseYear: String!
rating: Float!
}

10. Core Idea: Embed Accessibility
Metadata
query {
title
releaseYear
rating
a11y // example
}

11. Shifting Left: The Vision
Make accessibility part of the API contract, not a frontend afterthought
Encode Semantics
Embed accessibility metadata
directly in GraphQL schema using
custom directives
Generate Types
Create strongly typed models
that carry a11y metadata to clients
Deliver Defaults
Provide accessible labels, tokens,
and templates to all platforms
from day one
"Accessibility should be baked into the API, not sprinkled on top of the UI later."

12. Schema Wiring
Inject a11y
Add per field hints
Schema +
Directives
Enhanced
Schema
Response
summary: “The
movie
Inception,
released on
2010-07-16, is
rated 8.8 out of
10."
Custom
Wiring
Plugin

13. Core Idea: Embed Accessibility Metadata
Use GraphQL directives to annotate types and fields with accessibility information
@a11yLabel
Declare which field is the main
label for screen readers
@a11yToken
Structured data type with priority,
units, and formatting
@a11yTemplate
Sentence template with
placeholders for consistent
phrasing
The Goal: Consistent, Accessible Experiences
Clients assemble labels, tokens, and templates to generate reliable, localized summaries for screen
readers.
One schema change → consistent accessibility across all platforms.

14. @a11yLabel Directive
Declare the primary label for screen readers
GraphQL Schema What It Does
Tells screen readers which field contains the
primary, human readable label for this object.
Why It Matters
Provides the main identifier that screen readers
announce first when users encounter this object.
Usage Pattern
Applied to the object type, not individual fields,
points to the field that best represents the object.
directive @a11yLabel(field: String!) on
OBJECT | FIELD_DEFINITION
type Movie @a11yLabel(field: "title") {
title: String!
releaseYear: String!
rating: Float!
}

15. @a11yToken Directive
Structured data type for screen readers with priority and formatting
GraphQL type + field
The data type and field name this token represents
(e.g., "price", "rating", "date").
priority 0..n
Order of importance for screen readers. Lower
values = higher priority. Default: 0.
unitPrefix / unitSuffix
Format numbers with currency symbols,
percentages, or unit labels (e.g., "$", "/10", "GB").
number: Boolean
Treats the value as a number for proper screen reader
pronunciation (e.g., "299" vs "two nine nine").
directive @a11yToken(
type: String!
field: String!
priority: Int = 0
label: String
labelPosition: String
unitPrefix: String
unitSuffix: String
number: Boolean
) on FIELD_DEFINITION

16. @a11yTemplate Directive
Sentence template with dynamic placeholders
GraphQL Schema Template Placeholders
Use {fieldName} syntax to reference schema fields
in the template.
Natural Language
Template creates human readable sentences
that screen readers can speak naturally.
Dynamic Assembly
Runtime substitution ensures summaries stay
current with changing data.
directive @a11yTemplate(summary:
String) on OBJECT
type Movie @a11yTemplate(summary:
"{title}, {releaseYear}, rated {rating}/10")
{
title: String!
releaseYear: String!
rating: Float!
}

17. Complete Schema Example With A11y)
Full implementation with all three directives and generated types
type YourType @a11yTemplate(summary:
"{name}, {price}") {
name: String!
@a11yLabel(field: "name")
@a11yToken(type: "name", field: "name",
priority: 0)
price: Float
@a11yToken(
type: "price",
field: "price",
priority: 1,
unitPrefix: "$",
number: true
)
a11y: A11y!
}
type A11y {
label: String!
tokens: [A11yToken!]
templates: A11yTemplates
}
type A11yToken {
type: String!
value: String!
priority: Int!
}
type A11yTemplates {
summary: String
}

18. Query Structure
Requesting accessibility metadata alongside regular data
GraphQL Query
Clients request regular data plus a nested
a11y object that contains all accessibility
metadata.
The a11y field provides comprehensive
accessibility information
query Product$id: ID!) {
product(id: $id) {
name
price
a11y {
label
tokens {
type
value
priority
}
templates {
summary
}
}
}
}

19. Response Structure With A11y)
How clients receive accessibility metadata alongside regular data
JSON Response
{
"product": {
"name": "Noise-Canceling Headphones",
"price": 299.0,
"a11y": {
"label": "Noise-Canceling Headphones",
"tokens": [
{
"type": "name",
"value": "Noise-Canceling Headphones",
"priority": 0
},
{
"type": "price",
"value": "299",
"priority": 1
}
],
"templates": {
"summary": "Noise-Canceling Headphones, $299"
}
}
}
}

20. Response Structure With A11y)
Label
Main screen reader label
Tokens
Structured data with priority
Templates
Sentence assembly pattern

21. Android Example Jetpack Compose)
Using generated a11y metadata with Jetpack Compose
Kotlin/Jetpack Compose
Composable
fun ProductCard(product: Product) {
Column(
modifier = Modifier.semantics {
contentDescription =
product.a11y.templates.summary
}
) {
Text(product.name)
Text("$" + product.price)
}
}
Key Features
• Uses generated a11y.templates.summary field
• Direct semantic mapping from API
• Consistent with schema definition
Accessibility Benefits
• Screen readers get meaningful hints
• No manual string building needed
• Platform agnostic implementation

22. iOS Example SwiftUI
Using accessibility metadata in SwiftUI components
SwiftUI Code
SwiftUI automatically uses the
a11y.templates.summary for Voice
Over announcements.
Provides consistent
accessibility across all
Apple platforms.
struct ProductView: View {
let product: Product
var body: some View {
VStack(alignment: .leading) {
Text(product.name)
.font(.headline)
Text("$(product.price)")
.font(.subheadline)
}
.accessibilityLabel(Text(product.a11y.templates.summary))
}
}

23. Web Example React
Using a11y metadata in React components with ARIA attributes
React Component
React components can consume a11y
metadata directly through aria-label
attributes.
The a11y.templates.summary
provides a consistent, screen
readable summary for the entire
component.
function ProductCard({ product }) {
const { name, price, a11y } = product;
return (
<div aria-label={a11y.templates.summary}
role="group">
<h3>{name}</h3>
<p${price}</p>
</div>
);
}

24. Benefits & Impact
What you get when accessibility becomes part of your API contract
Single Source of Truth Removes Brittle Client Logic
Dynamic Per Instance Summaries Optional Field Level Nuance
Result: Consistent, accessible experiences across all platforms with less developer effort

25. Ownership & Considerations
Key questions and strategies for successful implementation
Who Owns the Directives?
1 Product + Design collaboration
Define semantic meaning and user experience
2 Backend engineers
Implement directives and resolvers
3 Combination
Collaboration of cross-functional teams
Missing Metadata Strategy
Sensible Fallbacks
Use field names as fallback labels when a11y
metadata is missing
Monitoring
Track missing a11y metadata and report gaps
Gradual Adoption
Start with critical fields, expand coverage over
time

26. Localization Strategy
Template per Locale
Use locale-specific templates in schema
Server-Side Injection
Inject localized strings at runtime
Deferred Loading
Load translations on demand
Versioning & Compatibility
Backward Compatibility
New directives are optional, existing clients
continue to work
Schema Evolution
Add new metadata fields without breaking
changes
Feature Flags
Enable/disable a11y generation per client
Ownership & Considerations
Key questions and strategies for successful implementation

27. Thank You!
Questions? Let's continue the conversation
github.com/vanessamj99/GraphQL-a11y
LinkedIn
Portfolio
#a11y #APIs
Vanessa Johnson - Android Engineer @ The New York Times
GitHub