Skip to main content

Extending

Once you are happy with the drop-in experience and your token overrides, you may want to go further: add consumer-specific components that feel native to Semetrika, override an existing component's appearance, add a brand-specific variant, or replace a component's JavaScript behavior. Together these techniques are the path to a consumer design system layered on top of Semetrika's generic substrate - your tokens, your components, your conventions, expressed in your own stylesheet rather than forked from the upstream bundle. This page covers each technique.

Build components against Semetrika's tokens​

The cleanest extension path is to write a regular CSS file that consumes Semetrika's tokens and ship your component as part of your own consumer stylesheet:

/* consumer.css */
.promo-card {
background: var(--background-color-subtle);
border-radius: var(--radius-md);
padding: var(--space-y-4) var(--space-x-4);
color: var(--text-color-neutral);
}

.promo-card h2 {
font-size: var(--heading-h3-font-size);
margin-bottom: var(--space-y-2);
}

Because your CSS uses the same tokens Semetrika uses, a brand swap in my-variables.css automatically re-themes both Semetrika's components AND your custom components. Add a :root[data-color-scheme='dark'] block in your token file and your components inherit dark-mode support for free.

Load order:

<link rel="stylesheet" href="semetrika.min.css" />
<link rel="stylesheet" href="my-variables.css" />
<link rel="stylesheet" href="consumer.css" />

Semetrika declares all of its design tokens in @layer tokens, the first and weakest layer in the bundle. Your my-variables.css overrides them with plain unlayered :root { --… } rules, which beat any layer - so a brand swap wins regardless of where the file sits in the load order, and even if you organize your own CSS into layers. See Tokens.

Override an existing component's appearance​

Write more-specific selectors in your own stylesheet:

/* consumer.css - make every card pill-shaped */
.card,
article {
border-radius: 9999px;
padding: var(--space-y-5) var(--space-x-5);
}

Because your stylesheet is unlayered, its declarations beat Semetrika's layered component rules regardless of load order. Use this sparingly - if you find yourself overriding many properties, you are probably better off adjusting tokens in your variables file (cheaper, theme-consistent, automatically applies to custom components too). See Tokens.

Add a variant using Semetrika's capability vocabulary​

Semetrika's capability vocabulary is shared across every component. Consumers can reuse vocabulary words in their own stylesheets for consistency:

/* consumer.css - a brand-specific intent for call-to-action buttons */
.btn.brand,
button.brand {
background: var(--brand-accent);
color: var(--brand-accent-on);
}

Note: brand is not in Semetrika's canonical capability vocabulary (see Vocabulary). Adding a word to your own stylesheet is fine for consumer-specific use, but if you find a pattern worth sharing, propose it upstream rather than diverging.

Create your own components​

Same approach as building components against tokens, but at a larger scope. Put all consumer components in a dedicated directory and one stylesheet:

your-site/
styles/
my-variables.css ← token overrides
components/
promo-card.css
newsletter-form.css
team-member.css
consumer.css ← imports all component files
index.html
<link rel="stylesheet" href="semetrika.min.css" />
<link rel="stylesheet" href="styles/my-variables.css" />
<link rel="stylesheet" href="styles/consumer.css" />

Conventions for consumer components​

Follow Semetrika's principles so everything in your site reads the same way:

  1. Use tokens, not hardcoded values. Every color, size, radius, and font should reference a var(--…). This keeps your components in sync with Semetrika's theme and lets brand swaps flow through your code automatically.
  2. Use Semetrika's capability vocabulary where it fits. If you need a "small" button, use .sm - do not invent .tiny. See Vocabulary.
  3. Use data attributes for JS behavior hooks. Do not bind JavaScript to classes. data-* attributes are the idiomatic binding mechanism in Semetrika.
  4. Keep component CSS standalone. No parent-dependent selectors. Each component should work anywhere in the DOM.
  5. Respect the classless-first principle. If a semantic HTML element covers your component, style it via the element selector first; add a mirror class only when consumers need to opt in from generic markup.

Semetrika's full set of mechanism rules is available in the contributor handbook. They are written for contributors to Semetrika itself, but they are equally useful as a style guide for consumer components.

Replace a component's JavaScript behavior​

If Semetrika's default JS behavior does not fit your use case, tear its enhancement down over the region you own, then remove the hook attribute so nothing re-binds it:

const region = document.querySelector('#my-region');

// Release Semetrika's listeners and observers within the region first.
window.Semetrika.destroyAll(region);

// Then remove the hook so the forward-binding observer does not re-enhance it.
region.querySelectorAll('[data-collapsible]').forEach((el) => {
el.removeAttribute('data-collapsible');
});

Order matters: removing the attribute first leaves the listeners allocated with nothing to tear them down. Attach your own behavior on a data attribute of your own, following the same lifecycle contract Semetrika's own modules use.

Accordions, and every other collapsible surface, are enhanced by the shared collapsible utility through [data-collapsible] rather than a per-component attribute - check the component's own .js file for the hook it registers before targeting one.

In practice this is rarely needed. Semetrika's behaviors are deliberately minimal, and most consumer needs are met by different markup, by toggling option flags, or by scoped token overrides.

When to upstream a change​

If you find yourself reaching for the same custom component, value, or token across multiple projects, that is a signal it belongs in Semetrika rather than in your consumer code. Open an issue on the GitHub repository and we can discuss whether the pattern fits Semetrika's vocabulary or whether a new capability needs to be defined.