Appendix
Reference material compiled by the Heuristic Order. Intended for use during active dungeon construction and retrospective audits. Not required for enjoyment of the main volume; essential for survival in the field.
account_tree I. The Classification System
The Heuristic Order spent eleven sessions debating the classification framework before agreeing on the current system. Two factions remain dissatisfied. This is considered a success.
swords II. Challenge Rating Methodology
Challenge Rating represents the combined implementation and maintenance burden of a creature in a production dungeon. It is not a measure of the creature's value — a CR ¼ Button is more consequential than a CR 8 Data Table in most dungeons — only its complexity.
Ratings are calculated across four axes, each scored 0–2, for a maximum of 8:
<button> scores 0. A full virtual-scroll data grid scores 2.role="status".| CR | Rating | Typical Specimen | Notes |
|---|---|---|---|
| CR ¼ | 1–2 / 8 | The Button | Native element handles most complexity. Primary failure mode is impersonation by a div. |
| CR ½ | 2–3 / 8 | The Tooltip, The Skeleton Loader | Simple in concept; accessibility requires attention. Both are frequently deployed incorrectly. |
| CR 1 | 3 / 8 | The Toast | Non-trivial animation and live region handling. Error variant frequently misused. |
| CR 2 | 3–4 / 8 | The Accordion | Accessible animation presents genuine technical challenge. Exclusive mode adds complexity. |
| CR 3 | 4–5 / 8 | The Dropdown | Custom implementations require significant ARIA. Browser autonomy creates design tension. |
| CR 4 | 5–6 / 8 | The Modal | Focus trap, return focus, scroll lock, and overlay all require correct implementation simultaneously. |
| CR 8 | 7–8 / 8 | The Data Table | Maximum observed score. Requirements expand over time; no known ceiling has been documented. |
masks III. Known Imposters
The following creatures present as legitimate interface components but lack the semantic properties that make the genuine article functional for all users. They are distinguishable from their authentic counterparts only by testing with a keyboard or screen reader — a test that is not performed often enough.
<div> or <span> styled to resemble a button. Has an onClick handler. Does not respond to Space or Enter. Does not receive focus without tabindex="0". Does not announce itself to screen readers without role="button". Cannot be disabled without additional logic. Encountered in approximately 34% of audited dungeons. The Heuristic Order considers this figure conservative.
<div> that navigates on click but is not an <a> element. Does not open in a new tab via middle-click. Does not appear in the browser's link list. Cannot be copied as a URL. Screen readers do not identify it as a navigational element. Often found cohabiting with The Div-Button in dungeons whose summoners discovered JavaScript before they discovered HTML.
<table> used for visual grid layout rather than tabular data. Predates CSS Grid and Flexbox. Announces its row and column structure to screen readers, which is deeply confusing when the structure has no semantic meaning. Considered extinct in new construction; still encountered in dungeons built before 2010 and never migrated. Treat as a heritage specimen.
placeholder text. The placeholder vanishes the moment the user begins typing, leaving them unable to verify what the field expects. Screen readers do not consistently announce placeholder text as a label. Encountered constantly. Defended with the argument that it "looks cleaner." The Order does not recognise this defence.
:hover with no keyboard or touch equivalent. Inaccessible by definition on touch devices and to keyboard users. Frequently combines with The Div-Button as the menu items. A common finding in dungeons whose navigation was designed in 2008 and considered "good enough" ever since. It is not good enough.
title attribute as a Tooltip. Browser-rendered, inconsistently styled, inaccessible on touch, not keyboard-triggerable, and visually indistinguishable from a browser UI element. The genuine Tooltip's oldest and most persistent ancestor. Still found on icon buttons across the entire Codebase. The Order has issued a formal notice of concern. Nobody has read it.
accessibility IV. The Accessibility Codex
The ARIA incantations required across the volume, consolidated for reference. To speak these words incorrectly is to speak them to no one. The native element is always preferred; ARIA is the remedy when native is not possible.
Roles
| Role | Applied To | Effect | Appears In |
|---|---|---|---|
| role="button" | Non-button interactive elements | Announces as a button to screen readers. Does not grant keyboard activation — that requires JavaScript. | Div-Button imposter |
| role="dialog" | Modal container | Announces as a dialog. Screen readers shift into forms mode. Requires aria-labelledby pointing to the dialog heading. | The Modal |
| role="tooltip" | Tooltip container | Identifies the element as a tooltip. Must be referenced from the trigger via aria-describedby. | The Tooltip |
| role="listbox" | Custom dropdown list | Marks the option container. Must contain elements with role="option". Required only for custom implementations. | The Dropdown |
| role="option" | Each item in a listbox | Marks individual selectable items. The selected option receives aria-selected="true". | The Dropdown |
| role="status" | Toast container (non-urgent) | Announces content politely — after current speech finishes. For success and informational messages. | The Toast |
| role="alert" | Toast container (urgent) | Announces content immediately, interrupting current speech. For error messages only. Do not overuse. | The Toast |
| role="region" | Accordion panel | Marks expandable content as a landmark region. Requires aria-labelledby pointing to the header. | The Accordion |
| role="grid" | Custom data table | Required when table includes interactive cells. Use role="row", role="columnheader", role="gridcell" throughout. | The Data Table |
States & Properties
| Attribute | Values | Use | Appears In |
|---|---|---|---|
| aria-expanded | true / false | Communicates open/closed state of a trigger controlling a collapsible region. | Modal trigger, Accordion header, Dropdown trigger |
| aria-controls | ID of controlled element | Associates a trigger with the element it shows/hides. | Accordion header, Dropdown trigger |
| aria-labelledby | ID of labelling element | Associates a region or dialog with its visible heading. | Modal, Accordion panel |
| aria-describedby | ID of describing element | Associates an element with supplementary description, such as a Tooltip. | Tooltip target, form fields |
| aria-haspopup | listbox / dialog / menu | Announces that activating an element will open a popup of a specific type. | Dropdown trigger, Modal trigger |
| aria-activedescendant | ID of focused option | Tracks the visually focused option in a listbox when DOM focus stays on the container. | The Dropdown (custom) |
| aria-sort | ascending / descending / none | Communicates current sort state on a column header. | The Data Table |
| aria-checked | true / false / mixed | "mixed" is the indeterminate state for the select-all checkbox when some but not all rows are selected. | The Data Table |
| aria-hidden | true | Removes an element from the accessibility tree entirely. Use on Skeleton Loaders and decorative elements. | The Skeleton Loader |
| aria-live | polite / assertive | Marks a region whose content updates should be announced. "polite" waits; "assertive" interrupts. | The Toast, The Skeleton Loader replacement region |
| aria-busy | true / false | Signals that a region is in the process of loading. Set to true during skeleton state; remove when content arrives. | The Skeleton Loader |
| aria-modal | true | Informs assistive technologies that content outside the dialog is inert. Supplements, does not replace, DOM inertness. | The Modal |
dictionary V. Glossary
Terms used throughout this volume, defined on the Order's own terms. The definitions are not universally agreed upon. They are the definitions this volume uses.
The entirety of software from which interface creatures emerge. Not a physical place. Experienced differently by those who navigate it and those who build it.
The DungeonA specific interface — a page, an application, a screen. A dungeon may contain many creatures. Its quality is determined by the care of its construction and the wisdom of its summoners.
The SummonerA designer or engineer who instantiates a component. Responsible for the creature's correct implementation and any harm it causes. "The component was in the design system" is not a defence.
The Heuristic OrderThe scholarly body that compiled this volume. Membership is unverified. Positions are strongly held. The Order meets quarterly, argues constantly, and reaches consensus occasionally.
Native ElementAn HTML element provided by the browser — <button>, <select>, <dialog>, etc. — that carries built-in behaviour and accessibility properties. Preferred over all custom implementations.
A technique that confines keyboard navigation within a bounded region — typically a Modal — for the duration of that region's presence. Correctly implemented: an accessibility feature. Incorrectly implemented: a cage.
A composite score reflecting the implementation complexity, accessibility burden, misuse likelihood, and edge case density of a creature. See Section II. Not a measure of value.
The ImposterA non-semantic element styled to resemble a legitimate component. Indistinguishable visually; detectable immediately by keyboard or screen reader. See Section III.
Perceived PerformanceThe subjective impression of an interface's speed, which may differ significantly from measured performance. The Skeleton Loader manages perceived performance. The Spinner does not.
The Pest VariantA subspecies that appears uninvited, in contexts that do not justify it, and provides negative value to the user. The Newsletter Modal is the type specimen. Pest variants exist in most creature families.
Live RegionA DOM region marked with aria-live whose content changes are announced by screen readers. The mechanism by which Toasts, loading completions, and dynamic updates reach users who cannot see them.
The implicit agreement between an HTML element and the user: a <button> performs an action; an <a> navigates; a <table> presents tabular data. Violating this contract has consequences only for the user.