Every framework widget — form fields, the submit button, active search,
autocomplete, the nav bar, breadcrumbs, hero banners, modals, tabs, pagination,
property lists, direct-to-storage upload, and job status — renders a semantic
autumn-* class (autumn-field, autumn-nav, autumn-modal, …), documented on
each widget's rustdoc. Historically the CSS backing those classes lived
copy-pasted in every app's Tailwind input.css; as of #1215 the framework ships
it itself, as one stylesheet, the same way it already ships
flash message styling.
Link it once
link rel="stylesheet" href=(autumn_web::ui::WIDGETS_CSS_PATH);
autumn new and the generators add this for you. It is served as a same-origin
asset (/static/css/autumn-widgets.css, immutably cached) — not inline styles —
so it works under a strict style-src 'self' Content-Security-Policy, and it is
embedded in release builds (--embed) with no loose files to ship.
No Tailwind build step is required to get styled widgets: the stylesheet is
plain CSS, not @apply rules, so linking it is enough even in a non-Tailwind
app.
Widget families
The widgets are in families. The core widgets (layout, navigation,
feedback and data display) need only the maud feature. Four families have
their own feature. All four are in default.
| Feature | Widgets | CSS file |
|---|---|---|
widgets-search | active_search, autocomplete_input | ui/widgets/search.css |
widgets-social | reaction_controls, comment_thread, infinite_feed | ui/widgets/social.css |
widgets-workflow | transition_controls, bulk_actions_form | ui/widgets/workflow.css |
widgets-charts | sparkline, bar_chart, line_chart | ui/widgets/charts.css |
The server joins the core rules (ui/widgets.css) and the CSS of each enabled
family into the one stylesheet. The URL does not change. The script bundle
(/static/js/autumn-widgets.js) works the same way: the search runtime is in
it only with widgets-search.
To compile and ship only the core, turn default features off and name the families you use:
autumn-web = { version = "0.11", default-features = false, features = ["maud", "htmx", "widgets-search"] }
The #[commentable] router renders comment_thread, so it needs
widgets-social.
Design tokens
The widget stylesheet uses the design tokens in autumn_web::ui::tokens. The admin plugin, the actuator dashboard and the error pages use the
same tokens.
| Group | Tokens |
|---|---|
| Surface | --bg, --surface, --surface-muted, --border, --control-border |
| Text | --text, --text-muted |
| Accent | --primary, --primary-hover, --primary-light, --on-primary |
| Status | --danger*, --on-danger, --success*, --warning*, --info* |
| Space | --space-1 … --space-8 (0.25rem … 2rem, scaled by density) |
| Type | --font-size-xs … --font-size-2xl, --font-weight-*, --line-height-*, --font-family, --font-mono |
| Radius | --radius-sm, --radius-md, --radius-lg, --radius-full, --radius |
| Z-index | --z-dropdown, --z-sticky, --z-banner, --z-toast (only without JS: the runtime puts the toast region in the top layer), --z-tooltip (only without the Chromium top layer) |
| Breakpoints | --breakpoint-sm … --breakpoint-xl |
--on-primary and --on-danger are the text colors on a --primary or a
--danger fill. Do not use white text on a fill: in the dark scheme the fill
is light.
--control-border is the border of a text input. It has 3:1 contrast on
every surface in both schemes (WCAG 1.4.11). --border is for decoration.
The breakpoint tokens are for reference only. @media cannot read var().
The stylesheet uses 768px for its one breakpoint, the same as
--breakpoint-md.
Dark mode
Each color token is light-dark(<light>, <dark>). The tokens set
color-scheme: light dark on :root, so the OS setting selects the scheme.
No JavaScript is necessary.
To set the scheme, put data-theme on <html>:
<html data-theme="dark"> <!-- or "light"; omit it to follow the OS -->
data-theme also works on a subtree. On a subtree, also set color and
background, because an inherited color can keep the parent scheme:
.promo[data-theme="dark"] { color: var(--text); background: var(--surface); }
A browser without light-dark() gets the light values.
A page with light-only colors of its own (for example Tailwind bg-gray-50
on <body>) must pin the light scheme. Otherwise a dark OS shows dark widgets
on a light page:
<html data-theme="light">
The widget script syncs data-theme from the cookie only on a page with a
toggle that posts to /_autumn/theme. Other pages keep their own
data-theme, even when the user picked "Dark" on another page.
Let the user select the theme
-
Merge the theme route into the app:
Rustautumn_web::app() .merge(autumn_web::ui::theme::router()) -
Read the cookie in the layout. Render
data-themeon<html>, so the first paint has the correct theme:Rustuse autumn_web::security::{CsrfFormField, CsrfToken}; use autumn_web::ui::theme::Theme; use autumn_web::widgets::{ThemeToggleConfig, theme_toggle}; fn layout( theme: Theme, csrf: Option<&CsrfToken>, field: Option<&CsrfFormField>, body: maud::Markup, ) -> maud::Markup { maud::html! { html lang="en" data-theme=[theme.data_theme()] { body { (theme_toggle(&ThemeToggleConfig::new(theme).csrf(csrf, field))) (body) } } } }Themeis an extractor. Addtheme: Themeto the handler arguments. Without the CSRF token, the no-JS post gets403. -
Load the widget script once in the layout:
Html<script src="/static/js/autumn-widgets.js" defer></script>With the script, a click applies the theme at once and sends no request. Without the script, the form posts to
/_autumn/theme. The route stores the cookie and redirects back.
The cookie is autumn.theme. It holds light or dark. "System" deletes it.
It is not HttpOnly, because the script writes it. The admin plugin reads
the same cookie.
To store the choice in a user profile, post to your own route with
.action("/settings/theme"). The script then applies the theme and lets the
form post. It does not write the cookie, and it does not change the
data-theme that your layout renders.
If a shared cache stores pages that read the cookie, send Vary: Cookie.
Density
Put data-density on <html> or on a subtree:
<main data-density="compact"> <!-- compact | comfortable | spacious -->
Density scales the --space-* tokens by 0.75, 1 or 1.25. Type sizes do not
change. autumn_web::ui::theme::Density has the three words.
Re-theme via tokens, not by forking the CSS
Override the tokens on :root in your own stylesheet. Load it after the
widget stylesheet. Use light-dark() to keep both schemes:
:root {
--primary: light-dark(#0369a1, #7dd3fc);
--primary-hover: light-dark(#075985, #bae6fd);
--on-primary: light-dark(#ffffff, #082f49);
--radius: var(--radius-sm);
}
A plain value (--primary: #0ea5e9;) sets the token for both schemes.
This changes the accent color and corner radius everywhere at once — the submit button, focus rings, the active tab underline, the current-page pager chip — without touching a single widget rule.
Override a specific widget
Every class is a normal, documented CSS hook — there's no ceiling. Override any rule in your own stylesheet (loaded after the widget stylesheet) the same way you would override a third-party component library:
.autumn-submit {
border-radius: 9999px; /* pill-shaped buttons, this app only */
}
Class names
Every widget class has the autumn- prefix. This includes the
alert, the badge and the wizard stepper:
| Old | New |
|---|---|
alert, alert-info … alert-error | autumn-alert, autumn-alert--info … autumn-alert--error |
alert__title, alert__body, … | autumn-alert__title, autumn-alert__body, … |
badge, badge--neutral … badge--danger | autumn-badge, autumn-badge--neutral … autumn-badge--danger |
wizard-progress, wizard-step, wizard-step--current, … | autumn-wizard-progress, autumn-wizard-step, autumn-wizard-step--current, … |
See the migration guide for the full map.
Coverage
A build-time test (autumn/tests/integration/widget_css_coverage.rs) scans
each widget source file for autumn-* classes. Each class must have a rule in
the stylesheet. A new class without a rule fails the build. A second test
fails when a widget emits, or the stylesheet styles, an old unprefixed class.
Contrast tests check the token pairs and the widget text in the light and the dark scheme against WCAG AA.
Migrating from a per-app input.css
If your app's input.css had its own @layer components block styling
autumn-* classes (the pattern autumn new generated previously), delete it —
the shipped stylesheet replaces it. Two things to check afterward:
- Accent color: the old copy-pasted block hardcoded an indigo accent
(
#4f46e5) independent ofui::tokens. The shipped stylesheet instead readsvar(--primary), so widgets now pick up whatever--primaryyour app (or the framework default, violet#7c3aed) resolves to. Restore the old accent by setting--primary: #4f46e5;(and--primary-hover,--primary-light) on:rootin your own stylesheet. - App-specific overrides: if your old block also carried bespoke colors or layout for one widget (a themed hero banner, a differently-colored breadcrumb link), re-add just those declarations to your own stylesheet, loaded after the widget one — see "Override a specific widget" above.