Build your first themed Krysalicss page

In about ten minutes you will produce a single static HTML file that uses Krysalicss for layout, typography, a card, and a button — and switches between light and dark themes without a page reload. Save the result and you have a working starting point for any project.

Prerequisites

This tutorial assumes:

  • You can open a terminal and run shell commands.
  • Node.js is installed (any version from 22 onward).
  • You have a text editor: anything from Notepad to Vim works.

You do not need:

  • A bundler, framework, or build tool beyond npx sass.
  • Prior Sass experience.
  • Any JavaScript framework.

Step 1: Create a project directory

Open a terminal anywhere you want a sandbox to live and run:

mkdir kc-tutorial
cd kc-tutorial
npm init -y

This creates an empty folder with a default package.json.

Step 2: Install Sass and Krysalicss

npm install --save-dev sass @adnap/krysalicss

Sass compiles your stylesheet; @adnap/krysalicss ships the framework's source. Both end up under node_modules/.

Step 3: Write a stylesheet

Create app.scss next to package.json:

// app.scss
// Pull the batteries-included entry: every component, light + dark themes.
@use '@adnap/krysalicss';

A single @use pulls every component plus the default light and dark themes. Themes are CSS custom property layers, so both can ship side by side at a small bundle cost.

Step 4: Compile to CSS

npx sass app.scss app.css

You should see app.css appear in the directory. Open it briefly: every component in the framework is in there, themed via :root { --kc-*: ...; } blocks.

Step 5: Write the HTML

Create index.html in the same directory. The file has three moving parts numbered in the comments: the inline theme bootstrap, the compiled CSS, and a tiny click handler.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Krysalicss tutorial</title>

    <!-- 1. Theme bootstrap (inline, runs before paint to avoid FOWT). -->
    <script>
      (function () {
        var stored = localStorage.getItem('theme');
        var prefersDark = matchMedia('(prefers-color-scheme: dark)').matches;
        if (stored === 'dark' || (!stored && prefersDark)) {
          document.documentElement.classList.add('theme-dark');
        }
      })();
    </script>

    <!-- 2. Compiled framework CSS. -->
    <link rel="stylesheet" href="app.css">
  </head>
  <body>
    <main class="container">
      <h1 class="title">Krysalicss is running.</h1>
      <p class="subtitle">A first themed page.</p>

      <div class="card">
        <h2 class="title">Hello, theme</h2>
        <p>
          This card uses <code>--kc-card-bg</code> and <code>--kc-card-fg</code>.
          Click the button below to switch themes: the card recolors
          without a reload.
        </p>
        <button class="button is-primary" id="toggle">Toggle dark theme</button>
      </div>
    </main>

    <!-- 3. The smallest possible theme switcher. -->
    <script>
      document.querySelector('#toggle').addEventListener('click', function () {
        var dark = document.documentElement.classList.toggle('theme-dark');
        localStorage.setItem('theme', dark ? 'dark' : 'light');
      });
    </script>
  </body>
</html>

Step 6: Open it

Double-click index.html in your file manager, or run npx serve in the project directory and open the URL it prints.

What you should see

Hello, theme

A page with a centered container, a heading, a subtitle, and a card with a primary button. The button toggles between light and dark on click; the choice persists across reloads via localStorage.

Step 7: Customise something

Open app.scss again and pass an override to the framework's @use:

// app.scss: same file, expanded
@use '@adnap/krysalicss' with (
  // Round all surface corners more aggressively.
  $global-border-radius: 10px,
);

Recompile and reload: every card, button, and surface now has rounder corners. Every !default variable in the codebase can be overridden the same way.

npx sass app.scss app.css   # rerun whenever app.scss changes

What you have now

A standalone, themeable, JS-light static page. From here: