tfm_ainventory/DESIGN_SYSTEM.md

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