gw-svelte/DESIGN-LANGUAGE.md

# Goodwalk Design Language (2026 Refined Edition)

This document is the source of truth for Goodwalk’s visual design system. It defines the visual language, emotional tone, interaction philosophy, and implementation rules used across the website and future digital products.

The goal is not trend-chasing. The goal is to create a calm, trustworthy, modern experience that feels premium without becoming cold, corporate, or overly “tech”.

---

# Core Principles

## 1. Warmth over perfection
Goodwalk is a human service business. The experience should feel:
- calm
- warm
- trustworthy
- emotionally safe
- premium without arrogance

Avoid interfaces that feel:
- clinical
- overly corporate
- aggressive
- “SaaS-like”
- excessively polished

Slight softness and imperfection are intentional.

---

## 2. Refinement over redesign
The brand identity already works.

Modernisation should happen through:
- spacing
- typography
- image treatment
- motion
- surface depth
- consistency
- restraint

Do not redesign for novelty.

---

## 3. Emotion before decoration
Visual decisions must support:
- trust
- clarity
- calmness
- conversion

Do not add visual effects simply because they are modern.

Every effect must have emotional purpose.

---

## 4. Mobile-first experience
The site must feel premium on:
- 375px width
- average brightness outdoors
- thumb-driven interaction
- imperfect network conditions

Mobile is not a secondary layout.

---

## 5. Quiet luxury
The site should feel:
- expensive
- intentional
- calm
- understated

Not:
- flashy
- loud
- hyper-animated
- trend-driven

Modern premium design in 2026 is increasingly about restraint.

---

# Colour System

Defined in:
`src/lib/styles/variables.css`

| Token | Hex | Purpose |
|---|---|---|
| `--gw-green` | `#213021` | Primary brand colour |
| `--green-mid` | `#2d4230` | Hover states, elevated surfaces |
| `--green-soft` | `#344b38` | Optional softer elevated green |
| `--yellow` | `#ffd100` | Primary CTA accent |
| `--yellow-soft` | `#f2bf2f` | Premium warm accent alternative |
| `--off-white` | `#fbfbfb` | Primary background |
| `--surface-light` | `#f7f8f6` | Elevated light surface |
| `--text` | `#2e3031` | Default text |
| `--gray` | `#59606d` | Secondary copy |
| `--beige` | `#e5d6c2` | Warm neutral accent |

---

# Colour Philosophy

## Greens
The green palette represents:
- safety
- reliability
- groundedness
- nature
- professionalism

Greens should feel deep and organic rather than synthetic.

Avoid:
- saturated emerald tones
- neon greens
- cold blue-greens

---

## Yellow usage
Yellow is an accent, not a dominant UI colour.

Yellow should:
- guide attention
- signal warmth
- create optimism

Yellow should NOT:
- overpower sections
- become large reading surfaces
- create visual fatigue

For premium applications:
```css
background:
linear-gradient(
135deg,
#ffd54a,
#f2bf2f
);
```

This creates a warmer, more refined feel.

---

# Surface Design

## Philosophy
Modern interfaces should feel layered rather than flat.

Depth should come from:
- tonal separation
- soft gradients
- atmospheric shadows
- subtle edge highlights

NOT heavy shadows or strong borders.

---

## Surface Rules

### Avoid pure white
Never use:
```css
#ffffff
```

Prefer:
```css
#fbfbfb
#f7f8f6
#f5f6f3
```

---

## Avoid pure black
Never use:
```css
#000000
```

Prefer:
```css
#0f1115
#16181d
#1b1d21
```

---

## Micro gradients
Large flat surfaces should contain extremely subtle tonal variation.

Example:
```css
background:
linear-gradient(
180deg,
rgba(255,255,255,0.95),
rgba(247,248,246,0.95)
);
```

These gradients should be nearly invisible.

---

# Typography

Defined in:
`src/lib/styles/typography.css`

| Token | Family | Purpose |
|---|---|---|
| `--font-head` | Unbounded | Headlines |
| `--font-body` | Readex Pro | Body text |

---

# Typography Philosophy

Typography should create:
- confidence
- calmness
- readability
- rhythm

Avoid:
- excessive weight changes
- overly dense layouts
- tiny text
- over-stylised headings

---

# Typography Rules

## Body copy
Desktop:
```css
font-size: 15px;
line-height: 1.65;
```

Mobile:
```css
font-size: 16px;
line-height: 1.7;
```

---

## Headings
Hero headings:
```css
letter-spacing: -0.04em;
```

Section headings:
```css
letter-spacing: -0.02em;
```

Large headings should feel:
- compact
- intentional
- editorial

---

## Weight restraint
Prefer:
- 400
- 500
- 700

Avoid excessive font-weight variety.

Spacing should create hierarchy more than font weight.

---

# Spacing System

## Philosophy
Modern premium interfaces feel expensive because they are under-filled.

Whitespace is a feature.

Do not compress layouts simply to fit more information.

---

## Spacing Scale

Only use:
- 4
- 8
- 12
- 16
- 24
- 32
- 48
- 64
- 72
- 96

Avoid arbitrary spacing values.

---

# Border Radius

| Context | Radius |
|---|---|
| Standard cards | `28px` |
| Large feature containers | `32px` |
| Pills | `999px` |
| Small UI surfaces | `16px` |

The system should feel soft and approachable.

Avoid:
- sharp corners
- overly circular “bubble UI”

---

# Shadows & Depth

## Philosophy
Modern depth is atmospheric, not dramatic.

Shadows should feel:
- diffused
- soft
- realistic

Avoid:
- heavy elevation
- dark shadows
- obvious floating cards

---

## Standard shadows

### Definition shadow
```css
inset 0 0 0 1px rgba(17,20,24,0.045);
```

### Ambient depth
```css
0 8px 40px rgba(0,0,0,0.06);
```

### Inner edge highlight
```css
inset 0 1px 0 rgba(255,255,255,0.04);
```

---

# Texture & Grain

## Philosophy
Digital flatness feels artificial.

Subtle texture adds:
- realism
- warmth
- richness

Very subtle grain is encouraged on:
- hero sections
- dark surfaces
- footers
- large empty areas

Texture must never become visibly noisy.

---

# Motion System

## Philosophy
Motion should feel calm and physical.

Avoid:
- excessive movement
- bouncing
- playful overshoot
- aggressive transitions

---

## Preferred transition timing

```css
220ms cubic-bezier(0.22, 1, 0.36, 1)
```

---

## Hover behaviour

Modern hover effects should rely more on:
- brightness shifts
- opacity
- slight elevation
- subtle glow

Less:
```css
translateY(-6px)
```

More:
```css
translateY(-2px)
filter: brightness(1.02)
```

---

# Cards

## Philosophy
Cards should not feel disconnected from the layout.

Modern premium layouts use:
- softer separation
- lower contrast
- quieter surfaces

Avoid:
- harsh borders
- obvious “dashboard card” styling
- excessive shadowing

---

# Photography Direction

## This is one of the most important parts of the brand.

Photography should feel:
- candid
- warm
- emotionally genuine
- lightly cinematic
- calm
- naturally lit

Avoid:
- harsh HDR
- over-sharpening
- fake bokeh
- obvious AI look
- cluttered backgrounds

---

## Image treatment

Preferred:
- shallow depth of field
- warm colour grading
- natural greens
- soft contrast
- realistic shadows

Images should feel:
“premium lifestyle”
not:
“local flyer advertisement”

---

# Layout Philosophy

## Editorial rhythm
Not every section should feel identical.

The site should alternate between:
- dense
- airy
- emotional
- informational

This creates pacing and reduces fatigue.

---

## Controlled asymmetry
Small asymmetry is encouraged:
- offset images
- uneven crops
- staggered alignment
- imperfect positioning

This creates humanity and visual interest.

Avoid perfect grid rigidity everywhere.

---

# Interaction Design

## Buttons
Buttons should feel:
- tactile
- confident
- soft

Never aggressive.

---

## Hover states
Hover should:
- reward
- guide
- reassure

Not distract.

---

# Navigation

The navigation should feel:
- lightweight
- stable
- unobtrusive

Avoid:
- oversized sticky headers
- excessive blur
- flashy dropdowns

The navigation exists to support trust and conversion.

---

# Mobile UX Principles

## Thumb-first interaction
Primary actions should remain reachable.

Spacing should prevent accidental taps.

---

## Reduced visual noise
Mobile layouts should:
- simplify aggressively
- reduce simultaneous options
- preserve emotional tone

Not simply shrink desktop layouts.

---

# Accessibility

Always support:
- reduced motion
- readable contrast
- large tap targets
- visible focus states
- scalable text

Accessibility should feel integrated, not bolted on.

---

# Design Language Keywords

The Goodwalk experience should feel:

- calm
- premium
- trustworthy
- editorial
- grounded
- warm
- modern
- understated
- human
- emotionally safe
- refined
- spacious

Never:
- corporate
- loud
- trendy
- hyper-minimal
- cold
- sterile
- flashy

---

# What To Prioritise Next

Highest impact improvements:

1. Better photography consistency
2. Softer surface contrast
3. More atmospheric depth
4. Grain/texture implementation
5. Reduced hover movement
6. More editorial layouts
7. More restrained motion
8. More premium CTA treatment
9. Improved mobile spacing rhythm
10. More subtle card separation

---

# Final Rule

If a design decision looks impressive but reduces:
- clarity
- warmth
- trust
- calmness

Do not ship it.

Goodwalk should feel premium because it feels thoughtful — not because it feels flashy.

---

# Implementation Reference

Technical specs for what is currently live. Update this section when the codebase changes.

## Colour tokens (variables.css)

| Token | Hex | Status |
|---|---|---|
| `--gw-green` | `#213021` | ✅ Live |
| `--green-mid` | `#2d4230` | ✅ Live |
| `--green-soft` | `#344b38` | ✅ Live |
| `--yellow` | `#ffd100` | ✅ Live |
| `--yellow-soft` | `#f2bf2f` | ✅ Live |
| `--gray` | `#59606d` | ✅ Live |
| `--beige` | `#e5d6c2` | ✅ Live |
| `--off-white` | `#fbfbfb` | ✅ Live |
| `--surface-light` | `#f7f8f6` | ✅ Live — use where a surface sits above `--off-white` |
| `--text` | `#2e3031` | ✅ Live |

## Typography (live values)

| Context | Size | Weight | Tracking | Line-height |
|---|---|---|---|---|
| Hero h1 | `clamp(34px, 4vw, 56px)` | 800 | `-0.04em` | `1.05` |
| Section headings | `42px` | 700 | `-0.02em` | `1.08` |
| Body (desktop) | `15px` | 400 | — | `1.65` |
| Body (mobile) | `16px` | 400 | — | `1.70` |
| Buttons | `14px` | 700 | `0.01em` | `1.2` |
| Eyebrow | `13px` | 700 | `0.08em` | — |

## Section padding rhythm (live values)

| Section | Padding |
|---|---|
| `#promise`, `#services` | `96px 0` |
| `#values`, `#testimonials`, `#info` | `72px 0` |
| `#newlead` | `80px 0` |
| `#instagram` | `60px` |

## Card hover behaviour (live values)

```css
/* Service and testimonial cards */
transform: translateY(-2px);
filter: brightness(1.02);
box-shadow: inset 0 0 0 1px rgba(17,20,24,0.06), 0 8px 40px rgba(0,0,0,0.08);
```

Reduced from `translateY(-6px)` — calmer, more restrained per design philosophy.

## Service icon bubble gradient (live)

```css
background: linear-gradient(135deg, #ffd54a, var(--yellow-soft));
```

Angled, warmer gradient — replaces the flat vertical yellow.

## Testimonial card surface (live)

```css
background: linear-gradient(180deg, #ffffff 0%, var(--off-white) 100%);
```

Micro-gradient — avoids flat pure white per surface design rules.

## Scroll reveals (live)

JS (`+layout.svelte`): `IntersectionObserver` targets `.section-heading`, `.service-card`, `.testimonial-card`, `.value-card`. Adds `data-reveal` attribute on mount, toggles `.is-visible` when the element crosses `40px` from the viewport bottom.

CSS (`base.css`): `opacity 0 → 1`, `translateY(20px) → none`, `0.5s`. Wrapped in `prefers-reduced-motion: no-preference`.

## Hero image gradient (live)

`#hero::after` pseudo-element: `linear-gradient(to top, var(--gw-green), transparent)`, `height: 120px`, covering the right 58% of the section. Hidden on mobile.

## Not yet implemented

| Item | Notes |
|---|---|
| Grain / texture | Needs a noise SVG or canvas overlay — skip until photography is consistent |
| `--surface-light` usage | Token is defined; not yet applied to any component |
| `--green-soft` usage | Token is defined; candidate for mega-menu icon hover state |
| More editorial layouts | Structural work — needs a design pass per page |