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

Restructure `color`, `logo` and `typography` to use named resources #2

Closed gadenbuie closed 2 months ago

gadenbuie commented 3 months ago

We can restructure color, logo and typography slightly to use a common abstraction of named resources. These are user-provided values that would be added to each section via the with keyword, providing a clear distinction between user keyword values and the fixed brand fields. All fields controlled by brand.yml can then be hoisted up to the top level; users can reference values declared in with directly in any values in that section:

logo:
  with:
    fancy-logo-1: acme-icon-1.png
    fancy-logo-2: acme-icon-2.png
    fancy-logo-3: acme-icon-3.png
  small: acme-icon-1.png
  medium: acme-icon-2.png
  large: acme-icon-3.png

color:
  with:
    acme-red: '#ff0000'
    acme-light-gray: '#ccc'
  primary: acme-red
  background-color: acme-light-gray

typography:
  with:
    - google: "Open Sans"
    - google: "Fira Code"
    - google:
        family: "Roboto Slab"
        weight: 600
        style: normal
        display: block
  base:
    family: "Open Sans"
    line-height: 1.25
    size: 1rem
  headings:
    family: "Roboto Slab"
    color: primary
    weight: 600
  monospace:
    family: "Fira Code"
    size: 0.9em 

One design principle I'd like to (try to) follow with this is that named values in with: could be directly specified in any of the direct fields, e.g.

field:
  with:
    name: <value>
  fixed-field: name

would be equivalent to

field:
  fixed-field: <value>

for any given <value> object.

Both color and logo follow that principle already, but typography would have to be modified to follow this pattern (see #3). I think it's worth the effort and consideration.

gordonwoodhull commented 3 months ago

FWIW although I like the consistency and generality of .with, I'll probably stick with brand-palette and brand-theme in Typst output as more descriptive.[^1]

Maybe we could document that brand.color.with is effectively a "palette" of colors of the brand.color "theme", just to tie the ideas together even if those words are no longer in the schema.

[^1]: Perhaps emitting a comment pointing users to brand.color.with and brand.color.