shopdb-flask/frontend/CLAUDE.md

Frontend Development Standards

Naming Convention (LOCKED)

The shopdb-flask naming convention lives in the root CONTRIBUTING.md. Read it before naming any variable, component, API param, or CSS class.

Frontend-specific reminders pulled from the convention:

• Variables holding API field values: match the API field name exactly. Do NOT convert to camelCase. (response.machineid, NOT response.machineId)
• Pure JS variables: camelCase (currentUser, isLoading)
• Vue components: PascalCase, spelled out (AssetDetail.vue, MachineForm.vue)
• CSS classes: lowercase with dashes (asset-detail, machine-form)
• API params sent to backend: match DB column names without underscores (params.locationid = 5, NOT params.location_id)
• No emojis, em-dashes, smart quotes, or Unicode arrows anywhere. Plain ASCII only.
• Banned shorthand as standalone variables: cfg, ctx, mgr, req, res, env, util, helper. Spell them out (canvasContext, response, manager, etc.). Suffix usage like printers_bp is allowed.

Pre-commit hook at scripts/check-naming-and-style.sh enforces these rules.

CSS Styling Standards

Use CSS Variables for ALL Colors

NEVER hardcode colors in component styles. Always use CSS variables defined in src/assets/style.css.

Available variables:

--primary       /* Primary brand color */
--primary-dark  /* Darker primary for hover states */
--secondary     /* Secondary/muted color */
--success       /* Success states (green) */
--warning       /* Warning states (orange) */
--danger        /* Error/danger states (red) */
--bg            /* Page background */
--bg-card       /* Card/panel background */
--text          /* Primary text color */
--text-light    /* Secondary/muted text */
--border        /* Border color */
--link          /* Link color (bright blue in dark mode) */

Bad:

.my-card {
  background: white;
  color: #1a1a1a;
}

Good:

.my-card {
  background: var(--bg-card);
  color: var(--text);
}

Detail Pages - Use Global Styles

All detail pages (MachineDetail, PCDetail, PrinterDetail, ApplicationDetail) should use the unified global styles from style.css:

• .detail-page - Container wrapper
• .hero-card - Main hero section with image and info
• .hero-image, .hero-content, .hero-title, .hero-meta, .hero-details
• .section-card - Info sections
• .section-title - Section headers
• .info-list, .info-row, .info-label, .info-value
• .content-grid, .content-column - Two-column layout
• .audit-footer - Created/modified timestamps

Only add scoped styles for page-specific elements (e.g., supplies grid for printers, version list for applications).

PrinterDetail.vue is the Master Template for Detail Pages

Use PrinterDetail.vue as the reference for new detail pages. Follow its structure and styling patterns.

List Pages - Use Global Styles

All list pages should use the unified global styles from style.css:

• .page-header - Header with title and action button
• .filters - Search and filter controls
• .card - Main content container
• .table-container - Scrollable table wrapper
• table, th, td - Table styling
• .pagination - Page navigation
• .badge, .badge-success, etc. - Status badges
• .actions - Action button column

PrintersList.vue is the Master Template for List Pages

Use PrintersList.vue as the reference for new list pages. It has NO scoped styles - everything uses global CSS.

Only add scoped styles for page-specific elements (e.g., icon cells for applications, stats badge for knowledge base).

Dark Mode Support

Dark mode is automatic via @media (prefers-color-scheme: dark). Using CSS variables ensures colors adapt automatically - no extra work needed per page.

Data Entry: Page or Modal

Both patterns are in use on purpose. Pick by what the record IS, not by how big the form feels today.

Routed form page (views/<Thing>Form.vue + a route) when the record has its own detail page and its own URL: machines, PCs, printers, network devices, measuring tools, USB devices, applications, knowledge-base articles, notifications, printed items. These forms are long, often carry an image upload, a map-position picker or relationship editing, and someone will want to link straight to one.

Modal over its list when the record is reference data that only exists inside the list it belongs to: every *TypesList, plus locations, vendors, models, VLANs, subnets, support teams, custom fields, API tokens, printer drivers, dashboard defaults. The form is a handful of fields, and keeping the list visible behind the dialog is the point.

Rule of thumb: a thing with a detail page gets a form page; a lookup row gets a modal.

Modal rules (from the overlay-close fix, commit d8fe0a4):

• A modal holding typed input must NOT close on overlay click or Escape. Losing a part-filled form to a stray click is not an acceptable failure.
• A confirmation dialog MAY close on overlay click (@click.self), since it holds nothing to lose.
• The panel background is var(--bg-card-solid), never var(--bg-card): the card variable is translucent in dark mode, which leaves a dialog see-through over the overlay. The shared .modal in style.css already does this; hand-rolled .modal-panel rules must too.

Component Organization

• Global styles: src/assets/style.css
• Page-specific styles: Scoped <style scoped> block, only for unique elements
• Font sizes: Use rem units, base is 18px for readability on 1080p

File Structure

src/
  assets/
    style.css          # Global styles, CSS variables, detail page styles
  views/
    machines/
      MachineDetail.vue   # Uses global styles only
    pcs/
      PCDetail.vue        # Global + PC-specific (app-list, etc.)
    printers/
      PrinterDetail.vue   # Global + printer-specific (supplies-grid)
    applications/
      ApplicationDetail.vue  # Global + app-specific (version-list, pc-list)