stenfert-ui v1.2.0

Stenfert UI

Stenfert UI is a Tailwind CSS plugin for Svelte. 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

Setup

Creating a custom font

The fontFamily property in the theme object is a string. You can either use the name of a font that is already installed on the user's device or use the name of a custom font. This custom font must then be added to the configuration file.

A custom font is created like so:

// src/lib/ui/stenfert-ui.config.ts
import { createFont } from "stenfert-ui";

const myCustomFont = createFont({
    name: "Custom Font",
    source: "/path/to/my/custom-font.ttf",
});

Creating a theme

The example below 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.

A simple theme can be created like so:

// src/lib/ui/stenfert-ui.config.ts
import { createTheme, Color, generateForeground, generateSizeRange } from "stenfert-ui";

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(),
}

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"),
});

Configuring the plugin

Create a configuration file somewhere in the lib directory of your project. In the example, the file can be found at $lib/ui/stenfert-ui.config.ts. Add the following code to your config:

// src/lib/ui/stenfert-ui.config.ts
import { StenfertUIConfig } from "stenfert-ui";

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: {
        revealBody: false, // Remove the "hidden" class from the body element. This ensures the page is displayed after the styles are loaded.
        fallbackFontFamily: "sans-serif" // The font family to use if the custom font is not available.
    }
} satisfies StenfertUIConfig;

Registering the plugin

Add the following code to the tailwind.config.ts file:

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

export default {
    content: [
        "./src/**/*.{html,js,svelte,ts}"
    ],
    plugins: [
        stenfertUI(),
    ]
} satisfies Config;

Initializing the plugin

Add the following code to the root layout of your Svelte project:

<!-- src/routes/+layout.svelte -->
<script lang="ts">
    import { load } from "stenfert-ui";
    import config from "$lib/ui/stenfert-ui.config";
    import { onMount } from "svelte";

    onMount(() => {
        load(config);
    });
</script>

<slot />

Also, it is recommended to add the "hidden" class to the body in the app.html file. Paired with the option revealBody: true, this will ensure that the page is displayed after the styles are loaded.

Usage

Changing the site settings

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

import { 
    setSettings, 
    fontSizeStore, 
    lineHeightStore, 
    letterSpacingStore, 
    wordSpacingStore, 
    contrastStore 
} from "stenfert-ui";

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
});

fontSizeStore.set("1.5"); // Or $fontSizeStore = 1.5 in .svelte files;
lineHeightStore.set("1"); // Or $lineHeightStore = 1 in .svelte files;
letterSpacingStore.set("1"); // Or $letterSpacingStore = 1 in .svelte files;
wordSpacingStore.set("1"); // Or $wordSpacingStore = 1 in .svelte files;
contrastStore.set("0"); // Or $contrastStore = 0 in .svelte files;

Changing the theme

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

<script lang="ts">
    import { getThemes, setTheme, themeStore, themesStore } from "stenfert-ui";
    
    function changeTheme(themeName: string) {
        setTheme(themeName);

        themeStore.set(themeName); // Or $themeStore = "default" in .svelte files;
    }
</script>

<!-- Use themesStore over #getThemes(), because method may return empty array if config has not been loaded yet. -->
{#each $themesStore as theme}
    <button on:click={() => changeTheme(theme.getName())}>{theme.getName()}</button>
{/each}