Introduction
Semetrika is a classless-first CSS design system. Open an HTML file, write <button>Submit</button>, and it is already styled. No class is required. Semetrika's philosophy, architecture, and tooling all flow from that single starting point.
This page explains how Semetrika is built and why. The seven principles below shape every decision in the system. Once you understand them, the rest of the documentation - tokens, components, vocabulary, accessibility - lines up around them.
1. Classless first
The web platform already gives you semantic elements: <button>, <article>, <details>, <table>, <dialog>, <nav>, <a>. Each one means something. Semetrika's position is that when a semantic element exists for the thing you want to build, you use the element, not a class. <button> is the button component. <article> is the card component. <details> is the accordion component. No wrapping, no class decoration, no extra markup.
The result is that you can produce correct, accessible, styled UI with nothing but HTML. No class vocabulary to memorize, no build step to learn, no JavaScript to bootstrap. The primary styling mechanism is the element selector: button { ... }.
2. Mirror classes where classless is not feasible
Not every context gives you control of the HTML element. CMSes output <div>s. Frameworks render wrappers. Some components have no semantic element equivalent at all - a carousel, a badge, an alert. For those cases Semetrika provides mirror classes - explicit CSS classes that produce the same visual result as the classless form.
<button> is a button. <a class="btn" href="/launch"> renders identically - but it is still a link, and a mirror class never changes that. Use <button> for an action on the current page and an anchor for navigation; the mirror class only carries the appearance across. It is the fallback, not the default. Components that have no matching semantic element are class-only - they live as .message, .carousel, .badge and have no classless form.
Mirror class names describe the component role, not the HTML tag. Most mirror classes match the component name (.card for card, .accordion for accordion, .modal for modal). A few differ: .btn is the established short form for button, and .group is the mirror for <fieldset>. The component's own name is still the canonical one.
3. Composable values, no combinatorial explosion
Components vary along independent axes - intent, fill, size, shape, layout, orientation, spacing, position, visibility, motion, surface. Semetrika treats each axis as an independent value class that composes on any compatible component:
<button class="subtle outline sm">Cancel</button>
Three values from three capabilities. No .btn-subtle-outline-sm, no compound names. The CSS uses custom properties so combinations work automatically without needing selectors for every permutation.
The canonical list of value words - what .subtle means, what .outline means, what is allowed and what is not - lives on the Vocabulary page.
4. Tokens drive the look
Every visual decision - color, size, spacing, radius, line height, font - is a CSS custom property. A consumer site swaps tokens and every component adapts. Three tiers: primitives (raw values on a scale: --space-x-4, --color-primary-5), foundation tokens that reference primitives and are shared across components (--background-color-neutral, --component-padding-block-md), and component tokens that a component declares for itself (--btn-background-color, --card-padding). Components consume the upper two tiers, never primitives directly.
Runtime options (--option-animations, --option-rounded-corners, --option-elevation) sit alongside tokens as numeric on/off feature flags consumed via calc(). You toggle them at runtime without rebuilding CSS.
See Tokens for the full model and how to override values.
5. Twig as reference markup, not a required template
Every component ships with a Twig template ({name}.twig). The Twig file is not a required way to render the component. It exists because:
- Storybook. Twig lets Storybook render a component with different prop combinations and play with its state live. A parameterised Twig template is more tractable in Storybook than static HTML copies.
- Server-side rendering. Any consumer whose stack renders Twig can include the template directly, rather than reimplementing the markup. One folder holds a component's template, styles, and behavior, so the whole component moves as a unit.
- Reference markup. The Twig file documents the canonical HTML a component should produce. A consumer building a static site copies the rendered output; a consumer building a React app uses it as a reference for what classes and structure to emit.
Semetrika itself is CSS and JavaScript. The Twig layer is a rendering convenience - useful but not load-bearing. A consumer who never uses Twig still gets the full design system.
6. JavaScript as progressive enhancement
Every component is expected to work without JavaScript. JS adds behavior that the base HTML and CSS cannot express - exclusive mode on accordions, focus trapping in modals, tooltip positioning, carousel sliding, scroll-spy observation. When JS is absent, the component still renders and is still usable. JavaScript is optional, never foundational.
JavaScript binds to markup via data-* attributes, not class selectors. Classes are for styling; data attributes are for behavior.
7. One bundle, everything in it
Semetrika ships one CSS file and one JavaScript file. No per-component imports, no split by mode, no tree-shaking. You include the bundle - from the CDN, from a GitHub install, or by direct download - and every component is available.
This also means components may assume other components are present. A card inside a grid can rely on grid styles being loaded. A header can rely on scrollspy JS existing. There is no defensive inlining of dependencies from another component.
Putting it together
Those seven principles - classless-first, mirror-class fallback, composable values, token-driven theming, Twig as reference, JS as enhancement, single bundle - are the shape of Semetrika.
From them everything else follows:
- Glossary defines every term used in those principles.
- Architecture describes what Semetrika ships and how it is classified into Foundations, Utilities, Components, and Patterns.
- Installation, Tokens, Color schemes, and Extending walk through how to consume Semetrika in a real site.
Consumer vs generic design system
Semetrika is a generic design system: a complete, working, neutral substrate with no brand baked in. It ships sensible defaults, a bounded capability vocabulary, an accessible component library, and a token system - all designed to be overridden. The word generic here is positive: it means Semetrika makes no assumptions about whose product it ends up in. Drop the bundle into a static HTML page and you already have a styled, usable interface; the design decisions it ships are intentionally restrained so they get out of the way of yours.
A consumer design system is the brand-specific layer built on top: your tokens, your typography, your components, your patterns, your conventions. It belongs to one organization, one product, or one site - and it expresses opinions a generic system cannot. A consumer design system says this is what a button looks like on our site, these are the only colors we use, this is the card pattern our editors reach for. Industry vocabulary calls these brand-specific design systems (Material Design for Google, Polaris for Shopify, Carbon for IBM, GOV.UK for the UK government); inside Semetrika we use consumer because that is who builds and owns them.
The two sit at different layers and do different jobs. Semetrika is what you start from. The consumer design system is what you assemble on top - by overriding tokens, extending the capability vocabulary, adding components that belong to your domain, and composing patterns specific to your product. The Customization layers below describe the practical surface for that assembly, and Extending shows the techniques. The glossary entries for Generic design system and Consumer design system tie the two terms to their industry equivalents (skeleton and brand-specific).
Utility frameworks vs design systems
A common point of confusion is that the most-reached-for CSS frameworks - Tailwind, Bootstrap, Bulma - are not design systems. They are tools used to build one. Tailwind ships single-purpose utility classes (text-center, p-4) that compose into anything; Bootstrap ships pre-styled component classes (btn, card) that look like Bootstrap until you replace them. Both hand you raw materials. Neither makes the design decisions a design system makes.
A design system decides things on your behalf - what a button looks like at default size, which colors your site uses, which type ramp the page follows, which spacings repeat. It bundles tokens, components, patterns, accessibility, and conventions into a coherent whole a team can pick up and use without re-deciding the basics. A utility framework is the means; a design system is the end.
Semetrika sits at the design-system level, not the framework level. Roughly 80% of the design decisions are already made and 20% are left for the consumer to brand. Sensible defaults, a bounded capability vocabulary, an accessible component library, and a token system - everything in place and ready to be overridden. You can think of Semetrika as your consumer design system with most of the work already done, waiting for the brand layer.
Reach for a utility framework when you want a blank slate. Reach for a generic design system when you want the first draft already written. The glossary entries for Utility framework and Classful CSS framework place each category in the layered hierarchy.
Design systems in the AI age
LLM-driven coding tools have changed what building a site looks like. You can ask a model to scaffold a page, render a section, draft a component - and it will. But there is a recurring failure mode: the output drifts. One page looks fine. Two pages have slightly different spacing. Three pages have inconsistent buttons, mismatched type, three different ways of writing the same card. Across a full site the drift compounds into visible slop - the same model rendering the same general idea five different ways.
The root cause is the model's freedom. Without a constraint that says this is the button, this is the type ramp, these are the only colours, the model picks plausibly each time and picks differently each time. HTML and CSS alone leave too many degrees of freedom for consistent output across many prompts.
A design system is the constraint. A bounded capability vocabulary (.danger, .outline, .sm - finite, named, capability-scoped) gives the model a small palette to choose from. A semantic-first markup model (just emit <button>, <article>, <details>) lets the model lean on HTML it already knows from training data. A single token system means the model writes var(--text-color-neutral) rather than guessing a hex code that diverges from one page to the next.
Semetrika is built for this. Bounded vocabulary, semantic-first markup, a single token system, and a small enough surface area that an LLM can hold the relevant pieces in working context. The same property that makes a design system valuable to a team building many pages by hand - shared vocabulary, shared tokens, shared conventions - is what an LLM needs to keep its output coherent across many prompts. See Architecture > Why this matters for AI integration for the structural side of this, and the glossary entry for LLM-legibility for the term.
This is not a claim about which model is best, or about whether AI tools should be writing your code at all. It is a narrower claim: a design system contributes rails to AI-assisted work, not just paint.
Customization layers
Semetrika is built to serve the full range of consumers - from someone dropping in a single stylesheet link to a team building a complete design system on top of it. Six layers describe who the consumer is and what surface area Semetrika exposes for them:
| Layer | Persona | Entry point | What this user touches |
|---|---|---|---|
| 1. Drop-in | Prototyper, beginner, single-page-site author | One stylesheet link / one import | Semantic HTML only |
| 2. Token theme | Brand designer, themer (no build) | Small custom stylesheet overriding :root tokens | Documented brand tokens |
| 3. Class composition | Site builder, content team | HTML class attribute | Documented class vocabulary |
| 4. Custom CSS | Site theme author (small bespoke site) | Custom stylesheet consuming Semetrika tokens | Tokens at all tiers, cascade layers, extension hooks |
| 5. System extension | Design-system builder | New components, extended capability vocabulary, new patterns | Architectural rules, scaffolding, conventions |
| 6. Brand application | Site-specific theme | Token overrides + small component overrides on the system extension | Whatever Layer 5 exposes |
Because Semetrika must serve all six layers simultaneously, its vocabulary stays minimal but non-empty: small enough that Layer 5 can supplement, meaningful enough that Layer 1 has working defaults, and structured enough that a design-to-code workflow can rely on it.