Prototype spec: lint, rejection and examples¶
Part of the agent-authored prototype specification.
Placeholder lint (#15444)¶
A successful show or patch returns placeholderFindings when a repeat or state placeholder sits
in a field that does not bind it, so it would be drawn literally. It is advisory, host-only and
never refuses a show. Each finding names the field path (for example root.children[0].label),
the placeholder as authored and a detail. The output keeps 50 findings, and
placeholderFindingsTotal reports the full count when it is capped.
- A repeat placeholder (
{index}, or{alias.field}for an enclosingrepeat.as) in a text field that is not in the bindable set, such aschip.labelorbadge.text. Fields that bind (button.label,topAppBar.title,searchBar.placeholder, andtextnodes) are not reported. - A
{key}state placeholder naming a declaredstatekey inchip.label,badge.text,textField.placeholderorsearchBar.placeholder. Only atextnode reads{key}from state. Other fields are left alone because a renderer may bind them beyond the contract.
To show a bound value there, use a text node next to the field.
Accessibility lint (#14126)¶
A successful show or patch returns accessibilityFindings: an advisory, host-only lint of the
component-expanded spec sent to the device. It never refuses a show and needs no device capability.
Each finding names a rule, the node path and a detail. The output keeps 50 findings, and
accessibilityFindingsTotal reports the full count when it is capped.
| Rule | Finds |
|---|---|
unlabeled-control |
A node with onTap, onLongPress or onDoubleTap, or an iconButton, fab, switch, checkbox, slider or select, with no contentDescription, label, text, spans, headline or title on itself or a descendant. |
unlabeled-image |
An image or icon with a testTag but no contentDescription. An untagged, non-tappable one without a description is decorative: the renderers hide it from accessibility, so it is not reported. |
unlabeled-text-field |
A textField or searchBar with no label, placeholder or contentDescription. |
low-contrast |
A text node with an authored style.color below WCAG AA against the nearest background the host can resolve: 4.5:1, or 3:1 for large text (textSize 24 or more, 18.66 or more at fontWeight 700, or a display/headline textStyle). It is checked in light and dark, or only the mode theme.mode pins; mode names the failing one, value the ratio. |
small-touch-target |
A tappable node or control whose authored width, height, maxWidth or maxHeight is under 48dp (44pt on iOS); value is the smallest side. Sizes left to layout are not checked. |
transition-without-visible-when |
A non-stack node with a transition but no visibleWhen: nothing ever enters or exits, so the transition never runs. |
Colours resolve on the host as the renderers do: a hex value, a {light, dark} pair, or a role
from the Material 3 baseline scheme with theme.colors overrides (flat, then per mode). A
theme.colors.seed or source: device makes the device derive its own scheme, so only the roles
the spec overrides are known then, and text using any other role is not checked. The background
starts at the surface role and follows authored style.background values, compositing
translucent ones. A gradient, a style.alpha, or a component that paints its own surface
(card, dialog, bottomSheet, snackbar, topAppBar, bottomNav, tabBar, button, fab,
chip) makes the background unknown. The lint then skips contrast. styleWhen overrides are not
evaluated.
Pseudo-locale (#14126)¶
show takes pseudoLocale: true. The device receives a copy of the spec in which every text,
label, placeholder, headline, title, supporting, supportingText, trailingText, check message and span text is
accented, padded by about 40% and wrapped in [ ]. Truncation and clipping then show without a
translation. {key}, {data:/pointer} and {item.field} bindings are left intact, as are
contentDescription, state, data, request bodies, emit context and payload, repeat and option values. The authored
spec is what status, patch and the accessibility lint see, so patch ops (other than a
replaceNode) edit the device copy and a replaceNode sends authored text. A linkify text keeps its mention, hashtag and URL tokens as written and takes no [ ]
wrapper, so links stay detectable. Stack screen and component names are never treated as spec
fields. Each show states the
option afresh.
Every starter template passes this lint with zero findings, pinned by the template gallery test.
test/fixtures/prototype-a11y/ holds one fixture per rule beside a clean spec.
On-device audit and RTL (#14126)¶
The wcag engine of accessibilityAudit (WcagAudit) reads the accessibility tree the Compose renderer projects, so it
sees prototype nodes through that projection, not the spec:
- A text field’s
labelis a child text node with no class, drawn inside theEditText. The audit counts a classless text node as a label candidate, so a labelled field is not reported. - A tappable container with no children keeps its node kind as
content-desc(“box”), and an icon button reads as its icon name. These are selector handles (seeprototypeContentDescription), soWcagAuditcannot tell an authored label from the fallback: it reports neither a missing label on such a node nor a missingcontentDescriptionon an icon button. Theunlabeled-controllint is the check for them. - An untagged or non-tappable
imageoriconis not interactive, soWcagAuditdoes not report a missing description; theunlabeled-imagelint does. - Compose enforces a 48dp minimum interactive size, so a tappable node authored smaller still
measures 48dp on the device and
WcagAuditreports no small target. Onlysmall-touch-targetsees the authored size. - Low contrast and an unlabeled
EditTextare reported on device as in a native app.
Under changeLocalization with textDirection: "rtl" for the host app, an Android row of
weighted and unweighted children lays out right to left. On iOS the audit is the XCUITest
accessibilityAudit.
Rejection paths and deterministic first error¶
Paths omit a leading $ for ordinary root members: root.children[1].style.color.
Array indices use brackets. Non-identifier keys use JSON-quoted brackets, e.g.
root["bad.key"]; top-level equivalents start with $["bad.key"]. A whole
input, malformed JSON, or spec byte error uses $. Missing/unknown discriminator
errors end in .type. Paths identify the rejected input, before any defaults.
Both walkers use the same sequence:
- Raw UTF-8 byte limit, then strict JSON parsing (syntax error at
$). - Depth-first structural walk. At a node entry, check node count, node depth, then image-use count. Nav image uses are checked at item entry. Container depth is checked at container reference entry. At a tagged object, check its discriminator first.
- At each object, visit the union of present and declared keys in ascending
UTF-16 lexicographic order, independent of JSON insertion order. Unknown keys
fail at their own path; missing required keys fail there too. Arrays visit
increasing indices, with length checked first and uniqueness after each item.
Selection binding exclusivity is checked after its fields, at
.pagerfor both/neither. An empty selector fails at.selector. Container exclusivity fails at.elementIdafter its fields are checked. - After structure passes, find duplicate pager IDs in node preorder (second
ID fails at
.id); then resolve node pager references in preorder, then action pager references in encounter order. Finally check initialized text/nav state binding types in node preorder, then existing sheet state types in node preorder. - Decode typed models. Any schema/model disagreement is an internal contract
failure at
$, never successful partial content.
Only the rule table is shared; walkers and model decoders are independent. Neither implementation parses Zod or kotlinx.serialization exception messages. Human error messages describe the failure; exact path parity is the shared contract.
The validator measures JSON supplied as an already-decoded TypeScript value as compact JSON, while string input measures original bytes. It accepts only JSON-representable values. Authors must avoid duplicate JSON object keys. Standard JSON decoders retain the last value. They are not unknown fields.
Worked examples¶
Full-screen variants with pager tabs¶
{
"id": "variants",
"window": { "placement": { "type": "fullscreen", "scrim": "#80000000" }, "opacity": 80 },
"state": { "query": "", "open": false },
"root": {
"type": "column",
"safeAreaPadding": { "edges": ["top", "bottom"], "types": ["systemBars", "cutout", "ime"] },
"children": [
{
"type": "tabBar",
"pager": "pages",
"items": [
{ "label": "Original", "icon": "home" },
{ "label": "Edited", "image": "variant-b" }
]
},
{
"type": "pager",
"id": "pages",
"children": [
{
"type": "scroll",
"axis": "vertical",
"child": { "type": "text", "text": "Page {page} of {pageCount}" }
},
{ "type": "image", "asset": "variant-b", "contentScale": "fit" }
]
},
{ "type": "textField", "stateKey": "query", "placeholder": "Feedback" },
{
"type": "text",
"text": "Next",
"onTap": [{ "type": "setPage", "pager": "pages", "page": "next" }]
},
{
"type": "bottomSheet",
"openWhen": { "key": "open", "equals": true },
"detents": ["half", "full"],
"child": { "type": "text", "text": "Details" }
}
]
}
}
Bottom window sheet with state navigation and horizontal scrolling¶
{
"id": "choices",
"window": { "placement": { "type": "sheet", "edge": "bottom", "height": 240 } },
"state": { "selected": 0 },
"root": {
"type": "column",
"children": [
{
"type": "scroll",
"axis": "horizontal",
"child": {
"type": "row",
"children": [
{
"type": "text",
"text": "Save",
"onTap": [{ "type": "emit", "name": "save", "payload": { "variant": "A" } }]
},
{ "type": "spacer", "style": { "width": { "dp": 16 } } },
{
"type": "icon",
"name": "favorite",
"onTap": [{ "type": "setState", "key": "selected", "value": 1 }]
}
]
}
},
{
"type": "bottomNav",
"stateKey": "selected",
"safeAreaPadding": { "edges": ["bottom"], "types": ["systemBars"] },
"items": [
{ "label": "Home", "icon": "home" },
{ "label": "Favorites", "icon": "favorite" }
]
}
]
}
}
Floating anchored replacement¶
{
"id": "button-preview",
"window": {
"placement": { "type": "floating", "gravity": "topStart", "offset": { "x": 24, "y": 120 } },
"opacity": 50
},
"root": {
"type": "box",
"anchor": { "type": "element", "selector": { "testTag": "buy" }, "alignment": "cover" },
"style": { "background": "#2255CC", "cornerRadius": 12 },
"children": [{ "type": "text", "text": "Buy now", "onTap": [{ "type": "dismiss" }] }]
}
}
The committed doc-example-3 fixture is this example verbatim. The renderer refuses an unresolved
element anchor, so the screenshot gallery substitutes a fixed resolved bounds anchor (same
alignment) before rendering; only the host resolves selectors.
Shared fixtures¶
The TypeScript and Kotlin suites enumerate the same test/fixtures/prototype-spec/valid and invalid
files, assert nonempty directories and require coverage of every node, action and placement. Invalid files
wrap {spec, expectedPath}. The byte limit has no fixture: each suite generates its own input and checks
the exact byte boundary (whitespace included) and the emit payload boundary. Fixture and contract files are
pinned to LF for Windows; no binary assets are included. The worked examples above are committed as
doc-example-N.json fixtures and test/parity/prototypeSpec.test.ts asserts they match this page.
Reference concept slices live in test/fixtures/prototype-concepts/<concept>/. Each holds today.json (a
whole concept app written only with capabilities Android and iOS both advertise, with literal data
in place of a mock backend). It also holds concept.json ({issue, name, capabilities}, the gate capabilities the
three strict policies must derive) and a README.md listing every required capability and each
workaround or dead end with its spec path. The TypeScript, Kotlin and Swift suites load every concept
directory; TypeScript also requires a testTag on every interactive node, a spec id of
<concept>-today and zero static accessibility lint findings.