NucleusContainer / NucleusSection

LayoutNew

The boring-but-essential layout primitives: consistent max-width, gutters and vertical rhythm so every page breathes the same.

Preview

size="sm"

size="md"

size="lg" · default

Installation

1shadcn/ui initialized (`npx shadcn@latest init`)
2Tailwind CSS v4 configured with the nucleusUI theme tokens

npm install lucide-react clsx tailwind-merge

Add to your globals.css

The nucleusUI accent lives in these CSS variables — without them the component falls back to the default shadcn zinc theme.

app/globals.css

:root {
  --primary: oklch(0.54 0.24 291);
  --primary-foreground: oklch(0.985 0 0);
  --ring: oklch(0.54 0.24 291);
  --accent: oklch(0.96 0.03 291);
  --accent-foreground: oklch(0.4 0.19 291);
}

.dark {
  --primary: oklch(0.68 0.21 291);
  --primary-foreground: oklch(0.145 0 0);
  --ring: oklch(0.68 0.21 291);
  --accent: oklch(0.26 0.06 291);
  --accent-foreground: oklch(0.87 0.09 291);
}

Usage

tsx

import { NucleusContainer } from "@/components/nucleus/nucleus-container";

export function Example() {
  return (
    <NucleusSection spacing="lg">
      <NucleusContainer size="md">
        <h1>Consistent width and rhythm</h1>
        <p>Container handles gutters + max-width, Section handles vertical padding.</p>
      </NucleusContainer>
    </NucleusSection>
  );
}

Source

Copy this file into components/nucleus/nucleus-container.tsx in your project — it's yours to own and modify.

components/nucleus/nucleus-container.tsx

import * as React from "react";
import { cn } from "@/lib/utils";

export interface NucleusContainerProps extends React.ComponentProps<"div"> {
  /** Max content width. */
  size?: "sm" | "md" | "lg" | "full";
  /** Center the container horizontally (default true). */
  center?: boolean;
}

const containerSizes = {
  sm: "max-w-2xl",
  md: "max-w-4xl",
  lg: "max-w-6xl",
  full: "max-w-none",
} as const;

/**
 * Horizontal layout primitive — enforces a consistent max-width,
 * responsive gutters and optional centering.
 */
export function NucleusContainer({
  className,
  size = "lg",
  center = true,
  ...props
}: NucleusContainerProps) {
  return (
    <div
      data-slot="nucleus-container"
      className={cn("w-full px-4 sm:px-6", center && "mx-auto", containerSizes[size], className)}
      {...props}
    />
  );
}

export interface NucleusSectionProps extends React.ComponentProps<"section"> {
  /** Vertical padding scale. */
  spacing?: "none" | "sm" | "md" | "lg";
}

const sectionSpacing = {
  none: "py-0",
  sm: "py-8 sm:py-10",
  md: "py-12 sm:py-16",
  lg: "py-20 sm:py-28",
} as const;

/**
 * Vertical layout primitive — consistent section rhythm,
 * wraps content in a NucleusContainer by default.
 */
export function NucleusSection({
  className,
  spacing = "md",
  children,
  ...props
}: NucleusSectionProps) {
  return (
    <section
      data-slot="nucleus-section"
      className={cn(sectionSpacing[spacing], className)}
      {...props}
    >
      <NucleusContainer>{children}</NucleusContainer>
    </section>
  );
}

Props

Prop	Type	Default	Description
`size`	"sm" \| "md" \| "lg" \| "full"	"lg"	Container max-width scale.
`center`	boolean	true	Center the container horizontally.
`spacing`	"none" \| "sm" \| "md" \| "lg"	"md"	Section vertical padding scale. (NucleusSection only)
`className`	string	—	Extra classes for the root element.