After writing our tech preview docs, and as we write our beta docs, we're noticing that we're using <FrameworkCase /> in nearly all our docs, but we rarely reach for <StyleCase />. In other words, docs frequently vary by framework (html and react variants) but rarely by style (css and tailwind).
We anticipate that this will change once we start getting into ui component api reference -- each ui component will have examples that include classnames and related styles.
However, even with some variation within api reference, many (a majority?) of our guides will not have differing content between styles. So we need to consider how google and other search engines will treat this duplicate content. We could set one style as the canonical that the others point to.
But then another issue arises. If the pages are substantially the same, is it a good dx to have these long urls that set style preferences when shared, even if the style is irrelevant to the page? Good question, debatable.
On the other hand, having style encoded in our url prevents CLS as ui component code blocks adapt to the user's preference. Though, that could be solved with a small, blocking script -- the same way we handle dark mode.
As you can see, we really could go either way. Issues and solutions exist on either side of the "keep style in the url" debate.
After discussing with @mihar-22 and @heff, though, I think we're going to drop them for now. Mostly because we're persuaded by the friction surrounding canonicals and long urls, and this is an easily reversible decision; if we find we're wrong, we'll add them back
After writing our tech preview docs, and as we write our beta docs, we're noticing that we're using
<FrameworkCase />in nearly all our docs, but we rarely reach for<StyleCase />. In other words, docs frequently vary by framework (html and react variants) but rarely by style (css and tailwind).We anticipate that this will change once we start getting into ui component api reference -- each ui component will have examples that include classnames and related styles.
However, even with some variation within api reference, many (a majority?) of our guides will not have differing content between styles. So we need to consider how google and other search engines will treat this duplicate content. We could set one style as the canonical that the others point to.
But then another issue arises. If the pages are substantially the same, is it a good dx to have these long urls that set style preferences when shared, even if the style is irrelevant to the page? Good question, debatable.
On the other hand, having style encoded in our url prevents CLS as ui component code blocks adapt to the user's preference. Though, that could be solved with a small, blocking script -- the same way we handle dark mode.
As you can see, we really could go either way. Issues and solutions exist on either side of the "keep style in the url" debate.
After discussing with @mihar-22 and @heff, though, I think we're going to drop them for now. Mostly because we're persuaded by the friction surrounding canonicals and long urls, and this is an easily reversible decision; if we find we're wrong, we'll add them back