93 lines
6.0 KiB
Markdown
93 lines
6.0 KiB
Markdown
# 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 (M1): `tokens.css` → `base.css` → `layout.css` → `components.css` → `utilities.css` → `style.css`. Enqueued in that order via `inc/setup/assets.php:1`. No global component bloat; each file is justification-scoped.
|
||
|
||
## 3. Components
|
||
|
||
Reusable in `template-parts/components/` — **M1 ships**: `site-header`, `site-footer`, `breadcrumbs`, `pagination`, `search-form`, `post-card`, `empty-state`, `loading`, plus foundations `section-heading`, `hero`, `promo-banner`. Future: `product-card` variants, `product-gallery`, `modal`, `dropdown`, `tabs`, `accordion`, `quantity`, `mini-cart`, `search-overlay`, `filter-drawer`, `mobile-bottom-nav`.
|
||
|
||
Implemented details (M1):
|
||
- `breadcrumbs.php:1` — semantic `<nav><ol>`, `aria-current="page"`, Woo-aware (shop/category/product/cart/checkout/account), filter `xshop_breadcrumbs_items`, never breaks on empty.
|
||
- `pagination.php:1` — `paginate_links()` with `aria-label`, `prev/next` flipped via `is_rtl()`, hidden when `max_num_pages<=1`.
|
||
- `post-card.php:1` — handles missing thumb (`No image` placeholder), missing excerpt (`wp_trim_words`), long title (`overflow-wrap`), lazy load.
|
||
- `search-form.php:1` — `role="search"`, unique `id` via `wp_unique_id()`, `label.sr-only`.
|
||
- `empty-state.php:1` / `loading.php:1` — `role="status"` + `aria-live`.
|
||
|
||
States: default/hover/focus-visible/active/disabled/loading. Focus ring via `:focus-visible` (token `--xshop-focus`).
|
||
|
||
## 4. Layouts
|
||
|
||
- **Header**: layouts `classic` (topbar + logo/search/actions + nav), `centered`, `minimal`. Sticky on scroll, height collapses slightly.
|
||
- **Footer**: 2–4 column widget area + logo/menus/social/copyright/custom HTML.
|
||
- **Shop**: sidebar (desktop) / drawer (mobile), active chips, sort, result count, grid/list.
|
||
- **Product**: gallery left (RTL mirrored), summary right, tabs below, related/upsells carousel.
|
||
- **Blog**: card grid, single with TOC where headings exist.
|
||
|
||
## 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 (M1 foundation)
|
||
|
||
Token swap via `[data-theme="dark"]` (set on `<html>` in `header.php:1` via `xshop_is_dark_mode()`). Covers `bg/surface/surface-2/card/text/muted/border/input-bg/input-border/input-text/focus/link/success-bg/warning-bg/danger-bg`. Toggle is `data-xshop-theme-toggle` in `assets/js/theme.js:1` (localStorage + cookie `xshop_theme` for SSR). No complex switcher yet — foundation only, future components consume tokens.
|
||
|
||
Body class helper `inc/setup/body-classes.php:1` adds `xshop--dark`/`xshop--light` + `xshop--has-woo`/`xshop--no-woo` for CSS targeting.
|
||
|
||
## 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.
|