Theming
Available Giddaa UI theme tokens and how to override them.
Giddaa UI ships its base styles through @giddaa-housing/ui/styles.css. Import that file once, then define your app's theme values after it.
@import "@giddaa-housing/ui/styles.css";Only import @giddaa-housing/ui/css/giddaa.css if the app wants the Giddaa brand theme. If you are defining your own theme, do not import giddaa.css; set your own values after styles.css.
@import "@giddaa-housing/ui/styles.css";
@theme {
--font-sans: "Red Hat Display Variable", ui-sans-serif, system-ui, sans-serif;
--color-canvas: #ffffff;
--color-fg-primary: #111827;
--color-action-primary: #166534;
--color-action-primary-hover: #14532d;
--color-line-focus: #166534;
}
.dark {
--color-canvas: #0f172a;
--color-fg-primary: #f8fafc;
--color-action-primary: #22c55e;
--color-action-primary-hover: #16a34a;
--color-line-focus: #22c55e;
}
/* Mirror of the `@theme` values so a `.light` subtree can sit inside `.dark`. */
.light {
--color-canvas: #ffffff;
--color-fg-primary: #111827;
--color-action-primary: #166534;
--color-action-primary-hover: #14532d;
--color-line-focus: #166534;
}Declare every token you override in .dark again in .light; a token that only
one scope sets leaks the other scope's value when the two are nested.
Semantic color tokens
These are the primary consumer-facing tokens. Tailwind utilities map from the token name, so --color-surface is used as bg-surface, --color-fg-primary as text-fg-primary, and --color-line as border-line.
| Token | Use |
|---|---|
--color-canvas | Page canvas. |
--color-surface | Default app surface. |
--color-surface-raised | Raised cards, panels, and muted containers. |
--color-surface-overlay | Overlays, popovers, dialogs, and floating surfaces. |
--color-surface-brand | Brand-filled surfaces. |
--color-surface-brand-subtle | Subtle brand background. |
--color-surface-accent | Accent-filled surfaces. |
--color-surface-accent-subtle | Subtle accent background. |
--color-surface-danger-subtle | Subtle danger background. |
--color-surface-info-subtle | Subtle informational background. |
--color-surface-glass-button | Button chrome over imagery. |
--color-surface-glass-overlay-button | Glass overlay button fill. |
--color-surface-glass-overlay-container-1 | First glass overlay container fill. |
--color-surface-glass-overlay-container-2 | Second glass overlay container fill. |
--color-fg-primary | Primary text. |
--color-fg-secondary | Secondary text. |
--color-fg-caption-placeholder | Captions, placeholders, and subdued text. |
--color-fg-brand | Brand text. |
--color-fg-danger | Danger text. |
--color-fg-info | Informational text in the Giddaa theme. |
--color-fg-accent | Accent text. |
--color-fg-on-brand | Text on brand-filled surfaces. |
--color-fg-on-accent | Text on accent-filled surfaces. |
--color-line-subtle | Subtle dividers and low-emphasis borders. |
--color-line | Default borders and dividers. |
--color-line-strong | Strong borders and dividers. |
--color-line-focus | Focus rings and active outlines. |
--color-line-danger | Invalid and danger borders. |
--color-action-primary | Primary action fill. |
--color-action-primary-hover | Primary action hover fill. |
--color-action-primary-pressed | Primary action pressed fill. |
--color-action-secondary | Secondary action fill. |
--color-action-secondary-hover | Secondary action hover fill. |
--color-action-secondary-pressed | Secondary action pressed fill. |
--color-action-tertiary | Tertiary action fill. |
--color-action-tertiary-hover | Tertiary action hover fill. |
--color-action-tertiary-pressed | Tertiary action pressed fill. |
--color-action-accent | Accent action fill. |
--color-action-danger | Danger action fill. |
--color-action-danger-hover | Danger action hover fill. |
--color-action-danger-pressed | Danger action pressed fill. |
--color-whatsapp-green | WhatsApp action fill. |
--color-status-success | Success states. |
--color-status-warning | Warning states. |
--color-status-danger | Danger states. |
--color-status-info | Informational states. |
--border | Shared default border alias. |
--color-whatsapp-button is a deprecated alias of --color-whatsapp-green. It
still resolves, so existing bg-whatsapp-button utilities and theme overrides
keep working, but it will be removed in the next major.
Type tokens
| Family | Tokens |
|---|---|
| Font | --font-sans |
| Display | --text-gdt-display, --text-gdt-display--line-height, --text-gdt-display--letter-spacing, --text-gdt-display--font-weight |
| Heading 1 | --text-gdt-h1, --text-gdt-h1--line-height, --text-gdt-h1--letter-spacing, --text-gdt-h1--font-weight |
| Heading 2 | --text-gdt-h2, --text-gdt-h2--line-height, --text-gdt-h2--letter-spacing, --text-gdt-h2--font-weight |
| Heading 3 | --text-gdt-h3, --text-gdt-h3--line-height, --text-gdt-h3--font-weight |
| Heading 4 | --text-gdt-h4, --text-gdt-h4--line-height, --text-gdt-h4--font-weight |
| Heading 5 | --text-gdt-h5, --text-gdt-h5--line-height, --text-gdt-h5--font-weight |
| Body | --text-gdt-xl, --text-gdt-xl--line-height, --text-gdt-lg, --text-gdt-lg--line-height, --text-gdt-md, --text-gdt-md--line-height, --text-gdt-sm, --text-gdt-sm--line-height, --text-gdt-xs, --text-gdt-xs--line-height |
| Small labels | --text-gdt-subtext, --text-gdt-subtext--line-height, --text-gdt-capitalized, --text-gdt-capitalized--line-height, --text-gdt-capitalized--font-weight |
Layout tokens
| Family | Tokens |
|---|---|
| Radius | --radius-sm, --radius-md, --radius-lg, --radius-xl, --radius-2xl, --radius-3xl, --radius-4xl |
| Spacing | --spacing-gdt-xs, --spacing-gdt-sm, --spacing-gdt-md, --spacing-gdt-lg, --spacing-gdt-xl, --spacing-gdt-2xl, --spacing-gdt-3xl, --spacing-gdt-4xl, --spacing-gdt-5xl, --spacing-gdt-6xl, --spacing-gdt-7xl |
Chart tokens
The base chart API reads from these semantic chart slots. Define values that match your app theme.
| Token | Use |
|---|---|
--color-chart-1 | First categorical chart series. |
--color-chart-2 | Second categorical chart series. |
--color-chart-3 | Third categorical chart series. |
Effects tokens
| Family | Tokens |
|---|---|
| Gradients | --gradient-hero-forest, --gradient-hero-forest-moss, --gradient-surface-canvas-lift, --gradient-surface-card-lift, --gradient-surface-brand-tint, --gradient-accent-brass-rise, --gradient-accent-forest-to-brass, --gradient-accent-emerald-to-brass, --gradient-overlay-photo-bottom, --gradient-overlay-photo-dual |
| Shadows | --shadow-1, --shadow-2, --shadow-3, --shadow-4 |
| Elevation 0 | --elevation-e0-bg, --elevation-e0-border, --elevation-e0-shadow |
| Elevation 1 | --elevation-e1-bg, --elevation-e1-border, --elevation-e1-shadow |
| Elevation 2 | --elevation-e2-bg, --elevation-e2-border, --elevation-e2-shadow |
| Elevation 3 | --elevation-e3-bg, --elevation-e3-border, --elevation-e3-shadow |
| Elevation 4 | --elevation-e4-bg, --elevation-e4-border, --elevation-e4-shadow |
Animation tokens
| Token | Use |
|---|---|
--animate-slideUp | Slide-up entrance animation. |
--animate-slideDown | Slide-down animation. |
--animate-scroll | Continuous horizontal scroll. |
--animate-bouncing-loader | Bouncing loading indicator. |
--animate-accordion-down | Accordion expand animation. |
--animate-accordion-up | Accordion collapse animation. |
--animate-sonar-glow | Sonar glow pulse. |
--animate-round-sonar-glow | Round sonar glow pulse. |
--animate-sonar-wave | Sonar's outward ring. Scales and fades a box-shadow ring, so it traces any border radius without leaving the compositor. |
--animate-spin-slow | Slow spin animation. |
Theme scopes
Theming is class-based and symmetric. .dark switches a subtree to the dark tokens, .light switches one back to the light tokens. Add the class to an ancestor — every component below it picks up the new token values; no component takes a theme prop.
<html className="dark">
<body>{children}</body>
</html>Because both classes re-declare every themed token, they nest. Use .light for an island that must stay light inside a dark app (or the reverse):
<div className="dark">
<section className="light">
<TopNavbar brand={<Logo />} items={items} />
</section>
</div>dark: utilities are scoped the same way and do not apply inside a .light island. Alternating deeper than one level (.dark inside .light inside .dark) is not supported.
One caveat: popups, dialogs, and sheets render in a portal on document.body, so they inherit the theme on <html> or <body> — not a scope class further down the tree. When you scope a theme to part of the page and its portalled surfaces must match, pass the class to that surface too (for example positionerProps={{ className: "light" }} on TopNavbar.Viewport, or className="light" on MobileSidebar.Content).
Only override dark tokens inside .dark; do not fork component styles for theme switching unless a component has a documented exception.