# XShop – UI Specification

## 1. Design Principles

- Persian-first, minimal, high contrast, generous whitespace, card-based.
- Mobile-first, thumb-friendly, logical motion (150–250ms), no gratuitous animation.
- Original design system (not a clone of reference).

## 2. Tokens

Defined in `xshop-theme/assets/css/tokens.css` via CSS custom properties. **M1 finalizes tokens** — full coverage for dark mode and components:

```css
:root {
  --xshop-primary: #0ea5e9; --xshop-primary-600: #0284c7; --xshop-primary-700: #0369a1;
  --xshop-secondary: #111827;
  --xshop-bg: #ffffff; --xshop-surface: #f8fafc; --xshop-surface-2: #f1f5f9; --xshop-card: #ffffff;
  --xshop-text: #0f172a; --xshop-muted: #64748b; --xshop-border: #e2e8f0;
  --xshop-input-bg: #ffffff; --xshop-input-border: #cbd5e1; --xshop-input-text: #0f172a;
  --xshop-focus: #0ea5e9; --xshop-link: #0ea5e9; --xshop-link-hover: #0284c7;
  --xshop-success: #16a34a; --xshop-success-bg: #f0fdf4; --xshop-warning: #f59e0b; --xshop-warning-bg: #fffbeb; --xshop-danger: #dc2626; --xshop-danger-bg: #fef2f2;
  --xshop-font-sans: system-ui, -apple-system, "Vazirmatn", "IRANSans", ...;
  --xshop-text-xs: 0.75rem; --xshop-text-sm: 0.875rem; --xshop-text-base: 1rem; --xshop-text-lg: 1.125rem; --xshop-text-xl: 1.25rem; --xshop-text-2xl: 1.5rem; --xshop-text-3xl: 1.875rem; --xshop-text-4xl: 2.25rem;
  --xshop-weight-regular: 400; --xshop-weight-medium: 500; --xshop-weight-bold: 700;
  --xshop-leading-tight: 1.25; --xshop-leading: 1.6; --xshop-leading-relaxed: 1.75;
  --xshop-space-1: 4px; ... --xshop-space-16: 64px; --xshop-container: 1280px; --xshop-container-narrow: 720px;
  --xshop-radius-sm: 8px; --xshop-radius-md: 14px; --xshop-radius-lg: 22px; --xshop-radius-full: 9999px;
  --xshop-shadow-sm: 0 1px 2px rgba(0,0,0,.06); --xshop-shadow-md: 0 8px 24px rgba(0,0,0,.08); --xshop-shadow-lg: 0 16px 40px rgba(0,0,0,.12);
  --xshop-z-header: 40; --xshop-z-overlay: 50; --xshop-z-modal: 60;
  --xshop-transition-fast: 120ms ease; --xshop-transition: 180ms ease; --xshop-transition-slow: 280ms ease;
}
[data-theme="dark"] { /* semantic swap, not inversion — covers bg/surface/card/text/muted/border/input/link/notice bg */ }
@media (prefers-reduced-motion: reduce) { :root { --xshop-transition: 0ms; } }
```

Typography: system-first + optional Vazirmatn. Scale 12/14/16/18/20/24/30/36, weights 400/500/700, line heights 1.25–1.75.

Breakpoints: 360 (xs), 640 (sm), 768 (md), 1024 (lg), 1280 (xl), 1536 (2xl). Container `--xshop-container` + `--xshop-container-narrow`.

CSS layering (M2): `tokens→base→layout→components→woo→utilities→style.css` via `inc/setup/assets.php:1` (`woo.css:1` 159 lines, global intentional). No hardcoded colors/spacing; tokens only.

## 3. Components

Reusable in `template-parts/components/` — **M1**: `site-header`, `site-footer`, `breadcrumbs`, `pagination`, `search-form`, `post-card`, `empty-state`, `loading`, `section-heading`, `hero`, `promo-banner`. **M2 adds**: `product-card.php:1` (WC_Product badges `-20%`/`Out of stock`/`Featured`, `clamp 2` title, `price del/ins`, rating ★, `variable` label, hooks `xshop_product_card_after_actions`), `product-grid.php:1` (grid `data-columns`, empty-state), `product-gallery.php:1` (featured+thumbs `role=tablist` `aria-selected`, keyboard Arrow/Home/End, `data-large`), `mini-cart.php:1` (count/items/subtotal/remove/empty).

Implemented details:
- `breadcrumbs.php:1` — semantic, Woo-aware, filterable
- `pagination.php:1` — RTL flip, hidden when 1 page
- `product-card` — handles simple/sale/variable/outofstock/featured/no-image/long Persian+English, `alt`, `aria-label` on media, `woocommerce_template_loop_add_to_cart` inside card
- `product-gallery` — no-image fallback, thumbs `aria-label View image %d`, `is-active` border token

States: default/hover/focus-visible/active/disabled/loading. Focus ring via `:focus-visible` (token `--xshop-focus`).

## 4. Layouts

- **Header**: `xshop-header` sticky, `site-header.php:1` (logo/search/account/cart/mobile toggle)
- **Footer**: 2–4 cols via `site-footer.php:1`
- **Shop (M2)**: `archive-product.php:1` → `xshop-page-header` + `xshop-shop-toolbar` (result-count + ordering) + `xshop-products` grid `4/3/2/1` (960/768/480), pagination, `empty-state` CTA, notices; category adds term title/desc/count.
- **Product (M2)**: `content-single-product.php:1` → `.xshop-product` grid `1.05fr 1fr → 1fr @900`, gallery `aspect 1/1` + thumbs `64px` scroll-x, summary (`title/rating/price/stock/short/variation/quantity/add-to-cart/meta`), tabs `.woocommerce-tabs` flex + panel, `related/upsells/cross-sells`.
- **Cart**: `.shop_table` + `.cart_totals`, responsive `display:block` → `data-title` ::before below 768.
- **Account**: `220px nav | 1fr content` → stacked @900, nav `is-active` token.
- **Checkout**: `.col2-set 1fr 1fr → 1fr`, fields in `xshop-card`.

## 5. Motion & Shadows

Transitions `var(--xshop-transition)`. Radius & shadows via tokens. No layout shift on hover.

## 6. Icons

SVG sprite or inline SVG, stroke 1.5–2. No icon font dependency. RTL flip via `scaleX(-1)` only for directional icons.

## 7. Dark Mode (M2)

`[data-theme="dark"]` covers all Woo elements via tokens: shop cards, gallery, price (`--xshop-wc-price-sale`), sale badge, tabs, tables, forms, notices. Verified dark tokens in `tokens.css:1` (`--xshop-bg 0b1220` etc). No second dark system.

## 8. Accessibility

- Semantic HTML5, landmarks, skip link.
- Keyboard nav for menus/drawers/modals (trap focus, Esc to close).
- Labels for all form controls, error messaging with `aria-describedby`.
- Colour contrast AA, reduced-motion `@media (prefers-reduced-motion)`.

## 9. RTL/LTR

- Logical properties: `margin-inline`, `padding-inline`, `inset-inline`.
- Carousel/breadcrumb/pagination directions follow `dir`.
- Mixed Persian/English: numbers stay LTR via `unicode-bidi: plaintext` where needed.

## 10. Reference Inspiration (not cloning)

From reference analysis: deep mega-menu, promotional story strip, category icon grid, flash-sale carousel, banner pairs, WC-like product cards with discount badge – XShop reinterprets with its own spacing/typography/radius system.