Appendix C - 14. `a11y_` prefix convention

The Structure of a11y_ prefix convention — its shape at a glance:

Each inserter names its artifact by the rule and records it in the registry. The validator reads the registry — and can also recognize any invisible insert by its prefix — so every registered insert is covered.

flowchart LR
  I1[Inserter A] -->|a11y_ + Record| Reg[(Insert registry)]
  I2[Inserter B] -->|a11y_ + Record| Reg
  Reg --> V{Insert validator}
  V --> Pass([covered])
  V --> Fail([unregistered → flagged])

Accessible description: two inserters each name their artifact with the reserved prefix and record it in the insert registry. The validator reads the registry and covers every registered insert; an insert that was never recorded is flagged.

Projected from the catalogue entry provenance-and-attribution / a11y_ prefix convention.

On this page: Intent · Motivation · Applicability · Structure · Sample Code · Consequences · Example use within DocAble · Related Patterns

Intent — A reserved naming prefix that marks tool-inserted, invisible-to-author artifacts (user-visible insertions keep ordinary names), so inserted content is distinguishable from authored content and a validator can cover it by prefix (our instance: the a11y_ prefix + InsertedContentValidator).

Motivation

The tool inserts content: alt text, tags, off-canvas scaffolding. Mixing tool-inserted content with author-written content risks two failures: presenting invisible scaffolding as if the user wrote it, or an insert that isn't tracked and so isn't validated. The failure is untracked or mislabelled inserted content, and it recurs per inserter and per insertion site.

Applicability

The naming convention (the three-way rule) applied at every insertion site.
A registry inserters record into, and a validator that reads it.

Structure

The Structure diagram appears at the top of this page.

Sample Code

Two parts make coverage automatic: a naming rule that marks an invisible insert by a reserved prefix, and a registry every inserter records into. The validator then walks the registry, so a new inserter is covered the moment it records — no hand-maintained list to drift.

PREFIX = "a11y_"   # reserved marker for invisible-to-author inserts

def insert_name(base: str, *, visible: bool, spec_name: str | None = None) -> str:
    if spec_name is not None:
        return spec_name             # spec-mandated names win
    return base if visible else f"{PREFIX}{base}"

class InsertRegistry:
    def __init__(self): self._records: list[dict] = []
    def record(self, name: str, kind: str) -> None:
        self._records.append({"name": name, "kind": kind})
    def all(self) -> list[dict]: return self._records

def validate_inserts(reg: InsertRegistry) -> list[str]:
    # every invisible insert must carry the prefix; the registry is the coverage set
    return [f"insert '{r['name']}' is invisible but unprefixed"
            for r in reg.all() if r["kind"] == "invisible" and not r["name"].startswith(PREFIX)]

Consequences

Adherence is partly discipline. A mis-named or unregistered insert escapes coverage until caught.
Spec-mandated names are exceptions to the prefix rule (by necessity), a small carve-out to track.
Every inserter must call registry.Record — the auto-coverage only works if the registration habit holds.

Example use within DocAble

The a11y_ prefix convention and its per-site corollaries.
registry.Record(...) + the InsertedContentValidator (automatic coverage of registered inserts).

Consumer — the InsertedContentValidator reads the registered inserts (naming + registration are what it depends on).
See also (sibling) — remediation-verbs: both bound the remediator's move-space; this one bounds how inserted content is named and tracked.