Customization

GolemUI gives you three levels of customization — pick the one that fits your needs:

CSS variable overrides — Change design tokens for quick, broad adjustments
Class-based overrides — Target specific components with standard CSS selectors
Headless mode — Drop all default styles and build your own from scratch

CSS variable overrides

The fastest way to customize GolemUI. Override any design token on :root or a scoped selector, and every component that references it updates automatically.

Global overrides

Set variables on :root to apply changes across your entire application:

:root {
  --gui-intent-primary: #8b5cf6;
  --gui-intent-primary-hover: #7c3aed;
  --gui-intent-primary-active: #6d28d9;
  --gui-radius-md: 8px;
  --gui-font-family: 'Inter', sans-serif;
}

Scoped overrides

Target a specific container to limit changes to one section of your page:

.my-sidebar-form {
  --gui-intent-primary: #10b981;
  --gui-bg-surface: #f0fdf4;
  --gui-border-default: #a7f3d0;
}

<div class="my-sidebar-form">
  <gui-form ...></gui-form>
</div>

Class-based overrides

When CSS variables alone aren’t enough, target specific BEM classes with standard CSS selectors.

Naming convention

GolemUI follows the BEM naming convention consistently:

Pattern	Example	Description
Block	`.gui-button`, `.gui-form`, `.gui-widget`	Top-level component class
Element	`.gui-repeater__card`, `.gui-repeater__add-btn`	Child element within a block
Modifier	`.gui-widget--horizontal`, `.gui-checkbox--left`	Variant of a block or element
Custom element	`gui-textinput`, `gui-select`, `gui-toggle`	The web component tag itself

Examples

Target all inputs within a form:

.gui-form .gui-widget input {
  border-radius: 8px;
  border-width: 2px;
}

Style buttons with uppercase text:

.gui-form button.gui-button {
  text-transform: uppercase;
  letter-spacing: 0.05em;
}

Customize the toggle slider shape:

.gui-form gui-toggle .gui-toggle--slider {
  border-radius: 4px;
}

Add a custom background to alert notifications:

.gui-alert-notification--success {
  background: linear-gradient(135deg, #d1fae5, #a7f3d0);
}

Headless mode

For complete control, skip the CSS import entirely. Components still render their full HTML structure with BEM class names, ARIA attributes, and all interactive behavior. You provide all the visual styling.

Here’s an example of styling a Textinput and a Password from scratch in headless mode with SCSS:

@import url('https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap');

.gui-form {
  font-family: "Roboto", sans-serif;
  font-optical-sizing: auto;
  font-weight: 400;
  font-style: normal;

  form {
    margin: 12px;
  }
}

.gui-flex__widget {
  display: flex;
  flex-direction: column;
  gap: 16px;
}

.gui-widget {
  display: flex;
  align-items: center;

  .gui-password__toggle {
    position: absolute;
    inset-inline-end: 20px;
    background: transparent;
    border: none;
    outline: none;
    cursor: pointer;
  }

  input {
    width: 100%;

    /* Base input */
    &[type='text'],
    &[type='password'] {
      font-size: 16px;
      padding: 12px 16px;
      border: 2px solid #e2e8f0;
      border-radius: 8px;
      background: white;
      color: #1e293b;
      transition: border-color 0.15s ease;

      /* Focus state */
      &:focus {
        border-color: #3b82f6;
        outline: none;
        box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.2);
      }
    }

    /* Invalid state */
    &[aria-invalid='true'] {
      border-color: #ef4444;
    }

    /* Disabled state */
    &:disabled {
      background: #f1f5f9;
      color: #94a3b8;
      cursor: not-allowed;
    }
  }
}

Components retain all their functionality — ARIA compliance, keyboard interactions, validation, and event handling. You write your own CSS from scratch, targeting the BEM class names that components render.

Component anatomy

Each component in the Components Reference includes an Anatomy section that shows the rendered HTML structure. Use these as a guide when writing class-based overrides — they show exactly which elements and class names are available to target.