Files
Andrew AquinoandJake Howell 2b7f03deea feat: replace Emoji Mart with Frimousse in the emoji picker (#30526)
> 🤖 This PR was modified by Coder Agents on behalf of Jake Howell.

An alternative to #30361 for DEQ-67 ("Focus indicator is missing" on the
template builder Customizations step). Instead of patching focus
handling into Emoji Mart's shadow DOM, this replaces Emoji Mart (last
released April 2024) with [Frimousse](https://frimousse.liveblocks.io),
a headless picker that we style with Tailwind and our theme tokens.

Fixes DEQ-67
Fixes DEQ-303
Fixes DEQ-201
Fixes DEQ-83

Also fixes 181 `aria-allowed-attr` tickets from Emoji Mart: 180 for
`aria-posinset`/`aria-setsize` on its emoji buttons, and DEQ-370 for
`aria-selected` on its category buttons. Frimousse renders a `grid` of
`gridcell`s instead, and the category buttons use `aria-current`.

- DEQ-303 (`scrollable-region-focusable`): the emoji grid is now a tab
stop.
- DEQ-201 (selected state of the category buttons): the current category
has `aria-current`.
- DEQ-83 (skin-tone button has no expanded state): the button now cycles
tones in place and no longer opens a menu.

<details>
<summary>aria-allowed-attr tickets (181)</summary>

Fixes DEQ-7
Fixes DEQ-8
Fixes DEQ-9
Fixes DEQ-11
Fixes DEQ-17
Fixes DEQ-18
Fixes DEQ-19
Fixes DEQ-26
Fixes DEQ-27
Fixes DEQ-30
Fixes DEQ-31
Fixes DEQ-33
Fixes DEQ-34
Fixes DEQ-41
Fixes DEQ-44
Fixes DEQ-47
Fixes DEQ-53
Fixes DEQ-57
Fixes DEQ-58
Fixes DEQ-65
Fixes DEQ-69
Fixes DEQ-71
Fixes DEQ-72
Fixes DEQ-73
Fixes DEQ-75
Fixes DEQ-77
Fixes DEQ-78
Fixes DEQ-80
Fixes DEQ-84
Fixes DEQ-85
Fixes DEQ-87
Fixes DEQ-89
Fixes DEQ-90
Fixes DEQ-96
Fixes DEQ-97
Fixes DEQ-98
Fixes DEQ-103
Fixes DEQ-109
Fixes DEQ-110
Fixes DEQ-113
Fixes DEQ-114
Fixes DEQ-116
Fixes DEQ-117
Fixes DEQ-119
Fixes DEQ-120
Fixes DEQ-123
Fixes DEQ-126
Fixes DEQ-129
Fixes DEQ-131
Fixes DEQ-135
Fixes DEQ-136
Fixes DEQ-153
Fixes DEQ-154
Fixes DEQ-157
Fixes DEQ-158
Fixes DEQ-160
Fixes DEQ-165
Fixes DEQ-170
Fixes DEQ-171
Fixes DEQ-173
Fixes DEQ-175
Fixes DEQ-179
Fixes DEQ-181
Fixes DEQ-185
Fixes DEQ-187
Fixes DEQ-188
Fixes DEQ-189
Fixes DEQ-192
Fixes DEQ-200
Fixes DEQ-202
Fixes DEQ-206
Fixes DEQ-212
Fixes DEQ-217
Fixes DEQ-220
Fixes DEQ-227
Fixes DEQ-229
Fixes DEQ-239
Fixes DEQ-240
Fixes DEQ-241
Fixes DEQ-245
Fixes DEQ-246
Fixes DEQ-247
Fixes DEQ-249
Fixes DEQ-251
Fixes DEQ-258
Fixes DEQ-262
Fixes DEQ-265
Fixes DEQ-270
Fixes DEQ-280
Fixes DEQ-282
Fixes DEQ-286
Fixes DEQ-296
Fixes DEQ-314
Fixes DEQ-315
Fixes DEQ-320
Fixes DEQ-322
Fixes DEQ-325
Fixes DEQ-326
Fixes DEQ-327
Fixes DEQ-334
Fixes DEQ-335
Fixes DEQ-343
Fixes DEQ-345
Fixes DEQ-347
Fixes DEQ-349
Fixes DEQ-353
Fixes DEQ-359
Fixes DEQ-360
Fixes DEQ-362
Fixes DEQ-367
Fixes DEQ-368
Fixes DEQ-369
Fixes DEQ-370
Fixes DEQ-372
Fixes DEQ-373
Fixes DEQ-375
Fixes DEQ-377
Fixes DEQ-380
Fixes DEQ-382
Fixes DEQ-389
Fixes DEQ-404
Fixes DEQ-405
Fixes DEQ-410
Fixes DEQ-413
Fixes DEQ-414
Fixes DEQ-415
Fixes DEQ-416
Fixes DEQ-421
Fixes DEQ-422
Fixes DEQ-423
Fixes DEQ-425
Fixes DEQ-429
Fixes DEQ-432
Fixes DEQ-435
Fixes DEQ-439
Fixes DEQ-442
Fixes DEQ-444
Fixes DEQ-448
Fixes DEQ-450
Fixes DEQ-451
Fixes DEQ-457
Fixes DEQ-460
Fixes DEQ-464
Fixes DEQ-465
Fixes DEQ-466
Fixes DEQ-468
Fixes DEQ-472
Fixes DEQ-475
Fixes DEQ-478
Fixes DEQ-485
Fixes DEQ-488
Fixes DEQ-490
Fixes DEQ-491
Fixes DEQ-501
Fixes DEQ-506
Fixes DEQ-507
Fixes DEQ-510
Fixes DEQ-513
Fixes DEQ-515
Fixes DEQ-518
Fixes DEQ-521
Fixes DEQ-523
Fixes DEQ-527
Fixes DEQ-528
Fixes DEQ-529
Fixes DEQ-530
Fixes DEQ-534
Fixes DEQ-538
Fixes DEQ-544
Fixes DEQ-547
Fixes DEQ-549
Fixes DEQ-551
Fixes DEQ-553
Fixes DEQ-561
Fixes DEQ-562
Fixes DEQ-571
Fixes DEQ-580
Fixes DEQ-582
Fixes DEQ-584
Fixes DEQ-593
Fixes DEQ-595

</details>


- **Focus indicators:** every control in the picker shows a 2px
`ring-content-link` focus ring: the category buttons, search field,
clear and skin-tone buttons, and the emoji grid. In the grid, DOM focus
stays in the search field or grid while the arrow keys move the active
emoji, the same model as Emoji Mart. The active emoji gets the same
ring, measured at `rgb(97,166,250)` on `rgb(9,9,11)` in dark mode and
`rgb(36,99,235)` on white in light mode. Frimousse announces the active
emoji through a live region.
- **Keyboard:** Tab order is search, skin tone, grid, then the category
buttons; the popover loops back to search. Arrow keys move the active
emoji while focus is anywhere in the picker, and Enter selects.
- **Same UX as before:** category buttons across the top, with Icons
last. One search covers Unicode emoji and the `icons.json` icons. The
skin-tone selector stays.
- **Same stored values:** emoji still save as `/emojis/<file>.png` (the
existing Apple PNGs) and icons as `/icon/<file>`. The file names in
`static/emojis` follow emoji-datasource's rule: they keep U+FE0F only
after characters that default to text style (`263a-fe0f`), while
Emojibase adds it after every character. `emojiToValue` drops it after
characters that are already emoji-style. Emoji newer than the shipped
Apple set (15.1) are left out, as are 3 symbols the set has no image
for.
- **No CDN:** the picker bundles `emojibase-data` instead of Frimousse's
default jsDelivr fetch, which matters for air-gapped deployments.
- **Spritesheet:** the grid draws emoji from one sheet,
`static/emojis/sheet-15.1.2.png` (4.5 MB, from emoji-datasource-apple
15.1.2, the same release as the PNGs), preloaded with the picker chunk
as Emoji Mart did. Frimousse virtualizes the grid, so with one PNG per
tile every category jump cost about 100 requests (2.7 s at 150 ms
latency); with the sheet it costs none. The sheet has a versioned name
because `/emojis` is served with immutable caching and its layout
differs from the old `spritesheet.png`. `pnpm update-emojis` regenerates
the sheet and its cell map (`emojiSheet.ts`) with
`scripts/generate-emoji-sheet.mjs`. Custom icons still render as images.
- **Removed:** `emoji-mart`, `@emoji-mart/*`, their type shim, and the
old `static/emojis/spritesheet.png` (emoji-datasource 15.0.1 layout).
- **Patched Frimousse:** 0.4.0 numbers `aria-rowindex` and
`aria-colindex` from 0, which axe reports as `aria-valid-attr-value`
(ARIA requires 1 or more). `site/patches/frimousse@0.4.0.patch` (a pnpm
patch) makes both start at 1 in `dist/index.js` and `dist/index.cjs`,
and shifts the `[aria-rowindex=...]` lookup that keyboard
scroll-into-view uses by the same amount. Renumbering in our `Row`
component alone would break that lookup. The bundles are minified to one
line, so the patch file is large, but it changes three expressions per
file: `"aria-rowindex":t?void 0:e` to `e+1`, `"aria-colindex":t` to
`t+1`, and `[aria-rowindex="${R}"]` to `${R+1}`. The source-level fix
and regression coverage are submitted upstream in
[liveblocks/frimousse#39](https://github.com/liveblocks/frimousse/pull/39).
Remove the patch only after upgrading to a Frimousse release containing
the fix.
- Note for reviewers: vendoring Frimousse's source into
`site/src/vendor` (as with `message-scroller`) was considered and would
have made the same fix as three readable lines, but was rejected because
we would own about 3,900 copied lines and re-sync them by hand on every
upgrade.

Lazy chunks (gzip): `EmojiPicker` 16 KB (including the 13 KB sheet cell
map) + `emoji-picker` 107 KB, versus about 134 KB for Emoji Mart and its
data.

Known differences and risks:

- Frimousse matches the query anywhere in a name or tag, while Emoji
Mart matches word prefixes. "apple" also returns "people wrestling" (tag
"grapple"). This was accepted during review.
- Frimousse's docs say custom data must be Unicode emoji. Icons are
entries whose `emoji` is the icon path, rendered as images by our
`Emoji` component. This works in 0.4.0 because Frimousse only filters
out unsupported emoji in its built-in data loader. `frimousse` is
pinned, and tests fail if icons stop appearing in search or stop
returning `/icon/...` values.
- Not tested with NVDA or another screen reader.
- Not fixed here: DEQ-130 (category labels aren't headings) and DEQ-115
(dark icons lack contrast).
- Shrinking the bundled emoji data is left for a follow-up.
- The sheet is quantized to 256 colors (as was Emoji Mart's), so a few
gradients differ slightly from the stored PNGs. Until it loads, emoji
tiles are blank.

<details>
<summary>Verification</summary>

- Upstream-tracking follow-up: `pnpm install --frozen-lockfile`, all 14
IconField and emoji-data tests, `pnpm check`, `pnpm lint`, `pnpm
format:check`, and `make lint/emdash` pass. Only the patch preamble and
generated lockfile hashes changed; the installed ESM and CommonJS
bundles are byte-for-byte unchanged.
- `pnpm check`, `lint:oxlint`, `lint:types`, `lint:knip`,
`lint:circular-deps`, and `lint:compiler` pass, and `vite build`
succeeds.
- Vitest: `IconField.test.tsx` covers picking an icon, picking an emoji
that keeps U+FE0F in its file name, picking with the keyboard, clearing
the search, and marking a category as current. `emojiData.test.ts`
checks that every emoji and skin tone maps to a PNG in `static/emojis`,
the FE0F rule, and that deprecated icons are left out. Removing an entry
from the list of unshipped symbols makes the first test fail, naming the
emoji.
- Playwright against Storybook, in dark and light themes: opened the
picker with the keyboard and tabbed through every control, checking the
focus ring on each. Typed "apple" and pressed ArrowDown and ArrowRight;
the active emoji showed the ring. Scrolling the whole list in all six
skin tones produced no failed image requests, and the picker made no
requests outside localhost.
- Storybook Vitest project (`--project=storybook`) for
`IconField.stories.tsx` passes.
- axe-core 4.11 against `OpenPicker` and `KeyboardActiveEmoji`, in dark
and light themes and at 1280px and 320px widths: the picker has no
violations. The remaining results are outside it: `aria-dialog-name` on
the shared `PopoverContent`, plus the page-level `region` and `bypass`.
With the patch, 150 ArrowDown and 150 ArrowUp presses through the full
list, and 40 of each in the "face" results, kept the active emoji fully
in view on every step. The grid viewport is now `role="group"`, because
axe flagged `aria-label` on a div with no role.
- Spritesheet: `emojiData.test.ts` checks that every emoji and skin tone
has a sheet cell and spot-checks coordinates. A Playwright script
compared all 3,775 sheet cells with their PNGs, and swapped 72 rendered
tiles in place for their PNGs; every tile matched its own cell better
than any neighbor. With 150 ms emulated latency, switching between
Flags, Smileys, and Objects made no emoji requests (before: about 100
per category).

</details>

<details>
<summary>Implementation plan and decision log</summary>

**Why Frimousse.** It's a headless set of React parts styled with
Tailwind, with a virtualized grid, keyboard navigation, and a
live-region announcer. Prototypes compared it with emoji-picker-react
4.22.3, which also met the requirements but can only be restyled through
its own CSS variables. @ferrucc-io/emoji-picker was ruled out over
doubts about long-term maintenance.

| Requirement | Frimousse | emoji-picker-react |
| --- | --- | --- |
| Category buttons, Icons last | Custom nav (~40 lines) | Built in |
| One search over emoji + icons | Yes | Yes |
| Icons in the same scroll list | Yes | Yes |
| Keyboard navigation across both | Yes | Yes; one Enter picked a gender
variant, unexplained |
| Stored values unchanged | Yes | Yes |
| No third-party requests | Yes (bundled data) | Yes |
| Tailwind styling | Native | CSS variables only |

**Plan as built:**

1. Dependencies: add pinned `frimousse` 0.4.0 and `emojibase-data`
17.0.0, plus `emojibase` 17.0.0 as a dev dependency for its types;
remove Emoji Mart and its type shim; rename the Vite chunk group.
2. Data (`emojiData.ts`): build Frimousse `EmojiData` from
`emojibase-data/en/data.json` and `messages.json`. Drop the "component"
group, emoji newer than 15.1, and the 3 symbols the Apple set lacks. Map
each emoji to its PNG by emoji-datasource's U+FE0F naming rule, and
offer skin tones only when all five single-tone variants are shipped.
Append the non-deprecated `icons.json` entries as a final "Icons"
category, with the same keywords as Emoji Mart.
3. Picker (`EmojiPicker.tsx`): category `nav` buttons with
`aria-current`. Clicking one clears the search and scrolls to the
category; scrolling updates the current button. The search uses the
shared `InputGroup` with our own clear button, and the native one is
hidden. The grid renders images through `ExternalImage`, without lazy
loading, and the icons are preloaded when the chunk loads, because a
cold cache showed empty tiles for about 0.5 s. The skin-tone button
cycles tones with `useSkinTone`. The grid is a tab stop.
4. `IconField.tsx`: `onEmojiSelect` now passes the stored value
directly. The hidden pre-warm picker is unchanged.
5. Tests and stories as listed under Verification.

6. Spritesheet (added after hands-on testing showed tiles popping in):
draw emoji from emoji-datasource-apple 15.1.2's `sheets-256/64.png` with
a generated cell map, sized with percentages so one cell fills the tile.
Native emoji glyphs were ruled out because they would not match the
stored Apple PNGs; preloading individual PNGs would still miss on
category jumps.

**Changes from the original plan:** replaced the planned generated list
of shipped files (3,787 lines of JSON) with emoji-datasource's U+FE0F
naming rule, which a test checks against `static/emojis`. Used `nav`
buttons with `aria-current` instead of `role="tab"`, since there are no
tab panels. Added a tab stop on the grid. Accepted substring search.

</details>

> This PR was generated by Coder Agents.

---------

Co-authored-by: Jake Howell <jake@hwll.me>
2026-11-05 12:06:28 -08:00
..