gw/theme.md

# Goodwalk Theme

This document captures the current frontend visual language so future public, admin, and members work stays consistent.

## Core direction

Goodwalk should feel:

- calm
- premium but friendly
- tactile rather than flat
- editorial rather than dashboard-generic
- warm and human, not corporate SaaS

The site should not drift into bright blue admin styling, generic Tailwind blocks, or default white-card-on-grey-dashboard patterns.

## Design tokens

Primary tokens live in `frontend/src/app.css`.

### Brand colours

- `--gw-accent-color-1`: `#FFD100`
  - warm yellow accent
  - use for highlights, badges, emphasis, and selective CTA attention
- `--gw-accent-color-2`: `#213021`
  - deep Goodwalk green
  - use for primary buttons, dark hero surfaces, nav shells, and strong contrast areas
- `--gw-accent-color-3`: `#59606D`
  - muted slate for secondary text
- `--gw-accent-color-4`: `#E5D6C2`
  - warm beige for soft surfaces and form focus tones
- `--gw-body-background-color`: `#FBFBFB`
  - base light background

### Supporting neutrals used in practice

- `#f7f2e9` to `#f5efe5`
  - warm page background gradients
- `#fcfaf7`
  - default input surface
- `#f8f4ed` / `#f5f1ea`
  - soft card and hover fills
- `#5f6773` / `#7e8793`
  - muted copy

## Typography

### Headings

- Use `DM Sans` / the `--gw-h*` heading families for hero, section, and card titles.
- Headings should feel slightly compact and graphic.
- Prefer tighter letter spacing on key titles: around `-0.03em` to `-0.04em`.

### Body

- Use `DM Sans` via `--gw-primary-font-font-family`.
- Body copy should stay easy to read, relaxed, and not overly condensed.

### Voice in UI copy

- Friendly and direct.
- Short, practical, low-jargon.
- Avoid product-management filler like “optimize workflow” or “streamline operations”.

## Layout rules

### Width and spacing

- Respect the site max width from `--gw-site-max-width`.
- Use generous outer padding, especially on desktop.
- Prefer 20px to 32px internal card padding.
- Use breathing room, but keep related content grouped tightly enough that screens do not feel empty.

### Backgrounds

- Avoid flat, clinical backgrounds for major screens.
- Prefer subtle radial gradients or layered warm neutrals.
- Dark shells should usually use a green gradient, not a flat navy or black.

### Cards and panels

- Cards should feel soft and layered.
- Use large radii, usually `20px` to `28px`.
- Prefer soft shadows and subtle borders over hard outlines.
- White surfaces should often be slightly warm rather than pure neutral white.

## Components

### Buttons

- Primary actions: deep green background with white text.
- Secondary actions: white or warm-light surface with green text and a subtle border.
- Yellow should be used selectively for emphasis, not everywhere.
- Buttons should be rounded and slightly weighty.

### Forms

- Inputs should be warm white with rounded corners.
- Focus states should use green borders plus a soft yellow halo where appropriate.
- Avoid thin default browser-looking inputs.
- Labels should be compact, bold, and clear.

### Navigation

- Private-area nav should visually echo the public hero/header language.
- Use dark green gradient shells with rounded containers.
- Nav items should feel like pills, not generic tabs.
- Active state should use warm highlighted surfaces or borders, not bright blue.

### Status and feedback

- Success: soft green background with darker green text.
- Warning: warm cream/yellow background with brown-gold text.
- Error: warm red-tinted background, never harsh pure red blocks unless necessary.

## Public-site cues to preserve

Patterns already established in the public frontend:

- rounded cream and white surfaces
- dark green hero bands with subtle gradients
- yellow accent sparingly applied
- expressive heading typography
- soft editorial spacing
- decorative but restrained atmosphere

Reference files:

- `frontend/src/app.css`
- `frontend/src/routes/Home-2.svelte`
- `frontend/src/components/BookingForm.svelte`

## Admin and members adaptation

Private areas should be visually related to the public site, not a separate product.

That means:

- keep the same palette family
- keep the same heading/body font pairing
- reuse warm backgrounds and soft cards
- keep navigation premium and branded
- avoid introducing a separate blue dashboard theme

Admin can feel slightly more operational than public pages, but still within the same brand system.
Members can feel slightly calmer and more reassuring, but should still use the same primitives.

## Interaction and motion

- Motion should be subtle and purposeful.
- Small hover lifts and shadow increases are fine.
- Avoid excessive bounce or ornamental animation in private tools.
- Keep transitions short, around `150ms` to `220ms`.

## What to avoid

- bright corporate blue as the main private-area colour
- generic grey dashboard backgrounds
- square cards and sharp corners
- system-font-only interfaces when the main frontend uses expressive typography
- purple or neon accents
- overuse of yellow as a primary fill everywhere
- dense enterprise table styling with no warmth

## Implementation guidance

When adding new screens:

1. Start from tokens in `frontend/src/app.css`.
2. Reuse existing private shell patterns from:
   - `frontend/src/routes/admin/+layout.svelte`
   - `frontend/src/routes/members/+layout.svelte`
3. Prefer extending shared page primitives instead of inventing a one-off visual language.
4. If a new screen feels like a different app, it is off-theme.

## Quick checklist

- Does it use Goodwalk green as the primary structural colour?
- Does the page background feel warm rather than cold?
- Are the headings using the established display type style?
- Are cards soft, rounded, and slightly layered?
- Are inputs and buttons consistent with BookingForm and the public site?
- Would the screen still look like Goodwalk if the logo were removed?