Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Rulepacks as a pluggable, versioned capability (only if productized)

Aperta
  • Qualcosa non va?
#195 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
15/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
playwright, typescript
Ambito
accessibility, testing-qa

Direzione di ricerca

The issue explicitly says this architecture is not planned for the contest and should be built only if usabl becomes a production product. Start by reading the existing makeRulepackProvider(extraChecks) seam and the linked prerequisite issues #182 and per-check isolation. A complete productized capability would need a stable provider API, versioning, declarative and trusted code packs, and an authoring workflow calibrated against real apps.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

area: rules enhancement

Status

Not planned for the contest. This is only worth building if usabl goes all the way to a real
production product sold to customers. It is recorded here so the decision and the design are not lost.

The decision

For the contest, the hand-coded PatternFly rulepack is the right call: it shows the differentiator on
Red Hat's own app. For a product, we would not keep hand-coding framework rulepacks into the engine.
We would make the rulepack a pluggable, versioned capability, ship PatternFly as one first-party pack
because it is strategic for Red Hat, and sell the engine's generic, honest verification substrate that
works on any framework.

Why a baked-in rulepack does not survive real customers

  • Customers do not all use PatternFly. A buyer might be on Material UI, Carbon, Ant, Salesforce
    Lightning, or their own system. Baking PF rules into the core only differentiates for PF shops and
    degrades to axe plus the keyboard walk for everyone else.
  • It is a maintenance treadmill we own forever. PF6 to PF7 moves selectors, class names, and ARIA
    patterns. Hand-coded checks rot on every design-system release, per framework, per version.
  • We are the wrong owner of the knowledge. The design system's own team knows its a11y contracts
    best. The architecture should let them publish and version their own pack.
  • The moat is the engine, not the framework knowledge: the keyboard walk, the readiness model, the
    no-false-green honesty, the gate, and the receipt. Those work on any framework. Framework rules are
    content riding on that engine.

The architecture to build instead

The engine already has the right shape. Providers emit Drafts, and the gate is the only verdict
authority. A rulepack is just a Draft-emitting provider, and the seam already exists
(makeRulepackProvider(extraChecks)). So a third-party or customer rulepack, even a buggy or hostile
one, cannot mint a false green, because it only produces Drafts and the gate still decides. That
property is what makes an open plugin model safe to sell.

  1. Declarative rulepack format for the common 80 percent. Most framework contracts are "for this
    selector, this ARIA state or role composition must be present." Express those as data (a manifest)
    evaluated by one generic engine-side evaluator. Non-engineers, including a design system's own a11y
    owner, can author and version them without writing code, and because they are data they cannot run
    arbitrary logic in the scan. This is both the maintainability win and the security boundary.
  2. Code plugins for the interactive 20 percent. Focus trap in a modal, focus restored on close,
    roving tabindex, announcement after an async action. These are genuinely stateful and need code.
    Ship them against a stable, constrained provider API, and treat code plugins as trusted-tier only
    (signed, reviewed, or first-party), while untrusted customer packs stay declarative.
  3. PatternFly as the first-party anchor pack, versioned alongside PF, ideally co-owned with the PF
    team. PF is the one framework where first-party investment is clearly justified for Red Hat. It
    ships as a pack pinned to a PF version, so a PF release is a pack bump, not an engine release.
  4. A rulepack authoring and calibration workflow as a product feature. The proof run is a coverage
    oracle: point usabl at a real app, see which components render, generate candidate rules, and
    calibrate them against the live app before promoting. This is the "bring your own design system"
    story a Material or Carbon shop needs.

What stays in the core (the thing we maintain)

The framework-agnostic substrate: the keyboard walk, readiness, the voicing lane, the gate, the
receipt, the trust and no-false-green properties, and the surfaces (stop hook, CI, PR comment,
overlay). That is the product. It delivers value on any framework on day one, and rulepacks are the
premium, per-design-system layer on top.

The honest tradeoff

A plugin architecture is more upfront engineering than hand-coding checks: a stable API, a versioning
story, and a real security boundary between trusted and untrusted packs. For a contest we would not do
it. For a product we must, because the alternative is owning a rulepack per customer framework
forever. The engine's "providers emit Drafts, gate is sole authority" design already gives us the hard
part of the safety model for free.

Prerequisites that are on the path either way

Two items are needed for even the current rulepack to be robust, and they are the first steps of this
plan, so they are not throwaway:

  • Unique, stable selectors (#182). A complete rulepack does many per-element reads and cannot rest on
    selectors that break on duplicate ids. The live proof run crashed the whole provider on a real AAP
    screen because queryAll returned a non-unique #toggle-kebab.
  • Per-check isolation. Today one check throwing kills the whole provider and drops every rulepack
    finding on that screen. A rulepack with many checks must isolate each so one failure is a disclosed
    gap, not total loss.

Scoping note

Define "complete" as target-driven: cover every stateful and compositional contract the target apps
actually render, calibrated against the live app, not the whole framework catalog. Use the proof run
as the coverage oracle to scope it.

Lingua principale
TypeScript
Stelle
0
Fork
0
Merge medio
2h 48m
PR unite (30g)
8

Preparare l'ambiente

  • Nessun Dockerfile né file Docker Compose
  • Ha un modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di usabl-dev/usabl

Tutte le issue di usabl-dev/usabl

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.