tessl/npm-shopify--polaris

Shopify's comprehensive admin product component library for React applications with TypeScript support and accessibility features.

—

Pending

Overview

Eval results

Files

Layout & Structure Utilities

Name: tessl/npm-shopify--polaris
Author: tessl

Flexible layout components and utilities for organizing content with consistent spacing, responsive behavior, and structured presentation. These components provide the foundational building blocks for creating well-organized user interfaces.

Capabilities

Box

Flexible container component providing padding, margin, background, and border control with design token integration.

/**
 * Flexible container with spacing and styling controls
 * @param children - Box content
 * @param padding - Padding on all sides
 * @param background - Background color token
 * @returns JSX element with box container
 */
function Box(props: BoxProps): JSX.Element;

interface BoxProps {
  /** Box content */
  children?: React.ReactNode;
  /** Padding on all sides */
  padding?: SpaceScale;
  /** Padding inline start (left in LTR) */
  paddingInlineStart?: SpaceScale;
  /** Padding inline end (right in LTR) */
  paddingInlineEnd?: SpaceScale;
  /** Padding block start (top) */
  paddingBlockStart?: SpaceScale;
  /** Padding block end (bottom) */
  paddingBlockEnd?: SpaceScale;
  /** Background color */
  background?: ColorBackgroundAlias;
  /** Color styling */
  color?: ColorTextAlias;
  /** Border radius */
  borderRadius?: BorderRadiusScale;
  /** Border width */
  borderWidth?: BorderWidthScale;
  /** Border color */
  borderColor?: ColorBorderAlias;
  /** Box shadow */
  shadow?: ShadowAlias;
  /** Overflow behavior */
  overflow?: 'hidden' | 'visible';
  /** Minimum height */
  minHeight?: string;
  /** Minimum width */
  minWidth?: string;
  /** Maximum width */
  maxWidth?: string;
  /** Width */
  width?: string;
  /** Height */
  height?: string;
  /** Position */
  position?: 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky';
  /** Inset positioning */
  insetBlockStart?: string;
  /** Inset positioning */
  insetBlockEnd?: string;
  /** Inset positioning */
  insetInlineStart?: string;
  /** Inset positioning */
  insetInlineEnd?: string;
  /** Opacity */
  opacity?: string;
  /** Z-index */
  zIndex?: string;
  /** Role for accessibility */
  role?: string;
  /** Tab index */
  tabIndex?: number;
  /** ID attribute */
  id?: string;
}

/** Spacing scale values from design tokens */
type SpaceScale = 
  | '025' | '050' | '100' | '150' | '200' | '300' | '400' | '500' | '600' 
  | '800' | '1000' | '1200' | '1600' | '2000' | '2400' | '2800' | '3200';

/** Background color aliases from design tokens */
type ColorBackgroundAlias = 
  | 'bg' | 'bg-inverse' | 'bg-subdued' | 'bg-surface' | 'bg-surface-neutral'
  | 'bg-surface-neutral-subdued' | 'bg-surface-success' | 'bg-surface-success-subdued'
  | 'bg-surface-warning' | 'bg-surface-warning-subdued' | 'bg-surface-critical'
  | 'bg-surface-critical-subdued' | 'bg-fill' | 'bg-fill-active' | 'bg-fill-selected'
  | 'bg-fill-disabled' | 'bg-fill-success' | 'bg-fill-warning' | 'bg-fill-critical';

Usage Example:

import React from 'react';
import { Box, Text, BlockStack } from '@shopify/polaris';

function ProductCard() {
  return (
    <Box
      background="bg-surface"
      padding="400"
      borderRadius="200"
      shadow="card"
    >
      <BlockStack gap="300">
        <Text variant="headingMd" as="h3">
          Product Title
        </Text>
        <Text variant="bodyMd" color="subdued">
          Product description with details about features and benefits.
        </Text>
        <Box
          background="bg-surface-success"
          padding="200"
          borderRadius="100"
        >
          <Text variant="bodySm" color="success">
            In Stock
          </Text>
        </Box>
      </BlockStack>
    </Box>
  );
}

BlockStack

Vertical stacking layout component for organizing content in a column with consistent spacing and alignment.

/**
 * Vertical stacking layout component
 * @param children - Content to stack vertically
 * @param gap - Space between items
 * @param align - Horizontal alignment of items
 * @returns JSX element with vertical stack
 */
function BlockStack(props: BlockStackProps): JSX.Element;

interface BlockStackProps {
  /** Content to stack */
  children?: React.ReactNode;
  /** Space between stack items */
  gap?: SpaceScale;
  /** Horizontal alignment */
  align?: 'start' | 'center' | 'end' | 'stretch';
  /** Inline size behavior */
  inlineAlign?: 'start' | 'center' | 'end' | 'baseline' | 'stretch';
  /** HTML element type */
  as?: 'div' | 'section' | 'span' | 'fieldset' | 'ul' | 'ol' | 'li';
  /** Reverse stack order */
  reverseOrder?: boolean;
}

InlineStack

Horizontal stacking layout component for organizing content in a row with wrapping and alignment options.

/**
 * Horizontal stacking layout component
 * @param children - Content to stack horizontally
 * @param gap - Space between items
 * @param align - Vertical alignment of items
 * @returns JSX element with horizontal stack
 */
function InlineStack(props: InlineStackProps): JSX.Element;

interface InlineStackProps {
  /** Content to stack */
  children?: React.ReactNode;
  /** Space between stack items */
  gap?: SpaceScale;
  /** Vertical alignment */
  align?: 'start' | 'center' | 'end' | 'baseline' | 'stretch';
  /** Horizontal alignment */
  blockAlign?: 'start' | 'center' | 'end' | 'baseline' | 'stretch';
  /** Allow items to wrap */
  wrap?: boolean;
  /** HTML element type */
  as?: 'div' | 'section' | 'span' | 'ul' | 'ol' | 'li';
}

InlineGrid

Responsive grid layout component with automatic column sizing and gap control.

/**
 * Responsive grid layout component
 * @param children - Grid items
 * @param columns - Column configuration
 * @param gap - Space between grid items
 * @returns JSX element with grid layout
 */
function InlineGrid(props: InlineGridProps): JSX.Element;

interface InlineGridProps {
  /** Grid content */
  children?: React.ReactNode;
  /** Number of columns or responsive configuration */
  columns?: number | string[] | ResponsiveValue<number | string>;
  /** Gap between grid items */
  gap?: SpaceScale | ResponsiveValue<SpaceScale>;
  /** Vertical alignment of grid items */
  alignItems?: 'start' | 'center' | 'end' | 'baseline' | 'stretch';
  /** HTML element type */
  as?: 'div' | 'section' | 'ul' | 'ol' | 'li';
}

/** Responsive value configuration */
type ResponsiveValue<T> = {
  xs?: T;
  sm?: T;
  md?: T;
  lg?: T;
  xl?: T;
};

Grid

CSS Grid layout component with named areas and responsive configuration for complex layouts.

/**
 * CSS Grid layout with named areas
 * @param children - Grid content
 * @param areas - Named grid areas configuration
 * @param columns - Column track sizing
 * @returns JSX element with CSS grid
 */
function Grid(props: GridProps): JSX.Element;

interface GridProps {
  /** Grid content */
  children?: React.ReactNode;
  /** Named grid areas */
  areas?: string[] | ResponsiveValue<string[]>;
  /** Grid template columns */
  columns?: string[] | ResponsiveValue<string[]>;
  /** Grid template rows */
  rows?: string[] | ResponsiveValue<string[]>;
  /** Gap between grid items */
  gap?: SpaceScale | ResponsiveValue<SpaceScale>;
  /** HTML element type */
  as?: 'div' | 'section';
}

/**
 * Individual grid cell component
 * @param children - Cell content
 * @param area - Named grid area
 * @param columnStart - Column start position
 * @param columnEnd - Column end position
 * @returns JSX element with grid cell
 */
function GridCell(props: GridCellProps): JSX.Element;

interface GridCellProps {
  /** Cell content */
  children?: React.ReactNode;
  /** Named grid area */
  area?: string | ResponsiveValue<string>;
  /** Column start position */
  columnStart?: number | ResponsiveValue<number>;
  /** Column end position */
  columnEnd?: number | ResponsiveValue<number>;
  /** Row start position */
  rowStart?: number | ResponsiveValue<number>;
  /** Row end position */
  rowEnd?: number | ResponsiveValue<number>;
}

LegacyStack

Legacy stack component (deprecated in favor of BlockStack/InlineStack) maintained for backward compatibility.

/**
 * Legacy stack component (use BlockStack/InlineStack instead)
 * @param children - Stack content
 * @param vertical - Vertical stack direction
 * @param spacing - Space between items
 * @returns JSX element with legacy stack
 * @deprecated Use BlockStack or InlineStack instead
 */
function LegacyStack(props: LegacyStackProps): JSX.Element;

interface LegacyStackProps {
  /** Stack content */
  children?: React.ReactNode;
  /** Vertical stacking */
  vertical?: boolean;
  /** Spacing between items */
  spacing?: 'extraTight' | 'tight' | 'loose' | 'extraLoose';
  /** Item distribution */
  distribution?: 'equalSpacing' | 'leading' | 'trailing' | 'center' | 'fill' | 'fillEvenly';
  /** Item alignment */
  alignment?: 'leading' | 'trailing' | 'center' | 'fill' | 'baseline';
  /** Wrap items */
  wrap?: boolean;
}

/**
 * Legacy stack item component
 * @param children - Item content
 * @param fill - Fill available space
 * @returns JSX element with stack item
 */
function LegacyStackItem(props: LegacyStackItemProps): JSX.Element;

interface LegacyStackItemProps {
  /** Item content */
  children?: React.ReactNode;
  /** Fill available space */
  fill?: boolean;
}

Bleed

Negative margin utility component for extending content beyond its container boundaries.

/**
 * Negative margin utility for extending content
 * @param children - Content to bleed
 * @param marginInline - Horizontal negative margin
 * @param marginBlock - Vertical negative margin
 * @returns JSX element with negative margins
 */
function Bleed(props: BleedProps): JSX.Element;

interface BleedProps {
  /** Content to apply bleed margins */
  children: React.ReactNode;
  /** Horizontal negative margin */
  marginInline?: SpaceScale;
  /** Vertical negative margin */
  marginBlock?: SpaceScale;
  /** Negative margin on inline start */
  marginInlineStart?: SpaceScale;
  /** Negative margin on inline end */
  marginInlineEnd?: SpaceScale;
  /** Negative margin on block start */
  marginBlockStart?: SpaceScale;
  /** Negative margin on block end */
  marginBlockEnd?: SpaceScale;
}

Divider

Visual separator component for creating clear content boundaries with customizable styling.

/**
 * Visual separator for content boundaries
 * @param borderColor - Divider border color
 * @param borderWidth - Divider border width
 * @returns JSX element with divider line
 */
function Divider(props: DividerProps): JSX.Element;

interface DividerProps {
  /** Border color */
  borderColor?: ColorBorderAlias;
  /** Border width */
  borderWidth?: BorderWidthScale;
}

/** Border width scale values */
type BorderWidthScale = '025' | '050' | '100';

/** Border color aliases from design tokens */
type ColorBorderAlias = 
  | 'border' | 'border-inverse' | 'border-subdued' | 'border-success'
  | 'border-success-subdued' | 'border-warning' | 'border-warning-subdued'
  | 'border-critical' | 'border-critical-subdued' | 'border-focus'
  | 'border-disabled';

Usage Example:

import React from 'react';
import { BlockStack, InlineStack, Box, Text, Divider, Button } from '@shopify/polaris';

function OrderSummary() {
  return (
    <Box padding="400" background="bg-surface" borderRadius="200">
      <BlockStack gap="400">
        <Text variant="headingMd" as="h2">
          Order Summary
        </Text>
        
        <Divider />
        
        <BlockStack gap="200">
          <InlineStack align="space-between">
            <Text variant="bodyMd">Subtotal</Text>
            <Text variant="bodyMd">$99.00</Text>
          </InlineStack>
          
          <InlineStack align="space-between">
            <Text variant="bodyMd">Shipping</Text>
            <Text variant="bodyMd">$5.99</Text>
          </InlineStack>
          
          <InlineStack align="space-between">
            <Text variant="bodyMd">Tax</Text>
            <Text variant="bodyMd">$8.40</Text>
          </InlineStack>
        </BlockStack>
        
        <Divider />
        
        <InlineStack align="space-between">
          <Text variant="headingSm" as="h3">Total</Text>
          <Text variant="headingSm" as="h3">$113.39</Text>
        </InlineStack>
        
        <Button primary fullWidth>
          Complete Order
        </Button>
      </BlockStack>
    </Box>
  );
}

Layout Design Tokens

/** Border radius scale values */
type BorderRadiusScale = 
  | '050' | '100' | '150' | '200' | '300' | '400' | '500' | '750';

/** Text color aliases from design tokens */
type ColorTextAlias = 
  | 'text' | 'text-inverse' | 'text-subdued' | 'text-disabled'
  | 'text-success' | 'text-warning' | 'text-critical' | 'text-interactive'
  | 'text-on-color';

/** Shadow aliases from design tokens */
type ShadowAlias = 
  | 'card' | 'popover' | 'modal' | 'button' | 'button-hover'
  | 'button-inset' | 'button-primary' | 'button-primary-hover'
  | 'button-primary-inset';

/** Responsive breakpoints configuration */
interface BreakpointsConfig {
  xs: string;
  sm: string;
  md: string;
  lg: string;
  xl: string;
}

Scrollable

Scrollable container component with customizable scrollbars and scroll event handling for content overflow management.

/**
 * Scrollable container with custom scrollbars
 * @param children - Content to make scrollable
 * @param vertical - Allow vertical scrolling
 * @param horizontal - Allow horizontal scrolling
 * @returns JSX element with scrollable container
 */
function Scrollable(props: ScrollableProps): JSX.Element;

interface ScrollableProps {
  /** Content to display in scrollable area */
  children?: React.ReactNode;
  /** Adds a shadow when content is scrollable */
  shadow?: boolean;
  /** Adds a hint for touch devices */
  hint?: boolean;
  /** Allow horizontal scrolling */
  horizontal?: boolean;
  /** Allow vertical scrolling */
  vertical?: boolean;
  /** Callback when the scrollable is scrolled */
  onScrolledToBottom?(): void;
  /** The scrollable element to observe */
  scrollbarWidth?: 'thin' | 'none';
  /** Focus ring when scrollable is focused */
  focusable?: boolean;
}

interface ScrollableRef {
  /** Scroll to a specific position */
  scrollTo(scrollTop: number, scrollLeft?: number): void;
}

Sticky

Sticky positioning component that keeps content visible during scroll, with customizable offset and boundary detection.

/**
 * Sticky positioning component for persistent content
 * @param children - Content to make sticky
 * @param top - Top offset for sticky positioning
 * @param boundaryElement - Element that defines sticky boundary
 * @returns JSX element with sticky positioning
 */
function Sticky(props: StickyProps): JSX.Element;

interface StickyProps {
  /** Element outlining the fixed position boundaries */
  boundaryElement?: HTMLElement | null;
  /** Offset from the top of the viewport */
  offset?: boolean;
  /** Should the element remain in a fixed position when the layout is stacked (smaller screens) */
  disableWhenStacked?: boolean;
  /** Content to display in sticky container */
  children?: React.ReactNode;
}

Install with Tessl CLI