docs(manifest): Improve icons member page

files/en-us/web/manifest/display/index.md

@@ -11,36 +11,44 @@ The `display` manifest member is used to specify your preferred display mode for
 
 ## Syntax
 
-```json
+```json-nolint
+/* Keyword values */
+"display": "fullscreen"
 "display": "standalone"
+"display": "minimal-ui"
+"display": "browser"
 ```
 
 ### Values
 
-The value of the `display` member is a string. The possible values include `fullscreen`, `standalone`, `minimal-ui`, and `browser`. If a browser does not support the specified display mode, it follows a pre-defined fallback chain: `fullscreen` → `standalone` → `minimal-ui` → `browser`. If `display` is not specified, the default value `browser` is used.
+- `display`
+
+  - : A string with keyword values. If not specified, the default value `browser` is used. The keyword values include:
 
-- `fullscreen`
+    - `fullscreen`
 
-  - : Opens the app with browser UI elements hidden and uses the entirety of the available display area. Use this value for apps where fullscreen engagement is crucial and desired. For example, use it for a game app that can take up the entire screen without any browser controls visible, providing a fully immersive gaming experience.
+      - : Opens the app with browser UI elements hidden and uses the entirety of the available display area. Use this value for apps where fullscreen engagement is crucial and desired. For example, use it for a game app that can take up the entire screen without any browser controls visible, providing a fully immersive gaming experience.
 
-    > [!NOTE]
-    > The `fullscreen` value of the manifest's `display` member works separately from the [Fullscreen API](/en-US/docs/Web/API/Fullscreen_API). The `fullscreen` display mode changes the state of the entire browser window to full screen, while the Fullscreen API only makes a specific element within the window go full screen. Therefore, a web app can be in `fullscreen` display mode while {{DOMxRef("Document.fullscreenElement")}} is `null` and {{DOMxRef("Document.fullscreenEnabled")}} is `false`.
+        > [!NOTE]
+        > The `fullscreen` value of the manifest's `display` member works separately from the [Fullscreen API](/en-US/docs/Web/API/Fullscreen_API). The `fullscreen` display mode changes the state of the entire browser window to full screen, while the Fullscreen API only makes a specific element within the window go full screen. Therefore, a web app can be in `fullscreen` display mode while {{DOMxRef("Document.fullscreenElement")}} is `null` and {{DOMxRef("Document.fullscreenEnabled")}} is `false`.
 
-- `standalone`
+    - `standalone`
 
-  - : Opens the app to look and feel like a standalone native app. This can include the app having a different window and its own icon in the app launcher. The browser will exclude UI elements such as a URL bar but can still include other UI elements such as the status bar. For example, use it for a task manager app that opens in its own window without the browser's URL bar, while still displaying the device's status bar for battery and notifications, thereby providing an integrated experience.
+      - : Opens the app to look and feel like a standalone native app. This can include the app having a different window and its own icon in the app launcher. The browser will exclude UI elements such as a URL bar but can still include other UI elements such as the status bar. For example, use it for a task manager app that opens in its own window without the browser's URL bar, while still displaying the device's status bar for battery and notifications, thereby providing an integrated experience.
 
-- `minimal-ui`
+    - `minimal-ui`
 
-  - : Opens the app to look and feel like a standalone app but with a minimal set of UI elements for navigation. The specific elements can vary by browser but typically include navigation controls like back, forward, reload, and possibly a way to view the app's URL. Additionally, the browser may include platform-specific UI elements that provide functionality for sharing and printing content. Use this value for apps where displaying a minimal browser interface is beneficial. For example, use it for a news reading or other general reading apps that show only the essential browser controls like back and reload buttons, providing a cleaner and less distracting interface.
+      - : Opens the app to look and feel like a standalone app but with a minimal set of UI elements for navigation. The specific elements can vary by browser but typically include navigation controls like back, forward, reload, and possibly a way to view the app's URL. Additionally, the browser may include platform-specific UI elements that provide functionality for sharing and printing content. Use this value for apps where displaying a minimal browser interface is beneficial. For example, use it for a news reading or other general reading apps that show only the essential browser controls like back and reload buttons, providing a cleaner and less distracting interface.
 
-- `browser`
-  - : Opens the app in a conventional browser tab or new window, using the platform-specific convention for opening links. Use this value for apps that are designed to be used within a browser context, where full browser functionality is needed. This is the default value if no `display` mode is specified.
+    - `browser`
+      - : Opens the app in a conventional browser tab or new window, using the platform-specific convention for opening links. Use this value for apps that are designed to be used within a browser context, where full browser functionality is needed. This is the default value if no `display` mode is specified.
 
 ## Description
 
 After a browser applies a `display` mode to an {{Glossary("application context")}}, it becomes the default display mode for the top-level browsing context. The browser may override this display mode for security reasons or provide users with a means for switching to another `display` mode.
 
+If a browser does not support the specified display mode, it follows a pre-defined fallback chain: `fullscreen` → `standalone` → `minimal-ui` → `browser`.
+
 Use the {{cssxref("@media/display-mode", "display-mode")}} media feature to determine the current `display` mode applied by the browser, which is useful for ensuring your app behaves as expected in different display contexts. Additionally, the `display-mode` media feature allows you to adjust your app's styles based on the `display` mode currently being used. This can help provide a consistent user experience regardless of whether the website is launched from a URL or from a desktop icon.
 
 > [!NOTE]
@@ -64,6 +72,8 @@ As shown in the code below, you can adjust an app's style depending on the `disp
 
 ## Examples
 
+### Specifying standalone display mode
+
 The following example manifest file for the web app named "HackerWeb" defines how the app should appear and behave when installed on a user's device. The `display` member is set to `standalone`, which specifies that the app should open in a separate window without the typical browser UI elements like the URL bar.
 
 ```json

files/en-us/web/manifest/icons/index.md

@@ -7,118 +7,144 @@ browser-compat: html.manifest.icons
 
 {{QuickLinksWithSubpages("/en-US/docs/Web/Manifest")}}
 
-<table class="properties">
-  <tbody>
-    <tr>
-      <th scope="row">Type</th>
-      <td><code>Array</code></td>
-    </tr>
-  </tbody>
-</table>
+The `icons` manifest member is used to specify one or more image files that define the icons to represent your web application.
+These icons uniquely identify your web app in different contexts, such as in an operating system's task switcher, system settings, home screen, app listings, and other places when application icons are displayed.
 
-The `icons` member specifies an array of objects representing image files that can serve as application icons for different contexts. For example, they can be used to represent the web application amongst a list of other applications, or to integrate the web application with an OS's task switcher and/or system preferences.
+## Syntax
 
-## Examples
-
-```json
-"icons": [
+```json-nolint
+/* Single icon with the minimum required property */
+"icons":
   {
-    "src": "icon/lowres.webp",
-    "sizes": "48x48",
-    "type": "image/webp"
-  },
+    "src": "icon/basic-icon.png"
+  }
+
+/* Single icon with multiple purposes */
+"icons":
   {
-    "src": "icon/lowres",
-    "sizes": "48x48"
-  },
+    "src": "icon/basic-icon.png",
+    "purpose": "monochrome maskable any"
+  }
+
+/* Two icons with various properties */
+"icons": [
   {
-    "src": "icon/hd_hi.ico",
-    "sizes": "72x72 96x96 128x128 256x256"
+  "src": "icon/lowres.png",
+  "sizes": "48x48"
   },
   {
-    "src": "icon/hd_hi.svg",
-    "sizes": "any"
+  "src": "maskable_icon.png",
+  "sizes": "48x48",
+  "type": "image/png"
   }
 ]
 ```
 
-## Values
-
-Image objects may contain the following values:
-
-<table class="fullwidth-table standard-table">
-  <thead>
-    <tr>
-      <th scope="col">Member</th>
-      <th scope="col">Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td><code>sizes</code></td>
-      <td>
-        A string containing space-separated image dimensions using the same syntax as the
-        <a href="/en-US/docs/Web/HTML/Element/link#sizes"><code>sizes</code></a>
-        attribute.
-      </td>
-    </tr>
-    <tr>
-      <td><code>src</code></td>
-      <td>
-        The path to the image file. If <code>src</code> is a relative URL, the
-        base URL will be the URL of the manifest.
-      </td>
-    </tr>
-    <tr>
-      <td><code>type</code></td>
-      <td>
-        A hint as to the media type of the image. The purpose of this member is
-        to allow a user agent to quickly ignore images with media types it does
-        not support.
-      </td>
-    </tr>
-    <tr>
-      <td><code>purpose</code></td>
-      <td>
-        <p>
-          Defines the purpose of the image, for example if the image is intended
-          to serve some special purpose in the context of the host OS (i.e., for
-          better integration).
-        </p>
-        <p>
-          <a href="https://w3c.github.io/manifest/#purpose-member"
-            ><code>purpose</code></a
-          >
-          can have one or more of the following values, separated by spaces:
-        </p>
-        <ul>
-          <li>
-            <code>monochrome</code>: A user agent can present this icon where a
-            <a
-              href="https://w3c.github.io/manifest/#monochrome-icons-and-solid-fills"
-              >monochrome icon with a solid fill</a
-            >
-            is needed. The color information in the icon is discarded and only
-            the alpha data is used. The icon can then be used by the user agent
-            like a mask over any solid fill.
-          </li>
-          <li>
-            <code>maskable</code>: The image is designed with
-            <a href="https://w3c.github.io/manifest/#icon-masks"
-              >icon masks and safe zone</a
-            >
-            in mind, such that any part of the image outside the safe zone can
-            safely be ignored and masked away by the user agent.
-          </li>
-          <li>
-            <code>any</code>: The user agent is free to display the icon in any
-            context (this is the default value).
-          </li>
-        </ul>
-      </td>
-    </tr>
-  </tbody>
-</table>
+### Values
+
+- `icons`
+
+  - : An object or an array of objects.
+    Each object represents an icon to be used in a specific context.
+    For example, you can add icons to represent your web app on devices with different screen sizes, for integration with various operating systems, for splash screens, or for app notifications.
+
+    Each icon object can have one or more properties. Of these, only `src` is required. The possible properties include:
+
+    - `src`
+
+      - : A string that specifies the path to the icon image file.
+        If `src` is relative, the path is resolved relative to the manifest file's URL.
+        For example, the relative URL `images/icon-192x192.png` for the manifest file located at `https://example.com/manifest.json` will be resolved as `https://example.com/images/icon-192x192.png`.
+
+    - `sizes` {{Optional_Inline}}
+
+      - : A string that specifies one or more sizes at which the icon file can be used.
+        Each `<size-value>` is specified as `<width in pixels>x<height in pixels>`.
+        Multiple `<size-value>` tokens can be specified, separated by spaces, for example: `48x48 96x96`.
+        When multiple icons are available, browsers may use `<size-values>` to select the most suitable icon for a 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 `<size-values>` is not specified, the selection and display of the icon may vary depending on the browser's implementation.
+
+        Note that the format of `<size-values>` is similar to the HTML `<link>` element's [`sizes`](/en-US/docs/Web/HTML/Element/link#sizes) attribute.
+
+    - `type` {{Optional_Inline}}
+
+      - : A string that specifies the {{Glossary("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, browsers typically infer the image type from the file extension.
+
+    - `purpose` {{Optional_Inline}}
+
+      - : A case-sensitive keyword string that specifies one or more contexts in which the icon can be used by the browser or operating system.
+        The value can be a single keyword or multiple space-separated keywords.
+        If omitted, the browser can use the icon for any purpose.
+
+        Browsers 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 browser 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.
+
+## Description
+
+The context in which an icon can be used is determined by the browser and the operating system, based on the specified sizes and formats.
+
+When working with icon images, both security and performance are important considerations.
+
+The browser's ability to fetch an icon image is governed by the Content Security Policy ({{Glossary("CSP")}}) of the manifest's owner document, specifically by the [`img-src`](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/img-src) directive. This security aspect is related to the `src` property. For example, if the `img-src` directive in a CSP header specifies `icons.example.com`, icons from only that domain would be fetchable. In a manifest with two icons, one from `icons.example.com/lowres` and another from `other.com/hi-res`, only the former would be fetched successfully because of CSP restrictions.
+
+The `type` property plays a part in determining performance. While this property is optional, specifying it can improve performance significantly. It allows browsers to quickly ignore images with formats they do not support. If you don't specify the `type` property, it is recommended to specify appropriate and unambiguous file extensions for the icon images to ensure correct handling by the browser.
+
+## Examples
+
+### Declaring multiple icons
+
+This example shows how to declare multiple icons for different scenarios and devices. If an icon for a specific situation is not supported or not available, browsers will fall back to other available formats and sizes.
+
+- Two icons of the same size (`48x48`) are provided in different formats. The first is explicitly specified as [WebP](/en-US/docs/Web/Media/Formats/Image_types#webp_image) using the `type` property. If a browser doesn't support WebP, it will fall back to the second icon of the same size. For the second icon, the browser will determine the MIME type either from the HTTP header or by inferring it from the image file's content. Icons at this size are typically used for browser tabs and bookmarks.
+
+- An [ICO](/en-US/docs/Web/Media/Formats/Image_types#ico_microsoft_windows_icon) file is provided with multiple sizes ranging from `72x72` to `256x256`. ICO files contain multiple raster icons that are individually optimized for various display sizes. Icons at these sizes are commonly used for desktop shortcuts.
+
+- For larger icons (`257x257` and above), an [SVG](/en-US/docs/Web/Media/Formats/Image_types#svg_scalable_vector_graphics) file is specified. The `sizes` value of this icon is set to `any`, which allows a browser to use this icon at any size. SVG icons maintain their quality at larger sizes. These icons ate ideal for high-resolution displays like in [progressive web apps (PWAs)](/en-US/docs/Web/Progressive_web_apps).
+
+```json
+{
+  "icons": [
+    {
+      "src": "icon/lowres.webp",
+      "sizes": "48x48",
+      "type": "image/webp"
+    },
+    {
+      "src": "icon/lowres",
+      "sizes": "48x48"
+    },
+    {
+      "src": "icon/hd_hi.ico",
+      "sizes": "72x72 96x96 128x128 256x256"
+    },
+    {
+      "src": "icon/hd_hi.svg",
+      "sizes": "any"
+    }
+  ]
+}
+```
 
 ## Specifications
 
@@ -127,3 +153,9 @@ Image objects may contain the following values:
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- [Image file type and format guide](/en-US/docs/Web/Media/Formats/Image_types#webp_image)
+- [Monochrome icons and solid fills](https://w3c.github.io/manifest/#monochrome-icons-and-solid-fills)
+- [Icon masks and safe zone](https://w3c.github.io/manifest/#icon-masks)

files/en-us/web/manifest/theme_color/index.md

@@ -15,13 +15,15 @@ This color application can provide a more native app-like experience for your we
 
 ## Syntax
 
-```json
-"theme_color": "<color-value>"
+```json-nolint
+/* Valid color value */
+"theme_color": "rebeccapurple"
+"theme_color": "#4285f4"
 ```
 
 ### Values
 
-- `<color-value>`
+- `theme_color`
 
   - : A string that specifies a [valid color value](/en-US/docs/Web/CSS/color_value).
 
@@ -81,13 +83,17 @@ body {
 ### Using a named color
 
 ```json
-"theme_color": "red"
+{
+  "theme_color": "red"
+}
 ```
 
 ### Using an RGB value
 
 ```json
-"theme_color": "rgb(66, 133, 244)"
+{
+  "theme_color": "rgb(66, 133, 244)"
+}
 ```
 
 ### Using a hexadecimal value