tfm_ainventory/frontend/styles/DESIGN_SYSTEM.md

TFM aInventory Design System

Z-Index Scale

Explicit z-index layering for consistent stacking context.

z-10   = Local stacking (shadows, hover states)
z-20   = Cards, modals (low-level)
z-30   = Dropdowns, tooltips
z-40   = Fixed navigation (BottomNav)
z-50   = Full-screen overlays (Scanner, AIOnboarding)
z-[100] = Toast notifications, alerts

Applied Locations:

• z-10: Interactive states, hover effects
• z-20: Modal backgrounds, card borders
• z-40: BottomNav fixed footer
• z-50: Scanner.tsx, AIOnboarding.tsx, full-screen UI
• z-[100]: Toast messages (react-hot-toast)

---

Spacing Scale

All spacing follows a consistent 4px baseline.

4px   = gap-1 (tightest)
8px   = gap-2
12px  = gap-3
16px  = gap-4 (default)
24px  = gap-6
32px  = gap-8
48px  = gap-12
64px  = gap-16

Applied Pattern:

• Use gap- utilities for sibling spacing
• Use p- for padding on containers
• Use m- sparingly (prefer gap)
• Never use arbitrary spacing (e.g., no gap-[13px])

---

Opacity Scale for Backgrounds

Consistent opacity for glass/translucent effects.

bg-slate-950/40   = Light transparency (hover states)
bg-slate-950/60   = Medium transparency (overlays)
bg-slate-950/80   = Heavy transparency (backdrop blur)
bg-slate-900/40   = Light glass (cards)
bg-slate-900/50   = Medium glass (borders)
bg-slate-900/90   = Heavy glass (panels)

Applied Locations:

• /40: Hover states, subtle layers
• /50: Card backgrounds
• /60-80: Modal backdrops
• /90: Solid-looking panels with slight transparency

---

Transition Timing

All interactive elements use consistent easing and duration.

transition-colors     = color changes (150ms)
transition-all        = all properties (200-300ms)
active:scale-95       = click feedback
hover:opacity-80      = hover feedback

Standards:

• Button state changes: transition-colors duration-200
• Major layout changes: transition-all duration-300
• Never use duration-0 or duration-1000 without reason
• Focus states: instant (no transition on ring)

---

Focus States

All interactive elements must be keyboard accessible.

focus:ring-2            = visible focus indicator
focus:ring-primary      = brand color on interactive elements
focus:ring-blue-500     = alternate for secondary buttons
focus:outline-none      = removes browser default

Applied to:

• All <button> elements
• All <a> elements (links)
• Form inputs (<input>, <textarea>, <select>)
• Custom interactive components (role="button", tabIndex)

---

Cursor States

Interactive elements must signal affordance.

cursor-pointer      = clickable button/card
cursor-not-allowed  = disabled state
cursor-default      = non-interactive

Applied Pattern:

<button className="cursor-pointer hover:... focus:ring-2 disabled:cursor-not-allowed">
  Action
</button>

---

Contrast Requirements

All text must meet WCAG AA minimum 4.5:1 contrast ratio.

Light Mode (if implemented):

• Body text: text-slate-900 (#0F172A) on white
• Secondary: text-slate-600 (#475569) on white
• Muted: text-slate-500 (#64748B) on white (only for labels)

Dark Mode (current):

• Body text: text-white on dark bg
• Secondary: text-slate-300 (#CBD5E1) on dark bg
• Muted: text-slate-500 (#64748B) on dark bg

Verified Combinations:

• ✓ white text on bg-slate-950
• ✓ text-slate-300 on bg-slate-900/50
• ✓ text-primary (#3B82F6) on dark backgrounds

---

Button States

Every button must implement all required states.

<button
  className="
    /* Default */
    bg-primary text-white rounded-lg font-semibold
    /* Hover */
    hover:bg-blue-600
    /* Focus */
    focus:ring-2 focus:ring-blue-500 focus:outline-none
    /* Active */
    active:scale-95
    /* Disabled */
    disabled:opacity-50 disabled:cursor-not-allowed
    /* Transition */
    transition-all duration-200
  "
  disabled={isLoading}
>
  Action
</button>

---

Icon Guidelines

• All icons from Lucide React (size 16-24)
• Never use emoji as UI icons
• Icon-only buttons require aria-label
• Icon size: size={20} (default), size={16} (compact), size={24} (prominent)

---

Form Elements

All form inputs require:

1. Associated <label> with htmlFor attribute
2. Clear focus states
3. Helpful placeholder text (optional, don't replace label)
4. Validation feedback

<label htmlFor="email" className="block text-sm font-semibold mb-2">
  Email Address
</label>
<input
  id="email"
  type="email"
  placeholder="you@example.com"
  className="
    w-full px-3 py-2 bg-slate-800 border border-slate-700 rounded-lg
    text-white placeholder:text-slate-500
    focus:border-primary focus:ring-2 focus:ring-primary
    transition-colors duration-200
  "
/>

---

Modal/Overlay Hierarchy

Predictable layering for overlays.

z-40  = BottomNav (fixed)
z-50  = Full-screen overlays (Scanner, AIOnboarding)
z-50+ = Nested modals (ConfirmationModal, ItemComparisonModal)

Backdrop colors:

• Scanner/AIOnboarding: bg-slate-950 (opaque)
• Modals: bg-black/40 (semi-transparent)

---

Migration Checklist

When implementing these standards:

• Add z-index only when necessary (nesting depth issue)
• Use spacing scale utilities (no arbitrary values)
• Add focus states to ALL interactive elements
• Add cursor-pointer to all clickable elements
• Verify transition duration is 150-300ms
• Test keyboard navigation (Tab, Enter, Escape)
• Verify contrast ratios (4.5:1 minimum)
• Check reduced motion preferences (prefers-reduced-motion)