Theming & accessibility
Every colour Borm draws - and the corner radius, the gap between fields and the form's width - is a
--bit-borm-* custom property declared on the form, with a light and a dark palette. Restyling every
form is a few lines of CSS, no stylesheet of your own to maintain. And whatever it looks like, the markup underneath
stays accessible: real labels, ARIA wiring, focus that goes where the problem is.
data-theme
on the form, or any ancestor, beats the system's preference. Move the controls to override single tokens - an inline
style here, a CSS rule in an app - and the CSS they come to is written out below. Submit the empty form to see the
error colours.
The CSS this comes to
/* Nothing overridden: every token has its default. */
View source
@* Any attribute BormView does not know is put on its <form>: a class, a data-theme, a style. *@
<BormView Definition="_schema" Data="_data" ShowErrorSummary="true" ShowResetButton="true"
data-theme="dark" style="--bit-borm-accent: #0d9488; --bit-borm-radius: 4px;" />
/* Or, for every form in the app - in a stylesheet loaded after bit-borm.css: */
.bit-borm-form {
--bit-borm-accent: #0d9488;
--bit-borm-radius: 4px;
--bit-borm-max-width: none; /* fill the container */
}
/* A theme toggle of your own: data-theme on any ancestor - or the form - beats the OS preference. */
<html data-theme="dark">The custom properties
Each is declared on .bit-borm-form itself, so a value set on an ancestor (:root,
body) is shadowed: write .bit-borm-form, or .my-page .bit-borm-form.
| Property | Light | Dark | Used for |
|---|---|---|---|
--bit-borm-accent | #4f46e5 | #4f46e5 | The primary button, focus rings, a checked switch, the range slider. |
--bit-borm-accent-contrast | #ffffff | #ffffff | Text and marks drawn on the accent colour. |
--bit-borm-surface | #ffffff | #111827 | The background of controls, tags and buttons. |
--bit-borm-surface-muted | #fafafa | #1f2937 | Read-only controls, affixes and hovered buttons. |
--bit-borm-surface-disabled | #f3f4f6 | #374151 | Disabled controls. |
--bit-borm-border | #d1d5db | #4b5563 | Control and card borders. |
--bit-borm-border-focus | var(--bit-borm-accent) | var(--bit-borm-accent) | The border of a focused control. |
--bit-borm-error | #dc2626 | #f87171 | Error text, invalid borders, the required marker. |
--bit-borm-error-contrast | #ffffff | #111827 | Text drawn on the error colour: a step's error count. |
--bit-borm-error-surface | #fef2f2 | #2a1215 | The error summary's background, and a tag's remove button on hover. |
--bit-borm-warning | #d97706 | #fbbf24 | Warning messages. |
--bit-borm-text | #111827 | #f9fafb | Labels and values. |
--bit-borm-muted | #6b7280 | #9ca3af | Help text, counters, placeholders. |
--bit-borm-radius | 8px | 8px | Corner radius of controls and cards. |
--bit-borm-gap | 1rem | 1rem | The space between fields. |
--bit-borm-max-width | 720px | 720px | The form's maximum width; none fills the container. |
A token both themes share - the accent, the radius, the gap, the width - needs one rule. One that differs between them has to be set once per theme, mirroring the stylesheet's own four rules, or the dark value would be replaced too:
.bit-borm-form { --bit-borm-surface: #fffdf7; }
[data-theme="light"] .bit-borm-form, .bit-borm-form[data-theme="light"] { --bit-borm-surface: #fffdf7; }
@media (prefers-color-scheme: dark) {
.bit-borm-form { --bit-borm-surface: #1c1917; }
}
[data-theme="dark"] .bit-borm-form, .bit-borm-form[data-theme="dark"] { --bit-borm-surface: #1c1917; }
Each theme also sets color-scheme, so the parts of a control the browser draws - date pickers, open
dropdowns, the file button, scrollbars - follow it too.
Styling hooks
The markup uses BEM-style classes under bit-borm-. The ones most worth targeting:
| Class | Element |
|---|---|
bit-borm-form | The <form>, carrying the tokens; __title, __description, __body, __actions are its parts. Class on BormView adds your own. |
bit-borm-field | One field - label, control, help and messages; --invalid, --checkbox, --static are its states. |
bit-borm-label, bit-borm-help, bit-borm-required | A label, its help text and the required marker. |
bit-borm-input | Every text-like control, select and textarea; --invalid while it holds an error. |
bit-borm-messages, bit-borm-message | A field's messages; --error, --warning, --info per severity. |
bit-borm-group, bit-borm-fieldgroup | A nested object, and a run of fields sharing a group name. |
bit-borm-array | A repeater; __item, __item-body, __item-actions, __header, __empty. |
bit-borm-stepper, bit-borm-tabs, bit-borm-section | A wizard's steps, steps as tabs (__badge counts the errors), and steps as sections or an accordion. |
bit-borm-review, bit-borm-summary | A review of the answers, and the error summary. |
bit-borm-btn | Every button; --primary, --ghost, --danger, --add, --icon, --sm. |
bit-borm-grid, bit-borm-sr-only | The form body when Columns(...) is set, and text read out but not shown. |
Accessible by default
- Every control has a real
<label>- a hidden one still names it withHideLabel()- and radio groups, multi-selects, groups and repeaters are<fieldset>s with a<legend>. aria-required,aria-invalidandaria-describedbyare on every control, the last pointing at its help and its messages, so a message is read out when focus reaches the field.- After a failed submit, focus moves to the first invalid field - or to the error summary, whose links reach each field, or its step. With nothing to focus, the outcome is announced.
- Changing a wizard step moves focus to the new step; adding a repeater row puts the caret in it, and removing one moves it to the row that took its place. Repeater, tag and character-count changes are announced.
- A message's severity is said in words as well as colour - "Error:", "Warning:", "Note:" - and an error is set heavier. A tab or section holding errors carries a count that is read out too.
- Tabs follow the WAI-ARIA tabs pattern, an accordion is the browser's own
<details>, andReadOnlyWhenkeeps a settled value focusable where a disabled one would leave the tab order.Autofocus()focuses a field when the form first renders. - Every target the stylesheet draws is at least 24 × 24 CSS pixels (WCAG 2.2), and the layout uses logical properties only, so a form mirrors inside
dir="rtl".
What the library cannot vouch for: a custom renderer's own markup, the browser's built-in pickers, and the colours an app re-tints the tokens to - check their contrast against WCAG 1.4.3 when you do.