---
title: "Media"
description: "Pictures, drawings and documents from somewhere else."
canonical: media.html
navigation-title: "Media"
---

<a id="media"></a>

# Media

- [sds-image](#sds-image)
- [sds-figure](#sds-figure)
- [sds-embed](#sds-embed)
- [sds-compare](#sds-compare)
- [sds-lightbox](#sds-lightbox)

Pictures, drawings and documents from somewhere else. One rule runs through
all of them: **every picture is a link**. One `<img>`, one file, and no
element decides anything about what is in the file.

A drawing as an image renders in a document of its own, where none of this
system's tokens exists. It keeps whatever grey its author wrote as the
fallback. A reference into the file lets it read the page's tokens.
[Artwork](../../design-system/artwork.md) says what Firefox and Safari have to ship
before a site can rest on that.

**A picture with its own colours gets a ground drawn for them.** The
figure's frame, a card's picture and the viewer all take `--surface-art`,
the one surface with a single value for both modes. A diagram a tool
exported is usually dark line art on nothing. On a dark ground the page
contradicts its own picture.

> [!NOTE]
> Nothing here takes a flag for the mode a picture arrives in, and the
> finishing step reads no drawing. What is in its own file lays out an
> image, and it is the same picture in light and in dark.

<a id="component-sds-image"></a>

<a id="sds-image"></a>

## sds-image

A picture, and nothing around it.

```html
<sds-image src="/art/pipeline.svg" alt="Source, build, published site"></sds-image>
<sds-image src="/art/pipeline.svg" alt="Source, build, published site" zoomable></sds-image>
<sds-image class="sds-signet" src="/soul/assets/signet.svg" alt=""
  width="24" height="24"></sds-image>
```

<a id="confval-sds-image-src"></a>

**`src`**

- Type: string
- Required

<a id="confval-sds-image-alt"></a>

**`alt`**

- Type: string
- Required

What the picture shows, for a reader who cannot see it. Empty where the
text beside it says the same thing: a mark in a lockup whose wordmark
spells the name. The picture then hides instead of an announcement with
no name.

<a id="confval-sds-image-width"></a>

**`width`**

- Type: number

<a id="confval-sds-image-height"></a>

**`height`**

- Type: number

Both, for a picture no stylesheet sizes. The file's own coordinate system
keeps the proportions inside them. A 5:4 mark in a square box draws 5:4
and centred, never stretched.

<a id="confval-sds-image-zoomable"></a>

**`zoomable`**

- Type: boolean
- Default: false

A press opens the picture at its made size. The trigger is a link to the
file, so a surface with no script still opens it. The element takes the
press over only after its upgrade. For a picture shrunk into its
column, and never for a mark in a lockup.

<a id="confval-sds-image-class"></a>

**`class`**

- Type: string

The class a caller gives is the one the picture renders with. That is why
a signet is `<sds-image class="sds-signet">`, and nothing in this
element has to know what a signet is.

> [!NOTE]
> The element takes no content, but it takes a **fallback**. That is the
> same picture in the class layer, for a surface that renders before a
> script and for a reader who runs none. The element redraws it and the server's
> copy goes, because light DOM otherwise leaves two pictures in one box.

<a id="component-sds-figure"></a>

<a id="sds-figure"></a>

## sds-figure

A picture and the claim it makes. The caption is mandatory and not a title.
A picture whose point a reader has to infer means something different to
every reader. So the sentence under it states the claim the picture stands
for.

```html
<sds-figure src="/art/pipeline.svg" alt="Source, build, published site"
  caption="Every route resolves to the same tokens." zoomable></sds-figure>
```

<a id="confval-sds-figure-src"></a>

**`src`**

- Type: string
- Required

<a id="confval-sds-figure-alt"></a>

**`alt`**

- Type: string
- Required

<a id="confval-sds-figure-caption"></a>

**`caption`**

- Type: string | markup

Can also stand between the tags as a `<figcaption>` with the caption
class. That is the form for a caption with a link or a literal in it. It
is also the form for a page read before the element upgrades.

<a id="confval-sds-figure-width"></a>

**`width`**

- Type: number

<a id="confval-sds-figure-height"></a>

**`height`**

- Type: number

The picture's own size, where a document declared one. A figure fills its
column and needs neither.

<a id="confval-sds-figure-zoomable"></a>

**`zoomable`**

- Type: boolean
- Default: false

A press opens the drawing at its drawn size. The trigger is a link to the
file, so a surface with no script still opens it. The element takes the
press over only after its upgrade. Worth it for anything wider than
its column, pointless for a photograph.

> [!NOTE]
> A picture a renderer already wrote between the tags **wins** over
> `src`. A rewrite replaces a picture the reader can see with a second
> request for the same file.

<a id="component-sds-embed"></a>

<a id="sds-embed"></a>

## sds-embed

A document from somewhere else, in a frame this page controls. An iframe
arrives with a size that has no relation to its column, and browsers draw it
with an inset border out of 1996. This gives it the hairline and the sunken
plane every other block here has.

```html
<!-- A video: no size of its own, so it fills the column at a ratio. -->
<sds-embed src="https://…" label="The release talk" ratio="16 / 9"
  allow="encrypted-media; picture-in-picture; web-share" allowfullscreen
  caption="Twelve minutes, from the 1.4 release."></sds-embed>

<!-- A card: made at a size, so the frame keeps it and scrolls. -->
<sds-embed src="/_cards/…" label="Surfaces" width="700" height="420"></sds-embed>
```

<a id="confval-sds-embed-src"></a>

**`src`**

- Type: string
- Required

An empty one is not nothing. A browser resolves it against the current
document and embeds the page in itself, so the frame stays empty instead.

<a id="confval-sds-embed-label"></a>

**`label`**

- Type: string
- Required

What the frame holds, in a few words. It becomes the accessible name. An
unnamed frame announces as "frame", and a reader skips it. Not `title`, which
on the element is a tooltip over the frame and the caption both.

<a id="confval-sds-embed-ratio"></a>

**`ratio`**

- Type: string
- Default: "16 / 9"

The shape the frame holds while it fills the column, as CSS writes it.
For a video, a map or anything else with no size of its own.

<a id="confval-sds-embed-width"></a>

**`width`**

- Type: number

<a id="confval-sds-embed-height"></a>

**`height`**

- Type: number

The size of the document, in pixels. Both together, and **without a
ratio**, make the frame fixed. It is exactly this wide, and it scrolls
instead of a reflow of what it holds.

<a id="confval-sds-embed-caption"></a>

**`caption`**

- Type: string

<a id="confval-sds-embed-allow"></a>

**`allow`**

- Type: string

The permissions policy of the frame. A video player asks for what it
needs. A card asks for nothing, and gets nothing.

<a id="confval-sds-embed-allowfullscreen"></a>

**`allowfullscreen`**

- Type: boolean
- Default: false

> [!NOTE]
> The frame does not load lazily, on purpose. An embed is the evidence on
> the page, and one that loads on scroll is blank in every screenshot.

<a id="component-sds-compare"></a>

<a id="sds-compare"></a>

## sds-compare

Two pictures side by side, each with its claim. A concept shows what stands
and what it proposes, and a reader reads the two against each other. So
they stand in one row, each an [sds-figure](#component-sds-figure)
with its own caption, under a word that says which is which.

```html
<sds-compare
  before-src="/shots/status.png" before-alt="…" before-caption="The row says what the source does now."
  after-src="/shots/source.png" after-alt="…" after-caption="The page keeps the last two reads."
  before-label="As it stands" after-label="Proposed"
  zoomable
></sds-compare>
```

The halves reflow by their own width, never by the window. A half narrower
than a picture reads is no half, and the two stand one under the other
instead. Each half is a figure, so a press opens either at its own size. A
picture arrives as every picture does: a link to a file, in the colours of
its export.

<a id="confval-sds-compare-src"></a>

**`before-src, after-src`**

- Type: string
- Required

The two files. `before-alt` and `after-alt` say what each shows for
a reader who cannot see it; `before-caption` and `after-caption`
carry the claim each makes.

<a id="confval-sds-compare-label"></a>

**`before-label, after-label`**

- Type: string
- Default: "Before", "After"

The word over each half. The caller's: `As it stands` and `Proposed`
where a paper says it that way, or the names of two pages read against
each other.

<a id="confval-sds-compare-zoomable"></a>

**`zoomable`**

- Type: boolean
- Default: false

A press opens either picture at its own size.

<a id="component-sds-lightbox"></a>

<a id="sds-lightbox"></a>

## sds-lightbox

A drawing at its drawn size, on the platform's `<dialog>`. So the page
behind it goes inert, the focus moves in and comes back, and Escape closes.
The surface is not the modal's. A modal stops at a reading measure because a
reader reads what is inside one, and a reader looks at a drawing.

The surface is a stage, not a box around the file: as much of the screen as
it can take without the edges. The picture fits into it and stands in the
middle, whichever way round it is. A picture smaller than the stage keeps
its own size, since a larger draw only blurs it. The page behind it stops
its scroll while it is open. The platform makes the rest inert, and a wheel
over the backdrop is not.

```html
<sds-button for="the-drawing">Open the drawing</sds-button>
<sds-lightbox id="the-drawing" src="/art/pipeline.svg"
  alt="Source, build, published site"></sds-lightbox>
```

<a id="confval-sds-lightbox-src"></a>

**`src`**

- Type: string
- Required

<a id="confval-sds-lightbox-alt"></a>

**`alt`**

- Type: string
- Required

<a id="confval-sds-lightbox-caption"></a>

**`caption`**

- Type: string

What the drawing claims, in the head. The same sentence the figure
carries, so the open is not a change of subject.

<a id="confval-sds-lightbox-open"></a>

**`open`**

- Type: boolean
- Default: false

It answers `sds-command`, `show`, `close`, `toggle`, and has
`show()` and `close()` for a page that calls them. `sds-figure` needs
none of it. It owns its viewer and calls `show()` itself.

> [!NOTE]
> [Diagrams](../../design-system/diagrams.md) for how to make a drawing a page can
> reference, and [Artwork](../../design-system/artwork.md) for what belongs in one.