> ## Oymyakon DS index
> Fetch the full index at: https://super-dollop-pzmo65r.pages.github.io/llms.txt
> HTML preview: https://super-dollop-pzmo65r.pages.github.io/icon-container.html
> Source: specs/primitives/icon-container.md

---

# IconContainer · Oymyakon DS 3

> The box an icon from the DS library sits in: one glyph, four sizes, two ways to size — the glyph
> inside a fixed 24 box, or the whole box with the glyph — and three states.

**Version:** 3.0.5 · **Status:** Draft · **Figma:** `[IconContainer] 3.0` (main components file
`7vdl5YkZFDWvh9QvSmydsH`, page `54:1192`; the public master `8216:8096` wraps an instance of the set
`Container` `8216:7494` — `Modify` × `Size` × `State` + the `Icon` swap; Specification frame `3071:4387`)

---

## 1. Description

IconContainer holds one icon from the DS library ([`icon-catalog.md`](https://super-dollop-pzmo65r.pages.github.io/icons.md)) and gives it a
size, a colour and a state. The Specification frame: "Container holding an icon", a base component
other components place their icons in — Cell, Button, Chips, TextField and more.

It has two configurations (Figma `Modify`):

- **Icon only** — the box stays `s24`; the glyph is sized inside it (24 / 20 / 16 / 12) and centred.
  For a glyph matched to text size while the layout keeps a larger box — a badge, a row.
- **Whole container** — the box and the glyph are one size (24 / 20 / 16 / 12). For a small icon
  next to text, where the row's height stays the text's.

The box itself is invisible by default — no fill, no border, no radius. Sizes scale with the SP modes
to 150% ("the icon set supports built-in A11y sizing with step increase up to 150%").

### Platform implementations

| Platform | Entry point | Version | Notes |
|---|---|---|---|
| Android | `DsIconContainer` | 3.0 | The manifest seed binds the set `8216:7494`; the Android bridge no longer lists it (sync 2026-11-12) — to confirm with the team |
| iOS | — | — | Icons sit in each component's own slot; no standalone entry in the bridge |
| Web | `src/shared/shared.css` (`.icon-container`) | 3.0.5 | Reference implementation; preview page `src/icon-container.njk`. Components that shipped before it draw their glyphs in their own slots |

---

## 2. Anatomy

```
[IconContainer] (.icon-container)     the box · Icon only: s24 · Whole container: the glyph's size
└── Icon (svg)                        a DS icon (Figma Icon swap) · centred · TextAndIcon/Primary
                                       Skeleton: a Skeleton shape in its place
```

| Part | Required | Description |
|---|---|---|
| **Box** | Required | `s24` square in Icon only; the glyph's size in Whole container. No fill by default — "bg color: empty", any `Background/*` token on an instance |
| **Icon** | Required | One SVG from `icons/` (Figma `Icon` instance swap), `fill="currentColor"` for outlined / filled. Always centred in the box |

---

## 3. Variants and sizes

| Axis | Values | Default | Web mechanism |
|---|---|---|---|
| **Modify** | `icon-only` · `whole-container` | `icon-only` | `.icon-container` (icon only) · `.icon-container--whole` |
| **Size** | `24` · `20` · `16` · `12` | `24` | `.icon-container--20` / `--16` / `--12` set `--icon-container-size` |
| **Icon** | any DS icon | `heart-outline` in Figma | The inline `<svg>` child |
| **State** | `standard` · `disabled` · `skeleton` | `standard` | `.icon-container--disabled` · `.icon-container--skeleton` |
| **Icon colour** | any `TextAndIcon/*` token — outlined and filled only | `TextAndIcon/Primary` | `color` on the root (the SVG uses `currentColor`) |
| **Background** | none · any `Background/*` token | none | `--icon-container-fill` on the instance |

- `double-color`, `color` and `flags` icons carry their own colours and are not tinted.
- `color/carbase` and `color/splash` icons have non-standard proportions and do not fit the sizes —
  they are not placed in an IconContainer.

### 3.5 RTL — directional icons

The number is kept from the earlier layout of this file: component specs cite the list below as
"`icon-container.md` § 3.5".

The SVG files are stored in their original form. An icon with meaningful horizontal direction carries
the `rtl: true` marker, and in an RTL interface it is mirrored (`scaleX(-1)`) —
`.icon-container--rtl` on the web, under `[dir="rtl"]`. Every other icon is `rtl: false` and never
mirrors.

#### Icons with `rtl: true` (32 icons)

The list is defined in `icons.html`. All belong to the `outlined` style.

| Icon | Category |
|---|---|
| `new-orders` | actions |
| `sort` | actions |
| `sort-down` | actions |
| `hint-outline` | actions |
| `attach` | actions |
| `progress` | actions |
| `undo-rotate` | actions |
| `enter` | actions |
| `exit` | actions |
| `share-outline` | actions |
| `chevron-left` | navigation |
| `chevron-right` | navigation |
| `chevron-left-small` | navigation |
| `chevron-right-small` | navigation |
| `cell-chevron` | navigation |
| `back-ring` | navigation |
| `forward-ring` | navigation |
| `back-arrow-left` | navigation |
| `forward-arrow-right` | navigation |
| `collapse-left` | navigation |
| `collapse-right` | navigation |
| `search-catalog` | actions |
| `send` | communication-media-art |
| `alongtheway` | map |
| `location-outline` | map |
| `car` | transport |
| `cargo` | transport |
| `doc` | documents |
| `doc-error` | documents |
| `doc-verified` | documents |
| `invoice` | finance |
| `loader-cart` | finance |

---

## 4. States

| State | What shows |
|---|---|
| **Standard** | The glyph in `TextAndIcon/Primary` (or the instance's colour); the box with no fill (Figma `State=Default`) |
| **Disabled** | The glyph in `TextAndIcon/Disabled`. A colour, not an interaction state — the control that holds the icon owns the disabled state |
| **Skeleton** | A Skeleton shape in the glyph's place, while the data loads — the glyph's size, radius `s6` (24, 20) or `s4` (16, 12), the Skeleton's `OnWhite` fill and wave |

- IconContainer is not interactive: no pressed or hover state of its own.
- Figma flags: the Skeleton shape binds `SP/130% ratio` while the frame's text says "(max*150%)" for
  its size; the Whole container 20 Default glyph binds `SP/130% ratio/s20` where every other glyph
  binds `SP/150%`; the Skeleton fill is the legacy `Additional/Skeleton/Start` (the DS token is
  `Skeleton/OnWhite`).

---

## 5. Animation and behavior

IconContainer has no motion of its own (reference:
[`motion-rules.md`](https://super-dollop-pzmo65r.pages.github.io/motion.md)). The frame's Animation block reads "TBD".

- The Skeleton wave is the Skeleton's — `Patterns/Shimmer`, zeroed under reduced motion.
- A press belongs to the control that holds the icon (`pushHighlight`, `pushButton`).
- A spinner glyph rotates on `Patterns/Spin` — the SVG's motion, not the box's.

---

## 6. Color tokens

| Element | Token | Notes |
|---|---|---|
| Icon — Standard | `var(--text-and-icon-primary)` | Default; any `TextAndIcon/*` token for outlined / filled icons ("may be changed to any DS style") |
| Icon — Disabled | `var(--text-and-icon-disabled)` | |
| Box fill | none | Any `var(--background-*)` token on an instance (`--icon-container-fill`). The frame lists "Primary, Alt. Primary, Secondary, Alt. Secondary, Tertiary, Alt. Tertiary" — legacy names; today's group is `Background/*` |
| Skeleton shape | `var(--skeleton-on-white)` | The Skeleton component's fill and wave |

---

## 7. Typography

IconContainer has no text.

---

## 8. Spacing

Sizes scale with the SP modes to 150% (`SP/150% ratio` → `var(--sp-sN)`); the Skeleton radius stops at
130% (`SP/130% ratio` → `var(--sp-130-sN)`).

| Property | Token | @100% | Notes |
|---|---|---|---|
| Box — Icon only | `var(--sp-s24)` | 24 | Fixed at 24 whatever the glyph's size |
| Glyph — 24 / 20 / 16 / 12 | `var(--sp-s24)` / `--sp-s20` / `--sp-s16` / `--sp-s12` | 24 / 20 / 16 / 12 | `--icon-container-size` |
| Box — Whole container | `var(--icon-container-size)` | = the glyph | |
| Inset — Icon only | — | 0 / 2 / 4 / 6 | Not a token: the glyph is centred in the `s24` box |
| Skeleton radius — 24, 20 | `var(--sp-130-s6)` | 6 | |
| Skeleton radius — 16, 12 | `var(--sp-130-s4)` | 4 | |

---

## 9. Usage context

From the frame:

1. **Adjusting the icon inside its container** (Icon only) — visual alignment while the box stays
   fixed: a glyph matched to text size in a badge, with a larger box kept for layout.
2. **Resizing the whole container** (Whole container) — a small icon matched to text size next to the
   text, the row keeping its height.

### When not to use

- An icon with a shaped, filled background — that is a [Squircle](https://super-dollop-pzmo65r.pages.github.io/squircle.md).
- `color/carbase` and `color/splash` artwork — non-standard proportions; use
  [ImageContainer](https://github.com/inDriver/oymyakon-ds/blob/main/specs/primitives/image-container.md).
- A tappable icon on its own — the control (Button, Squircle Button) carries the target; the icon sits
  inside it.

### Rules

1. Icons only from the `icons/` catalogue; no hand-drawn paths.
2. No hard-coded colour on the SVG — `currentColor` and a `TextAndIcon/*` token on the root.
3. No colour on `double-color`, `color` and `flags` icons.
4. Only the four sizes — no 18 or 22.

---

## 10. Accessibility

- IconContainer carries no semantics of its own and is never a focus stop.
- An icon beside text is decorative: `aria-hidden="true"` on the `<svg>`.
- An icon that stands alone and carries meaning: `role="img"` and an `aria-label` on the `<svg>` — or,
  inside a control, the label on the control and the icon `aria-hidden`.
- Skeleton: hidden from assistive technology; the loading region around it announces (the Skeleton
  rule).
- Disabled is a colour; the control that holds the icon announces its own state.
- Directional icons mirror in RTL (§ 3); the rest never do.
- Forced colours: `currentColor` icons follow the system text colour.

---

## 11. Analytics and coverage contract

Reference: [`docs/prototype-analytics-and-coverage.md`](https://github.com/inDriver/oymyakon-ds/blob/main/docs/prototype-analytics-and-coverage.md).

| Field | Value |
|---|---|
| `data-ds-component` | `icon-container` |
| Coverage unit | No by default when nested inside another component; optional when auditing icon-only composition |
| Tap target model | None — not interactive |
| Actions | None |
| Internal targets | None |
| Emits value | No |

```html
<span class="icon-container icon-container--20" data-ds-component="icon-container" data-ds-preset="icon-only">
  <svg viewBox="0 0 24 24" aria-hidden="true">…</svg>
</span>
```

`data-ds-preset` = `icon-only` | `whole-container`; `data-ds-state` = `standard` | `disabled` |
`skeleton` when it is not Standard.

---

## Changelog

| Version | Date | Change |
|---|---|---|
| 3.0.5 | 2026-11-12 | Rewritten to the Figma `[IconContainer] 3.0` (master `8216:8096`, set `Container` `8216:7494`, Specification frame `3071:4387`) for the first web build. **Modify** `icon-only` (the glyph in a fixed `s24` box) · `whole-container` (box = glyph); **Size** 24 / 20 / 16 / 12 (was 16 / 20 / 24 / 32); **State** Standard / Disabled / Skeleton (was "no states"); an optional `Background/*` fill. Sizes on `SP/150%` (full), the Skeleton radius cap130. Legacy token names (`--color-text-icon-*`) replaced by the semantic ones; `data-ds-component` = `icon-container`. The RTL directional-icon list kept, under its old number § 3.5 (component specs cite it). Web build: `shared.css` `.icon-container` + preview page (seven sections); a TextRow slot now hugs an IconContainer (TextRow 1.3.1), which the Usage example needs. Figma flags in § 4 and § 6. |
| 3.0.4 | 2026-04-29 | Added prototype analytics and DS coverage contract: no tap analytics by default. |
| 3.0.3 | 2026-04-23 | RTL icons are stored in their original SVG form without physical transformations. The `rtl: true` tag is an informational marker. Mirroring (`scaleX(-1)`) is applied by the component in RTL context. RTL badges restored in `icons.html`. Script `restore-rtl-icons.js`. |
| 3.0.2 | 2026-04-23 | The `rtl: false` default rule for all icons is now explicitly defined: in the property table and in the behavior description. `rtl: true` is set only for the 32 icons from the list in § 3.5. |
| 3.0.1 | 2026-04-23 | Added `rtl` property. RTL icons render with `transform: rotateZ(180deg)` as the base state. List of 32 RTL icons. |
| 3.0.0 | 2026-04-23 | Initial version within Oymyakon DS 3. Inheritance from Slot, properties `icon` / `size` / `color`, tinting rules by icon style (outlined/filled — tintable, others are not), default color `TextAndIcon/Primary`. CSS implementation, usage context. |