dark-mode: Add a proposal for dark mode extension icons

proposals/dark_mode_extension_icons.md

@@ -0,0 +1,205 @@
+# Dark Mode Extension Icons
+
+**Summary**
+
+Feature to enable developers to enhance extension icon visibility in dark mode.
+
+**Document Metadata**
+
+**Author:** <solomonkinard>
+
+**Sponsoring Browser:** Chromium.
+
+**Contributors:** <oliverdunk>
+
+**Created:** 2024-04-05
+
+**Related Issues:**
+* https://crbug.com/893175
+* https://github.com/w3c/webextensions/issues/229
+
+## Motivation
+
+### Objective
+
+Extension developers will be able to supply and define a set of icons to be used
+in the event that browser system settings are set to dark mode. The set of dark
+mode icons can and will be made automatically visible once the system setting is
+in dark mode, thereby enhancing the overall browser experience.
+
+#### Use Cases
+
+1. Improved icon visibility in the extension toolbar.
+1. Improved icon visibility on management the management and shortcuts pages.
+1. Dark mode icon declarations made possible through the extension manifest.
+1. setIcon() will allow setting of dark and/or light mode specific icons.
+1. Improved icon visibility on context menu (Chrome and Safari reply on default icons, only Firefox can specify icons).
+1. Improved icon visibility on side panel (Chrome replies on default icons, Firefox can specify icons).
+
+### Known Consumers
+
+The associated and linked bug has 48 stars and 31 comments.
+
+## Specification
+
+### Schema
+
+Some browsers don't currently have plans to support svg. Therefore, a drop-in
+replacement of an already supported image type will be allowed.
+
+numberToPathDictionary
+```
+{
+  "<number>": "<path>"
+}
+```
+
+manifest.json
+```
+{
+  "icon_variants": {
+    "<dark|light>": <numberToPathDictionary>
+  },
+  "action": {
+    "default_icon": <numberToPathDictionary>|<svgPathString|pathString>,
+    "icon_variants": {
+      "<dark|light>": <numberToPathDictionary>
+    }
+  }
+}
+```
+
+Action
+```
+action.setIcon({
+  imageData?: ImageData | object:<numberToPathDictionary>,
+  path?: string | object:<numberToPathDictionary>,
+  tabId?: number,
+  variants?: {
+    "<dark|light>": <numberToPathDictionary>
+  },
+});
+```
+
+### Examples
+
+manifest.json
+```
+{
+  "icon_variants": {
+    "dark": {
+      "128": "128_dark.png"
+    },
+    "light": {
+      "128": "128_light.png"
+    }
+  },
+  "action": {
+    "default_icon": {
+      "128": "128_action.png"
+    },
+    "icon_variants": {
+      "dark": {
+        "128": "128_action_dark.png"
+      },
+      "light": {
+        "128": "128_action_light.png"
+      }
+    }
+  }
+}
+```
+
+Action
+```
+action.setIcon({
+  variants?: {
+    "dark": {
+      "128": "128_action_dark.png"
+    },
+    "light": {
+      "128": "128_action_light.png"
+    }
+  },
+});
+```
+
+### Behavior
+
+Existing manifest key. The behavior of the icons manifest key will remain unchanged.
+```
+{
+  "icons": {
+    "64": "icon_64.png"
+  },
+  "action": {
+    "default_icon": {
+      "64": "action_64.png"
+    }
+  }
+}
+```
+
+Order of precedence. The new `icon_variants` keys and subkeys will take
+precedent, followed by the incumbent `icons` key.
+
+### New Permissions
+
+N/A.
+
+### Manifest File Changes
+
+#### Optional or required?
+`icon_variants` is an optional key of the top level manifest dictionary.
+`icon_variants` is also an optional sub-key in the action key dictionary.
+
+#### Fallback
+`icon_variants` will be used if they're supplied. Otherwise `default_icon` will
+be used if it's supplied. If neither are supplied, then `icons` will be used.
+
+#### Warning or error?
+The new `icon_variants` key (or sub-key) will only emit a non-blocking warning
+rather than a hard error in the event of unexpected values or missing icons.
+This will allow this optional key to be more flexible in the event of ideas for
+future changes. The `icons` key cannot be used for dark mode support because it
+errors in cases when a warning would have otherwise sufficed. The warning is
+ok for `icon_variants` based on the safety net outlined in the fallback section.
+
+## Security and Privacy
+
+### Exposed Sensitive Data
+
+N/A.
+
+### Abuse Mitigations
+
+N/A.
+
+### Additional Security Considerations
+
+N/A.
+
+## Alternatives
+
+### Existing Workarounds
+
+1. A developer could ask the user to specify what mode they're in and then
+dynamically set the icon to a dark mode icon using action.setIcon(). That
+wouldn't change the management page icon.
+2. A developer could change icons dynamically to dark mode icons if this is
+true: `window.matchMedia('(prefers-color-scheme: dark)')`.
+
+### Open Web API
+
+As stated in the workarounds section, the following is already an option to consider: `window.matchMedia('(prefers-color-scheme: dark)')`. However, that
+wouldn't automatically set icons dynamically, as it would require subsequent
+calls to action.setIcon(). It also wouldn't update the icon on the management
+pages.
+
+## Implementation Notes
+
+N/A.
+
+## Future Work
+
+Svg support may be considered at some point for some browsers.