# Design Principles The master vision calls for a product that feels **modern, elegant, minimal, professional, calm, fast, confident** — "minimal, premium, professional, elegant, timeless." Those words only become useful once they're checkable rules a component either follows or doesn't. This document is that translation. ## 1. One accent color, used sparingly The palette (`02-design-tokens.md`) has exactly one accent color. It's used for primary actions and the handful of things that genuinely need to draw the eye (the Store Health Score, a primary button, an active nav item). Everything else is neutral. **Check:** if a screen has more than one saturated color competing for attention at once, it fails this rule. Semantic colors (success/warning/danger) are the one exception, and only ever apply to status, never decoration. ## 2. Borders over shadows Per the master prompt's explicit instruction to avoid excessive shadows: default surfaces (cards, table rows, list items) are separated with a **1px border**, not a drop shadow. Shadow is reserved for genuine elevation — something temporarily floating above the page (a modal, a dropdown, a toast) — never for a static card sitting in the normal page flow. **Check:** if removing a shadow from a static element wouldn't change whether it reads as "above" the page, the shadow shouldn't be there. ## 3. Generous whitespace is the default, not an accent Per "whitespace should improve readability": spacing values (`02-design-tokens.md`) skew larger rather than smaller wherever there's a choice — between sections, around form fields, inside cards. Density is earned only in data-heavy contexts (large tables) where it directly serves the merchant's ability to scan, never applied by default for its own sake. ## 4. Typography carries hierarchy, not color or weight alone Per "typography should be highly readable": hierarchy between a page title, a section heading, and body text comes primarily from **size and spacing**, with weight as a secondary signal (see the type scale in `02-design-tokens.md`, which uses only three weights total). Avoid stacking multiple hierarchy signals (bold + color + larger size + all-caps) on the same element — pick the minimum combination that reads clearly. ## 5. Motion is purposeful, never decorative Per "animations should be subtle and purposeful": every animation in `05-motion-and-microinteractions.md` exists to communicate a state change (something was saved, something appeared, something was dismissed) — never to demonstrate polish for its own sake. **Check:** if an animation were removed entirely, would the interface become harder to understand? If not, it shouldn't exist as motion — a static state change is fine. ## 6. Every screen has one primary action Consistent with `../ux/03-ux-patterns-and-conventions.md` rule 6 ("one way to do a thing"): a screen's primary button (styled with the accent color, per rule 1) is the one action the merchant is most likely trying to take on that screen. Secondary actions exist but are visually quieter (outlined or text-only buttons), so the eye is never asked to choose between two equally loud options. ## 7. Timeless over trendy No gradients, no glassmorphism/blur effects, no oversized rounded "bubble" UI, no trend-driven visual flourish that will look dated in two years. The palette, type, and shape language in `02-design-tokens.md` are chosen to still look correct without a redesign five years from now — closer to how a well-made physical product ages than how a UI trend cycles. ## 8. Confidence means no unnecessary friction "Calm, fast, confident" shows up as an absence, not a presence: no unnecessary confirmation dialogs (see `../ux/03-ux-patterns-and-conventions.md` rule 3 for exactly when confirmation is warranted), no artificial loading delays, no interstitial screens between a merchant's intent and its result. If a component makes the merchant wait or double-check without a real reason, it violates this principle regardless of how it looks.