# Shared icon library

A standalone collection of Microsoft artwork and reusable symbols. Everything needed to browse and use the included icons is in this repository. No presentation project, template bundle or external checkout is required.

Open [the searchable catalogue](index.html). It works directly from disk, without a server or internet connection. The catalogue starts with favourites; typing a search removes the favourites limit while keeping the selected collection. Product and solution marks appear first in every view. Choose **Products & solutions** from the Collection menu to browse product marks across all source collections. Find service/resource and generic icons in their source collections or through search. Switch the preview background and select an icon to download files or copy an asset entry.

## Included collections

| Collection | Selection |
|---|---|
| Microsoft product pages | Current page artwork for Purview, Microsoft 365 Copilot, Microsoft Copilot, SharePoint, Teams, Word, Excel, PowerPoint, Outlook, OneNote, OneDrive, Defender, Clipchamp and Loop; original Exchange PNG |
| Power Platform and agents | Power Platform, Power Apps, Power Automate, Power Pages, Dataverse, AI Builder, Copilot Studio and Agent 365 |
| Entra | Official colour and monochrome product-family and identity icons |
| Azure | The V24 architecture pack, with byte-identical copies deduplicated and alternative source locations retained |
| Fabric | Largest available SVG per item/colour/non-item symbol; repetitive UI glyphs and smaller size variants omitted |
| Dynamics 365 | Official product family and app icons |
| Fluent concepts | 36 filled symbols with original, ANS light-blue, turquoise and navy versions |
| Microsoft 365 architecture, 2024 | The archived pack's dark-blue concept symbols, deduplicated; not a current product-logo pack |
| ANS symbols | The six existing grouped-list vector symbols, with original provenance retained |

The initial collection was retrieved on 15 September 2026. See [icons.json](icons.json) for exact entries and [sources.json](sources.json) for collection sources, selections and terms. This is broad coverage, not a claim to include every Microsoft product or certify that every service in an official pack is still available. Official packs can retain old names. Prefer current product-page favourites where available and check names against the subject being taught.

## Icon classification

These are maintained artwork roles, separate from the source collection and favourite status:

- **Product / solution:** distinctive standalone logo-style artwork, such as the Azure mark, Foundry marks, Microsoft 365 app icons and Fabric workload identities. Being a named Azure service or resource is not enough to enter this group.
- **Service / resource:** architecture and interface symbols for named services, resources, components and items. Examples include Advisor, API Management, App Services, Application Insights, Entra ID Governance and Fabric Lakehouse.
- **Generic icon:** reusable symbols for people, documents, arrows, locks, folders, actions and similar concepts.

All three can be used in diagrams. The role describes the artwork, not where it is allowed to be used. The Products & solutions view reuses the original entries without duplicating files or changing IDs. Each card shows its role; its details explain the classification. Sorting puts product marks first, then favourites, source collection and name.

The product group is a deliberately narrow visual selection based on the user's marked examples. The Azure pack was reviewed as contact sheets: the Azure, AI Foundry, AI Studio and Azure AI Foundry IQ marks are included; cloud-and-gear, database, network, shield-with-badge and other service/resource illustrations are excluded. A familiar service name, an abstract shape or a colourful gradient alone does not establish a product mark. Entra's identity and family marks, including matching monochrome silhouettes, remain products; its globe, person and card compositions are service/resource symbols.

Fabric's source filenames distinguish `color`, `item` and `non-item` artwork. The 13 named colour identities were visually checked against the marked examples. Its sample-workload placeholder is excluded from products; tiled items stay with services/resources, and the generic folder and empty placeholder stay with generic icons.

Maintain `kind` (`product`, `resource` or `generic`) and `classification_reason` in [icons.json](icons.json), then rebuild. New product candidates need a visual check against these examples; do not promote an entire pack or infer the role from its service names. This is an editorial browsing aid, not a Microsoft trademark classification or a claim of current product availability. Source names, dates and usage terms remain separate.

## Use the icons

Open `index.html` directly from disk. No installation, server or internet connection is needed for browsing or downloads. Keep the repository folders together: the HTML catalogue loads previews from `png/`.

1. Search or select a collection, then open an icon.
2. Choose a colour version where available and check it against white and navy backgrounds.
3. Download the SVG for scalable artwork or the PNG for compatibility, then insert it into your document, presentation, diagram or application.

SVG-derived PNGs are 512 pixels on their longest edge, preserving aspect ratio. Original raster artwork is not upscaled; Exchange remains 72 × 72. A PNG is a single raster image, not a collection of editable vector shapes.

**Copy asset entry** exports an optional YAML record with provenance and a checksum. The full [assets.yml](assets.yml) contains all records. Every `file` path is relative to this library's root:

```yaml
assets:
  microsoft-purview:
    file: png/microsoft-purview.png
    alt: Microsoft Purview product icon
```

When using a record in another project, copy the corresponding image and set `file` to its location there, according to that project's path rules. This library does not include or require a deck renderer. Asset IDs remain stable, but exported paths no longer assume a parent project's directory layout.

## For agents and scripts

The published site has an index that you can point an AI agent or script at. Replace `<site>` with the GitHub Pages address:

- `<site>/llms.txt` gives usage rules, every product and solution mark with links, and pointers to the full lists.
- `<site>/llms-full.txt` lists every icon on one line each: name, ID, kind, collection, SVG and PNG links. Products come first.
- `<site>/api/icons.json` holds machine-readable metadata, file URLs, provenance, checksums and per-collection usage terms.
- `<site>/api/changelog.json` lists icons added, removed and updated, newest first.

Every icon has predictable file URLs: `<site>/svg/<id>.svg` and `<site>/png/<id>.png` (512 pixels on the longest edge). These are always the original artwork. Fluent's ANS colour variants are at `<id>-ans-light-blue`, `<id>-ans-turquoise` and `<id>-ans-navy`. Raster-only originals such as Exchange have no SVG. The catalogue page links the index under **For agents**. The index is generated when the site is deployed, so it isn't in the repository.

## Style and usage

- Use official product artwork to identify the named Microsoft product, with its label nearby. Retain its original colours, proportions and orientation.
- Use Fluent symbols for generic concepts such as people, documents, locks, policies and devices. Keep one filled visual family; choose a suitable ANS colour for contrast. The original MIT licence is included in [licenses/fluent/LICENSE](licenses/fluent/LICENSE).
- Use the two background previews to check appearance. Colour variants do not automatically adapt after insertion into a deck.
- Architecture downloads and Microsoft website artwork have separate usage terms. The source records preserve this distinction. Web artwork does not inherit an architecture pack's permission. Product-specific training/documentation is the intended use here; apply the relevant partner/brand terms for marketing uses. The Entra pack explicitly excludes marketing communications.
- A file's presence on an official website verifies its source, not unrestricted reuse. Retain the collection's terms and any supplied notices with distributions. [Microsoft copyrighted-content guidance](https://www.microsoft.com/en-us/legal/intellectualproperty/copyright/permissions) and the collection-specific pages are linked from each catalogue entry.

## Files and maintenance

| File/folder | Role |
|---|---|
| `originals/` | Unchanged acquired SVGs and PNGs; permanent build inputs |
| `licenses/` | Supplied usage documents, Fluent MIT notice and local ANS provenance |
| `icons.json` | Stable IDs, classification, names, favourites, tags, provenance and rendition hashes |
| `sources.json` | Collection source pages, usage terms and selection notes |
| `acquisition.json` | Pinned source downloads, archive members and local acquisition mappings |
| `changelog.json` | Icons added, removed and updated, newest first; maintained by the site workflow |
| `changelog.template` | Changelog page template; rendered when the site is assembled |
| `discovery.json` | Upstream sources checked weekly for new or changed artwork, and rejected candidates (`ignore`) |
| `palette.json` | Colours used for the three ANS Fluent variants |
| `svg/`, `png/` | Generated Fluent SVG variants and PNG renditions |
| `catalogue.template` | Editable HTML/CSS/JavaScript catalogue template |
| `index.html`, `catalogue.html` | Generated catalogue and alternate entry point |
| `assets.yml`, `build.json` | Generated asset references and build checksums |
| `tools/`, `tests/` | Standalone import, discovery, build, site and validation tools and regression tests |
| `.github/workflows/` | Weekly discovery, site build and GitHub Pages deployment, pull-request checks |
| `design/` | Local North7 tokens, brand assets, fonts, catalogue styles and theme behaviour |

### North7 appearance

The catalogue follows North7 v0.2, with light, pastel and dark themes. Choose a
theme in the header; the choice is saved locally. A URL such as
`index.html?theme=dark` overrides the saved choice. The white/navy preview
control affects only icon inspection backgrounds and their preferred colour
variants, independently of the site theme.

North7 tokens and brand assets are copied into this repository. Space Grotesk
and JetBrains Mono are bundled with their font licences. The build embeds all
styles, fonts and theme code, so the catalogue needs no remote fonts or parent
workspace. See [the design snapshot notes](design/README.md) for provenance and
updates. Edit `design/catalogue.css` for layout changes; retain the canonical
token snapshot unchanged when making project-specific adjustments.

### Setup for maintainers

Browsing and using the checked-in artwork requires none of these tools. To maintain the library, install Node.js 20 or newer and Python 3, then run from this repository:

```sh
npm ci
npx playwright install chromium
```

Dependencies are pinned in `package-lock.json`. Initial dependency and browser installation requires internet access. Subsequent checks and builds are offline:

```sh
npm run icons:check
npm run icons:build
npm test
npm run verify:icons
```

The build uses Playwright Chromium to rasterise SVGs, regenerates the catalogue and asset manifest, and records output hashes. It reads only this repository. Paths are resolved from the tool location, so commands also work when invoked from another working directory.

To change a name, tag, classification or favourite, edit `icons.json` and rebuild. Edit `catalogue.template` for catalogue changes and `palette.json` for Fluent variant colours. Preserve product artwork unchanged. Rebuild and review after any change.

The build refuses to overwrite generated files whose contents differ from their recorded hashes. Preserve deliberate manual edits under a distinct filename before restoring or removing the generated copy and rebuilding. `icons.json` is intentionally editable canonical metadata.

Keep generated catalogue files and renditions checked in so the library is usable without a build. `node_modules/`, verification output and temporary files are ignored by Git.

### Re-acquiring reviewed sources

```sh
npm run icons:import
# Equivalent: python3 tools/icons-import.py
```

This is an explicit network operation, separate from offline builds. It verifies pinned downloads (ZIP archives, npm tarballs and single files) and acquired asset hashes before writing, and refuses to overwrite altered originals. It does not discover newer artwork; see [Automated updates](#automated-updates-and-publishing). The six ANS symbols use the included `originals/ans/` SVGs as their pinned local sources; retain them in every copy or backup of the library. Their provenance is recorded in [licenses/ans/README.md](licenses/ans/README.md).

To refresh a collection, review its official source and terms, update the acquisition records, add new originals and metadata, then rebuild and visually review. Preserve existing IDs used by consumers; give a newer identity a distinct ID when retaining the older artwork matters.

## Automated updates and publishing

GitHub Actions maintain and publish the library from this repository. No workstation is required.

| Workflow | When | What it does |
|---|---|---|
| `discover.yml` | Mondays 06:17 UTC, or **Run workflow** | Checks each source in `discovery.json`. It commits low-risk additions to `main`, opens or updates a review pull request for everything else, then triggers the site workflow. |
| `site.yml` | Every push to `main`, or when triggered | Takes the monthly backup if one is due and updates the changelog. Then it rebuilds the catalogue, which renders only new or changed artwork, runs the tests and commits any regenerated files. Finally it assembles the site and agent index, deploys to GitHub Pages and tags the published commit `site-live`. |
| `ci.yml` | Pull requests | Rebuilds without committing, then runs the tests, browser checks and site assembly. |

Sources checked:

- **Microsoft Learn packs** (Azure, Entra, Power Platform, Dynamics 365). The workflow follows each page's current download link, so it detects new pack versions and changed bytes at the same URL.
- **Fluent UI's Microsoft 365 product manifest**, for Office CDN product icons that aren't already covered.
- **`@fabric-msft/svg-icons` on npm.** The download is checked against npm's declared integrity, and only the largest size of each colour, item or non-item symbol is used.
- **The pinned Fluent System Icons commit**, checked for changes to the selected symbols.

**Low risk** (applied automatically) means that a source only adds service/resource or generic artwork, and every file already acquired stays byte-identical.

**Review** (pull request on `discovery/review`) covers:

- proposed product marks
- changed artwork or supporting documents
- files missing upstream (always kept locally)
- new pack versions

In the review pull request:

1. Check the rendered PNGs.
2. Confirm or correct `kind` and `classification_reason` in `icons.json`.
3. Merge.

To reject a candidate permanently, close the pull request and add its key to `ignore` in `discovery.json`. Each proposed addition shows its key in the pull request, for example `office-cdn:delve` or `fabric:ontology_item`.

The workflow won't overwrite a review branch that has your own commits on it. Merge or close it to receive new proposals.

A failed source check changes nothing and fails the workflow so that GitHub notifies you. Source pages can block automated requests; the check validates content rather than trusting the HTTP status. Scheduled runs may be delayed.

To run discovery locally (writes only under ignored `output/discovery/` until applied):

```sh
python3 tools/icons-discover.py scan
python3 tools/icons-discover.py report
python3 tools/icons-discover.py apply --risk review   # or --risk low
npm run icons:build
```

`icons:build` reuses existing PNGs whose source SVG is unchanged, because rasterisation differs slightly between platforms. Use `node tools/icons.mjs build --force` to re-render everything after a renderer upgrade.

### Changelog

On every push to `main`, the site workflow runs `tools/changelog.mjs` before rebuilding. It compares `icons.json` with the commit described by the newest entry in `changelog.json`. If anything changed, it adds an entry that records:

- icons added and removed
- updated icons, with the change: new artwork, rename, kind, collection, category or favourite
- the commit subjects as notes
- current counts

Provenance-only changes, such as a repinned download URL, aren't listed. The site shows the changelog as `changelog.html`, linked from the catalogue header. It's also published as `api/changelog.json`, and `llms.txt` summarises the three most recent changes.

Preview locally with `node tools/changelog.mjs --dry-run`. Don't run it without `--dry-run`; the workflow owns `changelog.json`.

### Monthly site backups

The first deployment of each month first takes a backup of the site that is currently live. After every successful deployment, the workflow moves a `site-live` tag to the published commit. `tools/site-backup.sh` rebuilds that commit's site, zips it and attaches it to a private `site-backup-YYYY-MM` release. It keeps the newest three backup releases.

To restore or compare, download the zip from **Releases**, unzip it, and open `index.html` or serve the folder. Run **Build and deploy site** with **Replace this month's site backup** ticked to take a fresh backup. A failed backup stops the deployment, so a change never goes live without one.

If nothing is deployed in a month, no backup is taken that month. The live site is then still the one the latest backup was taken from, plus the changes deployed after that backup.

### One-time GitHub setup

1. **Settings → Pages → Build and deployment → Source: GitHub Actions.** Pages from a private repository requires GitHub Pro, Team or Enterprise. The published site is public.
2. **Settings → Actions → General → Workflow permissions:** select **Read and write permissions** and tick **Allow GitHub Actions to create and approve pull requests**.
3. If `main` is protected, allow GitHub Actions to push to it, or the low-risk and rebuild commits will fail.
4. Run **Build and deploy site** once from the Actions tab, then **Discover icon updates**.

Pull requests opened by the workflow don't trigger `ci.yml`, because GitHub doesn't start workflows from `GITHUB_TOKEN` events. The discovery job has already built and tested the branch, and any commit you push to it runs the checks.

## Verification scope

- `icons:check` verifies IDs, classification, source and rendition hashes, local acquisition sources, local source/terms links, build inputs and generated outputs.
- `npm test` additionally checks portable asset paths, embedded catalogue data/downloads, classification examples, and maintenance tools run from an unrelated working directory. The Python importer is tested against the included local sources without network requests.
- `verify:icons` opens both HTML entry points offline in Chromium and exercises filtering, background selection, details, downloads and mobile layout. It decodes all PNGs and writes screenshots and a hash-linked report under `output/validation/icons/`.

Browser checks require an environment that permits local `file://` navigation. They do not imply verification in PowerPoint or another consuming application.