Build an operable interface from document structure

A document-card page looks orderly on a wide screen, but its titles overflow on a narrow screen and keyboard users cannot activate Save. A screenshot shows one state; operability requires structure, layout, and interaction to work together. HTML supplies meaning and native behavior, while CSS arranges the boxes.

The independent case contains search, category filters, document links, and save buttons. Establish understandable document structure before decoration. The offline example checks a small control contract without rendering a page.

Choose semantics from the content

Use meaningful regions and a heading hierarchy so readers can locate navigation, main content, and filters. Each document entry contains a title, description, category, and actions. Choose heading levels for document relationships, then control visual size with CSS.

Use a link to open a document and a button to change saved state. Native controls already provide semantics and keyboard behavior. Rebuilding them with clickable divs adds focus, role, and keyboard responsibilities. Links need actual destinations, buttons need understandable names, and icon-only controls need appropriate accessible names.

Associate the search input with a label. Placeholder text does not replace that label, and IDs must be unique. An error should identify the invalid input and explain its repair rather than only change border color. Decorative images should avoid redundant announcements; informative images need a description suited to their purpose.

Design the available box space

Content, padding, borders, and margins affect layout. An explicit box-sizing policy reduces width surprises. Consider container spacing, card limits, and long-text wrapping. Fixed heights can clip longer translations or enlarged text.

Start with normal document flow. Flexbox suits distribution along an axis, such as an action row. Grid suits row-and-column relationships, such as a card collection. Determine the minimum useful content width before choosing transitions between several columns and one column.

Give images suitable intrinsic dimensions or an aspect ratio so the browser can reserve space before loading. Other content changes can still shift layout. Test long URLs, unbroken titles, absent categories, and failed images instead of assuming one sample represents all inputs.

Understand rendering before measuring it

The browser forms a DOM, applies CSS rules, computes layout, and paints content. Changes can trigger these stages, but cost depends on the change and browser optimizations. Do not assign identical cost to every CSS mutation or guarantee animation performance from an attribute name.

Reading dimensions after each mutation in a loop may force repeated layout work. Group measurements and updates where practical. A document grid usually does not require JavaScript to calculate every card's position; browser layout tools can handle the flow.

Inspect actual boxes and computed styles during diagnosis. A clipping problem can originate in a parent width or fixed height rather than typography. After changing a constraint, retest nearby viewport sizes and enlarged text.

Verify keyboard behavior in a browser

Tab order should follow a sensible reading and action order, with a visible focus indicator. Avoid positive tabindex values as a substitute for sensible DOM order. Saving should work through native keyboard interaction, and filtering should not unexpectedly lose focus.

Make feedback discoverable. Show loading, retain input after failure, provide retry, and explain an empty result. Dynamic announcements require a suitable mechanism and frequency; announcing every keystroke can overwhelm users.

Accessibility also includes contrast, zoom, touch targets, reduced-motion preferences, and actual assistive-technology behavior. Automated checks expose some structural defects but do not replace keyboard and screen-reader testing. Passing one rule does not establish full WCAG conformance.

Check a minimal control contract

The example represents controls with an ID and name. It checks unique IDs, nonempty names, and existing label targets. Actual HTML associations, roles, and accessible-name computation involve more rules. This model demonstrates executable structural constraints.

controls = [{"id": "email", "label": "Email"}, {"id": "submit", "label": "Save"}]
ids = [c["id"] for c in controls]
assert len(ids) == len(set(ids))
assert all(c["label"].strip() for c in controls)
label_targets = {"email"}
assert label_targets <= set(ids)
print(ids)

The output is ['email', 'submit']. The assertions reject duplicate IDs, blank names, or a missing label target. Email is only a synthetic control identifier; no address is entered or validated. Passing the checks establishes nothing about contrast, visible focus, or screen-reader usability.

Adapt the controls to search and save, then represent independent buttons on two cards. A name such as "Save: transaction basics" identifies the action's object more clearly than identical "Click here" buttons. Keep these names consistent with the real interface.

Saved state also needs a meaningful representation. A color change alone does not tell keyboard or assistive-technology users what changed. Choose a suitable state attribute or clear text according to the control's meaning. If submission blocks repeated action, explain the reason and recovery condition.

Keep the title link and save button as separate actions. Avoid making an entire card a button with interactive elements nested inside it. A clickable icon does not establish valid structure. Consider text selection, link-opening behavior, and touch interaction when choosing the action areas.

Exercise: support several ways to operate the page

Define regions and headings, then implement links, buttons, and a labeled search field. Include narrow screens, long titles, image failures, empty results, loading, and errors. Specify the user's next available action in each state.

Acceptance requires keyboard completion of search, document opening, and saving; visible focus in a sensible order; no body-text overflow on narrow screens; reachable controls with enlarged text; and visible document titles after image failure. The offline audit must reject duplicate IDs and missing label targets. The browser report must state which contrast and assistive-technology checks were actually performed, rather than claim complete accessibility from a synthetic audit.