Statamic A11Y Docs Laravel Package

Technical Evaluation

Architecture fit. v1.4.0 is a minor release on an existing Statamic control-panel addon that scans a document library and reports remediation findings. The changes are additive and presentational: a new optional integration surface (a "Documents" band rendered onto the third-party Site Weather dashboard tile), pagination for the findings queue, and accessibility corrections across five tables plus filter labels and a dashboard title. No new persistence layer, no schema change, no change to the scanning pipeline. The release explicitly states "upgrading re-checks nothing," so the expensive path (document analysis) is untouched and upgrade cost is effectively deploy-only. Architecturally this is low-risk: the addon remains self-contained, and the one cross-package touchpoint is deliberately degradable.

Integration feasibility. Two integration modes exist and should be treated as separate decisions:

1. Core upgrade — queue pagination and accessibility fixes. Self-contained, no configuration, no data migration. Feasible in any environment already running a compatible 1.3.x.
2. Optional Site Weather band — requires the free bpmore/statamic-site-weather addon. This is a soft dependency with defined absent/partial states: not installed → nothing renders; installed but unconfigured, or no checks run yet → "unknown" rather than a false "clear." The deliberate refusal to render green in an unknown state is the strongest design signal in the release and materially reduces the risk of a misleading health indicator in front of stakeholders.

Technical risk. Low overall, with three watch items:

• Cross-addon version coupling. The band reads figures the weather dashboard draws; the contract between the two addons is implicit in the release note. A Site Weather major release could silently break or mis-scale the band. Need the declared Composer constraint and whether the band fails closed.
• Threshold semantics are opinion, not measurement. Mapping findings to clear/fair/overcast/rain/storm — including "a tenth of the library or more has critical problems" — is a judgement call baked into UI. If those cutoffs are hardcoded, sites will disagree with them; if configurable, that is a configuration surface to document.
• Accessibility claims are asserted, not certified. Header rows, visible labels, and consistent titling address obvious defects, but the release note does not reference an audit or assistive-technology testing. Treat as "defects fixed," not "WCAG conformance achieved."

Key questions.

• Which Statamic/Laravel/PHP versions are supported, and is 1.3.x → 1.4.0 a clean drop-in?
• What is the Composer constraint on Site Weather, and how does the band behave if the installed version predates the API it reads?
• Are the weather thresholds configurable per site, and are they documented?
• Is the weather band permission-aware — does it expose finding counts to roles that cannot open the dashboard?
• Does pagination alter URL/query behaviour in a way that affects bookmarks, exports, or cached responses?
• Is the 50-per-page page size configurable for very large libraries?

Integration Approach

Stack fit. Laravel/Statamic control-panel addon, installed via Composer and auto-discovered. Fits any Statamic site already running the 1.3.x line; the accessibility and pagination work benefits every installation regardless of whether Site Weather is adopted. No front-end, queue-worker, or storage assumptions change.

Migration path. Effectively none. No migrations, no re-scan, no reindex, no backfill. The upgrade is composer update plus the usual Statamic addon cache/asset refresh. The only behavioural change with user-visible consequence is that the findings queue now paginates — content that was previously unreachable past finding 50 becomes reachable, so expect a short-lived uptick in remediation activity rather than a technical issue.

Compatibility. Two independent compatibility axes: (a) the host Statamic/Laravel version, and (b) the Site Weather addon, which is optional and version-sensitive. Sites that skip Site Weather are unaffected by axis (b) entirely — the band simply does not appear. This makes the release safe to roll out broadly even where the companion addon is not approved.

Sequencing.

1. Upgrade in staging; confirm the control panel loads and the addon registers.
2. Verify the queue on a large library specifically — the release's motivating case is hundreds of untagged PDFs, so a small test set will not exercise pagination or filter persistence across pages.
3. Walk the five tables with a screen reader or accessibility checker, and confirm filter labels are exposed.
4. Defer the Site Weather decision to a separate change: install and configure it, confirm the "unknown" state renders as intended when unconfigured and when zero checks have run, then confirm the band opens this addon's dashboard.
5. Release to production; announce pagination, since users may have internalised "only 50 findings exist."

Operational Impact

Maintenance. Near-zero incremental burden. No background jobs, no scheduled tasks, no new storage. The one ongoing obligation is tracking the Site Weather addon's release cadence if the band is adopted — an additional package in the upgrade matrix for a cosmetic indicator.

Support. Net reduction expected. The queue's 50-item ceiling was a recurring class of confusion ("the tool says there are more findings but I can only see 50"), and pagination with filter persistence removes it. Consistent titling ("Document checks" matching the nav item since 1.3.2) removes a smaller wayfinding complaint. Counter-risk: users who must now page through results may report pagination itself as a regression; a brief note in release communications pre-empts this.

Scaling. Pagination improves perceived performance and memory footprint on large libraries but does not reduce total work — deep offset pagination on a very large findings table can degrade, and each page change re-runs the filtered query. For libraries in the many-hundreds-of-documents range this is fine; for very large libraries, page size and query efficiency are worth confirming. The weather band adds one aggregate read per dashboard load, which is negligible unless it recomputes over the whole library on every render.

Failure modes.

• Site Weather absent → no band; silent, correct, and the documented default.
• Site Weather installed but unconfigured, or no checks yet → "unknown." Correct by design, but a persistent "unknown" with no explanation reads as breakage; the band should surface why.
• Cross-addon contract drift → band shows stale or mis-scaled state. Highest-severity failure mode, and the one to guard with a version constraint and a fail-closed default.
• Misleading green → explicitly designed out; "clear" requires zero failures, not zero data.
• Pagination edge cases → filters dropped or page state lost on navigation; verify on the large-library path before release.

Ramp-up. Low for end users: the queue looks the same, now with headers, labels, and page controls, and the dashboard title matches what people already call it in navigation. No training required. For administrators, ramp-up is a one-page note covering the paginated queue and the optional Site Weather pairing — with emphasis that it is a suggestion, not a requirement, so nobody attempts a second addon install believing the upgrade depends on it.