# ShukWAY — Design System

**ShukWAY (שוק WAY)** is a mobile-first **navigation *guide* for traditional markets**, piloting at Jerusalem's Mahane Yehuda (שוק מחנה יהודה) with 300+ mapped stalls. It is deliberately **not a map app** — it's a *market guide*.

> Where Waze tells you *where you are*, ShukWAY tells you *what you're passing*: "go past Bentzi Fish (עבור את בנצי דגים), turn right after Ramla Bourekas (פנה ימינה אחרי בורקס רמלה), your destination is on your left."

Under the market's covered roof GPS lies by 30–50m, so ShukWAY throws away the blue dot and navigates **stall-to-stall by human landmarks**. Hebrew **RTL by default**, multi-language ready. The brand feeling is **warm, local, trustworthy, and alive** — the local who knows every alley, leading you by the hand.

---

## Products

ShukWAY is a small family of surfaces, all built on this one visual language:

1. **Consumer PWA** (`map.shukway.com`) — the live market. Full-bleed vector map (MapLibre + PMTiles, 527 stalls), category legend, search, business bottom-sheet, and the signature **"Guide Mode" (מצב מדריך)** turn-by-turn instruction card. This is the heart of the product.
2. **Business-owner dashboard** (`dashboard.shukway.com`) — stall owners manage their profile, hours, contact, insights, and **coupons** (the orange "go-live" moment that pushes a deal into the consumer app).
3. **Team / admin dashboard** (`view/`) — internal pilot operations: an intake/task board for onboarding the 300+ stalls (variations A/B/C explored).

## Sources this system was built from

Everything here is grounded in the real ShukWAY codebase and its own design canon — not reconstructed from memory.

- **GitHub:** [`ShukwayGit/shukway-apps`](https://github.com/ShukwayGit/shukway-apps) @ `main` — the two static sites (`map/`, `dashboard/`) plus the `design/` canon subtree. Explore it to build more faithfully.
  - `design/DESIGN.md` — the full brand canon (brand essence, palette, type, components, Guide Mode, motion, voice, agent prompt guide). **This is the source of truth.**
  - `design/tokens.css` — the canonical CSS custom properties.
  - `design/preview.html` — a live catalog of the foundation.
  - `map/` — the consumer PWA (`index.html`, `app.js`, `nav-engine.js`) — the category families and colors, guide-mode instruction phrasing, and pin/sheet markup are lifted from here.
  - `dashboard/` — the business-owner dashboard (`index.html`).
- **Related repos** (context, not read in full): `shuk-monitoring` (admin/analytics), `shukway-cuppon`, `shukway-portal`, `PEER`, `habbat`.
- **Uploaded assets:** Ploni webfonts, Heebo variable font, `logo.png` / `logo-horizontal.png` / `mark.png`, 410 real stall photos (`map/assets/photos/`).

 Tip for future work: read `design/DESIGN.md` in the repo above first — it is the canon and carries Hebrew rationale for every decision.

---

## CONTENT FUNDAMENTALS

The voice is **a local who knows the shuk**, not a corporate navigation app. Hebrew-first, warm, direct, a little cheeky (חצוף).

- **Language & direction.** Hebrew, RTL. Copy is written *for* Hebrew — generous line-height, standard punctuation (note the geresh in numbers: `140 מ׳`, `2 דק׳`). Multi-language ready but Hebrew is the default reading.
- **Person / address.** Speaks **to you**, usually plural-imperative ("חפשו", "פנו", "צאו") — the guide addressing the shopper. Warm, never stiff.
- **Instructions are always relative to a real business, never to coordinates or compass degrees.** ✅ "פנו ימינה ליד בנצי דגים" / "צאו מכניסת יפו והמשיכו" · ❌ "המשך צפון-מזרח 40 מ׳". The nearest known stall to each turn becomes the landmark ("ליד …").
- **Actions keep the same name through a flow.** The button "נווט לכאן" leads to a screen titled ניווט. Don't rename an action mid-journey.
- **Empty states invite action — never "no results."** ✅ "חפשו דוכן, מנה או קטגוריה…" · ❌ "אין תוצאות".
- **Casing & tone.** No ALL-CAPS Hebrew (Hebrew has no case). Latin labels (KPI eyebrows in dashboards) may use uppercase + letter-spacing sparingly. No marketing clichés ("חוויה בלתי נשכחת"), no "pilot" framing to users.
- **Numbers & data** are spoken plainly and set in Heebo: distance + time together, "140 מ׳ · 2 דקות", "נותרו 3 דק׳".
- **Emoji:** used sparingly and only where warm/functional in product surfaces — the coupon tag "קופון פעיל 🔥", arrival "הגעתם!", a check "הגעתי ✓". Not decorative sprinkling. Prefer the line-icon set for UI.

**Microcopy canon** (from DESIGN.md §8):

| Moment | Text |
|---|---|
| Empty search | חפשו עסק או הקישו על נקודה במפה |
| Arrival | הגעתם! ברוכים הבאים ל[שם העסק] |
| Instruction | פנו ימינה אחרי בורקס רמלה |
| Nav button | נווט לכאן |
| Confirm arrival | הגעתי |
| Status | פתוח עכשיו · 06:00–19:00 |

---

## VISUAL FOUNDATIONS

**Palette drawn from the market itself** — the teal of the awnings and shutters, the orange of spices and fruit, the light Jerusalem stone of the background.

- **Two colors, two jobs. `teal #038A82` = STRUCTURE, `orange #E56E13` = ACTION.** They never compete for attention in the same area. On any one screen, orange appears *only* on what invites a touch (primary CTA, hot/coupon pins, coupon pulse). Everything structural — headings, active chips, the map polygon, pins by default — is teal.
- **Never pure white, never pure black.** Canvas is `#EFF8F7` (soft teal-white stone), cards are cream `#FBF9F4`. Text is `#1A2E2C` (near-black with a teal cast). Pure `#FFF`/`#000` "kill the warmth."
- **Category color system** — 8 families, each with a fixed hue used for pins, chips and badges: food (orange), sweets (magenta #D6336C), produce (green #2F9E44), spices (amber #B0750F), meat & fish (red #C92A2A), gifts (gold #C99700), shops (emerald #0CA678), services (indigo #4C6EF5).
- **Type.** **Ploni** (brand, commercial license, self-hosted) for everything — a rounded-but-serious Hebrew face. **Heebo** as fallback *and* for all numbers/distances/data (tabular, scannable at a glance). Scale: Display 28/700 · Heading 22/700 · Subhead 18/500 · Body 16/400 · Label 14/500 · Caption 13/400. Line-height **1.5 body / 1.25 headings**. **letter-spacing always `normal`** — never negative tracking on Hebrew.
- **Spacing.** Strict **4px grid**: 4 · 8 · 12 · 16 · 24 · 32 · 48. 16px safe inset from screen edges. No arbitrary values.
- **Backgrounds.** Flat soft canvas or cream — no gradients on content surfaces. The *only* gradient use in the wild: dashboard top-bars (deep-teal linear) and hero panels. The consumer app background *is* the live map; UI floats above it as cream cards. Real stall **photography** (warm, saturated, daylight) fills business sheets/cards — never illustration for a real place.
- **Corners.** Buttons 14px · cards 16px · bottom sheet 22px (top only) · pills 999px.
- **Cards** = cream surface + 16px radius + soft **teal-tinted shadow** `0 4px 16px rgba(3,138,130,.10)`. Floating chrome over the map uses a stronger float shadow `0 8px 30px rgba(21,48,45,.14)`. Cards never sit flush to the edge — always 16px in. Hairline borders `#D6E7E4` (1px), or 1.5px teal for section rules.
- **Elevation / blur.** Floating chrome and sticky nav use translucent surfaces with `backdrop-filter: blur(6–10px)` over the map. Bottom sheet rises with `0 -10px 40px` shadow.
- **Hover / press.** Transitions are **fast: 150ms ease-out**. Press feedback is a subtle **shrink** `transform: scale(0.97)` on buttons; hover deepens color (teal→teal-deep, orange→orange-deep) or lifts cards `translateY(-2/-4px)` with a stronger shadow. Never slow, never bouncy-for-fun.
- **Motion is the perceived quality** (DESIGN.md §7) — every motion serves understanding or aliveness, never decoration:
  - **Cinematic camera landing:** on open, flyTo the shuk with 45° pitch, landing in under 5s ("time to wow").
  - **Pins land in a 30ms stagger** — arriving one-by-one, not all at once; this is what feels *alive*.
  - **Coupon pulse:** orange tag, gentle `scale 1.0→1.08→1.0`, 2s cycle.
  - **Guide card rises in** from the bottom; nav banner drops in from the top; the route line draws itself.
  - All gated on **`prefers-reduced-motion`** — pulse and stagger drop to 0.
- **Layout.** Mobile-first, single column, base width **380px**. The map is the bottom layer (full-bleed); everything else floats over it. **The bottom third is the action zone** — instruction card, "הגעתי" CTA, search — all in thumb reach (one hand, shopping bag in the other). Top third is map only.
- **Touch.** Targets ≥ **44px**; primary CTA **52px** tall, full-width at the bottom.

---

## ICONOGRAPHY

ShukWAY uses **hand-placed inline SVG line icons** throughout the product — a Lucide-style set: `stroke="currentColor"`, `stroke-width` ~2.2–2.6, `stroke-linecap/linejoin: round`, 24×24 viewBox, no fills. Icons inherit color from context (teal in structure, white on colored chips/pins). Examples in the codebase: search (magnifier), location pin, chevrons, crosshair/locate, "3D" pitch (text glyph in a FAB), direction arrows for turns, and the arrival check `M20 6L9 17l-5-5`.

- **Map pins** are teardrop shapes (`border-radius: 50% 50% 50% 4px; rotate(45deg)`) filled with the family color, white icon inside; a "hot" (coupon) pin is orange with a pulsing halo.
- **The `Icon` component** in this system wraps this convention with a curated glyph set so consumers don't hand-roll SVGs (see `components/`). It is an **intentional addition** — the source draws icons inline rather than as a named component, but a wrapper keeps stroke weight and sizing consistent.
- **No icon font, no sprite sheet** ships in the source; icons are inline. Where a CDN set is wanted for prototyping, **Lucide** is the closest match to the house stroke style.
- **Emoji** appear only as warm functional accents in copy (🔥 on live coupons, ✓ on confirm), never as a UI icon system.
- **Brand mark:** `assets/logo-horizontal.png` (wordmark שוק+way with the stall+pin illustration), `assets/logo.png` (same), `assets/mark.png` (the isometric market-stall-on-a-map illustration — usable as a hero/empty-state graphic).

---

## Index / Manifest

- `styles.css` — global entry point (import list only). **Consumers link this.**
- `tokens/` — `fonts.css`, `colors.css`, `typography.css`, `spacing.css`, `motion.css`.
- `assets/` — `logo-horizontal.png`, `logo.png`, `mark.png`; `fonts/` (Ploni + Heebo); `photos/` (real stall photography for kits).
- `guidelines/` — foundation specimen cards (Colors, Type, Spacing, Brand) shown in the Design System tab.
- `components/` — reusable primitives (see below), each with `.jsx` + `.d.ts` + `.prompt.md` + a card HTML.
- `ui_kits/` — full-screen recreations: `consumer/` (the PWA + Guide Mode), `dashboard/` (business owner).
- `SKILL.md` — Agent-Skills-compatible entry for downloading this system into Claude Code.

**Components** (grounded in DESIGN.md §5): `Button`, `CategoryChip`, `SearchBar`, `StatusBadge`, `CouponPill`, `BusinessCard`, `GuideCard` (signature), `MapPin`, `Icon` (intentional addition), `KpiCard` (dashboard).

### Intentional additions
- **`Icon`** — a thin wrapper over the house inline-SVG convention (the source draws icons inline). Keeps stroke weight/size consistent for consumers.
- **`KpiCard`** — factored out of the business-owner dashboard's KPI row; used across dashboards.

---

## Caveats / substitutions
- **Ploni is a commercially-licensed font** (fontef). It is self-hosted here for fidelity. In environments without the license, the system falls back to **Heebo** (already wired in `--font-brand`). No Google-Fonts substitution was needed — both Ploni and Heebo are provided.
- The **team/admin `view/` app** uses a *divergent* palette (teal `#0E5657`, Frank Ruhl Libre serif) that predates the V-NEXT canon. This system standardizes on the **canon** (`#038A82`, Ploni). Bring the admin app onto these tokens when it's next touched.
- Map tiles / MapLibre are out of scope for static specimens; the consumer UI kit mocks the map as a styled backdrop with real pins & sheets.