# Kainos Design Methodology

A start-to-finish process for producing beautiful software — synthesised from *Refactoring UI* (Wathan & Schoger), Google's DESIGN.md format, and Kainos brand standards.

The output of this process is a `DESIGN.md` file and code. Everything else is scaffolding.

---

## The Core Principles (memorise these)

**1. Prose beats tokens.** A specific reference — "a GOV.UK-style enterprise dashboard" — carries more information than a dozen hex values. Tokens are context. Prose is the design.

**2. Hierarchy is everything.** Visual hierarchy is not decoration; it is structure. Use size, weight, and colour together. Never rely on one alone.

**3. Systems beat decisions.** Define your spacing scale, type scale, and colour shades upfront. Then pick from the system — never pick from the picker.

**4. Start with too much, remove.** White space, features, labels, borders: start with more than you need and pull back. Never add to something that isn't already too bare.

**5. Features first, layout last.** An app is a collection of features. Design one feature. The shell comes from the features, not before them.

---

## Phase 1 — Intent (before any design tool)

Answer these questions with a single sentence each:

| Question | Drives |
|---|---|
| Who is the primary user and what do they need to accomplish? | Feature scope |
| What is a *specific real-world object* this interface resembles? | Overall personality |
| What is the single most important action per screen? | Hierarchy anchor |
| What must this design never feel like? | Do's and Don'ts |

**The reference test.** If your description uses only adjectives ("clean, modern, trustworthy"), rewrite it as a reference ("a Bloomberg terminal rebuilt with restraint" or "a Notion page inside a Kainos wrapper"). Adjectives describe a region. References describe a point.

Kainos enterprise default: *"A British civil-service tool — purposeful, unhurried, and trusted. No decoration earns its place without a functional argument."*

---

## Phase 2 — Systems (define before any pixel)

Define these in your `DESIGN.md` frontmatter **before** designing anything.

### Spacing and sizing scale

Base: **8px**. Every value is a multiple or factor.

```
4px   8px   12px   16px   24px   32px   48px   64px   96px   128px   192px   256px
```

Values must differ by at least 25% from their neighbours. Never pick an arbitrary value.

### Type scale

```
12px   14px   16px   18px   20px   24px   32px   48px   64px
```

Two weights only: **400** (body) and **600–700** (emphasis). Never go below 400 in UI.
Two fonts max: a display font for headings, a neutral sans for body.

### Colour

- Define 8–10 shades per key hue upfront. Never open the colour picker mid-task.
- Work in HSL. Grey is not `hsl(0, 0%, 50%)` — it is the background hue at reduced saturation and lightness.
- Grey text on a coloured background: hand-pick a hue-shifted lighter tint, not literal grey or opacity reduction.
- Minimum contrast: 4.5:1 for normal text (WCAG AA).
- Kainos Blue: `#283583` / `hsl(232, 53%, 35%)`. Kainos Green: `#61a83f` / `hsl(103, 44%, 45%)`.

### Rounded scale

```yaml
rounded:
  none: 0
  sm:   2px
  md:   4px
  lg:   8px
  xl:   12px
  full: 9999px
```

Pick one register and stay there. Mixing sharp and rounded in the same interface always looks worse.

---

## Phase 3 — Feature-First Design

Never start with the navigation shell. Start with the **single most important feature**.

**Workflow:**
1. List the elements the feature needs (fields, buttons, data).
2. Design in greyscale. Hierarchy must work before colour is added.
3. Once the hierarchy is solid, introduce colour.
4. Make it real (build it). Iterate on the live version.
5. Move to the next feature. Let the shell emerge.

**Be a pessimist.** Only design what you are ready to build. Nice-to-have features designed now become blockers later. Design the smallest useful version you can ship.

**Don't over-invest in static mockups.** Wireframes are disposable. Their job is to explore layout. Leave them behind the moment you have made a decision.

---

## Phase 4 — Hierarchy

Visual hierarchy is the most effective tool for making something feel designed.

### The three levels

| Level | Treatment |
|---|---|
| Primary | Dark colour, heavier weight (600–700), normal-to-large size |
| Secondary | Softer colour (same hue, higher lightness), normal weight |
| Tertiary | Much lighter colour or smaller size — not both |

### Rules

- **De-emphasise to emphasise.** If the focal element isn't standing out, soften what is competing with it — don't push the focal element harder.
- **Size is not enough.** A bold 18px title reads more clearly than a regular 30px title. Use weight and colour to let you reduce size.
- **Labels last resort.** If format and context convey meaning, the label is noise. "12 left in stock" beats "In stock: 12". Format data as prose.
- **Separate visual hierarchy from document hierarchy.** An `<h1>` tag does not have to be large. Style for visual role, not for semantic tag.
- **Semantics are secondary for buttons.** Every action sits in a hierarchy: primary (solid, high contrast), secondary (outline or lower contrast), tertiary (link style). Destructive actions are not automatically primary — combine with a confirmation step.
- **Icons are heavy.** Solid icons cover surface area like bold text. Give them a softer colour, not full contrast, when they sit alongside text.

---

## Phase 5 — Layout and Spacing

### White space

Start with too much. White space is almost always *added* to a design, which means you start with the minimum and end up with "not bad". Start with excess and remove until the density is right. Dense UIs exist — they are a deliberate choice, not the default.

### Sizing

- Give each element the size it needs. Don't stretch it to fill a container.
- Fixed-width sidebars and navs. Fluid content areas. Do not slave a sidebar's width to a percentage grid — it will be the wrong width on every screen size.
- Use `max-width` for centred content. A login card that wants to be 480px should have `max-width: 480px`, not a 6-of-12 column span.
- Relative units (`em`, `%`) do not scale uniformly. A headline at `2.5em` that looks right on desktop becomes enormous on mobile when the root size drops. Define breakpoint font sizes explicitly.

### Grids

Use a spacing scale, not a column grid, as your primary layout tool. Column grids constrain fluid widths and create the wrong kind of consistency — one that changes with viewport width. Reach for fixed widths and flexbox instead.

---

## Phase 6 — Colour

- **Ditch hex for HSL.** Choosing colours by feel is far easier when you can reason about hue, saturation, and lightness independently.
- **You need more shades than you think.** Define 9 shades per colour before you start. Name them 100–900. This prevents mid-project colour drift.
- **Don't let lightness kill saturation.** Light colours need more saturation to avoid looking washed out. Rotate the hue slightly towards yellow as you lighten; rotate towards blue/purple as you darken.
- **Greys are warm or cool.** Match the temperature of your greys to your brand colour. A warm-toned product should never have blue-grey neutrals.
- **Colour alone is not accessible.** Never use colour as the only signal for state (error, success, warning). Pair with an icon or label.

---

## Phase 7 — Typography

- **Establish a type scale upfront.** Pick from the scale. Never eyeball a size between two values.
- **Good fonts.** Pay for them if needed. Neutral sans: Inter, DM Sans. Humanist sans: Plus Jakarta Sans, Nunito. Display: Space Grotesk, Outfit. Serif: Fraunces, Libre Baskerville.
- **Line length.** 45–75 characters for body. Set `max-width: 65ch` on prose containers.
- **Align to baseline, not centre.** When text of different sizes sits side by side, align baselines, not vertical centres.
- **Line height is proportional.** Tight for large headings (1.1–1.2). Loose for small body text (1.5–1.7).
- **Letter-spacing.** Tighten large display headings (`-0.02em`). Loosen all-caps labels (`0.08em`). Leave everything else alone.
- **Links don't always need colour.** Inside a paragraph, underline is enough. Only make links blue when they are isolated and the context doesn't make them obvious.

---

## Phase 8 — Depth and Finishing

### Elevation

- **Flat UIs still have depth.** Use tonal layers (lighter surface = higher elevation), borders, and overlap instead of shadows where the aesthetic demands it.
- **Shadows have two parts.** A sharp, low-opacity shadow for the umbra; a soft, diffuse one for the ambient glow. Together they look physical. One alone looks cheap.
- **Simulate a consistent light source.** Light comes from above. Top/left faces are lighter. Bottom/right shadows are darker. Buttons in an inset state reverse this.

### Finishing touches

- **Supercharge defaults.** Replace generic browser bullets with purpose-built icons. Replace boring form inputs with clearly structured layouts. Replace empty content areas with onboarding prompts.
- **Accent borders.** A 4px left border in the brand colour on a card does more for polish than a full border.
- **Decorate backgrounds.** Subtle patterns, a single large faded icon, or a tonal gradient on a hero section break the monotony of flat surfaces.
- **Empty states matter.** Design them. An empty table is the first thing a new user sees.
- **Fewer borders.** Use space and tonal colour shifts to separate elements before reaching for a border. Every border is visual noise until proven necessary.

---

## The Output: DESIGN.md

Every project that has a UI must have a `DESIGN.md` at the root. It has two parts:

**YAML frontmatter** — machine-readable tokens (colours, typography, spacing, rounded, component variants). Exported to Tailwind or DTCG with `npx @google/design.md export`.

**Markdown body** — human-readable prose in this order:
1. Overview
2. Colors
3. Typography
4. Layout
5. Elevation & Depth
6. Shapes
7. Components
8. Do's and Don'ts

Lint with `npx @google/design.md lint DESIGN.md`. Fix all errors; address all warnings.

---

## Kainos Brand Defaults

When building Kainos-facing or client-facing tools on behalf of Kainos. Canonical source: the `kainos-ui-design` skill.

```yaml
colors:
  # Semantic
  primary:     "#283583"   # Kainos Blue
  primary-on:  "#ffffff"
  accent:      "#61a83f"   # Kainos Green
  neutral:     "#f4f4f6"
  on-surface:  "#1a1a2e"
  # Brand palette (raw)
  brand-mid-blue:      "#41679f"   # secondary backgrounds, chart series 2
  brand-dark-green:    "#004631"   # divider sections, dark hero backgrounds
  brand-grey:          "#575756"   # body text in documents and slides
  brand-orange:        "#ec6608"   # accent only — chart series 5
  brand-bright-green:  "#cfd600"   # accent only — chart series 4
  brand-bright-blue:   "#009fe3"   # accent only — chart series 3
typography:
  heading:
    fontFamily: Foundry Gridnik, Galano Grotesque, Century Gothic, sans-serif
    fontWeight: "700"
  body:
    fontFamily: Arial, Helvetica, sans-serif
    fontWeight: "400"
    fontSize: 16px
    lineHeight: 1.6
```

**Font hierarchy:** Foundry Gridnik (licensed) → Galano Grotesque (licensed alt) → Century Gothic (required fallback, always available). Never list Century Gothic first. Never substitute outside this stack.

**CSS custom properties (required on every Kainos web project):**

```css
:root {
  --k-blue:         #283583;
  --k-green:        #61a83f;
  --k-mid-blue:     #41679f;
  --k-dark-green:   #004631;
  --k-grey:         #575756;
  --k-orange:       #ec6608;
  --k-bright-green: #cfd600;
  --k-bright-blue:  #009fe3;
  --k-paper:        #ffffff;
  --k-font-heading: "Foundry Gridnik", "Galano Grotesque", "Century Gothic", sans-serif;
  --k-font-body:    "Century Gothic", "Galano Grotesque", sans-serif;
  --k-radius:     4px;
  --k-shadow:     0 2px 8px rgba(0, 0, 0, 0.12);
  --k-transition: all 0.2s ease;
  --k-max-width:  1200px;
}
```

**Chart palette order:** Blue → Green → Bright Blue → Bright Green → Orange.

---

## Voice and Tone

Kainos brand traits: **Honest · Humble · Familial · Ambitious · Confident**

| Trait | What it means in UI copy |
|-------|--------------------------|
| Honest | State what happened and what to do. No spin, no softening of errors. |
| Humble | The interface does not boast. No "world-class", no "best-in-breed". |
| Familial | Warm, second-person language. Write like a trusted colleague, not a vendor. |
| Ambitious | Frame obstacles as progress. "3 of 5 complete" beats "2 remaining". |
| Confident | Share expertise without arrogance. Don't apologise for system state. |

Positioning statements:
- Corporate: *"Thinking Beyond Limitations"*
- Employer: *"Our people write our story"*

**Writing rules:**
- British English: colour, centre, organisation, programme, practise (verb) / practice (noun).
- No exclamation marks in system messages. No "Oops!" error copy.
- State what happened and what the user can do. Never blame the user.
- Lead with the benefit. Explain the how afterwards.

---

## Design Motifs

Use only approved Kainos brand assets. No generative-AI imagery.

- **Flux** — Kainos visual mascot. Represents agile movement and energy. Use in empty states, success screens, onboarding. Use sparingly.
- **Energy Lines** — horizontal accent lines that emphasise words in section headings and convey pace. Use in hero sections and major section dividers.

Icons: approved Kainos icon library only (blue or green set, with or without background). Stroke weight 1.5px, corner radius 2px. Sizes: 16 / 24 / 32 / 48px.

---

## Quick Reference: Common Mistakes

| Mistake | Fix |
|---|---|
| Grey text on coloured background | Pick a hue-tinted lighter shade, not `gray` |
| Everything fighting for attention | De-emphasise secondary elements, don't push the primary harder |
| Arbitrary spacing values | Pick from the 8px scale |
| Labels everywhere | Let format and context carry meaning |
| Full-screen stretch for everything | Use `max-width`; give elements the space they need |
| Percentage sidebar widths | Fixed sidebar, fluid content |
| Emoji in professional UI | No |
| Multiple primary actions on one screen | There is one primary action. The rest are secondary or tertiary |
| Bold red "Delete" button everywhere | Only primary when it is the *primary action* on the screen |
| Starting with the nav shell | Start with a feature |