Skip to main content
Batoi UIF Docs

CSS Authoring Standards

Naming conventions, override boundaries, accessible states, and release checks.

Version 3.0.0 Version 3 active maintenance Reviewed Aug 11, 2026 Next review Nov 11, 2026
Start Reading Open GitHub Report documentation issue

Owner: Batoi Engineering Reviewed by: Batoi UIF Maintainers Source revision: b2f3478

Start FastLoad UIF in server-rendered pages and initialize declarative behavior. Chart SupportReview native SVG chart types, Flint mappings, and deferred advanced charts. Micro AppsBuild contained app surfaces that live inside larger Batoi routes. AI and MCPDesign approval UI while privileged tool execution stays server-side.
Browse Batoi UIF Documentation CSS Authoring Standards
On this page

CSS Authoring Standards

Naming and ownership

  • Reserve uif-* classes and --uif-* variables for framework contracts.
  • Use a feature prefix for application additions, such as clinic-assessment or report-print.
  • Use lowercase hyphen-separated names that describe a purpose, not a color or pixel value.
  • Keep CSS appearance separate from data-uif behavior. Renaming a CSS class does not migrate a JavaScript component.
  • Do not publish local aliases as framework APIs.

Cascade and overrides

Load UIF once, followed by the application theme, then narrowly scoped route styles. Do not edit minified distribution files. Set semantic variables before adding selector overrides; place light-theme overrides on :root, [data-theme="light"] and dark overrides on [data-theme="dark"]. A descendant theme declaration can override root variables, so test the actual theme boundary.

.clinic-assessment {
  gap: var(--uif-space-4);
  color: var(--uif-text);
}
.clinic-assessment .clinic-assessment-note {
  max-inline-size: var(--uif-measure-copy);
  overflow-wrap: anywhere;
}

Avoid global button, table, or .card overrides on mixed-shell pages. Prefer low-specificity feature selectors; use !important only for a documented utility or print exception. Do not assume that placing markup inside a container scopes the reset stylesheet.

Accessibility and states

Use semantic buttons, links, headings, labels, captions, and table headers. Preserve focus indicators and keyboard order. Disabled controls need native disabled; aria-disabled alone does not prevent actions. Invalid controls need explanatory text, aria-invalid, and an associated error description. Status colors must have visible text equivalents.

Check contrast in each theme, browser zoom at 200%, narrow screens, long translated labels, RTL layouts, reduced motion, and forced colors. Use logical spacing for international layouts. Do not hide essential information solely to make a page fit.

Maintenance

Document the tested UIF version alongside examples. Verify every selector and token against the released CSS, including actual media/container queries. Keep Bootstrap migration notes separate from native examples. Run examples with the production stylesheet, not a development-only theme that silently supplies missing classes.

Before release, test normal, hover, focus, disabled, loading, empty, validation-error, and long-content states. Keep server authorization and validation independent of visual state.