# Usage and accessibility

## Choose the correct family

Use File System Icons for a file, folder, device, repository, database, cloud location, or storage resource. Use Phosphor for actions such as download, upload, delete, search, open, and navigate.

A download action may use a Phosphor arrow. A downloaded-file entity uses `files/generic/download.svg`.

## Static entity

Use the standalone SVG when the icon state is static. A visible adjacent name is the accessible label, so the image is decorative.

```html
<img
  class="b-file-icon b-file-icon--display"
  src="icons/files/document/pdf.svg"
  alt=""
/>
<span>Quarterly report.pdf</span>
```

If the image is the only content that names the entity, provide a useful `alt` value. Do not use an extension alone when a better entity name is available.

## Live state with the sprite

Load `file-system-icons.css`, then reference the generated symbol. The icon-specific class provides its default palette; `data-state` applies the shared state token.

```html
<link rel="stylesheet" href="icons/file-system-icons.css" />

<svg
  class="b-fsi b-fsi--32 b-fsi--file-pdf"
  data-state="selected"
  aria-hidden="true"
>
  <use href="icons/sprite.svg#fsi-file-pdf"></use>
</svg>
```

Use the standalone SVG through `<img>` for portals opened directly from `file://`. Use the external sprite for applications served from the same HTTP origin.

## Sizes

| Size | Use |
|---:|---|
| 16px | Dense metadata; silhouette and category color are primary |
| 20px | Compact rows and navigation-adjacent entities |
| 24px | Attachments and list items |
| 32px | Default cards and tiles |
| 48px | The single entity tile: a full-bleed 48px icon in a 48px squircle tile |
| 64px | Media cards and catalog previews |
| 128px | Large empty states and high-resolution previews |

Do not crop or stretch the SVG. Preserve a square box and the `0 0 64 64` viewBox. Three-character labels share one font scale; four-character labels share a slightly smaller scale with protected side breathing. Do not resize individual labels to make their visible widths equal.

## Deliverable groups

One full-bleed tile serves the whole family: isolated tiles, deliverable rows, and folder summaries fill a 48px squircle tile with a 48px entity, and the drawing's built-in optical margins provide the framing. Keep the visible filename and metadata outside the SVG. Opening an entity and downloading it are separate actions.

There is no upload entity. When a user uploads a file, show the icon of the file's own type and communicate progress with the `uploading` state; the `uploads` folder remains available as a location.

Use the native `.b-deliverable-folder` pattern when several final files belong to one delivery. The folder summary controls disclosure; the folder and every child file expose a separate icon-only download action with an accessible name. Do not display the word “Download” in these compact actions.

## States

Supported states are `default`, `hover`, `selected`, `active`, `uploading`, `downloading`, and `syncing`. Transfer states keep the categorical palette and communicate activity through a pulse only; error, warning, success, and disabled are expressed by the surrounding component, text, and ARIA — never by recoloring the entity.

State changes never modify path data. They change only palette, filter, opacity, or motion. Uploading, downloading, and syncing use the same restrained pulse; reduced-motion preferences disable it.

Always expose state through text or semantics such as `aria-current`, `aria-selected`, `aria-busy`, `aria-invalid`, or a visible status label. Color and motion are supplementary.

## Themes and contrast

The entity palette is categorical and remains stable in light and dark themes. Place icons on neutral Baluarte surfaces. Very dark entity palettes may carry a tokenized low-contrast edge on the existing body path; do not recreate that edge with component borders, shadows, or duplicated SVG geometry. The generator selects light or dark mark ink with at least 4.5:1 contrast against the body color.

Do not recolor PDF red as danger, database indigo as selection, or folder amber as warning. Component state and accessible text disambiguate category from feedback.

## RTL

Document and folder geometry does not mirror. Physical devices, media symbols, labels, brands, and storage objects also keep their direction. Directional state and action glyphs remain in the Phosphor action layer.