Mmmm, from this I take it that some of the nuances with the system could be better explained in the docs. I can see how one might imagine withfaces to remap named faces seen within it. This reminds me of an extra utility that has come to my mind: a function like freezefaces(::AnnotatedString) which resolves all named faces into standalone Face objects.

Let's add this to the discussion we've lined up. Just so it's out of Slack, I'll also reproduce the list of benefits/annoyances of the current system I wrote and you suggested edits to.

Key points I like with the current system:

• Straightforward user-customisation of all named faces
• Composability across packages
• The ability to remap faces in certain contexts
• Being able to weakly depend on other package's faces
• Concise usage

Key points of annoyance with the current system:

• Global mutable state
• Requires __init__-y stuff
• Uses a TOML parser

Sounds good to me!

FWIW I would naively have expected annotated"..." to behave like in the OP but styled"..." to resolve eagerly, and then for styled(::AnnotatedString) to behave in the way you describe for freezefaces

And here's a gist sketching the "palette" idea that I brought up on Slack: https://gist.github.com/topolarity/f4e422c70441a002af88510750788048

The main idea here is to go from a single-level namespace to a two-level namespace, w/ more explicit inheritance - The goal is to make it easier to answer questions like:

• "Should I be prefixing all my Face names?"
  • not necessary (without palettes, it's almost certainly best practice - it's the emacs tradition for example)
• "How can I reasonably expect this to display?"
  • a Palette gives a place to document the "semantic" meaning of a Face, esp. for customizations (e.g. light v. dark assumptions, or "whole theme" assumptions like :title_bold should be readable inside of :title, :emphasis can never be used in a :title, etc.). For picky users that just want reliable styling without theming/customizations - they can opt-out via mutable = false and/or providing no toml_name
• "What is everything I need to customize to provide a 'theme'?"
  • the set of Faces in a Palette is fixed, just enumerate its contents