Skip to content
Sonenta

Surfaces

The concept

Section titled “The concept”

A surface is a content variant layered onto a key's base value. Where the base value is the main text, surfaces carry variants served according to context. They live on the key, in the content layer, are translated like the values, and served by the CDN, so received by your app without any code change.

Sonenta handles two orthogonal surface dimensions (a single key can carry both):

1. Device / channel surfaces

Section titled “1. Device / channel surfaces”

A variant of the text depending on the display device or channel. The base value serves one context, surpluses override it for the others.

  • Built-in: desktop, mobile, tablet.
  • Custom: you can create your own surfaces (for example watch, tv, kiosk). A surface slug is lowercase (letters, digits, _, -), 1 to 40 characters. The built-in surfaces are enabled or renamed; the custom ones are free-form.

Example: a long label on desktop, a short version on mobile. The Sonenta site itself uses this (the top-bar button text has a mobile variant).

2. Accessibility surfaces

Section titled “2. Accessibility surfaces”

A fixed set of 4 layers intended for assistive technologies, distinct from the visible text:

  • aria_label: the accessible name of an interactive element.
  • alt_text: the alternative text of an image.
  • screen_reader: text reserved for screen readers (sr-only).
  • plain_language: a plain-language (FALC) version of the value.

The detail of the accessibility model (key-types, cognitive score, flow, conformance) is on the Accessibility page.

Configuration

Section titled “Configuration”
  • Accessibility surfaces: declared in SonentaConfig.a11ySurfaces.
  • Device surfaces: declared in the SDK config (for example the surfaces list of @sonenta/astro).
  • sonenta-surface agent: recommends and enables surfaces (device and accessibility), config-only, 0 credit, non-destructive (create / update / delete_surface). It configures surfaces; it does not write the accessibility values (it hands off to sonenta-a11y) and does not manage regional variants (those are languages). Modes: audit, recommend+apply, handoff.

SDK side

Section titled “SDK side”

Accessibility surfaces are read via dedicated accessors (t.aria, t.alt, t.a11y) and the global FALC toggle for plain_language. Device surfaces are resolved by the SDK according to the display context.