Trigger Scenarios

处理 Skeleton 组件相关任务配置或调试 bones JSON 数据使用 boneyard CLI 进行构建或快照管理 leafTags 和 snapshotConfig 调整骨架屏加载状态与动画

Install

npx skills add 0xGF/boneyard --skill boneyard -g -y

More Options

Non-standard path

npx skills add https://github.com/0xGF/boneyard/tree/main/.claude/skills/boneyard -g -y

Use without installing

npx skills use 0xGF/boneyard@boneyard

指定 Agent (Claude Code)

npx skills add 0xGF/boneyard --skill boneyard -a claude-code -g -y

安装 repo 全部 skill

npx skills add 0xGF/boneyard --all -g -y

预览 repo 内 skill

npx skills add 0xGF/boneyard --list

SKILL.md

Frontmatter

{
    "name": "boneyard",
    "description": "Use boneyard-js to add, configure, debug, or rebuild skeleton screens. Triggers when working with Skeleton components, bones JSON, the boneyard CLI, fixtures, leafTags, snapshotConfig, skeleton loading states, or boneyard.config.json.",
    "allowed-tools": "Bash Read Edit Write Glob Grep Agent"
}

Boneyard Skeleton Skill

You are an expert on boneyard-js, a skeleton screen generator that snapshots real UI into positioned rectangle "bones". Use this knowledge to help with any boneyard-related task.

Architecture

Core files (in `packages/boneyard/`)

src/react.tsx — <Skeleton> React component (also exports configureBoneyard, registerBones)
src/preact.tsx — Native Preact integration (no compat needed)
src/Skeleton.svelte — Svelte 5 component
src/Skeleton.vue — Vue component
src/angular.ts — Angular component
src/native.tsx / src/react-native.tsx — React Native
src/extract.ts — snapshotBones() DOM walker, fromElement() descriptor extractor
src/shared.ts — bone registry, animation constants (SHIMMER, PULSE, DEFAULTS), resolveResponsive
src/types.ts — SnapshotConfig, Bone, CompactBone, ResponsiveBones
src/runtime.ts — vanilla renderBones() for non-React usage
bin/cli.js — CLI entry (boneyard-js build)

Package exports

boneyard-js — snapshotBones, renderBones, fromElement
boneyard-js/react — Skeleton, registerBones, configureBoneyard
boneyard-js/preact — Skeleton, registerBones, configureBoneyard
boneyard-js/native — Skeleton, registerBones, configureBoneyard (React Native)
boneyard-js/svelte — Skeleton component, registerBones
boneyard-js/vue — Skeleton component, registerBones, configureBoneyard
boneyard-js/angular — SkeletonComponent, registerBones, configureBoneyard
boneyard-js/vite — boneyardPlugin() Vite plugin

Bones format

Compact array: [x%, y_px, w%, h_px, borderRadius, isContainer?]

x and w are percentages of container width
y and h are pixels
borderRadius is number (px) or string ("50%")
isContainer (optional 6th element, truthy) — container bones are skipped during rendering. They represent parent backgrounds and would cause opacity overlap if rendered alongside child bones.

Bone resolution priority

Explicit initialBones prop (highest priority)
Registry lookup by name (from registry.js)
Fixture fallback (only during CLI build mode when window.__BONEYARD_BUILD === true)

Animation constants (in `shared.ts`)

All frameworks import from shared.ts — single source of truth:

SHIMMER = { angle: 110, start: 30, end: 70, speed: '2s', lightHighlight: '#f7f7f7', darkHighlight: '#2c2c2c' }
PULSE = { speed: '1.8s', lightAdjust: 0.3, darkAdjust: 0.02 }
DEFAULTS = { web: { light: '#f0f0f0', dark: '#222222' }, native: { light: '#f0f0f0', dark: '#222222' } }

Dark mode

Detected via .dark class on <html> or any parent element (standard Tailwind convention). Does NOT use prefers-color-scheme — gives the app developer explicit control. When .dark is present, darkColor and darkShimmerColor are used.

SnapshotConfig options

{
  leafTags?: string[]              // Tags treated as atomic bones (merged with defaults: p,h1-h6,li,td,th)
  captureRoundedBorders?: boolean  // Capture bordered+rounded elements even without bg (default: true)
  excludeTags?: string[]           // Skip these tags entirely
  excludeSelectors?: string[]      // Skip elements matching CSS selectors
}

Config file (`boneyard.config.json`)

The primary customization point. Controls both CLI build and runtime defaults. Runtime options are baked into the generated registry.js via configureBoneyard().

{
  "breakpoints": [375, 768, 1280],
  "out": "./src/bones",
  "wait": 800,
  "color": "#e5e5e5",
  "darkColor": "#2a2a2a",
  "animate": "shimmer",
  "shimmerColor": "#ebebeb",
  "darkShimmerColor": "#333333",
  "speed": "2s",
  "shimmerAngle": 110,
  "stagger": false,
  "transition": false,
  "boneClass": "",
  "resolveEnvVars": true,
  "auth": {
    "cookies": [{ "name": "session", "value": "env[SESSION_TOKEN]", "domain": "localhost" }],
    "headers": { "Authorization": "Bearer env[API_TOKEN]" }
  }
}

Build-time options

Key	Default	Description
breakpoints	[375, 768, 1280]	Viewport widths captured by CLI (auto-detects Tailwind)
out	./src/bones	Output directory
wait	800	ms to wait after page load before capturing

Runtime options (baked into registry.js)

Key	Default	Description
color	#f0f0f0	Bone fill color (light mode)
darkColor	#222222	Bone fill color (dark mode, `.dark` class)
animate	"pulse"	Animation: "pulse", "shimmer", or "solid"
shimmerColor	#f7f7f7	Shimmer highlight color (light mode)
darkShimmerColor	#2c2c2c	Shimmer highlight color (dark mode)
speed	"2s" (shimmer) / "1.8s" (pulse)	Animation duration
shimmerAngle	110	Shimmer gradient angle in degrees
stagger	false	Delay between bones in ms (true = 80ms)
transition	false	Fade transition when loading ends in ms (true = 300ms)
boneClass	—	CSS class applied to each bone element

Precedence

Per-component props > config file (via configureBoneyard()) > package defaults in shared.ts. CLI flags override config file for build options.

Common tasks

Adding a skeleton to a component

import { Skeleton } from 'boneyard-js/react'

<Skeleton name="my-component" loading={isLoading}>
  <MyComponent data={data} />
</Skeleton>

Using a fixture (when real data isn't available at build time)

<Skeleton
  name="my-component"
  loading={isLoading}
  fixture={<MyFixture />}
  snapshotConfig={{ leafTags: ["section"] }}
>
  <MyComponent data={data} />
</Skeleton>

Key pattern: use <section> (or any custom tag) as leaf elements in the fixture, then add that tag to leafTags so the extractor treats each as a single flat bone without recursing into children.

Excluding elements from capture

<nav data-no-skeleton>
  {/* No bone will be generated */}
</nav>

Or via snapshotConfig:

<Skeleton snapshotConfig={{ excludeSelectors: ['.icon', 'svg'], excludeTags: ['nav'] }}>

Running the CLI

# Auto-detect dev server
npx boneyard-js build

# Explicit URL + output
npx boneyard-js build http://localhost:PORT --out src/bones

# Force rebuild all (skip hash check)
npx boneyard-js build --force

# Watch mode (re-capture on HMR)
npx boneyard-js build --watch

# Custom breakpoints
npx boneyard-js build --breakpoints 375,640,768,1024,1280,1536

# React Native mode
npx boneyard-js build --native --out ./bones

Skeleton props reference

Prop	Type	Default	Description
`loading`	`boolean`	required	Show skeleton vs children
`children`	`ReactNode`	required	Real content
`name`	`string`	required	Registry key + CLI identifier
`initialBones`	`ResponsiveBones`	—	Pre-generated bones (overrides registry)
`color`	`string`	#f0f0f0	Bone fill color (light mode) — any CSS color (hex, rgba, hsl, etc.)
`darkColor`	`string`	#222222	Dark mode bone fill color (`.dark` class) — any CSS color
`animate`	`AnimationStyle`	`'pulse'`	"pulse", "shimmer", "solid" (also accepts boolean)
`stagger`	`number \| boolean`	`false`	Stagger delay (true=80ms)
`transition`	`number \| boolean`	`false`	Fade-out duration (true=300ms)
`boneClass`	`string`	—	CSS class per bone
`className`	`string`	—	Container class
`fallback`	`ReactNode`	—	Shown when loading + no bones
`fixture`	`ReactNode`	—	Mock content for CLI capture
`snapshotConfig`	`SnapshotConfig`	—	Controls bone extraction

Debugging checklist

Skeleton shows nothing: Check that registry.js is imported in app entry AND bones JSON exists for that name
Too many bones / internal shapes: Add leafTags to snapshotConfig and rebuild
Bones don't match layout: Rebuild with --force to regenerate from current DOM
Wrong breakpoint: Check container width — bones resolve using nearest <= breakpoint
Dark mode not detected: Skeleton uses .dark class on <html> or ancestor. Does NOT use prefers-color-scheme
CLI finds no skeletons: Components need loading={false} (or a fixture) so the real UI renders for capture
Opacity overlap / double-layering: Container bones (c: true) should be skipped in rendering — if they're not, the filter is missing
Shimmer not visible: Check that shimmerColor has enough contrast with color — defaults are #f7f7f7 on #f0f0f0

Version History

c085b32 Current 2026-07-24 11:30

Metadata

Files: 0
Version: c085b32
Hash: 5fbcfcbd
Indexed: 2026-07-24 11:30

boneyard