Accessibility Self-Review Questionnaire for VC Rendering Methods v1.0

Accessibility Self-Review of Verifiable Credential Rendering Methods v1.0

The following is an Accessibility Self-Review for Verifiable Credential Rendering Methods v1.0.

This specification describes an extension mechanism for the Verifiable Credential Data Model with which an issuer associates one or more render templates with a verifiable credential, so that a holder or verifier can present that credential through a visual, auditory, or (in the future) haptic medium.

Unlike most Verifiable Credentials Working Group deliverables, this specification is directly about rendering, and we expect it to warrant closer accessibility review than a pure data model would. It defines three render suites: card, a declarative JSON template producing a standardized structured output that a wallet renders in its own UI; html, in which an issuer supplies an HTML fragment carrying its own CSS and JavaScript that executes to produce the rendering; and nfc, which emits a binary payload over a wireless connection. It also defines an outputPreference object through which an issuer expresses an intended accessMode, media type, and iframe dimensions.

We have identified several accessibility concerns, listed at the end of this review, and we would welcome APA's guidance on all of them, particularly the card render suite (which is meant to be minimal and defer much of the a11y to the digital wallet), and html render suite, where issuer-supplied code produces output directly.

The following self-review question categories were analyzed and resulted in the following answers:

• The technologies DO allow for visual rendering of content
  • The html render suite renders a credential by executing an issuer-supplied HTML/CSS/JavaScript fragment inside a sandboxed iframe. The card render suite produces a standardized JSON output (name, description, icon, theme, fields, validFrom, validUntil) that the consuming wallet renders in its own card UI, so accessibility of the final presentation there rests with the wallet rather than the issuer.
  • The specification does not currently place any accessibility requirement on the HTML a template emits. It neither requires nor recommends that template code produce semantically structured, keyboard-operable, or contrast-adequate output. Should we say anything here, or should we just presume that they know to do that because they're using HTML?
• The technologies DO provide author control over color
  • The card render suite's theme object defines primaryColor and accentColor, either as literal values or as JSON Pointers into the credential. The specification places no constraint on the contrast ratio between these colors, or between them and the text a wallet renders over them, so an issuer can specify a theme that fails WCAG contrast requirements.
  • The html render suite gives an issuer complete control over color through the template's CSS, with no constraint at all.
  • Neither suite defines a way for a rendering to respond to a user's platform color preferences, such as high contrast, forced colors, or dark mode, should we enable something like that to flow through to the template? If so, what do you suggest we do? Is there a certain type of object we could construct and pass through?
• The technologies DO NOT provide features to accept user input
  • No render suite defines an input mechanism. Note, however, that the html suite executes arbitrary template JavaScript in the iframe, so a template can create interactive controls that the specification does not describe or constrain; see "user interaction features" below. Should we try to restrict input on the iframe? We are concerned that we might stifle innovation if we do that.
• The technologies DO provide user interaction features (indirectly, via the html render suite)
  • The specification defines exactly one interaction contract, between the template and the host page: the template calls window.renderMethodReady() to signal that rendering is complete, or window.renderMethodReady(new Error(...)) to signal a rendering error, over a MessageChannel established by the wrapper code. The host page uses the resulting renderPromise to decide when to display the iframe or show an error.
  • Beyond that, because the template's JavaScript runs, a template can introduce interactive UI (expandable sections, tabs, hover-revealed detail) inside the iframe. The specification says nothing about focus management, keyboard operability, or how such controls fit into the host page's focus order. Should we say something here? If so, what could we say as we feel like we might be duplicating what's in WCAG.
  • The ready/error contract itself has an accessibility dimension: the specification says an error message is displayed to the user, but does not say how, nor whether the completion or failure of rendering is announced to assistive technology. A rendering that never signals ready leaves the host page in an indefinite state with no defined user-facing behavior. Is this an issue? Anyone that authors iframes is in this situation, is there general language/guidance given to them by WCAG?
• The technologies DO define document semantics (indirectly, via the html render suite)
  • Do we need to say anything here? We felt like if we said something about document semantics, we'd just be repeating WCAG guidance for regular HTML page developers. Should we just say: All applicable WCAG guidance related to normal HTML pages applies here, or something to that effect?
• The technologies DO provide time-based visual media (potentially, via the html render suite)
  • The specification does not define time-based media, but nothing prevents an html template from producing animation, motion, or auto-updating content via CSS or JavaScript. The specification defines no mechanism for a user to pause, stop, or hide such content, and no requirement that a template honor prefers-reduced-motion.
  • The threat model addresses the most severe form of this directly. T4: Harmful Rendering Output records that a hostile template can drive a rapidly flashing or strobing pattern capable of triggering a seizure in a person with photosensitive epilepsy, or emit sudden loud or disruptive sound. Its first response is Accept, on the grounds that this is a condition of any rendering technology; its second, Reduce, advises deployers to favor constrained suites such as card, to honor platform accessibility settings limiting motion, flashing, and sound, and to review or transform output from untrusted template authors into a safe static form. We consider this the most serious accessibility and safety concern in the specification, and would particularly welcome APA's view on whether a Reduce/Accept posture is adequate or whether normative constraints belong in the specification itself. To what lengths should we go to protect individuals?
• The technologies DO provide audio (potentially, via the html render suite, and by design via accessMode)
  • The specification's abstract explicitly covers rendering a credential to a screen reader, and outputPreference.accessMode includes an auditory value, so auditory rendering is an intended use.
  • However, the specification defines no auditory render suite other than maybe html that generates audio. accessMode: ["auditory"] expresses an issuer's intent but there is no defined mechanism that realizes it: no audio template format, no text-to-speech guidance, and no defined relationship between an auditory intent and what a template actually produces. An html template can play audio through ordinary HTML, with no constraint on volume, autoplay, or duration, which is the mechanism T4 contemplates for sudden disruptive sound. Should we just use html as the auditory access mode, or would there be something better we could do here?
• The technologies DO NOT allow time limits
  • No render suite defines a time limit on reading, interacting with, or dismissing a rendering. The renderPromise has no specified timeout.
• The technologies DO allow text content
  • Both the card and html suites carry human-readable text. In card, the name, description, and each field's label and value are text, as are validFrom and validUntil. A render method also carries name and description properties describing the rendering itself, intended for use in a UI that lets a person choose among presentation modes.
• The technologies DO create objects that don't have an inherent text representation
  • The card suite's icon property references an image (URL or data URI) with no accompanying text alternative property. A wallet rendering a card has no defined source for alternative text; the name property is a reasonable fallback but is not specified as such. Should we use name as the fallback, or should we provide alt text for the images?
  • The html suite's outputPreference.mediaType contemplates transformation of a rendering into a non-text output, giving image and PDF conversion as examples. A rendering converted to a static image loses whatever text semantics the template had, and the specification says nothing about preserving a text alternative across that transformation, should it? Should we point at some WCAG guidance here instead?
• The technologies DO provide content fallback mechanisms, whether text or other formats
  • The strongest fallback mechanism is structural: renderMethod accepts one or more render methods, so an issuer can supply several alternative renderings of the same credential, and outputPreference.accessMode (visual, auditory, tactile, textual) lets each declare the modality it targets. An application can in principle select the render method matching a user's needs.
  • The specification defines no selection algorithm, no requirement that an issuer provide more than one modality, and no fallback behavior when no render method matches the user's needs or when the selected rendering fails. The render method's name and description are the only defined aid to a person choosing manually, and even those are probably not thought of as accessibility hints to the issuers/authors of the templates.
  • The card suite is itself a fallback of a kind: the specification notes that a wallet implementing it can display credentials of types it does not natively support, which keeps a credential renderable, and its declarative output is more amenable to accessible presentation than executing template code.
  • Beneath all render methods, the underlying credential's own data remains available, so an application can always fall back to a native rendering of the claims, but we don't expect many will implement that approach because there are many, many types of digital credentials out there.
• The technologies DO provide visual graphics
  • The card suite's icon references a graphic. The html suite's template can generate or embed graphics of any kind through HTML, CSS, and JavaScript. The specification neither renders nor manipulates graphics itself; it defines the environment in which template-produced graphics appear.
  • The outputPreference.style object lets an issuer state preferred width and height for the iframe. The specification does not say what happens when those dimensions conflict with a user's zoom level, text scaling, or viewport, and does not require the rendering to reflow or remain readable when they do. Reviewers may wish to consider whether issuer-specified fixed dimensions conflict with WCAG reflow and text-resize expectations. Do they? If so, what language does APA suggest?
• The technologies DO provide internationalization support
  • We go into this topics in great detail here: https://github.com/w3c/vc-recognized-entities/issues/98
• The technologies DO define accessible alternative features
  • outputPreference.accessMode is an explicit accessibility affordance, drawing its values (auditory, tactile, textual, visual) from the Accessibility Discoverability Vocabulary, and the ability to declare multiple render methods lets an issuer supply alternatives across modalities. The specification's abstract states the intent directly: rendering to a screen reader or braille output is in scope, and the introduction gives the example of an issuer providing an audio read-out for people with vision-related accessibility needs. That said, we don't hav eimplementers that are doing audio or tactile outputs yet. Should we leave that out of scope for now, or define something basic and hope some people start experimenting with in in the Candidate Rec phase?
  • The affordance is declarative only. accessMode is a hint an implementation SHOULD follow, there is no defined selection algorithm, and no render suite is defined for tactile or textual output. We would value APA's advice on whether accessMode is sufficient as an intent declaration, or whether the specification needs defined selection behavior and at least one non-visual render suite to make the alternative concrete. Would an inline data URL containing a mp3 or wav file be sufficient? Or are we depending on AI now to summarize to audio/text?
• The technologies DO provide content directly for end-users
  • A rendering is content a person perceives. The threat model models this explicitly as data flow F2: Observe Rendering, the flow by which the output of the render process reaches the holder or verifier who observes it, and identifies the holder (E2) and verifier (E3) as the humans on the receiving end.
• The technologies DO define an API (a narrow one)
  • The html render suite defines a small JavaScript surface: window.renderMethodReady(), provided to the template by the wrapper code, and the MessageChannel ready/error protocol between the wrapper code and the host page. This is a rendering-lifecycle signal rather than a user-facing API, but it is the point at which an application learns that a rendering is complete or has failed, and is therefore the natural place to hook an announcement to assistive technology. The specification does not require one. Should it?
• The technologies DO define a transmission protocol (the nfc render suite)
  • The nfc suite transmits a binary payload over a wireless NFC connection -- presumably WebNFC, but there are large user agent vendors that have not allowed the web platform to access NFC. Accessibility of NFC presentation, such as physically locating a reader, aligning a device, and knowing whether a tap succeeded, is a real concern for people with motor or vision impairments, and the specification defines no feedback mechanism for it. The render method's name, used in the specification's example as "Tap to send", is the only defined affordance for describing the interaction. We do have another spec, VC API, that defines an Interaction URL that the individual with accessibility needs can show and someone that has the ability could scan (as an alternative to NFC), though we don't think this is better (just different). In short, we don't know if we have to say much about NFC since it's an implementation detail that we have no control over (different spec).

Start with the accessibility concerns in this issue, then read the linked Verifiable Credential Rendering Methods specification and its T4 threat-model section. Identify the guidance or normative changes APA should address for the card and html suites, including fallback, interaction, media, and accessibility settings; done means the review questions have resolved recommendations or documented decisions.