# Sources and recipes
Where every column of the map comes from, how to trace it, and the traps that produce a confidently wrong row. The whole point of the skill is a cross-reference: each column is checked against at least one other source, never skimmed from one.
## Where each input lives
| Input | Source | Access |
|---|---|---|
| Figma structure (components, nodes, screenshot) | In-repo design export | Local files |
| CMS annotations and overlay geometry | Figma REST API (keychain `FIGMA_ACCESS_TOKEN`); Figma MCP in Dev Mode as the rate-limit-free alternative; the export as offline fallback | Network |
| Screenshot | `screens//screenshot.png` in the design export | Local |
| Specs repo files | `gh api repos///contents/` with `Accept: application/vnd.github.raw`; no checkout needed | Network |
| Redesign app and resources repo | Local checkouts | Local |
| Legacy values | `resources/Localization/Legacy/.json`, a flat snapshot that is refreshed from the label service | Local, network on refresh |
The Android app's committed `strings.xml` is only a key catalog: its values default to the key itself. Real legacy values live in the iOS bundled `language.plist` and, authoritatively, in the label service.
## New keys: the three-way union
A screen's keys come from three places, and each one misses something the others see:
1. **Design export**: read `screens//components-used.md` of each state frame the screen has (default, error, loading, filled...).
2. **Component registry**: each used component's `.json -> localizationKeys`. These are keys the component renders internally, and they are often absent from the screen code.
3. **Screen code**: on iOS, each call site of `..` counts as one element, where `` is the type the project generates its keys into. Pass it to `scan-screen-keys.py` and `verify-map.py` with `--key-type ` (repeatable, or a comma list), or set `"keyType"` in the mapping for `verify-map.py`; the default is `L10n`.
Take the union and tag every key: screen-specific, component-owned, or shared (a reusable component or a shared primitive).
Registry caveat: a shared component such as `ScreenHeader` or `ActionFooter` may list keys that this screen never shows, since the screen supplies its own title. Check the code before a registry key goes into the map.
### Keys the union cannot see
Error, validation and alert strings, and keys assembled at runtime, rarely appear in the design export or the registry. Run the scanner on the implemented screen:
```bash
python3 scripts/scan-screen-keys.py --out scan.json --screen-path --key-type
```
Every `error` and `dynamic` hit becomes a row. Compare the `static` hits with the union; whatever remains is a key the code wires but the map lacks. Skipping this step drops those strings silently.
## New values
Values are authored per key in `Suggested/.json`, one entry per language the project ships, and they are shared by all platforms: one value per key, only the key usage differs per platform.
```bash
python3 scripts/resolve-new-values.py --keys "," --resources-root --langs all \
--catalog
```
Always pass `--catalog`. A missing Suggested file means "not in this snapshot", not "unauthored": the snapshot can lag the shipped catalog. With the catalog the value still resolves and the script names the stale snapshot so it can be refreshed with `snapshot-resources.sh`. Only a key absent from both the snapshot and the catalog is truly unauthored. A catalog entry that is empty, or has no value in any requested language, counts as absent: the lookup then tries the normalised key form and otherwise lists the key as unresolved. Never open an authoring request for a key the catalog resolved.
## CMS copy (Figma annotations)
The content team writes final copy as Dev Mode annotations in the category "Final UX Writing", usually as `TR: ...` and `EN: ...` lines. The text drawn in the design is often placeholder copy; the annotation is the real value.
```bash
python3 scripts/fetch-annotations.py --out _annotations.json --mapping