🧭 QuizWizz admin information architecture strategy

Authority

This page decides how to streamline, polish, and organise the QuizWizz v1.10.0 admin UI on the isolated WRDP bench, especially the settings/config surface. It turns the complaint “some wild stuff is going on — like a highly relevant sub-category toggle is hidden in the last corner, and we lost the family aspect of things; where something is stored or theoretically grouped in, a user expects the backend to navigate more like the experience itself; everything most relevant for a page … title next to the thing” into a measurable information architecture and migration plan. It deliberately makes no production, deployment, or release claims. Bench evidence is evidence, not authorization. The program masterplan remains the wider program authority.

Diagnosis, measured

QuizWizz currently exposes this admin rail: Dashboard, Quizzes, Questions, Subjects, Settings (includes/Admin/AdminMenu.php). The rail is correct as of 2026-08-15; the problem is what happens after entering Settings.

Current section	What it owns now	Why that grouping is weak for users
qw-essential	Cross-cutting essentials and defaults	“Essential” ranks importance but does not identify the object being changed.
qw-builder	Quiz-building defaults, including quiz-size behaviour	Builder concerns are separated from the quiz being built.
qw-player	Player behaviour, sound, feedback, answer-time experience	Play-time controls are remote from the player and its preview.
qw-presentation	Display details, question numbering, answer marker, presentation switches	Presentation is a subsystem name; users think “what the question/player looks like.”
qw-pdf	Printing and PDF output, including theme choice and start/off labels	Print decisions are remote from the print action.
qw-theme	Theme enablement and default appearance	Appearance is split from presentation and PDF even when all affect what users see.
qw-ai	AI assistance and visitor-facing AI capabilities	Capability limits use implementation language such as “site ceiling.”
qw-data	Backups, portability, import/export, and data operations	Lifecycle actions share one region despite having different risk and frequency.
qw-advanced	Rare and technical switches	Correct home for true exceptions, but not a destination for relevant controls that lack another home.

The three structural faults

1. Relevance is flat. The screen contains 140 form controls; 124 are visible at once, with about 858 words of body copy. A highly relevant sub-category toggle can therefore be “hidden in the last corner” even though it is technically present: every section competes in one long visual field, so nothing is ranked.
2. The “family” is organised around code, not thought. The current families are plugin subsystems such as qw-pdf, qw-presentation, and qw-player. The user instead thinks in objects and moments: this quiz, this question, this subject, playing, printing, or changing appearance. That mismatch is exactly why the family aspect feels lost.
3. Controls are far from the thing they govern. A toggle that changes a quiz page lives in global Settings rather than next to the quiz page, its preview, or the action it modifies. The backend therefore does not navigate like the experience itself, and the title is not “next to the thing.”

Note

The tabs are not broken paging. Settings remains one intentional scroll-spy surface: showWorkspace() exits search, restores the panels allowed by the selected settings tier, chooses the requested visible tab and calls markActiveTab() without hiding every non-active panel (assets/js/qwizz-admin-settings.js:1241-1260). createSectionObserver() observes every visible section and drives the active tab from intersection geometry (:1487-1504). Re-filing “multiple sections remain visible” as a tab bug would misdiagnose the design.

The governing principle

Put the decision beside the thing it changes; organise the rest by the moment the user experiences it.

Operational rule	Before	After
Settings live next to the object they change.	PDF theme choice is inside qw-pdf, far from the print action.	Put PDF theme choice in the Print/PDF panel opened from the print action; keep only its shared default in the Print/PDF settings pane.
A pane shows the frequent set and folds the long tail.	124 of 140 controls are visible on one scroll page.	Each pane opens with its frequent controls; “More options” reveals uncommon controls in the same pane, with search also able to reveal and focus them.
Navigation mirrors the player/builder experience, not the code layout.	Question numbering and answer marker live under qw-presentation; player sound and feedback live under qw-player.	Put numbering and answer marker beside presentation preview; put sound and feedback beside the player preview. Preserve implementation paths underneath.

The law resolves both literal complaints:

• “Hidden in the last corner” becomes a ranking failure, not a request for a larger tab strip: surface the frequent control beside its object and fold the long tail.
• “We lost the family aspect” becomes an object-family rule: Quiz, Question, Subject, Play, Print/PDF, Look, AI, Data & lifecycle, Advanced.
• “Title next to the thing” becomes a placement requirement: the panel title names the object/action and sits next to its preview or action, not above unrelated subsystem controls.

The family map

This is the destination information architecture. “Contextual” means the control appears beside the affected object or action. A shared default may remain in a settings pane, but it must link to and use the same underlying setting path.

Object or moment	Controls sourced from current sections	Destination	Default-visible controls	Fold away
Quiz	qw-essential, qw-builder	Contextual “Quiz setup” panel on each quiz screen; shared defaults in a Quiz settings pane	Quiz-size default, core build defaults, immediately consequential quiz behaviour	Rare builder constraints and site-wide fallback defaults
Question	qw-builder, qw-presentation, qw-essential	Contextual panel beside the question editor and presentation preview	Question numbering, answer marker, relevant editor assistance	Rare presentation detail and helper-copy preference such as Show editor helper copy
Subject	qw-essential, qw-builder	Contextual panel on the subject screen; subject-wide defaults in a Subject settings pane	Supply/readiness-relevant defaults and controls that affect the selected subject	Site-wide fallback behaviour and uncommon constraints
Play	qw-player, relevant qw-presentation	Contextual panel beside the player preview; shared defaults in a Play settings pane	Player sound, feedback, answer interaction, common play behaviour	Uncommon timing and presentation refinements
Print/PDF	qw-pdf, relevant qw-theme and qw-presentation	Contextual panel opened from the print/PDF action; defaults in a Print/PDF settings pane	PDF theme choice, output essentials, immediately visible print options	Rare layout, pagination, and specialist output options
Look	qw-theme, visual controls from qw-presentation	Look settings pane with live preview; object-specific appearance remains contextual	Default theme, enabled themes, broad visual choices	Fine-grained presentation switches and uncommon theme details
AI	qw-ai	AI settings pane; visitor capability matrix presented as one unit	“What visitors may do” matrix, enabled state, common assistance choices	Provider/technical limits and rare operating controls
Data & lifecycle	qw-data, lifecycle parts of qw-essential	Data & lifecycle settings pane, with dangerous actions visually separated	Backups, portability job status, export/import entry points	Recovery details, retention/owner-specific internals, uncommon maintenance actions
Advanced	qw-advanced, only genuinely technical controls from other sections	Advanced settings pane	No more than the few controls needed for common diagnosis	All rare technical switches, collapsed by named task rather than a generic dump

Contextual placement decisions

Existing control family	Required placement	Why
PDF theme choice	Beside the print action, inside the contextual Print/PDF panel	The choice is understood while producing output, not while browsing global configuration.
Question numbering	Beside presentation preview	The user can see which title/number the switch changes.
Answer marker	Beside presentation preview	The label and visual result occupy the same decision surface.
Player sound	Beside the player preview	Sound is a play-time experience, not an abstract subsystem.
Player feedback	Beside the player preview	Feedback belongs to the answer moment and should be judged there.
Quiz-size defaults	Beside the builder, with the shared default in Quiz settings	Size is chosen while building; the default is still globally manageable.

Warning

“Contextual” does not mean duplicating state. One setting may have more than one entry point only when every entry point reads and writes the same data-path, reports the same saved value, and links to its shared default. Never create a second setting that merely looks equivalent.

Per-pane budget

The target is deliberately numeric. It defines success before visual polish begins.

Measure	Current measured baseline	Target	Acceptance rule
Total form controls	140	No forced reduction	Reorganisation may preserve all valid capabilities; deletion requires a separate product decision.
Controls visible at once	124	12 or fewer per pane at initial open	Count each open pane independently before any “More options” disclosure.
Body/helper copy	About 858 words on the settings page	80 words or fewer per pane at initial open	Exclude control labels; count visible explanatory copy, warnings, and descriptions.
Click depth to any setting	One Settings entry plus long-scroll/search discovery; depth is not currently the main cost	3 interactions or fewer from the relevant rail object	Count clicks/taps from Quizzes, Questions, Subjects, Settings, or the relevant action to a focused, operable control. Scrolling does not excuse excess depth.
Hidden long-tail controls	Not meaningfully ranked because almost all controls are simultaneously visible	One named disclosure maximum inside the destination pane	Search may reveal the same setting, but cannot be its only route.

How to measure

Run both viewports against the actual bench surface:

• Desktop: 1600×1000.
• Mobile: 390×844.
• For each pane at initial open, count visible controls with:

[...pane.querySelectorAll('input:not([type="hidden"]),select,textarea')]
  .filter((control) => control.offsetParent !== null).length

• Count visible helper/body-copy words inside that pane, excluding labels and hidden disclosure content.
• Record the interaction path from the relevant rail object or action to the focused control.
• Capture geometry for the pane, title, target control, disclosure, and save/status affordance at both viewports.
• Capture the accessibility tree so labels, groups, disclosure state, and focus order are evidence rather than visual assumptions.

Tip

The target is not “make the page shorter.” It is “make the frequent decision visible where it is relevant, while keeping every uncommon decision reachable and named.”

Label and copy rules

Replace implementation jargon with decisions

Current wording/problem	Required wording or structure	Rule
Ten controls say … site ceiling (includes/Admin/views/settings-page.php:382,386,413,434,447)	One What visitors may do capability matrix	Describe the visitor capability and allowed limit once; technical ceilings may appear in focused help.
Show editor helper copy (includes/Admin/views/settings-page.php:517)	Show guidance in the question editor	Name the affected object, location, and visible result.
Quiz Wizzard for visitors (includes/Admin/views/settings-page.php:812)	A visitor-facing capability row under What visitors may do	Do not use an internal feature name as a decision label.
Enable Quiz Wizzard for visitors (includes/Admin/views/settings-page.php:819)	Visitors can use Quiz Wizzard or the matching capability-matrix switch	Use actor + action; remove duplicate headings and controls where they express one decision.

Scope duplicate labels to their object

• Start: aus appears four times across PDF and Presentation. Replace it with object-scoped labels such as Start PDF section: off, Start presentation: off, or the exact affected object/action.
• Aus appears three times across Player and Presentation. Replace it with explicit states such as Player sound: off, Answer feedback: off, or the exact governed behaviour.
• Do not rely on surrounding cards, position, or section color to supply the missing scope; the accessible name must stand alone.
• Keep every control’s programmatic name. The current audit found 0 of 18 number inputs and 0 of 140 controls unnamed, so migration must preserve that baseline.
• Fix the one unnamed submit button in the Data section with a visible or programmatically associated action name; do not trade copy reduction for an unnamed control.

Put helper prose behind an accessible info affordance

• Keep the direct label short and decision-shaped.
• Put longer rationale, examples, and edge cases in an info affordance available on hover and keyboard focus, and operable by touch.
• Associate help with the control using the existing semantic pattern (aria-describedby or equivalent), not visual proximity alone.
• Never make title the only help source: it is unreliable for keyboard users and screen readers, and hover does not exist on touch.
• Keep safety-critical warnings visible in the pane; do not fold destructive consequences into optional help.

Do not do this

The design harvest that produced the pattern inventory (a rendered review of the archived HTML prototypes, held outside this vault) rejects these patterns on accessibility or control grounds:

• No hover-only symbol rail. It dies on touch, hides meaning from keyboard and screen-reader users, and title is not a reliable accessible label.
• No drag-only reordering. A pointer gesture cannot be the sole way to change order; provide keyboard-operable move controls and an announced result.
• No auto-advance after answering by default. It removes the learner’s control over reading feedback and creates timing/accessibility problems.
• No setting hidden behind search alone. Search is an accelerator, not information architecture; every setting needs a named object/moment family and a browsable route.

Migration waves

Each wave is independently shippable on the bench, has an acceptance test, and can be rolled back without depending on a later wave.

Wave 1 — Copy and grouping, no persistence change

Change

• Rename jargon and duplicate visible labels without changing control names, values, IDs, name, or data-path.
• Present the ten … site ceiling decisions as a single visible What visitors may do family while preserving the current underlying controls and save paths.
• Add explicit object scope to Start: aus ×4 and Aus ×3.
• Add an accessible name to the unnamed Data submit button.
• Introduce family headings in the existing long page; do not move controls yet.

Acceptance test

• Saved settings before and after are identical after opening and saving without edits.
• Every one of 140 controls has an accessible name; the Data submit button has a distinct action name.
• No visible site ceiling, ambiguous Start: aus, or bare Aus label remains.
• Keyboard focus and screen-reader traversal expose each family heading and its controls.

Rollback

• Reinstall the prior view/translation assets atomically; no stored values or schema need reversal because persistence did not change.

Wave 2 — Real panes and ranked disclosure

Change

• Replace scroll-spy-only presentation with actual object-first panes: Quiz, Question, Subject, Play, Print/PDF, Look, AI, Data & lifecycle, Advanced.
• Show the frequent set by default; move uncommon controls under one named “More options” disclosure per pane.
• Keep search as an accelerator that opens the correct pane/disclosure and focuses the result.

Acceptance test

• At 1600×1000 and 390×844, every pane initially shows 12 or fewer controls and 80 or fewer helper-copy words.
• Every setting is reachable within three interactions from its relevant rail object or action.
• Search results reveal, focus, and announce a hidden target; the target is also reachable without search.
• Saving an unchanged form produces no setting-value drift.

Rollback

• Restore the prior settings view and JavaScript assets; preserve all stored settings because paths and values remain unchanged.

Wave 3 — Contextual entry points

Change

• Add PDF theme choice near the print action.
• Add question numbering and answer marker near presentation preview.
• Add player sound and feedback near the player preview.
• Add quiz-size defaults near the builder.
• Link each contextual control to its shared default and show whether the current value is inherited or explicit.

Warning

Moving or re-rendering a control must not change its data-path. The apiFetch save payload posts {settings, revision} to D.settingsPath, and the no-script fallback also depends on submitted paths. A nonce-valid partial POST to qwizz_save_settings_fallback treats absent checkboxes as off and resets absent iface_lang to auto (includes/Admin/SettingsPage.php:543-572). Do not submit a partial fallback form as though omitted fields were unchanged.

Acceptance test

• Changing each contextual control updates the same stored setting shown in its settings pane, and both entry points agree after reload.
• The save bar, success state, and qw_settings_conflict optimistic-concurrency error remain visible and understandable.
• A no-script full-form save preserves untouched checkboxes and iface_lang; a deliberately partial fallback POST is blocked or otherwise prevented from silently resetting absent values.
• Keyboard and touch users can reach each contextual control and return to the affected action/preview.

Rollback

• Remove contextual renderers and links, restoring the settings-pane entry points; do not migrate or rewrite stored values.

Wave 4 — Polish, preview, and lifecycle safety

Change

• Align each contextual panel title beside the affected preview/action: “title next to the thing.”
• Add clear loading, saved, unsaved, conflict, empty, error, and disabled states using existing admin primitives.
• Separate routine portability/backups from destructive or recovery actions in Data & lifecycle.
• Preserve settings search, preview, owner-scoped backups, portability jobs, and no-script access.

Acceptance test

• Geometry evidence at both required viewports shows titles, controls, disclosure, preview/action, and save state without overlap or off-screen trapping.
• Accessibility-tree evidence shows names, groups, status announcements, disclosure state, and logical focus order.
• A forced stale revision surfaces qw_settings_conflict; a failed save retains the user’s unsaved values and offers a clear recovery action.
• All nine families remain browsable and every setting remains reachable without pointer-only interaction.

Rollback

• Restore Wave 3 presentation assets and templates; retain the object-first panes and unchanged persistence paths.

How to verify any admin UI change

Use 🛡️ Service Operations for bench access and the wider evidence rules.

• Confirm the target is the isolated bench running QuizWizz v1.10.0, schema 1.6.8.
• Stage every changed plugin file under /tmp/qwfix/; never edit the bind mount in place.
• Install atomically with sudo -n install -o www-data -g www-data -m 0644.
• Lint every changed PHP file in-container.
• Run ./scripts/quizwizz-probe.sh --wave all; the current benchmark is 1..94, assertions=94 failures=0, recorded in the standing probe authority.
• Exercise the changed admin path in the real browser, including loading, saved, error/conflict, disabled, disclosure, and no-script-relevant behaviour.
• Measure each affected pane at 1600×1000 and 390×844: visible-control count, visible helper-copy words, and interaction depth.
• Capture geometry evidence for the title, affected object/action, target control, disclosure, and save/status affordance.
• Capture accessibility-tree evidence for names, group relationships, focus order, disclosure state, and live status/error announcements.
• Verify keyboard-only and touch-equivalent operation; no control or help may depend on hover, drag, or search alone.
• Compare saved values before and after an unchanged save; confirm every moved control retained its data-path.
• Confirm DISALLOW_FILE_EDIT remains effective and no admin-editor workaround was introduced.
• Record the tested viewport, path, setting, expected effect, observed effect, and rollback artifact. Bench evidence remains bench evidence only.