Use of starlight variables in our CSS

[shubham-padia]

We are planning to use some css variables defined by starlight in our application. Some of them include --sl-line-height, --sl-steps-start, --bullet-size, --sl-text-xs, --sl-color-white, --shift-y and much more.

What is starlight's policy on these variables? Are these internals which might end up changing with minor releases, or does starlight aim to keep these variables around as much as possible.

If these are internals that may change anytime, what is the recommended approach for changing styles that might depend on these variables?

[HiDeoo]

Sharing the answer I gave on Discord for visibility:

👋 Looks like I totally missed your discussion, sorry for the delayed answer.

To give a bit of context, we do showcase how to overide some Starlight custom properties in the docs, and also link to our props.css file where we defined most of them. Altho, we do not yet properly document them individually in the Starlight docs. We also know that users, plugins, themes especially, and even our own theme editor, are using these custom properties to style their proejcts so we are definitely very careful about them. For reference, the last time a custom property was removed from this file was in 2023, and at the time plugins and themes were not yet a thing.

We also try to make sure breaking changes are well communicated in our changelog, e.g. this example: breaking changes are clearly marked as such and we also provide a migration guide or indicate how to preserve the previous behavior when applicable.

If we were to remove one for some reason:

• Before v1.0: this could happen in a minor (technically it could even be in a patch as per the semver spec: in major version zero, anything may change at any time — but we don't do breaking changes in patch releases) and we will definitely communicate it in the changelog as I mentioned above as a breaking change.
• After v1.0: this would happen in a major release, and we would also communicate it in the changelog as a breaking change.

[shubham-padia]

Thank you for the answer!