usabl docs: alt-text manifest is dormant without content requirements
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 42/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- playwright, typescript
- Domain
- accessibility, testing-qa
Research direction
Start by reading the demo application's content requirements and the usabl docs --html generation path. Decide whether adding a small set of requirements gives a useful live example of the bound-without-evidence state, or whether documentation should explain why the alt-text manifest is absent. Done when the demo shows that state or its expected absence is clearly documented.
Written by the indexing model from the issue text.
Description
Background
The alt-text manifest artifact is built from content requirements. When a project declares no content requirements, the manifest generator has nothing to draw from, so it emits no alt-text artifact.
Current behavior
On the demo application, which declares no content requirements, usabl docs produces only announcement-snippets and keyboard-paths. The alt-text-manifest kind never appears. As a result the "bound to a receipt but without per-entry evidence" honesty state, which the alt-text manifest is the canonical source of, is never exercised on the demo app. It is covered by unit tests, but not by any live run we can show.
Why this matters
The three honesty states the HTML renderer distinguishes are:
- verified: bound to a minted receipt and carries per-entry evidence.
- bound without evidence: bound to a receipt but no per-entry evidence, so the entries are expectations, not proof. The alt-text manifest is the real-world source of this state.
- observation: not bound to any receipt.
Without content requirements on a demo surface, state 2 has no live example, so a reader cannot see the middle state in a real generated page.
Proposed work
- Decide whether the demo application should declare a small set of content requirements so the alt-text manifest, and therefore the middle honesty state, appears in a real run.
- Alternatively, document clearly that the alt-text manifest is dormant until content requirements exist, so its absence is understood as expected, not as a missing feature.
Notes
Discovered while building and dogfooding usabl docs --html. No code defect: the generator behaves correctly given no content requirements. This is about coverage and demonstrability.
- 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 1/5 Under an hour Newbie friendliness 68/100
cursor/community-plugins#465 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 66/100
vetro-protocol/vetro-monorepo#978 ·
Maintainers usually reply within 1 day
-
ai-generated bug category:security effort:s priority:p3
Difficulty 2/5 1-3 hours Newbie friendliness 67/100
LanternOps/breeze#9697 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
maniator/verticopolis#1303 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
components-web-app/docs#297 ·