tfm_ainventory/DESIGN-TYPOGRAPHY-HIERARCHY.md

# Design: Typography & Visual Hierarchy Overhaul

Generated by /gstack-office-hours on 2026-04-19
Branch: dev
Repo: tfm_ainventory
Status: DRAFT
Mode: Builder (Intrapreneurship)

## Problem Statement

The current UI has weak visual hierarchy on tablets and larger screens. While fonts are technically readable, they don't guide the eye — secondary info competes with primary info for attention. Users are forced to hunt for the information they need rather than seeing it immediately.

**Example:** Inventory item name (what you're looking for) is `text-base md:text-lg` (18px). The category label next to it is almost the same size. Which is more important? The UI doesn't say.

## Current State

**Typography scale (Tailwind defaults):**
- Labels/metadata: `text-xs` to `text-base` (12–16px)
- Headings: `text-lg` to `text-xl` (18–20px)  
- Values/highlights: `text-2xl` to `text-3xl` (24–30px)
- Page titles: `text-3xl` to `text-4xl` (30–36px)

**Problem:** This scale flattens on tablets. A 18px label looks like a headline. A 30px value looks like a label. The hierarchy collapses.

## Premises

1. **Font size alone doesn't create hierarchy.** Weight, color, spacing, and contrast matter more than raw pixels.
2. **Tablet is a first-class device.** The app is used on iPads in warehouses. Design for that, not just mobile.
3. **Visual hierarchy = faster task completion.** If the user sees the item quantity immediately, they spend 0.5 seconds scanning. If they hunt, it's 3 seconds per item. Over 100 items, that's 4 minutes lost per session.
4. **We don't need bigger type everywhere.** Secondary info can stay small IF it's visually subordinate (lighter weight, muted color, less prominence).

## Open Questions

- What's the primary use case breakdown? Mostly mobile in the field, mostly tablet in warehouse, or mixed 50/50?
- Do users ever need to scan and read fine details simultaneously (e.g., zoom control labels)?
- Is there a standard tablet size we're optimizing for (iPad 10.2", iPad Pro 12.9", or both)?

## Approaches Considered

### Approach A: Scale Everything Proportionally (Simplest)

**Summary:** Increase base font sizes across all Tailwind scales uniformly. `text-base` → `text-lg`, `text-lg` → `text-xl`, etc. On tablets, everything gets bigger, hierarchy stays the same.

**Effort:** S (one config change to tailwind.config.ts, maybe 15 min)

**Risk:** Low

**Pros:**
- One-line fix in Tailwind config
- Consistent everywhere
- Easiest to test and verify
- No refactoring needed

**Cons:**
- Doesn't actually improve hierarchy — just makes things bigger
- Wasteful on mobile (text gets huge, less content per screen)
- Doesn't address the real problem: weak contrast between important and unimportant info
- Secondary info still competes for attention, just in a bigger font

**Reuses:** Tailwind's built-in scale

**Implementation:** Extend `fontSize` in tailwind.config.ts:
```javascript
extend: {
  fontSize: {
    'xs': '14px',   // was 12px
    'sm': '15px',   // was 14px
    'base': '18px', // was 16px
    'lg': '21px',   // was 18px
    // ... etc
  }
}
```

---

### Approach B: Responsive Scale + Weight-Based Hierarchy (Recommended)

**Summary:** Keep mobile readable, boost tablet sizes moderately. More importantly, use **font weight** (not just size) to create hierarchy. Primary info is bold/heavy; secondary is regular/light. Add color emphasis (primary color for key values).

**Effort:** M (audit components for hierarchy, add weight/color rules, test on device, ~2 hours)

**Risk:** Medium (changes visual feel, needs design review)

**Pros:**
- Mobile stays readable (no bloat)
- Tablets get 20-30% bigger type
- Weight creates REAL hierarchy instantly (user's eye goes to bold text)
- Pairs with color (key values in primary color, metadata in muted gray)
- Feels intentional, not lazy
- Works across all screen sizes

**Cons:**
- Requires auditing every component (20+ files)
- Needs design review to ensure consistency
- More moving parts to get right
- Testing on actual tablets essential

**Reuses:** Tailwind's weight classes, existing color system

**Implementation Pattern:**
```jsx
// OLD: No hierarchy
<span className="text-lg text-secondary">Item Name</span>
<span className="text-lg text-muted">Category</span>

// NEW: Clear hierarchy
<span className="text-lg md:text-xl font-bold text-white">Item Name</span>
<span className="text-sm md:text-base font-normal text-muted">Category</span>
```

**Tablet-specific rules:** Add responsive weights:
```javascript
extend: {
  fontSize: {
    'sm': ['14px', { lineHeight: '1.5' }],
    'base': ['16px', { lineHeight: '1.6' }],
    'lg': ['18px', { lineHeight: '1.6' }],
    'xl': ['20px', { lineHeight: '1.5' }],
  }
}
```

---

### Approach C: Fluid Typography + Dynamic Scaling (Future-proof)

**Summary:** Use CSS custom properties (variables) to scale type fluidly from mobile → tablet → desktop. Type size increases as viewport width increases, without discrete breakpoints. Add hierarchy through weight, spacing, and contrast.

**Effort:** L (requires CSS architecture change, build TypeScript scale generator, test thoroughly, ~4 hours)

**Risk:** High (new tooling, requires testing on 3+ device sizes)

**Pros:**
- Scales beautifully on ALL viewport sizes (not just mobile/md/lg breakpoints)
- Future-proof (works on foldables, 5" phones, 27" displays)
- Hierarchy through weight + color, not just size
- Professional feel (type gets more generous as screen gets bigger)
- One source of truth (single scale definition)

**Cons:**
- Adds build-time complexity (need a script to generate scales)
- CSS custom properties have limited browser support (but fine for modern browsers)
- More moving parts, harder to debug
- Needs comprehensive testing
- Overkill if app is only mobile + tablet

**Reuses:** Tailwind, but adds custom CSS layer

**Implementation idea:**
```css
/* Define fluid scale as CSS variables */
:root {
  /* At 375px (mobile), base = 16px. At 1440px (desktop), base = 18px. */
  --font-base: clamp(16px, 2.5vw, 18px);
  --font-lg: clamp(18px, 3vw, 20px);
  --font-xl: clamp(20px, 3.5vw, 24px);
}

/* Use in components */
.text-base { font-size: var(--font-base); }
.text-lg { font-size: var(--font-lg); }
.text-xl { font-size: var(--font-xl); }
```

---

## Recommended Approach: B (Responsive Scale + Weight-Based Hierarchy)

**Why:** 
- Solves the real problem (hierarchy, not just size)
- Effort-to-impact ratio is excellent
- Works across all devices without bloat
- Uses tools already in the design system
- Reviewable component-by-component (low risk of breaking things)

**Concrete next step:**
1. Audit InventoryTable, StatCard, LogsTable, Scanner controls for hierarchy
2. Add weight rules: primary data `font-bold`, metadata `font-normal`
3. Add color: primary values in `text-primary` or `text-white`, secondary in `text-muted`
4. Test on iPad (actual device or browser dev tools)
5. Review with user on actual tablet to verify readability

---

## Success Criteria

- **Tablet test (10.2" iPad):** User can read item names, quantities, and key metadata without squinting at normal viewing distance (12-18 inches)
- **Hierarchy test:** In a list of 20 items, user can identify which is the primary info (name/quantity) in <1 second without searching
- **Mobile preservation:** iPhone 14 screen still shows useful content (no excessive whitespace)
- **Consistency:** Same typography rules applied across Scanner, Inventory, Admin, Logs pages

---

## Distribution Plan

No new dependencies or build system changes (unless Approach C chosen).
Changes ship in the existing `dev` branch → `master` on next release.

---

## Dependencies

- Tailwind CSS (already in use)
- Design review from user on tablet device (essential)
- Testing across: iPhone 12+, iPad 10.2", iPad Pro 12.9" (ideally)

---

## The Assignment

**Before next office hours:** 
1. Load the app on an actual tablet (iPad or comparable).
2. Open the Inventory page, Scanner page, and Admin Dashboard.
3. Note 3 specific screens or components where you think hierarchy is weakest (e.g., "StatCard mixes label and value with equal prominence").
4. Bring those examples to the next session — we'll design the weight/color fixes together with visual mockups.

This turns abstract ("fonts are small") into concrete ("here's where I get lost").

---

## What I Noticed About How You Think

- You didn't say "make fonts bigger" — you said "better visual hierarchy." That's a designer's instinct, not an engineer's kneejerk response. You're thinking about information clarity, not pixel counts.
- You identified the problem on tablets specifically, not mobile. That's precise observation. Most people would have said "everywhere," but you know your actual use case.
- When asked what success looks like, you said hierarchy, not size. That shows you understand that **hierarchy IS the usability feature.** Big text that's all the same weight is just... big, hard-to-read text.

You're thinking like a product person. Keep that going.