Skip to main content
rule CX Codex

gradient-text-sweep — Claude Code rule: what it does, how to install

gradient-text-sweep guides Claude Code in animating gradients inside text via background-clip: text and GSAP. Fits title card sweeps, karaoke word reveals, and hue crossfades.

MIT ★ 328 updated 2026-10-29

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/gradient-text-sweep.md
Open on GitHub

What gradient-text-sweep does

This rule instructs Claude Code to animate color fills directly inside letterforms. Glyphs never move. The typography uses color: transparent paired with background-clip: text, while motion comes entirely from an oversized gradient sliding across the background. It structures three distinct patterns: a continuous title sweep, staggered word highlights, and a hue rotation that resolves into a solid tone.

The CSS mechanics introduce specific constraints. Tweening background-position only produces visible motion when background-size exceeds 100%, typically set to 200–400%. If set to 100%, the image stays pinned and the animation silently fails. The percentage axis is also inverted: interpolating from 100% 50% to 0% 50% moves the highlight from left to right.

Word-by-word highlights avoid DOM coordinate tracking. Each word consists of two identical grid-stacked spans: a resting base copy and an active highlight copy. GSAP cascades their opacity using a fixed WORD_LAG offset (0.25–0.5s). To lock into a solid tone, the recipe avoids tweening gradient color stops directly because browsers interpolate them inconsistently; it runs a quick crossfade to a stacked solid twin instead.

What it helps with

  • slide a gradient through letterforms without shifting glyph geometry
  • light up words sequentially without measuring individual DOM coordinates
  • transition a multi-stop color sweep into a solid brand tone
  • run a continuous sheen across a terminal video card using GSAP

Example prompts for the agent

  • Apply gradient-text-sweep to create a continuous linear sheen on the hero title.
  • Set up a word-to-word highlight across this headline using stacked span copies.
  • Animate a hue-sweep on the final word that settles into our primary accent color.

How to install gradient-text-sweep

Manually: put the files in place

.claude/rules/gradient-text-sweep.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about gradient-text-sweep

How do I install gradient-text-sweep in Claude Code?

Place the rule file at .claude/rules/gradient-text-sweep.md in your project root. Claude Code reads this file automatically when generating frontend typography animations.

What does gradient-text-sweep do?

It provides deterministic animation patterns for text fills using background-clip: text and GSAP. It standardizes continuous title sheens, sequential word lighting, and hue-based crossfades.

Why does tweening backgroundPosition produce no movement?

The background-size must strictly exceed 100%, with suggested values between 200% and 400%. At exactly 100%, the background image is locked to the container edges, making position updates a no-op.

Source text

gradient-text-sweep.md · MIT
---
name: gradient-text-sweep
description: A gradient tweened THROUGH letterforms — background-clip:text + a backgroundPosition tween. Three forms: a continuous horizontal sweep inside a held headline, a traveling word-to-word highlight, and a hue-sweep that settles to a solid. Glyphs never move; finite, deterministic, seek-safe.
metadata:
  tags: gradient, text, sweep, background-clip, highlight, hue, typography, headline
---

# Gradient Text Sweep

Color that lives **inside the glyphs**: the headline's fill is an oversized gradient clipped into the letterforms (`background-clip: text`), and the motion is the gradient sliding **through** the type — the letters never move. Three forms: a **continuous sweep** across a held title card, a **word-to-word highlight** that lights a line left→right, and a **hue-sweep** that settles to a solid.

Boundaries: [asr-keyword-glow.md](asr-keyword-glow.md) is word-timed emphasis railed to ASR timestamps — this rule is a design beat with no audio rail. [ambient-glow-bloom.md](ambient-glow-bloom.md)'s traveling sweep is a sheen riding **over a surface**; here the gradient is masked **into the type** (its "Shimmer sweep" variation is this mechanism re-aimed as a working-state loop). [css-marker-patterns.md](css-marker-patterns.md) draws accents _around_ text, never fills.

## How It Works

The text carries a gradient background **wider than its own box** (`background-size: SWEEP_SPAN 100%`, e.g. `300% 100%`) clipped into the glyphs, so tweening `backgroundPosition` slides the gradient through the visible letterforms. Two gotchas own this rule:

- **`background-position` percentages only produce travel when `background-size` exceeds 100%** — at 100% the image is pinned and the tween is a silent no-op.
- **The percent axis runs opposite to the perceived travel** — tweening `"100% 50%"` → `"0% 50%"` moves the highlight left→right through the text.

1. **Continuous sweep (held title card)** — one long **linear** `backgroundPosition` tween spanning the hold. First and last color stops equal, so the travel has no visible seam and reads as endless while remaining a single finite tween.
2. **Word-to-word highlight** — each word is two pixel-identical stacked copies: a base copy in the resting color and a gradient-clipped copy at `opacity: 0`. A per-word opacity envelope (rise, then fall as the next word rises) passes the highlight along on an index-derived stagger — an **envelope, not a moving mask**: no per-word position measurement.
3. **Hue-sweep → solid** — the gradient holds position while a `filter: hue-rotate()` tween sweeps its hues; the settle is a stacked-copy crossfade to a solid twin — never a color-stop tween (gradients with different stops don't interpolate reliably).

## Recipe

```html
<!-- inside a standard scene clip (hyperframes-core) -->
<!-- Forms A/C: gradient headline; solid twin behind for the Form C settle -->
<div class="headline-stack">
  <h1 class="headline solid-twin">{headlineText}</h1>
  <h1 class="headline gradient-fill" id="headline">{headlineText}</h1>
</div>

<!-- Form B: per-word stacked copies -->
<p class="line">
  <span class="word"><span class="w-base">{word1}</span><span class="w-hot">{word1}</span></span>
  <span class="word"><span class="w-base">{word2}</span><span class="w-hot">{word2}</span></span>
</p>
```

```css
.headline-stack,
.word {
  display: grid; /* twins share one cell — pixel-identical boxes */
}
.headline,
.w-base,
.w-hot {
  grid-area: 1 / 1;
}
.gradient-fill,
.w-hot {
  background-image: {gradient}; /* {sweepGradient} A/C, {highlightGradient} B */
  background-size: SWEEP_SPAN 100%; /* MUST exceed 100% or the position tween is dead */
  background-position: 100% 50%; /* start; tween toward 0% for left→right travel */
  -webkit-background-clip: text;
  background-clip: text;
  color: transparent;
}
.solid-twin {
  color: {settleColor};
}
.w-base {
  color: {restColor};
}
.w-hot {
  opacity: 0; /* the envelope raises it as the highlight passes */
}
```

```js
// Form A: continuous sweep. 100% → 0% reads left→right (percent axis inverted);
// ease "none" — an eased sweep reads as an object, not light.
tl.fromTo(
  "#headline",
  { backgroundPosition: "100% 50%" },
  { backgroundPosition: "0% 50%", duration: SWEEP_DUR, ease: "none" },
  SWEEP_START,
);

// Form B: traveling highlight — per-word rise/fall envelopes, index stagger.
gsap.utils.toArray(".w-hot").forEach((el, i) => {
  const at = HIGHLIGHT_START + i * WORD_LAG;
  tl.fromTo(el, { opacity: 0 }, { opacity: 1, duration: HOT_RISE, ease: "power2.out" }, at);
  tl.to(el, { opacity: 0, duration: HOT_FALL, ease: "power2.in" }, at + WORD_LAG);
});

// Form C: hue-sweep, then crossfade to the solid twin (never tween color stops).
tl.fromTo(
  "#headline",
  { filter: "hue-rotate(0deg)" },
  { filter: `hue-rotate(${HUE_RANGE}deg)`, duration: HUE_DUR, ease: "power1.inOut" },
  HUE_START,
);
tl.to(
  "#headline",
  { opacity: 0, duration: SETTLE_SNAP_DUR, ease: "power2.in" },
  HUE_START + HUE_DUR,
);
```

## Variations

- **Title-card crawl** — Form A stretched across a long terminal hold (3–8s end card): seamless-ended gradient, `ease: "none"`, `SWEEP_DUR` = the whole hold. One tween, no loop.
- **One-pass sheen inside type** — gradient is the resting fill everywhere except one narrow highlight band (≤ ~25% of the span); one `backgroundPosition` pass carries the band through and the text returns to rest with no crossfade.
- **Karaoke settle** — Form B with the fall tweens skipped: the line lights cumulatively left→right and holds fully lit; settle color = the hot state, base copies start dimmer.
- **Gradient climax word** — one emphasized word (often ~-8° rotated) carries the gradient while the line stays solid; static gradient + a short Form C hue shift on landing, settling to the brand accent. Pairs with a `kinetic-beat-slam` arrival.

## Values

| token               | range                  | notes                                                                                |
| ------------------- | ---------------------- | ------------------------------------------------------------------------------------ |
| SWEEP_SPAN          | 200–400%               | must exceed 100%; wider = softer/slower feel, narrower = busier color per glyph      |
| SWEEP_DUR           | 1.2–3s                 | match the card's hold exactly; slower than ~4s stops registering as motion           |
| WORD_LAG            | 0.25–0.5s              | HOT_FALL starts exactly WORD_LAG after the rise so envelopes cross — a gap = a blink |
| HOT_RISE / HOT_FALL | 0.15–0.3s / 0.25–0.45s | fall slightly longer — the highlight "trails"                                        |
| HUE_RANGE / HUE_DUR | 40–180° / 0.8–1.6s     | past ~180° the palette dissociates from itself mid-sweep                             |
| SETTLE_SNAP_DUR     | 0.1–0.35s              | the goldens snap (~0.15s)                                                            |
| {settleColor}       | —                      | one of the gradient's own stops (or the brand ink) so the settle reads as resolution |

## Critical Constraints

- **`background-size` > 100%** on any element whose `backgroundPosition` is tweened — otherwise the tween is a silent no-op.
- **Percent axis is inverted** — left→right perceived travel is `100% → 0%`.
- **Both `-webkit-background-clip: text` AND `background-clip: text`, with `color: transparent`** — missing the prefix renders a solid gradient block over the text in the capture browser.
- **`ease: "none"` on position sweeps** — this is supposed to read as light, not an accelerating object.
- **Seamless ends for a crawl** — first and last stops equal, or the wrap point flashes a hard edge mid-hold.
- **Stacked copies pixel-identical** — same box, font, weight, tracking, one grid cell; any metric drift makes the crossfade a double-exposure.
- **`data-layout-allow-occlusion` on the twin** — pixel-identical stacked copies trip `hyperframes check`'s `text_occluded` gate by construction; the flag is the sanctioned waiver for this mechanism.
- **Settle by crossfade, never by tweening stops**; and the glyphs never move — if the type must travel, that's a separate rule on the wrapper.
- **No CSS `@keyframes` shimmer** — wall-clock animation desyncs from seek; every sweep is a timeline tween.

## See also

`kinetic-beat-slam` (slam lands the climax word, hue settle finishes it) · `spring-pop-entrance` (pop in solid, sweep after) · `discrete-text-sequence` (swap-slot under a riding crawl) · `ambient-glow-bloom` (surface-level sibling) · `css-marker-patterns` (strokes around text; fills here).

© coco-research · MIT · coco-research/coco

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set82

The whole set →
test Runs the complete test cycle: coverage analysis, test generation, and regression validation. Call it to fill coverage gaps or verify the test suite runs end-to-end. CX Codex +1 ★ 328repo stars cognee:store cognee:store is a Claude Code skill that writes session entities, decisions and events to a Cognee knowledge graph through POST /api/v1/remember. Project agreements stay in the graph and come back on semantic search. CX Codex +1 ★ 328repo stars gsd-user-profiler The gsd-user-profiler subagent reads developer session messages and builds a behavioral profile with ratings, confidence levels, and evidence. A profiling workflow can launch it for analysis. CX Codex ★ 328repo stars mcp-specialist mcp-specialist — a subagent for building and configuring MCP servers in Claude Code. Handles architecture design, transport layer implementation, tool and resource setup, and connection troubleshooting against the MCP 2025-06-18 spec. CX Codex ★ 328repo stars ai-marketing-videos ai-marketing-videos is a Claude Code skill for product promos, ad creatives, and explainers using video and voice models. It combines scenes with a voice track. CX Codex +1 ★ 328repo stars fix A slash command for debugging: takes a bug report or failing test, traces the root cause, writes a regression test, and applies the fix. CX Codex +1 ★ 328repo stars cognee:recall cognee:recall is a Claude Code skill that searches a Cognee knowledge graph for entities, decisions, events and relationships. It uses semantic, graph-traversal and lexical search to add results to agent context. CX Codex +1 ★ 328repo stars browser-automation browser-automation enables agents to navigate URLs, fill web forms, interact with elements, and take screenshots. CX Codex +1 ★ 328repo stars

Project sponsors

Companies that keep this analytics open