@laddhaanshul/layout-spacing

v1.0.2

Published

21 days ago

A unified layout, spacing, responsive, and aspect-ratio system for React & React Native. Token-based 8pt grid spacing engine with Box, Flex, Stack primitives, responsive hooks, and AspectRatio component.

Downloads

260

0High
0Medium
0Low

laddhaanshul

react react-native layout spacing 8pt-grid design-tokens responsive aspect-ratio box flex stack components ui cross-platform

@laddhaanshul/layout-spacing

A unified, high-performance layout, spacing, responsive, and aspect-ratio system for React and React Native applications. Build consistent, pixel-perfect UIs that work seamlessly across Web, iOS, Android, and beyond.

🌟 Introduction

@laddhaanshul/layout-spacing is more than just a component library; it's a design system engine. It enforces architectural consistency in your UI development by providing a common language (tokens) and a set of architectural primitives (Box, Flex, Stack) that eliminate the need for custom CSS for most layout needs.

Key Philosophies:

Uniformity: One API for both Web and Native. No more context-switching between CSS Flexbox and React Native Stylesheets.
Constraint-Based Design: Enforces a strict 8pt grid system to ensure spacing is never "magic" or inconsistent.
Zero-Runtime (Optimization): Designed to be as thin as possible. Most layout styles are calculated statically or via highly optimized lookups.
Responsive by Default: Built-in support for multiple breakpoints with mobile-first logic that works identically across all screens.

💎 Why Layout Spacing?

Choosing the right layout system can significantly impact your project's long-term maintainability and performance. Here is why @laddhaanshul/layout-spacing stands out:

Design-to-Code Harmony: Speak the same language as your designers. When they say "16px gap", you just write gap={4}. No guesswork, no magic numbers.
True Cross-Platform Portability: Write your layout logic once. Whether you're building a dashboard for the web or a mobile app for iOS/Android, the layout behaves exactly as expected.
Performance Without Compromise: Near-zero runtime overhead means your animations stay smooth and your interaction latency stays low.
Scale with Confidence: As your codebase grows, atomic layout primitives make your components more readable, maintainable, and easier to refactor than thousands of lines of custom CSS.
Bulletproof Type Safety: Catch layout bugs before they reach your users. Our comprehensive TypeScript definitions provide an extra layer of protection for your design system.

📋 Table of Contents

📦 Installation

Install the package via your preferred package manager.

# Using npm
npm install @laddhaanshul/layout-spacing

# Using pnpm
pnpm add @laddhaanshul/layout-spacing

# Using yarn
yarn add @laddhaanshul/layout-spacing

Peer Dependencies

Ensure you have the following installed (standard for React projects):

react >= 16.8.0
react-native (if using in a Native/Expo environment)

🚀 Quick Start

1. Setup the Provider

Wrap your root component with LayoutSpacingProvider. This initializes the spacing tokens and responsive listeners.

import { LayoutSpacingProvider } from '@laddhaanshul/layout-spacing';

function Root() {
  return (
    <LayoutSpacingProvider>
      <App />
    </LayoutSpacingProvider>
  );
}

2. Build Your First Layout

Use Box, Flex, and Stack to structure your UI without writing a single line of CSS.

import { Box, Flex, Stack } from '@laddhaanshul/layout-spacing';

const ProfileCard = () => (
  <Box p={4} bg="#f8fafc" borderRadius={12} shadow="md">
    <Stack gap={3}>
      <Flex align="center" gap={3}>
        <Box w={48} h={48} bg="#3b82f6" borderRadius="50%" />
        <Box>
          <h3 style={{ margin: 0 }}>John Doe</h3>
          <p style={{ margin: 0, color: '#64748b' }}>Frontend Architect</p>
        </Box>
      </Flex>
      <Box pt={2}>
        <p>Expert in creating scalable design systems and cross-platform experiences.</p>
      </Box>
      <Flex gap={2}>
        <Box px={3} py={1} bg="#dbeafe" borderRadius={100} style={{ fontSize: 12 }}>React</Box>
        <Box px={3} py={1} bg="#dbeafe" borderRadius={100} style={{ fontSize: 12 }}>Native</Box>
      </Flex>
    </Stack>
  </Box>
);

🧠 Core Concepts

The 8pt Grid System

The library is built on the industry-standard 8pt grid. Spacing tokens are multiples of 4px, where 1 = 4px and 2 = 8px. This allows for extremely fine-grained control while maintaining a rigid structure.

Cross-Platform Architecture

When running on the Web, components default to rendering as <div> elements and use standard CSS properties (e.g., margin, padding, gap). When running on React Native, components default to View and use numeric style values (e.g., margin: 16), which is essential for StyleSheet performance.

📖 API Reference

1. Spacing System

The spacing system provides the tokens and hooks used to calculate dimensions.

`LayoutSpacingProvider`

The main configuration entry point.

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | spacing | Partial<SpacingConfig> | { baseUnit: 8 } | Configuration for the spacing grid. | | responsive | Partial<ResponsiveConfig> | See Breakpoints | Configuration for responsive breakpoints. |

Example:

<LayoutSpacingProvider 
  spacing={{ 
    baseUnit: 4,     // Changes 1 token from 4px to 8px
    useRem: true,    // Uses rem units on Web
    rootFontSize: 16 
  }}
>
  {children}
</LayoutSpacingProvider>

`useSpacing()`

The primary hook for accessing spacing logic in functional components.

Returns:

value(token: SpacingValue): string | number: Converts a token to its platform-specific value.
margin(direction: SpacingDirection, token: SpacingValue): Object: Returns a margin style object.
padding(direction: SpacingDirection, token: SpacingValue): Object: Returns a padding style object.
gap(token: SpacingValue): Object: Returns a gap style object.
scale(): Object: The full raw scale.

Example:

const spacing = useSpacing();
const boxStyle = {
  ...spacing.padding('x', 4), // { paddingLeft: 16, paddingRight: 16 }
  marginTop: spacing.value(8) // 32
};

2. Layout Primitives

These components are the building blocks of your UI. They all share common style and spacing props.

`Box`

The base component. Think of it as a div or View on steroids.

Common Props (Shared by Flex & Stack):

`Flex`

Extends Box with full Flexbox capabilities.

`Stack`

A higher-level component optimized for vertical or horizontal layouts with uniform spacing.

Example:

<Stack gap={2} direction="horizontal" align="center">
  <Box bg="red" p={2} />
  <Box bg="blue" p={2} />
</Stack>

3. Responsive System

The responsive system uses a mobile-first approach.

Default Breakpoints:

xs: 0px
sm: 576px
md: 768px
lg: 992px
xl: 1200px
xxl: 1440px

`useBreakpoint()`

Provides the current screen state.

Returns:

breakpoint: The current active key (e.g., 'md')
isAbove(bp): True if width >= breakpoint.
isBelow(bp): True if width <= breakpoint.
is(bp): True if width is exactly within that range.
width, height: Current pixel dimensions.
orientation: 'portrait' \| 'landscape'.

`useResponsiveValue(values)`

Returns a different value based on the current breakpoint. It searches from the current breakpoint down to xs for the nearest defined value.

const padding = useResponsiveValue({
  xs: 2, // 8px
  md: 4, // 16px
  xl: 6  // 24px
});

4. Aspect Ratio System

Ensures elements maintain their proportions, vital for images, videos, and complex UI tiles.

`AspectRatio` Component

Wraps any content to enforce a ratio.

Example:

<AspectRatio ratio={16/9}>
  <Image source={{ uri: '...' }} style={{ flex: 1 }} />
</AspectRatio>

🏗 Advanced Usage

Custom Theming

You can override the entire spacing scale or add custom breakpoint values.

const customBreakpoints = {
  xs: 0,
  mobile: 400,
  tablet: 800,
  desktop: 1200
};

<LayoutSpacingProvider responsive={{ breakpoints: customBreakpoints }}>
  {/* App */}
</LayoutSpacingProvider>

SSR Support

For Next.js or other SSR frameworks, you can provide an initialWidth to the ResponsiveProvider to prevent layout shift during hydration.

<LayoutSpacingProvider responsive={{ initialWidth: 1200 }}>
  {/* App */}
</LayoutSpacingProvider>

🥙 Recipes & Examples

Responsive Grid

const columns = useResponsiveValue({ xs: 1, sm: 2, md: 3, lg: 4 });

<Flex wrap gap={3}>
  {items.map(item => (
    <Box key={item.id} style={{ width: `${100 / columns}%` }}>
      <Content />
    </Box>
  ))}
</Flex>

Sticky Sidebar with Fixed Header

<Stack h="100vh">
  <Box h={64} bg="white" position="sticky" top={0} zIndex={10}>
    Header
  </Box>
  <Flex grow={1}>
    <Box w={240} bg="gray.100" position="sticky" top={64} h="calc(100vh - 64px)">
      Sidebar
    </Box>
    <Box grow={1} p={4} overflow="auto">
      Main Content
    </Box>
  </Flex>
</Stack>

📊 Full Spacing Scale Table

By default, tokens represent units on an 8pt grid.

| Token | Pixels | Use Case | | :--- | :--- | :--- | | 0 | 0px | Reset | | 0.5 | 2px | Micro dividers | | 1 | 4px | Tight text spacing | | 1.5 | 6px | Intermediate | | 2 | 8px | Standard small gap | | 3 | 12px | Comfortable list spacing | | 4 | 16px | Page margins (Mobile) | | 5 | 20px | - | | 6 | 24px | Large section gap | | 8 | 32px | Page margins (Desktop) | | 10 | 40px | - | | 12 | 48px | Hero section top padding | | 16 | 64px | - | | 24 | 96px | Large layout separation | | 32 | 128px | Extreme separation |

💻 Platform Support & Limitations

Web

Supports all modern browsers (Chrome, Firefox, Safari, Edge).
Utilizes ResizeObserver for breakpoint detection.
Supports rem units for accessibility.

React Native / Expo

Supports iOS and Android.
Uses Dimensions API for screen calculations.
as prop on Box/Flex/Stack can be used to pass TouchableOpacity, ScrollView, etc.
Limitation: calc() strings are not supported in dimensions (except on Web).

📄 License

MIT © Anshul Laddha

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide and Code of Conduct.

Fork the repo.
Create a feature branch (git checkout -b feature/amazing-feature).
Commit your changes (git commit -m 'Add amazing feature').
Push to the branch (git push origin feature/amazing-feature).
Open a Pull Request.

🏗 Component Deep Dives

Box Component (`<Box />`)

The Box component is the atomic unit of the Layout Spacing system. It serves as a replacement for div (Web) or View (Native) and provides a declarative way to apply styles.

Prop Breakdown & Examples

| Category | Prop | Type | Description | Example | | :--- | :--- | :--- | :--- | :--- | | Spacing | m, mt, mb, ml, mr, mx, my | SpacingValue | Margin controls | <Box m={4} /> (16px) | | | p, pt, pb, pl, pr, px, py | SpacingValue | Padding controls | <Box px={2} /> (8px) | | Sizing | w, h | number \| string | Width/Height | <Box w="100%" h={200} /> | | | minW, maxW, minH, maxH | number \| string | Constraints | <Box maxW={600} /> | | Styling | bg | string | Background Color | <Box bg="#000" /> | | | borderRadius | number \| string | Corner Radius | <Box borderRadius={8} /> | | | opacity | number | Transparency | <Box opacity={0.5} /> | | Layout | display | string | Display Mode | <Box display="none" /> | | | position | string | Positioning | <Box position="absolute" /> | | | top, right, bottom, left | number \| string | Insets | <Box top={0} /> | | | zIndex | number | Layering | <Box zIndex={999} /> | | Interaction | cursor | string | Mouse Cursor (Web) | <Box cursor="pointer" /> |

Advanced Example: Interactive Card

<Box 
  as="article"
  p={4} 
  m={2}
  bg="white" 
  borderRadius={16} 
  shadow="lg"
  cursor="pointer"
  style={{ transition: 'transform 0.2s' }}
  onMouseEnter={(e) => e.currentTarget.style.transform = 'scale(1.02)'}
>
  <Text>Hover me!</Text>
</Box>

Flex Component (`<Flex />`)

The Flex component handles all your directional layout needs. It abstracts the complexities of Flexbox into a readable set of props.

Flex-Specific Props

Example: Navigation Bar

<Flex as="nav" p={3} bg="#1a202c" justify="space-between" align="center">
  <Box color="white" fontWeight="bold">BrandLogo</Box>
  <Flex gap={4}>
    <Box as="a" href="/home" color="gray.300">Home</Box>
    <Box as="a" href="/about" color="gray.300">About</Box>
    <Box as="a" href="/contact" color="gray.300">Contact</Box>
  </Flex>
  <Box bg="blue.500" px={4} py={2} borderRadius={6} color="white">Login</Box>
</Flex>

Stack Component (`<Stack />`)

Stack is the "magic wand" for vertical and horizontal spacing. It is essentially a Flex component pre-configured for stacking.

Example: Form Layout

<Stack gap={4} p={5} maxWidth={400} mx="auto">
  <Stack gap={1}>
    <label>Email Address</label>
    <input type="email" style={{ padding: 12, borderRadius: 8, border: '1px solid #ccc' }} />
  </Stack>
  <Stack gap={1}>
    <label>Password</label>
    <input type="password" style={{ padding: 12, borderRadius: 8, border: '1px solid #ccc' }} />
  </Stack>
  <Box as="button" bg="blue.600" p={3} borderRadius={8} color="white" fontWeight="600">
    Sign In
  </Box>
</Stack>

🎣 Hooks Deep Dive

`useSpacing()`

The swiss-army knife for spacing tokens.

Methods:

value(token): Useful for non-standard CSS properties like borderWidth or fontSize if they follow your grid.
margin(dir, token): Returns a style object. dir can be x, y, all, top, etc.
padding(dir, token): Same as margin but for padding.
gap(token): Returns { gap: value }.

Advanced Hook Usage

const MyCustomComponent = () => {
  const { value, margin } = useSpacing();
  
  // Dynamic border thickness based on grid
  const borderThickness = value(0.5); 
  
  return (
    <div style={{ 
      border: `${borderThickness}px solid black`,
      ...margin('top', 4) 
    }}>
      Content
    </div>
  );
};

`useBreakpoint()`

The source of truth for responsive states.

Detailed Result Object:

{
  breakpoint: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl',
  width: number,      // Current width in px
  height: number,     // Current height in px
  isAbove: (bp) => boolean,
  isBelow: (bp) => boolean,
  is: (bp) => boolean,
  orientation: 'portrait' | 'landscape',
  activeBreakpoints: string[] // e.g. ['xs', 'sm', 'md']
}

`useResponsiveValue()`

The most powerful tool for multi-device layouts. It uses a "closest match" algorithm.

How it works:

If you are at the lg breakpoint and provide: { xs: 10, md: 20 } The hook will return 20 because md is the closest defined value below or at lg.

⚡️ Performance Tips

Prefer Props Over Hooks: Whenever possible, use component props (p={4}) instead of calling useSpacing(). Props are highly optimized and handle platform detection more efficiently.
Avoid Excessive Providers: You only need one LayoutSpacingProvider at the root. Nesting multiple providers is supported but can lead to complex re-renders if not managed.
Static Ratios: For AspectRatio, try to use numeric ratios (16/9) rather than strings for faster calculations.

🐛 Troubleshooting

1. Invariant Violation (React Native)

Error: View config getter callback for component div must be a function Cause: You are using Box, Flex, or Stack without a provider, or the build is corrupted. Fix: Ensure your app is wrapped in LayoutSpacingProvider.

2. Styles Not Applying (Web)

Cause: CSS custom properties might be disabled or not supported in your environment. Fix: Check if generateCSSVars() is called in your provider config.

3. Layout Shift (SSR)

Cause: The library detects screen size on the client. Fix: Provide an initialWidth in the responsive config of your provider to match your primary user base (e.g., 1200 for desktop-first).

📊 Full API Table (Exhaustive)

Spacing Utils

Responsive Utils

Aspect Ratio Utils

🛠 Advanced Pattern: The "Compound" Primitive

You can easily create your own primitives by extending the provided components.

import { Flex, FlexProps } from '@laddhaanshul/layout-spacing';

interface CardProps extends FlexProps {
  title: string;
}

const Card: React.FC<CardProps> = ({ title, children, ...props }) => (
  <Flex 
    direction="column" 
    p={4} 
    bg="white" 
    borderRadius={12} 
    shadow="sm"
    {...props} 
  >
    <Box mb={3} fontWeight="bold">{title}</Box>
    <Box>{children}</Box>
  </Flex>
);

🗺 Roadmap

[ ] Add Grid component for CSS Grid support on Web.
[ ] Add useTheme for custom color token integration.
[ ] VS Code Extension for autocompleting spacing tokens.
[ ] Integration with Figma for direct design-to-code syncing.

🎨 Why the 8pt Grid? A Deep Dive into Visual Rhythm

The 8pt grid is a methodology that uses multiples of 8 to define the dimensions, padding, and margin of elements. Why 8? Because 8 is easily divisible (4, 2) and scales perfectly across high-resolution screens (Retina, 4K).

Benefits of the 8pt Grid:

Eliminate Decision Fatigue: Stop wondering if you should use 15px or 17px. Use token 4 (16px).
Scalability: Icons are usually 16x16, 24x24, or 32x32. These all fit perfectly into our grid.
Visual Harmony: When everything follows the same mathematical rhythm, the UI feels "right" to the user, even if they can't explain why.

⚔️ Comparison: How We Differ

🏗 Architecture: Under the Hood

The Resolver Pipeline

When you pass p={4} to a Box:

Extraction: The Box component extracts p from its props.
Theming: It looks up the current SpacingConfig from the SpacingContext.
Calculation: It calls toCSSValue(4, config), which computes 4 * config.baseUnit (32px).
Platform Mapping:
- On Web, it creates a style object { padding: '32px' }.
- On Native, it creates { padding: 32 }.
Merging: It merges this with any other props and the user-provided style prop.

Breakpoint Detection

Web: Uses a single ResizeObserver on the window to update the ResponsiveContext. This is more performant than adding thousands of matchMedia listeners.
Native: Uses the Dimensions event listener to track orientation and width changes.

📚 Full TypeScript Definitions

`SpacingValue`

export type SpacingToken = 0 | 0.5 | 1 | 1.5 | 2 | 2.5 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 14 | 16 | 20 | 24 | 28 | 32 | 36 | 40 | 44 | 48 | 56 | 64 | 72 | 80 | 96;

export type SpacingValue = SpacingToken | 'auto' | string;

`BoxProps`

export interface BoxProps extends BaseStyleProps, SpacingProps {
  children?: React.ReactNode;
  as?: React.ElementType;
  testID?: string;
}

`ResponsiveConfig`

export interface ResponsiveProviderProps {
  children?: React.ReactNode;
  breakpoints?: Partial<BreakpointsConfig>;
  initialWidth?: number;
  initialHeight?: number;
}

🚀 Advanced Recipes

Responsive Aspect-Ratio Hero

const isDesktop = useBreakpoint().isAbove('md');

<AspectRatio ratio={isDesktop ? 21/9 : 16/9}>
  <Box bg="black">
    <video />
  </Box>
</AspectRatio>

The "Auto-Margin" Navbar

<Flex p={4} align="center">
  <Box>Logo</Box>
  <Box ml="auto">
    <Flex gap={2}>
      <Button>Home</Button>
      <Button>Logout</Button>
    </Flex>
  </Box>
</Flex>

📈 Migration Guide

From Standard CSS

Before:

.card {
  padding: 16px;
  margin-bottom: 24px;
  display: flex;
  flex-direction: column;
}

After:

<Stack p={4} mb={6}>
  {children}
</Stack>

From Tailwind

Before:

<div class="p-4 mb-6 flex flex-col gap-4">

After:

<Stack p={4} mb={6} gap={4}>

🌐 Community & Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Twitter: @laddhaanshul

📄 License

📑 Exhaustive Prop Reference (The Big Table)

Below is every single prop supported by the core layout primitives (Box, Flex, Stack).

Base & Spacing Props (All Components)

Flex-Specific Props

Stack-Specific Props

🏗 Why "Zero-Runtime"?

While "Zero-Runtime" is often a marketing term, in @laddhaanshul/layout-spacing, it refers to our approach of avoiding complex style re-calculations during the render loop.

Static Property Mapping: Most props map directly to CSS/Native properties without intermediate logic.
Memoized Resolvers: We use high-performance memoization for token lookups.
No CSS-in-JS Overhead: We don't inject <style> tags or generate dynamic class names on the fly, which is where most CSS-in-JS libraries lose performance.

🎨 Best Practices for Maintainability

Use Semantic Elements: Always use the as prop to maintain accessibility. Use as="section", as="header", etc.
Token Over Pixels: Avoid using raw numbers for p or m props. Use tokens (2, 4, 8) to ensure you stay on the 8pt grid.
Responsive Values Sparingly: Don't define every prop as a responsive object. Use useResponsiveValue only where the layout significantly changes.
Composition Over Inheritance: Build specialized components (e.g., Container, Card, Hero) by wrapping Box or Flex rather than using complex global styles.

🛠 FAQ

Can I use this with Tailwind?

Yes! You can use @laddhaanshul/layout-spacing for your core layout structure and Tailwind for utility-based styling (colors, typography).

Does it support Dark Mode?

We recommend using standard CSS variables or the SpacingProvider to swap out configurations dynamically if you need grid changes for dark mode.

How do I handle 1px borders?

Since 1 token is 4px, you can use 0.25 if your base unit is 4, or just pass the string '1px'.

📄 License

🤝 Support the Project

If you find @laddhaanshul/layout-spacing helpful, please consider:

Giving the repository a ⭐ on GitHub.
Sharing the library with your developer friends.
Contributing to the documentation or the code.

📄 License

Built with ❤️ by Anshul Laddha

Website: layoutspacing.anshulladdha.in GitHub: github.com/laddhaanshul/LayoutSpacing

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@laddhaanshul/layout-spacing

🌟 Introduction

Key Philosophies:

💎 Why Layout Spacing?

📋 Table of Contents

📦 Installation

Peer Dependencies

🚀 Quick Start

1. Setup the Provider

2. Build Your First Layout

🧠 Core Concepts

The 8pt Grid System

Cross-Platform Architecture

📖 API Reference

1. Spacing System

LayoutSpacingProvider

Example:

useSpacing()

Example:

2. Layout Primitives

Box

Flex

Stack

Example:

3. Responsive System

Default Breakpoints:

useBreakpoint()

useResponsiveValue(values)

4. Aspect Ratio System

AspectRatio Component

Example:

🏗 Advanced Usage

Custom Theming

SSR Support

🥙 Recipes & Examples

Responsive Grid

Sticky Sidebar with Fixed Header

📊 Full Spacing Scale Table

💻 Platform Support & Limitations

Web

React Native / Expo

📄 License

🤝 Contributing

🏗 Component Deep Dives

Box Component (<Box />)

Prop Breakdown & Examples

Advanced Example: Interactive Card

Flex Component (<Flex />)

Flex-Specific Props

Example: Navigation Bar

Stack Component (<Stack />)

Example: Form Layout

🎣 Hooks Deep Dive

useSpacing()

Methods:

Advanced Hook Usage

useBreakpoint()

Detailed Result Object:

useResponsiveValue()

How it works:

⚡️ Performance Tips

🐛 Troubleshooting

1. Invariant Violation (React Native)

2. Styles Not Applying (Web)

3. Layout Shift (SSR)

📊 Full API Table (Exhaustive)

Spacing Utils

Responsive Utils

Aspect Ratio Utils

🛠 Advanced Pattern: The "Compound" Primitive

🗺 Roadmap

🎨 Why the 8pt Grid? A Deep Dive into Visual Rhythm

Benefits of the 8pt Grid:

⚔️ Comparison: How We Differ

`LayoutSpacingProvider`

`useSpacing()`

`Box`

`Flex`

`Stack`

`useBreakpoint()`

`useResponsiveValue(values)`

`AspectRatio` Component

Box Component (`<Box />`)

Flex Component (`<Flex />`)

Stack Component (`<Stack />`)

`useSpacing()`

`useBreakpoint()`

`useResponsiveValue()`

`SpacingValue`

`BoxProps`

`ResponsiveConfig`