ponzischeme89
315 lines
13 KiB
Markdown
315 lines
13 KiB
Markdown
# Goodwalk — Design Language & Theme Reference
|
||
|
||
> Source of truth for visual language, spacing, tone, interaction style, and component feel across the Goodwalk frontend.
|
||
|
||
---
|
||
|
||
## Brand Palette
|
||
|
||
| Token | Value | Usage |
|
||
|---|---|---|
|
||
| `--gw-accent-color-1` | `#FFD100` | Highlight / CTA yellow |
|
||
| `--gw-accent-color-2` | `#213021` | Deep forest green (primary brand) |
|
||
| `--gw-accent-color-3` | `#59606D` | Muted slate |
|
||
| `--gw-accent-color-4` | `#E5D6C2` | Warm sand |
|
||
| `--gw-accent-color-5` | `#FFFFFF` | White |
|
||
| `--gw-accent-color-6` | `#000000` | Black |
|
||
|
||
Background texture: warm cream gradient (`#f4f1ea` → `#f1ede5`).
|
||
|
||
Typography: **DM Sans** (body), system heading scale.
|
||
|
||
---
|
||
|
||
## Desktop Design Language
|
||
|
||
**Tone:** Premium, intentional, warm. Not corporate. Feels like a trusted local service with high craft.
|
||
|
||
**Spacing:** 8-point grid. Components breathe. Generous white-space is never wasted.
|
||
|
||
**Surfaces:** Semi-transparent white (`rgba(255,255,255,0.94)`) on warm cream background. Cards carry a subtle multi-layer shadow.
|
||
|
||
**Borders:** Warm tan `#e7ddd1`, never cold grey.
|
||
|
||
**Shadows:** Multi-stop warm shadows — `0 4px 8px rgba(17,16,14,0.04), 0 16px 34px rgba(17,16,14,0.08)`.
|
||
|
||
**Navigation:** Sticky header with glassmorphism on scroll. Bottom tab bar on mobile (see below).
|
||
|
||
**Radius scale:** `8px` (inputs), `12px` (cards), `16px` (modals/sheets), `28px` (pills/nav).
|
||
|
||
**Interactions:** Subtle hover lifts (`translateY(-1px)`), scale-down press (`scale(0.96–0.98)`), smooth 150ms ease transitions.
|
||
|
||
---
|
||
|
||
## Admin Design System
|
||
|
||
Admin uses a theming layer on top of the base brand. The active theme is stored in `localStorage` as `gw_admin_theme`.
|
||
|
||
| Theme | Accent | Highlight |
|
||
|---|---|---|
|
||
| main | `#213021` | `#ffd100` |
|
||
| pink | `#c54b8c` | `#ffcadf` |
|
||
| purple | `#6f55d9` | `#d8cbff` |
|
||
| yellow | `#9a7700` | `#ffe08a` |
|
||
|
||
Admin CSS variables (set via inline `style` on the shell element):
|
||
|
||
```
|
||
--admin-accent, --admin-accent-dark, --admin-accent-rgb
|
||
--admin-topnav-start, --admin-topnav-end
|
||
--admin-highlight, --admin-highlight-rgb
|
||
--admin-button-text
|
||
--admin-font-scale
|
||
```
|
||
|
||
The admin header uses a gradient from `--admin-topnav-start` → `--admin-topnav-end`.
|
||
|
||
---
|
||
|
||
## Members Design System
|
||
|
||
Members uses the core brand palette directly (no theme switching).
|
||
|
||
```css
|
||
--members-accent: #213021
|
||
--members-accent-dark: #172217
|
||
--members-highlight: #ffd100
|
||
--members-border: #e7ddd1
|
||
--members-surface: rgba(255, 255, 255, 0.94)
|
||
--members-surface-soft: #f8f4ed
|
||
--members-surface-muted: #f2ece3
|
||
--members-text: #1d261d
|
||
--members-text-muted: #6b635c
|
||
```
|
||
|
||
---
|
||
|
||
## Mobile Design Language
|
||
|
||
> Mobile users receive a **dedicated, purpose-built experience** — not a squeezed desktop page. All mobile screens live under `/admin/m/` (admin) or `/members/m/` (members).
|
||
|
||
### Philosophy
|
||
|
||
- **Native-app inspired.** Feel fast, responsive, and deliberate. Every tap should feel satisfying.
|
||
- **One-handed first.** Primary actions sit at thumb-reach (bottom half of screen). Navigation is bottom-anchored.
|
||
- **Dense but not cramped.** Maximum information per screen without feeling overwhelming.
|
||
- **No desktop patterns forced onto phones.** Never squeeze a data table onto a 390px screen. Use lists, cards, and sheets instead.
|
||
|
||
### Mobile vs Desktop Rules
|
||
|
||
| Rule | Desktop | Mobile |
|
||
|---|---|---|
|
||
| Navigation | Top sticky header + subnav tabs | Fixed bottom tab bar |
|
||
| Primary actions | Anywhere sensible | Bottom-anchored action bar or prominent nav item |
|
||
| Modals | Standard centred modal | Slide-up bottom sheet |
|
||
| Tables / data grids | Full table layout | Vertical list with disclosure rows |
|
||
| Forms | Multi-column layouts OK | Single column, full-width fields |
|
||
| Page titles | In header nav | Sticky per-page header (MobilePageShell) |
|
||
| Content width | Max-width capped at 1320px | Full bleed (16px horizontal padding) |
|
||
|
||
### Mobile Token Layer
|
||
|
||
All mobile screens inherit tokens from the `MobileAppShell` component. These tokens provide a consistent design system shared between Admin and Member mobile experiences:
|
||
|
||
```css
|
||
/* Palette */
|
||
--m-accent: #213021 /* primary action colour */
|
||
--m-accent-dark: #172217 /* hover/active state */
|
||
--m-accent-rgb: 33, 48, 33 /* for rgba() usage */
|
||
--m-highlight: #ffd100
|
||
--m-bg: #f4f1ea
|
||
--m-surface: rgba(255,255,255,0.96)
|
||
--m-surface-soft: #f8f4ed
|
||
--m-surface-muted: #f2ece3
|
||
--m-border: #e7ddd1
|
||
--m-border-soft: rgba(231,221,209,0.6)
|
||
--m-text: #1d261d
|
||
--m-text-muted: #6b635c
|
||
--m-text-faint: #a09890
|
||
|
||
/* Shadows */
|
||
--m-shadow-card: 0 2px 8px rgba(17,16,14,0.06), 0 8px 20px rgba(17,16,14,0.08)
|
||
--m-shadow-sheet: 0 -8px 40px rgba(17,16,14,0.18)
|
||
--m-shadow-button: 0 4px 16px rgba(33,48,33,0.28)
|
||
|
||
/* Radii */
|
||
--m-radius-xs: 6px
|
||
--m-radius-sm: 10px
|
||
--m-radius: 16px /* default card/button radius */
|
||
--m-radius-lg: 24px
|
||
--m-radius-xl: 32px /* bottom sheet corners */
|
||
|
||
/* Spacing scale (4-point base) */
|
||
--m-space-1: 4px
|
||
--m-space-2: 8px
|
||
--m-space-3: 12px
|
||
--m-space-4: 16px
|
||
--m-space-5: 20px
|
||
--m-space-6: 24px
|
||
--m-space-8: 32px
|
||
--m-space-10: 40px
|
||
|
||
/* Type scale */
|
||
--m-text-xs: 11px
|
||
--m-text-sm: 13px
|
||
--m-text-md: 15px /* body text */
|
||
--m-text-lg: 17px /* page titles */
|
||
--m-text-xl: 20px
|
||
--m-text-2xl: 24px
|
||
--m-text-3xl: 30px /* stat card values */
|
||
|
||
/* Touch */
|
||
--m-touch-min: 44px /* minimum touch target (iOS HIG / WCAG) */
|
||
|
||
/* Layout */
|
||
--m-bottom-nav-h: 72px
|
||
--m-header-h: 56px
|
||
--m-page-px: 16px /* horizontal page padding */
|
||
|
||
/* Safe areas (iOS notch/home bar) */
|
||
--m-safe-top: env(safe-area-inset-top, 0px)
|
||
--m-safe-bottom: env(safe-area-inset-bottom, 0px)
|
||
```
|
||
|
||
For the **Admin mobile** variant, `--m-accent`, `--m-accent-dark`, `--m-accent-rgb`, and `--m-highlight` are overridden by the admin's active theme variables (`--admin-accent` etc.), so the admin theme switcher works on mobile too.
|
||
|
||
### Touch Target Minimums
|
||
|
||
- Every interactive element must be at least **44 × 44px** (iOS HIG) / **48 × 48dp** (Material).
|
||
- Use `min-height: var(--m-touch-min)` on buttons and list rows.
|
||
- Pad tappable areas generously — don't rely on text size alone for target size.
|
||
|
||
### Bottom Navigation Principles
|
||
|
||
The bottom tab bar is the **primary navigation** on mobile. It is always visible and never hides during scroll.
|
||
|
||
- Max **5 items** per bar. Fewer is better.
|
||
- Icons must be recognisable without labels — labels are shown but should not be the only differentiator.
|
||
- **One prominent item** allowed per bar (filled background, accent colour). Use for the most important CTA (e.g. Add Client, Complete Onboarding).
|
||
- Badge dots use red `#e03e3e` for unread counts (messages).
|
||
- The bar uses glassmorphism: `rgba(251,247,240,0.92)` background, `backdrop-filter: blur(18px)`, `border-radius: 28px`. Never make it a plain opaque bar.
|
||
- Accounts for safe area: `padding-bottom: calc(12px + env(safe-area-inset-bottom))`.
|
||
- Active state: light green tint `rgba(33,48,33,0.08)` + accent text colour.
|
||
- Inactive state: `--m-text-muted` colour.
|
||
- Press: `scale(0.94)` transform with `transition: 0.15s`.
|
||
|
||
### Spacing and Rhythm (Small Screens)
|
||
|
||
- Page content padding: `16px` horizontal.
|
||
- Section vertical spacing: `24px` top (tight variant: `16px`).
|
||
- Section labels: `11px`, `800` weight, `0.08em` letter-spacing, uppercase, muted colour.
|
||
- Card internal padding: `16px`.
|
||
- List row minimum height: `44px`. Default padding: `12px 0`.
|
||
- Group gaps: `8px` between sibling cards/list items, `12px` between elements within a card.
|
||
- Never use horizontal padding smaller than `8px` inside a card.
|
||
|
||
### Mobile Card / List Patterns
|
||
|
||
**Cards:**
|
||
- `border-radius: 16px`, warm border `#e7ddd1`, multi-layer warm shadow.
|
||
- Default: white surface with shadow.
|
||
- Subtle: `#f8f4ed` surface, no shadow (for secondary content blocks).
|
||
- Highlight: `3px` left border in accent colour (for time-sensitive or important content).
|
||
- Press: `scale(0.98)`.
|
||
|
||
**List items (MobileListItem):**
|
||
- Full-width rows with leading slot (icon/avatar), label, sublabel, trailing area (meta, badge, chevron).
|
||
- Divider is a `1px` line at `60%` opacity — not a full-width separator.
|
||
- Never nest more than 2 lines of text in a list item on mobile.
|
||
- Chevron (`›`) indicates navigable rows.
|
||
|
||
### Mobile Form Behaviour
|
||
|
||
- Single-column layouts only.
|
||
- Labels above inputs (`13px`, `700` weight).
|
||
- Full-width inputs with `min-height: 44px`, `border-radius: 10px`.
|
||
- Focus ring: `3px` at `0.12` opacity using accent colour.
|
||
- Error messages below the field in red (`#991b1b`), not in a toast.
|
||
- Use `MobileFormField` to wrap every input — it ensures consistent spacing and error handling.
|
||
- Avoid more than 4-5 fields visible at once without sectioning.
|
||
|
||
### Hierarchy of Headers and Page Titles
|
||
|
||
1. **App header** (`MobileHeader`) — optional sticky brand strip at the very top. Use only when brand context is needed (e.g. on first entry to a section).
|
||
2. **Page header** (`MobilePageShell`) — per-page sticky title bar. Always present. Contains: back button (44px touch), centred title (`17px, 700`), right-side action slot.
|
||
3. **Section headings** (`MobileSection title=`) — `11px, 800, uppercase, muted`. Acts as a visual grouping label, not a navigational heading.
|
||
4. **Card titles / list labels** — `15px, 600` for primary labels, `13px` for sublabels.
|
||
|
||
Do not repeat the page title in the body content. The sticky page header is the single source of truth for where you are.
|
||
|
||
### Motion and Transitions
|
||
|
||
- Duration: `150ms` for micro-interactions (hover, press), `260ms` for sheet entry.
|
||
- Easing: `cubic-bezier(0.25, 0.46, 0.45, 0.94)` (ease-out feel).
|
||
- Sheet entry: `fly` transition upward 320px, 260ms.
|
||
- Press scales: `0.94–0.98` depending on element size (buttons larger → less scale, small icons → more scale).
|
||
- No bouncing or spring physics on primary navigation (too distracting).
|
||
- Reserve spring easing (`cubic-bezier(0.34, 1.56, 0.64, 1)`) for playful one-off moments only.
|
||
- Skeleton loading: sinusoidal opacity pulse `0.45 → 0.85`, `1.4s` period, staggered delays.
|
||
|
||
### Empty / Loading / Error States
|
||
|
||
Use `MobileEmptyState` for all three variants:
|
||
|
||
- **Loading:** animated skeleton cards (3 staggered shimmer bars).
|
||
- **Empty:** emoji icon, title, optional body text, optional CTA button.
|
||
- **Error:** same as empty but `role="alert"`, red title, warning emoji.
|
||
|
||
Rules:
|
||
- Every list/data section must handle all three states explicitly.
|
||
- Never show a spinner in place of a full-page experience — use skeleton screens.
|
||
- Empty state CTAs should always provide a path forward (e.g. "Book a Walk").
|
||
|
||
### Admin and Member Mobile Alignment
|
||
|
||
Admin and Member mobile experiences are visually indistinguishable in structure — they share:
|
||
- The same `MobileAppShell` token layer.
|
||
- The same component library.
|
||
- The same bottom nav design, touch targets, motion, and type scale.
|
||
- The same card/list/section patterns.
|
||
|
||
They differ in:
|
||
- Admin inherits the admin theme (accent colour changes with theme switcher).
|
||
- Members always uses the green brand palette.
|
||
- Different nav items and routes.
|
||
- Different auth patterns (admin: CSR localStorage; members: server cookie + localStorage).
|
||
- Different feature sets and business logic.
|
||
|
||
### What Must Never Happen in Mobile Views
|
||
|
||
- **No horizontal scrolling** in page content. Horizontal scroll only inside explicit scroll containers (e.g. a chip row).
|
||
- **No data tables.** Replace with vertical lists with disclosure rows or summary cards.
|
||
- **No fixed-position elements other than the bottom nav and action bar.** Avoid top banners that take up screen space.
|
||
- **No touch targets smaller than 44px.** Not even "less important" actions.
|
||
- **No modals that cover the full screen** (except full-screen sheets on purpose). Prefer slide-up panels.
|
||
- **No desktop responsive hacks in mobile components.** Do not import mobile tokens into desktop components or add `@media (max-width)` patches to the mobile components file.
|
||
- **No mixing desktop and mobile layouts in the same file** (e.g., showing/hiding via CSS in a shared component). Use separate route/layout files.
|
||
- **No navigation items that do not exist on mobile.** If a feature isn't in the mobile nav, provide a clear path to the desktop version or a dedicated in-app screen.
|
||
|
||
---
|
||
|
||
## Component Library Summary
|
||
|
||
### Shared Desktop Components
|
||
Located in `src/components/` and `src/lib/`.
|
||
|
||
### Shared Mobile Components
|
||
Located in `src/lib/mobile/components/`. All use the `--m-*` token layer.
|
||
|
||
| Component | Purpose |
|
||
|---|---|
|
||
| `MobileAppShell` | Top-level layout wrapper, token layer, bottom nav integration |
|
||
| `MobilePageShell` | Per-page container with sticky title header |
|
||
| `MobileHeader` | Optional branded app header strip |
|
||
| `MobileBottomNav` | Fixed bottom tab bar |
|
||
| `MobileSection` | Content group with optional title and action link |
|
||
| `MobileCard` | Touchable surface card |
|
||
| `MobileListItem` | Single list row (leading/label/sublabel/trailing) |
|
||
| `MobileStatCard` | Metric display card for dashboards |
|
||
| `MobileActionBar` | Sticky bottom CTA button area |
|
||
| `MobileSearchBar` | Touch-friendly search input with clear button |
|
||
| `MobileFormField` | Form field wrapper (label + input slot + error/hint) |
|
||
| `MobileEmptyState` | Empty / loading skeleton / error state |
|
||
| `MobileFilterSheet` | Slide-up bottom sheet for filters |
|
||
| `MobileTabs` | Segmented tab switcher |
|