search

posit-dev / brand-yml

Unified branding with a single yaml file.
https://posit-dev.github.io/brand-yml/
MIT License
1 stars 0 forks source link

`logo.images` should only allow named file paths #22

Open gadenbuie opened 3 weeks ago

gadenbuie commented 3 weeks ago

Follow up from #18. logo.with was a place for definitions, but we've renamed it logo.images. In practice, I've also found it's much easier to implement and for downstream brand consumers if logo.images is strictly a list of named file paths.

Before After 
logo:
  images:
    white: logo-white.png
    black: logo-black.png
    paired:
      light: black
      dark: white
  small: paired
 
logo:
  images:
    white: logo-white.png
    black: logo-black.png
    # light-dark not allowed here
  small:
    light: black
    dark: white

The advantage is that we're able to consistently know that all entries in logo.images are file paths that (may) need to be resolved relative to the _brand.yml. And brand consumers can know that brand.logo.images["foo"] is a resolved file path, which is much easier to use – someone reaching into that part of brand wants a specific image.

cscheid commented 1 week ago

Quarto's schema for the small, medium, and large entries:

https://github.com/quarto-dev/quarto-cli/blob/c5c98f2d25e9e5a67c7d3f84ec8f21337ae00032/src/resources/schema/definitions.yml#L2503-L2516

Possible values for the logo field:

logo:
  small: logo-small.png

logo:
  images:
    white: logo-white.png
    black: logo-black.png
  small:
    light: white

logo:
  small:
    light: white
    dark: black

logo:
  medium:
    light: another-logo-white.png

Question: do we want to allow the specification of light but not dark and vice versa?

gadenbuie commented 1 week ago

Question: do we want to allow the specification of light but not dark and vice versa?

Giving light without dark would be the equivalent of saying: "I have a resource that works in light mode, but I don't have one that works in dark mode". I suppose that would translate in practice to showing the light logo when in light mode and then showing no logo in dark mode. As a brand consumer, though, that increases the cost of implementation quite a bit.

I'm in favor of making paired light and dark required to reduce the complexity around "how do I implement this?"

cscheid commented 1 week ago

I'm in favor of making paired light and dark required to reduce the complexity around "how do I implement this?"

Great, I agree. I made the change in https://github.com/quarto-dev/quarto-cli/commit/4fe762b922baa397434c1c2709047235dd64604b and it assumes exactly that.