# Theming

Some SVGs may be themed.

A theme-compatible SVG looks like this:

<svg height="100" width="100">
  <circle cx="50" cy="50" r="40" stroke="black" stroke-width="3" data-primary_color_value="red" data-primary_color_attr="fill" fill="red" />
</svg>

Notice the data attributes:

- `data-primary_color_attr="fill"`
- `data-primary_color_value="red"`

This means "replace the fill attribute's value with red". This might seem pointless since `fill="red"` is already there, but it's what lets us apply themes on top of this SVG. If we have a theme like this:

"red_theme": {
    "primary_color": "#00ff00",
    "secondary_color": "yellow"
}

When this theme is applied to the SVG, it becomes:

<svg height="100" width="100">
  <circle cx="50" cy="50" r="40" stroke="black" stroke-width="3" fill="#00ff00" />
</svg>

Notice that `secondary_color` is ignored because there is no data attribute targeting it on this SVG.

So, SVGs are renderable standalone (the one at the top of this post is visualizable in the browser), but can be themed through data attribute interpolation.

For adding themes to NFTs, please see [ADDTHEME]().

### Theme Inheritance

When an NFT A with theme X is equipped in an NFT B with theme Y, theme Y can inherit theme X values if its `_inherit` flag is set to `true`.

Parent theme X:

"parent_theme": {
    "primary_color": "blue",
    "dog": "beagle",
    "food": "corn",
    "toy": "ball"
}

Child theme Y:

"child_theme": {
    "primary_color": "yellow",
    "number_of_wheels": 4,
    "window_tint": "red",
    "_inherit": true
}

Resulting theme applied to child NFT's SVG:

{
    "primary_color": "blue",
    "dog": "beagle",
    "food": "corn",
    "toy": "ball",
    "number_of_wheels": 4,
    "window_tint": "red"
}

The result is a merge of the themes, with parent values taking priority over child values of the same name. If `_inherit` were `false`, the child theme would remain intact.

The reverse is also possible: if a theme has `_bubble` set to `true`, it will bubble up its values into the nearest `_inherit: true` parent. This means `_bubble` has highest priority, higher than what was potentially inherited from parent, because we value specificity over a more widely applicable inheritable theme.

In cases where there is a conflicting parent value, like so:

"parent_theme": {
    "primary_color": "blue",
    "dog": "beagle",
    "food": "corn",
    "toy": "ball",
    "number_of_wheels": 4,
    "window_tint": "red"
}

"child_theme": {
    "primary_color": "yellow",
    "number_of_wheels": 4,
    "window_tint": "green",
    "_inherit": true
}

"grandchild_theme": {
    "window_tint": "blue"
    "_bubble": true
}

In the example above, the `window_tint` value is in conflict - when rendering the `child`, which value do we use? Red or blue?

The answer is `blue` because bubbling implies that the `window_tint: blue` value will bubble up to the nearest `_inherit` theme.

Non-slot parts defined as `themable: true` are themable and automatically inherit properties from the parent theme.

## Example

Assume we have a lightsaber which can grow red, green, white, or blue. One could mint four separate ones, or one could mint a single one and apply the "red", "green", "blue", or "white" theme to each.

The advantages of the latter approach are:

- fewer assets to pin on IPFS and any decentralized storage
- easy to add new looks to an existing collection later on
- less load lag (fewer different resources to load - load one weapon and you loaded them all).

Now, if this lightsaber were to be equipped by a character NFT, it might want to change its appearance. Furthermore, the lightsaber could change its color by changing its color crystal - its own equippable NFT. So let's assume the following:

- if the weapon has a white crystal it glows white, but it changes color based on the character which holds it
- if the weapon has a color crystal, it is fixed to that color

So, for this example, let's assume we have the following NFTs:

- Obi Wan
- Darth Maul
- Lightsaber 1
- Lightsaber 2
- Lightsaber 3
- Blue Crystal
- Red Crystal
- Green Crystal
- White Crystal

Let's assume every lightsaber starts out with a White Crystal and glows white if not being held of if held by anyone other than Darth Maul or Obi Wan.

{
    "resources": [
        "id": "VykgH",
        "src": "hash-of-svg-on-ipfs"
    ],
    "themes": [
        "default": {
            "primary_color": "#ffffff",
            "_inherit": true
        }
    ]
}

Now let's assume Obi Wan makes it glow green, and Darth Maul makes it glow red.

{
    "symbol": "OBIWAN",
    "themes": {
        "default": {
            "primary_color": "#00ff00"
        }
    }
}

{
    "symbol": "DARTHMAUL",
    "themes": {
        "default": {
            "primary_color": "#ff0000"
        }
    }
}

Finally we assume that changing the crystal will change the color.

{
    "symbol": "BLUECRYSTAL",
    "themes": {
        "default": {
            "primary_color": "#0000ff",
            "_bubble": true
        }
    }
}