Skip to main content

LLM compose rules

The composition contract for any agent generating markup against Semetrika. Read after LLM overview. Every rule below is enforced either in CSS (a violation simply does not style) or by review.

Multiple class words on one element​

Values compose via multiple class words on the root element. Class order does not matter - precedence is determined by @layer, not source order.

<!-- Correct -->
<button class="solid md pill">Save</button>
<button class="md pill solid">Save</button>
<!-- equivalent -->

<!-- Wrong -->
<button class="btn-solid-md-pill">Save</button>
<!-- never compound -->
<button class="btn-solid">Save</button>
<!-- forbidden form -->

The pattern .{component}-{value} (.btn-solid) is RESERVED for child classes (e.g. .card-header, .modal-body), never for values. Atomic components (button, badge, chip) have no children - they own only their root.

Mirror class equivalence​

Every element-styled component has a mirror class that produces the identical visual on a generic element.

<!-- Element form -->
<button class="solid md">Save</button>
<article class="raised">...</article>
<dialog class="lg">...</dialog>

<!-- Mirror form - interchangeable -->
<a class="btn solid md">Save</a>
<div class="card raised">...</div>
<div class="modal lg">...</div>

Pick one form per element. NEVER apply both: <button class="btn"> is forbidden - the element is already styled, the mirror class is redundant.

Mirror class table - the canonical pairings shipped by Semetrika today:

ElementMirror
<button>.btn
<article>.card
<table>.table
<blockquote>.blockquote
<dialog>.modal
<nav>.nav
<details>.accordion
<progress>.progress
<a>.link
<fieldset>.group

When using the mirror form, prefer a meaningful semantic fallback (<a>, <section>, <article>) over a bare <div> when possible.

Component class lives on the outermost element​

When a landmark or wrapper element exists (<nav>, <aside>, <dialog>, <details>, <article>, <form>), the component class lives on that element, not on a nested child.

<!-- Correct -->
<nav class="pagination" aria-label="Pagination">
<ol>
...
</ol>
</nav>

<!-- Wrong -->
<nav aria-label="Pagination">
<ol class="pagination">
...
</ol>
</nav>

Emphasis and Intent are two separate palette capabilities​

Prominence and status are two orthogonal capabilities. A component opts into one, the other, or both.

  • Emphasis is the prominence dial: subtle, neutral, accent. Mutually exclusive - pick one. neutral is the implicit default for every component that declares Emphasis, so omit it unless you want to be explicit; both forms are equivalent.
  • Intent is the status palette: info, warning, danger, success. Mutually exclusive - pick at most one. Intent is opt-in with no default: a component carries no status unless you set one.

Pick at most one word from each capability. The default vocabulary styles each value within its own @layer; it does not define a combined emphasis-plus-intent rendering (e.g. subtle on danger) - a consumer who needs one extends the spec deliberately.

<!-- Correct - Emphasis on its own -->
<button class="solid subtle">Cancel</button>
<!-- Correct - Intent on its own -->
<button class="solid danger">Delete</button>

<!-- Wrong - two Emphasis values -->
<button class="solid subtle accent">...</button>
<!-- Wrong - two Intent values -->
<button class="solid danger success">...</button>

Size ladder and breakpoint suffixes​

The size ladder is xs, sm, md, lg, xl (a few utilities extend with xxs, xxl, xxxl). Bare size words are SIZE values only.

Breakpoint-scoped values use the .at-* suffix form, never the bare size word:

<!-- Correct -->
<div class="container at-md">...</div>
<!-- "from md and up" -->
<aside class="visible at-lg">...</aside>

<!-- Wrong -->
<div class="container md">...</div>
<!-- 'md' here is the SIZE value, not a breakpoint -->

Color names (.blue, .dark) MUST NOT be used as values. Emphasis values (.subtle, .neutral, .accent) and intent values (.info, .warning, .danger, .success) are the only color-bearing values.

State belongs on attributes, never on classes​

Runtime / observed state is expressed via attributes, in this priority order:

  1. Native pseudo-classes - :disabled, :checked, :hover, :focus-visible, :open.
  2. ARIA - aria-expanded, aria-current, aria-busy, aria-hidden, aria-pressed.
  3. Namespaced data-* - data-collapsible-collapsed, data-drawer-scroll-lock (per-component, declared in the schema's states).

The .is-* state-class convention (e.g. .is-active, .is-open) is forbidden everywhere. Bare value words on a child element that mark a declarative, author-set status (e.g. <li class="complete"> inside <ol class="steps">) are still values - they describe what the markup says, not runtime behavior.

<!-- Correct - state via attributes -->
<button disabled>Save</button>
<button aria-busy="true">Saving...</button>
<details open>...</details>

<!-- Wrong - never .is-* -->
<button class="is-disabled">Save</button>

JS hooks via data-*​

JS behavior is wired via per-component data-* attributes. Look up components.<name>.hooks to find each component's contract. Examples:

<!-- Collapsible: mark root, JS resolves trigger + panel -->
<div data-collapsible>
<button>Toggle</button>
<div>Body</div>
</div>

<!-- Carousel: data-carousel marks root, data-carousel-autoplay opts into autoplay -->
<div data-carousel data-carousel-autoplay="5000">...</div>

<!-- Drawer: data-drawer-backdrop opts into a sibling dimming overlay -->
<dialog class="drawer" data-drawer-backdrop>...</dialog>

Every JS-driven component works without JS as a baseline (progressive enhancement). The data attribute opts the element into enhancement; the visual baseline still renders without it.

The @layer order​

Value capabilities resolve in a fixed @layer order declared in src/layers.css. Later layers win when they declare the same property:

base → intent → emphasis → fill → size → shape → fit → layout →
orientation → alignment → spacing → position → visibility →
motion → elevation → surface → annotation → state

You will never need to write @layer declarations in consumer code - the bundle ships with the layer order baked in. The order matters only for understanding why <button class="md solid"> and <button class="solid md"> produce identical results.

Slots are markup positions, props are typed values​

Each component's contract declares two surfaces:

  • Slots - places where the consumer drops markup (text or HTML). The schema lists slot names and descriptions.
  • Props - typed values the component renders into attributes or text (string, number, boolean, enum, array, object). classes (array) and attributes (object) are universal passthroughs.
<!-- card has: title (prop, string), title_id (prop), supertitle (prop), -->
<!-- content (slot), image (slot), tags (slot), actions (slot) -->
<article class="card raised" aria-labelledby="card-1">
<header>
<small>October 2026</small>
<!-- supertitle prop -->
<h3 id="card-1">Quarterly report</h3>
<!-- title prop -->
</header>
<p>Body markup goes here.</p>
<!-- content slot -->
<footer>
<a class="badge">News</a>
<!-- tags slot -->
<button class="ghost">Read</button>
<!-- actions slot -->
</footer>
</article>

The schema's examples[].markup is the authoritative example for each documented usage pattern. Copy the closest example and substitute slot/prop values.

Common mistakes to avoid​

  • Compounding value words. .btn-solid-md is wrong. Use .solid .md on the same element.
  • Adding mirror class to a styled element. <button class="btn"> is redundant - <button> is already styled. Use <a class="btn"> only on non-button elements.
  • Adding role="button" to <summary> or role="dialog" to <dialog>. Native semantics already expose these - adding the redundant role is wrong.
  • Using .is-active, .is-open for state. Forbidden everywhere. Use native pseudo-classes, ARIA, or component-scoped data-* per the schema's states.
  • Combining values from the same capability. .subtle .accent is two Emphasis values - pick one. .danger .success is two Intent values - pick one.
  • Inventing class words. Every word lives in vocabulary (canonical capability values), components.<name>.capabilities.visual / components.<name>.props (per-component values), or the utility classes. If a word isn't in the schema, it isn't real.
  • Wrapping a component in a utility for layout positioning inside another component's markup. Layout and spacing utilities (.container, .py4, .grid) are positioned by the page author, not bundled into the component markup itself.
  • Using |raw in Twig consumer code. Semetrika's Twig examples assume autoescape: false; consumer-side Twig autoescape policy is up to the host.

Reading the canonical example trio​

Each renderable component ships three canonical examples - empty, minimal, full - plus zero or more custom examples. When you need to know what valid markup looks like for a component:

  • examples find name === 'minimal' - the smallest useful HTML the component supports. No value classes; just the structural skeleton with placeholder slot fills.
  • examples find name === 'full' - every slot filled and every value dim set to its next-on-ladder value (one step past the default). This is the single best place to read every value dim demonstrated at a non-default value in one snippet. If you see class="card solid lg rounded vertical raised subtle", that's six dims, six non-defaults, all valid.
  • examples find name === 'empty' - what the component renders when you pass nothing. Some components render the bare wrapper; others render an empty string because their twig guards on a primary slot. Read it to know whether the component is safe to drop in without filling content.

full does NOT show every value of every capability - only one non-default per capability. Use vocabulary.<capability>.enums and components.<name>.capabilities.visual[].values for the full allowlist.

Single-value capabilities​

When a component's capability declares a single value and no explicit default, that lone value IS the capability's default - the class is supported but absence of the class also represents the default state. The component only exposes one option for that capability; there is no other state to switch to.

Example: badge declares shape: ["pill"]. Both <span class="badge"> (no pill) and <span class="badge pill"> (with pill) are valid renderings of the default shape, because pill is the only value the shape capability can take. A multi-value capability with no default is a spec bug; a single-value capability with no default is the convention for "this capability has one optional class".

When in doubt​

Read components.<name>.examples[].markup - the rendered example for the closest pattern is the source of truth. The contract describes what's allowed; the example shows one valid instantiation. If you cannot find an example matching your need, you are probably trying to do something outside Semetrika's vocabulary; extend the spec or pick a closer pattern.