@neolithic-css/framework

A fully configurable CSS utility framework written in Sass.

Installation

You can install it via npm 📦

npm i @neolithic-css/framework

Basic Usage

If you use Webpack's sass loader, just reference it using the ~ syntax 🤟🏼

Here is a simple example.

@use "~@neolithic-css/framework" as nc with
(
    $breakpoints: (
        xs: 320px,
        sm: 550px,
        md: 768px,
    ),
    $modules: [
        'grid',
        'spacing',
        'typography',

        // to config a module use this syntax 
        [ 'background/background-color', ( property-name-alias: bg ) ],
    ],
    $colors: [ 'black', 'white', 'gray', 'red' ],
    $extra-colors: (
        primary: #0667B7,
        blue: (
            50: #f7fafd,
            100: #eaf2f9,
        )
    ),
    $mobile-first: true,
);

@include nc.build;

Default Naming Convention

By default, the framework use the CSS property name as the class name.

For example:

.border-top\:5 {
  border-top: 5px solid !important;
}

.border-radius\:20 {
  border-radius: 20px !important;
}

Only for some frequently used utilities use shortened class name.

• background-color → bg
• text-align, text-transform, text-decoration, vertical-align → t
• font-size, font-style, font-wight → fz, fs, fw
• margin-top, margin-bottom, margin-left, margin-right → mt, mb, ml, mr
• padding-top, padding-bottom, padding-left, padding-right → pt, pb, pl, pr

You can change the class name by set the property-name-alias option for each module.

See here to understand the core concept of neolithic-css's naming convention.

Fluid utility

Fluid utility utilizes the calc() function to automatically change a CSS property from one value to another according to the viewport width.

For example:

<div class="fz:50~23 mb:90~20">Text</div>

The above example indicates:

• change font-size from 50px to 23px automatically
• change margin-bottom from 90px to 20px automatically

By default, the value changes from breakpoint lg to xs.
You can set the range via the start-shrinking-width and stop-shrinking-width in $fluid option.

Breakpoint utility

By using breakpoint utilities, you can apply a utility conditionally at different breakpoints.

For example:

<div class="mb:20@md">Text</div>

where mb:20@md means:

@media (min-width: 768px) {
    .mb\:20\@md {
        margin-bottom: 20px !important;
    }
}

Grid System

By using the grid-cols and col-span utility, you can create almost any responsive grid layout.

Just some examples:

<div class="d:grid grid-cols:3@md gap:40~10">
    <div>column 1</div>
    <div>column 2</div>
    <div>column 3</div>
</div>

<div class="d:grid grid-cols:4@md">
    <div class="col-span:1@md">column 1</div>
    <div class="col-span:3@md">column 2</div>
</div>

<div class="d:grid grid-cols:12@md grid-cols:9@sm">
    <div class="col-span:5@md col-span:3@sm">column 1</div>
    <div class="col-span:7@md col-span:6@sm">column 2</div>
</div>

Options

$breakpoints

The breakpoints for each utility.

Default Value

$breakpoints: (
    xs: 320px,
    sm: 550px,
    md: 768px,
    lg: 1024px,
    xl: 1256px,
    xxl: 1600px,
) !default;

$property-name-delimiter $query-delimiter

Default Value

See more details about the concept of these two options.

$property-name-delimiter: ':' !default;
$query-delimiter: '@' !default;

$mobile-first

Default Value

Determine if use mobile-first mode for media query.

$mobile-first: true !default;

$important

Determine if appends the !important to each utility.

Default Value

$important: true !default;

$modules

The modules to be included. You can find all the modules in the src/** directory.

Default Value

$modules: [ 'grid', 'spacing', 'typography', ] !default;

To config a module use this syntax :

$modules: [
  [ 'background/background-color', ( property-name-alias: bg ) ]
],

$colors

The colors variations for the utilities.

For example, if you have included the module background/background-color, and have the green included in the $colors.

Classes like bg:green.300 will be generated, the 300 is the level of the color.

The default colors are picked up from Material Design color palettes.

Default Value

$colors: [ 'white', 'black', 'gray', 'red', 'green', 'blue', ] !default;

$extra-colors

In addition to $colors, you can define your own colors with this option.

For example:

$extra-colors: (
    primary: #0667B7,
    blue: (
        50: #f7fafd,
        100: #eaf2f9,
    )
)

$fluid

Options for fluid utility.

Default Value

$fluid: (
    start-shrinking-width: default(map.get($breakpoints, lg), 1024px),
    stop-shrinking-width: default(map.get($breakpoints, xs), 320px),
    strip-unit: true,
    step: 10px,
    min: 0px,
) !default;