Godui Learn Article

GodUI Learn Article

A Learn tab sits at the right of a component page's breadcrumb row (Docs | Learn segmented control). Docs is the normal component page; Learn is a blog-style, scroll-animated deconstruction of how the component's motion is built — layered scenes that auto-play on scroll-in with a replay button, annotated code, and a live result. Same layout as the rest of docs (sidenav + right TOC).

The tab system, routing, sidebar hiding, and the reusable ScrollScene primitive are already built and generic. Adding a Learn article to a new component is mostly: create the folder, write learn.mdx, and build a few component-specific scene components. This skill documents the whole system so you can extend it correctly.

Reference implementation: Magic Button — apps/docs/content/docs/components/buttons/magic-button/learn.mdx and apps/docs/src/components/learn/*.

Quick reference

How the system works (read before extending)

Routing — folder + index.mdx pattern (CRITICAL)

To get /docs/components/{cat}/{name} and /docs/components/{cat}/{name}/learn, the component must be a folder with index.mdx, not a flat {name}.mdx file:

components/buttons/magic-button/
  index.mdx   ← the Docs page (was magic-button.mdx)
  learn.mdx   ← the Learn article

Why not a flat sibling (magic-button.mdx + magic-button/learn.mdx): fumadocs then treats the docs page as a child of the folder, so pruning learn still leaves a child and the sidebar renders an expandable "Magic button" group. With index.mdx, folder.index is set, pruning learn empties children, and the prune plugin collapses the folder back to a plain leaf. Always use the folder+index layout.

The catch-all page ([[...slug]]/page.tsx) needs no change per component. It:

• derives base = slug.slice(0,3) for slug[0]==="components" && length>=3;
• isLearnPage = length 4 and last segment learn;
• shows the Learn tab only if source.getPage([...base,"learn"]) exists;
• on the learn page, the breadcrumb's last crumb uses the component title (from source.getPage(base)), not the article's frontmatter title;
• component badges (perf/dep) render on the docs page only (length===3).

Sidebar hiding — hideLearnPagesPlugin

source.ts runs a transformPageTree.root plugin that recursively drops any page node whose url ends in /learn, and collapses a folder emptied by that removal to its index leaf. Routing is unaffected (source.getPage still resolves the learn page). Do not list the learn page in meta.json — the explicit pages allowlist plus this plugin keep it out of the sidebar. This plugin is generic; new components need nothing here.

Keeping the component link selected on the learn tab

Because the learn route has no sidebar node, fumadocs marks the component's sidebar link data-active="false" there. SidebarActiveLink (client) flips it back to "true" (with a MutationObserver to survive re-renders) only while pathname is still that component's /learn. On leave it clears the forced flag (immediately if another sidebar item is already active) so client navigation never leaves two data-active="true" pills. page.tsx renders it when isLearnPage. Generic — no per-component work.

Adding a Learn article to a new component

1. Convert the component page to a folder

git mv apps/docs/content/docs/components/{cat}/{name}.mdx \
       apps/docs/content/docs/components/{cat}/{name}/index.mdx

Route and content are unchanged. meta.json still references components/{cat}/{name} and resolves to the folder index — leave it as-is.

2. Read the real component source

The article must be grounded in the actual implementation, not invented. Read packages/components/src/ui/{name}.tsx (core) or packages/lab/src/{name}/{name}.tsx (Lab) and note the true mechanisms: transforms, transition timings/beziers, keyframes, observers, a11y (keyboard/focus-visible/ motion-reduce). Every claim and code excerpt in the article comes from here.

3. Build component-specific scenes

Each interactive block wraps the shared ScrollScene. Its render-prop hands you { cycle, reduced }:

• cycle — 0 before scroll-in, 1 on scroll-in, +1 per replay. Use it as a React key on the animated subtree so CSS keyframes restart on replay.
• reduced — prefers-reduced-motion; render the resolved (final) state with no animation.

Reliable replay = keyframes + key={cycle} remount. Do NOT drive scenes with a transition toggled by a boolean — that replay is unreliable. Use CSS @keyframes (in an inline <style>) applied to elements that remount when cycle changes.

Skeleton:

"use client";

import { ScrollScene } from "./scroll-scene";

const CSS = `
@keyframes myscene-in {
  from { opacity: 0; transform: translateY(8px); }
  to   { opacity: 1; transform: translateY(0); }
}
.myscene-el { animation: myscene-in 700ms cubic-bezier(0.3,0.7,0.4,1.2) both; }
.myscene-static .myscene-el { animation: none; opacity: 1; transform: none; }
`;

export function MyScene() {
  return (
    <ScrollScene label="Section" note="what this shows">
      {({ cycle, reduced }) => (
        <div
          key={cycle}
          className={`flex flex-col items-center gap-8 ${reduced ? "myscene-static" : ""}`}
        >
          {/* biome-ignore lint/security/noDangerouslySetInnerHtml: static keyframes, no user input */}
          <style dangerouslySetInnerHTML={{ __html: CSS }} />
          <div className="myscene-el ...">…</div>
        </div>
      )}
    </ScrollScene>
  );
}

Scene design rules:

• Match the final component. Anatomy / structure scenes must use the same geometry the reader will see in the Result (open state, direction, piece count). If the component is an open FAB with satellites, draw that silhouette — do not invent a generic plate stack that doesn't map to the live UI.

• Don't clone Magic Button visuals. Reference scenes teach techniques (keyed keyframes, legends, looping cycles) — not a layout to copy. A new component gets scenes invented from its source, not a reskin of layer-reveal / push-physics / rainbow-sweep.

• Prose count = diagram count. If the article says "two layers," the scene and legend show two items. Don't add a third plate "for the trigger" when the mechanism under discussion is blob vs control.

• Compositor-only motion: animate transform / opacity / filter only. No top/width/box-shadow/clip-path. (The CI motion-lint gate only scans packages/components, so docs scenes aren't enforced — hold the rule anyway; it's the whole point of the article.)

• Grayscale by default, and theme-safe. Illustrative plates/shapes use the theme tokens bg-[var(--card)], bg-[var(--muted)], bg-[var(--foreground)], bg-[var(--background)]. Reserve real color for a scene whose subject is color (e.g. a gradient), and for the live component in the result panel.

• Black/white pattern — every scene MUST work in BOTH light and dark theme. This is the #1 source of bugs: a shape that's fine in dark mode goes invisible in light (or vice-versa). Rules:

  • Never use a fixed-luminance color on a theme-colored surface: bg-black/*, bg-white/*, border-white/*, border-black/*, text-white, text-black, hex like #000/#fff. Each only contrasts in ONE theme. (e.g. a black button bg-[var(--foreground)] on light theme is black; a bg-black/25 fill over it is black-on-black → invisible.)
  • Contrast a surface with the OPPOSITE token. A surface painted bg-[var(--foreground)] inverts per theme (black on light, white on dark); an overlay/fill/icon on top of it must use --background (bg-[var(--background)]/30, text-[var(--background)]) so it inverts the same way and always contrasts. Same in reverse for a --card/--background surface: tint with --foreground.
  • Borders on same-colored fills (white plate on white canvas): a neutral border-fd-border is often too faint. Use border-[var(--foreground)]/20 — a foreground-tinted border reads in both themes.
  • Verify both themes before finishing. Toggle the docs theme and look at every scene; nothing may disappear, and the first/lowest layer must stay visible.

• No copy on the diagram shapes. Never put button text ("Hold to delete", "Slide to confirm", "Get started") on the animated pieces — it reads as instructional UI and distracts from the motion. Where a shape needs to stand in for a label/content, use a neutral gray token bar (h-2 w-12 rounded-full bg-[var(--foreground)]/30, light on dark surfaces). Leave faces blank when the shape alone carries the point. Explanation lives in the legend, the mono captions, and the prose — not on the shape. Real component labels are fine (and expected) only in the Result panel, since that's the live product.

• Legend swatches MUST match the diagram (color + shape). This is the #1 legend bug. Every bottom-legend entry names a concrete piece the reader can see in the scene — not an abstract CSS concept with no visual counterpart.

  Rule	Pass	Fail
  Color	Swatch fill/border/opacity appears on that diagram piece	Opacity-only ramps (/30 vs /60 vs solid) that never appear as distinct pieces; primary / white / black that aren't on the diagram
  Shape	Swatch silhouette matches the piece	Same h-1.5 w-8 rounded-full pill for a card, a pointer, a dashed frame, and a hairline
  Meaning	Name = visible piece (Viewport, Tile, Active plate, Pointer)	Temporal labels (Pan / Settle / Flick) or CSS props (Perspective / Tilt) with no matching cue

  Shape vocabulary (pick the one that matches the piece):

  • Circle / dot — pointer, avatar, orb, status, thumb
  • Plate (rounded-md / rounded-xl / card border) — cards, panels, tiles
  • Pill / bar — only when the diagram itself uses a pill/bar (token label, progress fill, dock bus)
  • Dashed rect / ring — clip viewport, dashed guide, idle/ghost outline
  • Hairline — separator, connector, threshold, SVG stroke
  • Diamond / isometric — caret, or a tile that reads diamond because of rotateX/rotateZ (draw the swatch with the same transform + fill)

  Prefer a local LegendSwatch({ kind }) helper (or full shape classes on swatch) over always wrapping item.swatch in h-1.5 w-8 rounded-full. If two legend items would get identical swatches, either differentiate shapes or merge the items.

  If a concept isn't visible, make it visible first — then swatch it. Example: a perspective / overflow clip that has no border → add a dashed viewport outline on the diagram, then use a matching dashed-frame swatch. Do not invent a circle or dotted pill that doesn't exist in the scene (classic 3D Marquee failure).

  Temporal / motion phases (drag → settle → fling) need a visible cue for each phase (pointer dot, active plate, ghost outline at overshoot) — or rename the legend to the pieces that are actually drawn.

• Label with a grounded legend, not floating tags. Put a bottom legend row (swatch

  • name + one-liner per element). Floating absolutely-positioned tags read as broken — avoid them. Align legend column count with the number of pieces.

• 3D exploded views (only when they help): center a [transform-style:preserve-3d] stage in a fixed-size box ([perspective:1000px]), separate plates along translateZ. Works for stacked rectangular layers (Magic Button). Avoid for concentric circles — they occlude and look broken; prefer a front-facing split (layer A | layer B | together) instead. Don't put readable text on rotated plates (it distorts) — name them in the legend.

• Looping demos (e.g. a push cycle) are good — use animation: … infinite, gated behind cycle > 0 via the keyed remount so it only runs after scroll-in.

Reference scenes (technique patterns, not templates to clone):

• layer-reveal.tsx — isometric explode + legend (rectangular layers). Text-free plates.
• gooey-layers.tsx — same open silhouette, split by layer (blob | control | both). Uses a + glyph, no words.
• mask-twin-labels.tsx / slide-anatomy.tsx — canonical token-bar stand-ins for a label (h-2 w-12 rounded-full bg-[var(--foreground)]/30, light on dark).
• orbit-carousel-orbit.tsx — motion legend with shape-matched pieces (pointer · active plate · flick ghost), not opacity pills.
• three-d-marquee-anatomy.tsx — viewport dashed frame + isometric tile swatch matching the clipped diamond grid.
• rainbow-sweep.tsx — the one colored scene (gradient), reuses animate-magic-rainbow.
• push-physics.tsx — looping rest→hover→press cycle. NOTE: its face still reads "Push me" — that predates the no-copy rule; do not copy that, blank the face or use a token bar instead.