Uikit

LFX Uikit

Reference for using and extending the LFX uikit component library in frontend/app/components/uikit/.

Rules — always apply these

0. Before writing ANY markup in a .vue file, stop and scan the quick reference table below first. This is the single most frequently skipped step. A raw <button>, <i class="fa-...">, or hand-rolled dropdown/spinner is very likely a uikit component you didn't check for. Do this check even when copying an existing component's markup as a starting point — existing files are not guaranteed to be in-convention (see rule 4).

1. Always check the uikit first. Before writing any UI element (button, icon, dropdown, input, modal, etc.) look up the relevant component below. If it exists, use it.

2. Extend, don't copy. If a component almost fits but lacks a variant or prop, add it to the component and its types file rather than building a one-off styled element.

3. Ask before creating new components. If no uikit component covers the need, describe what it would do and why nothing existing works — then wait for the user's decision before building.

4. No raw HTML equivalents. Never write:

   • <button> → use <lfx-button> or <lfx-icon-button>
   • <i class="fa-..."> → use <lfx-icon>
   • Custom dropdown panels with v-show + manual listeners → use <lfx-dropdown>
   • Custom spinner/skeleton HTML → use <lfx-spinner> / <lfx-skeleton>

   Exception: a handful of existing step components (e.g. fundraise-project-hosting-step.vue) use raw <button> for large custom card/tile layouts (icon + label + description + radio indicator) that aren't simple label+icon actions. Matching that specific pre-existing pattern for a genuinely equivalent card widget is fine — but simple action buttons (submit, cancel, remove, add-item, icon-only actions) must always use <lfx-button> / <lfx-icon-button>, never a raw tag, even if a nearby file does it wrong.

5. Never define types, interfaces, or constants inside .vue files. This includes local interface/type declarations, option arrays (e.g. const FOO_OPTIONS = [...]), and lookup records (e.g. const FOO_LABEL: Record<...> = {...}) declared in <script setup> — even ones scoped to a single component.

   • Types/interfaces belong in frontend/app/types/<domain>.types.ts. Import with import type { ... } from '~/types/...'. A component may re-export a type from the types file (export type { Foo };) only if external callers currently rely on that import path, but the canonical definition must live in app/types/.
   • Component-local constants (option lists, label/color/icon maps, default-value factories) belong in frontend/app/components/modules/<module>/config/<feature>.config.ts (see fundraise/config/initiative-types.config.ts for the pattern). Import them, don't inline them.
   • Finding a precedent for inlining in an older file (e.g. HOSTING_OPTIONS in fundraise-project-hosting-step.vue) is not a justification to repeat it — the convention is the config folder, and existing violations should not be copied into new components.

Quick reference

Loading the detailed reference

• references/components.md — props, slots, and usage examples for every uikit component