Roadless UI — Design System

Overview

This is the canonical reference for the visual language of the Roadless UI frontend. Every token, font, and component pattern described here is wired into the running app — the swatches and demos below render with the live theme.

Source of truth lives in nuxt.config.ts (theme tokens, font loader, Vuetify defaults) and components/inputs/ (the canonical input wrappers). Adding a new color, font, or input convention means updating those files first, then this page.

Color tokens

Colors are organized in two layers: a primitive palette (the raw colors that exist in the app) and semantic tokens (what components actually consume, each one pointing at a primitive). The semantic layer is the source of intent — if you're building UI, you pick a semantic token, never a primitive.

Vuetify exposes every semantic token as a named option for the color prop and as a CSS variable --v-theme-{name}, consumable in scoped styles via rgb(var(--v-theme-{name})).

1 · Primitive palette

Greens

Three working greens in the brand family.

Blues / navy

Browns

Warm-earth family. Sits alongside the forest greens and navy blues — used for warm text, decorative highlights, and warm surface tints.

Status palette

Reserved hues for state communication.

Gray scale

Five-step neutral scale, darkest → lightest. Replaces ~13 ad-hoc grays previously used across the app.

Surface tints

The pale background tints used for inline panels and step framing.

Accents

Raw colors that serve as high-contrast partners for the brand colors. Each is documented as a semantic token below and visualized with measured WCAG ratios in the Accent — contrast partners section.

2 · Semantic tokens

Actions

Chrome & branding

Status

Surfaces & structure

Consumed via the color prop on v-card or via CSS variables in scoped styles.

Text

Neutral text roles. Pick by emphasis level, not by color.

Warm text & highlight

Brown-family roles for warm text, decorative highlights, and warm surface backgrounds.

Path accent

A single token shared by all three paths. Splits later if per-path color differentiation is wanted.

Contrast accents

High-contrast partners locked to a specific base color — each accent's ratio is only meaningful when paired with its base, so use it only in that pairing. Measured ratios shown in the Accent — contrast partners section below.

Accent — contrast partners

A high-contrast partner for each brand color that can host one. Light accents pair with the dark bases; the one dark accent reads only on the very-light header-light. secondary is mid-tone, so its accent clears 3:1 for bold/large text only (not AA body); header-medium gets none — no accent reads on it. Each block renders the accent on its base with the measured WCAG ratio; colors are read live from the theme.

Typography

Inter is the default for all body and UI text. Merriweather Sans is opt-in via the .display-heading utility for hero / page-title use. Both are loaded by @nuxt/fonts (Bunny provider).

Roles

Live samples

Common emphasis classes

• font-weight-bold — strong emphasis
• font-weight-medium — semi-emphasis
• text-medium-emphasis — secondary / muted body text
• text-primary — primary-color text (links, headings on light surfaces)
• text-green-darken-3 — used in step header copy on the green tint

Spacing

Vuetify's 4px-base scale (m{a,t,r,b,l,x,y}-{0..16}, pa-*) is the standard. Use it.

Container max-widths used

Iconography

Material Design Icons (MDI) via @mdi/font and @nuxt/icon. Vuetify default set is mdi. Use <v-icon> for inline icons; sizes small / default / large / 32 / 40 / 48 are all in use.

Buttons

Global default VBtn: { rounded: 'xl' } gives every button extra-large pill corners.

Variants

Semantic colors

Sizes

Canonical step navigation

Outlined Back, spacer, flat large Next with right arrow. Used in every step in the comment flow.

Buttons vs cards for choices

Single-line actions get a v-btn. Multi-line selections (long descriptions, rich content) get a clickable v-card — see Cards § selectable.

Cards & surfaces

Variants

Selectable card

Used in path selection, persona picker, concern picker, argument picker. Selected state flips to color="primary" + variant="flat".

Form input wrappers

Five wrappers in components/inputs/ codify field semantics — type, autocomplete, inputmode, format-validation rules — so browsers and phone keyboards get the right autofill and layout. The first four wrap <v-text-field>; RoadlessTextInput wraps <v-textarea> and adds automatic content sanitization.

What each wrapper locks

API conventions

• v-model — modelValue: string; always returns string (never undefined)
• variant="outlined" is locked — no escape hatch
• label / placeholder default per type but are overridable
• :rules composes additively after the built-in required + format rules
• required / disabled / error pass through
• Anything else passes through to the inner Vuetify component via v-bind="$attrs"

RoadlessTextInput sanitization

Every value emitted by RoadlessTextInput runs through this normalization before reaching the model:

Live demo

Other Vuetify inputs (no wrapper)

Use v-checkbox, v-select, etc. directly with color="primary" and outlined variants where applicable.

Alerts

variant="tonal" dominates; border="start" is used on prominent banners.

Prominent banner

Compact validation alert

Modals

Six dialogs in components/modals/ share this skeleton: primary-tinted header bar, top-right close, scrollable body, action footer with primary button right-aligned.

<v-dialog v-model="open" max-width="800" scrollable>
  <v-card>
    <v-card-title class="bg-primary text-white">
      <v-icon class="mr-2">mdi-info-outline</v-icon>
      Modal title
      <v-spacer />
      <v-btn icon="mdi-close" variant="text" color="white" @click="close" />
    </v-card-title>
    <v-card-text class="pa-6"> ... </v-card-text>
    <v-card-actions>
      <v-spacer />
      <v-btn color="primary" variant="elevated" @click="close">Done</v-btn>
    </v-card-actions>
  </v-card>
</v-dialog>

Step pattern

Every step in components/steps/*Step.vue shares this three-piece structure: green-tinted header (color="step-tint") with icon + title, outlined content card with the form panel, and a card-actions row with back / next buttons. Centered with ma-auto at max-width="600" or "700".

Layout shell

Page composition

1. HeaderComponent — full-bleed banner, rotating images, 200/150/100 px responsive heights, background secondary.
2. v-container fluid — 3-column row: news sidebar (lg=3), main content (lg=6), optional resources sidebar.
3. FooterComponentLight or FooterComponentDark.

Mobile / desktop branching

Single route per page. Each pages/*.vue imports both components/desktop/<Page>View.vue and components/mobile/<Page>View.vue and switches on useDevice().isDesktop.

<template>
  <DesktopView v-if="isDesktop" ... />
  <MobileView v-else ... />
</template>

<script setup>
const { isDesktop } = useDevice()
</script>

Path naming

The comment flow has three paths. They currently share the single path color token (aliased to secondary); per-path color differentiation can be introduced later by splitting the token.

File references

• nuxt.config.ts — theme tokens, font loader, Vuetify defaults (incl. VBtn rounded='xl')
• assets/styles/global.css — body chrome, .display-heading, footer, briefcase indicator, accessibility media queries
• assets/styles/mobile.css — mobile typography utilities
• assets/styles/vuetify.scss — Vuetify body/heading family override (Inter)
• components/inputs/Roadless{Email,Name,Zip,Phone}Field.vue — text-input wrappers
• components/inputs/RoadlessTextInput.vue — textarea wrapper with sanitization
• components/layout/HeaderComponent.vue, FooterComponent{Light,Dark}.vue — page chrome
• components/steps/ContactInfoStep.vue — canonical step example
• components/modals/PathSelectionModal.vue — selectable-card pattern