Theming

Kirby Loop comes with built-in theming support, allowing you to customize the visual appearance to match your brand or provide different user experiences. The plugin includes a default (light) theme and a dark theme, with support for creating custom themes.

Configuration#

Setting a Theme#

Configure the theme in your site/config/config.php:

return [
    // Set theme: 'default', 'dark', or custom theme name
    'moinframe.loop.theme' => 'dark',
];

Available options:

• 'default' - Light theme (default)
• 'dark' - Dark theme
• Custom theme name

Creating Custom Themes#

Custom themes are CSS files that override the default color and styling tokens. The theming system uses CSS custom properties (variables) for easy customization.

Basic Custom Theme#

Here's a minimal custom theme example:

/* frontend/src/styles/theme-custom.css */
kirby-loop[theme="custom"] {
  /* Accent color */
  --color-accent-l: 0.6;
  --color-accent-c: 0.15;
  --color-accent-h: 280; /* Purple accent */

  /* Neutral color lightness values */
  --color-neutral-l-0: 0.98;
  --color-neutral-l-100: 0.92;
  --color-neutral-l-200: 0.86;
  --color-neutral-l-300: 0.7;
  --color-neutral-l-400: 0.6;
  --color-neutral-l-500: 0.5;
  --color-neutral-l-600: 0.4;
  --color-neutral-l-700: 0.3;
  --color-neutral-l-800: 0.15;
  --color-neutral-l-900: 0.05;
  --color-neutral-l-1000: 0;
}

Configure Your Custom Theme#

Set your custom theme in the configuration:

// site/config/config.php
return [
    'moinframe.loop.theme' => 'custom',
];

Theme Architecture#

Color System#

The theming system uses OKLCH color space for consistent, perceptually uniform colors:

/* Accent colors */
--color-accent-l: 0.7;        /* Lightness (0-1) */
--color-accent-c: 0.12;       /* Chroma/saturation (0-0.4) */
--color-accent-h: 220;        /* Hue (0-360) */

/* Neutral colors */
--color-neutral-l-0: 1;       /* Lightest */
--color-neutral-l-100: 0.95;
--color-neutral-l-200: 0.9;
/* ... */
--color-neutral-l-900: 0.05;
--color-neutral-l-1000: 0;    /* Darkest */

Advanced Customization#

You can override any design token in your custom theme:

kirby-loop[theme="custom"] {
  /* Colors */
  --color-accent-l: 0.65;
  --color-accent-c: 0.18;
  --color-accent-h: 15; /* Orange accent */

  /* Shadows with custom opacity */
  --shadow-s: 0 0.1em 0.25em oklch(var(--color-neutral-l-900) var(--color-neutral-c) var(--color-neutral-h) / 0.15);

  /* Custom border radius */
  --border-radius: 0.5rem;
  --border-radius-rounded: 1rem;

  /* Custom fonts */
  --font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
}