Styling Overview

GolemUI is a Headless CSS library with a courtesy layer. The default theme ships as plain CSS that you can use as-is, override selectively, or remove entirely. No matter what you do with the styles, widgets always work — ARIA attributes, keyboard navigation, event handling, and state management are baked into the widgets themselves, not the CSS.

How it works

• Standard CSS — You can target any element with regular CSS selectors. No special techniques, no piercing, no workarounds needed.
• Predictable class names — Widgets use consistent classes like .gui-form, .gui-widget, .gui-button, .gui-repeater__card, and .gui-widget--horizontal that you can target directly.
• CSS custom properties — The entire design system is expressed through CSS variables defined on :root. Change a variable, and every widget that references it updates automatically.

Loading styles

Import the CSS file in your project:

@import '@golemui/gui-components/index.css';

That single import gives you the full courtesy layer — every widget is styled and ready to use.

Note

This import is entirely optional. If you skip it, you enter headless mode and widgets render without any visual styling. See Going Headless for how to build a theme from scratch.

What’s included

The index.css file bundles everything you need in a single import:

What you get	Description
Design tokens	Colors, spacing, typography, border radii, and shadows as CSS variables
Responsive scaling	Spacing and font sizes automatically adjust on smaller screens
RTL support	Right-to-left layout for Arabic, Hebrew, and similar languages
Form layout	Base form container that adapts to its available width
Input styling	Styled inputs, labels, hints, and shared field patterns
Widget styles	Visual styles for every widget (button, textinput, calendar, toggle, etc.)
Validation styles	Error message formatting and invalid-state indicators

Dark and light mode

The default is light. Dark mode is opt-in via a single data-theme attribute — "dark" forces dark, "auto" follows the user’s system preference, no attribute keeps things light. Every semantic token has both a light and a dark value; once dark tokens are applied, widgets switch over seamlessly.

See Theming / Dark mode for the full opt-in table and rationale.

Responsive

GolemUI adapts to different screen sizes using two complementary strategies: media queries for global token scaling, and container queries for widget-level layout adaptation.

Breakpoints

GolemUI defines four breakpoint reference tokens:

Token	Value
--gui-bp-sm	640px
--gui-bp-md	768px
--gui-bp-lg	1024px
--gui-bp-xl	1280px

Caution

CSS custom properties cannot be used inside @media queries — this is a CSS limitation. These tokens exist as documented references. The actual media queries in the stylesheet use literal pixel values.

Responsive token scaling

At smaller viewport sizes, spacing and typography tokens automatically scale down to keep the UI compact and readable.

At 768px and below:

Token	Default	Scaled to
--gui-space-6	1.5rem (24px)	1.25rem (20px)
--gui-space-8	2rem (32px)	1.5rem (24px)
--gui-space-10	2.5rem (40px)	2rem (32px)

At 640px and below:

Token	Default	Scaled to
--gui-space-4	1rem (16px)	0.75rem (12px)
--gui-space-6	1.5rem (24px)	1rem (16px)
--gui-space-8	2rem (32px)	1.25rem (20px)
--gui-space-10	2.5rem (40px)	1.5rem (24px)
--gui-font-2xl	1.5rem (24px)	1.25rem (20px)
--gui-font-3xl	2rem (32px)	1.5rem (24px)

Tip

Because widgets use these tokens for their spacing and sizing, they automatically become more compact on small screens — no extra work needed on your part.

Container queries

GolemUI forms respond to their container width, not just the viewport. A form placed in a narrow sidebar adapts correctly even on a wide screen.

When the form container is 480px or narrower:

Component	Behavior
Horizontal fields	Switch from row to column layout
Flex rows	Stack vertically
Calendars	Expand to full container width
Tab buttons	Reduce padding and font size

RTL

GolemUI supports right-to-left layouts for languages like Arabic, Hebrew, and Persian. When you set the localization property to a translator configured for an RTL language, the form switches direction automatically.

React

i18next.init({
  fallbackLng: 'fa',
  fa: {
    translation: {
      rtl: { username: 'نام کاربری', password: 'رمز عبور' },
    },
  },
});

const localization = { /* i18next implementation */ };
const config = { formDef, data: formData, formConfig, localization };

export function FormPage() {
  return <GuiForm config={config} />;
}

Angular

@Component({
  imports: [CommonModule, FormComponent],
  selector: 'app-dynamic-form',
  template: `<gui-form [config]="config"></gui-form>`,
})
export class AppFormPage {
  protected config = {
    formDef,
    localization: { /* i18next implementation */ },
  };
}

Lit

@customElement('lit-form')
export class FormElement extends LitElement {
  protected config = {
    formDef,
    localization: { /* i18next implementation */ },
  };

  render() {
    return html`<gui-form .config=${this.config}></gui-form>`;
  }
}

Vue

<script setup lang="ts">
import { GuiForm } from '@golemui/gui-vue';

const config = {
  formDef,
  data: formData,
  localization: { /* i18next implementation */ },
};
</script>

<template>
  <GuiForm :config="config" />
</template>

Vanilla JS

import '@golemui/gui-components/index.css';
import '@golemui/gui-lit';

const form = document.getElementById('app-form');
form.config = {
  formDef,
  data: formData,
  localization: { /* i18next implementation */ },
};

What adapts automatically

All widgets mirror automatically in RTL mode — no additional CSS needed on your side.

Area	What adapts
Text and inputs	Padding and alignment flip to match reading direction
Icons and arrows	Select arrows, date-picker icons, and toggle sliders reposition
Buttons	Repeater action buttons align to the correct side
Calendar	Month navigation arrows mirror direction

For full i18n setup, see Features / i18n.

Going headless

Skip the CSS import entirely and you enter headless mode — widgets render unstyled but functional. You write all the CSS yourself, targeting the BEM class names that widgets render.

This is the most powerful customization mode: full control, no fighting the courtesy layer. See Going Headless for the full walkthrough.

Next steps

• Theming — Built-in themes (Clay), creating new themes, scoped themes.
• Customization — Override styles with CSS variables, class selectors, design tokens, and icon customization.
• Going Headless — Build a theme from scratch.