CSS Architecture

Core CSS files

assets/css/vars/primitives.css

Internal calculated primitive values. Not a standard component API.

assets/css/vars/semantic.css

Semantic values that cannot be expressed conveniently as theme.json collections: radius, z-index, motion, line height, and others.

assets/css/vars/theme-core.css

Parent/child contract, helper aliases, breakpoints, and runtime variables.

assets/css/front.css

Frontend-only base layer:

• global box-sizing;
• link underline;
• text-wrap: pretty;
• focus-visible;
• header stacking;
• separate frontend integration styles.

assets/css/front-and-admin.css

Shared frontend and editor-iframe layer:

• mark reset;
• root layout corrections;
• core-block changes;
• utility classes;
• Navigation defaults.

assets/css/admin-block-editor.css

Administrative editor UI styles and fixes that must not reach the frontend.

assets/css/_doc-wp-presets.scss

Documentation and IDE autocomplete only for generated WordPress variables. This file is not a runtime source and must not be included in a bundle.

Import order in a child theme

Typical frontend/editor entry point:

@use '../../../../core-fse/assets/css/vars/primitives.css' as *;
@use '../../../../core-fse/assets/css/vars/semantic.css' as *;
@use '../../../../core-fse/assets/css/vars/theme-core.css' as *;
@use '../vars.css' as *;
@use '../../../../core-fse/assets/css/front-and-admin.css' as *;
@use '_extra.scss' as *;

Required order:

1. Primitive;
2. Semantic;
3. Core contract defaults;
4. child theme overrides;
5. shared core styles;
6. theme-specific styles.

The actual path to child variables may differ. The role and position of the file in the cascade are what matter.

Frontend-only entry point:

@use '../../../../core-fse/assets/css/front.css' as *;
@use '_extra.scss' as *;

Why core CSS is compiled into the child bundle

Core CSS is imported directly instead of being loaded through separate runtime handles:

• fewer CSS files and dependencies;
• a clear cascade order;
• the child theme owns the final bundle;
• the frontend and editor use a consistent foundation;
• the result is predictable for every theme.

Consequently, changing imported core CSS requires rebuilding every dependent child theme.

Source and generated assets

Sources of truth:

• .scss;
• unminified CSS variables;
• other explicitly editable source files.

Generated output:

• .min.css;
• source maps.

Do not manually fix generated CSS. If source and output differ, rebuild the output.

Commands and tooling may differ between child themes. In Benedictine:

npm run build

The documentation does not require every theme to have identical Vite configuration.

Frontend/editor parity

Styles affecting block contents in the editor must be included in the bundle loaded through enqueue_block_assets.

Frontend-only behavior is loaded through wp_enqueue_scripts.

Check the change:

1. frontend;
2. post editor;
3. Site Editor, if the change affects templates or template parts;
4. focus, hover, and responsive-layout states.

Accessibility

Base CSS sets focus-visible through the accent color and browser outline style. --color-on-image is used on media backgrounds.

Rules:

• do not remove an outline without an equivalent accessible replacement;
• check focus on base, accent, and image backgrounds;
• maintain sufficient contrast;
• do not break user text scaling;
• remember that typography and spacing are based on rem and fluid values.

Base visual rules

core-fse also provides:

• border-box for all elements;
• controlled underline thickness;
• improved text wrapping;
• maximum site width;
• the absence of an unwanted root block gap;
• base Navigation and Button changes;
• small utility classes.

This is part of the shared visual layer, not tokens.

Additional admin CSS

The Global Styles administrative module can add custom inline CSS to the frontend and editor. It is not part of the design system, but must be considered when diagnosing an unexpected override.