Accept and use style/theming configuration

[lognaturel]

User Story

As a ODK project manager
I want to specify simple style customizations
So that my forms can match my branding

(Decide whether in scope/a separate issue)
As the developer of an application that uses ODK Web Forms
I want to specify a completely custom style
So that my forms can match the host application

Questions

• Do we want to make it easy for people to opt out of Material/specify their own design language?
• What colors? Do we generate palette?
• Is passing in something like a logo image a theming concern?
• Do we allow for a preamble and suffix? Or is that a responsibility of the host app?
• Are we comfortable deferring the scope to whatever component framework we pick?
• If we defer to the component framework, should we still subset what we expose?
• Maybe styling is expressed as a CSS blob

[lognaturel]

For now we have decided to put style rules as close to what is being styled as possible.

We will initially expose a minimal number of well-documented design tokens that can be set to customize certain aspects of the look and feel.

In the future we may consider broadening what can be styled but continuing with the idea that each component has a well-defined base style and exposes tokens that can be used to customize it.

We will also allow users to bring their own CSS, likely similar to PrimeVue’s unstyled option.

[lognaturel]

As I understand it, PrimeVue's approach to its styled option has been to define a base for each component with a basic structure that uses many variables. For example, a checkbox has many things fixed about it but $checkboxWidth, etc are exposed for easy configuration in a theme.

I think in my ideal world we would continue that general approach in our wrapper around PrimeVue's components. That is, our components would define their basic styling with several well-defined variables. A theme would only involve setting a bunch of design tokens' values.

If we look at https://github.com/getodk/web-forms/blob/main/packages/ui-vue/src/themes/2024-light/theme.scss#L20, for example, that would mean the form wrapper styling moves to where the form wrapper is defined. It's much easier to add configurability in the future than to remove it so probably moving that styling to the component that uses it without introducing any configurability is a good first step. That would define the "base" for that component. Eventually some of that styling could use tokens that PrimeVue defines (e.g. $inlineSpacing) and/or introduce new tokens that can be set.

As I understand it, PrimeVue defines even its base theme outside of its components to make it easy to expose its unstyled mode. We could possibly use that kind of approach but my sense is that we can move to that later if it becomes necessary.

Does this make sense and align with what others got out of our discussion earlier?

I also was expressing excitement at PrimeVue 4 and its CSS-variable-based theming approach. I'm realizing that there's probably some time before it's mature enough for us to use. What does that mean for us? Would we first expose Sass-based theming and then change it? Or maybe it's a reason not to expose configurable theming immediately?