{
  "id": "text-reveal",
  "type": "motion",
  "status": "published",
  "name": {
    "zh": "文字显现",
    "en": "Text Reveal"
  },
  "aliases": [
    "文字一段一段出现",
    "文字逐行出现",
    "标题文字渐显",
    "一行一行浮现",
    "打字机出现"
  ],
  "category": [
    "Motion",
    "Text"
  ],
  "description": {
    "zh": "把标题或段落按行、按词逐个显现，而不是整块淡入。文字\"被说出来\"的节奏感让信息有先后与分量， 常用于落地页首屏大标题、章节开场与滚动叙事， 通常进入视口时触发一次。",
    "en": "Reveals a headline line by line or word by word instead of fading the whole block in. The spoken-rhythm staggering gives copy order and weight — a staple of landing-page hero titles, section intros and scrollytelling, usually triggered once on entering the viewport."
  },
  "use_when": [
    {
      "zh": "落地页首屏大标题、品牌口号需要登场感",
      "en": "Hero headlines and taglines that need an entrance"
    },
    {
      "zh": "滚动到视口时逐段显现，引导阅读顺序",
      "en": "Scroll-triggered sections that guide reading order"
    },
    {
      "zh": "编辑排版类页面，文字本身是主角",
      "en": "Editorial layouts where type is the protagonist"
    }
  ],
  "avoid_when": [
    {
      "zh": "正文段落逐词动画（阅读被拖慢，用户会烦）",
      "en": "Animating body copy word by word — it delays reading"
    },
    {
      "zh": "需要快速扫读的界面（后台、表格、文档）",
      "en": "Interfaces built for scanning — dashboards, tables, docs"
    },
    {
      "zh": "一屏多组文字同时做入场动画（互相打架）",
      "en": "Multiple competing text entrances in one viewport"
    }
  ],
  "tags": [
    "animation",
    "text",
    "typography",
    "entrance"
  ],
  "variants": [
    {
      "id": "line-mask",
      "name": {
        "zh": "行遮罩上滑",
        "en": "Line mask"
      },
      "note": {
        "zh": "文字从遮挡条下方向上滑出，电影字幕感",
        "en": "Lines slide up from behind a mask — cinematic captions"
      }
    },
    {
      "id": "word-stagger",
      "name": {
        "zh": "按词浮现",
        "en": "Word stagger"
      },
      "note": {
        "zh": "单词逐个上浮淡入，节奏更快",
        "en": "Words fade in one by one — quicker tempo"
      }
    },
    {
      "id": "typewriter",
      "name": {
        "zh": "打字机",
        "en": "Typewriter"
      },
      "note": {
        "zh": "逐字出现加闪烁光标，终端与对话感",
        "en": "Types characters with a blinking caret — terminal feel"
      }
    }
  ],
  "related": [
    {
      "id": "scroll-reveal",
      "relation": "similar_to"
    },
    {
      "id": "stagger-reveal",
      "relation": "similar_to"
    },
    {
      "id": "number-counter",
      "relation": "similar_to"
    },
    {
      "id": "editorial",
      "relation": "used_with"
    },
    {
      "id": "landing-page",
      "relation": "used_with"
    }
  ],
  "demo": {
    "component": "text-reveal",
    "modes": [
      "default",
      "variants"
    ],
    "motionControls": [
      "replay",
      "slow",
      "compare"
    ]
  },
  "implementation": {
    "css": [
      "overflow: hidden",
      "@keyframes translateY 100% → 0",
      "animation-delay stagger",
      "clip-path"
    ],
    "notes": {
      "zh": "行遮罩法：每行外层 overflow:hidden，内层从 translateY(100%) 过渡到 0，animation-delay 逐行递增 80～120ms， 比打字机更快读完。无动画时文字必须直接可见——初始 opacity:0 只能写在 keyframes 里； 尊重 prefers-reduced-motion 直接显示全文。",
      "en": "Line-mask recipe — wrap each line in overflow:hidden and animate the inner span from translateY(100%) to 0, stepping animation-delay 80–120ms per line. Faster to read than a typewriter. Text must be visible without animation — keep the initial opacity:0 inside the keyframes; with prefers-reduced-motion show everything at once."
    }
  },
  "sources": [
    {
      "name": "MDN — CSS animations",
      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations"
    }
  ],
  "prompts": {
    "basic": {
      "zh": "给首屏大标题添加文字显现效果：按行依次上浮出现。",
      "en": "Add a text reveal to the hero headline — lines float up one after another."
    },
    "design": {
      "zh": "首屏标题分三行，每行从遮罩下方向上滑入，600ms ease-out，行间延迟 100ms；动画只触发一次；无动画时文字直接可见。",
      "en": "Split the hero title into three lines, each sliding up from a mask, 600ms ease-out with a 100ms per-line delay; the animation plays once; text stays visible without animation."
    },
    "implementation": {
      "zh": "纯 CSS：外层 overflow:hidden，内层 @keyframes 从 translateY(100%) 到 0，animation-delay: calc(index * 100ms)。动画结束保持终态（forwards）。加 @media (prefers-reduced-motion: reduce) 直接显示。",
      "en": "CSS-only: outer overflow:hidden, inner keyframes translateY(100%) → 0, animation-delay calc(index * 100ms), fill-mode forwards. Add @media (prefers-reduced-motion: reduce) to show text immediately."
    },
    "agent": {
      "zh": "为当前项目落地页的首屏标题添加逐行文字显现。\n\n先检查现有入场动画与令牌，保持节奏一致。\n要求：\n- 行遮罩上滑，行间延迟 80～120ms，600ms 内完成\n- 只在进入视口后触发一次\n- 无 JS 时文字可直接可见（渐进增强）\n- 尊重 prefers-reduced-motion\n- 不引入新依赖\n完成后运行现有检查，说明修改文件。",
      "en": "Add a line-by-line text reveal to the project's hero headline.\n\nCheck existing entrance animations and tokens first; keep the rhythm consistent.\nRequirements:\n- Line mask slide-up, 80–120ms stagger, under 600ms total\n- Triggered once when entering the viewport\n- Text visible without JS (progressive enhancement)\n- Respect prefers-reduced-motion\n- No new dependencies\nRun existing checks when done and list modified files."
    }
  }
}