Advice or correction on custom themes

[eric-g-97477]

I am working to wrap my head around how theming is architected within PrimeVue and could use some advice. My thoughts below are scattered and I have probably gotten several things wrong. Hopefully someone will be able to make sense of what I have written and can offer correction.

I am focused on color. In my design system, there will be 29 different colors used for various elements. The UI elements themselves, like buttons, etc. will use a small subset of those colors.

I am going to focus on the Tree component.

Looking at packages/themes/src/presets/aura, I see that each provided PrimeVue component has an associated file that looks like:

(taken from aura/tree/index.js)

export default {
    root: {
        background: '{content.background}',
        color: '{content.color}',
...
    node: {
        color: '{text.color}',

Are content.background and text.color design tokens?

The keys and properties are defined in files for each component in packages/themes/types

(take from tree/index.d.ts)

export interface TreeDesignTokens extends ColorSchemeDesignToken<TreeDesignTokens> {
    root?: {
        /**
         * @designToken tree.background
         */
        background?: string;
...
    node?: {
        /**
         * @designToken tree.node.color
         */
        color?: string;

I believe the @designToken for each property is what that property will be assigned to. I am not sure where that mapping happens in the code. So, moving to the documentation, I found https://primevue.org/tree/#theming.tokens. What this is telling me is that root.background is mapped to tree.background which is mapped to the CSS variable --p-tree-background. Additionally, node.color is mapped to tree.node.color which is mapped to the CSS variable --p-tree-node-color.

So, back to my 29 colors defined in my design system. Each of those colors has a semantic name. For example, --common-background-color. If I wanted the background of the tree component to use --common-background-color, I would want to assign the CSS variable --p-tree-node-color to --common-background-color.

However, I am confused on how content.background and text.color relate to tree.background and tree.node.color. Perhaps what is going on here is that content.background and text.color are used as defaults, but can be overridden by tree.background and tree.node.color...? However, I don't see documentation stating this is the case...?

Any thoughts or comments would be appreciated.