# Font Subsetting

## Objective

Load only the glyphs a page needs, without breaking the alphabets it did not expect.

Per-script font subsets with declared character ranges and a fallback order for characters no subset covers.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Inventory the weights, styles, and families the app genuinely renders. Most projects ship two or three weights they never use, and dropping those is a larger win than any subsetting.
2. Split each family by writing system and declare the character ranges each file covers, so a page that renders only Latin text never fetches the Cyrillic or Greek file.
3. Choose subsets from the locales the product supports and the languages its users actually write in, not from the words currently on the page.
4. Define the fallback chain explicitly and pick system fallbacks with similar metrics, so the swap from fallback to web font does not move the text under the reader's eye.
5. Do not subset by scanning the current copy for characters in use. Translations, user-generated names, and pasted content will contain characters that scan never saw, and those characters will render as empty boxes.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Subsets must be chosen by the language coverage the product commits to. A subset built from today's marketing copy will fail the first customer whose surname carries a diacritic outside it.
- A page mixing scripts — a Japanese comment under an English article, an Arabic name in a Latin table — must fetch each needed subset independently and render both correctly, with no visible mismatch in size or baseline between them.
- The same face requested under two URLs, or reachable through both a subset file and a full file, downloads twice. Confirm each face is served from one canonical source across every route.
- A character no loaded subset covers must fall through to a system font that has it, not render as a blank box. Decide and verify what happens for emoji, mathematical symbols, and rare punctuation.
- Decide deliberately whether text is invisible while the font loads or shown immediately in the fallback, and hold that decision consistently — an app that does both looks broken.
- A variable font carrying every weight may beat several static instances or may be far larger; measure the real files rather than assuming.
- Font declarations, preloads, and loading behaviour belong here; the Critical CSS Strategy brief owns what is inlined for first paint, and the two must not both inline the same font-face rules.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Only the weights and styles the app renders are shipped.
- [ ] Each family is split by writing system with declared character ranges.
- [ ] A page containing a single script fetches only that script's files.
- [ ] A mixed-language page renders every script correctly, each from its own subset.
- [ ] No face is downloaded twice under different URLs across the app.
- [ ] Characters outside every subset fall back to a system font that renders them rather than showing empty boxes.
- [ ] The fallback stack is metrically close enough that the swap causes no visible reflow.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.