Add intro to the docs

Author: Adam Plesnik

src/css/keyframes.css

@@ -62,3 +62,12 @@
     transform: translateY(-60%);
   }
 }
+
+@keyframes opacity {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}

src/demos/DemoWrapper.tsx

@@ -26,9 +26,8 @@ const DemoWrapper = ({
         addWithSpace(className)
       }
     >
-      {children}
       {actionButton && (
-        <div className="absolute right-3 top-3">
+        <div className="sticky top-0 z-10 -mb-10 flex justify-end pr-2 pt-2">
           <ActionButton
             Icon={Repeat}
             IconOnClick={StepForward}
@@ -37,6 +36,7 @@ const DemoWrapper = ({
           />
         </div>
       )}
+      {children}
     </div>
   )
 }

src/demos/TimelineOverrideDemo.tsx

@@ -0,0 +1,26 @@
+import Code from '../components/Code'
+import DemoWrapper from './DemoWrapper'
+
+const TimelineOverrideDemo = () => {
+  return (
+    <DemoWrapper className="max-h-60 sm:max-h-48" actionButton>
+      <div className="sticky top-0  flex flex-col gap-4 p-8">
+        <div className="flex flex-1 items-center">
+          <span className="animate-opacity rounded-lg bg-sky-500/40 p-4 dark:bg-fuchsia-300/60">
+            <Code>timeline</Code> <span className="text-sm font-medium">before</span>{' '}
+            <Code>animate-opacity</Code>
+          </span>
+        </div>
+        <div className="flex flex-1 items-center">
+          <span className="animate-opacity rounded-lg bg-sky-500/40 p-4 timeline dark:bg-fuchsia-300/60">
+            <Code>animate-opacity</Code> <span className="text-sm font-medium">before</span>{' '}
+            <Code>timeline</Code>
+          </span>
+        </div>
+      </div>
+      <div className="h-96"></div>
+    </DemoWrapper>
+  )
+}
+
+export default TimelineOverrideDemo

src/docs/Docs.tsx

@@ -4,7 +4,15 @@ import Heading from '../components/Heading'
 import Paragraph from '../components/Paragraph'
 import MultiRangeDemo from '../demos/MultiRangeDemo'
 import SupportsDemo from '../demos/SupportsDemo'
-import { multiRange, multiRangeKeyframes, supports } from '../utils/demoExamples'
+import TimelineOverrideDemo from '../demos/TimelineOverrideDemo'
+import {
+  keyframes101,
+  keyframes102,
+  keyframes103,
+  multiRange,
+  multiRangeKeyframes,
+  supports,
+} from '../utils/demoExamples'
 import DocsTable from './DocsTable'
 
 const animationTimelineClasses = [
@@ -51,6 +59,25 @@ const Docs = () => {
       <Heading size={2} id="documentation">
         Documentation
       </Heading>
+      <Heading size={3} id="documentation-101">
+        How to Make Your CSS Animation Scroll-driven
+      </Heading>
+      <Paragraph>
+        CSS animations consist of two components, a set of keyframes and a style describing the
+        animation. Let's declare a simple <Code>@opacity</Code> keyframe set and apply it to an
+        element we want to control by a scroll timeline.
+      </Paragraph>
+      <CodeBlock language="css">{keyframes101}</CodeBlock>
+      <CodeBlock language="html">{keyframes102}</CodeBlock>
+      <Paragraph>
+        To effectively control the animation, make sure to declare the timeline in the code after
+        the animation. By default, the shorthand <Code>animation</Code> property sets the{' '}
+        <Code>animation-timeline: auto</Code> unless set otherwise. However, using this plugin and
+        Tailwind CSS animations ensures that the declaration order is correct.
+      </Paragraph>
+      <CodeBlock language="css">{keyframes103}</CodeBlock>
+      <Paragraph>Scroll the container.</Paragraph>
+      <TimelineOverrideDemo />
       <Heading size={3} href="#timeline" hrefType="demo" id="documentation-animation-timeline">
         Animation Timeline
       </Heading>
@@ -59,7 +86,6 @@ const Docs = () => {
         animation.
       </Paragraph>
       <DocsTable items={animationTimelineClasses} />
-
       <Heading size={3} href="#range" hrefType="demo" id="documentation-scroll-timeline">
         Scroll Timeline
       </Heading>
@@ -68,7 +94,6 @@ const Docs = () => {
         element.
       </Paragraph>
       <DocsTable items={scrollTimelineClasses} />
-
       <Heading size={3} href="#range" hrefType="demo" id="documentation-view-timeline">
         View Timeline
       </Heading>
@@ -85,7 +110,7 @@ const Docs = () => {
         on the animated element.
       </Paragraph>
       <DocsTable items={rangeClasses} />
-      <Paragraph size="small" className="pt-6">
+      <Paragraph className="pt-6">
         Scroll the container to see each how range utility class affects the animation.
       </Paragraph>
       <MultiRangeDemo />

src/utils/demoExamples.ts

@@ -82,3 +82,29 @@ export const supports = `<div>
   </div>
   ...   
 </div>`
+
+export const keyframes101 = `@keyframes opacity {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}`
+
+export const keyframes102 = `<div class="animate-opacity timeline">
+  <!-- The animation should be controlled by the timeline. -->
+</div>`
+
+export const keyframes103 = `
+.timeline { /* This timeline would be overriden */
+  animation-timeline: scroll(y);
+}
+
+.animate-opacity {
+  animation: opacity 8s ease-in-out both;
+}
+
+.timeline { /* This is the correct order */
+  animation-timeline: scroll(y);
+}`

tailwind.config.js

@@ -16,6 +16,7 @@ module.exports = {
         /* Scroll-driven animations */
         appear: 'appear auto cubic-bezier(0.65, 0.05, 0.17, 0.99) forwards',
         down: 'translate-down auto ease-in-out forwards',
+        opacity: 'opacity 8s ease-in-out forwards',
         'scale-to-right': 'scale-to-right auto linear forwards',
         'translate-down': 'translate-down auto cubic-bezier(0.65, 0.05, 0.17, 0.99) forwards',
         'translate-up': 'translate-up auto ease-in-out forwards',