# Design Guidelines

Visual and interaction conventions for all three frontends. Everything here is
enforced by `packages/shared/src/theme.css` tokens and `packages/ui`
components — if you need a value that does not exist, extend the theme or the
kit instead of improvising locally. No `<style scoped>`, no hex literals in
app code.

## Color

Semantic tokens only (Tailwind classes: `bg-bg`, `text-text`, …):

| Token | Value | Use |
|---|---|---|
| `bg` | `#f5f5f5` | page background |
| `surface` | `#ffffff` | cards, panels, nav, inputs |
| `border` | `#e2e5ea` | all borders/dividers |
| `text` | `#1c2330` | primary text |
| `muted` | `#66707f` | secondary text, placeholders |
| `primary` | accent | actions, links, active states |
| `danger` | `#d64545` | errors, destructive actions |
| `success` | `#1f9d63` | success feedback, positive states |
| `warning` | `#c77d0a` | pending/attention states |

**Accent presets** (`red` default, `blue`, `teal`, `violet`) swap
`--primary*` at runtime via `html[data-accent]`; users pick one with
`VAccentSwatch`. Derivatives: `primary-hover`, `primary-soft` (subtle tint for
selected/hover fills). Never reference a preset's hex directly.

Opacity modifiers for tinted feedback: `bg-danger/10 text-danger` etc. (see
`VBadge` tones).

## Typography

- Font: system stack (`--font-sans`, includes PingFang SC / Microsoft YaHei).
- Page title: `text-xl font-bold` (`VPage` provides it).
- Section heading: `text-base font-semibold` (consoles) /
  `text-lg font-semibold` (mall content sections).
- Body: `text-sm`; secondary/meta: `text-xs text-muted` (or `text-[13px]` in
  dense console sidebars).
- Bilingual copy renders through locale fallbacks, never side-by-side.

## Radius, borders, elevation

- Radius: `rounded-md` (8px) for cards/inputs/buttons; `rounded` (4px) for
  chips/badges; `rounded-full` for avatars and progress bars.
- Cards: `rounded-lg border border-border bg-surface shadow-sm` — this is
  exactly `VCard`; use it instead of re-deriving.
- Elevation: one level only (`shadow-sm` on cards). No stacked shadows.

## Layout

- Mall content max width: `max-w-mall` (1200px), centered, `px-4`.
- Consoles: sidebar (`md:w-60`) + fluid `<main class="min-w-0 flex-1">`;
  page content in `mx-auto w-full max-w-7xl px-4 md:px-6` (admin) or the
  shop-admin equivalent. Content columns must be `w-full min-w-0` — auto
  margins on grid items silently shrink them to fit-content.
- Buyer center (`apps/mall/pages/user.vue`): `234px` sidebar + fluid content
  in a `max-w-mall` grid.

## Components and when to use them

| Need | Use | Notes |
|---|---|---|
| Page shell | `VPage` (`:title`, `#actions`) | consoles |
| Card/section | `VCard` (`:padded="false"` for edge-to-edge tables) | one card per logical section |
| Button | `VBtn` (`variant`: default/primary/danger, `size`: md/sm) | primary = the one forward action; danger only for destructive |
| Badge/status | `VBadge` (`tone`: green/blue/orange/red/gray) | map domain status → tone once per page |
| Form field | `VField` (`:label`, `:error`) + `VInput` | errors inline, never alert() |
| Table | `VTable` in `overflow-x-auto` wrapper | dense console data |
| Empty state | `UiEmptyState` (mall) / muted text (consoles) | always provide one |
| Pagination | `UiPagination` (mall) / prev-next block (consoles) | server-driven totals |

## Interaction states (every async surface)

1. **Loading**: muted text/skeleton region; never a blank card.
2. **Error**: `role="alert"` + `text-danger`, keep user input intact.
3. **Success**: transient `role="status"` text near the action
   (`text-success`), not a toast system.
4. **Conflict (409)**: show the message and refresh from server state —
   the UI must converge to truth, not stack retries.
5. **Destructive actions**: `confirm()` + `VBtn variant="danger"`.

## Imagery and icons

- Product/content images: `object-cover` in fixed-ratio boxes
  (`h-12 w-20` thumbnails, `w-full` heroes).
- Icons: inline SVG path data (storefront quick links carry glyphs in the
  API). No icon font, no emoji as UI icons.
- Avatars: `rounded-full`, fallback `/mock/avatar.svg`.

## Accessibility floor

- All controls keyboard-reachable; visible focus via
  `focus:border-primary focus:outline-2 focus:outline-primary/30` (built into
  `VInput`).
- Icon-only buttons need an accessible name; star ratings use
  `role="img"` + `aria-label`.
- Respect locale switching without layout overflow (`min-w-0`, `truncate`).

## What stays out of scope

Charts, drag-and-drop builders, dark mode, and print styles have no tokens
yet. Propose them as a design extension (new tokens in `theme.css` + kit
components) instead of local one-offs.