{
  "schemaVersion": 1,
  "target": "react",
  "name": "skeleton",
  "version": "0.1.0",
  "category": "feedback",
  "title": "Skeleton",
  "description": "Loading placeholders for text lines, avatars, and cards, swept by one shared light that holds still under reduced motion.",
  "tags": [
    "loading",
    "placeholder",
    "shimmer",
    "loader",
    "aria-busy",
    "content placeholder"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {},
  "registryDependencies": [
    {
      "name": "button",
      "version": "0.2.1"
    }
  ],
  "docsPath": "/components/skeleton",
  "props": [
    {
      "name": "shimmer",
      "type": "boolean",
      "default": "true",
      "description": "Runs the shared light sweep on Skeleton, SkeletonText, SkeletonAvatar, and SkeletonCard. Off, the blocks are still tints. Always still under reduced motion."
    },
    {
      "name": "SkeletonText lines",
      "type": "number",
      "default": "3",
      "description": "Number of text lines. Each row is one line-height tall, so the real text replaces it without a layout jump."
    },
    {
      "name": "SkeletonText lastLineWidth",
      "type": "string",
      "default": "\"62%\"",
      "description": "Width of the last line, so the block reads as a paragraph."
    },
    {
      "name": "SkeletonText size",
      "type": "\"xs\" | \"sm\" | \"base\"",
      "default": "\"sm\"",
      "description": "Text size the lines stand in for; sets row height (16, 20, or 24px)."
    },
    {
      "name": "SkeletonAvatar size / shape",
      "type": "\"sm\" | \"md\" | \"lg\" / \"circle\" | \"square\"",
      "default": "\"md\" / \"circle\"",
      "description": "24, 32, or 40px; circle for people, square for workspace or app icons."
    },
    {
      "name": "SkeletonCard media / lines",
      "type": "boolean / number",
      "default": "false / 2",
      "description": "Adds a 16:9 media block above the text, and sets the number of body lines."
    },
    {
      "name": "SkeletonGroup label",
      "type": "ReactNode",
      "default": "\"Loading\"",
      "description": "What is loading. The group sets aria-busy=\"true\" and announces this once through a polite status message."
    }
  ],
  "accessibility": [
    "Every placeholder block is aria-hidden, so screen readers never hear a run of empty shapes.",
    "SkeletonGroup sets aria-busy=\"true\" on the loading region and announces its label once through a visually hidden role=\"status\" message.",
    "When the data arrives, render the real content in place of the group (or remove aria-busy from your own container) so the finished region is read.",
    "The sweep is a transform-only Web Animation that is never started under prefers-reduced-motion (and stops if the setting changes); the blocks then show as still tints.",
    "Text rows match real line heights, so content replacing the placeholders does not shift the layout."
  ],
  "states": [
    "loading",
    "static",
    "text",
    "avatar",
    "card"
  ],
  "files": [
    {
      "path": "ui/skeleton.tsx",
      "content": "\"use client\";\n\nimport { type ComponentProps, type ReactNode, useEffect, useRef } from \"react\";\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\n/*\n * One light passes over every skeleton on the page together. Each block's highlight is moved\n * in viewport coordinates and all animations share one start time, so blocks of any width and\n * position read as a single sweep instead of many out-of-step shimmers. It is a transform-only\n * Web Animation (compositor driven), with a rest between passes so it stays quiet.\n * Under reduced motion there is no sweep: the blocks are still tints.\n */\n\nconst PERIOD = 2400;\n/** Share of the period spent travelling; the rest is a pause before the next pass. */\nconst TRAVEL = 0.6;\n\nfunction useSweep(enabled: boolean) {\n  const ref = useRef<HTMLSpanElement>(null);\n\n  useEffect(() => {\n    const band = ref.current;\n    const host = band?.parentElement;\n    if (!enabled || !band || !host || typeof band.animate !== \"function\") return;\n\n    const motion = window.matchMedia(\"(prefers-reduced-motion: reduce)\");\n    let animation: Animation | undefined;\n\n    const start = () => {\n      animation?.cancel();\n      animation = undefined;\n      if (motion.matches) return;\n      const left = host.getBoundingClientRect().left;\n      const width = band.offsetWidth;\n      const from = -width - left;\n      const to = window.innerWidth - left;\n      animation = band.animate(\n        [\n          { transform: `translateX(${from}px)`, offset: 0, easing: \"cubic-bezier(0.45, 0, 0.55, 1)\" },\n          { transform: `translateX(${to}px)`, offset: TRAVEL },\n          { transform: `translateX(${to}px)`, offset: 1 },\n        ],\n        { duration: PERIOD, iterations: Infinity },\n      );\n      // Same phase for every skeleton, measured from the document timeline's origin.\n      animation.startTime = 0;\n    };\n\n    let resizeTimer: ReturnType<typeof setTimeout> | undefined;\n    const onResize = () => {\n      clearTimeout(resizeTimer);\n      resizeTimer = setTimeout(start, 150);\n    };\n\n    start();\n    motion.addEventListener(\"change\", start);\n    window.addEventListener(\"resize\", onResize);\n    return () => {\n      animation?.cancel();\n      clearTimeout(resizeTimer);\n      motion.removeEventListener(\"change\", start);\n      window.removeEventListener(\"resize\", onResize);\n    };\n  }, [enabled]);\n\n  return ref;\n}\n\nexport interface SkeletonProps extends ComponentProps<\"div\"> {\n  /** Runs the shared light sweep. Off, the block is a still tint. Always still with reduced motion. */\n  shimmer?: boolean;\n}\n\n/**\n * A placeholder block. Size and shape it with classes (`h-4 w-32`, `size-10 rounded-full`).\n * It is aria-hidden: announce loading once on the container with `SkeletonGroup` or `aria-busy`.\n */\nexport function Skeleton({ shimmer = true, className, children, ...props }: SkeletonProps) {\n  const band = useSweep(shimmer);\n  return (\n    <div\n      aria-hidden=\"true\"\n      data-slot=\"skeleton\"\n      className={cx(\n        \"relative isolate shrink-0 overflow-hidden bg-zinc-950/[0.06] dark:bg-white/[0.07]\",\n        // Default radius only when the caller sets none, so `rounded-full` and friends always win.\n        !/(^|\\s)rounded/.test(className ?? \"\") && \"rounded-md\",\n        className,\n      )}\n      {...props}\n    >\n      {shimmer ? (\n        <span\n          ref={band}\n          // Parked off the left edge until the sweep starts (the animation drives `transform`).\n          style={{ transform: \"translateX(-100%)\" }}\n          className={cx(\n            \"pointer-events-none absolute inset-y-0 left-0 w-48 motion-reduce:hidden\",\n            \"bg-linear-to-r from-transparent via-white/70 to-transparent dark:via-white/[0.07]\",\n          )}\n        />\n      ) : null}\n      {children}\n    </div>\n  );\n}\n\nexport interface SkeletonTextProps extends Omit<ComponentProps<\"div\">, \"children\"> {\n  /** Number of lines. */\n  lines?: number;\n  /** Width of the last line, so the block reads as a paragraph. Any CSS length. */\n  lastLineWidth?: string;\n  /** Text size the lines stand in for; sets the row height so the layout does not jump on load. */\n  size?: \"xs\" | \"sm\" | \"base\";\n  shimmer?: boolean;\n}\n\nconst lineRows = {\n  xs: { row: \"h-4\", bar: \"h-2\" },\n  sm: { row: \"h-5\", bar: \"h-2.5\" },\n  base: { row: \"h-6\", bar: \"h-3\" },\n} as const;\n\n/** Lines of text. Each row is one line-height tall, so swapping in the real text keeps the layout. */\nexport function SkeletonText({ lines = 3, lastLineWidth = \"62%\", size = \"sm\", shimmer = true, className, ...props }: SkeletonTextProps) {\n  const rows = lineRows[size];\n  return (\n    <div aria-hidden=\"true\" className={cx(\"grid w-full\", className)} {...props}>\n      {Array.from({ length: lines }, (_, i) => (\n        <div key={i} className={cx(\"flex items-center\", rows.row)}>\n          <Skeleton\n            shimmer={shimmer}\n            className={cx(\"rounded-[4px]\", rows.bar)}\n            style={{ width: i === lines - 1 && lines > 1 ? lastLineWidth : \"100%\" }}\n          />\n        </div>\n      ))}\n    </div>\n  );\n}\n\nconst avatarSizes = { sm: \"size-6\", md: \"size-8\", lg: \"size-10\" } as const;\n\nexport interface SkeletonAvatarProps extends SkeletonProps {\n  /** 24, 32, or 40px. */\n  size?: keyof typeof avatarSizes;\n  /** `circle` for people, `square` for workspace or app icons. */\n  shape?: \"circle\" | \"square\";\n}\n\nexport function SkeletonAvatar({ size = \"md\", shape = \"circle\", className, ...props }: SkeletonAvatarProps) {\n  return (\n    <Skeleton className={cx(avatarSizes[size], shape === \"circle\" ? \"rounded-full\" : \"rounded-lg\", className)} {...props} />\n  );\n}\n\nexport interface SkeletonCardProps extends Omit<ComponentProps<\"div\">, \"children\"> {\n  /** Shows a media block (an image or chart) above the text. */\n  media?: boolean;\n  /** Lines of body text. */\n  lines?: number;\n  shimmer?: boolean;\n}\n\n/** A card-shaped placeholder: avatar and title row, optional media, body lines, on the container surface. */\nexport function SkeletonCard({ media = false, lines = 2, shimmer = true, className, ...props }: SkeletonCardProps) {\n  return (\n    <div\n      aria-hidden=\"true\"\n      className={cx(\n        \"grid gap-4 rounded-xl border border-zinc-950/10 bg-white p-5 shadow-[0_1px_2px_rgb(0_0_0/0.04)]\",\n        \"dark:border-white/10 dark:bg-black dark:shadow-[inset_0_1px_0_rgb(255_255_255/0.06)]\",\n        className,\n      )}\n      {...props}\n    >\n      <div className=\"flex items-center gap-3\">\n        <SkeletonAvatar shimmer={shimmer} />\n        <div className=\"grid flex-1 gap-2\">\n          <Skeleton shimmer={shimmer} className=\"h-3 w-2/5 rounded-[4px]\" />\n          <Skeleton shimmer={shimmer} className=\"h-2.5 w-1/4 rounded-[4px]\" />\n        </div>\n      </div>\n      {media ? <Skeleton shimmer={shimmer} className=\"aspect-[16/9] w-full rounded-lg\" /> : null}\n      <SkeletonText lines={lines} shimmer={shimmer} />\n    </div>\n  );\n}\n\nexport interface SkeletonGroupProps extends ComponentProps<\"div\"> {\n  /** What is loading, announced once to screen readers (\"Loading deployments\"). */\n  label?: ReactNode;\n}\n\n/**\n * Wraps placeholders for one loading region. It sets `aria-busy=\"true\"` and announces `label`\n * once through a polite status message; the skeletons inside stay silent.\n *\n * When the data arrives, render the real content instead of the group (or drop `aria-busy`\n * on your own container) so assistive technology reads the finished region.\n */\nexport function SkeletonGroup({ label = \"Loading\", className, children, ...props }: SkeletonGroupProps) {\n  return (\n    <div aria-busy=\"true\" className={className} {...props}>\n      <span role=\"status\" className=\"sr-only\">\n        {label}\n      </span>\n      {children}\n    </div>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "\"use client\";\n\nimport { useEffect, useState } from \"react\";\nimport { Button } from \"@/components/shaken/ui/button\";\nimport { Skeleton, SkeletonAvatar, SkeletonCard, SkeletonGroup } from \"@/components/shaken/ui/skeleton\";\n\nconst members = [\n  { name: \"Priya Raman\", email: \"priya@northwind.dev\", role: \"Owner\" },\n  { name: \"Tomás Ibarra\", email: \"tomas@northwind.dev\", role: \"Admin\" },\n  { name: \"Mei Chen\", email: \"mei@northwind.dev\", role: \"Member\" },\n];\n\nexport default function SkeletonExample() {\n  const [loading, setLoading] = useState(true);\n\n  useEffect(() => {\n    if (!loading) return;\n    const timer = setTimeout(() => setLoading(false), 2600);\n    return () => clearTimeout(timer);\n  }, [loading]);\n\n  return (\n    <div className=\"grid w-full max-w-2xl gap-4\">\n      <div className=\"flex items-center justify-between gap-3\">\n        <p className=\"text-sm font-medium text-zinc-950 dark:text-white\">Team members</p>\n        <Button size=\"sm\" variant=\"secondary\" onClick={() => setLoading(true)}>\n          Reload\n        </Button>\n      </div>\n\n      <div className=\"grid items-start gap-4 md:grid-cols-[minmax(0,1fr)_15rem]\">\n        <div className=\"rounded-xl border border-zinc-950/10 dark:border-white/10\">\n          {loading ? (\n            <SkeletonGroup label=\"Loading team members\" className=\"divide-y divide-zinc-950/[0.07] dark:divide-white/[0.08]\">\n              {members.map((member) => (\n                <div key={member.email} className=\"flex items-center gap-3 px-4 py-3\">\n                  <SkeletonAvatar />\n                  <div className=\"grid flex-1 gap-1.5\">\n                    <Skeleton className=\"h-3 w-28 rounded-[4px]\" />\n                    <Skeleton className=\"h-2.5 w-40 max-w-full rounded-[4px]\" />\n                  </div>\n                  <Skeleton className=\"h-5.5 w-16 rounded-md\" />\n                </div>\n              ))}\n            </SkeletonGroup>\n          ) : (\n            <ul className=\"divide-y divide-zinc-950/[0.07] dark:divide-white/[0.08]\">\n              {members.map((member) => (\n                <li key={member.email} className=\"flex items-center gap-3 px-4 py-3\">\n                  <span className=\"flex size-8 items-center justify-center rounded-full border border-zinc-950/10 text-xs font-medium text-zinc-600 dark:border-white/12 dark:text-zinc-300\">\n                    {member.name\n                      .split(\" \")\n                      .map((part) => part[0])\n                      .join(\"\")}\n                  </span>\n                  <div className=\"grid min-w-0 flex-1\">\n                    <span className=\"truncate text-sm font-medium text-zinc-950 dark:text-white\">{member.name}</span>\n                    <span className=\"truncate text-xs text-zinc-500\">{member.email}</span>\n                  </div>\n                  <span className=\"inline-flex h-5.5 items-center rounded-md border border-zinc-950/10 px-2 text-xs font-medium text-zinc-700 dark:border-white/15 dark:text-zinc-300\">\n                    {member.role}\n                  </span>\n                </li>\n              ))}\n            </ul>\n          )}\n        </div>\n\n        {loading ? (\n          <SkeletonGroup label=\"Loading usage\">\n            <SkeletonCard lines={2} />\n          </SkeletonGroup>\n        ) : (\n          <div className=\"grid gap-4 rounded-xl border border-zinc-950/10 p-5 dark:border-white/10\">\n            <div className=\"flex items-center gap-3\">\n              <span className=\"flex size-8 items-center justify-center rounded-full bg-zinc-950 text-xs font-semibold text-white dark:bg-white dark:text-black\">\n                N\n              </span>\n              <div className=\"grid\">\n                <span className=\"text-sm font-medium text-zinc-950 dark:text-white\">Northwind</span>\n                <span className=\"text-xs text-zinc-500\">Team plan</span>\n              </div>\n            </div>\n            <p className=\"text-sm leading-5 text-zinc-600 dark:text-zinc-400\">\n              3 of 10 seats used. Billing renews on December 1.\n            </p>\n          </div>\n        )}\n      </div>\n    </div>\n  );\n}\n"
  }
}
