# JewelLink EDU — Design System

> **"Connecting Schools & Families"**
> A school–family communication and operations platform. JewelLink EDU brings everything a parent needs into one glance — live bus tracking, pickup/dismissal coordination, two-way school messaging, assignments & behavior, and payments — and gives school staff an admin web dashboard to run it all. The product's stated north star is to feel like **Uber for status clarity** and **Apple for clean, minimal design**, while directly competing with bus-tracking tools (e.g. SMART Tag) and replacing fragmented school communication apps.

---

## Products in this system

JewelLink EDU is **two surfaces sharing one brand**:

1. **Parent Mobile App** (iOS/Android) — the family-facing product.
   Bottom navigation: **Home · Messages · Transport · Activities · Profile**.
   Key screens: Login, Home Dashboard, Messages (+ AI Summary), Transport (live bus tracking), Pickup/Dismissal, Assignments & Behavior, Profile/Settings.

2. **Admin Web Dashboard** — the school/district staff product.
   Sidebar navigation: **Dashboard · Students · Transportation · Pickup Manager · Messaging · Payments · Reports · Settings**.
   Key views: Overview dashboard with live stats, live bus map, pickup queue, recent alerts, quick actions.

**Roles** (role-based access): `super_admin` (district), `admin` (school), `teacher`, `parent`, `student`, `driver`. Each role sees only its own data (a parent sees only their child; a teacher only their class).

---

## Sources used to build this system

This design system was reconstructed from the materials the user provided. **No live codebase or Figma was accessible** — the GitHub repo `github.com/ajones40-ux/school` was empty (no commits) and the mounted folder contained no source. Everything here is derived from:

- **`uploads/DEmo Design (2).png`** — a high-fidelity mockup board showing the logo, six parent-app screens (Home, Messages, Transport, Pickup, Assignments, Login) and the admin web dashboard. *Primary visual source of truth.*
- **`Jewel Link EDU Wireframe (1).docx`** — full UI wireframe system, screen-by-screen layouts, clickable flow, and an explicit **Design Style Guide** (the canonical brand colors below). Extracted to `docs_extracted/wireframe.txt`.
- **`API Structure (2).docx`** — REST + WebSocket API architecture and screen→endpoint mapping. → `docs_extracted/api_structure.txt`
- **`Project Structure Code (2).docx`** — Node/Express + Prisma backend structure. → `docs_extracted/project_structure.txt`
- **`Role-Based Access Model (2).docx`** — roles, RBAC middleware, data-access rules. → `docs_extracted/rbac.txt`
- **`FULL BACKEND (PRODUCTION STRUCTURE) (2).docx`** — production backend layout.

> **For future readers:** if you have access to the real repo (`github.com/ajones40-ux/school`) or a Figma file, explore it — recreating from source code/design context is far more faithful than from the mockup image alone. Re-attach via the Import menu and this system can be tightened to pixel accuracy.

---

## CONTENT FUNDAMENTALS

How JewelLink EDU writes copy. The voice is **warm, parent-first, and reassuring** — it reduces anxiety about a child's day. Think calm logistics, not corporate edtech.

- **Person & address:** Speaks **directly to the parent in second person** ("You are 2 mins away", "We'll notify school you're on the way"). The school/system is **"we"**. The child is referred to **by first name** ("EJ scanned ON at 3:05 PM").
- **Greeting is personal & time-aware:** *"Good afternoon, Jermaine"* — first-name, time-of-day greeting at the top of Home.
- **Tone:** Friendly, plain, confident. Status is stated as fact, not jargon: *"On the way"*, *"ETA 5 min"*, *"Car Rider"*, *"Completed"*. No exclamation overload — one warm beat ("Welcome back!") then straight to business.
- **Casing:**
  - **Screen titles & section headers:** Title Case ("Pickup Plan", "Today's Pickup", "Recent Alerts", "Quick Actions").
  - **Tiny section eyebrows:** UPPERCASE, letter-spaced ("BUS STATUS", "TODAY'S SCHEDULE", "RECENT ALERTS").
  - **Buttons:** Title Case verbs ("Sign In", "View on map", "Change Pickup Method", "Add Authorized Person", "Mark Picked Up", "Ask AI").
  - **Body & metadata:** sentence case ("Due Today · 11:59 PM", "Scanned on · 3:05 PM").
- **Numbers & status are front-loaded and large:** "5 min", "1,248", "$24,650", "4.9". Stats lead; labels follow in small muted text.
- **Microcopy for status:** short, glanceable, often with a relative time ("3m ago", "2m", "Due Tomorrow · 9:00 AM"). Priorities are single words: **High / Medium / Low**.
- **AI features are labeled plainly and invitingly:** "AI Homework Helper — Get step-by-step help and understand any topic", CTA "Ask AI"; "AI Summary" shortens long teacher messages.
- **Emoji:** **Not used in the product UI.** (The planning docs use emoji as section markers, but the shipped interface uses line icons, never emoji.) Don't put emoji in JewelLink screens.
- **Examples to reuse verbatim for tone:**
  - "Good afternoon, Jermaine"
  - "On the way · Bus #12 · ETA 5 min"
  - "EJ did great today in class!"
  - "You are 2 mins away — We'll notify school you're on the way."
  - "Welcome back! Sign in to continue"

---

## VISUAL FOUNDATIONS

The brand is **trustworthy, modern, and calm** — deep navy authority + warm gold optimism, on lots of clean white space. "Apple-clean with Uber-clear status."

### Color
- **Navy** is the brand anchor (`#1A3A6D`), deepening to near-black navy (`#001533`) for the admin sidebar and login background. Navy carries headers, sidebars, primary text, and the dark "hero" status cards.
- **Gold** (`#F5B82E`/`#FCC13E`) is the single warm accent — reserved for **primary CTAs** (Sign In), the graduation-cap in the logo, and bus/transport motifs. Used sparingly so it stays special.
- **Royal blue** (`#2A69BC` / `#1935B4`) is the interactive/secondary color: active nav icons, links, and the **AI feature cards** (blue gradient).
- **Cyan** (`#2FB6E0`) appears only inside the logo's network nodes — use as a rare accent, not a UI color.
- **Backgrounds** are white and very light cool gray (`#F5F7FA` / `#F9FAFC`). Never pure-gray-heavy; the canvas is bright.
- **Semantic badges** are pastel-tinted pills: red `#FEEBE6`/`#E5484D` (High, alerts), amber `#FEF3D6`/`#F0B540` (Medium, pending), green `#E6F7EF`/`#1F9D57` (Low, completed, on-time, "scanned ON" check), blue `#E3EDFB`/`#2A69BC` (info).

### Type
- One family does everything: a **clean geometric-humanist sans** (we substitute **Plus Jakarta Sans** — see font note). Weights run 400→800.
- **Big, readable hierarchy.** Status numbers are huge and extra-bold; labels are small, muted, often UPPERCASE eyebrows. Generous line-height on body.
- Negative letter-spacing on large headings; positive tracking on uppercase eyebrows.

### Backgrounds & surfaces
- **No photography as backgrounds.** Backgrounds are flat white/light-gray. The only imagery is the logo, a friendly **school-bus illustration** inside the transport hero card, map tiles in tracking views, and small circular avatar photos.
- **Gradients** are used deliberately and only in three places: the **hero status card** (navy→teal-blue), the **login screen** (navy vertical gradient), and **AI cards** (royal-blue gradient). Elsewhere, surfaces are flat.
- **Maps** appear as muted, desaturated tiles with gold bus pins — calm, not vivid.

### Cards
- The system's core unit. **White fill, ~14px radius, soft shadow** (`--shadow-sm`/`--shadow-md`), hairline border `#DEE3EC` when on white. Roomy internal padding (16–20px). Minimal clutter.
- **Hero cards** (bus status, AI) are filled with a gradient, white text, ~18px radius, and a stronger lifted shadow.
- Cards rarely use colored left-borders; status is shown with pill badges and icons instead.

### Spacing & layout
- **4pt spacing system.** Comfortable, airy. Mobile uses ~16px screen gutters; cards stack with 12–16px gaps.
- Mobile: fixed top bar (greeting + bell), scrolling content, **fixed bottom tab bar** (5 items, active item navy/blue with label).
- Admin: **fixed dark sidebar** (~220px) + top search/utility bar; content is a responsive card grid (stat tiles row, then two-column panels).
- Generous whitespace; one idea per card; large touch targets (≥44px).

### Borders & radii
- Hairline borders `1px #DEE3EC`. Corner radii: inputs/buttons 10–12px, cards 14px, hero cards 18px, pills/avatars fully rounded.

### Shadows & elevation
- **Soft, low-spread shadows** — never harsh. Three steps: subtle (resting cards), medium (raised panels/menus), and a richer colored shadow for navy/gold hero elements. No inner shadows; no heavy outlines.

### Hover / press / states
- **Hover:** subtle — buttons darken one step (gold→`--gold-600`, navy→`--navy-500`), cards lift to `--shadow-md`, list rows tint to `--gray-100`.
- **Press:** slight scale-down (`scale(.98)`) + one shade darker. Quick.
- **Active nav:** icon + label switch to navy/blue, often with a soft tinted background behind the icon.
- **Focus:** 2px blue ring (`--blue-500` at low alpha) on inputs.
- **Selected segmented tabs** (To Do/Completed, day picker): filled navy pill with white text; unselected are transparent with muted text.

### Transparency & blur
- Used lightly: map overlays and bottom action bars may use a translucent white with slight blur; status-bar area on hero cards uses subtle white-alpha layering. Not a glassmorphism-heavy brand.

### Animation
- **Calm and quick.** Fades and short slides (150–250ms), gentle ease-out. Status updates (ETA, bus position) transition smoothly. **No bounces, no playful spring** — the brand is reassuring, not bouncy.

### Imagery vibe
- Warm and human: real diverse family/teacher avatar photos (small, circular). Illustrations (the bus) are flat, friendly, slightly rounded. Overall palette of imagery is bright and warm, never moody.

---

## ICONOGRAPHY

- **Style:** clean **line icons, ~1.75–2px stroke, rounded caps & joins** — a Feather/Lucide-family look. Filled variants appear only for the active bottom-nav item and a few status glyphs.
- **Icon set used here:** **[Lucide](https://lucide.dev)** via CDN. The original product's exact icon source was not provided; Lucide is the closest match to the mockup's thin, rounded, modern strokes. **⚠ Substitution flagged** — if the product ships a specific set (e.g. custom SVGs, SF Symbols), drop them into `assets/icons/` and update this section.
- **Common glyphs:** house (Home), message-circle (Messages), bus/bus-front (Transport), clipboard-list / calendar-check (Activities/Assignments), user (Profile), bell (alerts), map-pin (location/ETA), credit-card (Payments), bar-chart (Reports), settings (gear), search, chevron-right, check-circle (completed / scanned-on), alert-triangle (warnings).
- **Emoji:** **Never** used as UI icons in the product. Unicode symbols aren't used as icons either — always a proper line icon.
- **Logo:** the JewelLink mark is a **blue faceted diamond ("jewel") topped by a gold graduation cap**, with a **cyan connection-node network** inside the diamond (the "connecting schools & families" motif). Wordmark: "JewelLink" in navy bold + "EDU" in a gold tab, tagline beneath. See `assets/`.
- **Bus motif:** a friendly yellow school-bus illustration is a recurring brand element in transport contexts (`assets/` crop available).

---

## CONTENT INDEX (manifest)

Root files:
- **`index.html`** — visual landing page indexing the whole system (links to both UI kits + foundations). Open this first.
- **`README.md`** — this file: product context, content + visual foundations, iconography, manifest.
- **`SKILL.md`** — Agent-Skill front-matter so this folder works as a downloadable Claude skill.
- **`colors_and_type.css`** — all design tokens: color scales, semantic colors, gradients, radii, shadows, spacing, type families + semantic type classes (`.jl-h1`, `.jl-body`, etc.).
- **`assets/`** — brand assets: `logo-full-color.png`, `logo-mark.png`, `logo-mark-onnavy.png`, bus illustration crop.
- **`docs_extracted/`** — plain-text extractions of the provided wireframe, API, backend, and RBAC docs.
- **`preview/`** — Design-System-tab cards (colors, type, spacing, components).
- **`ui_kits/`** — high-fidelity interactive recreations:
  - `ui_kits/parent-app/` — the Parent Mobile App (login → dashboard → messages → transport → pickup → activities).
  - `ui_kits/admin-dashboard/` — the Admin Web Dashboard.
- **`uploads/`** — original provided materials (mockup + source docx files).

---

*Built from provided mockup + docs. Where source was missing it is noted and flagged. Iterate by attaching the real repo or Figma.*