Configuration

Before building pages, set the project’s typography, scaling, and component defaults to match the Figma design. The settings below show where to make those changes.

Typography

Match $type-scale in scss/00-sass/_variables.scss to the desktop and mobile typography variables in Figma.

Scaling

Check the mobile and desktop reference dimensions in scss/01-base/_scaling.scss. They default to 390px and 1440px wide.

Components

Set shared appearance and sizing once, then extend each component as needed. For buttons, use $btn-design and $btn-sizes.

Only what you need

Comment out unused forwards in the components and utilities entry files, then rebuild to omit their CSS.

Folder structure

Each layer builds on the one before it. Keep shared decisions near the top and project-specific styling in the layer that owns it.

postcss-pxv

kni-cascade comes bundled with pxv, our custom viewport unit. Write the size from your design, and kni-cascade scales it using the viewport and the active mobile or desktop settings.

You write

.card {
  padding: 24pxv;
}

PostCSS outputs

.card {
  padding: calc(24 * var(--pxv-unit));
}

Browser computes

One shared unit keeps every pxv value in proportion. The browser calculates the final size as the viewport changes. Here’s what that padding becomes at a few desktop widths:

Values are rounded to two decimal places. Standard px values stay fixed.

Breakpoints

One simple media query

One simple media query switches the site-basis settings that power scaling in kni-cascade. The site starts with its mobile basis settings, including a reference width of 390px. At $tm (768px by default), the query activates the desktop basis settings, including a reference width of 1440px. Typography switches between its mobile and desktop sizes at the same threshold by default.

That media query switches the design basis; pxv handles the sizes in between. Spacing, dimensions, and other pxv values scale together as the viewport changes, while typography follows its configured scaling and readability limits. Instead of repeatedly adjusting individual values across tablet, laptop, and desktop widths, you define the mobile and desktop compositions and let the shared scaling system carry them through each range.

Use @include sm and @include lg for structural changes at that same switch. With the defaults, sm applies below 768px and lg applies from 768px upward. For example, stack a feature on mobile and place its image and text side by side on desktop:

.feature {
  display: grid;
  gap: 24pxv;

  // Mobile: stack the image and text.
  @include sm {
    grid-template-columns: 1fr;
  }

  // Desktop: show two equal columns.
  @include lg {
    grid-template-columns: repeat(2, minmax(0, 1fr));
  }
}

The layout changes once, while the 24pxv gap scales within each range. Use the same mixins to change navigation or rearrange content, and add other media queries when the content needs them.

Advanced scaling settings

These defaults should work for most projects without adjustment. If you’re feeling ambitious, here’s what’s happening under the hood—and how to fine-tune the scaling for your design.

Edit the mobile and desktop CSS custom properties in scss/01-base/_scaling.scss; the primary media query activates the appropriate set.

Reference dimensions

--mobile-basis-w and --desktop-basis-w match the design widths: 390 and 1440 by default. Their height counterparts, --mobile-basis-h and --desktop-basis-h, default to 667 and 750. Reference height affects scaling only when squish is above zero. Enter these dimensions as unitless numbers.

Desktop squish

--desktop-squish defaults to 1. Normally, pxv scales from viewport width. When a desktop window is wide but short, width alone can make the composition too large for the available height. Squish lets the calculation switch to a viewport-height-based scale when that produces a smaller result. This helps a hero's typography, spacing, and imagery stay in proportion in a short laptop window.

How the switch works

At 1, the calculation uses whichever scale is smaller: viewport width relative to the reference width, or viewport height relative to the reference height. With the default desktop basis of 1440 × 750, a 1440 × 600 window produces a height-based scale of 0.8, so 100pxv becomes 80px. At 0, height has no influence and that same value stays 100px. Values between zero and one soften the height influence. Mobile defaults to width-only scaling.

Floor

--desktop-floor defaults to 500. Below that viewport height, the height calculation continues using 500px, preventing short windows from shrinking the composition indefinitely. This does not set a minimum page height. The mobile floor defaults to 0 and has no effect while mobile squish is zero.

Scaling limits

The active minimum and maximum clamp the scale to equivalent viewport widths. Mobile uses 0 through $tm - 1; desktop starts at $tm and caps at $desktop-max, which defaults to 1800. Set $desktop-max in scss/00-sass/_variables.scss to change that cap. Height influence can keep the scale below it. These limits constrain sizing without changing the layout breakpoint.

For example, reduce --desktop-squish if a wide, short window makes the composition feel too small. Raise --desktop-floor if you want the height-based shrinking to stop sooner. Use @include max for layout rules at and above $desktop-max.

Headers

heading--xxxl

heading--xxl

heading--xl

heading--l

heading--m

heading--s

heading--xs

heading--xxs

Body

body--l

body--l longform

body--m

body--m longform

body--s

body--xs

body--xxs

body--xxxs

Caps

Caps inherit their sizes from the corresponding body tokens in the shared type-scale() mixin. Combine caps with a body class such as body--m; update the body values in $type-scale to change both.

body--l caps

body--m caps

body--s caps

body--xs caps

body--xxs caps

body--xxs caps

Text helpers

Alignment

Apply alignment to a text element or its container.

Wrapping

Compare the same headline at equal widths. Balance aims for similar line lengths; pretty improves line breaks, including short last lines. Results depend on the font, available width, and browser support.

Longform reading

Use .longform to increase line-height to 1.5 for longer passages.

Font weight

Font-weight classes run from .w--100 through .w--900 in increments of 100. Load matching font weights for accurate results.

.w--100 — Thin text

.w--200 — Extra-light text

.w--300 — Light text

.w--400 — Regular text

.w--500 — Medium text

.w--600 — Semibold text

.w--700 — Bold text

.w--800 — Extra-bold text

.w--900 — Black text

[btn]

A shared starting point for consistent button sizing across projects. Make the appearance your own with project colors, spacing, hover effects, and animation. Extend [btn], or take just the sizing and build your own.

Make it yours

Set your project’s colors, corners, and spacing in scss/00-sass/_variables.scss. $btn-design controls appearance; $btn-sizes keeps responsive label sizes and padding together. Start with these defaults and adapt them to your design.

// Allow labels to grow beyond their configured mobile/desktop font sizes.
$btn-scale-up: false !default;

$btn-design: (
  radius: 999pxv,              // Corner radius; 999pxv creates a pill
  weight: 600,                 // Label font weight
  nudge: 0.01em,               // Optical vertical label adjustment
  gap: 0.5em,                  // Space between label and icon
  speed: 0.2s,                 // Color transition duration
  background: #001a3d,         // Default background and outline color
  text: #fff,                  // Default label color
  hover-background: #123456,   // Hover and pressed background
  hover-text: #fff,            // Hover and pressed label color
  focus: #0061c7               // Keyboard focus ring
) !default;

Adjust horizontal and vertical padding for each size separately. Height follows the label, line-height, and padding; no fixed or minimum button height is applied.

// padding-x = left/right; padding-y = top/bottom. Both follow the label size.
$btn-sizes: (
  xs: (desktop: 11, mobile: 10, padding-x: 1.5em, padding-y: 0.5em),
  s: (desktop: 12, mobile: 11, padding-x: 1.5em, padding-y: 0.625em),
  m: (desktop: 14, mobile: 12, padding-x: 1.5em, padding-y: 0.75em),
  l: (desktop: 16, mobile: 14, padding-x: 1.5em, padding-y: 0.75em)
) !default;

Usage

Bare btn defaults to medium. Add size and treatment tokens as needed.

<button type="button" btn="s">Small action</button>

Sizes

Use xs, s, m, or l. Each size controls typography and padding together. Labels use the desktop and mobile values in $btn-sizes, using the global --font-min-clamp minimum (12px in this demo). Button tokens start one step below their corresponding body tokens. The global minimum can make the smallest labels render at the same size; their padding still differs. By default, labels scale down but stop growing at their active mobile or desktop reference size. Set $btn-scale-up: true in settings to allow upward scaling.

Treatments

Set your button colors once. outline uses its background color for the stroke and label. inverted swaps background and text colors for dark surfaces, with a subtle hover tint derived from the same palette. Combine both treatments in either order; neither needs a separate settings map.

Links and full width

Use a real button for an action and an a with an href for navigation. Set type="button" for buttons that should not submit a form.

<button type="button" btn="l block">Full-width action</button>

Focus and disabled states

Tab to the examples to check the focus ring. Native disabled buttons cannot be activated and keep their disabled appearance on hover or press. aria-disabled="true" provides the same styling but does not prevent an action: projects must disable the underlying behavior too. This disabled link has no href.

Custom hover, same foundation

The default hover and pressed states change colors only. There is no built-in filter, movement, or decorative pseudo-element to undo. This project class adds its own animated fill while keeping btn="m" dimensions, focus, and disabled behavior. Reduced-motion preferences disable its movement.

<button type="button" btn="m" class="btn-demo-reveal">
  <span>Explore the details</span>
</button>

.btn-demo-reveal {
  --btn-bg: #172332;
  --btn-hover-bg: #172332;
  --btn-hover-border: #172332;

  position: relative;
  isolation: isolate;
  overflow: hidden;

  &::before {
    content: '';
    position: absolute;
    inset: 0;
    z-index: -1;
    background: #7c3aed;
    transform: translateX(-101%);
    transition: transform 350ms var(--easing);
  }


  &:where(:not(:disabled, [aria-disabled='true'])):focus-visible {
    &::before {
      transform: translateX(0);
    }

  }

  @media (hover: hover) {
    &:where(:not(:disabled, [aria-disabled='true'])):hover {
      &::before {
        transform: translateX(0);
      }

    }
  }

  @media (prefers-reduced-motion: reduce) {
    &::before {
      transform: none;
      transition: none;
    }
  }
}

Build on the foundation

Add a project class to override properties such as --btn-bg, --btn-hover-bg, --btn-radius, and --btn-weight. Or use the sizing mixin alone for a completely custom component.

To omit button CSS entirely, comment out @forward 'button' in scss/02-components/_index.scss.

Additional color themes are optional. Add an entry to $btn-themes only when the project needs another palette; the default empty map generates no extra theme selectors.

For a completely custom button, @include btn-size(m) supplies just font size and padding. Your component owns its appearance and interaction states.

@use 'kni-cascade/scss/00-sass' as *;

.custom-button {
  @include btn-size(m);
  // Add your project appearance and interaction styles.
}

Tables

Three starting points for native HTML tables. Add one class to choose a treatment; font and text color inherit from the surrounding content.

Minimal

Horizontal separators keep rows easy to follow.

<table class="table-min">...</table>

Bordered

A full cell grid with a lightly shaded header.

<table class="table-bordered">...</table>

Zebra

Alternating body rows help you scan across columns.

<table class="table-zebra">...</table>

Make it yours

Edit $table-design in scss/00-sass/_variables.scss for project defaults. Override inherited CSS variables on a section or table for a local treatment. Padding uses em so it follows the table’s font size.

.pricing {
  --table-padding-y: 1em;
  --table-scroll-background: #fff;
  --table-border: #bac8d3;
  --table-stripe-background: #f0f5f8;
}

On smaller screens

Wrap wide tables in .table-scroll to keep columns intact and allow horizontal scrolling. The examples above use the same wrapper. A focusable, labeled region lets keyboard users scroll it too. The CSS-only right-edge fade is enabled by default with mobile-overflow-scrim: true in $table-design. Set it to false to disable it. Wrap the scroller in .table-scroll-frame to apply the fade on mobile. It stays visible at the scroll end; omit the frame for tables that fit without scrolling. The fade defaults to 5% black; override --table-scroll-background to change its color. --table-scroll-fade-width controls its width.

<div class="table-scroll" role="region"
     aria-label="Project schedule" tabindex="0">
  <table class="table-min">...</table>
</div>

Include @forward 'tables'; in scss/02-components/_index.scss when the project needs these styles. Unclassed tables keep their existing appearance.

Forms

Sensible defaults for native form elements. Include @forward 'forms' in scss/02-components/_index.scss to use them, or comment it out to omit them. No styling attribute or JavaScript replacement is needed.

Make it yours

Edit $form-design in scss/00-sass/_variables.scss for project-wide appearance. Font family, weight, and text color inherit from the surrounding content. Controls use at least 16px text with font-relative padding; borders stay 1px. Layout and spacing between fields belong to your project.

// scss/00-sass/_variables.scss
$form-design: (
  radius: 4pxv,
  padding-x: 0.875em,
  padding-y: 0.4375em,
  background: #fff,
  border: #c5cbd1,
  muted: #68717e,
  accent: #001a3d,
  focus: #0061c7,
  error: #b42318
) !default;

Everyday controls

Inputs and selects share sizing. Textareas resize vertically. Checkboxes and radios use thin borders and a subtle 0.2-second selection animation, while keeping native keyboard and selection behavior. These examples are previews and do not send data.

<form class="contact-form">
  <label for="email">Email</label>
  <input id="email" name="email" type="email"
         autocomplete="email" aria-describedby="email-help">
  <p id="email-help" class="form-help">Use your work email.</p>
  <button type="submit" btn>Get in touch</button>
</form>

States

Use native disabled and readonly attributes. Mark an error with aria-invalid="true", explain it in text, and connect that message using aria-describedby. Validation timing and submission behavior remain your application's responsibility.

More native controls

Try these controls directly. Range, color, file, and date pickers retain their browser behavior. Their exact appearance can vary by browser and operating system.

Choice-control edge cases

Required fields and browser validation

Try submitting this preview empty, then fill it in. Native validation handles required fields and email format. Real projects supply submission and server-side validation; nothing here is sent.

One form, a different look

Override inherited --form-* variables on a form or wrapper. Low-specificity selectors make ordinary CSS overrides easy. The select's dropdown stays native; only its closed box is styled.

.contact-form {
  color: #172332;
  --form-bg: #fff9f7;
  --form-border: #963a30;
  --form-radius: 0;
  --form-accent: #963a30;
  --form-focus: #963a30;
}

Color, date, range, and file inputs keep their specialized native UI; this component does not replace browser pickers. Use --form-select-arrow to supply a different arrow image if needed.

.flex

Use class="flex" to create a flex container, then add modifier classes such as class="flex j-sb a-c column-mobile wrap".

Justification follows the main axis; alignment follows the cross axis. These axes swap when using a column. Modifiers ending in -mobile apply below the shared tablet breakpoint; -desktop modifiers apply at and above it.

Justification

class="flex j-start"

class="flex j-c"

class="flex j-end"

class="flex j-sb"

class="flex j-sa"

class="flex j-se"

Alignment

class="flex a-start"

class="flex a-c"

class="flex a-end"

class="flex a-baseline"

class="flex center"

Direction, wrapping, and inline display

class="flex column"

class="flex row-reverse"

class="flex wrap"

class="flex inline"

Responsive options — resize the window

Responsive modifier classes: wrap-mobile inline-mobile column-mobile column-mobile-reverse column-desktop row-reverse-desktop a-c-desktop a-start-desktop j-c-desktop j-sb-desktop j-end-desktop.

class="flex wrap-mobile"

class="flex inline-mobile"

class="flex column-mobile"

class="flex column-mobile-reverse"

class="flex column-desktop"

class="flex row-reverse-desktop"

class="flex a-c-desktop"

class="flex a-start-desktop"

class="flex j-c-desktop"

class="flex j-sb-desktop"

class="flex j-end-desktop"

Item options — apply to the child

grow fills available space, grow-0 disables growth, and no-shrink prevents shrinking. Use these modifiers with class="flex" on the child; it also becomes a flex container.

a-self-start a-self-c a-self-end position individual children.

Combine modifiers

class="flex j-sb a-c column-mobile"

[shadow]

Shadows add depth and help separate an element from its background. Use them on cards, menus, or floating controls to make the visual hierarchy clearer. Each preset combines multiple shadow layers for a soft falloff; elevation controls how lifted it feels, while intensity controls how dark it appears.

Layering a tight shadow with broader, softer shadows creates a more natural sense of depth than a single uniform blur. The presets balance those layers for you and provide a consistent set of shadows to reuse across a site, without tuning blur, spread, offset, and opacity for every component. They use standard CSS box-shadow underneath. Use a preset for a shared elevation level, or write your own box-shadow when a component needs a custom treatment.

Explore the shadow demo ↗

Combine elevation, intensity, and an optional color. Options can appear in any order.

<div shadow="20 .1 blue">A low blue shadow</div>

Elevation

10, 20, 30, 40, or 50, from a tight shadow to a broad, lifted shadow. These are preset names, not pixel measurements.

Intensity

.1 through .9, from lighter to darker. This sets the base opacity; individual shadow layers also apply weights, so it is not the final combined opacity.

Color

black by default. Add blue for the blue preset, or set style="--shadow-color: 120, 40, 90;" for a custom RGB color.

Hover only

use shadow-hover="30 .1". It also activates on keyboard focus for buttons and links.

Resting and hover

combine shadow="20 .1" with shadow-hover="50 .2". Hover settings override only the options supplied; omitted options retain the resting values.

Use shadow for a persistent shadow. Elevation presets run from 10 (tight) to 50 (broad). Bare shadow defaults to elevation 30 with intensity 0.08.

Elevation — same .1 intensity

Intensity — same elevation 20

Tokens .1 through .9 set the base alpha directly; each shadow layer also applies its own weight.

Defaults and color

Hover or keyboard focus

Hover these buttons or reach them with Tab. Their shadows fade in without changing layout. Reduced-motion settings disable the transition.

Resting shadow → hover shadow

These buttons already have a shadow. Hover or Tab to them to change elevation, intensity, and optionally color; move away to restore the resting settings.

Build shadows into a component

Use attributes for individual elements, or include the same styling in a component class. Import scss/00-sass for mixins without generating utility CSS. Omitted hover arguments retain the resting settings.

@use '../scss/00-sass' as *;

.mixin-shadow-card {
  @include shadow(20, 0.1);
  @include shadow-hover(30, 0.2);
}

.mixin-shadow-hover {
  @include shadow-hover(20, 0.2, (0, 20, 190));
}

[inset-border]

An inset border grows inward on hover or keyboard focus, over images and other content without changing layout. Use the attribute on individual elements or the mixin on a component class. The effect is invisible at rest.

Attribute on an image card inset-border

Mixin on a component class @include inset-border(5pxv, #a5106f);

Disabled — no effect inset-border disabled

<a class="news-card" inset-border href="/story">Read the story</a>

Set color, thickness, and duration on your component class. Defaults are currentColor, 5pxv, and 350ms. The overlay inherits the element's corner radius.

.news-card {
  border-radius: 12pxv;
  --inset-border-color: #2a649c;
  --inset-border-width: 5pxv;
  --inset-border-speed: 350ms;
}

Build it into a component

@use '../scss/00-sass' as *;

.news-card {
  @include inset-border(5pxv, #2a649c, 350ms);
  border-radius: 12pxv;
}

The effect reserves ::after and sets position: relative. Set your own positioning after the mixin or override the attribute rule if the host needs absolute, fixed, or sticky positioning. Use a block or inline-block host. The overlay ignores pointer events, preserves the host's own shadow, and disables its transition for reduced motion. Keep an accessible focus indicator; this decorative effect does not replace it.

To omit the attribute CSS, comment out @forward 'inset-border'; in scss/01-base/utilities/_index.scss. The mixin remains available through 00-sass.

Layout & visibility

.container

Centers content with mobile gutters and a desktop maximum width set by --container-size.

.desktop-only

Visible at and above the tablet breakpoint.

.mobile-only

Visible below the tablet breakpoint.

<div class="container">Centered content</div>
<p class="desktop-only">Desktop only</p>
<p class="mobile-only">Mobile only</p>

Hidden examples use display: none, so do not put essential information exclusively in one variant. The helpers switch at the shared tablet breakpoint (768px by default).

Images & positioning

Image fitting

Give the frame a height or aspect ratio, then choose how the image fills it.

Cover

Fill the frame; crop the edges.

Contain

Show the whole image; leave space as needed.

<figure class="fit-photo cover" style="aspect-ratio: 16 / 9;">
  <img src="photo.jpg" alt="Describe the image">
</figure>

Use .fit-photo.contain instead of .fit-photo.cover to preserve the entire image. Both work with direct child images and videos.

<div class="clip-container">
  <div class="clip-container__inner">Decorative content</div>
</div>

Colors

Color

.color--white

White text.

.color--black

Black text.

.background--white

White background.

.background--black

Black background.