PixelIconFrame

Decorative icon container with surface-aware borders, tone tinting, sizes, shapes, and an optional accent badge.

Five fixed sizes (48 / 56 / 64 / 80 / 112) for consistent layout rhythm
Seven tone keys driven by shared tokens for soft tinted backgrounds
Square, rounded, and circle shapes that respect surface radius
Optional accent badge slot (top-right or bottom-right)
Respects prefers-reduced-motion when animated

Status: stable
Category: cards
Since: v1.7.0

API

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

Prop	Type	Default	Description
`icon` (required)	`React.ReactNode`	—	The icon.
`size`	`48 \| 56 \| 64 \| 80 \| 112`	`56`	Width and height, in px.
`tone`	`'neutral' \| 'green' \| 'cyan' \| 'gold' \| 'red' \| 'purple' \| 'pink'`	`'neutral'`	Tone of the border, fill and icon.
`shape`	`'square' \| 'rounded' \| 'circle'`	`'square'`	`square` keeps the surface's corners.
`accent`	`{ icon: React.ReactNode; position?: AccentPosition }`	—	Badge in a corner: its content and corner (top right by default).
`animated`	`boolean`	`false`	Pulses, unless the user prefers reduced motion.
`surface`	`'pixel' \| 'linear'`	—	Surface override; defaults to the nearest provider.

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

ref points to <div>.

WCAG target: 2.1 AA

decorative wrapper

Inner icon and accent are aria-hidden. Provide an accessible label on a parent element when the frame conveys meaning.

Usage

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

const Glyph = () => (
  <span style={{ fontFamily: 'monospace', fontWeight: 700 }}>{'>_'}</span>
);

export function Default() {
  return <PixelIconFrame icon={<Glyph />} />;
}

Examples

Default

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

const Glyph = () => (
  <span style={{ fontFamily: 'monospace', fontWeight: 700 }}>{'>_'}</span>
);

export function Default() {
  return <PixelIconFrame icon={<Glyph />} />;
}

Tones

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

const Glyph = () => (
  <span style={{ fontFamily: 'monospace', fontWeight: 700 }}>{'>_'}</span>
);

export function Tones() {
  return (
    <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
      <PixelIconFrame icon={<Glyph />} tone="neutral" />
      <PixelIconFrame icon={<Glyph />} tone="cyan" />
      <PixelIconFrame icon={<Glyph />} tone="green" />
      <PixelIconFrame icon={<Glyph />} tone="gold" />
      <PixelIconFrame icon={<Glyph />} tone="red" />
      <PixelIconFrame icon={<Glyph />} tone="purple" />
      <PixelIconFrame icon={<Glyph />} tone="pink" />
    </div>
  );
}

Sizes

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

const Glyph = () => (
  <span style={{ fontFamily: 'monospace', fontWeight: 700 }}>{'>_'}</span>
);

export function Sizes() {
  return (
    <div style={{ display: 'flex', gap: 12, alignItems: 'center', flexWrap: 'wrap' }}>
      <PixelIconFrame icon={<Glyph />} size={48} />
      <PixelIconFrame icon={<Glyph />} size={56} />
      <PixelIconFrame icon={<Glyph />} size={64} />
      <PixelIconFrame icon={<Glyph />} size={80} />
      <PixelIconFrame icon={<Glyph />} size={112} />
    </div>
  );
}

Shapes

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

const Glyph = () => (
  <span style={{ fontFamily: 'monospace', fontWeight: 700 }}>{'>_'}</span>
);

export function Shapes() {
  return (
    <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
      <PixelIconFrame icon={<Glyph />} shape="square" />
      <PixelIconFrame icon={<Glyph />} shape="rounded" />
      <PixelIconFrame icon={<Glyph />} shape="circle" />
    </div>
  );
}

With Accent

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

const Glyph = () => (
  <span style={{ fontFamily: 'monospace', fontWeight: 700 }}>{'>_'}</span>
);

const Dot = () => (
  <span style={{ width: 6, height: 6, borderRadius: 9999, background: 'currentColor', display: 'inline-block' }} />
);

export function WithAccent() {
  return (
    <PixelIconFrame
      icon={<Glyph />}
      tone="cyan"
      accent={{ icon: <Dot />, position: 'top-right' }}
    />
  );
}