docs: define public avatar and currency icon design

docs/superpowers/specs/2026-08-10-public-avatar-currency-design.md

@@ -0,0 +1,69 @@
+# Public Avatar Thumbnail and Currency Icon Design
+
+## Goal
+
+Make avatar and currency presentation consistent across the public site:
+
+- user thumbnails in lists and compact cards show only the avatar head at a fixed 40 x 40 pixel size;
+- full-body avatars remain available on profile pages and deliberately large previews;
+- currency amounts use the existing graphical currency icons instead of placeholder letters such as `c`, `cr`, `du`, or `di`.
+
+## Scope
+
+The change covers public-facing pages and shared public components. It includes rankings, leaderboards, shop and badge-purchase currency rows, plus every other compact user list or card that currently renders an avatar directly.
+
+Admin-only screens are outside this visual cleanup unless they reuse a shared public component changed by this work. Profile hero avatars, the main current-user avatar, registration/login previews, and other intentionally large previews retain their full-avatar presentation.
+
+## Avatar Design
+
+Compact user representations will use one shared semantic thumbnail path rather than choosing imager options independently in each page.
+
+The thumbnail contract is:
+
+- request `headOnly: true` from the avatar imager;
+- render at 40 x 40 CSS and image dimensions;
+- preserve pixel-art rendering and contain the image without stretching;
+- prevent the thumbnail container from shrinking into adjacent text;
+- use the user's actual figure and the existing avatar URL fallback behavior;
+- keep useful alternative text based on the displayed username where that context is available.
+
+The existing shared avatar component will be extended with an explicit compact/head-thumbnail variant, or a narrowly focused wrapper will be added if that keeps call sites clearer. Public list and compact-card call sites will migrate to this shared contract. Large/profile call sites will remain explicit so they cannot be accidentally cropped by a global CSS rule.
+
+## Currency Design
+
+All public currency amount rows will use the existing `CurrencyIcon` component and the existing assets under `public/assets/images/icons/currency`.
+
+The mapping is:
+
+- credits: `credits.png`;
+- duckets: `duckets.png`;
+- diamonds/crystals: `diamonds.png`.
+
+Icons will be decorative when the surrounding UI already names the currency, using an empty alternative text to avoid repeated screen-reader announcements. The numeric amount and existing pill/layout styling remain unchanged. Icon size will be fixed consistently for compact amount rows, with no textual placeholder left visible.
+
+## Migration Strategy
+
+1. Add the shared compact avatar contract and focused tests.
+2. Inventory public avatar call sites and classify each as compact thumbnail or large/profile preview.
+3. Migrate every compact call site to the shared head-only 40 x 40 rendering.
+4. Replace textual and empty CSS currency markers in public amount rows with `CurrencyIcon` and the correct currency kind.
+5. Remove CSS rules that exist only to draw obsolete letter-based or background-only markers, while retaining layout classes still used by the amount pills.
+
+This semantic migration is preferred over a global CSS crop because it sends the correct head-only request to the imager and does not risk changing profile avatars.
+
+## Verification
+
+Verification will include:
+
+- automated tests for the compact avatar contract (`headOnly`, fixed dimensions, actual figure propagation);
+- source/component checks ensuring public currency rows use `CurrencyIcon` with the correct mapping and no placeholder letters remain;
+- the existing test, type-check, and build commands relevant to the changed files;
+- visual checks at desktop and narrow widths for rankings, leaderboard, shop, badge purchase, and representative user lists/cards;
+- explicit checks that profile pages and large avatar previews still render full avatars.
+
+## Non-goals
+
+- changing balances or currency business logic;
+- changing the avatar imager service itself;
+- redesigning profile hero sections;
+- modifying admin-only layouts that do not share the affected public components.