Design Book

v1.6 — Tarbert

This document defines the shared design language for GTV, the JACB Services helpdesk app, and any future projects. It follows GOV.UK Design System structure and principles, with tokens adapted to our brand and themes.

The system uses two themes — light (GTV default) and dark (helpdesk and invoice app) — driven by CSS custom properties. Use the Light / Dark buttons in the top bar to switch.

Colour

All colours are defined as CSS custom properties. The dark theme overrides the same properties — no additional class names needed on components.

Brand

brand#4b286d
brand-dark#361f50
brand-mid#7c52a5
brand-light#f3eef8

Status

success#00703c
error#d4351c
warning#f47738
info#1d70b8

Typography

IBM Plex Sans for UI text, IBM Plex Mono for code, metadata, and monospace contexts. Sizes follow a modular scale.

--text-3xl / 40px
Page heading
--text-2xl / 32px
Section heading
--text-xl / 24px
Sub-section heading
--text-lg / 20px
Component heading
--text-md / 18px
Lead paragraph or large body text
--text-base / 16px
Body text — standard size for most content
--text-sm / 14px
Secondary text, labels, captions
--text-xs / 12px
Mono — tags, metadata, code labels

Spacing

4px base unit. Use the named scale rather than arbitrary values.

--space-1 · 4px
--space-2 · 8px
--space-3 · 12px
--space-4 · 16px
--space-6 · 24px
--space-8 · 32px
--space-12 · 48px
--space-16 · 64px

Button

Buttons follow GOV.UK conventions — the primary action per page or section gets the primary button. Destructive actions use the warning variant. Ghost buttons are for low-emphasis actions inline with text.

Primary

Example
<button class="btn btn--primary">Save and continue</button>

Secondary

Example
<button class="btn btn--secondary">Cancel</button>

Warning (destructive)

Example
<button class="btn btn--warning">Delete record</button>

Ghost

Example
<button class="btn btn--ghost">View all records</button>

All variants

Example

Notification banner

Used for system feedback — confirmation, error, caution, or neutral information. Always placed at the top of the main content area, above the page heading.

Success

Example
<div class="banner banner--success" role="alert"> <div class="banner__icon">✓</div> <div> <p class="banner__title">Record saved</p> <p class="banner__body">The testimony has been updated.</p> </div> </div>

Error

Example

Warning

Example

Info

Example

Card

Cards are used for content listings — news items, testimonials, tickets, records. The branded variant with a top border is the primary pattern. Cards in a grid use card-grid.

Standard card

Example
Testimony

Ruth Adler — Glasgow, 1938

Added 14 January 2025

Ruth fled Vienna with her family after Kristallnacht. She settled in Glasgow and later became a teacher.

View testimony →
<div class="card card--branded"> <span class="card__tag">Testimony</span> <h3 class="card__title"><a href="#">Title</a></h3> <p class="card__meta">Added 14 January 2025</p> <p class="card__body">Summary text.</p> <a href="#" class="card__action">View →</a> </div>

Card grid (3-up)

Example
News

New testimonies added

12 March 2025

Three new oral histories from the Dundee collection have been digitised.

Event

Exhibition opens in Edinburgh

4 March 2025

The interactive exhibition visits the Scottish Parliament next month.

Update

Partnership with NLS confirmed

18 February 2025

The National Library of Scotland will host the archive from 2026.

Table

Use for structured data with clear column relationships. Avoid tables for layout. Numeric columns align right with mono font. Add table--striped for longer lists.

Standard table

Example
Name Status Country of origin Year arrived
Ruth Adler Published Austria 1938
Max Freedman Draft Germany 1936
Hana Kovač Published Czechoslovakia 1939

Striped variant

Example
Ticket Assigned to Priority Created
#1042JeremyHigh21 Mar
#1041UnassignedLow20 Mar
#1040JeremyMedium19 Mar
#1039UnassignedHigh19 Mar

Vertical nav

Used for in-page or section navigation — typically in a left sidebar. Groups of links are separated by small-caps headings. The active item has a solid brand-coloured left border. This is the same pattern used by this design book itself.

Standard vertical nav

Example
<nav class="vnav" aria-label="Section navigation"> <div class="vnav__section"> <p class="vnav__heading">Foundations</p> <ul class="vnav__list"> <li><a href="#colour">Colour</a></li> <li><a href="#spacing" class="active">Spacing</a></li> </ul> </div> </nav>

Notes

Set class="active" on the current page link. For JS-driven single-page use, toggle this class on scroll using an IntersectionObserver — the same approach used in this design book.

Accordion

Use to let users show and hide sections of content. Good for FAQs, supporting detail, and anything where most users won't need all the content. Do not use to hide information that most users need — keep that visible.

Standard accordion

Example

Gathering the Voices is a Scottish charity that records and preserves oral testimonies from Holocaust survivors and refugees who settled in Scotland.

All testimonies are available on the GTV website. Some include audio recordings, transcripts, and photographs contributed by families.

Yes. If you or a family member has a testimony to share, get in touch through the contact page. GTV works with families to record and preserve stories sensitively.

<div class="accordion"> <div class="accordion__item"> <button class="accordion__button" aria-expanded="false"> Section title <span class="accordion__icon" aria-hidden="true"></span> </button> <div class="accordion__body"> <div class="accordion__content"> <p>Content goes here.</p> </div> </div> </div> </div>

Notes

Toggle is handled with a small JS snippet — clicking the button toggles accordion__item--open on the parent item and updates aria-expanded. Multiple items can be open at once. To restrict to one open at a time, close siblings on open.

Open source

This design system is free to use, adapt, and build on.

Our position

We built this design system for our own projects — GTV and the JACB Services helpdesk app — but we're happy for anyone to use it. If it saves you time, that's a good thing. Take what's useful, leave what isn't, and adapt it freely to your own context.

We don't require attribution, though it's always appreciated. We don't place any restrictions on commercial use. If you improve something or spot a mistake, feel free to share it back — but there's no obligation.

What you're free to do

  • Use the HTML, CSS, and JS in your own projects
  • Adapt the tokens and components to your own brand
  • Use it commercially
  • Build on top of it without crediting us
  • Redistribute it as part of your own work

Built on the shoulders of others

This system is built on the principles and patterns of the GOV.UK Design System, which is itself open source and maintained by the Government Digital Service. We've adapted their approach, not copied their code. IBM Plex Sans and IBM Plex Mono are released under the SIL Open Font Licence.

FAQ

Common questions about using the design system.

How do I switch between light and dark theme?

Add data-theme="dark" to the <html> element for the dark theme. Remove it (or set it to "light") for the GTV light theme. All component styles respond automatically — no extra classes needed on individual elements.

Do I need to include all the CSS?

For now, yes — copy the full :root token block and the component styles you need. Once the system matures we'll split this into a base stylesheet plus per-project overrides.

Why no border-radius?

GOV.UK uses sharp corners throughout — it reads as clear and utilitarian rather than decorative. This is a deliberate choice and should be kept consistent across all projects.

What fonts are required?

IBM Plex Sans (weights 400, 500, 700) and IBM Plex Mono (weights 400, 500). Load from Google Fonts:

<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:ital,wght@0,400;0,500;0,700;1,400&display=swap" rel="stylesheet">

Can I add new components?

Yes — add them to this file with the same structure: a db-subsection block with a rendered example and the code snippet below it. Add an entry to the sidebar nav and a db-nav-group if it's a new category. Update the changelog with the version and date.

What's the GTV brand colour?

Primary brand purple is #4b286d. Use --color-brand rather than hardcoding the hex, so theme overrides work correctly.

Changelog

A record of changes to the design system.

v1.6 — Tarbert · 21 March 2026

  • Search icon and input now equal height (32px in header, 44px in component)
  • Working in-page search — scans section titles, descriptions, and subheadings; results overlay with keyword highlighting; closes on Escape or outside click
  • Added Search as a component with standard variant, code example, and usage notes
  • Search added to sidebar navigation

v1.5 — Tarbert · 21 March 2026

  • Header nav hover colour corrected — stronger white underline with subtle background tint on hover
  • Header logo mark changed from GTV to JACB on both pages
  • Footer updated to JACB Services branding on both pages
  • Added Open source section — position statement, permissions, and attribution notes
  • Open source acknowledgement added to footers of index.html and design-book.html
  • Open source added to sidebar navigation

v1.4 — Tarbert · 21 March 2026

  • Added index.html homepage in GOV.UK Design System style
  • Design book chrome updated to full-width header bar + vertical nav panel layout
  • Theme toggle moved to header bar (Light / Dark buttons)
  • Navigation / header component example colours corrected — inline styles replace component class to avoid theme interference
  • Added Vertical nav component with grouped sections, active state, and hover treatment
  • Vertical nav added to sidebar navigation

v1.3 — Tarbert · 21 March 2026

  • Added Accordion component with CSS-only open/close animation and ARIA support
  • Introduced named version scheme — towns and villages on the west coast of Scotland, changing weekly
  • Retconned v0.1 and v0.2 into v1.1 and v1.2 under the Tarbert release

v1.2 — Tarbert · 21 March 2026

  • Navigation header height increased to 72px
  • Fixed nav link hover jitter caused by border-bottom layout shift
  • Added FAQ section
  • Added Changelog section
  • Added FAQ and Changelog entries to sidebar navigation

v1.1 — Tarbert · 21 March 2026

  • Initial release
  • Foundations: colour tokens, typography scale, spacing scale
  • Two themes: light (GTV) and dark (Helpdesk/Invoice), driven by CSS custom properties
  • Components: Button (primary, secondary, warning, ghost), Notification banner (4 variants), Card + card grid, Table (standard + striped), Navigation/header, Breadcrumb

Design Book v1.6 Tarbert — JACB Services. Built on GOV.UK Design System principles.

This design system is open source. We're happy for anyone to use, adapt, or build on it — no strings attached. If it's useful to you, use it. Read our open source note →