MelangeCSS - Guide - Customizing

Overriding Custom Properties

Where possible, MelangeCSS uses CSS custom properties AKA variables. If you examine the top of melange.css, you can see these variables, and each one is documented in the reference.

To change these values, you can modify their values in CSS after where you have included MelangeCSS. Here is an example of how you might do that using the CDN install method:

<head>

  <!-- your head existing section -->

  <link rel="stylesheet"
        href="https://unpkg.com/melange-css@1.0.0-RC5/melange.min.css"/>
  <style>
    :root {
      --ff-sans: Avenir, Montserrat, Corbel, 'URW Gothic', source-sans-pro, sans-serif;
      --green-900: #e6ffe6;
      --green-600: #99ff99;
      --green-500: #009900;
      --green-400: #006600;
      --green-100: #003300;
    }
  </style>
</head>

As long as you re-assign the variables after including MelangeCSS, it will override the defaults. Note that this isn't specific al to this library—it's just how CSS and web browsers work.

Adding Your Own Classes

MelangeCSS doesn't come with every possible class for every possible combination of CSS properties and values. It comes with a reasonable basis for making most websites and apps, but your needs are different. If you want to make your own utility classes, and have them available for certain media queries and/or pseudo-selectors, you'd be in for a lot of copy and paste if MelangeCSS didn't include a command line tool to manage this for you!

To use the CLI tool, you'll need to install the melange-cli NPM package:

npm install --saveDev melange-cli

Next, create a .css file with the classes you need. This file can be regular CSS, but can also include two additional special forms that allow enhancement of existing properties. When you run the CLI, new CSS is generated based on the contents of this .css file and the media queries and/or psuedo selectors you configure.

/* Form 1 - regular CSS */
.text-shadow-1 {
  text-shadow: 1px 1px 2px var(--gray-500);
  /*
   * This class will be duplicated for each breakpoint and
   * psuedo-selector you specify on the command-line, using
   * MelangeCSS's naming scheme.
   */
}

/* Form 2 - exact selector from MelangeCSS */
.bg-red-500 /*
             * Since this class is part of MelangeCSS, MelangeCSS will
             * dupicate its definition for each media query and
             * psuedo-selector you specify on the command-line, using
             * MelangeCSS's naming scheme.
             *
             * This alleviates the need to re-state the definition of the class.
             */

/* Form 3 - wildcard match to selectors from MelangeCSS */
.bg-blue-* /*
            * Since this matches existing classes that are part of MelangeCSS,
            * it will dupicate its definition for each media query and
            * psuedo-selector you specify on the command-line, using
            * MelangeCSS's naming scheme.
            *
            * This alleviates the need to re-state the definition of the class.
            */

Use npx melange-css to generate a .css file with all the breakpoints and pseudo classes you want. For example, this would create classes for all three breakpoints, plus hover, plus, active pseudo classes.

npx melange-css \
      --input melange-input.css \
      --output melange-custom-classes.css \
      --mediaQuery ns \
      --mediaQuery m \
      --mediaQuery l \
      --pseudoSelector active \
      --pseudoSelector hover

Based on our input file above, this would create the following classes:

text-shadow-1: text-shadow-1, text-shadow-1-ns, text-shadow-1-m, text-shadow-1-l, active-text-shadow-1, active-text-shadow-1-ns, active-text-shadow-1-m, active-text-shadow-1-l, hover-text-shadow-1, hover-text-shadow-1-ns, hover-text-shadow-1-m, hover-text-shadow-1-l.
bg-red-500: active-bg-red-500. (hover-bg-red-500 is already defined)
bg-blue-*: active-bg-blue-100, active-bg-blue-200, active-bg-blue-300, active-bg-blue-400, active-bg-blue-500, active-bg-blue-600, active-bg-blue-700, active-bg-blue-800, active-bg-blue-900. (hover-bg-blue-* are already defined)

Use --help to see what media queries and pseudo-classes are avalable:

> npx melange-css --help
usage: npx melange-css [options]

OPTIONS

  -i/--input            - Input .css to process
  -o/--output           - Output .css (this is what your app will use)
  -q/--mediaQuery       - Media Queries to target in output (see values below)
                          [use multiple times for mulitple values]
  -p/--pseudoSelector   - Pseudo selectors to target in output (see values below)
                          [use multiple times for mulitple values]

MEDIA QUERIES

   ns - Not Small Width
        Screens that are larger than mobile sized
        @media screen and (min-width: 30em)

    m - Medium Width
        Screens larger than the mobile size but smaller than what is considered large (e.g. tablets)
        @media screen and (min-width: 30em) and (max-width: 60em)

    l - Large Width
        Screens larger than the medium size (e.g. desktops)
        @media screen and (min-width: 60em)

   dm - Dark Mode
        Prefers dark mode (light mode considered default)
        @media (prefers-color-scheme: dark)

   rm - Reduced Motion
        Prefers reduced motion (full/regular motion considered default)
        @media (prefers-reduced-motion: reduce)

   hc - High Contrast
        Prefers more contrast (Browser and HTML-configured contrast is the default)
        @media (prefers-contrast: more)

PSEUDO SELECTORS

       hover - Hover
               .some-selector:hover { ... }

      active - Active
               .some-selector:active { ... }

       focus - Focus
               .some-selector:focus { ... }

    disabled - Disabled
               .some-selector:disabled { ... }

       valid - Valid
               .some-selector:valid { ... }

     invalid - Invalid
               .some-selector:invalid { ... }

Example

Suppose you wish to create a green text glow style that works just like any other MelangeCSS class. You also want a style for green text that doesn't glow. You want both available for hover states and for high-contrast media queries. Following the naming conventions, you'd want the following classes:

green-text-glow: Applies the green glowing text
green-text-no-glow: Applies the green non-glowing text
hover-green-text-glow: Applies the green glowing text only on hover
hover-green-text-no-glow: Applies the green non-glowing text only on hover
green-text-glow-hc: Applies the green glowing text when higher contrast is preferred.
green-text-no-glow-hc: Applies the green non-glowing text when higher contrast is preferred.
hover-green-text-glow-hc: Applies the green glowing text only on hover when higher contrast is preferred.
hover-green-text-no-glow-hc: Applies the green non-glowing text only on hover when higher contrast is preferred.

This would allow you to write something like this:

<code class="green-text-glow green-text-no-glow-hc">
  console.log("Long live the fighters!")
</code>

For users who prefer higher-contrast, they will not see the glowing text, but everyone else will.

Do achieve this, you only need to write the un-prefixed classes. You'd create, say, melange-input.css like so:

.green-text-glow {
  color: #66ff22;
  text-shadow: rgba(230,255,130,0.61) 0px 0px 5px;
}

.green-text-no-glow {
  color: #88ff88;
}

Then, you can use npx melange-css to produce all the needed classes to include in your project:

npx melange-css --input melange-input.css \
                --output melange-custom-classes.css \
                --mediaQuery hc \
                --pseudoSelector hover

This would produce melange-custom-classes.css like so:

.green-text-glow {
  color: #66ff22;
  text-shadow: rgba(230,255,130,0.61) 0px 0px 5px;
}

.green-text-no-glow {
  color: #88ff88;
}

.hover-green-text-glow:hover {
  color: #66ff22;
  text-shadow: rgba(230,255,130,0.61) 0px 0px 5px;
}

.hover-green-text-no-glow:hover {
  color: #88ff88;
}

@media (prefers-contrast: more) {
  .green-text-glow-hc {
    color: #66ff22;
    text-shadow: rgba(230,255,130,0.61) 0px 0px 5px;
  }

  .green-text-no-glow-hc {
    color: #88ff88;
  }

  .hover-green-text-glow-hc:hover {
    color: #66ff22;
    text-shadow: rgba(230,255,130,0.61) 0px 0px 5px;
  }

  .hover-green-text-no-glow-hc:hover {
    color: #88ff88;
  }
}

You can target as many breakpoints and pseudo classes as you like. For example, if you also wanted the not small breakpoint as well as the focus pseudo-selector, you'd run this:

npx melange-css --input melange-input.css \
                --output melange-custom-classes.css \
                --mediaQuery hc \
                --mediaQuery ns \
                --pseudoSelector focus \
                --pseudoSelector hover

Run npx melange-css --help to see the complete list of media queries and pseudo selectors you can use.