WebIDL

[tabatkins]

Your current API block is written in something that I guess is TS-derived? Here's the WebIDL that we'd want in an actual spec:

partial interface Navigator {
  readonly attribute PreferenceManager preferences;
}

interface PreferenceManager {
  // null means the preference is not overridden
  attribute ColorSchemePref?  colorScheme;
  attribute ContrastPref?  contrast;
  attribute ReducedMotionPref?  reducedMotion;
  attribute ReducedTransparencyPref?  reducedTransparency;
  attribute ReducedDataPref? reducedData;
  // Future preferences can be added here, the exact properties will be down to the browser support.

  Promise<sequence<PreferenceSupportData>> getSupported();
}

enum ColorSchemePref { "light", "dark" };
enum ContrastPref { "no-preference", "more", "less" };
enum ReducedMotionPref { "no-preference", "reduce" };
enum ReducedTransparencyPref { "no-preference", "reduce" };
enum ReducedDataPref { "no-preference", "reduce" };

interface PreferenceSupportData {
  readonly attribute DOMString name;
  readonly attribute FrozenArray<DOMString> values;
}

(Using enumerations like this makes things somewhat self-documenting. However, the default behavior for an attribute that's set to a value not in the enum is to just ignore the set, rather than throw: https://webidl.spec.whatwg.org/#idl-enums. We can override that manually, if desired, but matching platform convention is probably better.)

[lukewarlow]

Thanks for this! I meant to look into writing the WebIDL but TypeScript felt easier initially. I'll copy this in to my latest change.

[lukewarlow]

I've also updated the setting an invalid value to be a no-op rather than an exceptional event.

[lukewarlow]

Decided to make a start on a bikeshed document for a "spec" it's no where near done but mostly just copying the readme into a bikeshed format.

https://specs.lukewarlow.dev/web-preferences-api/

[tabatkins]

I think what you've got is more than enough to get started with; no sense spending more effort on formatting until it proves necessary.