Add authoring support for a @PageColor directive

[ethan-kusters]

Bug/issue #, if applicable: rdar://106153042

Summary

Adds a new @PageColor metadata directive that allows for customizing the color used to represent a given page.

@PageColor gives authors control over the color used when rendering a page – initially this will affect the background color Swift-DocC-Render uses in the page's introduction (hero) section.

Example:

# What's New in SlothCreator

@Metadata {
    @PageColor(red: 233, green: 58, blue: 43)
}

![A sloth on a tree wearing a fedora.](sloth-fedora)

Let's check out what's new in SlothCreator!

...

Details:

@PageColor accepts the following parameters:

• red: An integer value between 0 and 255 that represents the amount of red in the color.

• green: An integer value between 0 and 255 that represents the amount of green in the color.

• blue: An integer value between 0 and 255 that represents the amount of blue in the color.

• opacity: An optional floating-point value between 0.0 and 1.0 that represents the opacity of the color.

  Defaults to 1.0.

This forums post for this change is still pending.

Dependencies

Swift-DocC-Render PR TBD.

Testing

Add @PageColor to the @Metadata directive in a Swift-DocC article or extension file and confirm that the resulting RenderNode includes a color metadata property.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[ethan-kusters]

@swift-ci please test

[dobromir-hristov]

I have a few questions:

1. Why dont we allow them to specify a css color string? - #fafafa, rgb(244,244,244) or linear-gradient(to right top, #051937, #004d7a);?
2. Should we have light/dark mode support?
3. Because we dont allow them to change the icon/text color, someone will surely end up with colors that are not accessible by any means. Should we give them that option or do we try to be smart about it and do some science figure that out 👨‍🔬

[SamLanier]

• Why dont we allow them to specify a css color string? - #fafafa, rgb(244,244,244) or linear-gradient(to right top, #051937, #004d7a);?
• Should we have light/dark mode support?
• Because we dont allow them to change the icon/text color, someone will surely end up with colors that are not accessible by any means. Should we give them that option or do we try to be smart about it and do some science figure that out 👨‍🔬

1. Yes, it would be great if we could allow for any of these color options (#fafafa, rgb(244,244,244) or linear-gradient(to right top, #051937, #004d7a);)
2. Dark mode support would be a nice to have, imo
3. We should just provide the customization abilities (and suggest best practices separately ; ) )

[d-ronnqvist]

I may not have the full context here but to me this functionality feels more at home in with the rest of the theming support.

It's a little different in that the other theme configuration applies to all pages and this applies to a single page but I feel that the better solution would be to improve the theming support so that a theme configuration can be scoped to a single page.

[ethan-kusters]

Thank you for the feedback here!

Closing in favor of

• Add authoring support for a @PageColor directive #525