fullbleed.ui Accessibility Authoring¶
For class_name, selectors and attached styles, see the worked styling examples. The reference below focuses on the accessibility authoring layer.
Reference imported from v2.5.48. Check the installed runtime for your exact version.
For general document creation, start with Build PDFs with Python components. It covers named elements, props, children, rich text, Python styles and direct rendering.
This guide covers the component-first HTML authoring helpers in fullbleed.ui,
with a focus on fullbleed.ui.accessibility for remediation-oriented document
workflows.
Modules¶
fullbleed.ui: core HTML/component authoring (Element,Document,to_html)fullbleed.ui.primitives: engine-safe layout and presentation primitivesfullbleed.ui.style: inline style composition (Style,style(...))fullbleed.ui.accessibility: semantic wrappers and a11y validation
Scaffold starter:
fullbleed new accessible <path>creates an accessibility-first local project scaffold using these modules.- The scaffold renders through
fullbleed.accessibility.AccessibilityEngineand emits verifier/PMR/PDF seed artifacts plus non-visual traces by default.
Runtime Surface (fullbleed.accessibility)¶
Authoring and runtime/output are intentionally separated:
fullbleed.ui.accessibility: semantic authoring primitives +A11yContractfullbleed.accessibility: PDF/UA-targeted runtime wrapper (AccessibilityEngine)
Use the UI layer to author semantic HTML. Use the accessibility runtime surface to emit artifacts and audit/trace outputs for review and CI.
Core Pattern¶
Use @Document(...) to compose a document artifact, then emit HTML with
artifact.to_html(...).
from fullbleed.ui.core import Document
from fullbleed.ui import el
from fullbleed.ui.accessibility import FieldGrid, FieldItem
@Document(title="Example", bootstrap=False)
def App():
return el("div", FieldGrid(FieldItem("Name", "Jane Doe")))
artifact = App()
html = artifact.to_html(a11y_mode="raise")
a11y_mode values (v1):
None: no automatic validation during HTML emission"warn": emit diagnostics as warnings and return HTML"raise": raiseA11yValidationErroron structural errors
Inline Styles (fullbleed.ui.style)¶
style= accepts strings and composed values.
from fullbleed.ui import el, style
node = el(
"div",
"hello",
style=style({"font_weight": 700}, "color: #123;", {"margin_top": "4px"}),
)
Behavior:
- preserves authored/insertion order
- normalizes
snake_caseproperties to kebab-case - warns on suspicious values/types (for example raw booleans)
Accessibility Module Highlights¶
Semantic tables¶
Use SemanticTable* wrappers for data tables. This keeps table semantics
distinct from generic layout primitives.
from fullbleed.ui.accessibility import (
SemanticTable, SemanticTableHead, SemanticTableBody, SemanticTableRow,
ColumnHeader, RowHeader, DataCell
)
Field/value semantics¶
Use FieldGrid + FieldItem for non-tabular label/value content.
FieldGridis semantic-first and emitsdl/dt/dd- use
LayoutGrid(infullbleed.ui.primitives) for non-semantic box layout
Landmarks, sections, status¶
Available wrappers include:
Region,Heading,SectionStatus,Alert,LiveRegionFieldSet,Legend,Label,HelpText,ErrorTextDetails,SummarySrText
A11yContract Validation¶
A11yContract is a lightweight structural validator intended for document
authoring and remediation workflows.
Current checks include:
- duplicate IDs
- missing
aria-labelledby/aria-describedbytargets - empty
aria-label - multiple
mainlandmarks - unlabeled
region - informative image text alternatives
- signature enum validation (
signature_status,signature_method)
Example:
from fullbleed.ui.accessibility import A11yContract
report = A11yContract().validate(artifact, mode="warn")
Signature Semantics (Text First)¶
Model signatures as two separate concerns:
- Meaningful signed-state content (textual/machine-readable)
- Visual signature mark (supplemental, optionally decorative)
Use:
SignatureStatusSignatureMarkSignatureBlock
Guidance:
- do not rely on a signature image alone to convey signed state
- when a signature image carries meaning, provide text equivalent including
Signatureand the signer name (for exampleSignature: Jane Doe) - if the mark is redundant, make it decorative (
Decorative(...)ormark_decorative=True)
Canary Examples¶
Two canary examples in examples/ exercise the v1 accessibility APIs:
examples/semantic_table_a11y_canary/report.pyexamples/signature_accessibility_canary/report.py
Each example emits:
- PDF + preview PNG(s)
- component mount validation JSON
A11yContractvalidation JSON
Component mount validation uses the native render-time pagination trace as the authoritative overflow signal when the engine exposes it. Legacy JIT placement bounds remain a fallback for older engines; their conservative glyph-run padding is not treated as painted layout overflow when native pagination reports none.