@zemax/mf-ui

Personal SCSS library: a toolkit of generic Sass functions/mixins (src/css/lib/) plus a small optional base theme built on top of it (src/css/1-base/, src/css/2-page-components/).

Purpose

The goal is to avoid starting from scratch on every project for recurring needs: px → rem/em conversion, mediaqueries for named breakpoints, a fluid flex grid, sprites, inline SVG icons generated on the fly (color set from Sass), accessibility helpers, button reset…

The repo is structured in two independent layers:

• src/css/lib.scss — the toolkit: only @function/@mixin/variables, no CSS output. Designed to be @use-able as-is in any project, with or without the rest.
• src/css/styles.scss — a demo/starter theme (reset, typography, forms, buttons, header…) that consumes the toolkit. This is what gets compiled into dist/css/styles.css.

Detailed documentation for each toolkit helper lives in docs/.

Installation

npm install

Build dependencies: Dart Sass, PostCSS + Autoprefixer, and @zemax/sass-svg for SVG inlining (see docs/svg-shapes.md and the .background-sprite-checkbox/.background-sprite-radiobox block in src/css/1-base/_forms.scss).

Build

npm run build:css    # compile src/css/styles.scss -> dist/css/styles.css (+ .map)
npm run watch:css     # rebuild automatically on every change under src/css/
npm run livereload    # serve dist/ with livereload (run alongside watch:css)

Using just the toolkit in another project

lib.scss re-exports (@forward) every module under src/css/lib/ without imposing anything visual. In a consuming project:

// Direct access, no prefix (equivalent to the old global @import behavior)
@use "<path-to>/mf-ui/src/css/lib" as *;

.card {
  padding: rem(16px);

  @include medium-or-more {
    padding: rem(24px);
  }
}

Or with a namespace (recommended to avoid collisions):

@use "<path-to>/mf-ui/src/css/lib" as tools;

.card {
  padding: tools.rem(16px);
}

Running the visual test (style guide)

tests/style-guide.html is a static page exercising the main theme components (headings, text, form, custom radios/checkboxes, burger menu) to visually confirm everything still renders correctly after a change.

1. Compile the CSS:

   npm run build:css

2. Open tests/style-guide.html in a browser.

Structure

src/
  assets/              SVG icons used by the checkbox/radiobox components
  css/
    lib.scss            toolkit entry point (@forward)
    lib/                 generic functions/mixins, no CSS output (see docs/)
    styles.scss          demo theme entry point (@use)
    1-base/               reset, colors, typography, forms, buttons…
    2-page-components/    page components (header)
dist/css/               compiled output (styles.css + .map)
tests/style-guide.html  manual visual check page
docs/                   detailed reference for the lib/ helpers