CSS

hugolify-theme-design-system uses CSS custom properties (design tokens) instead of SASS variables. Tokens are plain CSS, consumable by any tool (Figma, Tokens Studio, style dictionaries).

CSS packages

The module does not ship its own reset or token system. It composes four framework-agnostic npm packages and adds the Hugolify-specific layer on top.

hugolify-theme-design-system itself is a Hugo module, not an npm package: it is imported through module.yaml and brings the Hugolify-specific layer (tokens, layouts, components, blocks, pages and utilities), writing into every layer above.

Token architecture

Tokens follow a three-level chain: primitive → semantic → component.

primitive/color.css      → raw values (oklch…)
semantic/color.css       → purposeful aliases (--color-brand, --color-danger…)
components/button.css    → scoped tokens (--btn-color-background, --btn-border-radius…)

Never skip two levels: a component token should reference a semantic token, not a primitive directly — unless the primitive has no semantic meaning (e.g. --radius-none).

CSS layers

All tokens and styles are assigned to a named layer. The order is declared once, at the very top of assets/css/main.css, before any @import — CSS fixes a layer’s position the first time its name is seen.

@layer reset, tokens, vendors, base, layouts, components, pages, utilities;

The last layer wins. reset and tokens come first (lowest priority) so token defaults never override base, layout or component styles.

Custom media queries are not layered: @custom-media is resolved at build time by PostCSS.

Breakpoints

Breakpoints are @custom-media rules from @uncinq/css-base, named as rungs on a ladder rather than devices.

@media (--md) {
  .card { --card-padding-inline: var(--spacing-lg); }
}

The device names still work but are aliases kept for compatibility — prefer --sm/--md/--lg/--xl in new code.

Components that own a panel (header, filters, sidebar menu, table of contents) get their own semantic custom media, generated in main.css from site params — so the breakpoint and the .panel-inline-* classes in the markup cannot drift:

# /config/_default/params.yaml
header:
  expand: md # md by default, none = always an overlay

Heading sizes

Heading font sizes are fluid: each level references a clamp() token from the semantic scale, so no media query is involved.

/* @uncinq/design-tokens — semantic/typography.css */
--font-size-fluid-xl:   clamp(1.5rem, 0.9718rem + 2.2535vw, 3rem);
--font-size-heading-01: var(--font-size-fluid-xl);
--font-size-heading-02: var(--font-size-fluid-lg);

/* @uncinq/css-base — base/headings.css */
h1 { --font-size-heading: var(--font-size-heading-01); }

To change a heading size, redefine the token — not the selector:

/* assets/css/tokens/site.css */
@layer tokens {
  :root {
    --font-size-heading-01: var(--font-size-fluid-2xl);
  }
}

Responsive tokens

Some component tokens change at breakpoints. The breakpoint logic lives in the component CSS, not in the token file: token files only hold static values, and the media query just reassigns the token the component reads.

/* @uncinq/component-tokens — components/container.css — static values */
--container-max-width-tablet:      100%;
--container-max-width-tablet-wide: 100%;
--container-max-width-laptop:      100%;
--container-max-width-desktop:     var(--size-desktop);

/* @uncinq/css-base — layouts/container.css — responsive logic */
.container {
  max-width: var(--container-max-width, var(--container-max-width-mobile));

  @media (--tablet)      { --container-max-width: var(--container-max-width-tablet); }
  @media (--tablet-wide) { --container-max-width: var(--container-max-width-tablet-wide); }
  @media (--laptop)      { --container-max-width: var(--container-max-width-laptop); }
  @media (--desktop)     { --container-max-width: var(--container-max-width-desktop); }
}

Grid params and image widths

Four site params describe the page grid in numbers. They are read only by the Go templates, to compute the pixel width of an image before it is resized. They never produce a single line of CSS.

column:
  mobile: 1
  desktop: 12
container:
  desktop: 1440
  mobile: 375
gap:
  desktop: 30
  mobile: 30
gutter:
  desktop: 60
  mobile: 30

A block asking for a 4-column image gets GetColumnWidth → (container − 2 gutters − gaps) / 12 × 4 + gaps, rounded up, and that number is what Hugo (or your image CDN) resizes to.

Dark mode

Dark mode is off by default. Turning it on hands the choice to the operating system:

css:
  darkmode: true # false (default) forces light

The dark values ship with @uncinq/design-tokens and reassign the semantic color tokens only: --color-background, --color-text, --color-border… Components follow without a single dark-specific rule.

Your own dark values go under the same guard, so a site switched back to light keeps working:

/* assets/css/tokens/theme.css */
@layer tokens {
  @media (prefers-color-scheme: dark) {
    :root:not([data-color-scheme="light"]) {
      --color-brand: oklch(0.7 0.16 22);
      --header-color-background: var(--color-background);
    }
  }
}

Where overrides go

The module ships four empty files, imported last by main.css in this order — tokens first, rules after, and site after theme in each pair:

tokens/theme.css → tokens/site.css → theme.css → site.css

In both pairs the split is the same, and it is about lifespan, not about size: what a second site would want too goes in the theme file, typically shipped as a theme module of your own; what only this project needs goes in the site file. A project with no shared look uses the site files only, and never has to touch the theme ones.

The four files are empty in the module — create the one you need at the same path in your project, and Hugo’s asset priority (project > theme > modules) replaces it.

Overriding tokens

Two entry points, both imported after tokens/design-system.css, so they cascade over every default:

/* assets/css/tokens/theme.css — the look, reusable across sites */
@layer tokens {
  :root {
    --color-brand: #e63946;
    --btn-border-radius: var(--radius-pill);
  }
}

/* assets/css/tokens/site.css — this site only, wins over the theme above */
@layer tokens {
  :root {
    --header-height: 72px;
  }
}

Overriding CSS

Same split for rules that no token covers. Write to the same layer as the rule you are overriding:

/* assets/css/site.css */
@layer components {
  .card .media img { filter: grayscale(1); }
}

Component variants

Color variants set CSS custom properties scoped to the modifier class, consumed by the base component:

.alert { background-color: var(--alert-color-background); color: var(--alert-color-text); }

.alert-danger  { --alert-color-background: var(--color-danger-muted);  --alert-color-text: var(--color-danger-strong); }
.alert-success { --alert-color-background: var(--color-success-muted); --alert-color-text: var(--color-success-strong); }

Available variants (alert, badge, btn): brand, primary, secondary, neutral, success, danger, warning, info, light, dark.

Buttons add ghost, link and control variants, plus sizes btn-xs to btn-xl.