ADR-0069: Shared UI components take the rental look from the theme boundary

Status

Accepted (2026-09-27)

Tags

rental, solidstart, ui, design-system, theming, css, tailwind, glass, adr-0063

Decision

packages/ui serves two design systems: Panel (glass) and Rental (flat, “The Open Door”, frontend/solidstart/apps/rental/DESIGN.md). A shared component picks its look from where it renders, not from a prop the caller must remember.
  • Every rental screen renders inside RentalThemeBoundary / RentalLayout, which sets the --rental-* CSS variables for the active role (landlord or tenant) and light/dark mode.
  • A shared component calls useRentalAppearance(() => local.appearance). Inside a boundary it returns true and the component uses rental styling. Outside, it keeps the Panel look. appearance="rental" still forces rental outside a boundary; on Card, appearance="default" opts out. Wired today: Card (+ Header/Footer), Button, Input, Textarea, Badge, Table parts, Modal.
  • Rental styling that a page may override is written as Tailwind utilities merged with cn() (Card). Styling a page never overrides stays in rentalAppearance.module.css (Button, Input, Badge tones, Table). The module file is unlayered CSS, so it always beats Tailwind utilities; that is only safe where call-site overrides are not expected.
  • Rental pages use only --rental-* variables for colour, e.g. text-(--rental-muted), bg-(--rental-warning-soft). The variables switch for dark mode, so rental code has no dark: colour classes. Status colours are shared tones (--rental-{success,warning,danger,neutral}-soft and --rental-on-…), identical for both roles.
  • apps/rental/src/rentalStyleGuard.test.ts fails on glass, backdrop-blur, or raw palette classes (slate-, teal-, emerald-, …) in rental source, with no exception list.

Why

The portal moved out of Panel (ADR-0063) but kept Panel’s components. Newer slices were built in the Panel style, so about 40 rental files carried glass cards and raw Tailwind colours, and landlord teal appeared on tenant screens. The opt-in prop was the cause: every screen that forgot appearance="rental" silently got glass. A second defect hid behind the first. Rental Card styles lived in the unlayered CSS module, which beats every Tailwind utility. Pages that asked for a tinted or danger-bordered card (bg-(--rental-accent-soft), border-(--rental-danger)) rendered plain white.

Considered options

  • Keep the opt-in prop. Rejected: it is what failed. Nothing reminds the caller.
  • One set of semantic variables for both apps (components read --card-bg, --card-blur; Panel sets glass values, Rental flat ones). The cleanest end state, but it rewrites every Panel style for no Panel benefit. Revisit if a third design system appears.
  • Separate component libraries per app. Rejected: duplicates behaviour, focus handling, and accessibility work that is identical in both.

Consequences

  • Panel is unchanged: no boundary, no rental styling. Verified by Panel’s 259 tests.
  • Every existing rental Card now takes the rental look even without the prop, and page-level tone classes on rental cards now take effect (four screens were silently broken before).
  • New shared components that render in rental must call useRentalAppearance, and must put overridable styling in utilities, not the CSS module.
  • All rental source was migrated slice by slice on 2026-09-27; the guard keeps it that way.