Fastcss — Config-driven SASS/SCSS Utility CSS Framework

What is fastcss #

A fully customizable, pure-SASS utility CSS framework. Generate only the classes you need from a single config map.

Fastcss generates helper classes at build time from a SASS $config map. The config controls colors, spacing scale, screen breakpoints, typography and more — so the final CSS only contains what you actually configured.

View on GitHub — fastcss/fastcss

Installation #

npm install fastcss
# or
yarn add fastcss

// Use default config
@use 'fastcss';

// Or supply your own config
@use 'fastcss' with ($config: $myConfig);

sass scss/build.scss dist/fastcss.css

Configuration #

All of fastcss is driven by a single $config Sass map. Copy node_modules/fastcss/scss/_config.scss into your project, trim it down to only what you need, and pass it to fastcss at compile time. Every value you add generates more CSS — keep the config lean and your output file will stay small.

Minimal config example

// _my-config.scss

$defaultConfig: (

  // ─── Typography ────────────────────────────────────────────────
  // Each key in font-size generates .fs-{key}, each weight generates .fw-{weight}.
  // More values = more classes = bigger file.
  'typography': (
    'font-family': (
      'base': "Roboto, -apple-system, sans-serif",
      'mono': monospace,
    ),
    'font-size': (
      'sm':   .875rem,   // → .fs-sm
      'base': 1rem,      // → .fs-base
      'lg':   1.25rem,   // → .fs-lg
      'xl':   1.5rem,    // → .fs-xl
    ),
    'font-weight': (400, 600, 700),  // → .fw-400 .fw-600 .fw-700
    'font-style':  (normal, italic),
    'line-height': (
      'base': 1.5,                   // → .lh-base
    ),
  ),

  // ─── Box / Spacing ─────────────────────────────────────────────
  // padding and margin lists are the actual values. stripunits:true removes
  // the px suffix from class names (e.g. p-10 instead of p-10px).
  'box': (
    'stripunits':   true,
    'padding':      (0, 5px, 10px, 15px, 20px),   // → .p-0 .p-5 .p-10 …
    'margin':       (0, auto, 5px, 10px, 20px),   // → .m-0 .m-auto .m-5 …
    'width':        (100%, 200px, 400px),          // → .w-100\% .w-200 …
    'height':       (100%, 40px),
    'positions':    (0, 5px, 10px),               // top/right/bottom/left helpers
    'z-index':      (1, 2, 99),
    'border-radius':(0, 4px, 50%),                // → .rad-0 .rad-4 .rad-50\%
    'border-width': (0, 1px, 2px),                // → .b-0 .b-1 .b-2

    // Named or numeric keys — key becomes the class suffix: bs-{key}
    // Add a named key for semantic aliases: hover:bs-card
    'shadow': (
      '0':    "none",
      '1':    "0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.24)",
      '2':    "0 3px 6px rgba(0,0,0,0.16), 0 3px 6px rgba(0,0,0,0.23)",
      'card': "0 2px 8px rgba(0,0,0,0.10), 0 1px 3px rgba(0,0,0,0.08)",
    ),
  ),

  // ─── Grid ──────────────────────────────────────────────────────
  // columns: number of grid columns.
  // screens: each breakpoint doubles the class count for every utility.
  // Remove breakpoints you don't need to reduce output size significantly.
  'grid': (
    'columns':   12,
    'gutter':    30px,
    'utilities': true,
    'screens': (
      'xs': 576px,
      'sm': 768px,
      'md': 992px,
      'lg': 1200px,
    ),
  ),

  // ─── Colors ────────────────────────────────────────────────────
  // Format: 'name:variant1,variant2,...': #baseHex
  // Each variant generates .name-text:variant, .name-fill:variant, .name-border:variant
  // plus all their responsive and state variants → colors are the biggest CSS cost.
  // 
  // Omit variants to generate only the base (500): 'white': #fff
  'colors': (
    'palette': (
      'transparent': transparent,
      'white':       #FFFFFF,
      'black':       #000000,
      'gray:300,500,700':         #9E9E9E,   // → .gray-text:300 .gray-fill:500 …
      'blue:100,300,500,700,900': #2196F3,   // → .blue-text .blue-fill .blue-border …
      'red:300,500,700':          #F44336,
    ),

    // Lightness/darkness adjustment per variant (positive = lighter, negative = darker)
    'variants': (
      '100': 70,
      '300': 30,
      '500': 0,    // base — no adjustment
      '700': -21,
      '900': -52.5,
    ),

    // Named or numeric gradient keys → grad-{key}
    'gradients': (
      '0':          linear-gradient(90deg, #2196F3, #9E9E9E),
      'blue-fade':  linear-gradient(180deg, #2196F3 0%, transparent 100%),
    ),
  ),

  // ─── Utilities ─────────────────────────────────────────────────
  'utilities': (
    'cursor':          ('pointer', 'default', 'grab', 'grabbing'),
    'text-decoration': ('none', 'underline', 'line-through'),
    'vertical-align':  ('middle', 'top', 'bottom'),
    'list-style-type': ('none', 'disc', 'decimal'),
  ),
);

How to use your config

// main.scss
@use 'my-config' as *;            // exposes $defaultConfig
@use 'fastcss' with ($config: $defaultConfig);

Responsive prefixes #

Almost every utility class is generated for each breakpoint defined in grid.screens. Prefix a class with {screen}: to apply it only at that breakpoint and above.

Text colors #

Format: {color}-text (base / 500 variant) or {color}-text:{variant}

Fill (background) #

Format: {color}-fill or {color}-fill:{variant}

Border colors #

Format: {color}-border or {color}-border:{variant}. Requires a border-width class (e.g. b-1) to be visible.

Gradients #

Format: grad-{key} — the key is defined in colors.gradients config. Use numeric keys for backwards compatibility and named keys for readability.

'gradients': (
  '0':            linear-gradient(...), // → .grad-0
  'blue-to-grey': radial-gradient(...), // → .grad-blue-to-grey
)

State variants are also generated: hover:grad-0, hover:grad-blue-to-grey, etc.

Color state variants #

All color classes (text, fill, border, gradients) are also generated for hover:, focus:, and active: states.

Font family #

Format: ff-{name}

Font size #

Format: fs-{key}

Font weight #

Format: fw-{weight}

Font style #

Format: fs-{style}

Line height #

Format: lh-{key}

Text utilities #

Responsive — all classes work with screen prefixes.

State variants available: hover:text-strike, hover:text-underline, hover:no-decoration

Padding #

Format: {direction}-{value}. Values from config: 0, 1, 2, 3, 4, 5, 10, 15, 20

Margin #

Format: m{direction}-{value}. Values: 0, 5, 10, 15, 20, 30, 40, auto

Border width #

Format: b{direction}-{value}. Values: 0, 1, 2, 3, 4. Combine with a {color}-border class to set the color — border-style is set automatically.

Directions

Widths

Combined directions with color

All border classes also work with responsive prefixes: sm:bl-2, md:b-0, etc.

Border radius #

Format: rad-{value}. Values: 0, 3, 5, 10, 50%

Width & Height #

Width values: 10, 15, 20, 1200, 100% — Height values: 10, 15, 20, 100%, 1

Positions #

Used with absolute / fixed / sticky. Values: 0, 5, 10, 15

Z-index #

Format: z-{value}. Values: -1, 1, 2, 3, 99

Box shadow #

Format: bs-{key} — the key is defined in box.shadow config. Use numeric keys for backwards compatibility and named keys for readability.

'shadow': (
  '0':    "none",                          // → .bs-0
  '1':    "0 1px 3px rgba(0,0,0,0.12)...", // → .bs-1
  'card': "0 2px 8px rgba(0,0,0,0.12)...", // → .bs-card
)

Material scale (bs-0 → bs-5)

State variants

Every shadow class is also generated for hover:, focus:, and active: states. Useful for interactive elements like cards and buttons.

<div class="bs-1 hover:bs-4">Card</div>
<div class="bs-0 hover:bs-card">Flat card</div>
<button class="bs-2 active:bs-0">Button</button>

Add any key to box.shadow in your config to generate a new bs-{key} class with state variants automatically included.

Flexbox — Display #

Flexbox — Direction #

Example: flex flex-col

Flexbox — Wrap #

Flexbox — Grow & Shrink #

Flexbox — Basis #

Flexbox — Justify content #

Flexbox — Align items #

Example: flex items-center

Flexbox — Align content #

Used with multi-line flex containers (flex-wrap).

Flexbox — Align self #

Applied to an individual flex child to override the parent's align-items.

Flexbox — Order #

Flexbox — Shorthand helpers #

Convenience classes that combine display + alignment in one.

Grid — Container #

container

Centered, max-width constrained per breakpoint. Resize the window to see it adapt.

<div class="container">
  <div class="row">
    <div class="xs:col-12 sm:col-3 md:col-2 lg:col-1">...</div>
    <div class="xs:col-6  sm:col-6 md:col-8 lg:col-10">...</div>
    <div class="xs:col-6  sm:col-3 md:col-2 lg:col-1">...</div>
  </div>
</div>

container-fluid

Always stretches to full width, only adds gutter padding on the sides.

<div class="container-fluid">
  <div class="row">
    <div class="xs:col-10 sm:col-6 md:col-8 lg:col-10">...</div>
    <div class="xs:col-2  sm:col-6 md:col-4 lg:col-2">...</div>
  </div>
</div>

Grid — Row #

Grid — Columns #

12-column grid. Responsive: prefix with xs:, sm:, md:, lg:.

<div class="row">
  <div class="col-12 sm:col-6 md:col-4 lg:col-3">...</div>
  <div class="col-12 sm:col-6 md:col-8 lg:col-9">...</div>
</div>

Grid — Offset, Push, Pull #

Grid — Row utilities #

Applied to a .row element to control alignment of its columns.

Utilities — Display #

All are responsive.

Utilities — Position #

All are responsive.

Utilities — Overflow #

Utilities — Float & Clear #

Utilities — Vertical align #

Format: va-{value}

Utilities — Group #

A horizontal flexbox row with no-shrink children. Useful for button groups, navbars, etc.

Utilities — List #

Utilities — Cursor #

Format: cursor-{value}

Utilities — State child/sibling toggles #

Toggle the display of all direct children or all siblings when the element enters a state.

Format: {state}:{target}-{display}

<div class="hover:child-block">
  Hover me
  <div style="display:none">
    Child visible on hover
  </div>
</div>

<input class="focus:sibling-flex" />
<div style="display:none">
  Sibling appears on focus
</div>

<div class="active:child-hide">
  <span>Click me</span>
  <span>Hidden on click</span>
</div>

<div class="hover:child-flex">
  Card content
  <div style="display:none">
    <!-- action buttons -->
  </div>
</div>

<span class="hover:sibling-block">
  Hover for tooltip
</span>
<div style="display:none">
  Sibling tooltip
</div>

<button class="active:sibling-flex">
  Press me
</button>
<div style="display:none">
  Shown while pressed
</div>