CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-polished

A lightweight toolset for writing styles in JavaScript with Sass-style helper functions and mixins.

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

math.mddocs/

Math Functions

CSS unit-aware mathematical calculations with support for complex formulas, mixed units, and mathematical operations designed for responsive design and design systems.

Capabilities

Mathematical Formula Evaluation

Function for performing mathematical calculations with CSS units and values.

/**
 * Helper for doing math with CSS units. Accepts a formula as a string and evaluates it.
 * @param formula - Mathematical formula as string with CSS units
 * @param additionalSymbols - Optional object with additional variables/symbols
 * @returns Calculated result as string with appropriate unit
 */
function math(formula: string, additionalSymbols?: Object): string;

Supported Operations

The math function supports the following mathematical operations:

  • Addition: +
  • Subtraction: -
  • Multiplication: *
  • Division: /
  • Square root: sqrt()
  • Power/Exponentiation: ^ or pow()
  • Factorial: !
  • Minimum: min()
  • Maximum: max()
  • Parentheses: () for grouping

Supported CSS Units

The math function can work with any CSS unit:

  • Absolute units: px, pt, pc, in, cm, mm
  • Relative units: em, rem, ex, ch, vh, vw, vmin, vmax
  • Percentage: %
  • Unitless values: Numbers without units

Usage Examples

Basic Calculations

import { math } from "polished";

// Simple arithmetic with units
const width = math("100px + 50px");           // "150px"
const height = math("100vh - 80px");          // "calc(100vh - 80px)"
const fontSize = math("16px * 1.5");          // "24px"
const margin = math("40px / 2");              // "20px"

// Mixed unit calculations (automatically uses calc())
const responsiveWidth = math("50% + 20px");   // "calc(50% + 20px)"
const fluidHeight = math("100vh - 3rem");     // "calc(100vh - 3rem)"

Complex Formulas

import { math } from "polished";

// Responsive grid calculations
const columnWidth = math("(100% - 60px) / 4");        // "calc((100% - 60px) / 4)"
const gutterSize = math("20px * 1.5");                // "30px"

// Typography calculations
const lineHeightCalc = math("24px * 1.4");            // "33.6px"
const typeScale = math("16px * pow(1.25, 3)");        // "31.25px"

// Layout spacing calculations
const containerPadding = math("max(20px, 5vw)");      // "max(20px, 5vw)"
const verticalRhythm = math("24px * 2 + 16px");       // "64px"

// Advanced mathematical operations
const goldenRatio = math("(1 + sqrt(5)) / 2");        // "1.618033988749895"
const circleArea = math("pow(10px, 2) * 3.14159");    // "314.159px"

Custom Variables and Symbols

import { math } from "polished";

// Define custom variables
const designTokens = {
  baseFont: "16px",
  baseSpacing: "8px",
  ratio: 1.25
};

// Use custom variables in calculations
const headingSize = math("baseFont * pow(ratio, 3)", designTokens);    // "31.25px"
const largeSpacing = math("baseSpacing * 4", designTokens);            // "32px"
const responsiveFont = math("baseFont + 2vw", designTokens);           // "calc(16px + 2vw)"

// Complex design system calculations
const modularSpacing = math("baseSpacing * pow(2, 3)", designTokens);  // "64px"
const fluidType = math("baseFont + (24px - baseFont) * (100vw - 320px) / (1200px - 320px)", designTokens);

Responsive Design Patterns

import { math } from "polished";

// Fluid grid system
const createFluidGrid = (columns, gap = "20px") => ({
  width: math(`(100% - ${gap} * ${columns - 1}) / ${columns}`),
  marginRight: gap,
  "&:nth-child(${columns}n)": {
    marginRight: 0
  }
});

// Responsive container widths
const containerSizes = {
  small: math("min(90%, 600px)"),      // "min(90%, 600px)"
  medium: math("min(85%, 900px)"),     // "min(85%, 900px)"
  large: math("min(80%, 1200px)")      // "min(80%, 1200px)"
};

// Aspect ratio calculations
const aspectRatio = (width, height) => ({
  width: "100%",
  height: 0,
  paddingBottom: math(`${height} / ${width} * 100%`)
});

// Usage
const videoAspect = aspectRatio("16", "9");  // 16:9 aspect ratio

Design System Integration

import { math } from "polished";

// Spacing scale based on mathematical progression
const spacingScale = {
  xs: math("4px * 1"),         // "4px"
  sm: math("4px * 2"),         // "8px"  
  md: math("4px * 4"),         // "16px"
  lg: math("4px * 6"),         // "24px"
  xl: math("4px * 8"),         // "32px"
  xxl: math("4px * 12")        // "48px"
};

// Typography scale with mathematical ratios
const createTypeScale = (baseSize = "16px", ratio = 1.25) => {
  const symbols = { base: baseSize, r: ratio };
  
  return {
    xs: math("base / pow(r, 1)", symbols),    // Smaller text
    sm: math("base / pow(r, 0.5)", symbols),  // Small text
    base: math("base", symbols),              // Base text
    lg: math("base * pow(r, 1)", symbols),   // Large text
    xl: math("base * pow(r, 2)", symbols),   // Extra large text
    xxl: math("base * pow(r, 3)", symbols)   // Heading text
  };
};

// Border radius scale
const borderRadiusScale = {
  sm: math("2px * 1"),         // "2px"
  md: math("2px * 2"),         // "4px"
  lg: math("2px * 4"),         // "8px"
  xl: math("2px * 6"),         // "12px"
  full: "50%"
};

Error Handling

The math function will:

  • Return CSS calc() expressions when mixing incompatible units
  • Preserve units when performing operations on compatible units
  • Handle division by zero gracefully
  • Maintain precision for decimal calculations
import { math } from "polished";

// Compatible units are calculated directly
const samePx = math("100px + 50px");           // "150px"

// Incompatible units use calc()
const mixedUnits = math("50% + 100px");        // "calc(50% + 100px)"

// Complex expressions with calc()
const complexCalc = math("(100vw - 40px) / 3 + 2rem");  // "calc((100vw - 40px) / 3 + 2rem)"

Install with Tessl CLI

npx tessl i tessl/npm-polished

docs

color.md

easings.md

helpers.md

index.md

math.md

mixins.md

shorthands.md

tile.json