# Design Direction

Status: Approved decision record. Source of truth for all visual work in Phase 01+.
Scope: every customer-facing surface (storefront, catalog, ordering, account) and the storefront e-commerce admin.
Basis: `design-taste-frontend` skill (dials, token discipline, anti-slop), `nuxt-ui` skill (theming model), `AGENTS.md` (Nuxt UI first).

---

## 1. Design Read

**Reading this as:** a B2B e-commerce purchasing product for procurement and purchasing professionals, with a serious-B2B, trust-first-but-modern language, leaning toward themed Nuxt UI (the mandated design system) with custom tokens: IBM Plex Sans + IBM Plex Mono, the KeluargaMart royal-blue brand (deep royal blue primary, sky-blue accent, blue-tinted neutrals), dense but readable data surfaces.

The generic consumer-ecommerce aesthetics in `ui-ux-pro-max` ("Vibrant & Block-based", "Liquid Glass + Glassmorphism") are rejected: the audience is buyers placing orders against contracts, not shoppers browsing for pleasure. Speed, legibility, and predictability outrank decoration.

## 2. Dials

- **DESIGN_VARIANCE: 4** (asymmetric layouts allowed on the marketing home only; strict grids everywhere else)
- **MOTION_INTENSITY: 2** (micro-feedback only; reduced-motion is the default posture)
- **VISUAL_DENSITY: 7** (data surfaces dense; the marketing home drops to 4)

Reasoning: a purchasing product lives or dies on scanning speed. Variance and motion stay low because every animated or asymmetric element competes with prices, stock, and order status. The storefront landing is the one place a buyer is a visitor, not a worker, so it gets the only variance/motion budget. This matches the design-taste dial table for trust-first, accessibility-critical product UI.

## 3. Product Truths That Shape the Design

1. **Backend is authoritative.** Frontend renders API prices, totals, availability, and status. The UI must present these as facts, not marketing numbers. No client-computed pricing displays, no fake precision.
2. **Buyers scan, then act.** Dense tables, mono numerals, and stable layouts are features, not compromises.
3. **Status is semantics.** Stock, order, payment, and shipping states are real signals. Color-coded status is allowed only where the state is real (see 6.4).
4. **Trust over surprise.** Consistent positioning, predictable navigation, and honest loading states build more trust than any visual flourish.

## 4. Surface Map

| Surface | Variance | Density | Notes |
|---|---|---|---|
| Storefront home / landing | 6 | 4 | Only marketing surface. See section 12. |
| Catalog, browse, search | 4 | 7 | Strict product grid; compact table view; mono numerics. |
| Product detail | 4 | 6 | Price block prominent; spec sheet grouped, never row-bordered lists. |
| Cart / checkout | 3 | 6 | Single-column flow, calm, minimal chrome. |
| Auth / account | 3 | 6 | Forms with label-above-input, inline validation. |
| Orders / shipping / payments | 3 | 8 | Data-dense tables; status as semantic badges. |
| Notifications / support | 4 | 6 | |
| E-commerce admin | 3 | 8 | Highest density; no marketing treatment. |

## 5. Typography

**Family: IBM Plex Sans (UI) + IBM Plex Mono (data).** Designed together, purpose-built for dense enterprise data products. Not an AI-default font, and its character reads "industrial infrastructure", which is exactly the trust signal a B2B purchasing panel expects. No serif anywhere: this is commerce software, not an editorial or luxury brief (design-taste serif discipline).

**Weights:** Sans 400 / 500 / 600 / 700. Mono 400 / 500 / 600.

**Usage rules:**
- UI text: IBM Plex Sans. Body 14-16px, relaxed leading.
- Mono numerals (IBM Plex Mono 500) for: SKU / part numbers, order numbers, quantities in table cells, unit prices in dense tables, timestamps, status codes, promo codes. Mono is data, never headlines.
- Prices in prose (product cards, detail): IBM Plex Sans 600 with tabular numerals, never mono.
- Marketing home display: IBM Plex Sans 600/700, tight tracking. Headline scale capped at `text-4xl md:text-5xl lg:text-6xl`; no oversized display type.
- All figures everywhere: tabular numerals.

**Loading:** self-hosted via `@nuxt/fonts` (font-display: swap, no external font CDN requests). Phase 01 concern.

## 6. Color

**KeluargaMart brand palette: deep royal blue primary, sky-blue accent, blue-tinted neutrals.** Rooted in the logo (deep royal blue `#142B80` field with pale cyan `#80C8F0` outlines): the interface stays mostly white/light — the royal blue is the brand anchor, the cyan is reserved for accents, never a blue-SaaS wash.

### 6.1 Light tokens

| Token | Value | Use |
|---|---|---|
| bg-page | #F5F8FF | Page background (background soft) |
| bg-elevated | #FFFFFF | Cards, tables, dialogs (background) |
| bg-muted | #EEF3FA | Striped rows, hover rows, chips (surface) |
| text-default | #14213D | Primary text (dark navy) |
| text-muted | #64748B | Secondary text (slate blue-gray, 4.7:1 on white) |
| text-faint | #94A3B8 | Placeholders, captions |
| border-default | #D9E2F0 | Card/table borders (light blue-gray) |
| border-muted | #E7EDF7 | Dividers inside surfaces |
| primary | #142B80 | Primary CTA, links, selected state (11:1 vs white) |
| primary-hover | #102268 | CTA hover |
| primary-soft | #DCE7FC | Badge/selected backgrounds (with primary text) |
| accent | #80C8F0 | Badges, icons, highlights, focus (never text/button bg) |
| accent-light | #D8F5FF | Accent backgrounds, focus rings |

### 6.2 Dark tokens

| Token | Value | Use |
|---|---|---|
| bg-page | #0A1128 | Page background (deep navy) |
| bg-elevated | #16224B | Cards, tables, dialogs |
| bg-muted | #101A3A | Striped rows, hover rows, chips |
| text-default | #E6ECF7 | Primary text (pale blue-white) |
| text-muted | #9FB0CC | Secondary text |
| text-faint | #6B7EA3 | Placeholders, captions |
| border-default | #22315C | Card/table borders |
| border-muted | #1A2649 | Dividers inside surfaces |
| primary | #142B80 | Primary CTA, links, selected state (11:1 vs white) |
| primary-hover | #28459A | CTA hover (lightens on navy) |
| primary-soft | #16224B | Badge/selected backgrounds |
| accent | #80C8F0 | Badges, icons, highlights, focus |
| accent-light | #1A3A5C | Accent backgrounds, focus rings |

### 6.3 Contrast rules (mandatory)
- Light mode: primary buttons are `#142B80` with white text (11:1, WCAG AAA). Hover `#102268`. Never use the sky accent `#80C8F0` as a button background or text color — it fails AA on white (≈1.7:1); it is for badges, icons, highlights, charts, progress, and focus states only.
- Dark mode: primary buttons stay `#142B80` with white text (11:1); hover lightens to `#28459A`. The sky accent remains non-text (badges, icons, focus).
- Accent is for interactive and selected states only. Never for decorative gradients or glows.
- One accent, locked across the whole app. No section may introduce a second accent (color consistency lock).

### 6.4 Status colors (semantic only)
- success `#16A34A` (dark `#4ADE80`): in-stock, paid, delivered, completed.
- warning `#D97706` (dark `#FBBF24`): low stock, pending, backorder.
- error `#DC2626` (dark `#F87171`): out of stock, failed, cancelled, validation errors.
- info `#0284C7` (dark `#38BDF8`): neutral notices.
- Status colors appear only where the state is real and API-driven. No decorative dots, no colored dots on nav or list rows (design-taste dot rule).

## 7. Shape and Radius (consistency lock)

One documented radius system, applied everywhere:
- **4px** controls: buttons, inputs, selects, badges, chips.
- **8px** surfaces: cards, dialogs, drawers, tables, dropdowns.
- **Full pill** only: segmented controls, tooltips, notifications.

No mixing beyond this rule. Sharp corners signal industrial density; the small delta between controls and surfaces keeps the UI from feeling soft or consumer-y.

## 8. Spacing and Density

- Product surfaces: section padding `py-8` to `py-16`; compact table rows (dense density on Nuxt UI tables); content max-width 1280px, `mx-auto`.
- Marketing home: section padding `py-16` to `py-24`; hero top padding capped at `pt-24`; hero must fit the initial viewport (design-taste hero rules apply to the home only).
- Mobile: every multi-column layout declares its under-768px collapse in the same component: single column, full width, `px-4`.

## 9. Motion (MOTION_INTENSITY 2)

Every animation below is allowed because it has a job:
1. Skeleton shimmer on data loading (feedback).
2. Row/card hover: background and border shift, 150ms (affordance).
3. Button / checkbox press: scale to 0.98 on `:active` (feedback).
4. Nuxt UI built-in dialog, drawer, select, and notification transitions (state change).
5. Focus-visible ring on keyboard navigation (accessibility).
6. Optional 120ms page fade on client-side navigation (orientation).

Banned: parallax, scroll hijack, marquees, magnetic physics, glassmorphism on product UI, infinite loops, animated counters, scroll cues, hover-zoom on product images beyond 1.02.

Reduced motion: `prefers-reduced-motion: reduce` collapses all of the above to instant; skeletons render as static placeholder blocks. Reduced motion is the default posture, not an afterthought.

## 10. Dark Mode

- Strategy: CSS variables (Nuxt UI v4 theme tokens). Swap values under the dark selector. One token set for the whole app, per section 6.
- Default: `prefers-color-scheme`; a manual light/dark toggle lives in the header (Phase 01).
- No pure `#000000`, no pure `#FFFFFF`. Blue-tinted off-navy and off-white only.
- Both modes tested per surface before any surface is declared done.
2. Theme lives in the Nuxt UI theme config: primary color = royal-blue brand scale (`brand` in `main.css` @theme, anchored at `#142B80`), radius tokens per section 7, semantic tokens per section 6.
## 11. Nuxt UI Implementation Notes

1. `UApp` wraps the whole app (required for toasts, tooltips, overlays).
2. Theme lives in the Nuxt UI theme config: primary color = royal-blue brand scale (`brand` in `main.css` @theme, anchored at `#142B80`), radius tokens per section 7, semantic tokens per section 6.
3. Components use semantic classes only (`text-default`, `bg-elevated`, `border-muted`). Raw Tailwind palette colors in component code are prohibited.
4. No custom buttons, inputs, tables, modals, or selects. Reuse Nuxt UI, themed.
5. Thin domain components allowed, composed from Nuxt UI: `ProductCard`, `PriceTag`, `StatusBadge`, `SkuCode`, `EmptyState`, `ErrorState`, `SkeletonList`. No component may reimplement a Nuxt UI primitive.

## 12. Storefront Home (Only Marketing Surface)

- Layout families vary per section; at most 2 consecutive image+text splits; never three equal feature cards; bento sections use exactly as many cells as items.
- Eyebrow restraint: max 1 eyebrow per 3 sections. Headlines carry the meaning.
- Imagery: API/CMS product and banner imagery at runtime. Development mocks use seeded photography URLs (e.g. `https://picsum.photos/seed/<descriptive-seed>/<w>/<h>`). Never div-built fake screenshots, never hand-rolled decorative SVG.
- CTA discipline: one label per intent, max 3 words, single line at desktop, WCAG AA contrast against background.
- No version labels, no scroll cues, no locale/time strips, no logo walls with category labels, no marquee.

## 13. Anti-Slop Commitments (bind all surfaces)

- Zero em-dashes and zero en-dashes in any visible copy. Use periods, commas, parentheses. (Design-taste rule 9.G.)
- No AI-purple or blue-glow gradients, anywhere.
- No Inter as a default font.
- No glassmorphism on product UI.
- No decorative status dots.
- No fake-precise numbers. Every figure comes from the API; dev mocks are labeled mock.
- No placeholder brands like "Acme". Mock data uses realistic company/product names.
- No marquees, no scroll hijack, no parallax.
- One accent, one radius system, one neutral palette per project.

## 14. Pre-Flight Mapping (design-taste Section 14)

Checks that apply to every surface: theme lock, color consistency lock, shape consistency lock, button/form contrast, copy self-audit, motion motivated, reduced motion, dark mode tokens, mobile collapse, viewport stability (`min-h-[100dvh]`, never `h-screen`), empty/loading/error states, cards only where elevation earns them, no hand-rolled SVG icons (Iconify via Nuxt UI only), no AI tells.

Checks that apply to the marketing home only: hero viewport fit, hero top padding cap, hero stack discipline, eyebrow count, split-header ban, zigzag cap, layout-family diversity, bento cell count, logo-wall rules, real images.

Checks that do not apply to this product and are explicitly waived: scroll-pinned/horizontal-pan GSAP patterns (MOTION 2), page-level marquees (banned), serif discipline (no serif chosen), premium-consumer palette ban (palette is not the beige family).

2. Map section 6 tokens into the Nuxt UI theme (CSS variables), set primary = royal-blue brand (`#142B80` scale), radius tokens per section 7.

Phase 01 must consume this doc:
1. Add `@nuxt/fonts`; load IBM Plex Sans + IBM Plex Mono self-hosted.
2. Map section 6 tokens into the Nuxt UI theme (CSS variables), set primary = royal-blue brand (`#142B80` scale), radius tokens per section 7.
3. Wire `UApp`, semantic color discipline, dark mode init (system preference + header toggle).
4. Build the shared primitives from section 11.5 (Skeleton/Empty/Error first, they gate every later phase).
5. Register the design read and dials in the phase notes and feature matrix as implemented.