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.
| Type | What it is | Reach for it? |
|---|---|---|
| Foundation | Tokens (primitive, semantic), colors, typography scale, icons, options | No - substrate everything builds on |
| Utility | Grid, container, atomic CSS (.mt-4, .justify-center), JS helpers (collapsible, scrollspy) | Components use these internally |
| Component | Reusable UI building block (button, card, navbar, textfield) | Yes - what a page author places |
| Pattern | Composition 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:
| Capability | Sample values | Layer |
|---|---|---|
| Intent | info, warning, danger, success | intent |
| Emphasis | subtle, neutral, accent | emphasis |
| Fill | solid, outline, ghost | fill |
| Size | xs, sm, md, lg, xl | size |
| Shape | rounded, square, pill, circle | shape |
| Fit | cover, contain, fill | fit |
| Layout | fluid, contained, fullscreen | layout |
| Orientation | horizontal, vertical | orientation |
| Alignment | top, bottom, left, right, center | alignment |
| Position | sticky | position |
| Visibility | hidden, assistive, invisible | visibility |
| Motion | animated, still | motion |
| Elevation | flat, raised, elevated | elevation |
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
| Question | Look 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:
| Kind | Group | Address | Example |
|---|---|---|---|
sprite | icons | group path + # + item key | icons.svg#close |
collection | fonts | group path + item dir + the variant file | fonts/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.itemsand 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>.variantsbefore emittingsolid. 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:
| Role | Token | Face | Source | Weight axis |
|---|---|---|---|---|
primary | --font-family-primary | Plus Jakarta Sans | bundled | 200-800 |
secondary | --font-family-secondary | Outfit | bundled | 100-900 |
mono | --font-family-mono | Fira Code | remote | 300-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>.variantsbefore emitting italic text in that family -secondaryandmonoshipregularonly, because neither face draws an italic, and a browser asked for one synthesises a slanted approximation instead. - Read
sourcebefore promising a page renders offline.monois 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.primaryandsecondarynever 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. Itslabelanddescriptionare authored, sodescriptionis 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 itslabelis derived from its own id anddescriptionisnull, 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:
| Example | What it shows | How the producer renders it |
|---|---|---|
empty | The 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. |
minimal | The 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. |
full | Every 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
overview- this document, inlined as a string.composeRules- the composition contract, inlined as a string.vocabulary- the canonical capability dictionary.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.