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:

: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.

6.0 KiB Raw Blame History Unescape Escape