Viewport-relative spacing and standardized container sizes for responsive layouts, providing both fluid spacing that adapts to viewport width and consistent component sizing throughout Carbon Design System applications.
Viewport-relative spacing values that scale with screen size for responsive designs.
const fluidSpacing01: number; // 0
const fluidSpacing02: string; // "2vw"
const fluidSpacing03: string; // "5vw"
const fluidSpacing04: string; // "10vw"
/**
* Array containing all fluid spacing values
*/
const fluidSpacing: Array<number | string>;Fluid Spacing Scale:
| Token | Value | Description | Viewport Calculation |
|---|---|---|---|
| fluidSpacing01 | 0 | No spacing | Fixed 0 |
| fluidSpacing02 | 2vw | Small fluid | 2% of viewport width |
| fluidSpacing03 | 5vw | Medium fluid | 5% of viewport width |
| fluidSpacing04 | 10vw | Large fluid | 10% of viewport width |
Usage Examples:
import { fluidSpacing02, fluidSpacing03, fluidSpacing04 } from '@carbon/layout';
const heroStyles = {
paddingTop: fluidSpacing04, // "10vw" - scales with viewport
paddingBottom: fluidSpacing03, // "5vw" - medium fluid spacing
marginLeft: fluidSpacing02, // "2vw" - small fluid margins
};
// Responsive padding that scales with screen size
const fluidContainer = {
padding: `${fluidSpacing02} ${fluidSpacing03}`, // "2vw 5vw"
maxWidth: '100vw',
};Viewport Calculations:
// At 1200px viewport width:
// fluidSpacing02 = 24px (2% of 1200px)
// fluidSpacing03 = 60px (5% of 1200px)
// fluidSpacing04 = 120px (10% of 1200px)
// At 800px viewport width:
// fluidSpacing02 = 16px (2% of 800px)
// fluidSpacing03 = 40px (5% of 800px)
// fluidSpacing04 = 80px (10% of 800px)Standardized container sizes for consistent component sizing and layout structure.
const container01: string; // "1.5rem" (24px)
const container02: string; // "2rem" (32px)
const container03: string; // "2.5rem" (40px)
const container04: string; // "3rem" (48px)
const container05: string; // "4rem" (64px)
/**
* Array containing all container values
*/
const container: string[];Container Scale Reference:
| Token | Value | Pixels | Common Use Case |
|---|---|---|---|
| container01 | 1.5rem | 24px | Small component height |
| container02 | 2rem | 32px | Button height, input height |
| container03 | 2.5rem | 40px | Medium component height |
| container04 | 3rem | 48px | Large component height |
| container05 | 4rem | 64px | Header height, large containers |
Usage Examples:
import { container01, container02, container04, container05 } from '@carbon/layout';
const componentSizes = {
button: {
small: container01, // "1.5rem"
medium: container02, // "2rem"
large: container03, // "2.5rem"
},
input: {
height: container02, // "2rem"
padding: `0 ${container01}`, // "0 1.5rem"
},
header: {
height: container05, // "4rem"
padding: `0 ${container02}`, // "0 2rem"
},
};Extended size system with named sizes for consistent component dimensions.
const sizeXSmall: string; // "1.5rem" (24px)
const sizeSmall: string; // "2rem" (32px)
const sizeMedium: string; // "2.5rem" (40px)
const sizeLarge: string; // "3rem" (48px)
const sizeXLarge: string; // "4rem" (64px)
const size2XLarge: string; // "5rem" (80px)
interface Sizes {
XSmall: string;
Small: string;
Medium: string;
Large: string;
XLarge: string;
'2XLarge': string;
}
/**
* Object mapping size names to values
*/
const sizes: Sizes;Size Scale Reference:
| Size Name | Value | Pixels | Use Case |
|---|---|---|---|
| XSmall | 1.5rem | 24px | Compact components |
| Small | 2rem | 32px | Small buttons, inputs |
| Medium | 2.5rem | 40px | Default component size |
| Large | 3rem | 48px | Large components |
| XLarge | 4rem | 64px | Extra large components |
| 2XLarge | 5rem | 80px | Hero elements |
Usage Examples:
import { sizes } from '@carbon/layout';
const componentVariants = {
avatar: {
xs: sizes.XSmall, // "1.5rem"
sm: sizes.Small, // "2rem"
md: sizes.Medium, // "2.5rem"
lg: sizes.Large, // "3rem"
xl: sizes.XLarge, // "4rem"
},
iconButton: {
width: sizes.Medium, // "2.5rem"
height: sizes.Medium, // "2.5rem"
},
hero: {
minHeight: sizes['2XLarge'], // "5rem"
},
};
// Programmatic access
Object.entries(sizes).forEach(([name, size]) => {
console.log(`${name}: ${size}`);
});Standardized icon sizes for consistent iconography.
const iconSize01: string; // "1rem" (16px)
const iconSize02: string; // "1.25rem" (20px)
/**
* Array containing icon size values
*/
const iconSize: string[];Icon Size Reference:
| Token | Value | Pixels | Use Case |
|---|---|---|---|
| iconSize01 | 1rem | 16px | Small icons, inline icons |
| iconSize02 | 1.25rem | 20px | Medium icons, button icons |
Usage Examples:
import { iconSize01, iconSize02 } from '@carbon/layout';
const iconStyles = {
small: {
width: iconSize01, // "1rem"
height: iconSize01, // "1rem"
},
medium: {
width: iconSize02, // "1.25rem"
height: iconSize02, // "1.25rem"
},
};
// Use in button with icon
const buttonWithIcon = {
display: 'flex',
alignItems: 'center',
gap: spacing03, // "0.5rem"
'& .icon': {
width: iconSize01,
height: iconSize01,
},
};The SCSS API provides equivalent variables generated during the build process.
SCSS Usage Examples:
@use '@carbon/layout' as layout;
.button {
height: layout.$container-02; // 2rem
padding: 0 layout.$container-01; // 0 1.5rem
&--large {
height: layout.$container-04; // 3rem
}
}
.avatar {
width: layout.$size-sm; // 2rem
height: layout.$size-sm; // 2rem
&--large {
width: layout.$size-lg; // 3rem
height: layout.$size-lg; // 3rem
}
}
.icon {
width: layout.$icon-size-01; // 1rem
height: layout.$icon-size-01; // 1rem
}
// Fluid spacing in SCSS
.hero {
padding-top: 10vw; // Same as fluidSpacing04
padding-left: 5vw; // Same as fluidSpacing03
}Combining fixed and fluid spacing for optimal responsive behavior:
import {
container02, container05,
fluidSpacing02, fluidSpacing03,
breakpointUp
} from '@carbon/layout';
const hybridContainer = {
// Mobile: fixed spacing
padding: container02, // "2rem"
// Desktop: fluid spacing with limits
[breakpointUp('lg')]: {
padding: `${fluidSpacing02} ${fluidSpacing03}`, // "2vw 5vw"
maxPadding: container05, // Cap at "4rem"
},
};Creating consistent size variants across components:
import { container, sizes } from '@carbon/layout';
const createSizeVariants = (baseStyles) => {
const variants = {};
Object.entries(sizes).forEach(([sizeName, sizeValue]) => {
variants[sizeName.toLowerCase()] = {
...baseStyles,
height: sizeValue,
padding: `0 ${container[0]}`, // Always use smallest container for padding
};
});
return variants;
};
const buttonVariants = createSizeVariants({
display: 'inline-flex',
alignItems: 'center',
justifyContent: 'center',
});Using fluid spacing for full-width layouts:
import { fluidSpacing03, fluidSpacing04, container05 } from '@carbon/layout';
const fluidLayout = {
width: '100vw',
minHeight: '100vh',
padding: `${fluidSpacing04} ${fluidSpacing03}`, // "10vw 5vw"
// Limit maximum padding
'@media (min-width: 1200px)': {
paddingTop: container05, // Cap at "4rem"
paddingBottom: container05,
},
};The layout scale is deprecated but still available for backward compatibility:
const layout01: string; // "1rem" (deprecated)
const layout02: string; // "1.5rem" (deprecated)
const layout03: string; // "2rem" (deprecated)
const layout04: string; // "3rem" (deprecated)
const layout05: string; // "4rem" (deprecated)
const layout06: string; // "6rem" (deprecated)
const layout07: string; // "10rem" (deprecated)
/**
* Array containing deprecated layout values
* @deprecated Use container or sizes instead
*/
const layout: string[];Migration Guide:
// Deprecated
import { layout01, layout02, layout05 } from '@carbon/layout';
// Recommended alternatives
import { container02, container03, container05, sizes } from '@carbon/layout';
// layout01 → container02 or sizes.Small
// layout02 → container03 or sizes.Medium
// layout05 → container05 or sizes.XLarge