Architecture
This page describes how Semetrika is organized internally. You do not need to know any of this to consume Semetrika from a <link> tag - but you do if you plan to extend it, integrate it with a tool, or generate code against it.
Three load-bearing ideas: components are spec-driven, everything Semetrika ships belongs to one of four types, and mechanism rules govern the implementation.
Spec-driven components
Every component ships with a spec file alongside its CSS, Twig, and JS:
src/components/button/
├── button.css Component styles
├── button.variables.css Component tokens
├── button.twig Reference markup
├── button.stories.js Storybook stories
├── button.spec.js Public contract
├── button.spec.json Generated from the spec and the template
└── button.mdx Component docs
Button ships no JavaScript, because it needs none. A component that does adds a button.js alongside a mandatory button.test.js.
button.spec.js is the machine-readable public contract. It declares which canonical value classes the button opts into, which scalar props it accepts, which attributes its root accepts, and which slots the consumer fills in.
import { componentSpec, ComponentKind, slot, prop } from 'semetrika-spec';
import { Capability as c } from '../../../spec/spec.js';
export default componentSpec('button', {
kind: ComponentKind.component,
description: 'A button triggers an action or event.',
slots: [slot('content', { description: 'Visible button text.', required: true })],
props: [
prop.boolean('is_disabled', { description: 'Renders the disabled attribute.' }),
prop.array('classes', { description: 'Additional CSS class words merged into the root element.' }),
prop.object('attributes', { description: 'Additional HTML attributes spread on the root element.' }),
],
capabilities: [
c.Emphasis.use([c.Emphasis.subtle, c.Emphasis.neutral, c.Emphasis.accent], { default: c.Emphasis.neutral }),
c.Intent.use([c.Intent.info, c.Intent.warning, c.Intent.danger, c.Intent.success]),
c.Size.use([c.Size.xs, c.Size.sm, c.Size.md, c.Size.lg, c.Size.xl], { default: c.Size.md }),
c.Fill.use([c.Fill.solid, c.Fill.outline, c.Fill.ghost], { default: c.Fill.solid }),
],
});
Abridged - the shipped button.spec.js also declares type, is_loading, and the Layout, Shape, Elevation, and Motion capabilities.
One canonical source of truth drives every piece of tooling:
- Storybook controls are generated from the spec - the story file never re-lists which values exist.
- The lint CLI validates that the CSS only uses value classes the spec declares.
- The component class registry and capability vocabulary documents in the source repository are auto-generated from every spec at once.
- Code generation (and AI tooling) can read the spec to assemble valid markup without parsing the spec, the Twig, and the CSS separately.
There is no JSON Schema and no separate validator - the componentSpec() factory is itself the schema enforcer. Every declaration factory takes its name first and one options object after it, and construction-time validation throws a TypeError naming the call and the field that's wrong. That includes an option the factory doesn't read, so a misspelled key can't slip through unnoticed. A malformed spec fails the module load.
Foundation tokens (primitives, semantic tokens) ship as the same kind of spec, one level up. Every --space-*, --color-*, --component-* lives inside a typed TokenRegistry. The CSS, the Storybook reference pages, and the override tables on the Tokens page are all generated from the registries.
The four types Semetrika ships
Everything Semetrika exports - every token, every utility, every component, every pattern - belongs to exactly one of four types. The type determines where it lives in the sidebar, what consumers can do with it, and what the implementation rules require.
1. Foundation - the substrate
Tokens, colors, typography scale, icon library, options. Reference material that defines how Semetrika is themed. Foundations are not things consumers place on a page - they are the substrate everything else is built from.
| Foundation | What it is |
|---|---|
| Primitive tokens | Flat-scale values - font sizes, space, radius, transition. |
| Semantic tokens | Cross-component UI decisions - text color, surface, border, focus ring, typography bundles. |
| Options | Runtime feature flags (--option-animations, --option-rounded-corners). |
| Colors | Brand palette + generated steps. |
| Typography scale | The type ramp. |
| Icons | The shipped icon set and sprite generator. |
2. Utility - shipped infrastructure
Grid, container, scrollspy, collapsible, and atomic CSS helpers. Things components reach for, not things consumers place directly.
| Utility category | Examples |
|---|---|
| Layout scaffolding | grid, container |
| JavaScript behavior helpers | scrollspy, collapsible, close, loading |
| Atomic CSS classes | spacing (.mt-4), display (.block), flex (.justify-center), text (.text-center) |
A consumer building a page reaches for "a heading, a card, a navigation". They never say "I need a scrollspy here" - they say "I need a sticky header" and the header component uses scrollspy under the hood. That is the test: utilities are reached for by components, not by page authors.
3. Component - the reachable layer
A reusable building block of the user interface. Components are the things consumers reach for when assembling a page - a card, a button, a navigation, a textfield.
Components are defined by intent and reach, not by implementation. Whether a component is styled via an element selector, a component class, or a mirror class is an implementation detail. The classification as a Component depends on whether a consumer reaches for it when building a page.
Components ship as a flat list in the Storybook sidebar (no sub-groups), with form controls separated into their own top-level section because consumers reach for them as a set when building forms.
4. Pattern - compositions
A composition of components and utilities demonstrating real-world usage - "how do you build a contact form out of the form-control components?", "how do you lay a set of cards into a responsive grid?".
The full shipped set. The Utilities column lists structural layout utilities only - atomic helpers such as spacing and text alignment are used throughout and are not itemized.
| Pattern | Components | Utilities |
|---|---|---|
address-entry | form, fieldset, textfield, select, checkbox, button | - |
article-listing | collection, card | grid |
brands | image | list |
call-to-action | section, button | flex |
card-grid | collection, card | grid |
contact-form | form, fieldset, textfield, textarea, radio, checkbox, button | - |
faq | section, accordion | - |
feature-grid | collection, card, icon | grid |
login-form | form, fieldset, textfield, checkbox, button | - |
newsletter-signup | section, form, fieldset, textfield, checkbox, button | grid |
payment-form | form, fieldset, textfield, select, checkbox, button | - |
pricing-table | section, card, badge, button | grid |
signup-form | form, fieldset, textfield, checkbox, button | - |
stats-band | section | grid |
team-grid | collection, card, avatar, socials | grid |
testimonials | collection, card, avatar, blockquote | grid |
timeline-mission | section, timeline | - |
Patterns are reference assemblies that consumers copy and adapt; they are not reusable components to import directly.
The classification test
For any new thing being added to Semetrika:
- Is a consumer reaching for this when building a page? → Component
- Is this shipped infrastructure that components use internally (grid, container, JS helper, atomic CSS class)? → Utility
- Is this a composition of components and utilities showing a specific use case or full page assembly? → Pattern
- Is this reference material (tokens, colors, scale, icons) that defines how components look and behave at a base level? → Foundation
If none of the above, the thing is speculative or incorrectly scoped.
The rules system
The four-type framework decides what Semetrika ships. A parallel system of numbered rules decides how each part is built.
The rules are organized by mechanism. Each rule covers exactly one decision a contributor faces when implementing a component. They are short (one mechanism per file), interlinked, and authoritative - when a rule and an existing implementation disagree, the rule wins.
Rule groups:
| Group | Examples | What it governs |
|---|---|---|
| 1x - Markup | Rendering modes (classless vs mirror class), data attributes, accessibility. | What HTML a component emits, what attributes it carries. |
| 2x - CSS | Class structure and composition, capability vocabulary, tokens and options, state and color scheme, animations. | What CSS the component ships, which class words are allowed. |
| 3x - Twig | Prop naming, code formatting (header normalization, vertical attribute stacking). | How the Twig reference markup is shaped. |
| 4x - JavaScript | Progressive enhancement, unit tests, custom events, the JS spec contract, collection access. | What JS may do, what it must remain optional, how it binds. |
| 5x - Project | File structure, stories folder alignment, the component spec, prohibited words, workspace packages. | Where files live, how the spec is declared, which words are banned, how packages are imported. |
| 6x - Storybook | Stories, chrome levels, layout/component story conventions. | How stories are authored and how the canvas is dressed. |
The rule corpus lives in the contributor handbook. As a consumer you do not need them - but the capability vocabulary (Rule 22) and the token contract (Rule 23) are the surfaces you interact with through this docs site. See Vocabulary and Tokens.
Why this matters for AI integration
Three architectural choices make Semetrika friendly to LLM-driven code generation:
- Bounded vocabulary. The value list is small, named, and capability-scoped - the model emits
.danger,.outline,.smrather than memorizing a per-frameworkvariantmapping. - Semantic-first markup. The classless form is plain HTML. A model that knows HTML already knows how to emit a Semetrika page.
- Spec as source of truth. A model (or any tool) can read each
*.spec.jsto enumerate exactly what a component accepts. There is no second mental model to reconcile against the CSS.
This is architectural LLM-legibility - a property of how Semetrika is designed, present regardless of any AI tooling layered on top. Bolt-on tooling (llms.txt, MCP servers) is on the roadmap; the legibility is here already.