@stenfert-ui/core v1.0.2

Stenfert UI

A Tailwind plugin to create themes and change styles at runtime. Its core features are:

• Register custom fonts.
• Create detailed themes in a simple manner.
• Switch between themes and change the site settings dynamically.
• Store the current theme and site settings in local storage.

Installation

npm install @stenfert-ui/core

Setup

Registering the plugin

To use the plugin with Tailwind V4, simply add the following line to your index.css file:

/* src/index.css */
@plugin "@stenfert-ui/core";

If you are using Tailwind V3, you can add the plugin to your tailwind.config.ts file like this:

// tailwind.config.ts
import type { Config } from "tailwindcss";
import stenfertUI from "@stenfert-ui/core";

export default {
    plugins: [
        stenfertUI,
    ]
} satisfies Config;

Configuring the plugin

The configuration file must be accessible during runtime. In this example the file is located at src/stenfert-ui.config.js, but you can place it anywhere in your project.

An empty configuration file looks like this:

// src/stenfert-ui.config.js
import { StenfertUIConfig } from "@stenfert-ui/core";

export default {
    defaultTheme: "default", // The name of the default theme. This name must match the name of a theme in the themes array.
    fonts: [], // An array of custom fonts.
    themes: [], // An array of themes.
    options: {
        fallbackFontFamily: "sans-serif" // The font family to use if the custom font is not available.
    }
} satisfies StenfertUIConfig;

Adding custom themes

A simple theme can be created like this:

// src/themes/default-theme.js
import { createTheme, Color, generateForeground, generateSizeRange } from "@stenfert-ui/core";

const colors = {
    surface: Color.ofHex("#eeeeee").getShades(),
    primary: Color.ofHex("#0041c2").getShades(),
    secondary: Color.ofHex("#371f76").getShades(),
    tertiary: Color.ofHex("#90e4c1").getShades(),
    success: Color.ofHex("#22bb33").getShades(),
    warning: Color.ofHex("#f0ad4e").getShades(),
    danger: Color.ofHex("#bb2124").getShades(),
    debug: Color.ofHex("#5bc0de").getShades(),
}

export const myDefaultTheme = createTheme({
    name: "default",
    colors: {
        background: colors,
        foreground: generateForeground(colors),
    },
    borderWidth: "2px",
    borderRadius: "8px",
    fontFamily: "Arial",
    fontSize: generateSizeRange("1rem"),
    lineHeight: generateSizeRange("1rem"),
    letterSpacing: generateSizeRange("0.035rem"),
    wordSpacing: generateSizeRange("0.035rem"),
});

The example above makes use of the methods #generateSizeRange, #generateForeground and Color#getShades to create a theme.

In case you would like to assign specific values to the shades of the foreground and background colors, and the size ranges, you can replace those methods and define the values manually.

To include your theme in your project, import the theme file in your configuration file and add it to the themes array:

// src/stenfert-ui.config.js
import { StenfertUIConfig } from "@stenfert-ui/core";
import { myDefaultTheme } from "./themes/default-theme.js";

export default {
    defaultTheme: "default", // The name of the default theme. This name must match the name of a theme in the themes array.
    fonts: [], // An array of custom fonts.
    themes: [ myDefaultTheme ], // An array of themes.
    options: {
        fallbackFontFamily: "sans-serif" // The font family to use if the custom font is not available.
    }
} satisfies StenfertUIConfig;

Using a custom font

To use a custom font in your themes, you must first register the custom font inside your configuration file.

Assuming the assets/fonts directory contains a custom font called "MyCustomFont.ttf", you can register the font like this:

// src/stenfert-ui.config.js
import { StenfertUIConfig } from "@stenfert-ui/core";
import { myDefaultTheme } from "./themes/default-theme.js";
import { createFont } from "@stenfert-ui/core";

const myCustomFont = createFont({
    name: "Custom Font",
    source: "/assets/fonts/MyCustomFont.ttf",
});

export default {
    defaultTheme: "default", // The name of the default theme. This name must match the name of a theme in the themes array.
    fonts: [ myCustomFont ], // An array of custom fonts.
    themes: [ myDefaultTheme ], // An array of themes.
    options: {
        fallbackFontFamily: "sans-serif" // The font family to use if the custom font is not available.
    }
} satisfies StenfertUIConfig;

To use it in your themes, simply pass the name of your custom font to the fontFamily property of the theme.

Loading the plugin

The plugin can be loaded via the load method:

<!-- src/index.html (from Tailwind installation: https://v4.tailwindcss.com/docs/installation) -->
<!doctype html>
<html>
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <link href="/src/index.css" rel="stylesheet">
    </head>
    <body>
        <h1 class="text-3xl font-bold underline">
            Hello world!
        </h1>
    </body>
    <script defer type="module">
        import { load } from "@stenfert-ui/core";
        import config from "./stenfert-ui.config.js";

        load(config);
    </script>
</html>

If you use one of the framework specific packages, call the load function inside the root layout, and once the component has mounted. See the READMEs of the framework projects for their specific implementations.

Usage

Changing the site settings

The font size, line height, letter spacing, word spacing and contrast can be requested and changed dynamically during runtime. This can be done with the following methods:

import { 
    getSettings,
    setSettings
} from "@stenfert-ui/core";

console.log(getSettings()); // { fontSize: "1", lineHeight: "1", letterSpacing: "1", wordSpacing: "1", contrast: "0" }

setSettings({
    fontSize: "1.5", // Range from 0 to Number.MAX_SAFE_INTEGER
    lineHeight: "1", // Range from 0 to Number.MAX_SAFE_INTEGER
    letterSpacing: "1", // Range from 0 to Number.MAX_SAFE_INTEGER
    wordSpacing: "1", // Range from 0 to Number.MAX_SAFE_INTEGER
    contrast: "0", // Range from -1 to 1
});

These settings are multipliers and will be multiplied against the theme's values.

Changing the theme

The theme can be changed dynamically during runtime. This can be done with the following method:

import { getActiveTheme, getThemes, setActiveTheme } from "@stenfert-ui/core";

const themes = getThemes(); // Returns an array of all themes.
const theme = themes[0]; // Let's say we want to set the active theme to the theme at index 0.

setActiveTheme(theme.getName()); // Set the active theme to the theme at index 0.
console.log(getActiveTheme()); // Prints the theme at index 0.

The method #getThemes() may return an empty array at first. This is because the plugin has not yet loaded. You could listen to the events 'plugin-loaded' and 'theme-added' from the eventBus to update your array.

In the framework specific packages, this is done using reactive stores. See their READMEs for more information.