Aster UI / Guides
Check an application with aster-lint
Aster UI provides elements for the controls an application needs: buttons, fields, checkboxes, selects, grids, dialogs, tabs and navigation. They share binding, validation, keyboard behaviour, states and themes. A hand-made control works on the day it is written but falls out of step: it misses a state, a theme or an accessibility rule the element already handles.
aster-lint checks an application's templates, HTML and CSS for those
shortcuts. Each finding names the Aster element to use instead and its entry in
the reference. Where no element fits, a comment silences the
finding and records why, so the exceptions stay visible and can be reported as
gaps.
Run it
aster-lint ships with @getaster/elements. Point it at the application's
source and page files:
bunx aster-lint src index.html
bunx aster-lint --theme src/brand-theme.css src # a theme file may set tokens
bunx aster-lint --allowances src # also list every silence
It reads .ts, .tsx, .js, .mjs, .html and .css files, skipping
node_modules, dist, build, hidden directories, type declarations and
*.test.* or *.spec.* files. It exits with 1 when it finds a problem, so it
can run in a pre-commit hook or CI:
{ "scripts": { "lint": "aster-lint src index.html" } }
What it checks
In lit html templates, strings assigned to innerHTML, createElement
calls and HTML files:
| Rule | Finds | Use instead |
|---|---|---|
native-button |
<button>, button-type inputs |
aster-button, aster-command-bar, aster-menu |
native-checkbox |
<input type="checkbox"> |
aster-check, aster-switch |
native-input |
Text, number and date inputs | aster-field, aster-number-field, aster-date, aster-picker |
native-textarea |
<textarea> |
aster-field |
native-select |
<select> |
aster-select, aster-choice |
native-table |
<table> |
aster-grid |
native-dialog |
<dialog> |
aster-dialog |
native-details |
<details> |
aster-disclosure inside text, aster-section, aster-accordion |
native-progress |
<progress> |
aster-progress-status |
native-form |
<form> |
aster-form |
role-… |
Hand-made ARIA widgets: tabs, menus, listboxes, comboboxes, trees, grids, dialogs, switches and toolbars | The matching element |
Radio inputs, ranges, file inputs, links, headings and layout elements have no
Aster replacement and aren't flagged. A panel a host gives role="tabpanel"
for aster-tabs is expected and isn't flagged either.
In CSS files, <style> blocks, style attributes and lit css templates:
| Rule | Finds |
|---|---|
css-restyle |
Selectors that reach into Aster's own markup: an .aster-* class, a descendant of an Aster element that isn't the application's own content, or a pseudo-element on one. Also any property on an Aster element other than placing it: size, position, margin, and grid or flex placement. Its custom properties, such as --split-handle, may be set. |
css-colour |
Fixed colours: hex values, colour functions and colour names. A colour worked out from a token, such as oklch(from var(--aster-accent) l c h / .2) or color-mix() with tokens, is fine. |
css-font |
Font families and weights given directly instead of --aster-font-ui, --aster-font-figure and the --aster-weight tokens. @font-face rules are exempt. |
css-token |
Setting an --aster-* token outside a theme file passed with --theme. Component variables ([[constant:COMPONENT_VARS]]), such as --aster-window-header-height, may be set on one placement. |
Layout CSS that arranges the application's own regions is not checked. Styling
the application's own markup inside an Aster element, such as a renderer's
.status class in a grid cell, is the application's content and is allowed.
Silence a finding
When no Aster element fits, add a comment on the finding's line or the line above it, naming the rule and the reason:
<!-- aster-allow native-select: a native list of 400 time zones -->
<select name="zone">…</select>
// aster-allow native-button, native-input: the sign-in form posts natively
html`<form method="post"><input name="user"><button>Sign in</button></form>`;
/* aster-allow css-colour: the brand mark's fixed colour */
.logo { color: #0a5; }
A silence without a reason, with a rule name that doesn't exist, or with
nothing on its line or the next to silence is itself a problem. That keeps
silences meaningful as the code changes. --allowances lists them all with
their reasons. A silence that marks a missing element or property is worth
reporting, so Aster can fill the gap.