Class prefix
Sépale's classes are plain: btn, chip, title. In a project that
already has a .title or a .chip of its own, the kit styles it by name. A Vite plugin shipped
in @sepale/components renames the kit's classes while the project builds, so the two never meet.
Turn it on
One line in the Vite config. The prefix is yours to choose, which is why it is applied while you build rather than shipped: nothing published carries it, and without the option nothing changes.
// vite.config.ts
import { sepale } from '@sepale/components/vite';
import { sveltekit } from '@sveltejs/kit/vite';
export default {
plugins: [
sepale({ prefix: 'sp', family: '@sepale/style/peony.css' }),
sveltekit()
]
};The project keeps importing the same stylesheet and the same components. The plugin renames both on their way through the build.
<script>
import '@sepale/style/peony.css'; // still the unprefixed file: the plugin renames it
import '@sepale/style/peony/themes/iris.css';
import { Button, Chip } from '@sepale/components';
</script>
<Button color="primary">Save</Button> <!-- renders <button class="sp-btn sp-btn-primary"> -->
<Chip>Draft</Chip> <!-- your own .chip is no longer the kit's -->Options
What is renamed
Classes, and only classes. The stylesheet and the components are renamed from the same list, the classes the family ships, so they cannot disagree.
- The family stylesheet, token by token. Comments, strings and
url()are left alone. - The components of
@sepale/components:classattributes and directives, the classes a component builds from its name (checkboxandcheckbox-primary), classes it tests or toggles, classes in the selectors it queries. - Not renamed: custom properties (
--btn-bg), keyframes, element selectors, attributes, and the classes of a library the kit only reaches into (air-datepicker).
.btn { … } .sp-btn { … }
.btn-primary { … } → .sp-btn-primary { … }
.toast.toast-top { … } .sp-toast.sp-toast-top { … }
--btn-bg: #fff; --btn-bg: #fff; /* a custom property is never renamed */So a theme, a background prop or a reset needs no change: they never named a class.
Your own markup
A class you write on an element, or hand to a component through class, chipClass or field, is the kit's own: it takes the prefix too. The types do not know the prefix. They narrow what a family
draws (color, size), not how a class is spelled.
<!-- Your own markup takes the prefixed names too --> <p class="sp-text-s2 sp-text-b1">Fixed price</p> <!-- and so does a class you give a component --> <Input class="sp-input-ghost" />
A family that is not in @sepale/style
family takes any stylesheet that follows the family contract, so a private family or one made on the family page is prefixed like the published ones. It is the plugin that reads it: the prefix is never part of
its build.
// A family that is not in @sepale/style: a private one, one built from a theme editor,
// one written by hand. Same option, any path.
sepale({ prefix: 'sp', family: '@acme/ui/acme.css' })
sepale({ prefix: 'sp', family: './src/styles/acme.css' })Another bundler
Only Vite has a plugin. The two functions behind it are exported, so any build step can do the same.
// Any other build tool: the plugin is a thin layer over two functions.
import { classesIn, prefixCss, prefixComponent } from '@sepale/components/prefix';
const css = readFileSync('peony.css', 'utf8');
const classes = classesIn(css); // what the family ships
writeFileSync('peony.sp.css', prefixCss(css, 'sp'));
// on every .svelte of @sepale/components, before Svelte compiles it:
const { code } = prefixComponent(source, 'sp', classes);Limits
- A rename is made on the syntax tree, so a class has to be written where it can be seen: a string in a class attribute, or in what the attribute reads. A class assembled elsewhere would be missed.
- That is checked on what ships:
pnpm run check:prefixrenders every component, every axis value and every flag through the plugin and fails on any class of a family that comes out unprefixed. - No source map for the renamed files: a rename moves columns on a line, never lines.
- The decisions are written down in ADR 0007 and ADR 0017.