Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 29 additions & 4 deletions showcase/specs/skeleton.ts
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,9 @@ export const skeletonSpec: ComponentSpec = {
id: 'skeleton',
name: 'Skeleton',
description:
'A placeholder block for content whose layout is already known: flat bg-muted fill, one shimmer synchronized across every block of a cluster. Shape it with class — line for text, circle for avatar, block for media.',
'A placeholder block for content whose layout is already known: zero-chroma translucent fill that inherits any underlying surface, crossed by one shimmer synchronized across every block of a cluster. Shape it with class — line for text, circle for avatar, block for media.',
descriptionZh:
'已知布局内容的加载占位块:扁平 bg-muted 填充,同一簇内所有块共享一道同步微光。用 class 塑形——文本用行、头像用圆、媒体用块。',
'已知布局内容的加载占位块:纯中性半透明底色自动融入任意表面(含非黑白灰底色与配色主题),同一簇内所有块共享一道同步微光。用 class 塑形——文本用行、头像用圆、媒体用块。',
controls: [
{ kind: 'enum', key: 'shape', label: 'Shape', options: ['line', 'circle', 'block'], default: 'line', display: 'segmented' },
{ kind: 'enum', key: 'size', label: 'Size', options: ['sm', 'default', 'lg'], default: 'default', display: 'segmented' },
Expand Down Expand Up @@ -91,6 +91,29 @@ export const skeletonSpec: ComponentSpec = {
]),
]),
},
{
name: 'On tinted surfaces',
nameZh: '有色底面',
render: () =>
// One-off demo strips exercising translucent compositing across non-gray semantic surfaces.
h('div', { class: 'grid w-full max-w-md grid-cols-1 gap-3 sm:grid-cols-3' }, [
h('div', { class: 'rounded-xl bg-brand-soft p-3 space-y-2' }, [
h(Skeleton, { class: 'h-3 w-16' }),
h(Skeleton, { class: 'h-5 w-24' }),
h(Skeleton, { class: 'h-3 w-20' }),
]),
h('div', { class: 'rounded-xl bg-info-soft p-3 space-y-2' }, [
h(Skeleton, { class: 'h-3 w-16' }),
h(Skeleton, { class: 'h-5 w-24' }),
h(Skeleton, { class: 'h-3 w-20' }),
]),
h('div', { class: 'rounded-xl bg-warning-soft p-3 space-y-2' }, [
h(Skeleton, { class: 'h-3 w-16' }),
h(Skeleton, { class: 'h-5 w-24' }),
h(Skeleton, { class: 'h-3 w-20' }),
]),
]),
},
],
render: state => h(Skeleton, { class: shapeSizeClass(state) }),
// class is always shown — it IS the component's API; there is no default to
Expand All @@ -99,12 +122,14 @@ export const skeletonSpec: ComponentSpec = {

- Shape the block to the real content: text lines at their real line height, avatar as rounded-full, media as a block. The last line of a paragraph runs short — a full-width final line lies about the layout.
- Compose clusters with plain flex/space-y wrappers; every block in a cluster shares ONE synchronized shimmer (the viewport-anchored sheet on [data-slot="skeleton"] in style.css) — never give a single block its own animation.
- Both the resting fill (bg-skeleton) and the drifting shimmer are zero-chroma translucent overlays, so Skeleton blends naturally over tinted surfaces and non-default color schemes without passing custom colors.
- Not for unknown durations or no-layout-yet waits: a bare glyph is Spinner, work a button triggered is Button :loading. Skeleton answers "what will appear here"; a spinner answers "something is working".
- Reduced motion freezes every block to flat bg-muted automatically — nothing to wire per call site.`,
- Reduced motion freezes every block to flat bg-skeleton automatically — nothing to wire per call site.`,
usageZh: `Skeleton 是已知布局内容的加载占位。它镜像即将到来的内容的形状,让数据到达时布局不跳动。

- 块的形状要对齐真实内容:文本行用真实行高、头像用 rounded-full、媒体用整块。段落末行要短一截——末行拉满是在谎报布局。
- 用普通的 flex/space-y 容器组合成簇;同一簇里所有块共享一道同步微光(style.css 中 [data-slot="skeleton"] 的视口锚定渐变)——绝不给单个块配独立动画。
- 静止底色(bg-skeleton)与流动微光均为零色度半透明叠层,放在有色底面或任意配色主题上会自动融入表面,无需按场景手写底色。
- 时长未知或布局未定的等待不用它:裸字形用 Spinner,按钮触发的等待用 Button :loading。Skeleton 回答"这里将出现什么",spinner 回答"正在处理"。
- 减弱动态效果时所有块自动冻结为扁平 bg-muted——调用点无需任何处理。`,
- 减弱动态效果时所有块自动冻结为静止的 bg-skeleton——调用点无需任何处理。`,
}
7 changes: 4 additions & 3 deletions src/components/skeleton/Skeleton.vue
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,11 @@ const props = defineProps<SkeletonProps>()
</script>

<template>
<!-- bg-muted is the reduced-motion / fallback base; the sliding two-gray shimmer
gradient is driven by the [data-slot=skeleton] rule in style.css. -->
<!-- bg-skeleton is the zero-chroma translucent resting fill (also the reduced-motion
fallback); the sliding translucent shimmer seam is driven by [data-slot=skeleton]
in style.css so both layers composite cleanly over neutral or tinted surfaces. -->
<div
data-slot="skeleton"
:class="cn('rounded-lg bg-muted', props.class)"
:class="cn('rounded-lg bg-skeleton', props.class)"
/>
</template>
39 changes: 22 additions & 17 deletions src/style.css
Original file line number Diff line number Diff line change
Expand Up @@ -697,14 +697,14 @@
}
}

/* Skeleton loading shimmer — a soft two-gray seam drifts left→right. The gradient is
one repeating tile (--skeleton-tile wide) marching across a VIEWPORT-anchored sheet
(background-attachment:fixed), so every skeleton block — wherever it sits — samples
the SAME light by its own position: a cluster (avatar + lines) reads as one surface
crossed by a single seam, never independent per-block pulses (the "one paper, many
windows" model). The tile is narrower than a typical row, so a fresh seam revisits
the group every cycle — a short gap, not a viewport-wide wait. Animating by exactly
one tile width loops seamlessly. Two CLOSE grays keep it a gentle seam, not a band. */
/* Skeleton loading shimmer — a soft zero-chroma translucent seam drifts left→right.
The gradient is one repeating tile (--skeleton-tile wide) marching across a
VIEWPORT-anchored sheet (background-attachment:fixed), so every skeleton block —
wherever it sits — samples the SAME light by its own position: a cluster (avatar +
lines) reads as one surface crossed by a single seam, never independent per-block
pulses (the "one paper, many windows" model). Because the gradient stops fade from
transparent through the neutral alpha --skeleton-shimmer and back to transparent,
the seam composites over any base fill or tinted surface without stamping gray. */
@keyframes skeleton-shimmer {
to {
background-position-x: var(--skeleton-tile);
Expand Down Expand Up @@ -785,9 +785,9 @@
[data-slot="skeleton"] {
background-image: linear-gradient(
100deg,
var(--muted) 40%,
var(--skeleton-mid) 50%,
var(--muted) 60%
transparent 40%,
var(--skeleton-shimmer) 50%,
transparent 60%
);
background-attachment: fixed;
background-repeat: repeat;
Expand Down Expand Up @@ -1164,9 +1164,12 @@
output), and a single declaration here already tracks --muted's .dark /
per-scheme overrides at use-time, so it needs no redeclaration below. */
--muted-soft: color-mix(in oklab, var(--muted) 40%, transparent);
/* Skeleton shimmer mid-stop — one hair DARKER than --muted (0.967) so the sliding
seam is a calm shadow, not a bright flash, on the light gray block. */
--skeleton-mid: oklch(0.93 0.002 286);
/* Skeleton base + shimmer — zero-chroma neutral overlays (black in light, white
in dark) so both the resting block and the drifting seam composite over any
surface (neutral or tinted) instead of stamping opaque gray or losing scheme hue.
Light: 4.5% base (~244 on white card, matching --muted 245) + 4.5% peak (~233). */
--skeleton-bg: oklch(0 0 0 / 0.045);
--skeleton-shimmer: oklch(0 0 0 / 0.045);
/* Shimmer tile width — narrower than a typical skeleton row so a fresh seam revisits
each cluster every cycle (short gap). Bigger = longer gap; smaller = denser. */
--skeleton-tile: 640px;
Expand Down Expand Up @@ -1558,9 +1561,10 @@
--secondary-foreground: oklch(0.86 0 0);
--muted: oklch(0.26 0 0);
--muted-foreground: oklch(0.70 0 0);
/* On dark, the mid-stop is one hair LIGHTER than --muted (0.26) — a gentle lift,
never a glaring white sweep. */
--skeleton-mid: oklch(0.315 0 0);
/* On dark, neutral white overlays gently lift the underlying surface (7.5% base +
6% shimmer peak) without painting tinted surfaces dead gray. */
--skeleton-bg: oklch(1 0 0 / 0.075);
--skeleton-shimmer: oklch(1 0 0 / 0.06);
--accent: oklch(0.26 0 0);
--accent-foreground: oklch(0.86 0 0);
--destructive: oklch(0.704 0.191 22.216);
Expand Down Expand Up @@ -2022,6 +2026,7 @@
--color-muted: var(--muted);
--color-muted-foreground: var(--muted-foreground);
--color-muted-soft: var(--muted-soft);
--color-skeleton: var(--skeleton-bg);
--color-accent: var(--accent);
--color-accent-foreground: var(--accent-foreground);
--color-destructive: var(--destructive);
Expand Down
Loading