Boneyard

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

1. Explicit initialBones prop (highest priority)
2. Registry lookup by name (from registry.js)
3. 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

Runtime options (baked into registry.js)

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>