Style Enhancement Guide

This guide documents the design system tokens and component classes implemented in styles/custom.css. It serves as a reference for border, surface, shadow, radius, button, gradient, transition, focus, and typography tokens used across the theme.

Status: All design tokens and component classes described below are implemented and available for use.

How to Read This Guide

Each section documents a token category:

Token definitions — CSS custom properties with light/dark mode values
Component mapping — which theme components use each token
Implementation notes — usage guidance and accessibility considerations

Token tables are split by light mode and dark mode where values differ.

1. Color System

Alpha-Transparent Borders

The theme uses alpha-transparent borders instead of solid gray colors. This allows borders to adapt naturally to any background.

/* Alpha-transparent border pattern */
border: 1px solid var(--f5-border-default);  /* neutral at 20% alpha */

Border Tokens

/* Light mode */
:root[data-theme='light'] {
  --f5-border-faint: #3434341a;    /* --f5-black-3 at 10% */
  --f5-border-default: #34343433;  /* --f5-black-3 at 20% */
  --f5-border-strong: #22222266;   /* --f5-black-4 at 40% */
}

/* Dark mode */
:root {
  --f5-border-faint: #f5f5f51a;    /* --f5-white-2 at 10% */
  --f5-border-default: #f5f5f533;  /* --f5-white-2 at 20% */
  --f5-border-strong: #cccccc66;   /* --f5-white-4 at 40% */
}

Border Use Cases

Token	Opacity	Use Case
`--f5-border-faint`	10%	Subtle separators, table rows
`--f5-border-default`	20%	Default borders, card outlines
`--f5-border-strong`	40%	Emphasized borders, active states

Status: Complete — implemented in styles/custom.css.

Interactive Surface Colors

Semantic surface tokens for hover and active states.

Light Mode Surfaces

Token	Value	Purpose
`--f5-white`	`#ffffff`	Main backgrounds
`--f5-white-1`	`#faf9f7`	Sidebar, subtle areas
`--f5-white-2`	`#f5f5f5`	Elevated surfaces
`--f5-surface-hover`	`var(--f5-white-2)`	Hover fill
`--f5-surface-active`	`var(--f5-white-3)`	Pressed/active fill

Dark Mode Surfaces

Token	Value	Purpose
`--f5-black`	`#000000`	Main backgrounds
`--f5-black-4`	`#222222`	Sidebar, subtle areas
`--f5-surface-hover`	`var(--f5-black-3)`	Hover fill
`--f5-surface-active`	`var(--f5-black-2)`	Pressed/active fill

Surface Token Definitions

:root[data-theme='light'] {
  --f5-surface-hover: var(--f5-white-2);     /* #f5f5f5 */
  --f5-surface-active: var(--f5-white-3);    /* #e6e6e6 */
}

:root {
  --f5-surface-hover: var(--f5-black-3);     /* #343434 */
  --f5-surface-active: var(--f5-black-2);    /* #666666 */
}

Status: Complete — implemented in styles/custom.css.

2. Elevation and Shadow System

Shadow Scale

The theme uses neutral-tinted alpha shadows with double-layer values for natural depth. Light mode uses --f5-black-3 (#343434) as the tint base; dark mode uses #cccccc.

Light Mode Shadows

:root[data-theme='light'] {
  --f5-shadow-inset: inset 0px 1px 2px 1px #3434341a;
  --f5-shadow-low:
    0px 1px 1px 0px #3434340d,
    0px 2px 2px 0px #3434340d;
  --f5-shadow-mid:
    0px 2px 3px 0px #3434341a,
    0px 8px 16px -10px #34343433;
  --f5-shadow-high:
    0px 2px 3px 0px #34343426,
    0px 16px 16px -10px #34343433;
  --f5-shadow-higher:
    0px 2px 3px 0px #3434341a,
    0px 12px 28px 0px #34343440;
}

Dark Mode Shadows

:root {
  --f5-shadow-inset: inset 0px 1px 2px 1px #cccccc0d;
  --f5-shadow-low:
    0px 1px 1px 0px #cccccc0a,
    0px 2px 2px 0px #cccccc0a;
  --f5-shadow-mid:
    0px 2px 3px 0px #cccccc0d,
    0px 8px 16px -10px #cccccc1a;
  --f5-shadow-high:
    0px 2px 3px 0px #cccccc1a,
    0px 16px 16px -10px #cccccc1a;
  --f5-shadow-higher:
    0px 2px 3px 0px #cccccc0d,
    0px 12px 28px 0px #cccccc26;
}

Component Shadow Mapping

Component	Shadow Level
`.swatch`, `.icon-card`	`--f5-shadow-low` (at rest)
`.starlight-aside`	`--f5-shadow-low`
`.expressive-code .frame`	`--f5-shadow-mid`
`.mermaid-container`	`--f5-shadow-mid`
Cards on hover	`--f5-shadow-mid`
Dropdowns, popovers	`--f5-shadow-high`
Modals	`--f5-shadow-higher`

Status: Complete — all shadow levels (inset, low, mid, high, higher) implemented in styles/custom.css.

3. Border Radius Scale

Radius Tokens

:root {
  --f5-radius-xs: 0.1875rem;   /* 3px — badges, tags */
  --f5-radius-sm: 0.3125rem;   /* 5px — nav items, small controls */
  --f5-radius-md: 0.375rem;    /* 6px — cards, code blocks */
  --f5-radius-lg: 0.5rem;      /* 8px — modals, large containers */
  --f5-radius-full: 999px;     /* pills, fully rounded */
}

Component Radius Mapping

Component	Radius Token
`.swatch`	`--f5-radius-md` (6px)
`.icon-card`	`--f5-radius-md` (6px)
`.starlight-aside`	`--f5-radius-md` (6px)
`.expressive-code .frame`	`--f5-radius-md` (6px)
`.mermaid-container`	`--f5-radius-lg` (8px)
`.edit-link`	`--f5-radius-full` (pill)
Sidebar nav items	`--f5-radius-sm` (5px)
Badges	`--f5-radius-xs` (3px)

Status: Complete — radius scale (xs, sm, md, lg, full) implemented in styles/custom.css.

/* Sidebar navigation items */
nav.sidebar a {
  border-radius: var(--f5-radius-sm);    /* 5px */
  padding: 0.25rem 0.5rem;               /* 4px 8px */
  min-height: 2.25rem;                    /* 36px */
  display: flex;
  align-items: center;
  transition: background-color 0.15s ease, color 0.15s ease;
}

/* Light mode hover */
:root[data-theme='light'] nav.sidebar a:hover {
  background-color: var(--f5-white-2);   /* #f5f5f5 */
}

/* Dark mode hover */
:root nav.sidebar a:hover {
  background-color: var(--f5-black-3);   /* #343434 */
}

/* Active page indicator */
nav.sidebar a[aria-current="page"] {
  background-color: var(--f5-white-3);   /* #e6e6e6 light */
  font-weight: 600;
}

:root:not([data-theme='light']) nav.sidebar a[aria-current="page"] {
  background-color: var(--f5-black-2);   /* #666666 → adjust for readability */
}

Left Accent Indicator

nav.sidebar a[aria-current="page"] {
  border-left: 3px solid var(--sl-color-accent);
  padding-left: calc(0.5rem - 3px);  /* compensate for border */
}

Status: Complete — sidebar hover, active, and accent indicator implemented in styles/custom.css.

5. Button System

Button Variants

/* Primary — using F5 Red as brand action */
.btn-primary {
  background: var(--f5-red);
  color: var(--f5-white);
  border: none;
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease, box-shadow 0.15s ease;
}
.btn-primary:hover {
  background: var(--f5-red-3);
  box-shadow: var(--f5-shadow-low);
}

/* Secondary — outline style */
.btn-secondary {
  background: transparent;
  color: var(--sl-color-gray-2);
  border: 1px solid var(--f5-border-default);
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease, border-color 0.15s ease;
}
.btn-secondary:hover {
  background: var(--f5-surface-hover);
  border-color: var(--f5-border-strong);
}

/* Tertiary — ghost/text-only */
.btn-tertiary {
  background: transparent;
  color: var(--sl-color-accent);
  border: none;
  border-radius: var(--f5-radius-sm);
  padding: 0.625rem 1rem;
  font-weight: 500;
  font-size: 0.875rem;
  transition: background-color 0.15s ease;
}
.btn-tertiary:hover {
  background: var(--f5-surface-hover);
}

Button Size Scale

Size	Padding	Font Size	Min Height
Small	`0.375rem 0.75rem`	`0.8125rem` (13px)	`32px`
Medium (default)	`0.625rem 1rem`	`0.875rem` (14px)	`40px`
Large	`0.75rem 1.5rem`	`1rem` (16px)	`48px`

Status: Complete — all button variants (primary, secondary, tertiary, critical) and size scale (sm, default, lg) implemented in styles/custom.css.

6. Hero and Header Backgrounds

Hero Gradients

Using the F5 brand palette:

/* Primary hero gradient — River blue */
.hero-gradient-primary {
  background: linear-gradient(135deg, var(--f5-river-2) 0%, var(--f5-river) 100%);
  /* #6e8dcc → #0e41aa */
}

/* Faint page wash — subtle warm tone */
:root[data-theme='light'] .hero-gradient-faint {
  background: linear-gradient(180deg, #faf9f7 0%, #f5f5f5 100%);
}
:root .hero-gradient-faint {
  background: linear-gradient(180deg, #222222 0%, #000000 100%);
}

/* Eggplant variant for feature pages */
.hero-gradient-eggplant {
  background: linear-gradient(135deg, var(--f5-eggplant-2) 0%, var(--f5-eggplant) 100%);
  /* #9c59c9 → #62228b */
}

/* Red brand variant for announcements */
.hero-gradient-red {
  background: linear-gradient(135deg, var(--f5-red-2) 0%, var(--f5-red) 100%);
  /* #f06680 → #e4002b */
}

Gradient Overlay Techniques

/* Radial vignette for depth */
.hero-vignette::after {
  content: '';
  position: absolute;
  inset: 0;
  background: radial-gradient(ellipse at center, transparent 40%, rgba(0, 0, 0, 0.15) 100%);
  pointer-events: none;
}

/* Bottom fade to page background */
.hero-fade::after {
  content: '';
  position: absolute;
  bottom: 0;
  left: 0;
  right: 0;
  height: 30%;
  background: linear-gradient(to bottom, transparent, var(--sl-color-black));
  pointer-events: none;
}

Status: Complete — hero gradients (primary, eggplant, red, faint) and overlays (hero-fade, hero-vignette) implemented in styles/custom.css.

7. Hover Effects and Transitions

Transition Tokens

:root {
  --f5-transition-fast: 0.15s ease;
  --f5-transition-base: 0.2s ease;
  --f5-transition-bounce: 0.2s cubic-bezier(0.68, -0.2, 0.265, 1.15);
  --f5-transition-decelerate: 0.6s cubic-bezier(0.5, 1, 0.89, 1);
  --f5-transition-spring: 0.2s cubic-bezier(0.54, 1.5, 0.38, 1.11);
}

Token	Duration	Easing	Use Case
`--f5-transition-fast`	`0.15s`	`ease`	Most hover states, color changes
`--f5-transition-base`	`0.2s`	`ease`	Background fills, border changes
`--f5-transition-bounce`	`0.2s`	`cubic-bezier(0.68, -0.2, 0.265, 1.15)`	Switches, toggles
`--f5-transition-decelerate`	`0.6s`	`cubic-bezier(0.5, 1, 0.89, 1)`	Tab indicators, sliding panels
`--f5-transition-spring`	`0.2s`	`cubic-bezier(0.54, 1.5, 0.38, 1.11)`	Tooltips, popover entry

What to Animate

Property	Safe to Animate	Notes
`background-color`	Yes	Standard for hover fills
`color`	Yes	Text color changes
`border-color`	Yes	Border emphasis on hover
`box-shadow`	Yes	Elevation changes (use `will-change` if jank)
`transform`	Yes	Scale, translate for feedback
`opacity`	Yes	Fade in/out
`width`, `height`	Avoid	Causes layout reflow
`padding`, `margin`	Avoid	Causes layout reflow

Component Transition Mapping

/* Sidebar nav items */
nav.sidebar a {
  transition: background-color var(--f5-transition-fast),
              color var(--f5-transition-fast);
}

/* Cards — shadow lift on hover */
.swatch, .icon-card {
  transition: box-shadow var(--f5-transition-base),
              transform var(--f5-transition-base);
}
.swatch:hover, .icon-card:hover {
  box-shadow: var(--f5-shadow-mid);
  transform: translateY(-1px);
}

/* Buttons */
.btn-primary, .btn-secondary, .btn-tertiary {
  transition: background-color var(--f5-transition-fast),
              border-color var(--f5-transition-fast),
              box-shadow var(--f5-transition-fast);
}

/* Links */
a {
  transition: color var(--f5-transition-fast);
}

Status: Complete — all five transition tokens (fast, base, bounce, decelerate, spring) and component transitions implemented in styles/custom.css.

8. Focus Ring System

Focus Ring Tokens

The theme uses a double-ring pattern with an inset inner ring and an outer glow:

/* Action focus — using F5 River blue */
:root {
  --f5-focus-action: inset 0 0 0 1px var(--f5-river), 0 0 0 3px var(--f5-river-2);
  /* inset 0 0 0 1px #0e41aa, 0 0 0 3px #6e8dcc */

  --f5-focus-critical: inset 0 0 0 1px var(--f5-red-3), 0 0 0 3px var(--f5-red-2);
  /* inset 0 0 0 1px #a70020, 0 0 0 3px #f06680 */
}

/* Apply to interactive elements */
a:focus-visible,
button:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible {
  outline: none;
  box-shadow: var(--f5-focus-action);
}

/* Critical variant for destructive buttons */
.btn-critical:focus-visible {
  box-shadow: var(--f5-focus-critical);
}

Accessibility Notes

The double-ring pattern meets WCAG 2.2 Focus Appearance requirements (minimum 2px contrasting outline)
Using box-shadow instead of outline allows border-radius to be respected
:focus-visible ensures the ring only appears for keyboard navigation, not mouse clicks

Status: Complete — double-ring focus pattern (action, critical) and :focus-visible styles implemented in styles/custom.css.

9. Typography

Font Stack

:root {
  --sl-font: "proximaNova", system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
  --sl-font-heading: "neusaNextProWide", system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
  --sl-line-height-headings: 1.1;
}

Type Scale

Scale	Size	Line Height	Usage
Display 500	`1.875rem` (30px)	1.267	`--sl-text-h1`
Display 400	`1.5rem` (24px)	1.333	`--sl-text-h2`
Display 300	`1.125rem` (18px)	1.333	`--sl-text-h3`
Display 200	`1rem` (16px)	1.5	`--sl-text-h4`
Display 100	`0.8125rem` (13px)	1.385	Overline text
Body 300	`1rem` (16px)	1.5	Primary body
Body 200	`0.875rem` (14px)	1.429	Sidebar text, captions
Body 100	`0.8125rem` (13px)	1.385	Small print

Key Characteristics

Aspect	Value	Notes
Heading line height	`1.1`	Tight headings for brand impact; consider `1.2` for readability
Body line height	`1.5` (Starlight default)	Well-suited for reading
Font family	Custom brand fonts	proximaNova (body), neusaNextProWide (headings)
Heading weights	`h1-h2: 700, h3: 500, h4-h6: 700 uppercase`	Opinionated for brand consistency

Priority: No changes needed. Current typography is well-defined and brand-appropriate. Minor adjustment to heading line height (1.1 to 1.2) is optional.

10. Implementation Changelog

All design tokens were implemented across five sprints:

Sprint	Scope	Tokens Added
1. Foundation	Shadows + border radius	`--f5-shadow-` (5 levels), `--f5-radius-` (5 levels)
2. Sidebar + Surfaces	Navigation + interactive tokens	`--f5-surface-hover`, `--f5-surface-active`, `--f5-border-*` (3 levels), `--f5-transition-fast`
3. Buttons	Component system	`.btn-primary`, `.btn-secondary`, `.btn-tertiary`, `.btn-critical`, size variants
4. Hero Gradients	Background utilities	`.hero-gradient-primary`, `-eggplant`, `-red`, `-faint`, `.hero-vignette`, `.hero-fade`
5. Focus + Transitions	Accessibility + polish	`--f5-focus-action`, `--f5-focus-critical`, `--f5-transition-*` (5 tokens), card hover effects

Quick Reference: Token Summary

All Custom Properties

:root {
  /* Border radius scale */
  --f5-radius-xs: 0.1875rem;     /* 3px */
  --f5-radius-sm: 0.3125rem;     /* 5px */
  --f5-radius-md: 0.375rem;      /* 6px */
  --f5-radius-lg: 0.5rem;        /* 8px */
  --f5-radius-full: 999px;

  /* Transition timing */
  --f5-transition-fast: 0.15s ease;
  --f5-transition-base: 0.2s ease;
  --f5-transition-bounce: 0.2s cubic-bezier(0.68, -0.2, 0.265, 1.15);
  --f5-transition-decelerate: 0.6s cubic-bezier(0.5, 1, 0.89, 1);
  --f5-transition-spring: 0.2s cubic-bezier(0.54, 1.5, 0.38, 1.11);

  /* Focus rings */
  --f5-focus-action: inset 0 0 0 1px var(--f5-river), 0 0 0 3px var(--f5-river-2);
  --f5-focus-critical: inset 0 0 0 1px var(--f5-red-3), 0 0 0 3px var(--f5-red-2);

  /* Dark mode shadows (default) */
  --f5-shadow-low: 0px 1px 1px 0px #cccccc0a, 0px 2px 2px 0px #cccccc0a;
  --f5-shadow-mid: 0px 2px 3px 0px #cccccc0d, 0px 8px 16px -10px #cccccc1a;
  --f5-shadow-high: 0px 2px 3px 0px #cccccc1a, 0px 16px 16px -10px #cccccc1a;
  --f5-shadow-higher: 0px 2px 3px 0px #cccccc0d, 0px 12px 28px 0px #cccccc26;

  /* Dark mode borders */
  --f5-border-faint: #f5f5f51a;
  --f5-border-default: #f5f5f533;
  --f5-border-strong: #cccccc66;

  /* Dark mode surfaces */
  --f5-surface-hover: var(--f5-black-3);
  --f5-surface-active: var(--f5-black-2);
}

:root[data-theme='light'] {
  /* Light mode shadows */
  --f5-shadow-low: 0px 1px 1px 0px #3434340d, 0px 2px 2px 0px #3434340d;
  --f5-shadow-mid: 0px 2px 3px 0px #3434341a, 0px 8px 16px -10px #34343433;
  --f5-shadow-high: 0px 2px 3px 0px #34343426, 0px 16px 16px -10px #34343433;
  --f5-shadow-higher: 0px 2px 3px 0px #3434341a, 0px 12px 28px 0px #34343440;

  /* Light mode borders */
  --f5-border-faint: #3434341a;
  --f5-border-default: #34343433;
  --f5-border-strong: #22222266;

  /* Light mode surfaces */
  --f5-surface-hover: var(--f5-white-2);
  --f5-surface-active: var(--f5-white-3);
}