tessl/npm-carbon--layout

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Unit Conversion

Name: tessl/npm-carbon--layout
Author: tessl

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

Capabilities

Base Font Size

Default font size used for all unit conversions.

/**
 * Base font size used for unit conversions
 */
const baseFontSize: number; // 16

Pixel to Rem Conversion

Converts pixel values to rem units based on the base font size.

/**
 * Convert a given px unit to a rem unit
 * @param px - Pixel value to convert
 * @returns String with rem unit
 */
function rem(px: number): string;

Usage Examples:

import { rem } from '@carbon/layout';

const headerHeight = rem(64); // "4rem"
const buttonPadding = rem(12); // "0.75rem"
const iconSize = rem(24); // "1.5rem"

Pixel to Em Conversion

Converts pixel values to em units based on the base font size.

/**
 * Convert a given px unit to a em unit
 * @param px - Pixel value to convert
 * @returns String with em unit
 */
function em(px: number): string;

Usage Examples:

import { em } from '@carbon/layout';

const fontSize = em(18); // "1.125em"
const lineHeight = em(24); // "1.5em"
const letterSpacing = em(1); // "0.0625em"

Pixel String Conversion

Converts numeric values to pixel strings.

/**
 * Convert a given px unit to its string representation
 * @param value - Number of pixels
 * @returns String with px unit
 */
function px(value: number): string;

Usage Examples:

import { px } from '@carbon/layout';

const borderWidth = px(2); // "2px"
const shadowOffset = px(4); // "4px"
const borderRadius = px(8); // "8px"

SCSS Unit Conversion

The SCSS API provides equivalent functionality with additional error checking and the option to use the newer to-rem function.

/// Default font size
/// @type Number
$base-font-size: 16px !default;

/// Convert a given px unit to a rem unit
/// @param {Number} $px - Number with px unit
/// @return {Number} Number with rem unit
@function to-rem($px);

/// Legacy rem conversion function (deprecated)
/// @param {Number} $px - Number with px unit
/// @return {Number} Number with rem unit
/// @deprecated Use to-rem instead
@function rem($px);

/// Convert a given px unit to a em unit
/// @param {Number} $px - Number with px unit
/// @return {Number} Number with em unit
@function em($px);

SCSS Usage Examples:

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

.component {
  height: convert.to-rem(64px); // 4rem
  padding: convert.to-rem(16px); // 1rem
  font-size: convert.em(14px); // 0.875em
  
  // Legacy function (deprecated)
  margin: convert.rem(8px); // 0.5rem
}

Conversion Reference

Common pixel to rem conversions at 16px base font size:

Pixels	Rem	Em	Common Use Case
2px	0.125rem	0.125em	Border width
4px	0.25rem	0.25em	Small spacing
8px	0.5rem	0.5em	Mini unit
12px	0.75rem	0.75em	Small padding
16px	1rem	1em	Base font size
20px	1.25rem	1.25em	Icon size
24px	1.5rem	1.5em	Medium spacing
32px	2rem	2em	Large spacing
48px	3rem	3em	Component height
64px	4rem	4em	Header height

Error Handling

The SCSS functions include type checking and will throw errors for invalid input:

// This will cause an error
.invalid {
  height: convert.to-rem(64); // Error: Expected px unit, got number
  padding: convert.to-rem("16px"); // Error: Expected number, got string
}

// Correct usage
.valid {
  height: convert.to-rem(64px); // ✓ 4rem
  padding: convert.to-rem(16px); // ✓ 1rem
}

Install with Tessl CLI