or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

breakpoints.mdcontainers.mdindex.mdscss-api.mdspacing.mdunit-conversion.md
tile.json

tessl/npm-carbon--layout

Layout helpers for digital and software products using the Carbon Design System

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@carbon/layout@11.19.x

To install, run

npx @tessl/cli install tessl/npm-carbon--layout@11.19.0

index.mddocs/

@carbon/layout

@carbon/layout provides comprehensive layout utilities for building consistent and responsive designs using the Carbon Design System. It offers both JavaScript and SCSS implementations for unit conversion, responsive breakpoints, spacing systems, container sizing, and icon utilities.

Package Information

  • Package Name: @carbon/layout
  • Package Type: npm
  • Language: JavaScript/TypeScript (with SCSS)
  • Installation: npm install @carbon/layout

Core Imports

import { rem, em, breakpoints, spacing01, miniUnits, unstable_tokens } from '@carbon/layout';

CommonJS:

const { rem, em, breakpoints, spacing01, miniUnits } = require('@carbon/layout');

SCSS:

@use '@carbon/layout';
@use '@carbon/layout/scss/convert';

Basic Usage

import { rem, em, breakpoints, spacing05, breakpointUp } from '@carbon/layout';

// Unit conversion
const headerHeight = rem(64); // "4rem"
const iconSize = em(16); // "1em"

// Responsive breakpoints
const tablet = breakpointUp('md'); // "@media (min-width: 42rem)"

// Spacing system
const padding = spacing05; // "1rem"

// Programmatic spacing
import { miniUnits } from '@carbon/layout';
const customSpacing = miniUnits(3); // "1.5rem" (3 * 8px / 16)

SCSS usage:

@use '@carbon/layout';
@use '@carbon/layout/scss/convert' as convert;

.header {
  height: convert.to-rem(64px); // 4rem
  padding: layout.$spacing-05; // 1rem
  
  @media (min-width: layout.$md-breakpoint) {
    padding: layout.$spacing-06; // 1.5rem
  }
}

Architecture

@carbon/layout is built around several key systems:

  • Unit Conversion: JavaScript functions and SCSS functions for px to rem/em conversion
  • Breakpoint System: Predefined responsive breakpoints with utility functions for media queries
  • Spacing Scale: 13-step spacing scale based on 8px mini-unit system
  • Container System: Standardized container sizes for UI components
  • Icon Sizing: Consistent icon size scales
  • Fluid Spacing: Viewport-relative spacing for responsive design
  • Token System: Programmatic access to all layout tokens

Capabilities

Unit Conversion

Core utility functions for converting between px, rem, and em units, ensuring consistent sizing across different contexts.

const baseFontSize: number; // 16
function rem(px: number): string;
function em(px: number): string;
function px(value: number): string;

Unit Conversion

Responsive Breakpoints

Comprehensive breakpoint system with predefined responsive breakpoints and utility functions for creating media queries.

interface BreakpointConfig {
  width: string;
  columns: number;
  margin: string;
}

const breakpoints: {
  sm: BreakpointConfig;
  md: BreakpointConfig;
  lg: BreakpointConfig;
  xlg: BreakpointConfig;
  max: BreakpointConfig;
};

function breakpointUp(name: 'sm' | 'md' | 'lg' | 'xlg' | 'max'): string;
function breakpointDown(name: 'sm' | 'md' | 'lg' | 'xlg' | 'max'): string;
function breakpoint(name: 'sm' | 'md' | 'lg' | 'xlg' | 'max'): string;

Responsive Breakpoints

Spacing System

Standardized spacing scale based on 8px mini-unit system, providing consistent spacing throughout applications.

const miniUnit: number; // 8
function miniUnits(count: number): string;

const spacing01: string; // "0.125rem"
const spacing02: string; // "0.25rem"
const spacing03: string; // "0.5rem"
const spacing04: string; // "0.75rem"
const spacing05: string; // "1rem"
const spacing06: string; // "1.5rem"
const spacing07: string; // "2rem"
const spacing08: string; // "2.5rem"
const spacing09: string; // "3rem"
const spacing10: string; // "4rem"
const spacing11: string; // "5rem"
const spacing12: string; // "6rem"
const spacing13: string; // "10rem"

const spacing: string[];

Spacing System

Fluid Spacing & Container Sizing

Viewport-relative spacing and standardized container sizes for responsive layouts and consistent component sizing.

const fluidSpacing01: number; // 0
const fluidSpacing02: string; // "2vw"
const fluidSpacing03: string; // "5vw"
const fluidSpacing04: string; // "10vw"
const fluidSpacing: Array<number | string>;

const container01: string; // "1.5rem"
const container02: string; // "2rem"
const container03: string; // "2.5rem"
const container04: string; // "3rem"
const container05: string; // "4rem"
const container: string[];

interface Sizes {
  XSmall: string;
  Small: string;
  Medium: string;
  Large: string;
  XLarge: string;
  '2XLarge': string;
}
const sizes: Sizes;

Fluid Spacing & Containers

SCSS Functions & Variables

Complete SCSS API providing the same functionality as JavaScript with additional utility functions for advanced use cases.

// Variables
$base-font-size: 16px !default;

// Functions
@function to-rem($px);
@function rem($px); // Deprecated
@function em($px);
@function map-deep-get($map, $keys...);
@function key-by-index($map, $index);
@function last-map-item($map);

// Generated variables (available after build)
$spacing-01, $spacing-02, ..., $spacing-13;
$container-01, $container-02, ..., $container-05;
$icon-size-01, $icon-size-02;
$size-xs, $size-sm, $size-md, $size-lg, $size-xl, $size-2xl;

SCSS API

Token System

Programmatic access to all layout token names for dynamic usage and validation.

/**
 * Array of all available layout token names
 */
const unstable_tokens: string[];

The unstable_tokens array contains all token names that are available as exports from the package, including:

  • All spacing tokens (spacing01-spacing13)
  • Fluid spacing tokens (fluidSpacing01-fluidSpacing04)
  • Container tokens (container01-container05)
  • Size tokens (sizeXSmall, sizeSmall, sizeMedium, sizeLarge, sizeXLarge, size2XLarge)
  • Icon size tokens (iconSize01, iconSize02)
  • Deprecated layout tokens (layout01-layout07)

Usage Example:

import { unstable_tokens } from '@carbon/layout';
import * as Layout from '@carbon/layout';

// Validate that all tokens are available
unstable_tokens.forEach(token => {
  if (Layout[token] === undefined) {
    console.warn(`Token ${token} is not available`);
  }
});

// Get all token values programmatically
const tokenValues = unstable_tokens.reduce((acc, token) => {
  acc[token] = Layout[token];
  return acc;
}, {});

Types

type BreakpointName = 'sm' | 'md' | 'lg' | 'xlg' | 'max';

interface BreakpointConfig {
  width: string;
  columns: number;
  margin: string;
}

interface Breakpoints {
  sm: BreakpointConfig;
  md: BreakpointConfig;
  lg: BreakpointConfig;
  xlg: BreakpointConfig;
  max: BreakpointConfig;
}

interface Sizes {
  XSmall: string;
  Small: string;
  Medium: string;
  Large: string;
  XLarge: string;
  '2XLarge': string;
}

type SpacingScale = [
  string, string, string, string, string, string, string,
  string, string, string, string, string, string
];

type FluidSpacingScale = [number, string, string, string];
type ContainerScale = [string, string, string, string, string];
type IconSizeScale = [string, string];