Resolve "skeleton" naming collision (state vs. planned component) before shipping .sf-skeleton (blocks #384 item 8)

[jackgranatowski]

Problem

"Skeleton" is about to be used for two different axes at once:

1. Live today — a state utility: core/states.css:77-95 — .sf-is-skeleton (+ img.sf-is-skeleton), a generic shimmer/loading-state class applicable to any element, on any component.
2. Planned — a component family: docs/roadmap.md:50-53 and issue Components: second batch #384 (item 8) — a future .sf-skeleton component with shape modifiers: .sf-skeleton--text, .sf-skeleton--line, .sf-skeleton--avatar, .sf-skeleton--card.

Once item 8 of #384 ships, an author could plausibly write:

<div class="sf-skeleton sf-skeleton--card sf-is-skeleton">

Two independently-named "skeleton" concepts stacked on one element — unclear at a glance whether .sf-is-skeleton (the shimmer effect) is even meant to combine with .sf-skeleton--card (a shape/component), or whether the component is supposed to carry its own built-in shimmer without needing the state class at all. This is exactly the class of bug that produced #571 (.sf-btn--secondary colliding with --sf-color-secondary) — same word, two axes, and it's cheaper to fix now, before anything ships, than after.

Secondary, smaller echo of the same problem: .sf-skeleton--card reuses the word "card" to mean a placeholder shape, not the real .sf-card component — someone skimming class names could misread .sf-skeleton--card as "a skeleton version of .sf-card" (with matching padding/radius/etc.) rather than just "a rectangular placeholder shape shaped roughly like a card."

Why file this separately from #384

#384 is the tracking issue for the whole first component batch (button, card, badge, tag, alert, avatar, modal, skeleton, custom form controls, @starting-style animations) and doesn't currently call out this naming risk for item 8 specifically. This issue exists so the naming question gets resolved as a design decision before .sf-skeleton implementation starts, not discovered after.

Proposed resolution (pick one before implementing #384 item 8)

• (a) Keep .sf-is-skeleton as the shimmer state (any element), and rename the planned component to something that doesn't share the word — e.g. .sf-placeholder or .sf-shape, with modifiers .sf-placeholder--text/--line/--avatar/--card. The component's base rule would then itself apply (or require) .sf-is-skeleton for the shimmer, making the composition explicit: .sf-placeholder .sf-placeholder--card for shape + .sf-is-skeleton for the shimmer behavior, cleanly separated.
• (b) Keep .sf-skeleton as the component name, and make it self-sufficient (it always shimmers on its own, no separate .sf-is-skeleton class needed on skeleton-component elements) — document clearly that .sf-is-skeleton (state) and .sf-skeleton (component) are never meant to be used together, and pick non-colliding names for the shape modifiers to avoid the .sf-skeleton--card vs .sf-card echo (e.g. .sf-skeleton--card-shape or drop the "card" name in favor of a purely geometric descriptor).

Recommend (a) — it keeps the state/component axis separation the framework already uses elsewhere (.sf-is-* = state, .sf-* = structural), rather than introducing a new "self-sufficient component that also happens to share a name with a state" pattern.

Scope

• Decide (a) vs (b) (or an alternative) before implementation of Components: second batch #384 item 8 begins
• If renaming, update docs/roadmap.md's planned modifier list accordingly
• Ensure whatever ships doesn't reuse "card" for the shape modifier in a way that implies parity with .sf-card's actual token set

Related

• Components: second batch #384 (component batch tracking issue — item 8 is .sf-skeleton)
• .sf-btn: fix color/style naming collision on "secondary", complete the color axis, and ship gradient fill/outline variants #571 (the naming-collision pattern this issue is pre-empting)