Design System Governance

1. Executive Summary

The Samtrygg design system has a strong foundation: a coherent brand palette built around #FF6D59, a distinctive proprietary typeface (Nuckle), a well-structured 8px spacing scale, and a component language that is largely consistent in intent if not in implementation. The Design System document is intended to be the single source of truth and is mostly correct, but the current page implementations do not yet reflect it consistently.

However, an audit of 38 pages reveals three structural problems that will compound as the product grows:

These are fixable without a rebuild. The system is not broken — it is incomplete. The recommendations in this document are conservative, prioritised, and practical.

2. Design Principles

These six principles should guide every future design system decision. They are not aesthetic preferences — they are decision filters. When a proposed change conflicts with one of these principles, the principle wins unless there is a strong, documented reason to override it.

3. What to Keep

4. What to Change

4a. Add a semantic colour layer

The current system is primitive only. Every colour decision requires knowing the brand palette by heart. A thin semantic layer adds intent without changing any visual output:

/* Interactive */
--color-action:       var(--sam-red);
--color-action-hover: color-mix(in oklab, var(--sam-red) 88%, black);
--color-action-fg:    var(--sam-white);

/* Feedback */
--color-success:      #1a7a3c;    /* currently raw hex on 30+ pages */
--color-success-bg:   #e7f5ed;
--color-warning:      #8b5a00;
--color-warning-bg:   #fff4e0;
--color-danger:       var(--sam-error);
--color-danger-bg:    #fdecea;
--color-info:         #1a4a8a;
--color-info-bg:      #e8f0fe;

/* Surface */
--surface-base:       var(--sam-brown-light);   /* page background */
--surface-raised:     var(--sam-white);         /* cards */
--surface-sunken:     #f7f8fc;                 /* inputs, OTP, code blocks */
--surface-overlay:    rgba(49,49,49,.50);       /* modal backdrops */
--surface-inverse:    var(--sam-dark);          /* dark sections, topband, footer */

/* Text */
--text-primary:       var(--sam-dark);
--text-secondary:     var(--sam-medium);
--text-disabled:      var(--sam-light);
--text-inverse:       var(--sam-white);
--text-link:          var(--sam-red);

/* Border */
--border-default:     var(--sam-light);
--border-strong:      var(--sam-dark);
--border-focus:       var(--sam-dark);
--border-error:       var(--sam-error);

4b. Unify the button class system

Two incompatible button systems currently co-exist:

4c. Define a type scale

Pages use 15+ arbitrary font sizes (including half-steps like 11.5px, 13.5px, 14.5px) because the system defines font families but not a scale. Add:

--text-xs:   11px;   /* legal, captions, metadata */
--text-sm:   13px;   /* labels, helper text, badges */
--text-base: 15px;   /* body default */
--text-md:   17px;   /* body large, lead text */
--text-lg:   20px;   /* card titles, section subheads */
--text-xl:   26px;   /* page headings (product surfaces) */
--text-2xl:  34px;   /* section headings, hero sub */
--text-3xl:  48px;   /* display (brand surfaces only) */

4d. Tokenise placeholder image gradients

Five gradient pairs are used as listing card placeholders across 15+ pages as raw hex. Tokenise them:

--ph-warm-start:   #e8d5c4; --ph-warm-end:   #c9a382;
--ph-green-start:  #c5d9c2; --ph-green-end:  #8aaa85;
--ph-blue-start:   #c5d2e0; --ph-blue-end:   #8aa2bc;
--ph-rose-start:   #f4d3d7; --ph-rose-end:   #e9aab0;
--ph-purple-start: #d4c5e2; --ph-purple-end: #a89fc0;

5. What to Remove

6. What to Standardise First

In strict priority order — not time-boxed, because estimates at this stage would be false precision:

1. Semantic colour tokens — add to :root in the Design System. Zero visual change. Highest leverage because every future page inherits the benefit immediately.
2. Button class unification — find-replace across 38 files. Mechanical work, no design judgment required. Eliminates the largest single source of implementation confusion.
3. Type scale tokens — add 8 variables to :root, then make a pass replacing arbitrary sizes across pages.
4. Placeholder gradient tokens — add 10 variables, update page CSS. Straightforward.
5. Brand vs product surface rules — document and enforce two clear layout templates (see Section 7). This is the highest-judgment item and should be done after the mechanical fixes above.
6. Focus states — add --border-focus token and apply consistently to all :focus-visible selectors on form elements. Accessibility baseline.

7. Brand vs Product Surface Rules

Samtrygg operates across two distinct surface contexts. They share the same brand DNA — same typeface, same palette, same component shapes — but they differ fundamentally in intent, density, and visual emphasis. Treating them identically produces pages that are simultaneously over-designed for task completion and under-expressive for brand communication.

CTA hierarchy across surfaces

The current system allows multiple primary buttons per view, which dilutes the signal. The rule should be:

8. Component Intent

For each core component: what it is for, and what it is not for. These definitions should govern every future usage decision.

9. Visual Hierarchy, CTA Hierarchy, and Form Communication

Visual hierarchy

The current pages have consistent component styling but inconsistent visual hierarchy within pages. The heading scale is applied locally rather than systematically, which means a --text-xl heading on one page competes with a --text-2xl heading on an adjacent page at the same level of the information architecture.

• Page title → always --text-xl (26px) on product surfaces
• Section heading within a page → always --text-lg (20px)
• Card title → always --text-base or --text-md (15–17px) with font-weight 700
• Label / eyebrow → always --text-xs (11px), uppercase, letter-spacing, --text-secondary
• Never use more than three heading levels per page view. If you need four, the information architecture needs restructuring.

Status and form communication

The current system communicates form state primarily through border colour. This is insufficient. Validation, loading, and success states need a fuller communication pattern:

10. Priority Fixes

10a. Change Control

This document is titled a governance document. It requires a lightweight rule set for how the system itself evolves — not just what it currently contains.

All future design system changes should follow these rules:

• No new raw hex values without a token proposal. The token must be named, documented, and added to the Design System before it appears in any page.
• No new component variant without a name, a usage rule, and an implementation pattern. A visual change without these three things is not a variant — it is a local exception.
• No inline colour styles unless explicitly documented as a temporary exception with a named owner and a resolution date.
• Any exception to the system must be documented with the reason and the person responsible. Undocumented exceptions accumulate silently and are the primary source of design drift.
• Design system changes should be reviewed jointly by design and frontend before adoption. Neither discipline owns the system alone.
• The system should be audited quarterly for drift — pages that have diverged from the documented patterns without a corresponding system update.

11. Final Recommendation

The Samtrygg design system is at a decision point. It has enough surface area to work — the brand is recognisable, the palette is distinctive, the component shapes are appropriate. But it is missing the governance layer that would make it scale reliably.

The recommended sequence is not a fixed timeline but a dependency graph. Steps 1–4 create the conditions for Step 5 to succeed consistently. Step 5 creates the conditions for new page production to scale. Do not skip ahead.

The goal of this document is not to produce a perfect design system immediately. It is to make the next decision easier than the last one — and the one after that easier still. That only happens when the system is trusted, which only happens when it is complete, consistent, and enforced.

12. v1.3 Addendum — April 22, 2026

This addendum captures decisions made during the April 22 polish rundor. None contradict the governance directives above — each extends the system.

Brand color contrast — documented WCAG AA exceptions

Lighthouse audit 2026-04-22 flagged the following contrast ratios below WCAG AA 4.5:1. After deliberation, these are accepted brand exceptions, not defects:

Brand-red exceptions apply only to decorative text and CTA button labels. Any new use of red on white/brown-light outside those contexts must pass 4.5:1 or be restyled.

Samtrygg Design System Governance v1.3 · April 2026 · Design Systems Lead · Samtrygg (Remix)