From 8a3924c6603dc521477100bade63bb833a294a14 Mon Sep 17 00:00:00 2001
From: Oliver Mee <102673257+oliver-mee@users.noreply.github.com>
Date: Tue, 18 Aug 2026 14:16:30 +0800
Subject: [PATCH] feat(registry): let components declare a description

Every published registry item carried a placeholder description, because
build-registry-index.ts falls back to `A ${type} component.` and there was
nowhere to declare anything else. 158 items shared four description strings.

The shadcn CLI ranks search across descriptions as well as titles, so this made
the registry reachable only by exact component name, which is the hardest thing
to guess for visual effects.

Read `description` from the sidecar .json next to each component, the same file
that already carries cssVars and additionalDependencies, following the existing
pattern in generateRegistryItem. The fallback is untouched, so anything without
a description behaves as before.

Adds a description for all 45 components under src/fancy/components, written
from each component's source and its demo. The 99 demo entries keep the
placeholder.
---
 .../components/background/animated-gradient-with-svg.json  | 1 +
 src/fancy/components/background/pixel-trail.json           | 3 +++
 src/fancy/components/blocks/circling-elements.json         | 1 +
 src/fancy/components/blocks/css-box.json                   | 3 +++
 src/fancy/components/blocks/drag-elements.json             | 3 +++
 src/fancy/components/blocks/element-along-svg-path.json    | 3 +++
 src/fancy/components/blocks/float.json                     | 3 +++
 src/fancy/components/blocks/marquee-along-svg-path.json    | 3 +++
 src/fancy/components/blocks/media-between-text.json        | 3 +++
 src/fancy/components/blocks/screensaver.json               | 3 +++
 src/fancy/components/blocks/simple-carousel.json           | 3 +++
 src/fancy/components/blocks/simple-marquee.json            | 3 +++
 src/fancy/components/blocks/stacking-cards.json            | 3 +++
 src/fancy/components/carousel/box-carousel.json            | 3 +++
 src/fancy/components/filter/gooey-svg-filter.json          | 3 +++
 src/fancy/components/filter/pixelate-svg-filter.json       | 3 +++
 src/fancy/components/image/image-trail.json                | 3 +++
 src/fancy/components/image/parallax-floating.json          | 3 +++
 .../components/physics/cursor-attractor-and-gravity.json   | 7 +++----
 src/fancy/components/physics/elastic-line.json             | 3 +++
 src/fancy/components/physics/gravity.json                  | 7 +++----
 src/fancy/components/text/basic-number-ticker.json         | 3 +++
 src/fancy/components/text/breathing-text.json              | 3 +++
 src/fancy/components/text/letter-3d-swap.json              | 3 +++
 src/fancy/components/text/letter-swap-forward-anim.json    | 3 +++
 src/fancy/components/text/letter-swap-pingpong-anim.json   | 3 +++
 .../components/text/random-letter-swap-forward-anim.json   | 3 +++
 .../components/text/random-letter-swap-pingpong-anim.json  | 3 +++
 src/fancy/components/text/scramble-hover.json              | 3 +++
 src/fancy/components/text/scramble-in.json                 | 3 +++
 src/fancy/components/text/scroll-and-swap-text.json        | 3 +++
 src/fancy/components/text/text-along-path.json             | 3 +++
 src/fancy/components/text/text-cursor-proximity.json       | 3 +++
 src/fancy/components/text/text-highlighter.json            | 3 +++
 src/fancy/components/text/text-rotate.json                 | 3 +++
 src/fancy/components/text/typewriter.json                  | 3 +++
 src/fancy/components/text/underline-center.json            | 3 +++
 src/fancy/components/text/underline-comes-in-goes-out.json | 3 +++
 src/fancy/components/text/underline-goes-out-comes-in.json | 3 +++
 src/fancy/components/text/underline-to-background.json     | 3 +++
 src/fancy/components/text/variable-font-and-cursor.json    | 3 +++
 .../components/text/variable-font-cursor-proximity.json    | 3 +++
 .../components/text/variable-font-hover-by-letter.json     | 3 +++
 .../text/variable-font-hover-by-random-letter.json         | 3 +++
 src/fancy/components/text/vertical-cut-reveal.json         | 3 +++
 src/fancy/schema.ts                                        | 1 +
 src/scripts/build-registry-index.ts                        | 3 +++
 47 files changed, 135 insertions(+), 8 deletions(-)
 create mode 100644 src/fancy/components/background/pixel-trail.json
 create mode 100644 src/fancy/components/blocks/css-box.json
 create mode 100644 src/fancy/components/blocks/drag-elements.json
 create mode 100644 src/fancy/components/blocks/element-along-svg-path.json
 create mode 100644 src/fancy/components/blocks/float.json
 create mode 100644 src/fancy/components/blocks/marquee-along-svg-path.json
 create mode 100644 src/fancy/components/blocks/media-between-text.json
 create mode 100644 src/fancy/components/blocks/screensaver.json
 create mode 100644 src/fancy/components/blocks/simple-carousel.json
 create mode 100644 src/fancy/components/blocks/simple-marquee.json
 create mode 100644 src/fancy/components/blocks/stacking-cards.json
 create mode 100644 src/fancy/components/carousel/box-carousel.json
 create mode 100644 src/fancy/components/filter/gooey-svg-filter.json
 create mode 100644 src/fancy/components/filter/pixelate-svg-filter.json
 create mode 100644 src/fancy/components/image/image-trail.json
 create mode 100644 src/fancy/components/image/parallax-floating.json
 create mode 100644 src/fancy/components/physics/elastic-line.json
 create mode 100644 src/fancy/components/text/basic-number-ticker.json
 create mode 100644 src/fancy/components/text/breathing-text.json
 create mode 100644 src/fancy/components/text/letter-3d-swap.json
 create mode 100644 src/fancy/components/text/letter-swap-forward-anim.json
 create mode 100644 src/fancy/components/text/letter-swap-pingpong-anim.json
 create mode 100644 src/fancy/components/text/random-letter-swap-forward-anim.json
 create mode 100644 src/fancy/components/text/random-letter-swap-pingpong-anim.json
 create mode 100644 src/fancy/components/text/scramble-hover.json
 create mode 100644 src/fancy/components/text/scramble-in.json
 create mode 100644 src/fancy/components/text/scroll-and-swap-text.json
 create mode 100644 src/fancy/components/text/text-along-path.json
 create mode 100644 src/fancy/components/text/text-cursor-proximity.json
 create mode 100644 src/fancy/components/text/text-highlighter.json
 create mode 100644 src/fancy/components/text/text-rotate.json
 create mode 100644 src/fancy/components/text/typewriter.json
 create mode 100644 src/fancy/components/text/underline-center.json
 create mode 100644 src/fancy/components/text/underline-comes-in-goes-out.json
 create mode 100644 src/fancy/components/text/underline-goes-out-comes-in.json
 create mode 100644 src/fancy/components/text/underline-to-background.json
 create mode 100644 src/fancy/components/text/variable-font-and-cursor.json
 create mode 100644 src/fancy/components/text/variable-font-cursor-proximity.json
 create mode 100644 src/fancy/components/text/variable-font-hover-by-letter.json
 create mode 100644 src/fancy/components/text/variable-font-hover-by-random-letter.json
 create mode 100644 src/fancy/components/text/vertical-cut-reveal.json

diff --git a/src/fancy/components/background/animated-gradient-with-svg.json b/src/fancy/components/background/animated-gradient-with-svg.json
index 1691452a..ecdc036d 100644
--- a/src/fancy/components/background/animated-gradient-with-svg.json
+++ b/src/fancy/components/background/animated-gradient-with-svg.json
@@ -1,4 +1,5 @@
 {
+  "description": "Fills its container with softly blurred, randomly placed and sized SVG circles that drift and pulse, forming an ambient animated gradient backdrop.",
   "cssVars": {
     "@theme inline": {
       "--animate-background-gradient": "background-gradient",
diff --git a/src/fancy/components/background/pixel-trail.json b/src/fancy/components/background/pixel-trail.json
new file mode 100644
index 00000000..3a59440f
--- /dev/null
+++ b/src/fancy/components/background/pixel-trail.json
@@ -0,0 +1,3 @@
+{
+  "description": "Divides the container into a pixel grid that lights up and fades out as the cursor passes over it, leaving a trailing wake of squares."
+}
diff --git a/src/fancy/components/blocks/circling-elements.json b/src/fancy/components/blocks/circling-elements.json
index 9a268910..0c4d6b14 100644
--- a/src/fancy/components/blocks/circling-elements.json
+++ b/src/fancy/components/blocks/circling-elements.json
@@ -1,4 +1,5 @@
 {
+  "description": "Arranges child elements evenly around a circle and spins them continuously at a set radius, direction, and speed, pausable on hover.",
   "cssVars": {
     "@keyframes circling": {
       "0%": {
diff --git a/src/fancy/components/blocks/css-box.json b/src/fancy/components/blocks/css-box.json
new file mode 100644
index 00000000..b16d65f4
--- /dev/null
+++ b/src/fancy/components/blocks/css-box.json
@@ -0,0 +1,3 @@
+{
+  "description": "Renders a draggable, spring-animated 3D cube built from six CSS faces, with imperative controls to snap to any face or arbitrary rotation."
+}
diff --git a/src/fancy/components/blocks/drag-elements.json b/src/fancy/components/blocks/drag-elements.json
new file mode 100644
index 00000000..8bb9d189
--- /dev/null
+++ b/src/fancy/components/blocks/drag-elements.json
@@ -0,0 +1,3 @@
+{
+  "description": "Makes each child freely draggable within its container with elastic constraints and momentum, bringing the dragged item to the front."
+}
diff --git a/src/fancy/components/blocks/element-along-svg-path.json b/src/fancy/components/blocks/element-along-svg-path.json
new file mode 100644
index 00000000..245559e7
--- /dev/null
+++ b/src/fancy/components/blocks/element-along-svg-path.json
@@ -0,0 +1,3 @@
+{
+  "description": "Moves one or more child elements along a custom SVG path, driven either automatically over time or by scroll progress, slowing on hover."
+}
diff --git a/src/fancy/components/blocks/float.json b/src/fancy/components/blocks/float.json
new file mode 100644
index 00000000..5078c271
--- /dev/null
+++ b/src/fancy/components/blocks/float.json
@@ -0,0 +1,3 @@
+{
+  "description": "Applies continuous, organic sine-wave drifting and 3D tilt to its children, simulating a slow floating object suspended in space."
+}
diff --git a/src/fancy/components/blocks/marquee-along-svg-path.json b/src/fancy/components/blocks/marquee-along-svg-path.json
new file mode 100644
index 00000000..13695201
--- /dev/null
+++ b/src/fancy/components/blocks/marquee-along-svg-path.json
@@ -0,0 +1,3 @@
+{
+  "description": "Loops repeated copies of its children endlessly along a custom SVG path, with optional scroll-linked speed, drag, and rolling z-index depth."
+}
diff --git a/src/fancy/components/blocks/media-between-text.json b/src/fancy/components/blocks/media-between-text.json
new file mode 100644
index 00000000..fe15c9a9
--- /dev/null
+++ b/src/fancy/components/blocks/media-between-text.json
@@ -0,0 +1,3 @@
+{
+  "description": "Expands an image or video from zero width between two text labels on hover, scroll into view, or manual trigger, like text swallowing a thumbnail."
+}
diff --git a/src/fancy/components/blocks/screensaver.json b/src/fancy/components/blocks/screensaver.json
new file mode 100644
index 00000000..57289664
--- /dev/null
+++ b/src/fancy/components/blocks/screensaver.json
@@ -0,0 +1,3 @@
+{
+  "description": "Bounces its child element around inside a container at a constant angle and speed, reflecting off the edges like a classic DVD screensaver."
+}
diff --git a/src/fancy/components/blocks/simple-carousel.json b/src/fancy/components/blocks/simple-carousel.json
new file mode 100644
index 00000000..6981e5ea
--- /dev/null
+++ b/src/fancy/components/blocks/simple-carousel.json
@@ -0,0 +1,3 @@
+{
+  "description": "Scrolls repeated children endlessly in a row or column at constant velocity, with optional scroll-linked speed, hover slowdown, and drag control."
+}
diff --git a/src/fancy/components/blocks/simple-marquee.json b/src/fancy/components/blocks/simple-marquee.json
new file mode 100644
index 00000000..6981e5ea
--- /dev/null
+++ b/src/fancy/components/blocks/simple-marquee.json
@@ -0,0 +1,3 @@
+{
+  "description": "Scrolls repeated children endlessly in a row or column at constant velocity, with optional scroll-linked speed, hover slowdown, and drag control."
+}
diff --git a/src/fancy/components/blocks/stacking-cards.json b/src/fancy/components/blocks/stacking-cards.json
new file mode 100644
index 00000000..d99e5c32
--- /dev/null
+++ b/src/fancy/components/blocks/stacking-cards.json
@@ -0,0 +1,3 @@
+{
+  "description": "Stacks sticky cards on scroll so each new card shrinks the ones beneath it, creating a layered deck-of-cards reveal effect."
+}
diff --git a/src/fancy/components/carousel/box-carousel.json b/src/fancy/components/carousel/box-carousel.json
new file mode 100644
index 00000000..6bf98a11
--- /dev/null
+++ b/src/fancy/components/carousel/box-carousel.json
@@ -0,0 +1,3 @@
+{
+  "description": "Displays images or videos on the faces of a rotating 3D cube, navigable by drag, buttons, or keyboard to cycle through media items."
+}
diff --git a/src/fancy/components/filter/gooey-svg-filter.json b/src/fancy/components/filter/gooey-svg-filter.json
new file mode 100644
index 00000000..50079d7c
--- /dev/null
+++ b/src/fancy/components/filter/gooey-svg-filter.json
@@ -0,0 +1,3 @@
+{
+  "description": "An SVG filter definition that blurs and re-thresholds overlapping shapes so they visually merge into a smooth, blobby gooey mass."
+}
diff --git a/src/fancy/components/filter/pixelate-svg-filter.json b/src/fancy/components/filter/pixelate-svg-filter.json
new file mode 100644
index 00000000..aad68483
--- /dev/null
+++ b/src/fancy/components/filter/pixelate-svg-filter.json
@@ -0,0 +1,3 @@
+{
+  "description": "An SVG filter definition that mosaics whatever it's applied to into large flat blocks, producing a chunky pixelated look at a configurable block size."
+}
diff --git a/src/fancy/components/image/image-trail.json b/src/fancy/components/image/image-trail.json
new file mode 100644
index 00000000..7266903f
--- /dev/null
+++ b/src/fancy/components/image/image-trail.json
@@ -0,0 +1,3 @@
+{
+  "description": "Reveals repeated child images one by one as the cursor moves past a distance threshold, each easing toward the pointer to form a following trail."
+}
diff --git a/src/fancy/components/image/parallax-floating.json b/src/fancy/components/image/parallax-floating.json
new file mode 100644
index 00000000..2257ecb1
--- /dev/null
+++ b/src/fancy/components/image/parallax-floating.json
@@ -0,0 +1,3 @@
+{
+  "description": "Shifts registered child elements by amounts proportional to their declared depth as the cursor moves, producing a multi-layer parallax effect."
+}
diff --git a/src/fancy/components/physics/cursor-attractor-and-gravity.json b/src/fancy/components/physics/cursor-attractor-and-gravity.json
index 4833f518..d6604ae2 100644
--- a/src/fancy/components/physics/cursor-attractor-and-gravity.json
+++ b/src/fancy/components/physics/cursor-attractor-and-gravity.json
@@ -1,5 +1,4 @@
 {
-    "additionalDependencies": [
-        "poly-decomp", "@types/matter-js"
-    ]
-}
\ No newline at end of file
+  "description": "Runs a Matter.js physics simulation where draggable DOM elements are pulled toward both a fixed attractor point and the cursor whenever it is within a set radius.",
+  "additionalDependencies": ["poly-decomp", "@types/matter-js"]
+}
diff --git a/src/fancy/components/physics/elastic-line.json b/src/fancy/components/physics/elastic-line.json
new file mode 100644
index 00000000..e3c22353
--- /dev/null
+++ b/src/fancy/components/physics/elastic-line.json
@@ -0,0 +1,3 @@
+{
+  "description": "Draws a straight SVG line that can be grabbed and pulled into a curve, springing back to straight when released, like a plucked string."
+}
diff --git a/src/fancy/components/physics/gravity.json b/src/fancy/components/physics/gravity.json
index 4833f518..6caf7e86 100644
--- a/src/fancy/components/physics/gravity.json
+++ b/src/fancy/components/physics/gravity.json
@@ -1,5 +1,4 @@
 {
-    "additionalDependencies": [
-        "poly-decomp", "@types/matter-js"
-    ]
-}
\ No newline at end of file
+  "description": "Runs a Matter.js physics simulation that turns DOM children into draggable rigid bodies which fall, collide, and settle under configurable gravity.",
+  "additionalDependencies": ["poly-decomp", "@types/matter-js"]
+}
diff --git a/src/fancy/components/text/basic-number-ticker.json b/src/fancy/components/text/basic-number-ticker.json
new file mode 100644
index 00000000..d420811f
--- /dev/null
+++ b/src/fancy/components/text/basic-number-ticker.json
@@ -0,0 +1,3 @@
+{
+  "description": "Animates a number counting from a start value to a target value over a configurable transition, with imperative start and complete callbacks."
+}
diff --git a/src/fancy/components/text/breathing-text.json b/src/fancy/components/text/breathing-text.json
new file mode 100644
index 00000000..4a12fe8a
--- /dev/null
+++ b/src/fancy/components/text/breathing-text.json
@@ -0,0 +1,3 @@
+{
+  "description": "Cycles each letter's variable font weight (or other font-variation axis) back and forth on a staggered loop, giving text a pulsing breathing look."
+}
diff --git a/src/fancy/components/text/letter-3d-swap.json b/src/fancy/components/text/letter-3d-swap.json
new file mode 100644
index 00000000..d33a99f3
--- /dev/null
+++ b/src/fancy/components/text/letter-3d-swap.json
@@ -0,0 +1,3 @@
+{
+  "description": "On hover, flips each letter as a 3D cube face to reveal a second character behind it, staggered per letter in a chosen rotation direction."
+}
diff --git a/src/fancy/components/text/letter-swap-forward-anim.json b/src/fancy/components/text/letter-swap-forward-anim.json
new file mode 100644
index 00000000..1fb1f576
--- /dev/null
+++ b/src/fancy/components/text/letter-swap-forward-anim.json
@@ -0,0 +1,3 @@
+{
+  "description": "On hover, slides each letter out and swaps in a duplicate that resets instantly, playing the letters in order (first to last) once per hover."
+}
diff --git a/src/fancy/components/text/letter-swap-pingpong-anim.json b/src/fancy/components/text/letter-swap-pingpong-anim.json
new file mode 100644
index 00000000..762b4e75
--- /dev/null
+++ b/src/fancy/components/text/letter-swap-pingpong-anim.json
@@ -0,0 +1,3 @@
+{
+  "description": "On hover, slides letters in sequence to reveal a duplicate underneath, then slides them back in the same order when the cursor leaves."
+}
diff --git a/src/fancy/components/text/random-letter-swap-forward-anim.json b/src/fancy/components/text/random-letter-swap-forward-anim.json
new file mode 100644
index 00000000..464ef22f
--- /dev/null
+++ b/src/fancy/components/text/random-letter-swap-forward-anim.json
@@ -0,0 +1,3 @@
+{
+  "description": "On hover, slides each letter out to reveal a duplicate in a randomized per-letter order, playing forward once without reversing on hover-out."
+}
diff --git a/src/fancy/components/text/random-letter-swap-pingpong-anim.json b/src/fancy/components/text/random-letter-swap-pingpong-anim.json
new file mode 100644
index 00000000..93266846
--- /dev/null
+++ b/src/fancy/components/text/random-letter-swap-pingpong-anim.json
@@ -0,0 +1,3 @@
+{
+  "description": "On hover, slides letters in a randomized order to reveal duplicates underneath, then reverses the swap back when the cursor leaves."
+}
diff --git a/src/fancy/components/text/scramble-hover.json b/src/fancy/components/text/scramble-hover.json
new file mode 100644
index 00000000..4366ba80
--- /dev/null
+++ b/src/fancy/components/text/scramble-hover.json
@@ -0,0 +1,3 @@
+{
+  "description": "While hovered, cycles each character through random glyphs before settling, optionally revealing characters in sequence from the start, end, or center."
+}
diff --git a/src/fancy/components/text/scramble-in.json b/src/fancy/components/text/scramble-in.json
new file mode 100644
index 00000000..96d6211b
--- /dev/null
+++ b/src/fancy/components/text/scramble-in.json
@@ -0,0 +1,3 @@
+{
+  "description": "On mount or manual trigger, reveals text left to right while a trailing window of characters scrambles through random glyphs just ahead of the reveal."
+}
diff --git a/src/fancy/components/text/scroll-and-swap-text.json b/src/fancy/components/text/scroll-and-swap-text.json
new file mode 100644
index 00000000..36f36da6
--- /dev/null
+++ b/src/fancy/components/text/scroll-and-swap-text.json
@@ -0,0 +1,3 @@
+{
+  "description": "Slides the current text up and out while a duplicate slides up into place, with the transition driven by scroll progress through a tracked container."
+}
diff --git a/src/fancy/components/text/text-along-path.json b/src/fancy/components/text/text-along-path.json
new file mode 100644
index 00000000..72828eff
--- /dev/null
+++ b/src/fancy/components/text/text-along-path.json
@@ -0,0 +1,3 @@
+{
+  "description": "Renders text following a custom SVG path, animating its position along the path automatically over time or by tying it to scroll progress."
+}
diff --git a/src/fancy/components/text/text-cursor-proximity.json b/src/fancy/components/text/text-cursor-proximity.json
new file mode 100644
index 00000000..d73836dd
--- /dev/null
+++ b/src/fancy/components/text/text-cursor-proximity.json
@@ -0,0 +1,3 @@
+{
+  "description": "Animates each letter's CSS properties based on its distance from the cursor, with linear, exponential, or gaussian falloff for a proximity-reactive effect."
+}
diff --git a/src/fancy/components/text/text-highlighter.json b/src/fancy/components/text/text-highlighter.json
new file mode 100644
index 00000000..2954ba3e
--- /dev/null
+++ b/src/fancy/components/text/text-highlighter.json
@@ -0,0 +1,3 @@
+{
+  "description": "Sweeps a colored highlight background across text from a chosen direction, triggered on hover, scroll into view, or manual control."
+}
diff --git a/src/fancy/components/text/text-rotate.json b/src/fancy/components/text/text-rotate.json
new file mode 100644
index 00000000..281cfd0d
--- /dev/null
+++ b/src/fancy/components/text/text-rotate.json
@@ -0,0 +1,3 @@
+{
+  "description": "Cycles through an array of text strings, animating each in and out by words, characters, or lines with staggered enter and exit transitions."
+}
diff --git a/src/fancy/components/text/typewriter.json b/src/fancy/components/text/typewriter.json
new file mode 100644
index 00000000..19468db6
--- /dev/null
+++ b/src/fancy/components/text/typewriter.json
@@ -0,0 +1,3 @@
+{
+  "description": "Types out one or more strings character by character with a blinking cursor, then deletes and retypes the next string when given an array."
+}
diff --git a/src/fancy/components/text/underline-center.json b/src/fancy/components/text/underline-center.json
new file mode 100644
index 00000000..6702f77a
--- /dev/null
+++ b/src/fancy/components/text/underline-center.json
@@ -0,0 +1,3 @@
+{
+  "description": "On hover, grows an underline outward from the center of the text to full width beneath it, for a centered reveal effect."
+}
diff --git a/src/fancy/components/text/underline-comes-in-goes-out.json b/src/fancy/components/text/underline-comes-in-goes-out.json
new file mode 100644
index 00000000..29b0894c
--- /dev/null
+++ b/src/fancy/components/text/underline-comes-in-goes-out.json
@@ -0,0 +1,3 @@
+{
+  "description": "On hover, an underline grows in from one edge across the full text width, then shrinks back out the opposite edge on the way out."
+}
diff --git a/src/fancy/components/text/underline-goes-out-comes-in.json b/src/fancy/components/text/underline-goes-out-comes-in.json
new file mode 100644
index 00000000..08c60b1f
--- /dev/null
+++ b/src/fancy/components/text/underline-goes-out-comes-in.json
@@ -0,0 +1,3 @@
+{
+  "description": "On hover, an underline shrinks away from one edge before regrowing across the full text width from the opposite edge, the reverse of comes-in-goes-out."
+}
diff --git a/src/fancy/components/text/underline-to-background.json b/src/fancy/components/text/underline-to-background.json
new file mode 100644
index 00000000..a2cd089d
--- /dev/null
+++ b/src/fancy/components/text/underline-to-background.json
@@ -0,0 +1,3 @@
+{
+  "description": "On hover, expands a thin underline vertically into a full background fill behind the text while the text color animates to a target color."
+}
diff --git a/src/fancy/components/text/variable-font-and-cursor.json b/src/fancy/components/text/variable-font-and-cursor.json
new file mode 100644
index 00000000..880eab6e
--- /dev/null
+++ b/src/fancy/components/text/variable-font-and-cursor.json
@@ -0,0 +1,3 @@
+{
+  "description": "Maps cursor x and y position within a container to two variable font axes, morphing the whole text's weight or slant as the mouse moves."
+}
diff --git a/src/fancy/components/text/variable-font-cursor-proximity.json b/src/fancy/components/text/variable-font-cursor-proximity.json
new file mode 100644
index 00000000..ecb1b963
--- /dev/null
+++ b/src/fancy/components/text/variable-font-cursor-proximity.json
@@ -0,0 +1,3 @@
+{
+  "description": "Interpolates each letter's variable font axes individually based on distance from the cursor, with linear, exponential, or gaussian falloff."
+}
diff --git a/src/fancy/components/text/variable-font-hover-by-letter.json b/src/fancy/components/text/variable-font-hover-by-letter.json
new file mode 100644
index 00000000..a7e3ac4e
--- /dev/null
+++ b/src/fancy/components/text/variable-font-hover-by-letter.json
@@ -0,0 +1,3 @@
+{
+  "description": "On hover, animates every letter's variable font settings (like weight or slant) together in a staggered sweep from a chosen starting letter."
+}
diff --git a/src/fancy/components/text/variable-font-hover-by-random-letter.json b/src/fancy/components/text/variable-font-hover-by-random-letter.json
new file mode 100644
index 00000000..d8452471
--- /dev/null
+++ b/src/fancy/components/text/variable-font-hover-by-random-letter.json
@@ -0,0 +1,3 @@
+{
+  "description": "On hover, animates each letter's variable font settings in a randomized per-letter order rather than sweeping sequentially across the text."
+}
diff --git a/src/fancy/components/text/vertical-cut-reveal.json b/src/fancy/components/text/vertical-cut-reveal.json
new file mode 100644
index 00000000..a1c5a408
--- /dev/null
+++ b/src/fancy/components/text/vertical-cut-reveal.json
@@ -0,0 +1,3 @@
+{
+  "description": "Reveals text by sliding words, characters, or lines up (or down) into view from behind a clipped mask, staggered across the chosen split unit."
+}
diff --git a/src/fancy/schema.ts b/src/fancy/schema.ts
index e7b4a5c0..edfcfd3b 100644
--- a/src/fancy/schema.ts
+++ b/src/fancy/schema.ts
@@ -9,6 +9,7 @@ export const registrySchema = z.record(
   z.string(),
   z.object({
     name: z.string(),
+    description: z.string().optional(), // one line summary of the component. fetched from the addition .json file next to the component .tsx file
     dependencies: z.array(z.string()).optional(), // external dependencies. inferred from the import statements, and fetched from the addition .json file next to the component .tsx file
     devDependencies: z.array(z.string()).optional(), // dev dependencies. fetched from the addition .json file next to the component .tsx file
     registryDependencies: z.array(z.string()).optional(), // other component dependencies
diff --git a/src/scripts/build-registry-index.ts b/src/scripts/build-registry-index.ts
index 14a2155a..188c3ef2 100644
--- a/src/scripts/build-registry-index.ts
+++ b/src/scripts/build-registry-index.ts
@@ -340,6 +340,9 @@ function generateRegistryItem(
           ],
         }
       : null),
+    ...(additionalConfig?.description && {
+      description: additionalConfig.description,
+    }),
     ...(additionalConfig?.tailwind && {
       tailwind: additionalConfig.tailwind,
     }),