Theming

Core Principles

Our theming system is built on three fundamental principles:

1. Semantic Color Tokens - Colors are defined by their purpose, not their appearance
2. Build-time vs Runtime - Understanding when design decisions are made vs. when themes are applied
3. Component Cooperation - Components must actively participate in theming, not just receive it passively

Adaptive vs. Design Choice

A critical distinction in our theming system is between adaptive sections and design choices:

Adaptive Sections naturally adjust to feel appropriate in both themes:

• Sections without explicit isDark: true configuration
• Text and background colors automatically invert with theme
• Screen overlays (light/dark) invert to maintain proper contrast

Design Choices maintain their intentional styling regardless of theme:

• Sections with isDark: true are deliberate design decisions
• These sections stay "dark" in both light and dark themes
• They don't invert because they represent the designer's intent

Section Wrapper Behavior

The section wrapper in commons.css handles adaptive theming:

/* Default behavior - light theme */
.section-wrapper {
  &.has-dark-screen {
    color: var(--contrast-text-on-dark);
    .background-image::after {
      background: var(--dark-screen);
    }
  }

  &.has-light-screen {
    color: var(--contrast-text-on-light);
    .background-image::after {
      background: var(--light-screen);
    }
  }
}

/* Dark theme: invert ONLY if not a design choice */
.dark-theme {
  .section-wrapper {
    &.has-light-screen:not(.is-dark) {
      /* Invert: light screen becomes dark */
      color: var(--contrast-text-on-dark);
      .background-image::after {
        background: var(--dark-screen);
      }
    }
    /* Sections with .is-dark stay dark (don't invert) */
  }
}

The :not(.is-dark) selector is crucial - it prevents inverting sections that are intentionally dark as a design choice.

Logo Visibility

Dark logos can disappear on dark backgrounds. Solution: subtle background in dark theme:

.logo {
  padding: var(--space-s);
  border-radius: 8px;
  transition: background-color 0.3s ease;
}

.dark-theme .logo {
  background-color: rgb(255 255 255 / 15%);
}

SVG Icons

SVG icons should use theme-aware stroke/fill colors:

svg {
  stroke: var(--color-text);
  fill: none;
}

svg * {
  stroke: var(--color-text);
  fill: none;
}

Third-Party Components

External components (like Shikwasa player) need explicit dark theme overrides:

/* Override Shikwasa when our dark theme is active */
.dark-theme .shk[data-theme='auto'] {
  --color-theme: #333;
  --color-text: #fff;
  --color-title: #fff;
}

Gradient Masks

Gradient overlays (like on the Logos List page) need to match the background color:

/* Light theme - white gradient */
.mask::before {
  background-image: linear-gradient(
    to right,
    rgb(255 255 255 / 100%) 0%,
    transparent 100%
  );
}

/* Dark theme - dark gradient */
.dark-theme .mask::before {
  background-image: linear-gradient(
    to right,
    rgb(26 26 26 / 100%) 0%,
    transparent 100%
  );
}

DO

• Use semantic CSS variables
• Distinguish between adaptive sections and design choices
• Use inherit and opacity for text hierarchy
• Test logos and icons in dark theme
• Evaluate build-time vs. runtime decisions
• Document special cases in component CSS
• Use theme-aware variables for borders, shadows, and backgrounds

DON'T

• Hardcode colors in component CSS
• Assume all sections should invert in dark theme
• Use colors directly from design mockups
• Ignore about third-party components styling
• Mix build-time configuration with runtime theme switching
• Create per-component color tokens (use global semantic tokens)
• Add dark theme overrides when semantic variables would work