feat(metadata|docs|site): reuse metadata from a base icon with $extends: (#4360)

* feat(metadata): reuse metadata from a base icon with `$extends:`

Icon metadata can reference a base icon with an inline `$extends:<icon-name>`
marker in `tags`, `categories` or `contributors`. The marker is replaced in
place with the base icon's resolved values at build time.

- Resolve markers in `readAllMetadata` and `getIconMetaData`, failing on
  unknown icons, self references and circular chains
- Accept markers in `icon.schema.json`
- `pnpm checkIcons` fails on duplicate markers and on literals a marker
  already provides, and runs in CI
- Docs read the resolved metadata index instead of the raw icon JSON
- Use `$extends:alarm-clock` in `alarm-clock-minus`

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(metadata): reuse metadata from a base icon with `$extends:`

Icon metadata can reference a base icon with an inline `$extends:<icon-name>`
marker in `tags`, `categories` or `contributors`. The marker is replaced in
place with the base icon's resolved values at build time.

- Resolve markers in `readAllMetadata` and `getIconMetaData`, failing on
  unknown icons, self references and circular chains
- Accept markers in `icon.schema.json`
- `pnpm checkIcons` fails on duplicate markers and on literals a marker
  already provides, and runs in CI
- Docs read the resolved metadata index instead of the raw icon JSON
- Use `$extends:alarm-clock` in `alarm-clock-minus`

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Fix comments

* Format code

* Update tools/build-helpers/src/resolveMetadataExtends.ts

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Fix resolving icon metadata

* feat(metadata): reuse metadata from a base icon with `$extends:`

Icon metadata can reference a base icon with an inline `$extends:<icon-name>`
marker in `tags`, `categories` or `contributors`. The marker is replaced in
place with the base icon's resolved values at build time.

- Resolve markers in `readAllMetadata` and `getIconMetaData`, failing on
  unknown icons, self references and circular chains
- Accept markers in `icon.schema.json`
- `pnpm checkIcons` fails on duplicate markers and on literals a marker
  already provides, and runs in CI
- Docs read the resolved metadata index instead of the raw icon JSON
- Use `$extends:alarm-clock` in `alarm-clock-minus`

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Fix comments

* Format code

* Update tools/build-helpers/src/resolveMetadataExtends.ts

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Fix resolving icon metadata

* Fix comments

* Format code

* Update tools/build-helpers/src/resolveMetadataExtends.ts

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.github/workflows/linting-icons.yml

@@ -42,6 +42,25 @@ jobs:
         env:
           CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }}
 
+  check-icons:
+    name: Check Icons & Categories
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          cache: 'pnpm'
+          node-version-file: 'package.json'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check icons and categories
+        run: pnpm checkIcons
+
   check-lab-icons:
     name: Check Lab Icons
     runs-on: ubuntu-latest