Skip to main content

LLM overview

A dense primer for an AI agent that has not seen Semetrika before and needs to generate or audit markup against it. Read this once, then read LLM compose rules. Together they cover the public contract; the structured contract per component is shipped in dist/semetrika.spec.json.

Identity​

Semetrika is a classless-first CSS design system. Plain semantic HTML is the primary form: <button>, <article>, <dialog>, <details>, <nav>, <table>. Every element-styled component also exposes a mirror class so the same visual works on a generic element when the host markup is constrained.

<!-- Element form (preferred) -->
<button class="solid md">Save</button>

<!-- Mirror form (equivalent - same visual) -->
<a class="btn solid md">Save</a>

The element form and the mirror form share CSS declarations. Never apply both at once: <button class="btn"> is redundant and forbidden.

The four types​

Everything Semetrika ships belongs to exactly one of four types.

TypeWhat it isReach for it?
FoundationTokens (primitive, semantic), colors, typography scale, icons, optionsNo - substrate everything builds on
UtilityGrid, container, atomic CSS (.mt-4, .justify-center), JS helpers (collapsible, scrollspy)Components use these internally
ComponentReusable UI building block (button, card, navbar, textfield)Yes - what a page author places
PatternComposition of components and utilities (contact-form, card-grid, pricing-table)Copy and adapt - reference only

The classification test for any new thing: would a page author reach for it when building a page? If yes, Component. If it's shipped infrastructure components use internally, Utility. If it's a composition of components and utilities, Pattern. If it's substrate (tokens, scale, icons), Foundation.

The capability vocabulary​

Values are bare class words composed on the root element. Thirteen canonical capabilities (each mapped to a CSS @layer of the same name) cover every visual axis:

CapabilitySample valuesLayer
Intentinfo, warning, danger, successintent
Emphasissubtle, neutral, accentemphasis
Fillsolid, outline, ghostfill
Sizexs, sm, md, lg, xlsize
Shaperounded, square, pill, circleshape
Fitcover, contain, fillfit
Layoutfluid, contained, fullscreenlayout
Orientationhorizontal, verticalorientation
Alignmenttop, bottom, left, right, centeralignment
Positionstickyposition
Visibilityhidden, assistive, invisiblevisibility
Motionanimated, stillmotion
Elevationflat, raised, elevatedelevation

Authoritative values, descriptions, and per-component support live in dist/semetrika.spec.json under vocabulary (canonical capabilities) and components.<name>.capabilities.visual (the subset each component opts in to).

A capability's default names the value a component renders with no class set. Not every capability declares one. intent never does, since a component reads as neutral until you give it a status, and a component can leave other capabilities without a default too: its base styling applies until a class opts in, so a badge stays rounded until you add pill. A component lists a capability's values in the order the capability itself declares them.

Where to look in semetrika.spec.json​

QuestionLook here
What values does the intent capability allow?vocabulary.intent.enums
What values does the emphasis capability allow?vocabulary.emphasis.enums
Does card support elevation? Which values?components.card.capabilities.visual[].name == "elevation"
What slots does card accept?components.card.slots
What does the markup look like for a card with image?components.card.examples[].markup
What data-* attribute marks a carousel root?components.carousel.capabilities.behavioral[].hooks (init)
What custom event does drawer emit when it opens?components.drawer.capabilities.behavioral[].emits (opened)
What primitive token family backs --body-font-size?tokens.semantic.families.body.tokens.fontSize.from
Which components depend on link?components.*.dependencies[].name == "link"
Is there a cart icon, and in which variants?assets.icons.items.cart.variants
Which icon means "dismiss this dialog"?assets.icons.items.*.description
Does the body typeface have an italic?assets.fonts.items.secondary.variants
Which file backs the heading typeface?assets.fonts.items.primary.files
Which typefaces must the consumer host themselves?assets.fonts.items.*.source == "bundled"

Each entry in components.<name>.dependencies is {name, kind} where kind is "component" or "utility". Consumers can map the kind to host-system asset bundling (e.g. per-component asset dependencies for components, theme-wide CSS includes for utilities).

Shipped assets​

The files behind Semetrika's icons and typefaces are published under assets, keyed by group. Every group carries the same envelope, so you can iterate assets without knowing what is in it: kind (sprite when one file holds every item, collection when there is a file per item), path, mediaType, variants, defaultVariant, and items.

kind is what tells you how to address an item:

KindGroupAddressExample
spriteiconsgroup path + # + item keyicons.svg#close
collectionfontsgroup path + item dir + the variant filefonts/plus-jakarta-sans/…woff2

A collection item therefore carries dir, files (variant to file name), and source, which a sprite item does not: a sprite packs every variant inside one symbol, so the key IS the address and the source file names never ship.

source says who serves an item: bundled means it ships in the package and the consumer deploys it; remote means a third party serves it, dir is null, and each entry in files is an absolute URL rather than a file name. Read it before telling anyone what they need to host.

Icons​

Icons are addressed by role, not by the artwork's name. A role says what the icon means, so close is the dismiss icon regardless of which drawing backs it:

<svg class="icon"><use href="/assets/icons.svg#close"></use></svg> <svg class="icon solid"><use href="/assets/icons.svg#star"></use></svg>

Two rules matter when generating markup:

  • Never invent a role. Read assets.icons.items and use a key that exists; a missing symbol renders as empty space with no error.
  • Never assume both variants exist. Check assets.icons.items.<role>.variants before emitting solid. A role with a single variant ignores the class rather than failing, so the mistake is silent.

The four status roles (info, warning, danger, success) deliberately match the Intent capability values, so a component carrying intent: danger uses the icon role of the same name.

Fonts​

Typefaces are addressed by role on the same principle, one per --font-family-* token:

RoleTokenFaceSourceWeight axis
primary--font-family-primaryPlus Jakarta Sansbundled200-800
secondary--font-family-secondaryOutfitbundled100-900
mono--font-family-monoFira Coderemote300-700

Every face is variable, so one file per style covers a weight range rather than a single weight. secondary draws every --font-weight-* token; primary starts at 200, so --font-weight-thin (100) clamps and renders identically to --font-weight-extralight.

Nothing needs emitting for any of them. The bundle's own @font-face rules load them, so deploying dist/fonts/ beside semetrika.css is the whole integration for the bundled pair, and the remote one needs nothing at all. Never emit a <link> to a font host: the bundled faces would be duplicated over a network they do not need, and the remote face is already declared.

Two rules matter when generating markup:

  • Never assume a family has an italic. Check assets.fonts.items.<role>.variants before emitting italic text in that family - secondary and mono ship regular only, because neither face draws an italic, and a browser asked for one synthesises a slanted approximation instead.
  • Read source before promising a page renders offline. mono is fetched from Google's CDN, so code samples fall through to the system stack the token names after it when that request cannot be made. primary and secondary never leave the consumer's origin.

Trusting an item​

Every item carries the same keys, but canonical tells you how much to trust them:

  • canonical: true - Semetrika declares this item. Its label and description are authored, so description is what to read when choosing between icons.
  • canonical: false - the consuming project dropped the file in and rebuilt without registering it. It ships and renders, but its label is derived from its own id and description is null, so there is nothing authored to select on. Treat the id as the only signal.

The canonical example trio​

Every renderable component ships three canonical examples - empty, minimal, full - under components.<name>.examples. Read them in this order to understand a component:

ExampleWhat it showsHow the producer renders it
emptyThe component with no slot or prop fills. Some components render nothing (their twig guards on {% if content %}); others render the bare wrapper.No args passed to twig.
minimalThe structural skeleton: required slots and props only, plus any prop the author seeded with demo data. No value classes - capabilities are left unset.Producer fills required slots with placeholders and skips every visual capability.
fullEvery slot filled, every capability and every enum prop set to the next-on-ladder value past its default. Disambiguates every capability from its default in a single example.Producer auto-derives uses from the spec metadata; any authored uses on full is ignored.

Custom examples beyond the trio are allowed - components add them when a specific configuration needs to be demonstrated in isolation (e.g. a navbar with a megamenu layout).

Reading order for a cold-start session​

  1. overview - this document, inlined as a string.
  2. composeRules - the composition contract, inlined as a string.
  3. vocabulary - the canonical capability dictionary.
  4. components - per-component contracts, examples, JS behavior.

The tokens section is only needed when authoring foundation overrides; skip it for component-level markup generation. Read assets when emitting an icon, or when asking whether a typeface has the style you are about to use.

What this document deliberately does NOT contain​

  • Per-component examples (live in components.<name>.examples).
  • Per-component hook/state/event lists (live in components.<name>.capabilities.behavioral[] - hooks / states / emits / listens).
  • Token values (live in tokens).
  • The icon set and the shipped typefaces (live in assets.<group>.items).
  • Composition mechanics (live in llms-compose.md).

Reach for the structured sections of semetrika.spec.json for any of those. The two narrative documents are short by design.