# TFM aInventory - Design System

**Status**: ACTIVE | **Last Updated**: 2026-04-26
**Target**: Premium Industrial Fidelity (Sharp, Dense, High-Contrast)

---

## 1. Core Visual Principles
- **Aesthetics**: "Premium Industrial". Density must remain high.
- **Shapes**: **STRICT 0px border radius** (sharp corners) on all components.
- **Depth**: No box-shadows. Use tonal layers, borders (1px/2px), and contrast for depth.
- **Layout**: Main page containers MUST use `max-w-7xl`.

## 2. Typography Rules (MANDATORY)
Hierarchy is achieved ONLY via size and color.
- **NO BOLD FONTS**: Use `font-normal` (400) throughout the entire application.
- **NO UPPERCASE**: All text must be Title Case or Sentence Case. NEVER use `uppercase` or `toUpper`. But do not replace `toUpper` with `toLower` or `uppercase` with `lowercase` either, leave text in UI/UX as is.
- **NO ITALICS**: Italics are forbidden.
- **Letter Spacing**:
  - `headline-lg`: -0.02em
  - `headline-md/sm`: -0.01em
  - `label-md`: +0.05em
- **StatCard Rule**: Numeric values MUST match the exact text size of their corresponding labels (e.g., `text-base md:text-lg`).

## 3. Color System (Single Source of Truth)
All colors are defined in `frontend/colors.mjs`. **Hardcoded Tailwind colors (e.g., bg-blue-500) are FORBIDDEN.**

### Semantic Mapping
| Intent | Color | Value | Use Case |
|--------|-------|-------|----------|
| **Primary / Caution** | `primary` | #ffb781 | Primary actions, "Caution Orange", important warnings |
| **Secondary / Info** | `secondary` | #c8c6c5 | Secondary actions, hints, metadata |
| **Success / Healthy** | `tertiary` | #00e639 | Success status, "Scanner Ready", stock added |
| **Error / Destructive** | `error` | #ffb4ab | Errors, "Delete", low stock, offline |
| **Muted** | `muted` | #474746 | Disabled states, placeholders |

### Surface Tiers
- **Background**: #131313 (`bg-background`)
- **Surface**: #1c1b1b (`bg-surface`)
- **Outline**: #a48c7c (`border-outline`)
- **Outline Variant**: #564335 (`border-outline-variant`)

## 4. Spacing & Grid
Base unit: **4px**.
- **Gutter**: 16px (`gap-4`)
- **Margin**: 32px (`p-8` / `m-8`)
- **Stack-SM**: 8px (`space-y-2`)
- **Stack-MD**: 16px (`space-y-4`)

## 5. Components & Icons
- **Iconography**: Use **Lucide Icons** exclusively. Size: 20px (default), 16px (compact).
- **Unified Headers**: Icon box (`p-4 bg-primary/10 border-primary/20`) + Title (`text-3xl font-normal`).
- **Buttons**:
  - Primary: `bg-primary text-on-primary`
  - Secondary: `bg-secondary text-on-secondary`
  - Destructive: `bg-error text-on-error`
  - All: `hover:opacity-80 transition-all active:scale-95`

## 6. Z-Index Scale
- `z-10`: Local stacking (hover states)
- `z-20`: Cards, modals (low)
- `z-30`: Dropdowns, tooltips
- `z-40`: Fixed navigation (BottomNav)
- `z-50`: Full-screen overlays (Scanner, AIOnboarding)
- `z-[100]`: Toasts, critical alerts