sheq-analysis-tool/DESIGN.md

# DESIGN.md — Ventia Brand Guidelines for SHEQ Tool

## Typography

**Primary font family:** Source Sans Pro

Source Sans Pro is our primary design font family used across all brand applications and designed collateral. It offers a wide range of weights in both roman and italic.

| Weight        | Use Case                              |
|---------------|---------------------------------------|
| Bold (700)    | Headings, stat callouts, table headers |
| SemiBold (600)| Sub-headings, emphasis labels          |
| Regular (400) | Body text, table data, bullet points   |
| Light (300)   | Captions, footnotes, muted annotations |

**Fallback stack:** `"Source Sans Pro", "Source Sans 3", -apple-system, "Segoe UI", sans-serif`

### Sizing

| Element            | DOCX (pt) | Web (rem) |
|--------------------|-----------|-----------|
| Report title       | 28        | 2.0       |
| Section heading    | 16        | 1.5       |
| Sub-heading        | 13        | 1.15      |
| Body text          | 11        | 1.0       |
| Table cell         | 9–10      | 0.85      |
| Caption / footnote | 8         | 0.75      |

---

## Colour Palette

### Primary Colours

The signature colours are **Deep Blue** and **Sky Blue**. These should be the lead colours in most instances.

| Name      | HEX       | RGB             | CMYK              | PMS      | Usage                                      |
|-----------|-----------|-----------------|--------------------|----------|---------------------------------------------|
| Deep Blue | `#0b3254` | 11, 50, 84      | 100, 80, 39, 37   | PMS 540C | Headings, header bars, table headers, nav   |
| Sky Blue  | `#13b5ea` | 19, 181, 234    | 69, 7, 0, 0       | PMS 298C | Sub-headings, accents, links, chart highlight |

### Secondary Colours

The secondary palette allows for flexibility, versatility and personality in the brand.

| Name        | HEX       | RGB             | CMYK              | PMS       | Usage                                      |
|-------------|-----------|-----------------|--------------------|-----------|---------------------------------------------|
| Dark Green  | `#006e47` | 0, 110, 71      | 100, 30, 88, 21   | PMS 7727C | Positive indicators, body part charts        |
| Mid Green   | `#009946` | 0, 153, 70      | 96, 10, 100, 1    | PMS 347C  | Secondary positive, trend improvements       |
| Light Green | `#7bc143` | 123, 193, 67    | 57, 0, 100, 0     | PMS 368C  | Tertiary positive, low-severity shading      |
| Purple      | `#96358d` | 150, 53, 141    | 48, 94, 5, 0      | PMS 513C  | Categorical distinction, chart series accent |

### Functional Colours

These are derived from the brand palette and used for semantic meaning in data visualisation and reporting.

| Role          | Colour      | HEX       | Notes                                |
|---------------|-------------|-----------|--------------------------------------|
| Warning       | Amber       | `#d97706` | Moderate consequence, caution states |
| Critical      | Red         | `#dc2626` | Major/Substantial, LTI, alerts       |
| Muted text    | Slate grey  | `#64748b` | Captions, secondary labels           |
| Card background | Off-white | `#f0f5fa` | Alternating table rows, card bg      |
| Page background | Near-white | `#f8fafc` | Web app body background              |
| Borders       | Light grey  | `#e2e8f0` | Table borders, card edges            |

---

## Colour Application

### DOCX Reports

- **Page header:** Deep Blue `#0b3254` underline rule
- **Heading 1:** Deep Blue `#0b3254`, Source Sans Pro Bold 16pt
- **Heading 2:** Sky Blue `#13b5ea`, Source Sans Pro SemiBold 13pt
- **Table header row:** Deep Blue `#0b3254` fill, white text
- **Alternating rows:** Off-white `#f0f5fa` / white `#ffffff`
- **Footer text:** Slate grey `#64748b`

### Web App

- **Navigation / header bar:** Deep Blue `#0b3254`
- **Primary buttons:** Deep Blue `#0b3254`
- **Secondary buttons:** Sky Blue `#13b5ea`
- **Active accent / links:** Sky Blue `#13b5ea`
- **Sidebar background:** White `#ffffff` with light grey border
- **Body background:** Near-white `#f8fafc`

### Charts & Data Visualisation

Use this sequence for multi-series charts:

```
Series 1:  Deep Blue   #0b3254
Series 2:  Sky Blue    #13b5ea
Series 3:  Dark Green  #006e47
Series 4:  Mid Green   #009946
Series 5:  Light Green #7bc143
Series 6:  Purple      #96358d
Series 7:  Amber       #d97706
Series 8:  Red         #dc2626
```

For PD comparison charts:
- **PD 1 (prior):** Deep Blue `#0b3254`
- **PD 2 (current):** Sky Blue `#13b5ea`

For consequence severity:
- **Negligible:** Dark Green `#006e47`
- **Minor:** Amber `#d97706`
- **Moderate:** Red `#dc2626`
- **Major / Substantial:** Purple `#96358d`

---

## CSS Variables (Web App)

```css
:root {
    /* Primary */
    --deep-blue: #0b3254;
    --sky-blue: #13b5ea;

    /* Secondary */
    --dark-green: #006e47;
    --mid-green: #009946;
    --light-green: #7bc143;
    --purple: #96358d;

    /* Functional */
    --amber: #d97706;
    --red: #dc2626;
    --muted: #64748b;
    --card-bg: #f0f5fa;
    --page-bg: #f8fafc;
    --border: #e2e8f0;
    --text: #1e293b;
    --white: #ffffff;

    /* Typography */
    --font-primary: "Source Sans Pro", "Source Sans 3", -apple-system, "Segoe UI", sans-serif;
    --font-heading: var(--font-primary);
}
```

---

## Python Constants (analysis.py)

```python
# Brand colours
DEEP_BLUE = "#0b3254"
SKY_BLUE = "#13b5ea"
DARK_GREEN = "#006e47"
MID_GREEN = "#009946"
LIGHT_GREEN = "#7bc143"
PURPLE = "#96358d"
AMBER = "#d97706"
RED = "#dc2626"

CHART_PALETTE = [DEEP_BLUE, SKY_BLUE, DARK_GREEN, MID_GREEN, LIGHT_GREEN, PURPLE, AMBER, RED]
```

---

## Notes

- Source Sans Pro is available from [Google Fonts](https://fonts.google.com/specimen/Source+Sans+Pro) and should be installed locally for DOCX rendering. In the web app, import via Google Fonts CDN.
- When Source Sans Pro is unavailable in a DOCX context (e.g. recipient doesn't have it installed), the fallback is Calibri then Arial.
- Always maintain sufficient contrast — do not place Sky Blue text on white backgrounds at small sizes. Use Deep Blue for body text and Sky Blue for headings/accents only.