Add icons for packages and elements

justinfagnani · justinfagnani · commit 36b1df465a9f · 2025-07-08T11:18:16.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,6 +17,18 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 <!-- ### Removed -->
 <!-- ### Fixed -->
 
+<!-- ## [x.y.z] - YYYY-MM-DD -->
+## Unreleased
+<!-- ### Changed -->
+### Added
+
+- Added the `icons` field to `Package` and `CustomElement` to describe available
+  icons for those objects.
+
+<!-- ### Removed -->
+<!-- ### Fixed -->
+
+
 ## [2.1.0] - 2024-05-16
 
 ### Added
diff --git a/schema.d.ts b/schema.d.ts
@@ -36,6 +36,11 @@ export interface Package {
    */
   readme?: string;
 
+  /**
+   * The icons that represent this package.
+   */
+  icons?: Array<Icon>;
+
   /**
    * An array of the modules this package contains.
    */
@@ -48,6 +53,75 @@ export interface Package {
   deprecated?: boolean | string;
 }
 
+/**
+ * Represents an icon for a Package or CustomElement to be used in a specific
+ * context. For example, you can add icons to represent your elements in
+ * different tools such as documentation viewers, catalogs, or IDEs.
+ *
+ * This interface follows the [Web App Manifest icons
+ * member](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons).
+ */
+export interface Icon {
+  /**
+   * A string that specifies the path to the icon image file. The path is
+   * relative to the package root. Icon files should be included in the
+   * package.
+   */
+  src: string;
+
+  /**
+   * A string that specifies one or more sizes at which the icon file can be
+   * used. Each size is specified as `<width in pixels>x<height in pixels>`. If
+   * multiple sizes are specified, they are separated by spaces; for example,
+   * `48x48 96x96`. When multiple icons are available, tools may select the
+   * most suitable icon for a particular display context. For raster formats
+   * like PNG, specifying the exact available sizes is recommended. For vector
+   * formats like SVG, you can use any to indicate scalability. If `sizes` is
+   * not specified, the selection and display of the icon may vary depending on
+   * the tools's implementation.
+   */
+  sizes?: string;
+
+  /**
+   * A string that specifies the MIME type of the icon. The value should be in
+   * the format image/<subtype>, where <subtype> is a specific image format; for
+   * example, image/png indicates a PNG image. If omitted, tools typically
+   * infer the image type from the file extension.
+   */
+  type?: string;
+
+  /**
+   * A case-sensitive keyword string that specifies one or more contexts in
+   * which the icon can be used a tool. The value can be a single keyword or
+   * multiple space-separated keywords. If omitted, the tool can use the icon
+   * for any purpose.
+   *
+   * Tools use these values as hints to determine where and how an icon is
+   * displayed. For example, a monochrome icon might be used as a badge or
+   * pinned icon with a solid fill, which is visually distinct from a full-color
+   * launch icon. With multiple keywords, say monochrome maskable, the tool
+   * can use the icon for any of those purposes. If an unrecognized purpose is
+   * included along with valid values (e.g., monochrome fizzbuzz), the icon can
+   * still be used for the valid purposes. However, if only unrecognized
+   * purposes are specified (e.g., fizzbuzz), then it will be ignored.
+   *
+   * Valid values include:
+   *
+   * - `monochrome` Indicates that the icon is intended to be used as a
+   *   monochrome icon with a solid fill. With this value, a browser discards
+   *   the color information in the icon and uses only the alpha channel as a
+   *   mask over any solid fill.
+   *
+   * - `maskable` Indicates that the icon is designed with icon masks and safe
+   *   zone in mind, such that any part of the image outside the safe zone can
+   *   be ignored and masked away.
+   *
+   * - `any` Indicates that the icon can be used in any context. This is the
+   *   default value.
+   */
+  purpose?: string;
+}
+
 // This type may expand in the future to include JSON, CSS, or HTML
 // modules.
 export type Module = JavaScriptModule;
@@ -231,6 +305,11 @@ export interface CustomElement extends ClassLike {
    */
   tagName?: string;
 
+  /**
+   * The icons that represent this element.
+   */
+  icons?: Array<Icon>;
+
   /**
    * The attributes that this element is known to understand.
    */
diff --git a/schema.json b/schema.json
@@ -372,6 +372,13 @@
                     },
                     "type": "array"
                 },
+                "icons": {
+                    "description": "The icons that represent this element.",
+                    "items": {
+                        "$ref": "#/definitions/Icon"
+                    },
+                    "type": "array"
+                },
                 "kind": {
                     "enum": [
                         "class"
@@ -522,6 +529,13 @@
                     },
                     "type": "array"
                 },
+                "icons": {
+                    "description": "The icons that represent this element.",
+                    "items": {
+                        "$ref": "#/definitions/Icon"
+                    },
+                    "type": "array"
+                },
                 "kind": {
                     "enum": [
                         "mixin"
@@ -714,6 +728,31 @@
             ],
             "type": "object"
         },
+        "Icon": {
+            "description": "Represents an icon for a Package or CustomElement to be used in a specific\ncontext. For example, you can add icons to represent your elements in\ndifferent tools such as documentation viewers, catalogs, or IDEs.\n\nThis interface follows the [Web App Manifest icons\nmember](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons).",
+            "properties": {
+                "purpose": {
+                    "description": "A case-sensitive keyword string that specifies one or more contexts in\nwhich the icon can be used a tool. The value can be a single keyword or\nmultiple space-separated keywords. If omitted, the tool can use the icon\nfor any purpose.\n\nTools use these values as hints to determine where and how an icon is\ndisplayed. For example, a monochrome icon might be used as a badge or\npinned icon with a solid fill, which is visually distinct from a full-color\nlaunch icon. With multiple keywords, say monochrome maskable, the tool\ncan use the icon for any of those purposes. If an unrecognized purpose is\nincluded along with valid values (e.g., monochrome fizzbuzz), the icon can\nstill be used for the valid purposes. However, if only unrecognized\npurposes are specified (e.g., fizzbuzz), then it will be ignored.\n\nValid values include:\n\n- `monochrome` Indicates that the icon is intended to be used as a\n  monochrome icon with a solid fill. With this value, a browser discards\n  the color information in the icon and uses only the alpha channel as a\n  mask over any solid fill.\n\n- `maskable` Indicates that the icon is designed with icon masks and safe\n  zone in mind, such that any part of the image outside the safe zone can\n  be ignored and masked away.\n\n- `any` Indicates that the icon can be used in any context. This is the\n  default value.",
+                    "type": "string"
+                },
+                "sizes": {
+                    "description": "A string that specifies one or more sizes at which the icon file can be\nused. Each size is specified as `<width in pixels>x<height in pixels>`. If\nmultiple sizes are specified, they are separated by spaces; for example,\n`48x48 96x96`. When multiple icons are available, tools may select the\nmost suitable icon for a particular display context. For raster formats\nlike PNG, specifying the exact available sizes is recommended. For vector\nformats like SVG, you can use any to indicate scalability. If `sizes` is\nnot specified, the selection and display of the icon may vary depending on\nthe tools's implementation.",
+                    "type": "string"
+                },
+                "src": {
+                    "description": "A string that specifies the path to the icon image file. The path is\nrelative to the package root. Icon files should be included in the\npackage.",
+                    "type": "string"
+                },
+                "type": {
+                    "description": "A string that specifies the MIME type of the icon. The value should be in\nthe format image/<subtype>, where <subtype> is a specific image format; for\nexample, image/png indicates a PNG image. If omitted, tools typically\ninfer the image type from the file extension.",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "src"
+            ],
+            "type": "object"
+        },
         "JavaScriptExport": {
             "properties": {
                 "declaration": {
@@ -1114,6 +1153,13 @@
                 "boolean"
             ]
         },
+        "icons": {
+            "description": "The icons that represent this package.",
+            "items": {
+                "$ref": "#/definitions/Icon"
+            },
+            "type": "array"
+        },
         "modules": {
             "description": "An array of the modules this package contains.",
             "items": {
