Re: [w3c/manifest] Add support for defining a theme color for both light & dark modes (prefers color scheme) (#975)

Weighing in here on the syntax:

Quick summary:

- If order is important, we should use an array, not an object (relying on the order of the keys). But I don't think the order should be important.
- I strongly strongly dislike the syntax `"(prefers-color-scheme: dark)"` (either as a key or as a value). We should use simple strings like `"light"` and `"dark"`.

Aaron's first proposal of [these three](https://github.com/w3c/manifest/issues/975#issuecomment-833959325) SGTM.

**On the order of dictionary keys**

@marcoscaceres wrote:

> They are ordered in the JS spec and in our spec. We explicitly use an ordered map.
>
> To be clear, all browsers treat JSON properties as ordered irrespective of what the JSON spec says.

To go into the technicals: yes, we use an ordered map to represent the _output_ of processing the manifest, but we still start by parsing JSON into an [object](https://www.w3.org/TR/appmanifest/#dfn-object), which we define to be "object" as defined in the JSON spec, [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259). That spec _explicitly_ defines "object" as "an **unordered** collection of zero or more name/value pairs" (emphasis mine). So per our own specification, we aren't allowed to depend on the order of keys (despite what the implementations make possible).

But I don't think the spec really matters that much (after all we could change what the spec says if we really wanted to). I think what's more important is how confusing it is for developers. I would argue, _very_. When I see the syntax:

```json
{
   "x": "y",
   "a": "b"
}
```

in JSON, JavaScript, Python, Ruby, Lua, etc, I have a basic assumption that the order of the keys won't matter, because they're going to be inserted into either a hash table or a sorted tree. It is very unintuitive to tell developers that the order of these keys matters; it goes against decades of experience in virtually all modern programming languages.

If you want to define a data structure where the order matters, use an array.

Having said that, I don't have a problem with Aaron's first syntax:

```json
"color_schemes": {
  "dark": {
    "theme_color": "#fff",
    "background_color": "#000"
  },
  "light": {
    "theme_color": "#000",
    "background_color": "#fff"
  }
}
```

because this isn't a case of "try one and fall back to the other", right? It would be "if there's a match, use it, if not, use the `theme_color` and `background_color` from the top-level object. Am I understanding correctly?

**On the strings used in the key**

It's not clear to me whether the key `"(prefers-color-scheme: light)"` would be matched as a literal value, or whether it would be parsed as CSS or something else.

- If we're planning to literally put into the spec to match against the key (or value) string `"(prefers-color-scheme: light)"` and `"(prefers-color-scheme: dark)"`, then why would we use such a complex string? Why not just `light` and `dark`?
- If we're planning to _parse_ the contents of this string, please please don't. It looks like this is trying to look like CSS? Are you actually suggesting that we run a CSS parser over this string? Or that we define a new mini-language that we will parse inside this string? Either way, please don't parse these strings. Represent the data structure we need in JSON.

Again, Aaron's first suggestion seems fine to me.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/manifest/issues/975#issuecomment-853534482