Are the class names in Elements stylesheet a public API?

[kurtdoherty]

Q: Are the class names in Elements' stylesheet considered a public API, or are they considered an implementation detail that we simply allow consumers to depend on?

Why am I asking this question?

1. We have previously asked and answered What kind of component library is Elements? #98, agreeing that is an implementation of Reapit's Design System, not a general-purpose component library;
2. By design, Elements can be used without React via the class names generated from our use of the styled and/or css utilities from Linaria;
3. There are third-party integrators, and maybe internal product teams, that rely on the class names defined in the Elements stylesheet;
4. @willmcvay's proposal in Spike: V5 format proposal #124 got me thinking about whether the Linaria styled components are particularly important or not. Initially, I viewed them as implementation details, but...
5. I've realised that Elements' stylesheet probably does represent a public interface that we need to consider when making changes. I'd like to confirm or deny that fact, because...
6. It impacts what contributors need to consider when making changes to existing components.

If the class names are a public API:

• Changing the name of a styled component or a css variable is a breaking change;
• Changing what styled components are used (and what CSS they each represent) is a breaking change;
• Contributors need to be aware of breaking changes at both the CSS/styled component level, and the React component level; and,
• Changing what component design pattern is used for a particular component may introduce breaking changes for both CSS consumers and React consumers.

If the class names are not a public API:

• Changing the name of a styled component or a css variable is implementation detail;
• Changing what styled components are used (and what CSS they each represent) is implementation detail;
• Contributors only need to be aware of introducing breaking changes at the React component level; and,
• Changing what component design pattern is used for a particular component only (officially) impacts React consumers (because CSS-only consumers would be depending on "implementation details", not a public interface).

[kurtdoherty]

@willmcvay I'm keen to understand how you would answer this question and, if it is a public interface, how the team has handled changes to the Linaria styled components historically.

[willmcvay]

@kurtdoherty The former, they are a public API - we handle using semver essentially. From v1 to v2 there were minimal breaking changes. From v2 to v3, there was a complete re-write and from v3 to v4 there were almost no breaking changes meaning users could transition seamelssly, albeit there was a design system overhaul.

The reason we didn't we didn't fully align with the design system at v4 was we wanted to avoid breaking changes so were limited to CSS only changes. We notified any upcoming breaking changes in v5 using deprecation notices in the console.

For v4 to v5, we have already agreed we can make whatever breaking changes are required to achieve design system parity. Best efforts to keep these to a miniumum for obvious reasons but there are no har restrictions. We will be re-naming components for example and this will clearly effect the underlying CSS class so unavoidable.

Hope this answers :-)

[kurtdoherty]

Great, thanks for confirming. I understand v4 to v5 is able to make whatever breaking changes are necessary, but I'm thinking more about beyond v5 where I assume we'll fall back into minimising them to reduce upgrade costs for our internal products.

When making changes to the underlying CSS and DOM structure of a component, e.g. a Linaria styled component is split into three separate styled components, would you maintain the old styled component for backwards compatibility, but deprecate it and mark it for removal in the next major version?

Again, I know we probably won't worry about that during the v4 to v5 upgrades, but I'm asking in the context of post-v5. I'm trying to get a solid mental model of what it looks like for a dev to contribute Design System changes to Elements and, therefore, what we might be able to do with the file structure (e.g. what you're proposing in #124) to help them understand what's important.