0017: Vuetify, and Vuetify first

Status:

Accepted

Date:

2026-10-19, extended 2026-10-20

Context

The catalog’s screens need list, filter and table-like components, and Material Design is acceptable for an internal governance tool. A desktop UI review later found contrast, alignment and prominence defects, many caused by hand-written CSS fighting the component library.

Decision

Use Vuetify (stack-fastapi-vuetify) rather than headless components with plain CSS. Express every visual change with Vuetify’s own mechanisms, stopping at the first that works:

  1. theme colours and variables (plugins/vuetify.ts);

  2. global defaults and aliases in createVuetify;

  3. <v-defaults-provider> for one region;

  4. component props and utility classes;

  5. Vuetify SASS settings.

Custom scoped CSS is the last resort, may use only theme variables, and each rule carries a comment saying why steps 1 to 5 could not express it. Further rules from the same review: one page width for every route, status chips only when they differ from the default, strong colour only for issues and rejection, the light/dark/system theme following the OS by default, and the MD3 type scale with self-hosted Roboto.

Consequences

  • Frontend guard tests fail on retired MD2 typography classes, literal colours in style blocks, unjustified style rules, and theme text pairs below 4.5:1 contrast.

  • The rule is repeated in the repository’s CLAUDE.md.