Skip to main content

Vocabulary

Semetrika curates a deliberately short class vocabulary. This page explains the philosophy behind that choice. The exhaustive list of canonical value words organized by capability lives on the auto-generated Capability vocabulary page.

Why a short vocabulary​

Three properties matter for a design-system class vocabulary - composability, predictability, and an upper bound on the surface area authors and tools have to learn. Semetrika solves all three by naming capabilities explicitly and keeping the words on each capability to a small, memorable set.

Composability beats combinatorial explosion​

A button can vary along several independent axes - how prominent it is (emphasis), how it fills its background (fill), how big it is (size), what shape its corners take (shape), how it animates (motion). If you encode every combination as a dedicated class, you get .btn-subtle-outline-sm-rounded-still and dozens of cousins. The CSS file grows combinatorially and authors have to memorize the exact name of every permutation.

Semetrika treats each axis as an independent value class that composes on the same element:

<button class="subtle outline sm rounded still">Cancel</button>

Five values from five capabilities. No compound names. The CSS uses custom properties so combinations work automatically - no selector is needed for every permutation.

Predictability beats per-component vocabulary​

Many frameworks let each component define its own variant vocabulary. A button might have variant="ghost"; a card might have variant="elevated"; an alert might have variant="warning". Three components, three different meanings of the same prop name. An author moving between components has to relearn what variant controls each time.

Semetrika defines a shared vocabulary across components. .outline always means "bordered, transparent background". .sm always means "small". .danger always means "destructive / error". When a component opts into a capability, it picks from the canonical list of words for that capability - it does not invent new ones.

An upper bound on what you have to learn​

The canonical capabilities are about a dozen. The words per capability are 2-7. The whole vocabulary fits on one screen. A new contributor (or a new AI tool generating Semetrika markup) can hold the entire surface area in their head.

Per-component differences exist - a button does not need .assistive from the Visibility capability; an avatar does not need a .flush spacing value. But the words available to a given component are always a subset of the canonical list. There is no surprise vocabulary on any single component.

Why this is friendly to LLM-driven code generation​

A model generating Semetrika markup picks from a small, named, capability-scoped set rather than memorizing a per-framework variant mapping. The class .outline is self-describing - it refers to a capability (Fill) whose values are visible on every other component the model has seen. Compare to variant="contained" which only makes sense if the model has memorized that this particular framework happens to use variant for the Fill axis and contained for solid fill.

See the Glossary for the variant-vs-value discussion in depth.

The canonical capabilities​

Semetrika names a small set of capabilities; each has a few allowed words. The full list with every word, label, and description is on Capability vocabulary, auto-generated from the spec system.

The capabilities are: Alignment, Elevation, Emphasis, Fill, Fit, Intent, Layout, Motion, Orientation, Position, Shape, Size, Visibility.

Per-component subsets​

A component opts into the capabilities it supports and the words on each capability it accepts. For example, the button component opts into Fill, Size, Shape, Layout, Motion, Elevation, Emphasis, and Intent - but not Visibility. Putting .assistive on a button is meaningless (the component does not opt into that capability) and will not be styled.

The full per-component class signature - root class, every value the component opts into with its capability, the sub-element classes its CSS exposes, the slots its spec declares - is on the auto-generated Component classes page.

Custom values​

A handful of components ship custom values that fall outside the canonical capabilities because the concept is specific to that one component. Examples:

  • .flush on accordion, fieldset, table, grid - removes internal padding or gap. There is no canonical zero-value value across the capabilities because most components do not need one.
  • .thumbnail on attachments - editorial type that attaches a preview image to each file instead of a file-type icon.
  • .mega, .mega-full on navbar - megamenu layouts.

The full list, grouped by component, is documented under "Component custom values" on the Capability vocabulary page. They are intentionally rare - if multiple components share a concept, it gets promoted to a canonical capability instead.

Utility classes​

Atomic utility classes (.mt-4, .justify-center, .text-uppercase, .col-md-6) live in the Utilities section of Storybook. They are different from component values - they are designed to be reached for by components, not placed by page authors directly. The full inventory is in the "Utility classes" section of the Capability vocabulary page. See Architecture for the four-types framework that places utilities, components, foundations, and patterns.