Figure out how to let application developers customize provided basic catalog implementation

[jacobsimionato]

Ideally, when developers use the basic catalog, they could potentially set some settings e.g. to determine the border radius of a Card etc.

[jacobsimionato]

Ideally, this customization should be on a per-Component basis, because components can be mixed and matched across different catalogs. Perhaps just constructor args? It might look different for different renderers, but ideally we'll make it as unified as we can.

[jacobsimionato]

See internal doc https://docs.google.com/document/d/1ot3RbGjvSzoa1da8UPD68sWzNdiubN0zQBHSycPu-K8 for a short manifesto on this topic

[ava-cassiopeia]

This is tricky when it comes to cross-platform, but I'm just the visiting web person, so I'm gonna drop my thoughts here primarily in web words. I think that a lot of this could be generalized into some structured JSON or similar so that we have cross-platform compatibility.

Anyway, I'm pretty fond of how Angular Material (et al.) does this: they compose styles based on a hierarchy of CSS custom props (variables) that we can probably take inspiration from.

This chart might act as a good summary:

flowchart LR

A(Color) --> D[Theme]
B(Typography) --> D
C(Density) --> D
D --> E[Component-specific CSS props]

Loading

Where style inheritance flows from color/typography/density through the theme and down to the component-specific props. Color, typography, and density are specific components of the total theme (which also includes 'private', not-meant-to-be-changed core stuff) that can be swapped in and out separately.

Consider an example of a Card. A Card impl in our standard catalog might look something like:

.a2ui-card {
  --a2ui-card-padding: var(--a2ui-theme-density-content-padding, 20px);
  --a2ui-card-bg-color: var(--a2ui-theme-color-content-bg-color, #fff);
}

A theoretical developer could modify the way the Card is styled in a number of ways. In order of precision, they could:

1. Specifically override the Card-specific props, ie.:

     :root {
       --a2ui-card-padding: 12px;
       --a2ui-card-bg-color: blue;
     }

   Where the above would only affect cards, but you could imagine the developer syncing that up with their implementation of Card-like things.

2. Specifically override certain parts of one of the configs, ie.:

     :root {
       --a2ui-theme-density-content-padding: 12px;
       --a2ui-theme-color-content-bg-color: blue;
     }

   This would have a broader affect on the component library, but only highly specific portions of how parts of the library render (in this case, some background colors and padding values).

3. Provide a full plugin for color/typography/density and it sets these values. This is similar to how the easy-path integration with Angular Material is, where you just specify what primary color you want your app to be themed and the plugin handles all of the rest.

   That typically looks something like:

     .my-app {
       @import example.example-theme($palette-blue);
     }

This gives developers a lot of levers to pull. They could theme the whole thing at a very high level, they could only care about, say, density (to match their app) but keep the rest default, they could zoom in and modify specific components, or anywhere in between.

If we define all these props and keep them stable, component developers can also rely on them to re-implement catalog items and still inherit styles, or create custom catalog items that still pull in theme-wide styles.

Angular Material goes super deep on this (example from MatButton), but I think we can start with something a bit similar (/ have reasonable defaults).

I'm not sure everything we'll need, but typically I find it is useful to expose (on top of all the normal things around padding and font sizes and blah blah):

:root {
  // Color used for the "primary" parts of the app, typically
  // the navbar, buttons that want to draw the user's attention,
  // and other decoration.
  --primary-color: ...;
  // Computed value of either #fff or #000 based on --primary-color.
  // We want to be careful about exposing this prop, if we do at all,
  // because otherwise we might be compromising visual a11y.
  --primary-complement-color: ...;
  
  // Sometimes this is also useful for accented but lower-visual-priority
  // parts of the UI.
  --secondary-color: ...;
  --secondary-complement-color: ...;

  --heading-font: ...;
  --body-font: ...;
  --code-font: ...;

  --content-bg: ...;
  --content-text-color: ...;

  --gutter: ...;

  // Useful for "reduce motion" settings.
  --fast-animation-speed: 250ms;
  --slow-animation-speed: 750ms;
}

I'm sure there's others, I'd need to go take a census from past projects, Angular, tailwind, etc., but I think that illustrates what I'm talking about.

[ava-cassiopeia]

One more thing for now: a key part of this is that there will often be directly layered contrasting parts of the page. For example, a card with a --content-bg-color and its text with a --content-text-color. Somehow, we want to be considering aria guidance on color contrast for these such that the reasonable defaults are set to high-contrast colors. There's tools for this in SCSS and CSS, and we want it to be easy for the user to take advantage of them with good defaults.