Styling

Base Components (MUI Wrappers)

Thin re-exports of MUI components. Import from @swiftpost/elysium/ui/base/*.

Text (Typography Rename)

MUI's Typography is renamed to Text throughout the project. All related types are also renamed:

import Text from '@swiftpost/elysium/ui/base/Text';
import type { TextProps } from '@swiftpost/elysium/ui/base/Text';

// TextProps, TextClassKey, TextClasses, TextOwnProps, textClasses, etc.

Enhanced Components

Custom components that add behavior beyond MUI. Import from @swiftpost/elysium/ui/*.

Link (@swiftpost/elysium/ui/Link)

Integrates next/link with MUI Link styling. Always use this for navigation — never next/link directly.

interface Props {
  href: string;
  children: React.ReactNode;
  inheritStyle?: boolean;  // inherits color + fontWeight from parent
  external?: boolean;      // skips next/link, renders plain <a>
  blank?: boolean;         // target="_blank" + rel="noopener"
  sx?: SxProps;
}

import Link from '@swiftpost/elysium/ui/Link';

// Internal navigation (uses next/link under the hood)
<Link href="/about">About</Link>

// External link in new tab
<Link href="https://example.com" external blank>Example</Link>

// Inherit parent font styling
<Text variant="h6">
  Read our <Link href="/terms" inheritStyle>Terms</Link>
</Text>

Image (@swiftpost/elysium/ui/Image)

Smart wrapper around next/image. Falls back to plain <img> when source is a URL string without dimensions.

interface Props extends Omit<NextImageProps, 'src' | 'width' | 'height'> {
  source: string | ImageSourceData;  // URL string, or object with src/width/height
  alt: string;
  width?: number | string;
  height?: number | string;
}

import Image from '@swiftpost/elysium/ui/Image';

// Static import (next/image with optimization)
import logo from '@/public/logo.png';
<Image source={logo} alt="Logo" />

// Dynamic URL (falls back to <img>)
<Image source="https://example.com/photo.jpg" alt="Photo" width={200} height={150} />

Exported helpers:

• isStaticImageData(data) — type guard for static imports
• Types: ImageSourceData, StaticImageData, DynamicImageData

ContentFittedStack (@swiftpost/elysium/ui/ContentFittedStack)

Layout component for sections that need constrained, centered content within a full-width container.

interface Props extends Exclude<StackProps, 'maxWidth' | 'width'> {
  contentMaxWidth: StackProps['maxWidth'];  // max width of inner content
  slotProps?: {
    container?: StackProps;  // props for inner content Stack
  };
  slots?: {
    container?: React.FC<StackProps>;  // override inner component
  };
}

import ContentFittedStack from '@swiftpost/elysium/ui/ContentFittedStack';

<ContentFittedStack
  component="footer"
  contentMaxWidth="lg"
  minHeight={staticTheme.spacing(6)}
  slotProps={{
    container: { sx: { backgroundColor: 'grey.100' } }
  }}
>
  <Text>Footer content</Text>
</ContentFittedStack>

Layout Components

StackLayout (@swiftpost/elysium/layouts/StackLayout)

Full-height stack layout with optional footer. Uses the Slots pattern. Wrapped in memo.

interface SlotProps {
  mainContainer: {
    children: React.ReactNode;
    sx?: SxProps;
  };
  footerContainer?: {
    children: React.ReactNode;
    sx?: SxProps;
  };
}

interface Props {
  slots?: Partial<InferSlotsFromSlotProps<SlotProps>>;
  slotProps: SlotProps;
  sx?: SxProps;
}

CSS class names: stack-layout, stack-layout-container, stack-layout-footer.

Core Providers

AppRouterCacheProvider (@swiftpost/elysium/core/AppRouterCacheProvider)

Wraps MUI's Emotion cache provider for Next.js App Router. Sets cache key to 'elysium' by default.

ThemeProvider (@swiftpost/elysium/core/ThemeProvider)

'use client' wrapper around MUI's ThemeProvider. Accepts a theme object from @swiftpost/elysium/themes/gamut.

Theme Configuration

Runtime Theme (@swiftpost/elysium/themes/gamut)

'use client' — creates the full MUI theme.

• theme — Full createTheme() object
• mainFont — Roboto via next/font/google with CSS variable --font-roboto

Static Theme (@swiftpost/elysium/themes/gamut/static)

SSR-safe theme values. Use staticTheme from @/styles/staticTheme in the main package (which wraps this).

const staticThemeOptions = {
  spacing: (factor: number) => `${0.5 * factor}rem`,
  breakpoints: {
    values: { xs: 340, sm: 600, md: 900, lg: 1200, xl: 1536 }
  },
  typography: {
    fontFamily: 'var(--font-roboto)'
  }
} as const;

• spacing(2) = '1rem'
• Use staticTheme to read values without 'use client' or hook overhead.

Hooks

Types (@swiftpost/elysium/ui/types)

import type { SxProps, Theme, SystemStyleObject, InferSlotsFromSlotProps, SxArray } from '@swiftpost/elysium/ui/types';

Style Utilities (@swiftpost/elysium/utils/styles/sxProps)

spreadSx(sx)

Normalizes any SxProps value into a spreadable SxArray. Essential for safe style merging.

import { spreadSx } from '@swiftpost/elysium/utils/styles/sxProps';

// Always merge sx with array syntax — never overwrite
sx={[{ display: 'flex' }, ...spreadSx(sx), ...spreadSx(slotProps.root.sx)]}

Handles: undefined → [], single object → [object], array → pass-through.

isSxArray(sx)

Type guard that returns true if sx is an SxArray.

Reusable Component Pattern (Slots)

When building reusable UI components, use the MUI 7 Slots & SlotProps pattern:

1. Define a SlotProps interface for each internal element
2. Main Props includes slots?, slotProps, and sx?
3. Use spreadSx for safe style merging — never overwrite sx
4. Define const componentBaseName (kebab-case) for CSS class targeting
5. Wrap in memo

import type { InferSlotsFromSlotProps, SxProps } from '@swiftpost/elysium/ui/types';
import { spreadSx } from '@swiftpost/elysium/utils/styles/sxProps';
import Box from '@swiftpost/elysium/ui/base/Box';
import { memo } from 'react';

const componentBaseName = 'custom-card';

interface SlotProps {
  root: { children: React.ReactNode; sx?: SxProps };
  footer?: { children: React.ReactNode; sx?: SxProps };
}

interface Props {
  slots?: Partial<InferSlotsFromSlotProps<SlotProps>>;
  slotProps: SlotProps;
  sx?: SxProps;
}

const CustomCard: React.FC<Props> = ({ slots, slotProps, sx }) => {
  const Root = slots?.root ?? Box;
  const Footer = slots?.footer ?? Box;

  return (
    <Root
      className={componentBaseName}
      sx={[{ p: 2, borderRadius: 1 }, ...spreadSx(sx), ...spreadSx(slotProps.root.sx)]}
    >
      {slotProps.root.children}
      {slotProps.footer && (
        <Footer
          className={`${componentBaseName}-footer`}
          sx={[{ mt: 2 }, ...spreadSx(slotProps.footer.sx)]}
        >
          {slotProps.footer.children}
        </Footer>
      )}
    </Root>
  );
};

export type CustomCardProps = Props;
export default memo(CustomCard);

Styling & Responsive Design

• Mobile-first: Define base styles for xs, override with breakpoints for larger screens.

  sx={{ width: { xs: '100%', md: '50%' }, p: { xs: 1, md: 2 } }}
  

• Use staticTheme for values outside 'use client' components.
• Never overwrite sx. Always merge using array syntax + spreadSx.