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

SCSS API

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

Complete SCSS API providing layout utilities, conversion functions, and generated variables that mirror the JavaScript functionality while leveraging SCSS-specific features for advanced styling scenarios.

Capabilities

SCSS Module Structure

The SCSS API is organized into several modules that can be imported individually or collectively.

// Import all layout functionality
@use '@carbon/layout';

// Import specific modules
@use '@carbon/layout/scss/convert';
@use '@carbon/layout/scss/spacing';
@use '@carbon/layout/scss/utilities';

Module Organization:

index.scss - Main entry point forwarding all modules
scss/convert - Unit conversion functions
scss/spacing - Generated spacing variables
scss/utilities - Utility functions for advanced use cases
scss/generated/* - Build-time generated variables and maps

Unit Conversion Functions

Core conversion functions with type checking and error handling.

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

/// Convert px to rem units (recommended)
/// @param {Number} $px - Value with px unit
/// @return {Number} Value with rem unit
@function to-rem($px);

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

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

Usage Examples:

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

.component {
  // Recommended approach
  height: convert.to-rem(64px); // 4rem
  padding: convert.to-rem(16px); // 1rem
  font-size: convert.em(14px); // 0.875em
  
  // Legacy function (still works but deprecated)
  margin: convert.rem(12px); // 0.75rem
  
  // Custom base font size
  $custom-base: 18px;
  line-height: math.div(24px, $custom-base) * 1rem; // 1.333rem
}

Utility Functions

Advanced utility functions for working with maps and complex data structures.

/// Access nested map values with dot notation
/// @param {Map} $map - Source map
/// @param {Arglist} $keys - Key chain to traverse
/// @return {*} Value at key path
@function map-deep-get($map, $keys...);

/// Get map key by numeric index
/// @param {Map} $map - Source map
/// @param {Integer} $index - 1-based index
/// @return {String} Key at given index
@function key-by-index($map, $index);

/// Get the last item from a map
/// @param {Map} $map - Source map
/// @return {*} Last map value
@function last-map-item($map);

Usage Examples:

@use '@carbon/layout/scss/utilities' as utils;
@use '@carbon/layout' as layout;

// Deep map access
$nested-config: (
  spacing: (
    small: (
      mobile: 0.5rem,
      desktop: 1rem
    )
  )
);

$mobile-spacing: utils.map-deep-get($nested-config, spacing, small, mobile); // 0.5rem

// Key by index
$first-spacing-key: utils.key-by-index(layout.$spacing, 1); // First spacing key

// Last map item  
$largest-spacing: utils.last-map-item(layout.$spacing); // Last spacing value

Generated Spacing Variables

Build-time generated variables providing direct access to all spacing values.

// Individual spacing variables
$spacing-01: 0.125rem !default;
$spacing-02: 0.25rem !default;
$spacing-03: 0.5rem !default;
$spacing-04: 0.75rem !default;
$spacing-05: 1rem !default;
$spacing-06: 1.5rem !default;
$spacing-07: 2rem !default;
$spacing-08: 2.5rem !default;
$spacing-09: 3rem !default;
$spacing-10: 4rem !default;
$spacing-11: 5rem !default;
$spacing-12: 6rem !default;
$spacing-13: 10rem !default;

// Spacing map for programmatic access
$spacing: (
  spacing-01: $spacing-01,
  spacing-02: $spacing-02,
  // ... all spacing values
) !default;

Usage Examples:

@use '@carbon/layout' as layout;

.component {
  padding: layout.$spacing-05; // 1rem
  margin: layout.$spacing-07; // 2rem
  gap: layout.$spacing-03; // 0.5rem
}

// Programmatic spacing
@each $key, $value in layout.$spacing {
  .#{$key} {
    margin: $value;
  }
}

// Generate utility classes
@for $i from 1 through 13 {
  $key: spacing-#{'%02d' % $i};
  .p-#{$i} {
    padding: map.get(layout.$spacing, $key);
  }
}

Generated Container Variables

Container sizing variables for consistent component dimensions.

// Individual container variables
$container-01: 1.5rem !default;
$container-02: 2rem !default;
$container-03: 2.5rem !default;
$container-04: 3rem !default;
$container-05: 4rem !default;

// Container map
$container: (
  container-01: $container-01,
  container-02: $container-02,
  container-03: $container-03,
  container-04: $container-04,
  container-05: $container-05,
) !default;

Usage Examples:

@use '@carbon/layout' as layout;

.button {
  height: layout.$container-02; // 2rem
  
  &--small {
    height: layout.$container-01; // 1.5rem
  }
  
  &--large {
    height: layout.$container-04; // 3rem
  }
}

// Generate container utility classes
@each $key, $value in layout.$container {
  .h-#{str-slice($key, 11)} { // Remove 'container-' prefix
    height: $value;
  }
}

Generated Size Variables

Named size variables with semantic naming for component dimensions.

// Individual size variables
$size-xs: 1.5rem !default;
$size-sm: 2rem !default;
$size-md: 2.5rem !default;
$size-lg: 3rem !default;
$size-xl: 4rem !default;
$size-2xl: 5rem !default;

// Size map (if generated)
$sizes: (
  xs: $size-xs,
  sm: $size-sm,
  md: $size-md,
  lg: $size-lg,
  xl: $size-xl,
  2xl: $size-2xl,
) !default;

Usage Examples:

@use '@carbon/layout' as layout;

.avatar {
  width: layout.$size-sm; // 2rem
  height: layout.$size-sm; // 2rem
  
  &--large {
    width: layout.$size-lg; // 3rem
    height: layout.$size-lg; // 3rem
  }
}

// Size-based component variants
$component-sizes: (xs, sm, md, lg, xl, 2xl);

@each $size in $component-sizes {
  .component--#{$size} {
    width: map.get(layout.$sizes, $size);
    height: map.get(layout.$sizes, $size);
  }
}

Generated Icon Size Variables

Icon sizing variables for consistent iconography.

// Individual icon size variables
$icon-size-01: 1rem !default;
$icon-size-02: 1.25rem !default;

// Icon size map
$icon-size: (
  icon-size-01: $icon-size-01,
  icon-size-02: $icon-size-02,
) !default;

Usage Examples:

@use '@carbon/layout' as layout;

.icon {
  width: layout.$icon-size-01; // 1rem
  height: layout.$icon-size-01; // 1rem
  
  &--large {
    width: layout.$icon-size-02; // 1.25rem
    height: layout.$icon-size-02; // 1.25rem
  }
}

// Icon button with consistent sizing
.icon-button {
  width: layout.$container-02; // 2rem
  height: layout.$container-02; // 2rem
  
  .icon {
    width: layout.$icon-size-01; // 1rem
    height: layout.$icon-size-01; // 1rem
  }
}

Advanced SCSS Patterns

Custom Configuration

Override default configuration to customize the system:

// Override base font size before importing
$base-font-size: 18px;
@use '@carbon/layout/scss/convert' as convert with (
  $base-font-size: 18px
);

.component {
  // Conversion now uses 18px as base instead of 16px
  height: convert.to-rem(36px); // 2rem (36/18)
}

Mixin Creation

Create custom mixins using layout utilities:

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

@mixin component-size($size) {
  $height: map.get(layout.$container, container-#{$size});
  
  height: $height;
  padding: 0 calc($height * 0.5);
  font-size: convert.to-rem(14px);
  
  @if $size >= 3 {
    font-size: convert.to-rem(16px);
  }
}

.button {
  @include component-size(2); // Uses container-02
  
  &--large {
    @include component-size(4); // Uses container-04
  }
}

Responsive SCSS Patterns

Combining SCSS variables with responsive design:

@use '@carbon/layout' as layout;

.responsive-container {
  padding: layout.$spacing-05; // 1rem
  
  @media (min-width: 42rem) { // md breakpoint
    padding: layout.$spacing-07; // 2rem
  }
  
  @media (min-width: 66rem) { // lg breakpoint  
    padding: layout.$spacing-10; // 4rem
  }
}

// Fluid spacing in SCSS
.hero {
  padding: 5vw layout.$spacing-06; // Mix fluid and fixed
  min-height: layout.$size-2xl; // 5rem
}

Error Handling and Validation

SCSS functions include built-in error handling:

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

.component {
  // These will cause compilation errors:
  // height: convert.to-rem(64); // Error: Expected px unit
  // width: convert.to-rem("64px"); // Error: Expected number
  
  // Correct usage:
  height: convert.to-rem(64px); // ✓ 4rem
  width: convert.to-rem(32px); // ✓ 2rem
}

Build Integration

The SCSS build process generates variables from JavaScript values:

// Generated during npm run build
// These files are created automatically:
// scss/generated/_spacing.scss
// scss/generated/_container.scss  
// scss/generated/_icon-size.scss
// scss/generated/_size.scss
// scss/generated/_layout.scss (deprecated)

@use '@carbon/layout' as layout;

// All generated variables are available
.component {
  padding: layout.$spacing-05;
  height: layout.$container-02;
  
  .icon {
    width: layout.$icon-size-01;
    height: layout.$icon-size-01;
  }
}

SCSS vs JavaScript Usage

When to Use SCSS API

Static styles that don't change at runtime
Advanced SCSS features (mixins, functions, loops)
Build-time optimizations and dead code elimination
Integration with existing SCSS workflows

When to Use JavaScript API

Dynamic styles based on component state
Runtime calculations and responsive behavior
CSS-in-JS libraries and frameworks
Programmatic access to design tokens

Hybrid Approach

// SCSS for static base styles
@use '@carbon/layout' as layout;

.component {
  height: layout.$container-02;
  padding: layout.$spacing-05;
}

// JavaScript for dynamic behavior
import { breakpointUp, spacing07 } from '@carbon/layout';

const dynamicStyles = {
  [breakpointUp('lg')]: {
    padding: spacing07, // Dynamic based on breakpoint
  },
};

Install with Tessl CLI