Documentation acceptance test

This acceptance test evaluates the documentation as a reader would use it. Start from an existing framework application without reading Simurgh source. Follow only linked published pages, record the commands and observations, and fail the run when a required step needs undocumented knowledge.

Test setup

Run the journey once in React, Vue, and Angular. Use supported framework versions from the compatibility matrix, a clean working tree, keyboard access, and a browser with developer tools. Use package consumption for tasks 1–5 and a separate disposable application for the copied-source task.

Record the framework and Simurgh versions, package manager, browser, operating system, viewport, color scheme, text direction, reduced-motion preference, and test date. Pin exact package versions so another reader can reproduce the result.

1. Install one component

Follow Installation and the Button page. Install the active adapter and styles package, import Button from its component subpath, import button.css, and render a named button.

Pass when the application production build resolves both JavaScript and CSS, the button is keyboard focusable, and pressing Enter or Space activates it once. Fail for an undocumented dependency, aggregate-only import, missing recipe, or inaccessible name.

2. Customize its theme

Follow Theming. Override semantic primary, foreground, focus-ring, radius, and duration tokens after the recipe import. Activate light and dark modes with the documented selectors, then repeat in RTL and reduced motion.

Pass when the override wins without !important, focus remains visible, text contrast remains acceptable in both themes, logical layout follows direction, and reduced motion removes nonessential movement. Record contrast measurements and screenshots with the result.

3. Build and submit a form

Use the Form, Field, Label, Input, Checkbox, and Button pages. Build a labeled account form with one required text value and one optional checkbox. Submit invalid and valid data and inspect the resulting FormData.

Pass when errors are associated and announced, the first invalid control can receive focus, valid named controls submit the documented values, disabled controls are omitted, and a loading submit button prevents duplicate activation. Test keyboard-only operation and browser validation behavior.

4. Open an overlay

Follow the Dialog page and Overlay focus. Open a Dialog from a trigger, move through its controls, dismiss it with Escape and its close control, and repeat after scrolling.

Pass when focus enters the dialog, stays within the modal interaction, Escape closes it, focus returns to the trigger, the background is not operable while modal, and the surface remains usable at a narrow viewport and 200% zoom. Repeat in RTL, dark mode, and reduced motion.

5. Handle an event

Use the Checkbox page and its framework API table. Listen for the documented change contract, store the next value in application state, display that value in a live status region, and toggle by mouse and keyboard.

Pass when React’s callback, Vue’s emitted update, or Angular’s output fires once per activation with the documented value; controlled state stays synchronized; and the status is exposed without moving focus. Switching framework tabs must reveal an equivalent framework-native event example.

6. Update a copied component

Follow Updates and migrations. In a disposable application, run CLI initialization, add Dialog, make an identifiable local class customization, and commit or back up the file. Run diff, generate the newer source separately, perform the documented three-way review, and preserve the customization while adopting upstream behavior.

Pass when diff reports the intentional difference, the original edit remains recoverable, overwrite is never used without an inspected backup, accessibility and keyboard behavior are retested, and the adopted registry version is recorded only after review.

Framework-switch checkpoint

After each task, switch the documentation tabs from React to Vue to Angular. Verify that imports, props or inputs, events or outputs, content syntax, and native-attribute behavior use that framework’s conventions while preserving the same user-visible and accessibility outcome. Fail any tab that silently relies on syntax or APIs from another adapter.

First-time-reader comprehension checkpoint

Run this checkpoint from the home page in a fresh browser context without reading repository source. It is a documentation walkthrough, not a substitute for moderated research with new human users.

1. Identify styling status. Open the component overview and determine whether Native Select is native, structurally styled, or recipe styled. Pass when the gallery exposes the answer without opening implementation source.
2. Select the correct primitive. Find a fixed-option form control and distinguish Native Select, Select, and Combobox. Pass when comparison guidance explains the native, custom-listbox, and editable-filtering tradeoffs from the gallery journey.
3. Preview the real default. Open Select and inspect its Basic usage and Examples sections. Pass when the rendered result and framework-native source are available before the exhaustive API.
4. Install it. Find the package and CLI installation paths. Pass when the component page exposes pnpm dlx @simurgh-ui/cli add select, subpath imports, and optional recipe CSS without source-code inspection.
5. Choose a density. Follow Theming and identify comfortable, compact, and dense modes. Pass when the data-density scope, intended use, and control-size consequences are documented.
6. Customize semantic tokens. Identify the primary, foreground, ring, radius, and duration controls. Pass when import order and semantic overrides are shown without requiring selector archaeology or !important.
7. Verify accessibility modes. Locate the focus, RTL, and dark-theme instructions. Pass when a reader can state what to inspect and can switch the documentation theme using a labeled control.

On 2026-08-13, a fresh-context browser walkthrough passed all seven documentation-discovery steps. Filtering the gallery to native components matching “select” returned only Native Select; its card exposed status, behavior, keyboard complexity, framework availability, and comparison guidance. The Select page exposed installation before usage and kept React, Vue, Angular, and styling reference tables collapsed by default. The theme control applied light mode, while Theming and Accessibility & RTL exposed density, semantic-token, focus, direction, and dark-mode guidance. The walkthrough also found and corrected singular result copy from “1 components” to “1 component.”

This result validates findability and information architecture through an automated fresh-reader proxy. A release candidate should still include moderated observation with people unfamiliar with Simurgh, recording task completion, hesitation, wrong turns, and terminology questions.

Recorded acceptance result

The repository run on 2026-08-12 recorded the following evidence. CI evidence confirms that package entry points, styles, declarations, and documented fences build; the manual column remains the required browser/user observation and must be rerun for a release candidate.

Task	CI evidence	Manual evidence required	Result
Install one component	React, Vue, and Angular package quick starts bundle JavaScript and recipe CSS.	Keyboard activation and accessible name.	CI pass; manual release check required.
Customize its theme	Complete light/dark theme tokens and 20 contrast pairings are validated.	Visual focus, screenshots, RTL, zoom, and reduced motion.	CI pass; manual release check required.
Build a form	Adapter contracts and documented examples compile; form documentation is required for 18 controls.	Submission values, announcements, focus, and duplicate prevention.	CI pass; manual release check required.
Open an overlay	Adapter contracts, examples, and documentation browser tests cover overlay guidance.	Focus containment/restoration, scroll, zoom, and narrow viewport.	CI pass; manual release check required.
Handle an event	Generated API tables and examples validate callback, emit, and output declarations.	One event per pointer/keyboard activation and live status behavior.	CI pass; manual release check required.
Update copied source	CLI tests cover init, add, diff, preservation, and overwrite behavior.	Three-way review quality and retained local customization.	CI pass; manual release check required.
Switch frameworks	Every component page has parity documentation and compiled adapter examples.	Reader comprehension and equivalent task outcome in all adapters.	CI pass; manual release check required.

Do not convert “manual release check required” to a pass without recording the environment and observations. A fully green CI run is necessary but is not evidence that focus, contrast perception, screen-reader announcements, or reader comprehension were manually observed.

Published documentation browser observation

On 2026-08-12, the built documentation site was observed in the Codex in-app Chromium browser on Windows. The desktop viewport and a 390 × 844 responsive viewport were exercised against the published static output.

• React, Vue, and Angular example tabs changed their visible framework-native snippets. Arrow Right moved selection and focus to Angular, and Home returned selection and focus to React.
• The active example’s copy control produced the visible polite status message Copied!.
• The labeled Checkbox preview was operable by pointer and exposed a native, enabled, focusable checkbox. The Button preview exposed named enabled and disabled controls.
• Dark theme selection set data-theme="dark", produced a dark browser color scheme, and retained readable foreground and background presentation.
• At 390 × 844, the page had no horizontal document overflow. The mobile menu opened, closed with Escape, removed its expanded-page state, and restored focus to the Menu button.
• The RTL guide and its horizontal-keyboard reversal guidance were visible. The observed browser did not request reduced motion, so reduced-motion preference behavior remains CI-validated rather than manually observed in this run.

This observation validates the documentation reader interface, not the runtime behavior of a consumer application. Adapter-host evidence and the remaining visual and assistive-technology observations are recorded separately below.

Adapter-host acceptance evidence

On 2026-08-13, focused application-host contract tests were run against the React, Vue, and Angular adapters. Thirteen tests passed across the three framework suites. The selected contracts covered:

• a named modal or Dialog host, automated accessibility audit, Escape dismissal, contained focus, and restoration to its trigger;
• Checkbox activation, one framework-native change callback/emission/output, its checked state, and native form serialization where the adapter exposes a form value;
• invalid-form handling that focuses the first invalid control and exposes the error summary as an alert; and
• RTL-aware tabs or roving-focus navigation.

This evidence runs components inside each framework’s real test host and complements the package quick-start builds. It is not a visual browser or assistive-technology observation.

Automated release-candidate UI evidence

On 2026-08-13, five Chromium release-candidate checks passed against real documentation previews:

• a 640 CSS-pixel viewport, equivalent to a 1280-pixel layout at 200% zoom, had no horizontal document overflow and kept the Form preview reachable;
• a 390 × 420 short viewport kept an open Dialog and its Save action visible and reachable;
• forced RTL and reduced motion preserved a visible two-pixel Radio Group focus indicator while suppressing animation; and
• axe-core reported no WCAG A or AA violations on the hydrated Form page in light or dark themes.

These repeatable checks complement rather than replace manual browser zoom and assistive-technology testing. Release-candidate applications still need 200% browser-zoom and screen-reader output recorded by a tester.

Last verified on 2026-08-13 against Simurgh registry 0.1.1.