Custom utilities

Register a static utility

Use a lowercase hyphenated name and ordinary CSS declarations. A project definition takes priority when it resolves the same body as a built-in utility.

@coordiation;

@co-utility content-auto {
  content-visibility: auto;
  contain-intrinsic-size: auto 1000px;
}

<section class="co-content-auto md:co-content-auto hover:!co-content-auto">
  ...
</section>

Add a functional wildcard

End a pattern with one -* wildcard. Resolve the captured part through co-value(); the first matching resolver wins.

@co-theme {
  --co-tab-size-github: 8;
}

@co-utility tab-* {
  tab-size: co-value(
    --co-tab-size-*,
    integer,
    [integer],
    co-default(4)
  );
}

This definition accepts co-tab, co-tab-github, co-tab-7, and co-tab-[13].

Resolve slash modifiers separately

Use co-modifier() for the portion after an unbracketed slash. A declaration with no matching modifier is omitted while other valid declarations remain.

@co-utility type-* {
  font-size: co-value(--co-text-*, [length]);
  line-height: co-modifier(
    --co-leading-*,
    [length],
    co-default(1.2)
  );
}

<h2 class="co-type-[2rem]/tight">Readable heading</h2>

Keep fractions as one value

The ratio resolver treats an unbracketed slash as part of the value before trying modifier resolution.

@co-utility frame-* {
  aspect-ratio: co-value(ratio, [ratio]);
}

Both co-frame-3/4 and co-frame-[7/9] compile to validated ratios. A zero denominator is rejected.

Declare negative behavior explicitly

Negative values are never inferred. Register a second pattern so reviewers and agents can see exactly which family permits negation.

@co-utility offset-* {
  inset: calc(co-value(integer) * var(--co-space-unit));
  inset: co-value([length], [percentage]);
}

@co-utility -offset-* {
  inset: calc(co-value(integer) * var(--co-space-unit) * -1);
  inset: calc(co-value([length], [percentage]) * -1);
}

<div class="co-offset-4 -co-offset-[2rem]"></div>

Fail before invalid CSS ships

The compiler rejects malformed names, duplicate patterns, empty or malformed declarations, unsafe candidate values, nested rules, and authored !important. Use the class important modifier so variants and output remain canonical.

Inspect the project manifest

Each compile result reports project-local patterns without mixing them into the framework's global registry.

const result = compile(inputCss, candidates);

console.log(result.customUtilities);
// [{
//   pattern: "tab-*",
//   functional: true,
//   properties: ["tab-size"]
// }]