MaverickWave

Using SCSS Source Files

For full customization, clone the repository and integrate the SCSS source directly into your project's Sass build (Dart Sass required). The entry point is src/scss/main.scss.

MaverickWave uses @use / @forward (modern Sass module syntax). Pass your overrides through @use ... with (...) - a plain assignment before the @use has no effect, because the root colors are declared with !default.

Theme Mode

Set $mw-theme-mode to control theme behavior:

• 'switchable' (default) - follows the OS; .mw-theme-light or .mw-theme-dark on <html> pins one side
• 'dark' - compile dark theme only
• 'light' - compile light theme only

Note: The main header and navigation always use the dark appearance regardless of theme mode.

Example - your main SCSS file

// styles.scss

@use 'path/to/maverick-wave/src/scss/main' with (
  // Theme mode (optional, default is 'switchable')
  $mw-theme-mode: 'switchable',

  // Root colors - everything else is derived from them at runtime
  $primary-color: #0f766e,
  $secondary-color: #b45309,
  $accent-text-color: #f2fafa,
  $dark-background: #172127,
  $light-background: #f2f6f7,
  $dark-text-color: #e8eef0,
  $light-text-color: #172127,

  // How far card and footer sit from the page background. Below 1 steps
  // toward black, above 1 toward white - 0.85 means the card sits at 85%
  // of the page's lightness.
  $card-surface-dark: 0.85,
  $card-surface-light: 1.05,
  $footer-surface-dark: 0.75,
  $footer-surface-light: 0.95
);

// Your additional styles
body {
  // custom overrides
}

Importing Only What You Need

Every layer forwards one module per file and no @extend crosses a file boundary, so components can be imported individually. Applications usually have no use for the marketing components (blog-post, gallery, content-slider, techstack-bucket, tiles, coming-soon, ratings, home).

// styles.scss - the configuration has to come first
@use 'maverick-wave/src/scss/abstracts/variables' with (
  $primary-color: #0f766e
);

@use 'maverick-wave/src/scss/base'; // required - carries the :root tokens
@use 'maverick-wave/src/scss/layout/grid';
@use 'maverick-wave/src/scss/layout/page-header';
@use 'maverick-wave/src/scss/components/buttons';
@use 'maverick-wave/src/scss/components/cards';
@use 'maverick-wave/src/scss/components/modals';
@use 'maverick-wave/src/scss/components/tables';
@use 'maverick-wave/src/scss/components/tags';
@use 'maverick-wave/src/scss/form-elements';
@use 'maverick-wave/src/scss/utilities';

Without base every component renders without colors - it carries the :root custom properties. A subset like the one above compiles to roughly 113 kB raw / 17 kB gzipped, against 281 kB / 40 kB for the full build.

Mixins and Functions

abstracts brings these into your own rules. They exist on the SCSS path only - the compiled CSS carries none of them.

• fluid($min, $max, $from: 'xs', $to: 'md') - a clamp between two sizes. Each end is a key of $font-sizes or a plain rem/px length, so a hero that does not sit on the scale still gets one. The rem term is the point: a vw-only clamp ignores the reader's font size. The default range stops at md, a headline passes $to: 'xl'.
• media-up($bp) / media-down($bp) - the $breakpoints map as a query.
• touch-context($bp: 'md') - coarse pointer or narrow viewport, the condition every target-size rule in the framework hangs under.
• touch-floor($size: 2.75rem) - that condition plus a min-height. Not for a link inside a sentence: WCAG 2.5.8 exempts those, and a min-height there pushes the lines of the paragraph apart.
• hit-area($grow: 6px) - grows the hit area through ::after without touching the silhouette, for a control whose size is the design. Neighbours need a gap of at least twice $grow, or two hit areas overlap.

@use 'maverick-wave/src/scss/abstracts' as *;

.hero h1 {
  font-size: fluid(1.95rem, 4.2rem, $to: 'xl');
}

.my-close-button {
  @include touch-floor;
}

Angular Integration

Download the compiled files and place them in your Angular project (e.g. src/assets/), then reference them in angular.json:

// angular.json
"styles": [
  "src/assets/maverick-wave.min.css",
  "src/styles.scss"
]

No "scripts" entry for the JS file. maverick-wave.min.js wires everything up once on DOMContentLoaded and writes straight into the DOM - in a SPA everything rendered afterwards stays uninitialized, and the class toggles happen behind change detection. Rebuild the behaviors in components; the state classes (mw-active, open, mw-selected) are the whole contract. A modal is the exception - write it as a <dialog class="mw-modal"> and the element brings Escape, the focus trap and the scroll lock with it.

Alternatively, use the CDN link directly in src/index.html:

<link rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/maverick-wave@6.6.0/maverick-wave.min.css">

For SCSS integration, use the npm package (or a local copy of src/scss/) from src/styles.scss:

// src/styles.scss
@use 'maverick-wave/src/scss/main' with (
  $primary-color: #3f51b5,
  $mw-theme-mode: 'switchable'
);

Theme switching

Light mode is one class on <html>. Keep it in a service so the choice survives navigation:

// theme.service.ts
readonly light = signal(localStorage.getItem('mw-theme') === 'light');

constructor() {
  effect(() => {
    const light = this.light();
    document.documentElement.classList.toggle('mw-theme-light', light);
    document.documentElement.classList.toggle('mw-theme-dark', !light);
    localStorage.setItem('mw-theme', light ? 'light' : 'dark');
  });
}

Reactive Forms

The mw-field wrapper groups label, control, hint and error. The control turns red by itself from Angular's ng-invalid ng-touched; the message is yours:

<div class="mw-field">
  <label class="mw-field-label mw-required" for="email">Email</label>
  <input id="email" type="email" class="mw-input" formControlName="email" />
  @if (email.invalid && email.touched) {
    <span class="mw-field-error">
      <i class="fas fa-exclamation-circle"></i> Please enter a valid email.
    </span>
  }
</div>

React Integration

Download the compiled CSS file and import it in your entry point, or use the CDN link in index.html:

// main.jsx / index.js
import './assets/maverick-wave.min.css';

Do not import maverick-wave.min.js in a SPA - it binds once on DOMContentLoaded and never sees anything rendered later. Accordion, tabs, modal and theme toggle are class toggles; bind them with className from state.

Example usage in a React component:

function App() {
  return (
    <div className="mw-container">
      <h1 className="mw-text-primary">Hello, MaverickWave!</h1>
      <button className="mw-btn mw-btn-primary">Get Started</button>
    </div>
  );
}

For SCSS integration with Vite, copy the source and import from your main stylesheet:

/* src/index.css or src/App.scss */
@use './maverick-wave/src/scss/main';