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:

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:

// 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:

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:

/* 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.