PixelBox

Surface-aware polymorphic container with tone, variant, padding, radius, border, and shadow controls.

  • Surface-aware tokens (pixel / linear)
  • Tone + variant matrix (solid / soft / outline / ghost)
  • Polymorphic as for semantic landmarks (section, nav, aside, main, header, footer, article); in Angular, the element you put pxlBox on
  • Dev-time a11y warning when rendered as a landmark without an accessible name
  • Padding and radius scale tokens with sensible defaults
Status
stable
Category
layout
Since
v1.6.0

API

import { PixelBox } from '@pxlkit/ui-kit';
PropTypeDefaultDescription
tone'green' | 'cyan' | 'gold' | 'red' | 'purple' | 'pink' | 'neutral''neutral'Tone of the fill and border.
surface'pixel' | 'linear'—Surface override; defaults to the nearest provider.
variant'solid' | 'soft' | 'ghost' | 'outline''solid'solid and soft fill; outline and ghost stay transparent.
padding'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl''md'Padding scale.
radius'none' | 'sm' | 'md' | 'lg' | 'full'—Fixed radius; the surface's large radius when unset.
borderboolean—Whether to render a border. Defaults to true when variant === 'outline' (outlines without a border are meaningless), false otherwise. Pass true to force a border on solid/soft/ghost; pass false to force-off on outline. Note: when polymorphic as is a landmark element (section, nav, aside, main), supply aria-label or aria-labelledby for a11y.
shadowbooleanfalseSurface drop shadow. On pixel it shows with a radius only: the default corners are cut, and a drop shadow cannot show past them.
as'div' | 'section' | 'article' | 'aside' | 'header' | 'footer' | 'main' | 'nav'—Element to render.

Also takes the native attributes and event handlers of <div> (HTMLAttributes<HTMLDivElement>), except color.

ref points to <div>.

Accessibility

WCAG target: 2.1 AA

  • unopinionated-polymorphic-surface

Inherits semantics from the as element. When as is a landmark (section, nav, aside, main), provide aria-label or aria-labelledby for an accessible name.

Usage

import { PixelBox } from '@pxlkit/ui-kit';

export function Default() {
  return (
    <PixelBox tone="neutral" variant="solid" padding="md">
      <p className="text-sm text-retro-muted">Surface-aware container box.</p>
    </PixelBox>
  );
}

Examples

Default

import { PixelBox } from '@pxlkit/ui-kit';

export function Default() {
  return (
    <PixelBox tone="neutral" variant="solid" padding="md">
      <p className="text-sm text-retro-muted">Surface-aware container box.</p>
    </PixelBox>
  );
}

Outline

import { PixelBox } from '@pxlkit/ui-kit';

export function Outline() {
  return (
    <PixelBox tone="cyan" variant="outline" padding="lg">
      <p className="text-sm text-retro-muted">Outline variant with implicit border.</p>
    </PixelBox>
  );
}

Soft

import { PixelBox } from '@pxlkit/ui-kit';

export function Soft() {
  return (
    <PixelBox tone="purple" variant="soft" padding="md" radius="md">
      <p className="text-sm text-retro-muted">Soft tonal background.</p>
    </PixelBox>
  );
}

As Section

import { PixelBox } from '@pxlkit/ui-kit';

export function AsSection() {
  return (
    <PixelBox as="section" aria-label="Stats" tone="green" variant="soft" padding="md" shadow>
      <p className="text-sm text-retro-muted">Rendered as a semantic section landmark.</p>
    </PixelBox>
  );
}

Related