usabl docs: add a whole-app mode that documents every in-scope surface
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 52/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- playwright, typescript
- Domain
- accessibility, developer-experience
Research direction
Start by reading the usabl docs command path and tracing how it selects in-scope surfaces from a run and git status. The issue identifies the renderer’s three honesty states as already working, so focus on what the generator feeds it. Done means a whole-app mode includes every in-scope surface independent of git status while preserving honest empty results, receipt evidence requirements, and exit 0 without minting a verdict.
Written by the indexing model from the issue text.
Description
Background
usabl docs projects documentation artifacts (alt-text manifest, announcement snippets, keyboard paths) from a run. Today the run it projects from is scoped the same way the gate scopes work: to the surfaces the current change actually touched. That is the right default for the gate, because the gate only judges what changed. It is a surprising default for documentation, where a reader usually wants the whole application described, not just the diff.
Current behavior
On a clean working tree, a run reaches few or no surfaces, so usabl docs (and usabl docs --html) can produce little or nothing. That is honest, but it is easy to mistake for a bug: "I asked for the docs and got an almost empty page."
Proposed behavior
Add a whole-app documentation mode that documents every in-scope surface, independent of git status, so a reader can generate a full accessibility document for the application on demand.
Keep the honesty invariant intact:
- A clean tree with nothing to prove should still yield an honest idle or empty result, clearly labelled, never a fabricated verdict.
- Whole-app mode is a generator like the current command: it always exits 0 and mints no verdict. Only surfaces that reached a minted receipt with per-entry evidence may read as verified; everything else stays an expectation or an observation, exactly as in the per-change mode.
Notes
Discovered while building usabl docs --html. The renderer already distinguishes the three honesty states correctly; this issue is about widening what the generator feeds it, not about the rendering.
- Dominant language
- TypeScript
- Stars
- 0
- Forks
- 0
- Avg merge
- 2h 48m
- Merged PRs (30d)
- 8
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- No contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from usabl-dev/usabl
-
area: engine bug
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
-
Stop hook allows a stop on an unknown verdict, and the self-check prints IDLE for a null verdictOpenarea: assistants bug
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
area: engine bug security
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
Overlay: browser context failures are counted per plugin, not per browser, and close is not sharedOpenarea: overlay bug
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
-
area: engine enhancement performance
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 1 day
-
bug
Difficulty 1/5 Under an hour Newbie friendliness 76/100
logto-io/logto#9837 · 1 comment ·
Maintainers usually reply within 1 day
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
Difficulty 1/5 Under an hour Newbie friendliness 76/100
lingdojo/kana-dojo#32964 · 1 comment · 5 reactions ·
Maintainers usually reply within 1 day
-
Documentation status: needs triage
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
mastra-ai/mastra#28194 · 1 comment ·
Maintainers usually reply within 1 day
-
priority-low refactor-3
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Maintainers usually reply within 3 days