Hyphens as segment boundaries

Decision: Hyphens denote segment boundaries within the token architecture. Multi-word descriptors within a segment use camelCase.

button-primary-color-background-onLight-default

Rationale: A hyphen between every word (pure kebab-case) makes long token names difficult to parse — the eye cannot distinguish structural boundaries from word joins. CamelCase within segments preserves readability at the segment level while keeping hyphens meaningful as structural dividers.

American English for tokens, British English for documentation

Decision: Token names use American English spelling throughout (‘color’). All documentation and guidelines use British English spelling (‘colour’).

Rationale: CSS custom properties follow American English conventions universally — ‘color’, not ‘colour’. Using British English in token names would create inconsistency with every CSS reference and tool. Documentation uses British English to maintain Skipton’s brand voice in written materials.

Strong and subtle refer to colour darkness

Decision: Strong and subtle describe colour darkness, not contrast level. Darker colours are strong, lighter colours are subtle — consistently across both light and dark modes.

Rationale: Using strong/subtle as a contrast descriptor would create confusion in dark mode where the relationship between darkness and contrast inverts. Anchoring the terms to absolute colour darkness means the rule is always the same regardless of mode — darker = strong, lighter = subtle. This reduces cognitive load for anyone applying the system.

OnLight/OnDark pattern

Decision: Every token that responds to surface context uses the onLight/onDark pattern. Identify the surface — apply the corresponding tokens.

Rationale: A single rule that governs the entire system. Light surfaces use onLight tokens. Dark and brand surfaces use onDark tokens. This applies to text, headlines, buttons and hyperlinks without exception. Learning one rule unlocks the entire system rather than requiring per-component memorisation.

Default/Alt split is a light mode concern only

Decision: In dark mode, the distinction between default and alt button and hyperlink treatments is intentionally removed. The default/alt split is a light mode concern only.

Rationale: Dark mode surfaces reduce the need for prominence differentiation. The fjord scale provides a unified dark palette where the visual distinction between default and alt treatments would be minimal and potentially confusing. A unified treatment maintains visual consistency across the reduced colour palette without requiring additional dark mode variants.

Fjord family — dark mode backbone

Decision: Fjord is a seven-stop dark teal-blue scale. Each stop maps to a corresponding light mode surface.

Rationale: The dark mode colour swaps in this system are not simply darkened versions of the light mode colours — they are a distinct palette chosen for accessible contrast on dark backgrounds. The fjord family provides a stepped scale where each stop has been validated against its corresponding light mode surface text and headline options. The teal-blue undertone maintains visual warmth in dark mode rather than rendering as flat grey.

Meridian onDark shares value with midnight onDark

Decision: color-surface-meridian-onDark intentionally shares the same value as color-surface-midnight-onDark (color-fjord-700).

Rationale: Meridian was added to the design system later as a bolt-on. Due to their tonal similarity, Meridian and Midnight produce visually indistinct results in dark mode. Rather than introduce a separate fjord stop for Meridian’s dark mode, the shared value maintains visual consistency. Meridian and Midnight should never be used as adjacent surface colours within the same layout — their similarity in dark mode is a known constraint, not an oversight.

color-text-onDark-strong is a dark value

Decision: color-text-onDark-strong resolves to color-fjord-100 (#001D2E) — a very dark value. Its use is limited to the primary button fill in dark mode where the arctic background provides sufficient colour contrast.

Rationale: Strong and subtle are anchored to colour darkness throughout the system. In dark mode, strong = darker, subtle = lighter. color-text-onDark-strong is therefore the darkest text value. This creates a specific use case: dark text on the arctic-400 button background in dark mode. It will fail contrast on most dark surfaces and should not be used outside this context. The constraint is documented rather than removed because the naming convention consistency is more valuable than the edge case confusion.

color-text-onLight-subtle and color-headline-onLight-6 are white

Decision: Both tokens resolve to color-white-100. They are intended for use on dark or brand surfaces only.

Rationale: White text on a light surface fails WCAG AA contrast on almost every light background in the system. These tokens exist specifically for situations where white copy or headlines are placed on marine, midnight, meridian or other dark surfaces within a light mode email. Cross-referencing the contrast grid before use is mandatory — the token name alone does not prevent misuse.

Accent is context-independent

Decision: color-yellow-500 (#ffed00) has no onLight/onDark variant. It is used identically in both modes.

Rationale: #ffed00 maintains sufficient contrast and visual presence on both white (#ffffff) and black (#1d1d1b) backgrounds. Introducing an onLight/onDark split would add complexity without functional benefit. The accent is the single brand colour that works universally — keeping it context-independent is an intentional simplification that reinforces the single-colour brand identity.

Headline colour is a constrained design decision

Decision: Six headline colour options are available on light surfaces. color-headline-onLight-5 (midnight-500) is the default for H2–H5. Alternatives are available for intentional creative emphasis only.

Rationale: Prescribing a single headline colour for all situations would limit the expressive range of the system. However, completely free colour choice would undermine consistency and accessibility. A constrained palette of validated options — each checked against the contrast grid — gives designers creative flexibility within a safe range. The default exists to ensure consistency when no creative emphasis is needed.

Surface usage guidance — avoid bright pullout panels

Decision: Marine is the default surface for panels containing a primary contact CTA. Saturated surfaces should be used sparingly. When multiple panels appear in the same email, lighter surfaces should be used to create a subtle, layered layout.

Rationale: Multiple saturated panels in sequence compete with each other, dilute the impact of the primary CTA, and create visual noise that works against the reader’s journey. Surface colour should function like typographic scale — used sparingly, with intention, to guide attention rather than demand it. Marine carries brand authority and is the appropriate container for the most important action in the email.

Gradient stops validated for contrast

Decision: Every gradient stop has been deliberately chosen to maintain the same accessible text and headline colour options as the fallback colour. Colour contrast has been validated at every stop.

Rationale: A gradient background changes the effective contrast ratio across its range. If contrast is only validated at the start and end points, text placed over the middle of the gradient may fail WCAG AA. By validating every stop against the same text options as the fallback solid colour, the system ensures that any text placement across the gradient maintains accessibility compliance.

typography-weight-black = bold

Decision: All headline weights are defined as bold in CSS despite being visually black weight.

Rationale: Some email clients — particularly older versions of Outlook — fail to render font weights above bold (700) correctly. Setting weight to bold rather than 900 or ‘black’ ensures the headline renders as intended across the broadest range of clients. The visual intention is black weight; the CSS implementation uses bold as the most reliable cross-client equivalent.

typography-h2-size-large omitted

Decision: H2 large scale is intentionally omitted from the type scale.

Rationale: H2 at large scale (28px+) creates visual conflict with H1, which owns the large display size within the type hierarchy. Including a large H2 would undermine the clarity of the heading hierarchy and invite misuse — designers reaching for large H2 when a smaller H1 would be more appropriate.

typography-h5-size-medium omitted

Decision: H5 medium scale is intentionally omitted from the type scale.

Rationale: H5 at medium scale has no defined use case within the current email design system and has not been implemented. Adding a token that has never been used and has no use case is noise rather than completeness. If a use case emerges, the token can be added at that point with proper documentation.

H1 responsive override only

Decision: H1 is the only heading level with a defined responsive breakpoint. It scales to 33px on mobile unless overridden.

Rationale: Additional responsive breakpoints create risk when email clients strip media queries — the layout may break entirely if it relies on responsive type scaling. The system is designed to be robust without media queries. H1 is the only exception because the display typeface at large sizes (40px+) can create layout issues on narrow mobile viewports. All other heading levels are sized to work across desktop and mobile without a breakpoint.

Minimum body copy size 16px

Decision: Body copy must never go below 16px. This is an accessibility requirement, not a stylistic preference.

Rationale: Skipton’s member base skews older. Smaller text sizes create legibility barriers for readers with visual impairments or age-related vision changes. 16px is the established accessibility baseline for body copy and is non-negotiable regardless of layout constraints. If a design requires smaller text to fit, the layout should be reconsidered rather than the text size reduced.

Button padding outside the spacing scale

Decision: Button padding values are intentionally outside the spacing scale: standard 0.3em 1.2em, large 0.4em 0.9em.

Rationale: Button padding requires optical balancing that does not align cleanly with a 4px grid. The vertical and horizontal padding relationship needs to create a visually balanced pill shape — this requires fine-tuning that grid-aligned values do not provide. These values have been tested across email clients and should not be adjusted to align with the scale without visual regression testing.

Rolling Hill radius is a brand requirement

Decision: The exaggerated bottom-right curve on the hero wrapper (radius-hero: 4em) is a direct expression of the Skipton Rolling Hill brand code.

Rationale: The Rolling Hill motif appears consistently across Skipton’s visual identity. In email, the hero section is the primary expression of this brand code. The asymmetric radius — large curve bottom-right, subtle curve bottom-left — is not a decorative choice. It is a brand requirement. Reducing or removing it breaks brand consistency. The radius is applied to both the wrapper and the hero image to ensure consistent rendering across email clients that handle overflow differently.

Left corner omitted on panel-topleft images

Decision: radius-image-panel-topleft uses radius-050 0 0 0 — the left corners are intentionally not rounded.

Rationale: When an image sits in the top-left corner of a panel, applying a radius to the left corners creates a visual gap between the image edge and the panel boundary. Removing the left corner radius creates a harder visual divide between the image and the container, reinforcing the structural boundary. This is a deliberate decision to reduce the density of rounded corners in the layout.

Grid built on multiples of 4

Decision: Every spacing value in the system is a multiple of 4px.

Rationale: A 4px base grid creates visual harmony across all spacing decisions. When spacing values are multiples of a common unit, layouts feel balanced and intentional rather than arbitrary. The em-based scale ensures spacing scales proportionally with the base font size, maintaining the relationship between text and space across different contexts.

Button icons required

Decision: Every button must include an icon. This is a requirement, not an option.

Rationale: Some email clients do not render border-radius on buttons, making it difficult for readers to distinguish a CTA from plain text. Icons provide a second signifier of interactivity that works regardless of border-radius rendering. Four icon types are defined — Link, Download, Call/Callback, Document — each communicating the nature of the action as well as the fact that it is interactive.

Secondary button hover — border only

Decision: Secondary button hover state is communicated through border colour change only. Text colour remains consistent across default and hover states by design.

Rationale: Secondary buttons use a transparent background. Changing the text colour on hover in addition to the border colour would create a more disruptive visual state change that draws attention away from the primary CTA. The border change alone is sufficient to communicate interactivity on supported clients while keeping the visual weight of the secondary action appropriately subordinate.

Disabled states omitted

Decision: Disabled button states are intentionally omitted from this design system.

Rationale: Email serves an engagement function. Every CTA in an email should be actionable — if an action requires a prerequisite, the email should not be sent until that prerequisite is met, or the CTA should direct the reader to a web journey where the prerequisite can be completed. A disabled button in email communicates a dead end with no path forward. There is no valid use case for a disabled state in this context.

Focus state on backlog

Decision: A unified focus state is defined but not yet implemented.

Rationale: Focus state is a WCAG 2.1 requirement. The absence of a visible focus indicator is an accessibility failure. The focus state has not been implemented in the current version due to technical complexity around cross-client rendering. It is on the backlog and will be added in a future iteration. This is a known gap, not a deliberate omission.

Hyperlink hover states omitted

Decision: Hyperlink hover states are intentionally omitted from this design system.

Rationale: Email client support for CSS hover states is inconsistent. Outlook desktop — which represents a significant portion of the Skipton member audience given the financial services context — ignores hover states entirely. Designing a hover state that a significant portion of the audience never sees creates an inconsistency between the intended and actual experience. The underline provides the primary affordance signifier. This decision may be revisited in a future iteration as client support improves.

Primary button background onDark hover unchanged

Decision: Primary button background does not change on hover in dark mode.

Rationale: In dark mode the primary button uses arctic-400 as its background. The hover state behaviour of deepening the background colour — which works in light mode by shifting from marine-500 to marine-700 — does not have a clear equivalent in the arctic scale at the current time. Rather than introduce an untested hover value, the background remains unchanged in dark mode. This is a known limitation to be revisited in a future iteration.

Three-wrapper architecture

Decision: Every email uses three full-width wrappers: hero wrapper, content wrapper, footer wrapper. Each contains an inner container constrained to 36em (576px).

Rationale: Full-width wrappers create the edge-to-edge colour bands that give the email its visual structure. Without them, background colours would be constrained to the content width and the layout would feel narrow and box-like. The inner container ensures content remains readable at the correct width while the wrapper creates the visual environment.

Unsubscribe link required in marketing emails only

Decision: The unsubscribe link is required in all marketing emails. It is not required for service or transactional communications.

Rationale: Under PECR and GDPR, marketing emails must provide a clear and easy mechanism to opt out of future communications. Service and transactional emails — account notifications, payment confirmations, security alerts — are exempt from this requirement as they are not marketing communications. Applying the unsubscribe requirement universally would be incorrect and potentially confusing for recipients of service communications.

Dark mode implemented via three CSS mechanisms

Decision: Dark mode uses prefers-color-scheme media query, [data-ogsb] attribute selector for Outlook mobile, and a separate Yahoo Mail selector.

Rationale: No single CSS mechanism covers all email clients that support dark mode. prefers-color-scheme is the web standard but Outlook on iOS and Android uses a data attribute approach. Yahoo Mail has its own non-standard implementation. All three mechanisms reference the same semantic token values, ensuring a consistent experience regardless of which client triggers the switch.

Footer navigation always present

Decision: Footer navigation is always present regardless of email objective, unlike header navigation which requires deliberate consideration.

Rationale: By the time a reader reaches the footer, they have consumed the email’s content. The primary CTA opportunity has passed. Providing navigation links in the footer gives engaged readers a path to explore further without creating the premature journey abandonment risk that header navigation introduces. The footer is a natural place for wayfinding — the header is not.

Header navigation requires deliberate consideration

Decision: The navigation bar in the header should be a considered inclusion, not a default. Suppress it when the email has a single-minded CTA.

Rationale: The navigation bar gives the reader an immediate exit route from the email journey. For emails designed to drive one specific action — a product application, a rate change response — every navigation link is a competing destination that risks the reader abandoning the intended journey before completing it. The default should be to omit the navigation for CTA-focused emails and include it only when the email benefits from giving the reader broader website access.

Responsive behaviour minimal by design

Decision: Only H1 typography and image border radius have defined responsive overrides. All other elements are designed to work across desktop and mobile without media queries.

Rationale: Some email clients strip media queries entirely, which can cause layouts that rely on responsive behaviour to break in unexpected ways. The system is designed to be robust without media queries — spacing, type scale and layout all work at both desktop and mobile widths without intervention. Responsive overrides are limited to cases where the visual difference between desktop and mobile genuinely requires adjustment: H1 display size and image border radius curves.

Single template serving two brands via Liquid

Decision: The system serves SBS and Intermediaries from a single HTML template, with brand assets, colours and typography controlled dynamically through Liquid conditionals in Taxi for Email.

Rationale: Maintaining separate templates for each brand multiplies the maintenance overhead — every system update requires changes in multiple places, creating risk of inconsistency and error. A single template with brand logic handled at the variable level means system updates happen once and propagate to all brands automatically. The Liquid conditional approach was not available natively in Taxi at the time — it required custom implementation.

Legacy brand versions maintained in system

Decision: Two legacy brand versions (Vi24) are maintained alongside the current brand (Vi25) within the design system.

Rationale: Financial services organisations face a specific operational challenge: regulatory communications must go out quickly, but rebranded assets require review and sign-off that takes time. The design system deliberately maintained legacy brand versions to enable regulatory communications to be built and sent against an approved brand without waiting for re-approval against the new brand. This is agility within compliance constraints — not technical debt.

Accessibility solutions built from scratch

Decision: The European Accessibility Act was incoming at the time of development but tooling had not caught up. Contrast systems, semantic markup patterns and dark mode token logic were built without native platform support.

Rationale: Taxi for Email and most comparable platforms had no native accessibility framework at the time of development. Rather than wait for tooling to catch up or accept an inaccessible system, solutions were built from first principles — a full contrast matrix validating every surface/text combination, semantic markup patterns that work within the table-based email layout model, and a three-mechanism dark mode implementation covering the major clients. These solutions predate what is now becoming industry standard practice.

Three-tier architecture

Decision: The token system uses three tiers: Primitive (raw values), Semantic (intent), Component (specific usage). Component tokens reference semantic tokens. Semantic tokens reference primitives. Raw values are never used directly in component tokens.

Rationale: A flat token system — where component tokens reference hex values directly — breaks when the system evolves. Changing a brand colour requires finding and updating every component that uses it. A three-tier architecture means changing a primitive propagates through every semantic and component token that references it automatically. The semantic layer also means the intent of a colour is documented in its name, not just its value.

Surface tokens as the root design decision

Decision: Surface tokens govern how every component responds to its background context. The surface choice is the root design decision in every content block.

Rationale: Every other colour decision in a content block — text, headlines, buttons, hyperlinks — follows from the surface choice. By making the surface the root token and deriving everything else from it via the onLight/onDark pattern, the system encodes the design rules into the architecture. A developer applying the correct surface token automatically gets the correct text, headline and button tokens without needing to consult documentation for every combination.

Gradient stops as tokens

Decision: Hero gradient stops are tokenised individually (start, mid, end, fallback, angle) rather than as a single composite value.

Rationale: A single gradient token would be opaque — it would not communicate the colour values involved or allow individual stops to be updated independently. Tokenising each stop makes the gradient construction transparent, allows individual colours to be traced back to their primitives, and makes the relationship between the gradient and its fallback explicit. The fallback token pointing to the same mid-point primitive as the main gradient ensures visual consistency when gradients are not supported.