feat(icons): support "icons" contribution point #2594

## Problem

This PR re-organizes how we do icons within the Toolkit, mostly by leveraging the VS Code icons contribution point.

The old structure had the following problems:

    * No clear guidance for how to add and use icons within the Toolkit
    * Difficult to keep track of what icons are actually being used
    * Have to maintain separate light/dark icons for everything
    * Impossible to use our current icons with ThemeIcon
    * Using SVGs in Webviews in-lines them

## Solution

    * Put all icons in resources/icons
        * There's a single, top-level "namespace" to help a bit for organization
        * Everything within a namespace is flattened out at build time
    * Use the new icons contribution point
        * This section is generated (otherwise it'd be really tedious....)
    * Generate CSS classes from an icon font
    * Add function getIcon that handles all the legacy/Cloud9 compatibility logic.
       * Contributors no longer need to touch a bunch of files just to add a single icon.

Author: JadenSimon

.eslintignore

@@ -1,5 +1,4 @@
 node_modules/**
-third-party
 **/*.json
 src/shared/telemetry/clienttelemetry.d.ts
 src/codewhisperer/client/codewhispererclient.d.ts

.gitignore

@@ -30,3 +30,8 @@ src/codewhisperer/client/codewhispererclient.d.ts
 # Generated by tests
 src/testFixtures/**/bin
 src/testFixtures/**/obj
+
+# Icons
+resources/icons/cloud9/generated/**
+resources/fonts/aws-toolkit-icons.woff
+resources/css/icons.css

.prettierignore

@@ -1,6 +1,5 @@
 out
 resources/endpoints.json
-third-party/**
 CHANGELOG.md
 src/shared/telemetry/service-2.json
 .changes

.vscode/settings.json

@@ -1,11 +1,13 @@
-// Place your settings in this file to overwrite default and user settings.
 {
     "files.exclude": {
-        "src/testFixtures": true,
-        "out": false // set this to true to hide the "out" folder with the compiled JS files
+        "**/src/testFixtures": true
     },
     "search.exclude": {
-        "out": true // set this to false to include "out" folder in search results
+        "dist": true,
+        "node_modules": true
+    },
+    "files.watcherExclude": {
+        "**/src/testFixtures": true
     },
     "typescript.preferences.importModuleSpecifier": "relative",
     "javascript.preferences.importModuleSpecifier": "relative"

.vscodeignore

@@ -7,11 +7,9 @@
 !dist/libs
 !dist/*/!(testFixtures|test)/**/!(*.*.map)
 !dist/*/!(*.*.map)
-!media/**
 !resources/**
 !syntaxes/**
 !templates/**
-!third-party/**
 !types/**
 !LICENSE
 !NOTICE

CONTRIBUTING.md

@@ -315,12 +315,25 @@ requests just from the model/types.
     req.send(function (err, data) { ... });
     ```
 
+### Font generation
+
+For extensions to contribute their own codicons, VS Code requires a font file as well as how that font maps to codicon IDs. The mapping is found in `package.json` under the `icons` contribution point. Icons located in `resources/icons` are stitched together at build-time into a single font, automatically adding mappings to `package.json`. More information can be found [here](docs/icons.md).
+
+As a simple example, let's say I wanted to add a new icon for CloudWatch log streams. I would do the following:
+
+1. Place the icon in `resources/icons/aws/cloudwatch`. I'l name the icon `log-stream.svg`.
+1. Use `npm run generatePackage` to update `package.json`. Commit this change with the new icon.
+1. You can now use the icon in the Toolkit:
+
+    ```ts
+    getIcon('aws-cloudwatch-log-stream')
+    ```
+
 ## Importing icons from other open source repos
 
 If you are contribuing visual assets from other open source repos, the source repo must have a compatible license (such as MIT), and we need to document the source of the images. Follow these steps:
 
-1. Use a separate location in this repo for every repo where images are
-   sourced from, in the form `third-party/resources/from-<BRIEF_REPO_NAME>`.
+1. Use a separate location in this repo for every repo/organization where images are sourced from. See `resources/icons/vscode` as an example.
 1. Copy the source repo's licence into this destination location's LICENSE.txt file
 1. Create a README.md in the destination location, and type in a copyright attribution:
 
@@ -332,8 +345,7 @@ If you are contribuing visual assets from other open source repos, the source re
     <PASTE_SOURCE_LICENSE_HERE>
     ```
 
-1. Copy the SVG file(s) into a suitable place within the destination location, for example `.../dark/xyz.svg` and `.../light/xyz.svg`
-1. Add an entry to `third-party/README.md` summarizing the new destination location, where the asserts were sourced from, and a brief rationale.
+1. Add an entry [here](docs/icons.md#third-party) summarizing the new destination location, where the assets were sourced from, and a brief rationale.
 
 [PR #227](https://github.com/aws/aws-toolkit-vscode/pull/227) shows an example.
 

docs/icons.md

@@ -0,0 +1,66 @@
+# Icons
+
+All icons that are used in the Toolkit can be found in `resources/icons`.
+
+A [build script](../../scripts/build/generateIcons.ts) generates Toolkit artifacts:
+
+-   `resources/icons/cloud9/generated`
+-   `resources/fonts/aws-toolkit-icons.woff`
+-   `resources/css/icons.css`
+-   `contributes.icons` in [package.json](../../package.json)
+
+This script should be ran using `npm run generatePackage` after making updates. Any changes made to `package.json` should be committed with the relevant icons.
+
+## Fonts
+
+Icons to be used in fonts should ideally be:
+
+-   Monochromatic (`currentColor` fill or stroke)
+-   Equal in size and width
+-   Defined by a single path
+
+The benefits of doing this include:
+
+-   `ThemeIcon` support
+-   Automatic generation of CSS classes for webviews
+-   Static validation of icon identifiers
+
+If your desired icon does not work well as a font, see [Theme Overrides](#theme-overrides) for adding icons as standalone images.
+
+## Identifiers
+
+Icons (except those in `cloud9`) can be referenced within the Toolkit by concatenating the icon path with hyphens, omitting the 'theme' if applicable.
+
+Examples:
+
+-   `resources/icons/aws/apprunner/service.svg` -> `aws-apprunner-service`
+-   `resources/icons/vscode/dark/help.svg` -> `vscode-help`
+-   `resources/icons/vscode/codicons/close.svg` -> `vscode-close`
+
+This specific format is used to keep things consistent with CSS classes while still supporting some semblance of namespacing. In Webviews, font-based icons can be used through the combination two CSS classes: `icon icon-${IDENTIFIER}`.
+
+## Theme Overrides
+
+By default, icons are assumed to be monochromatic and suitable for use as a font. If this is not the case, then icons specific to each theme (i.e. `dark` and `light`) must be added separately.
+
+For example, if I wanted to use a special App Runner service icon, then I need to add the icons like so:
+
+-   `resources/icons/aws/dark/apprunner-service.svg`
+-   `resources/icons/aws/light/apprunner-service.svg`
+
+A similar format is used for overriding icons only on Cloud9:
+
+-   `resources/icons/cloud9/dark/aws-apprunner-service.svg`
+-   `resources/icons/cloud9/light/aws-apprunner-service.svg`
+
+These icons will **not** be usuable as Codicons or as font icons.
+
+## Third Party
+
+Icons sourced from third-party repositories need a corresponding entry placed within this section. Any added icons need to be placed in their own directory named after the source. Repositories that belong to the same organization may be placed in the same location.
+
+### VS Code
+
+[Visual Studio Code Icons](https://github.com/microsoft/vscode-icons) were moved to their own repository in August 2019. These files are located within [resources/icons/vscode](resources/icons/vscode).
+
+[Visual Studio Code Codicons](https://github.com/microsoft/vscode-codicons). Codicons are VS Code's font-based icon set. These files are located within [resources/icons/vscode/codicons](resources/icons/vscode/codicons).