CORE UTILITY FAMILY
Arbitrary properties
Emit a validated CSS property/value pair when no first-class utility represents a one-off requirement.
WHEN TO USE IT
Choose the right tool for the layout.
Use arbitrary properties as an escape hatch, keep them literal for scanning, and promote repeated values into theme tokens or registered utilities later.
QUICK REFERENCE
Classes and generated CSS
These examples are resolved by the compiler when the registry manifest is generated. A broken example fails the test suite.
co-[mask-type:luminance]mask-type: luminance;co-text-[length:2rem]font-size: 2rem;co-bg-[image:linear-gradient(to_right,#000,#fff)]background-image: linear-gradient(to right,#000,#fff);VISUAL EXAMPLE · ONE-OFF PROPERTY
Use a CSS property that has no dedicated utility
Write the property and value directly inside brackets. This is useful for isolated browser features while keeping the declaration colocated with the component.
<p class="co-[writing-mode:vertical-rl]">
Vertical label
</p>
<svg class="co-[mask-type:luminance]">...</svg>VISUAL EXAMPLE · TYPE HINTS
Disambiguate values with an explicit type
Type hints tell the resolver whether an ambiguous value represents a length, color, image, position, font family, or font weight.
<h2 class="co-text-[length:2rem]">Large heading</h2>
<p class="co-text-[color:oklch(60%_0.2_250)]">Typed color</p>
<div class="co-bg-[image:linear-gradient(to_right,#000,#fff)]"></div>
<div class="co-grid co-grid-cols-[200px_minmax(0,1fr)]"></div>SYNTAX EXAMPLE · SPACES & UNDERSCORES
Encode spaces without breaking the class name
An unescaped underscore becomes a space. Escape it when the resulting CSS value must contain a literal underscore.
<!-- underscores become spaces -->
<div class="co-grid-cols-[200px_minmax(0,1fr)]"></div>
<p class="co-font-[family:Inter,_sans-serif]">...</p>
<!-- escaped underscore stays an underscore -->
<div class="co-[--label:hello\_world]"></div>VISUAL EXAMPLE · CUSTOM PROPERTIES
Define and consume a local CSS variable
Custom property names beginning with -- are valid arbitrary properties. This keeps a one-off relationship explicit without adding a global token.
<article class="co-[--card-angle:4deg] co-[transform:rotate(var(--card-angle))]">
Rotated by a local variable
</article>INTERACTIVE EXAMPLE · VARIANT COMPOSITION
Combine arbitrary declarations with normal variants
Hover the card. State and responsive prefixes wrap arbitrary properties using the same variant pipeline as first-class utilities.
<article class="co-[transform:translateY(0)] hover:co-[transform:translateY(-7px)] hover:co-[letter-spacing:.08em] md:co-[padding:2rem]">
Hover me
</article>AI-FRIENDLY EXAMPLE · STATIC SCANNING
Keep the complete candidate literal in source
The scanner reads source as text and does not execute template interpolation. Choose from complete class strings so humans and AI agents can verify the exact generated candidate.
// Good: every complete candidate exists in source
const widths = {
compact: "co-[width:18rem]",
wide: "co-[width:32rem]",
};
<aside class={widths[mode]} />
// Avoid: the scanner cannot reconstruct this candidate
<aside class={`co-[width:${size}rem]`} />SECURITY EXAMPLE · VALIDATION
Reject declarations that escape their boundary
The compiler validates property names and values before emitting CSS. Arbitrary values must still come from trusted source code and never directly from runtime user input.
<!-- accepted -->
<div class="co-[mask-type:luminance]"></div>
<!-- rejected: attempts to inject a second declaration -->
<div class="co-[color:red;background:blue]"></div>DESIGN SYSTEM · PROMOTION PATH
Promote repeated values into a token
An arbitrary value is appropriate for a genuine exception. When the same decision appears repeatedly, give it a semantic theme name so usage becomes consistent and easier for AI to track.
<!-- Fine for a one-off prototype -->
<div class="co-rounded-[18px]"></div>
<!-- Repeated decision: promote it -->
@co-theme { --co-radius-panel: 18px; }
<div class="co-rounded-panel"></div>BASIC USAGE
Apply a utility directly.
Keep the complete class string in your template so the plain-text scanner can discover it without evaluating application code.
<div class="co-[mask-type:luminance] co-text-[length:2rem] co-bg-[image:linear-gradient(to_right,#000,#fff)]">
Your content
</div>HOW IT WORKS
Core concepts
- 01
Syntax is co-[property:value].
- 02
Unescaped underscores inside arbitrary values become spaces while \_ remains an underscore.
- 03
Type hints disambiguate color, length, image, position, font family, and font weight values.
- 04
Property names and declaration values are validated before CSS is emitted.
CSS PROPERTIES
What this family controls
any validated CSS propertycustom properties beginning with --VARIANTS
Responsive and state conditions
Prefix any supported utility with responsive or state variants. Variants compose from left to right and the compiler emits the required selector or at-rule.
<div class="co-[mask-type:luminance] md:co-text-[length:2rem] hover:co-[mask-type:luminance]">
Responsive and state-aware content
</div>ARBITRARY VALUES
Escape the scale when necessary
Use square brackets for a one-off CSS value. Prefer theme tokens for values repeated across components so an AI agent and human reviewer can recognize design intent.
co-[{property}:{value}]
co-[content-visibility:auto]SCOPE BOUNDARIES
Intentional boundaries
This family is implemented, documented, and tested. These notes define where a neighboring family or browser behavior takes over.
- User-provided arbitrary values are emitted as CSS and should come from trusted source code, not runtime input.
- Repeated arbitrary values should be promoted to theme tokens for consistency.