stnd.build

Hybrid Element Styling

Error: [ERR_HYBRID_ELEMENT_STYLING] Element mixes framework utility classes with custom inline or scoped layout styles. Standard Architecture: Single Source of Truth per Element.


The Problem

An HTML element splits its layout or dimensional styling across two competing systems: utility classes on the element itself, and custom inline style="..." attributes (or competing rules in <style>).

<!-- Problematic: Hybrid Frankenstein styling -->
<div class="flex gap-2" style="align-items: center;">
<div class="grid grid-2" style="gap: var(--space-d2); margin-bottom: var(--space-d3);">

The Why

Mixing utility classes and bespoke styling on the same element creates architectural confusion known as hybrid styling or Frankenstein code:

  1. Split mental model: Half of the element’s layout lives in the HTML class attribute, while the other half is declared in an inline style or a <style> block. Anyone modifying or debugging the element must inspect both places simultaneously.
  2. Specificity & overriding conflicts: Utility classes (.flex, .gap-2, .items-center) are designed to be self-sufficient layout primitives. When combined with inline styles or custom block declarations that set align-items, gap, or display, they trigger specificity clashes and redundant overrides.
  3. Loss of Vanilla First clarity: Standard components follow the Single Source of Truth per Element law. An element is styled either entirely through the framework’s Swiss utilities in HTML, or entirely through component-scoped CSS in <style>.

The Solution

Choose one of the two pure modes:

If the layout fits within the Standard utility vocabulary, use utility classes exclusively directly in the HTML. Do not add inline layout styles or custom class overrides:

<!-- Clean Mode A: 100% utility classes -->
<div class="flex items-center gap-2">
<div class="grid grid-2 gap-d2 mb-d3">

Mode B: 100% Scoped CSS in <style> (When exceeding utilities)

If the element requires complex grid definitions, custom container queries, animation keyframes, or pseudo-elements (::before/::after):

Remove all utility classes from the element, and declare 100% of its layout and styling inside the component’s <style> block:

<!-- Clean Mode B: 100% scoped style, zero utility classes -->
<div class="inspector-grid">
/* Inside component <style> */
.inspector-grid {
  display: grid;
  grid-template-columns: 240px 1fr 320px;
  gap: var(--space-d2);
  margin-bottom: var(--space-d3);
  align-items: center;
}