# Media

Canonical: https://socra.design/components/media

Images with stable geometry, explicit crop and truthful loading or failure states.

Keep media recognizable and surrounding content stable while the source loads, changes or fails.

Status: partial. Source implementation and canonical specimen are prepared. Public package adoption and rendered catalog verification are required before release.

Library: @socra/web-ui

## Anatomy

- Image requires positive intrinsic width and height and either alt or decorative=true. The frame creates no action or tab stop.
- Image preserves intrinsic aspect ratio; cover reserves that ratio below 900px and stretches inside a card column with a 320px minimum above it. The card owns outer desktop corners; inset cover media uses the shared showcase radius.
- Artwork reserves 20:13 at up to 400px, centered within available width. It contains the full scene by default. Decorative artwork is omitted in forced colors.
- darkSrc follows the app dark class and the nearest explicit theme scope, not the operating system preference. One accessible image description covers both sources.
- placeholderSrc renders a blurred preview of the same source below the full image and is not announced by screen readers. Reduced transparency removes the blur.

## States

- **Rest:** The decoded source replaces its preview without changing geometry.
- **Hover:** Passive media adds no hover treatment or pointer cursor.
- **Focus:** The frame adds no tab stop. Controls placed over media keep their own focus contract.
- **Pressed:** Media is not an action and adds no pressed treatment.
- **Selected:** Media carries no selection state; a host that makes it selectable owns that state.
- **Disabled:** Media has no disabled state. An unavailable source is an Error, not a dimmed image.
- **Loading:** Intrinsic dimensions reserve the complete frame; an optional small preview remains beneath native image loading.
- **Error:** Missing sources, transfer failures and decoding failures remain distinct, preserve the frame and accessible description, and recover when the host supplies a new source.

## Motion

Media changes without decorative animation. Loading, errors, theme changes and reduced motion retain the reserved frame.

## Usage

- Choose complete-image containment or an intentional crop. Contain preserves every edge; cover fills the frame while retaining image proportions.
- Describe meaningful media; mark redundant artwork decorative. One accessible name serves both theme variants, and forced colors can omit decorative scenes.

## Avoid

- Do not recreate the frame in product styles. Shared media owns geometry, corners, placeholder, crop and theme switching.

## Tokens


## Example

```tsx
import { Image } from '@socra/web-ui/media';

<Image presentation="cover" src={cover.src} placeholderSrc={cover.placeholder}
  width={cover.width} height={cover.height} alt={cover.alt} />
```