Automatic Conflict Resolution

Maple treats the class attribute as an ordered style declaration. When two utilities write the same CSS property in the same context, the utility on the right wins and the overridden utility is removed from the element.

Why Maple Merges Classes

Utility classes are easy to compose, but equal-specificity utilities do not follow the visual order of the class string by default. The browser chooses between generated CSS rules by stylesheet order, not by the order of tokens inside the class attribute.

In Tailwind-style component code, conflicts are often handled by passing class strings through helpers such as clsx and tailwind-merge. Maple moves that responsibility into the runtime CSS engine instead. It reads the element after classes exist in the DOM, calculates what each utility will write, and normalizes the class list in place.

The Class Attribute Is the Source of Truth

You can append classes from templates, bindings, CMS fields, server output, or direct DOM APIs. Maple resolves the final class list after those classes are on the element.

Core Rule

Maple builds a conflict key from the generated CSS property plus its media-query and selector context. If a later utility targets the same key, it replaces the earlier one. If the context is different, both utilities stay.

<div class="p-4 p-8"></div>
<!-- Normalizes to class="p-8" -->

<div class="@md:p-4 @md:p-8"></div>
<!-- Normalizes to class="@md:p-8" -->

<div class="p-4 @md:p-8"></div>
<!-- Both are kept as they are in different contexts -->

Input

Normalized

Reason

p-4 p-8

p-8

Both write padding in the base context.

@md:p-4 @md:p-8

@md:p-8

Both write padding in the same media context.

p-4 @md:p-8

Base and responsive contexts are independent.

&:hover:p-4 &:hover:p-8

&:hover:p-8

Both write padding inside the same selector context.

Context Is Exact

Stacked modifier order is part of the selector context. &:hover:focus:p-2 and &:focus:hover:p-4 are preserved as separate contexts.

Context Details

The context part of a conflict key includes media prefixes, selector prefixes, arbitrary variants, and important priority. Different contexts preserve their utilities even when the final property is the same.

Input

Normalized

Why

p-6 p-6

p-6

Exact duplicates collapse to the last occurrence.

@md:p-4 @lg:p-4

Different media contexts do not conflict.

@dark:@md:p-6 @md:@dark:p-4

@md:@dark:p-4

Equivalent media stacks share a context after Maple normalizes them.

^.active:p-4 ^.active:p-6

^.active:p-6

Parent selectors are part of the selector context.

[&:nth-child(3)]:py-0 [&:nth-child(3)]:py-4

[&:nth-child(3)]:py-4

Arbitrary variants merge when their selector context matches.

Property-Aware Merging

Maple does not compare class names as plain strings. It parses each utility, resolves abbreviations, understands shorthand coverage, and compares the CSS properties that would actually be emitted.

Input

Normalized

What Maple Sees

p-4 padding-6

padding-6

Abbreviations and original CSS property names share a conflict space.

p-4 p=10px

p=10px

Token values, arbitrary values, and literal values all target the same property.

h-[10px] h-[20px]

h-[20px]

Arbitrary values merge by their generated property.

--tone-factor=1 --tone-factor=2

--tone-factor=2

CSS variable utilities merge by variable name.

fx gr

gr

Aliases conflict when they emit the same CSS property.

Broad shorthands can remove earlier longhands that they fully cover, but Maple keeps later refinements when they intentionally narrow part of a shorthand. This lets you write broad defaults first and then adjust one edge, axis, or component.

Input

Normalized

Result

mx-4 m-6

m-6

The later margin shorthand covers the earlier X axis.

m-6 mx-4

The later X-axis utility refines the shorthand.

brt-1 br-2

br-2

The later border shorthand covers the top border.

br-px_solid brc-red

Border color can refine a previously declared border.

brc-red br-px_solid

br-px_solid

The later border shorthand includes browser's native color definition, overriding the previous border color utility.

False Positives Are Avoided

Maple compares real CSS relationships, not property-name prefixes. Pairs such as br-px rad-px, fx-1 fxdir=row, of=hidden ofwr=anywhere, and cols-1 col-2 stay together because they target distinct behavior.

Composable Properties

Some CSS features are assembled from independent components. Maple merges those utilities by component, not by the final serialized property, so compatible transform and filter utilities can live together.

Input

Normalized

Reason

tl-4 rot-45

Translate and rotate are separate transform components.

tl-4 tl-8

tl-8

Both utilities write the translate component.

blur-4 brightness-100

Different filter components compose.

blur-4 blur-8

blur-8

Both utilities write the blur component.

Important Utilities

Important utilities participate in the same merge model, but Maple preserves CSS priority. A later important utility replaces earlier normal or important utilities for the same property. A later normal utility does not remove an earlier important utility, because both can affect the final cascade differently.

<div class="!p-3 !p-4"></div>
<!-- class="!p-4" -->

<div class="p-3 !p-4"></div>
<!-- class="!p-4" -->

<div class="!p-3 p-4"></div>
<!-- class="!p-3 p-4" -->

Refinements follow the same priority rules. For example, !p-3 px-5 stays intact because the normal X-axis refinement can still contribute where it is not suppressed, while px-5 !p-3 becomes !p-3.

Aliases

Aliases are expanded before merge checks, so their members can conflict with regular utilities. The alias token remains in the class list when at least one expanded utility still contributes to the element.

<html class="--alias-space=p-4">
  <div class="@space p-8"></div>
  <!-- class="p-8" -->
</html>

<html class="--alias-focus-ring=olw-2px;olst=solid;olc=currentColor">
  <button class="@focus-ring olw-4px"></button>
  <!-- class="@focus-ring olw-4px" -->
</html>

In the first example, @space expands only to p-4, so a later p-8 fully replaces it. In the second, @card also contributes bgc-white, so the alias stays even though its padding member is overridden.

Disabling Conflict Resolution

Automatic conflict resolution is enabled by default. Use nomerge only when you deliberately want Maple to leave class attributes exactly as authored. The behavior and trade-offs are covered in Configuration: Nomerge Mode.