Docs/BLOCKS/Feature Walkthrough

A split-layout feature walkthrough for product onboarding and marketing pages. The left panel lists clickable steps with a sliding orange indicator; the right panel shows a sticky glass preview card with animated visual transitions. Ships with GwenUI CLI-themed demo data out of the box.

Installation#

$ pnpm dlx @gwenui/cli add feature-walkthrough

File Structure#

feature-walkthrough/
├── FeatureWalkthrough.tsx   # FeatureWalkthrough component & demo visuals
├── index.ts                 # Module entry point (re-exports)
└── block.json               # Block metadata configuration

Usage#

Drop in the default GwenUI CLI walkthrough:

import { FeatureWalkthrough } from "@/components/blocks/feature-walkthrough";
 
export default function Page() {
  return <FeatureWalkthrough />;
}

Auto-play#

Enable automatic step cycling. Playback pauses while the user hovers over the component.

import { FeatureWalkthrough } from "@/components/blocks/feature-walkthrough";
 
export default function Page() {
  return (
    <FeatureWalkthrough
      autoPlay
      autoPlayInterval={5000}
    />
  );
}

Custom Steps#

Pass your own steps with custom preview visuals. Each visual is a ReactNode rendered inside the glass preview panel.

import { FeatureWalkthrough } from "@/components/blocks/feature-walkthrough";
import type { WalkthroughStep } from "@/components/blocks/feature-walkthrough";
 
function DashboardPreview() {
  return (
    <div style={{ padding: "1rem", textAlign: "center", color: "oklch(0.7 0.02 265)" }}>
      Your dashboard preview here
    </div>
  );
}
 
const steps: WalkthroughStep[] = [
  {
    id: "connect",
    stepNumber: "01",
    title: "Connect",
    description: "Link your workspace in one click.",
    badge: "New",
    visual: <DashboardPreview />,
  },
  {
    id: "configure",
    stepNumber: "02",
    title: "Configure",
    description: "Set preferences and invite your team.",
    visual: <DashboardPreview />,
  },
  {
    id: "launch",
    stepNumber: "03",
    title: "Launch",
    description: "Go live with full analytics enabled.",
    visual: <DashboardPreview />,
  },
];
 
export default function Page() {
  return <FeatureWalkthrough steps={steps} />;
}

Default Demo Steps#

The built-in demo walks through the GwenUI CLI workflow:

StepTitlePreview
01InstallTerminal mockup — npx gwenui init
02Browse BlocksMini block card grid (3 cards)
03Add to ProjectTerminal mockup — gwenui add bento-grid
04CustomizeOKLCH CSS token snippet
05ShipDeploy success card with checkmark

FeatureWalkthrough Props#

PropTypeDefaultDescription
stepsWalkthroughStep[]GwenUI CLI demoArray of walkthrough steps.
autoPlaybooleanfalseAutomatically cycle through steps.
autoPlayIntervalnumber4000Interval between auto-play transitions (ms).
classNamestringundefinedExtra class on the root container.

WalkthroughStep Props#

PropTypeDefaultDescription
idstringrequiredUnique step identifier (used for active state & animations).
stepNumberstringrequiredDisplay label e.g. "01", "02" (Space Mono, orange).
titlestringrequiredStep heading (Plus Jakarta Sans Bold).
descriptionstringrequiredSupporting body copy below the title.
visualReactNoderequiredContent rendered in the right preview panel.
badgestringundefinedOptional pill above the step number e.g. "CLI", "New".

Layout & Interaction#

AreaBehavior
Left panelVertical step list; click or focus to activate
Active stepOrange left border, surface background, spring layoutId indicator
Inactive stepMuted title, transparent background
Right panelSticky glass card (desktop); static on mobile
Preview transitionAnimatePresence slide — opacity + 20px horizontal
Auto-playCycles on interval; pauses on mouseenter, resumes on mouseleave

Responsive#

BreakpointBehavior
Desktop (> 768px)40% steps / 60% preview grid; preview sticky at top: 2rem
Mobile (≤ 768px)Single column — preview stacks below steps

Accessibility#

  • Steps use role="tablist" / role="tab" / role="tabpanel"
  • aria-selected, aria-controls, and aria-labelledby wire tabs to panels
  • Steps are native <button> elements — keyboard focusable

Styling#

All layout and theme styles ship via an embedded <style> tag (no Tailwind grid utilities). Gwen Noir tokens:

  • Background: oklch(0.1895 0.0496 296)
  • Primary accent: oklch(0.7204 0.1507 48)
  • Preview card: oklch(0.13 0.005 265) with orange-tinted border

Dependencies#

PackagePurpose
framer-motionStep indicator layoutId, preview AnimatePresence transitions
lucide-reactIcons in default demo visuals
Next.js 16TypeScriptFramer MotionLucide
Made by JinXSuper with Gwen 🧡