dev_arc_aws/design-decisions.md

ArchNest — Design Decisions & Lessons Learned

This file captures all visual/UX decisions made during Glance page development. Apply these consistently to ALL future pages to avoid repeated iteration.

---

Global Rules (Apply to Every Page)

Sidebar

• Expanded width: 200px (matches mockup proportions — needs room for labels)
• Collapsed width: 64px (icon only)
• User can manually collapse/expand via toggle button (not just responsive)
• Main content margin-left must match sidebar width exactly

Page Title (Top Bar)

• Color: Gold (#C8A434) — NOT white. Use inline style={{ color: '#C8A434' }} if Tailwind class doesn't apply
• Font: 18px, bold, uppercase, tracking-wide
• No border on top bar — blends into the page background

Colors — Use Inline Styles When Tailwind Fails

• Tailwind v4 @theme custom colors (text-gold, bg-card, etc.) may not always apply
• If a color isn't rendering correctly, fall back to inline style={{ color: '#C8A434' }}
• Always verify visually after changes

Content Alignment

• All rows must share the same horizontal padding (px-6 applied once at the parent container level)
• Do NOT use different padding for different rows — this causes misalignment
• The hero banner, status cards, middle row, and bottom row must all line up left and right edges

Hero Banner + KPI Overlap

• Banner height: 200px
• Status cards overlap via negative margin: -mt-12
• Banner image: object-cover with object-position: center 25% (show the top/skyline, not center)
• Cards use backdrop-blur-sm and bg-card/95 for glass effect over the banner

KPI Card Sizing

• KPI 1 (System Status) and KPI 4 (Network): wider — 1.3fr
• KPI 2 (Infrastructure) and KPI 3 (Security): standard — 1fr
• Grid: grid-cols-[1.3fr_1fr_1fr_1.3fr]
• Cards have compact padding: p-4 (not p-5 or p-6)

No Footer

• The mockup does NOT have a footer/status bar
• Do not add one unless explicitly requested

Target Display

• Primary design target: 16-inch screen / 1920px width
• Lots of horizontal space available — don't constrain content width unnecessarily
• Design should feel spacious, not cramped

Typography Sizes (smaller than default)

• Card titles: 10-11px, uppercase, tracking-[1.5px], secondary color, font-medium
• Large numbers: 24-28px, bold, primary color
• Subtitles/labels: 10-11px, secondary color
• Body text in lists: 13px, primary color
• Timestamps: 11px, secondary color
• Breakdowns: 9-10px, secondary color

Animations

• Card hover: border → gold, 0.2s ease
• Progress ring: animates from 0 to value in 1s
• Sparklines: draw animation 1s
• Progress bars: fill animation 0.8s

Icons

• Source: Lucide React (imported per component, tree-shaken)
• Size: 14-18px depending on context
• Color: gold for active/accent, text-secondary for inactive
• Gold glow on active sidebar items: shadow-[0_0_6px_rgba(200,164,52,0.5)]

---

Page-Specific Notes

Glance Page

• No footer
• Status cards overlap hero banner
• Middle row: 3 equal-ish columns (30/40/30)
• Bottom row: 2 columns (65/35)
• Network Traffic card has its own background image at low opacity
• User avatar dropdown has: Profile, Appearance, Security, Help & Support, Sign Out

---

Future Integration Notes

Live Provider Data (AWS, Linode, etc.)

• All KPI/status card data (resource counts, health, pricing, budgets, cost breakdowns, utilization, regions/map data) is currently mocked/static.
• The Infrastructure page (and likely Glance) should eventually integrate with real cloud provider APIs — AWS, Linode, or any other VPC/cloud provider — via user-supplied API keys, to pull live data such as:
  • Resource inventory/counts and health status
  • Pricing and budget/cost data (replacing the static Cost Breakdown numbers)
  • Resource utilization metrics
  • Region/datacenter info for the Infrastructure Map
• Design the data layer so it's provider-agnostic (a common interface/adapter per provider) since users may connect more than one provider's API key.