Frontend Rules

Frontend Rules & Conventions

Reference guide for all frontend code in packages/frontend/. Read this before writing or modifying frontend components.

General

• All file names use kebab-case (e.g., reminder-form-dialog.vue, use-submit-transaction.ts)
• All components use <script setup lang="ts">
• Use TypeScript — no any unless absolutely unavoidable
• Use date-fns for all date formatting and manipulation. Never use raw Date methods or other date libraries
• Magic numbers: when a numeric literal's meaning isn't obvious from context, extract it into a descriptive constant (e.g., const MAX_VISIBLE_TAGS = 5). Simple, self-evident values (array indices, 0/1 checks, common multipliers, etc.) are fine inline — use your judgement

Project Structure

API layer

All API call functions live in src/api/. Components and composables must import from there — never inline fetch or axios calls directly in components.

Component placement

• Shared / reusable components go in components/common/ or components/lib/
• Page-specific components go in pages/<feature>/components/

Route constants

Route paths are defined as constants in routes/constants.ts. Always use those constants for router.push() and <RouterLink :to="...">. Never hardcode path strings.

Responsive breakpoints

The project defines CUSTOM_BREAKPOINTS and provides the useWindowBreakpoints composable. Use those for JS-based responsive logic — never use custom media queries or magic pixel values.

Container queries for content-area layout

The app has a ~300px sidebar visible on screens wider than 768px, so the content area is significantly narrower than the viewport (e.g., 900px screen = ~600px content). Viewport breakpoints (md:, lg:) don't account for this and can produce wrong results for content layout.

Prefer CSS container queries (@container) when the layout depends on the available content width — multi-column grids, card arrangements, etc. Use Tailwind's named container syntax:

<!-- Parent: define the container -->
<Card class="@container/my-section max-w-4xl">
  <!-- Child: query the container width, NOT the viewport -->
  <div class="grid grid-cols-1 @sm/my-section:grid-cols-2">
    ...
  </div>
</Card>

Container queries aren't needed everywhere — use judgement:

• Container queries (@container): multi-column grids, card layouts, anything where the sidebar makes viewport breakpoints inaccurate
• Viewport breakpoints (md:, lg:): showing/hiding the sidebar, header layout, simple show/hide toggles that genuinely depend on screen size
• useWindowBreakpoints: JS-based responsive logic — toggling components, conditional rendering based on device class

Testing

All computation functions, services, utils, and helpers must have unit tests to verify their logic. If you create or modify a pure function (formatting, calculation, transformation, validation), write or update a corresponding unit test.

Styling

• Use Tailwind CSS for all styling — avoid custom CSS unless absolutely necessary
• Never use default Tailwind colors directly (e.g., text-red-500, bg-blue-200). Always use the project's color variables defined in packages/frontend/src/styles/global.css
• If no existing color fits, tell the user about it and suggest adding it to global.css rather than using raw color values
• Use cn() utility from @/lib/utils for conditional class composition. Never use manual string concatenation for dynamic classes

Amount colors

Text/icon color vs. fill color

Semantic colors come in pairs: the base token is a fill (button/badge backgrounds, with *-foreground for the label on top), and the *-text token is the tint tuned for text and icons sitting directly on the page/card background. Icons count as text here — lucide icons inherit currentColor.

• Never use text-primary or text-destructive to color text or icons. Fill tokens are tuned so a white label passes contrast on top of them, which makes them too low-contrast as text on the dark theme (this is why --primary-text exists as a separate, brighter tint in dark mode)
• Tinted chips like bg-primary/10 still count as a dark background — text/icons inside them use text-primary-text
• Borders, strokes (progress rings), and chart lines may keep using the base token — non-text UI parts only need 3:1 contrast

Components

Buttons

Always use the project's Button component (@/components/lib/ui/button). Never use raw <button> elements.

Available variants: default, destructive, outline, secondary, ghost, ghost-destructive, soft-destructive, ghost-primary, soft-primary, success, outline-success, ghost-success, soft-success, link

Available sizes: default, sm, lg, icon, icon-sm

Button is inline-flex with gap-2, so spacing between its children (icon + label, multiple icons, etc.) is handled by the button itself. Do not add mr-* / ml-* / space-x-* to icons or text inside a Button — it doubles the gap and looks off.

<!-- WRONG — gap-2 already spaces the icon from the label -->
<Button><PlusIcon class="mr-2 size-4" /> Add item</Button>

<!-- CORRECT -->
<Button><PlusIcon class="size-4" /> Add item</Button>

Form fields

Always use the project's field components from @/components/fields/. Never use raw <input>, <select>, or <textarea> elements.

Placeholders are required

Every form field must have a :placeholder set. An empty input or an empty select with only a label leaves the user guessing what to enter or pick (especially in dialogs that open with no prefilled value). The placeholder should be a concrete prompt — "Enter payee name", "Select a category", "DD/MM/YYYY" — not a restatement of the label.

Always wire placeholders through i18n (:placeholder="$t('...')"); never inline raw English strings.

Icons

Always use @lucide/vue icons. Never use raw SVGs or other icon libraries. Do not use lucide-vue-next — that's the old package and has been replaced.

Always import icons with the Icon suffix — e.g., CircleCheckIcon, Trash2Icon, ChevronDownIcon. Never use the short form without the suffix.

<!-- WRONG -->
import { CircleCheck, Trash2 } from '@lucide/vue'
<CircleCheck />

<!-- WRONG — old package -->
import { CircleCheckIcon, Trash2Icon } from 'lucide-vue-next'

<!-- CORRECT -->
import { CircleCheckIcon, Trash2Icon } from '@lucide/vue'
<CircleCheckIcon />

Scroll areas

Always use the ScrollArea component (@/components/lib/ui/scroll-area) for scrollable containers. Never use raw overflow-auto / overflow-y-scroll divs. Adding the ScrollArea's id to a global variable is not needed unless there's a concrete use case for it.

Checkbox

The project's Checkbox component (@/components/lib/ui/checkbox) uses modelValue / update:modelValue, not checked / update:checked. Always bind with :model-value and @update:model-value (or v-model).

<!-- Correct -->
<Checkbox :model-value="form.notifyEmail" @update:model-value="(val) => (form.notifyEmail = !!val)" />

<!-- Also correct -->
<Checkbox v-model="form.notifyEmail" />

<!-- WRONG — will silently do nothing -->
<Checkbox :checked="form.notifyEmail" @update:checked="..." />