# Graphite + Pink Accent UI Style Guide

An ultra-calm graphite system with one simple pink accent for primary actions.

This system keeps the interface ADHD-friendly by using calm surfaces, one clear primary colour, one quieter secondary colour and restrained supporting accents.

---

## 1. Core principles

- Use neutral surfaces for most of the page.
- Reserve the primary colour for the next important action.
- Use the secondary colour for optional or supporting actions.
- Use spacing and typography before adding more colour.
- Present one main task at a time.
- Avoid animation unless it communicates useful state.
- Never use colour as the only status signal.

---

## 2. Light mode

| Token | Value | Purpose |
|---|---:|---|
| `--page` | `#F7F7F7` | Main page background |
| `--page-accent` | `#ECEEEF` | Subtle page depth |
| `--surface` | `#FFFFFF` | Cards and dialogs |
| `--surface-alt` | `#F1F2F3` | Inputs and secondary regions |
| `--surface-strong` | `#E1E4E6` | Selected and elevated elements |
| `--text` | `#292D30` | Main text |
| `--muted` | `#6C7378` | Secondary text |
| `--border` | `#D1D5D8` | Borders and dividers |
| `--primary` | `#D35F87` | Main action and brand colour |
| `--primary-hover` | `#B4476E` | Primary hover and active state |
| `--secondary` | `#E3E6E8` | Secondary action |
| `--secondary-hover` | `#D4D9DC` | Secondary hover state |

---

## 3. Dark mode

| Token | Value | Purpose |
|---|---:|---|
| `--page` | `#020303` | Main dark background |
| `--page-accent` | `#080A0B` | Background depth |
| `--surface` | `#121516` | Cards and dialogs |
| `--surface-alt` | `#1B2022` | Inputs and secondary regions |
| `--surface-strong` | `#2B3235` | Selected and elevated elements |
| `--text` | `#F3F5F5` | Main text |
| `--muted` | `#BAC0C2` | Secondary text |
| `--border` | `#424B4F` | Borders and dividers |
| `--primary` | `#EE7DA4` | Main action and brand colour |
| `--primary-hover` | `#D45F8B` | Primary hover and active state |
| `--secondary` | `#3A4347` | Secondary action |
| `--secondary-hover` | `#4C575C` | Secondary hover state |

---

## 4. Colour roles

### Primary

Use the primary colour for the single strong accent for main actions and active states.

Good uses:

- main button
- active navigation
- selected controls
- important links
- compact brand details

Do not use it on every surface. The primary colour should answer:

> What should I do next?

### Secondary

Use the secondary colour for neutral graphite structure and optional actions.

Good uses:

- secondary buttons
- optional actions
- toolbars
- supporting cards
- inactive navigation

The secondary colour should answer:

> What else can I do?

### Supporting accents

| Role | Light | Dark |
|---|---:|---:|
| Accent 1 | `#7D858A` | `#929A9E` |
| Accent 2 | `#8A9499` | `#7F979C` |
| Accent 3 | `#B79A70` | `#C8AA78` |
| Success | `#6B8872` | `#91AF98` |
| Danger | `#A75C68` | `#DD97A1` |

Use only one supporting accent inside a component unless there is a strong reason to use more.

A useful page-level balance is:

- **70%** neutral backgrounds and surfaces
- **20%** primary and secondary structure
- **10%** supporting accents and status colours

---

## 5. Typography

```css
--font-body:
  "Atkinson Hyperlegible",
  "Segoe UI",
  Arial,
  sans-serif;

--font-ui:
  "Lexend",
  "Segoe UI",
  Arial,
  sans-serif;
```

Use **Atkinson Hyperlegible** for paragraphs, instructions, tables and form help.

Use **Lexend** for headings, buttons, navigation and labels.

Recommended sizes:

| Element | Size |
|---|---:|
| Body text | `18px` |
| Small text | `14–15px` |
| Form labels | `16–17px` |
| Buttons | `16–18px` |
| H1 | `42–64px` |
| H2 | `28–38px` |
| H3 | `21–26px` |

Reading rules:

- body line-height around `1.6`
- paragraphs below roughly `70ch`
- left-aligned body text
- no long all-caps passages
- bold used selectively
- short, concrete headings

---

## 6. Layout and spacing

Use an 8-pixel rhythm.

```text
4px   tiny adjustment
8px   closely related elements
16px  normal component spacing
24px  groups inside a section
32px  separation between sections
48px+ major page regions
```

Recommended widths:

- forms: `400–480px`
- reading content: `680–760px`
- application layouts: `1040–1200px`

Keep one clear purpose per card. Avoid deeply nested cards and heavy borders.

---

## 7. Components

### Primary button

```css
background: var(--primary);
color: var(--on-primary);
```

Use one obvious primary action per task area.

### Secondary button

```css
background: var(--secondary);
color: var(--on-secondary);
```

Use for optional or reversible actions.

### Inputs

```css
background: var(--surface-alt);
border: 1px solid var(--border);
color: var(--text);
```

On focus:

```css
border-color: var(--primary);
outline: 3px solid var(--focus);
```

### Validation

- Put errors beside the affected field.
- Explain how to fix the problem.
- Preserve entered information.
- Use text or icons as well as colour.
- Reserve the danger colour for genuine errors or destructive actions.

---

## 8. ADHD-friendly interaction rules

- Present one main task at a time.
- Reduce optional decisions near the primary button.
- Keep related controls physically close.
- Use consistent action placement.
- Preserve entered data after errors.
- Avoid unexpected layout movement.
- Respect `prefers-reduced-motion`.
- Keep notifications short and actionable.
- Use progressive disclosure for advanced options.
- Do not hide critical actions behind unlabeled icons.

---

## 9. Accessibility checks

Before release:

- Test keyboard navigation.
- Verify visible focus states.
- Check text and button contrast.
- Test at 200% zoom.
- Connect labels to form controls.
- Use semantic HTML before ARIA.
- Test light and dark modes separately.
- Check error messages with assistive technology when possible.

---

## 10. Quick tokens

```css
:root {
  --page: #F7F7F7;
  --surface: #FFFFFF;
  --surface-alt: #F1F2F3;
  --text: #292D30;
  --muted: #6C7378;
  --border: #D1D5D8;
  --primary: #D35F87;
  --secondary: #E3E6E8;
}

html[data-theme="dark"] {
  --page: #020303;
  --surface: #121516;
  --surface-alt: #1B2022;
  --text: #F3F5F5;
  --muted: #BAC0C2;
  --border: #424B4F;
  --primary: #EE7DA4;
  --secondary: #3A4347;
}
```

---

## 11. Final rule

When the design starts to feel busy, remove emphasis before adding another colour.

The primary colour should identify the next action. The secondary should support it. Neutral surfaces should make the interface feel calm, stable and readable.
