@coinbase/cds-mcp-server 8.27.0 → 8.27.1

package/CHANGELOG.md

@@ -8,6 +8,10 @@ All notable changes to this project will be documented in this file.
 
 <!-- template-start -->
 
+## 8.27.1 ((12/4/2025, 06:51 AM PST))
+
+This is an artificial version bump with no new change.
+
 ## 8.27.0 ((12/3/2025, 09:30 AM PST))
 
 This is an artificial version bump with no new change.

package/mcp-docs/mobile/components/Tour.txt

@@ -10,25 +10,32 @@ import { Tour, TourStep } from '@coinbase/cds-mobile/tour'
 
 ## Examples
 
+The Tour component guides users through your app with step-by-step coachmarks.
+You define tour steps with unique IDs and wrap target elements with `TourStep` components.
+
 ### Basic usage
 
-```tsx live
-function Example() {
+```jsx
+function BasicTourExample() {
   const [activeTourStep, setActiveTourStep] = useState(null);
 
   const StepOne = () => {
     const [checked, setChecked] = useState(false);
-
     const { goNextTourStep, stopTour } = useTourContext();
 
     return (
       <Coachmark
-        action={<Button variant="secondary" onPress={goNextTourStep} compact label="Next" />}
+        action={
+          <Button compact onPress={goNextTourStep} variant="secondary">
+            Next
+          </Button>
+        }
         checkbox={
           <Checkbox checked={checked} onChange={setChecked}>
-            Don&apos;t show again
+            Don't show again
           </Checkbox>
         }
+        closeButtonAccessibilityLabel="Close"
         content="Add up to 3 lines of body copy. Deliver your message with clarity and impact"
         onClose={stopTour}
         title="My first step"
@@ -40,16 +47,21 @@ function Example() {
     const { goNextTourStep, stopTour } = useTourContext();
     return (
       <Coachmark
-        action={<Button variant="secondary" onPress={goNextTourStep} compact label="Next" />}
+        action={
+          <Button compact onPress={goNextTourStep} variant="secondary">
+            Next
+          </Button>
+        }
+        closeButtonAccessibilityLabel="Close"
         content={
           <VStack gap={2}>
-            <TextCaption as="p" color="fgMuted">
+            <Text color="fgMuted" font="caption">
               50%
-            </TextCaption>
+            </Text>
             <ProgressBar progress={0.5} />
-            <TextBody as="p">
+            <Text font="body">
               Add up to 3 lines of body copy. Deliver your message with clarity and impact
-            </TextBody>
+            </Text>
           </VStack>
         }
         media={<RemoteImage height={150} source={ethBackground} width="100%" />}
@@ -65,9 +77,15 @@ function Example() {
       <Coachmark
         action={
           <HStack gap={1}>
-            <Button variant="secondary" onPress={goPreviousTourStep} compact label="Back" />
-            <Button variant="secondary" onPress={goNextTourStep} compact label="Next" />
-            <Button variant="secondary" onPress={stopTour} compact label="Done" />
+            <Button compact onPress={goPreviousTourStep} variant="secondary">
+              Back
+            </Button>
+            <Button compact onPress={goNextTourStep} variant="secondary">
+              Next
+            </Button>
+            <Button compact onPress={stopTour} variant="secondary">
+              Done
+            </Button>
           </HStack>
         }
         content="Add up to 3 lines of body copy. Deliver your message with clarity and impact"
@@ -77,67 +95,388 @@ function Example() {
     );
   };
 
+  const tourSteps = [
+    { id: 'step1', Component: StepOne },
+    { id: 'step2', Component: StepTwo },
+    { id: 'step3', Component: StepThree },
+  ];
+
+  const TourContent = () => {
+    const { startTour } = useTourContext();
+
+    return (
+      <VStack flexGrow={1} gap={2} justifyContent="space-between">
+        <Button onPress={() => startTour()} compact>
+          Start tour
+        </Button>
+        <TourStep id="step1">
+          <Box background="bgSecondary" padding={4}>
+            <Text>This is step 1</Text>
+          </Box>
+        </TourStep>
+        <Box height={300} />
+        <TourStep id="step2">
+          <Box background="bgSecondary" padding={4} width={150}>
+            <Text>This is step 2</Text>
+          </Box>
+        </TourStep>
+        <Box height={300} />
+        <TourStep id="step3">
+          <VStack background="bgSecondary" padding={4} width={150}>
+            <Text>This is step 3</Text>
+          </VStack>
+        </TourStep>
+      </VStack>
+    );
+  };
+
+  return (
+    <Tour activeTourStep={activeTourStep} onChange={setActiveTourStep} steps={tourSteps}>
+      <TourContent />
+    </Tour>
+  );
+}
+```
+
+Coachmarks can contain rich content including images, progress indicators, and custom layouts.
+
+```jsx
+function RichContentExample() {
+  const RichStep = () => {
+    const { goNextTourStep, stopTour } = useTourContext();
+
+    return (
+      <Coachmark
+        action={
+          <Button compact onPress={goNextTourStep} variant="secondary">
+            Continue
+          </Button>
+        }
+        closeButtonAccessibilityLabel="Close"
+        content={
+          <VStack gap={2}>
+            <Text color="fgMuted" font="caption">
+              Step 2 of 4
+            </Text>
+            <ProgressBar progress={0.5} />
+            <Text font="body">
+              This step showcases how you can include rich content like progress bars and images.
+            </Text>
+          </VStack>
+        }
+        media={
+          <Image
+            accessibilityIgnoresInvertColors
+            source={{ uri: 'https://example.com/feature-image.png' }}
+            style={{ width: '100%', height: 150 }}
+          />
+        }
+        onClose={stopTour}
+        title="Rich Content Example"
+      />
+    );
+  };
+}
+```
+
+You can use TypeScript string literal types to ensure type safety for your step IDs.
+
+```tsx
+type StepId = 'intro' | 'feature-highlight' | 'call-to-action';
+
+function TypeSafeTourExample() {
+  const [activeTourStep, setActiveTourStep] = useState<TourStepValue<StepId> | null>(null);
+
+  const tourSteps: TourStepValue<StepId>[] = [
+    { id: 'intro', Component: IntroStep },
+    { id: 'feature-highlight', Component: FeatureStep },
+    { id: 'call-to-action', Component: CTAStep },
+  ];
+
+  return (
+    <Tour activeTourStep={activeTourStep} onChange={setActiveTourStep} steps={tourSteps}>
+      <TourStep id="intro">
+        <IntroContent />
+      </TourStep>
+      <TourStep id="feature-highlight">
+        <FeatureContent />
+      </TourStep>
+      {/* TypeScript error if id doesn't match StepId type */}
+      <TourStep id="call-to-action">
+        <CTAContent />
+      </TourStep>
+    </Tour>
+  );
+}
+```
+
+### Scrolling
+
+When tour steps are off-screen, you can use the `onBeforeActive` callback to scroll them into view.
+This callback runs before the step becomes active and can be async.
+
+```jsx
+function ScrollingTourExample() {
+  const [activeTourStep, setActiveTourStep] = useState(null);
+  const scrollViewRef = useRef(null);
+  const step2Ref = useRef(null);
+  const step3Ref = useRef(null);
+
+  // Helper function to scroll an element into view
+  const scrollIntoView = async (scrollViewRef, elementRef) => {
+    const scrollView = scrollViewRef.current;
+    if (!scrollView) return;
+    elementRef.current?.measureLayout(scrollView, (x, y) => {
+      scrollView.scrollTo({ x, y, animated: true });
+    });
+  };
+
   const tourSteps = [
     {
       id: 'step1',
-      onBeforeActive: () => console.log('step1 before'),
       Component: StepOne,
     },
     {
       id: 'step2',
-      onBeforeActive: () => console.log('step2 before'),
+      onBeforeActive: async () => {
+        // Scroll step 2 into view before showing the coachmark
+        await scrollIntoView(scrollViewRef, step2Ref);
+      },
       Component: StepTwo,
     },
     {
       id: 'step3',
-      onBeforeActive: () => console.log('step3 before'),
+      onBeforeActive: async () => {
+        await scrollIntoView(scrollViewRef, step3Ref);
+      },
       Component: StepThree,
     },
   ];
 
-  const TourExample = ({ spacerWidthIncrement = 0, spacerHeightIncrement = 500 }) => {
-    const { startTour } = useTourContext();
-
-    const handlePress = useCallback(() => startTour(), [startTour]);
-
-    return (
-      <VStack flexGrow={1} gap={2} justifyContent="space-between">
-        <Button onPress={handlePress} compact label="Start tour" />
+  return (
+    <Tour activeTourStep={activeTourStep} onChange={setActiveTourStep} steps={tourSteps}>
+      <ScrollView ref={scrollViewRef} style={{ flex: 1 }}>
         <TourStep id="step1">
-          <Box backgroundColor="secondary" padding={4}>
-            <Text>This is step 1</Text>
+          <Box background="bgSecondary" padding={4}>
+            <Text>Step 1 - visible on load</Text>
           </Box>
         </TourStep>
-        <Box height={spacerHeightIncrement} />
-        <HStack justifyContent="flex-end">
-          <Box flexShrink={0} width={spacerWidthIncrement} />
-          <TourStep id="step2">
-            <Box backgroundColor="secondary" padding={4} width={150}>
-              <Text>This is step 2</Text>
-            </Box>
-          </TourStep>
-        </HStack>
-        <Box height={spacerHeightIncrement} />
-        <HStack>
-          <Box flexShrink={0} width={spacerWidthIncrement * 2} />
-          <TourStep id="step3">
-            <VStack backgroundColor="secondary" padding={4} width={150}>
-              <Text>This is step 3</Text>
-            </VStack>
-          </TourStep>
-        </HStack>
-      </VStack>
-    );
-  };
+        <Box height={1000} />
+        <TourStep id="step2">
+          <Box ref={step2Ref} background="bgSecondary" padding={4}>
+            <Text>Step 2 - requires scroll</Text>
+          </Box>
+        </TourStep>
+        <Box height={1000} />
+        <TourStep id="step3">
+          <Box ref={step3Ref} background="bgSecondary" padding={4}>
+            <Text>Step 3 - requires more scroll</Text>
+          </Box>
+        </TourStep>
+      </ScrollView>
+    </Tour>
+  );
+}
+```
+
+### Customization
+
+#### Overlay
+
+You can hide the dimmed overlay behind the coachmark using the `hideOverlay` prop.
+This can be set globally on the `Tour` component or per-step.
+
+```jsx
+function HideOverlayExample() {
+  const [activeTourStep, setActiveTourStep] = useState(null);
+
+  const tourSteps = [
+    {
+      id: 'step1',
+      Component: StepOne,
+      // Hide overlay for just this step
+      hideOverlay: true,
+    },
+    {
+      id: 'step2',
+      Component: StepTwo,
+    },
+  ];
 
   return (
-    <Tour activeTourStep={activeTourStep} onChange={setActiveTourStep} steps={tourSteps}>
-      <TourExample />
+    // Or hide overlay for all steps
+    <Tour
+      hideOverlay
+      activeTourStep={activeTourStep}
+      onChange={setActiveTourStep}
+      steps={tourSteps}
+    >
+      ...
     </Tour>
   );
 }
 ```
 
+#### Mask
+
+Customize the mask (cutout) around the highlighted element with padding and border radius.
+
+```jsx
+function MaskCustomizationExample() {
+  const [activeTourStep, setActiveTourStep] = useState(null);
+
+  const tourSteps = [
+    {
+      id: 'step1',
+      Component: StepOne,
+      // Per-step mask customization
+      tourMaskPadding: 16,
+      tourMaskBorderRadius: 12,
+    },
+    { id: 'step2', Component: StepTwo },
+  ];
+
+  return (
+    <Tour
+      activeTourStep={activeTourStep}
+      onChange={setActiveTourStep}
+      steps={tourSteps}
+      tourMaskPadding={8}
+      tourMaskBorderRadius={8}
+    >
+      ...
+    </Tour>
+  );
+}
+```
+
+#### Positioning
+
+The Tour component uses `@floating-ui` to position coachmarks relative to their target elements.
+You can customize positioning with the `tourStepOffset`, `tourStepShift`, and `tourStepAutoPlacement` props.
+
+```jsx
+function PositioningExample() {
+  const [activeTourStep, setActiveTourStep] = useState(null);
+
+  const tourSteps = [
+    { id: 'step1', Component: StepOne },
+    { id: 'step2', Component: StepTwo },
+  ];
+
+  return (
+    <Tour
+      activeTourStep={activeTourStep}
+      onChange={setActiveTourStep}
+      steps={tourSteps}
+      tourStepOffset={32}
+      tourStepShift={{ padding: 16 }}
+    >
+      ...
+    </Tour>
+  );
+}
+```
+
+#### Arrow
+
+You can customize the arrow that points to the target element by providing a custom `TourStepArrowComponent`.
+
+```jsx
+function CustomArrowExample() {
+  const [activeTourStep, setActiveTourStep] = useState(null);
+
+  // Custom arrow component (must forward ref)
+  const CustomArrow = memo(
+    forwardRef((props, ref) => {
+      return <DefaultTourStepArrow {...props} ref={ref} style={{ color: 'yellow' }} />;
+    }),
+  );
+
+  const tourSteps = [
+    {
+      id: 'step1',
+      Component: StepOne,
+      // Per-step custom arrow
+      ArrowComponent: CustomArrow,
+      arrowStyle: { color: 'red' },
+    },
+    { id: 'step2', Component: StepTwo },
+  ];
+
+  return (
+    <Tour
+      activeTourStep={activeTourStep}
+      onChange={setActiveTourStep}
+      steps={tourSteps}
+      TourStepArrowComponent={CustomArrow}
+    >
+      ...
+    </Tour>
+  );
+}
+```
+
+### Accessibility
+
+Always provide accessibility labels for close buttons using the `closeButtonAccessibilityLabel` prop and ensure coachmarks are navigable.
+
+```jsx
+function AccessibleTourExample() {
+  const AccessibleStep = () => {
+    const { goNextTourStep, stopTour } = useTourContext();
+
+    return (
+      <Coachmark
+        action={
+          <Button
+            accessibilityHint="Advances to the next step in the tour"
+            compact
+            onPress={goNextTourStep}
+            variant="secondary"
+          >
+            Next
+          </Button>
+        }
+        closeButtonAccessibilityLabel="Close tour and return to main content"
+        content="This coachmark has proper accessibility labels for screen readers."
+        onClose={stopTour}
+        title="Accessible Step"
+      />
+    );
+  };
+}
+```
+
+### Callbacks
+
+Use the `onBeforeActive` callback to perform actions before a step becomes active,
+such as scrolling, fetching data, or preparing the UI.
+
+```jsx
+function CallbacksExample() {
+  const tourSteps = [
+    {
+      id: 'step1',
+      onBeforeActive: () => {
+        console.log('Step 1 is about to become active');
+        // Perform any setup needed
+      },
+      Component: StepOne,
+    },
+    {
+      id: 'step2',
+      onBeforeActive: async () => {
+        // Async operations are supported
+        await someAsyncSetup();
+        console.log('Step 2 setup complete');
+      },
+      Component: StepTwo,
+    },
+  ];
+}
+```
+
 ## Props
 
 | Prop | Type | Required | Default | Description |

package/mcp-docs/web/components/Tour.txt

@@ -10,6 +10,9 @@ import { Tour, TourStep } from '@coinbase/cds-web/tour'
 
 ## Examples
 
+The Tour component guides users through your app with step-by-step coachmarks.
+You define tour steps with unique IDs and wrap target elements with `TourStep` components.
+
 ### Basic usage
 
 ```jsx live
@@ -56,13 +59,13 @@ function Example() {
         }
         content={
           <VStack gap={2}>
-            <TextCaption as="p" color="fgMuted">
+            <Text as="p" color="fgMuted" font="caption">
               50%
-            </TextCaption>
+            </Text>
             <ProgressBar progress={0.5} />
-            <TextBody as="p">
+            <Text as="p" font="body">
               Add up to 3 lines of body copy. Deliver your message with clarity and impact
-            </TextBody>
+            </Text>
           </VStack>
         }
         media={<RemoteImage height={150} source={ethBackground} width="100%" />}
@@ -73,7 +76,7 @@ function Example() {
   };
 
   const StepThree = () => {
-    const { stopTour, goNextTourStep, goPreviousTourStep } = useTourContext();
+    const { stopTour, goPreviousTourStep } = useTourContext();
     return (
       <Coachmark
         action={
@@ -122,16 +125,20 @@ function Example() {
           Start tour
         </Button>
         <TourStep id="step1">
-          <Box background="bgAlternate" padding={4}>
-            <TextBody as="p">This is step 1</TextBody>
+          <Box background="bgSecondary" padding={4}>
+            <Text as="p" font="body">
+              This is step 1
+            </Text>
           </Box>
         </TourStep>
         <Box height={spacerHeightIncrement} />
         <HStack justifyContent="flex-end">
           <Box flexShrink={0} width={spacerWidthIncrement} />
           <TourStep id="step2">
-            <Box background="bgAlternate" padding={4} width={150}>
-              <TextBody as="p">This is step 2</TextBody>
+            <Box background="bgSecondary" padding={4} width={150}>
+              <Text as="p" font="body">
+                This is step 2
+              </Text>
             </Box>
           </TourStep>
         </HStack>
@@ -139,8 +146,10 @@ function Example() {
         <HStack>
           <Box flexShrink={0} width={spacerWidthIncrement * 2} />
           <TourStep id="step3">
-            <VStack background="bgAlternate" padding={4} width={150}>
-              <TextBody as="p">This is step 3</TextBody>
+            <VStack background="bgSecondary" padding={4} width={150}>
+              <Text as="p" font="body">
+                This is step 3
+              </Text>
             </VStack>
           </TourStep>
         </HStack>
@@ -156,6 +165,397 @@ function Example() {
 }
 ```
 
+You can use TypeScript string literal types to ensure type safety for your step IDs.
+
+```tsx
+type StepId = 'intro' | 'feature-highlight' | 'call-to-action';
+
+function TypeSafeTourExample() {
+  const [activeTourStep, setActiveTourStep] = useState<TourStepValue<StepId> | null>(null);
+
+  const tourSteps: TourStepValue<StepId>[] = [
+    { id: 'intro', Component: IntroStep },
+    { id: 'feature-highlight', Component: FeatureStep },
+    { id: 'call-to-action', Component: CTAStep },
+  ];
+
+  return (
+    <Tour activeTourStep={activeTourStep} onChange={setActiveTourStep} steps={tourSteps}>
+      <TourStep id="intro">
+        <IntroContent />
+      </TourStep>
+      <TourStep id="feature-highlight">
+        <FeatureContent />
+      </TourStep>
+      {/* TypeScript error if id doesn't match StepId type */}
+      <TourStep id="call-to-action">
+        <CTAContent />
+      </TourStep>
+    </Tour>
+  );
+}
+```
+
+### Scrolling
+
+The Tour component automatically scrolls to bring off-screen targets into view.
+You can customize this behavior with the `scrollOptions` prop or disable it entirely with `disableAutoScroll`.
+
+```jsx
+function ScrollingExample() {
+  const [activeTourStep, setActiveTourStep] = useState(null);
+
+  const tourSteps = [
+    { id: 'step1', Component: StepOne },
+    {
+      id: 'step2',
+      // Disable auto-scroll for just this step
+      disableAutoScroll: true,
+      Component: StepTwo,
+    },
+    {
+      id: 'step3',
+      // Custom scroll options for this step
+      scrollOptions: {
+        behavior: 'smooth',
+        marginX: 50,
+        marginY: 150,
+      },
+      Component: StepThree,
+    },
+  ];
+
+  return (
+    <Tour
+      activeTourStep={activeTourStep}
+      onChange={setActiveTourStep}
+      steps={tourSteps}
+      // Global scroll options
+      scrollOptions={{
+        behavior: 'smooth',
+        marginX: 100,
+        marginY: 100,
+      }}
+    >
+      ...
+    </Tour>
+  );
+}
+```
+
+### Customization
+
+#### Overlay
+
+You can hide the dimmed overlay behind the coachmark using the `hideOverlay` prop.
+This can be set globally on the `Tour` component or per-step.
+
+```jsx live
+function HideOverlayExample() {
+  const [activeTourStep, setActiveTourStep] = useState(null);
+  const [hideOverlay, setHideOverlay] = useState(false);
+
+  const StepOne = () => {
+    const { goNextTourStep, stopTour } = useTourContext();
+    return (
+      <Coachmark
+        action={
+          <Button compact onClick={goNextTourStep}>
+            Next
+          </Button>
+        }
+        content="This step respects the global hideOverlay setting."
+        onClose={stopTour}
+        title="Step One"
+      />
+    );
+  };
+
+  const StepTwo = () => {
+    const { stopTour, goPreviousTourStep } = useTourContext();
+    return (
+      <Coachmark
+        action={
+          <HStack gap={1}>
+            <Button compact onClick={goPreviousTourStep} variant="secondary">
+              Back
+            </Button>
+            <Button compact onClick={stopTour}>
+              Done
+            </Button>
+          </HStack>
+        }
+        content="This step also respects the global hideOverlay setting."
+        title="Step Two"
+      />
+    );
+  };
+
+  const tourSteps = [
+    { id: 'step1', Component: StepOne },
+    { id: 'step2', Component: StepTwo },
+  ];
+
+  const TourContent = () => {
+    const { startTour } = useTourContext();
+    return (
+      <VStack gap={2}>
+        <HStack gap={2} alignItems="center">
+          <Button compact onClick={() => startTour()}>
+            Start tour
+          </Button>
+          <Checkbox checked={hideOverlay} onChange={() => setHideOverlay((prev) => !prev)}>
+            Hide overlay
+          </Checkbox>
+        </HStack>
+        <HStack gap={4}>
+          <TourStep id="step1">
+            <Box background="bgSecondary" padding={4}>
+              <Text as="p" font="body">
+                Step 1
+              </Text>
+            </Box>
+          </TourStep>
+          <TourStep id="step2">
+            <Box background="bgSecondary" padding={4}>
+              <Text as="p" font="body">
+                Step 2
+              </Text>
+            </Box>
+          </TourStep>
+        </HStack>
+      </VStack>
+    );
+  };
+
+  return (
+    <Tour
+      hideOverlay={hideOverlay}
+      activeTourStep={activeTourStep}
+      onChange={setActiveTourStep}
+      steps={tourSteps}
+    >
+      <TourContent />
+    </Tour>
+  );
+}
+```
+
+#### Mask
+
+Customize the mask (cutout) around the highlighted element with the `tourMaskPadding` and `tourMaskBorderRadius` props.
+
+```jsx
+<Tour
+  activeTourStep={activeTourStep}
+  onChange={setActiveTourStep}
+  steps={tourSteps}
+  // Padding around the highlighted element (default: 8)
+  tourMaskPadding={16}
+  // Border radius of the cutout (default: 8)
+  tourMaskBorderRadius={12}
+>
+  ...
+</Tour>
+```
+
+You can provide a completely custom mask component using the `TourMaskComponent` prop.
+
+```jsx
+function CustomMaskExample() {
+  const [activeTourStep, setActiveTourStep] = useState(null);
+
+  const CustomMask = ({ activeTourStepTargetRect, padding = 8, borderRadius = 8 }) => {
+    // Custom mask implementation
+    // activeTourStepTargetRect contains { x, y, width, height } of the target element
+    return (
+      <svg
+        style={{
+          position: 'fixed',
+          top: 0,
+          left: 0,
+          width: '100vw',
+          height: '100vh',
+          pointerEvents: 'none',
+        }}
+      >
+        <defs>
+          <mask id="tour-mask">
+            <rect fill="white" height="100%" width="100%" />
+            <rect
+              fill="black"
+              height={activeTourStepTargetRect.height + padding * 2}
+              rx={borderRadius}
+              ry={borderRadius}
+              width={activeTourStepTargetRect.width + padding * 2}
+              x={activeTourStepTargetRect.x - padding}
+              y={activeTourStepTargetRect.y - padding}
+            />
+          </mask>
+        </defs>
+        <rect fill="rgba(0,0,0,0.5)" height="100%" mask="url(#tour-mask)" width="100%" />
+      </svg>
+    );
+  };
+
+  return (
+    <Tour
+      activeTourStep={activeTourStep}
+      onChange={setActiveTourStep}
+      steps={tourSteps}
+      TourMaskComponent={CustomMask}
+    >
+      ...
+    </Tour>
+  );
+}
+```
+
+#### Positioning
+
+The Tour component uses `@floating-ui` to position coachmarks relative to their target elements.
+You can customize positioning with the `tourStepOffset`, `tourStepShift`, and `tourStepAutoPlacement` props.
+
+```jsx
+function PositioningExample() {
+  const [activeTourStep, setActiveTourStep] = useState(null);
+
+  const tourSteps = [
+    { id: 'step1', Component: StepOne },
+    { id: 'step2', Component: StepTwo },
+  ];
+
+  return (
+    <Tour
+      activeTourStep={activeTourStep}
+      onChange={setActiveTourStep}
+      steps={tourSteps}
+      // Distance between coachmark and target (default: 24)
+      tourStepOffset={32}
+      // Padding when shifting to stay in viewport (default: { padding: 32 })
+      tourStepShift={{ padding: 16 }}
+      // Auto-placement options from @floating-ui
+      tourStepAutoPlacement={{ allowedPlacements: ['top', 'bottom'] }}
+    >
+      ...
+    </Tour>
+  );
+}
+```
+
+#### Arrow
+
+You can customize the arrow that points to the target element by providing a custom `TourStepArrowComponent`.
+
+```jsx
+function CustomArrowExample() {
+  const [activeTourStep, setActiveTourStep] = useState(null);
+
+  // Custom arrow component - MUST forward ref
+  const CustomArrow = memo(
+    forwardRef((props, ref) => {
+      return <DefaultTourStepArrow {...props} ref={ref} style={{ color: 'var(--color-blue60)' }} />;
+    }),
+  );
+
+  const tourSteps = [
+    {
+      id: 'step1',
+      Component: StepOne,
+      // Per-step custom arrow
+      ArrowComponent: CustomArrow,
+      // Or just customize the style
+      arrowStyle: { color: 'var(--color-purple60)' },
+    },
+    { id: 'step2', Component: StepTwo },
+  ];
+
+  return (
+    <Tour
+      activeTourStep={activeTourStep}
+      onChange={setActiveTourStep}
+      steps={tourSteps}
+      TourStepArrowComponent={CustomArrow}
+    >
+      ...
+    </Tour>
+  );
+}
+```
+
+#### Portal
+
+By default, the Tour uses React portals to render outside the DOM hierarchy.
+You can disable this behavior if needed.
+
+```jsx
+<Tour
+  ...
+  disablePortal
+>
+  ...
+</Tour>
+```
+
+### Accessibility
+
+Always provide accessibility labels for close buttons using the `closeButtonAccessibilityLabel` prop and ensure coachmarks are navigable.
+
+```jsx
+function AccessibleTourExample() {
+  const AccessibleStep = () => {
+    const { goNextTourStep, stopTour } = useTourContext();
+
+    return (
+      <Coachmark
+        action={
+          <Button
+            aria-label="Advances to the next step in the tour"
+            compact
+            onClick={goNextTourStep}
+          >
+            Next
+          </Button>
+        }
+        closeButtonAccessibilityLabel="Close tour and return to main content"
+        content="This coachmark has proper accessibility labels for screen readers."
+        onClose={stopTour}
+        title="Accessible Step"
+      />
+    );
+  };
+}
+```
+
+### Callbacks
+
+Use the `onBeforeActive` callback to perform actions before a step becomes active,
+such as fetching data, preparing the UI, or custom scrolling logic.
+
+```jsx
+function CallbacksExample() {
+  const tourSteps = [
+    {
+      id: 'step1',
+      onBeforeActive: () => {
+        console.log('Step 1 is about to become active');
+        // Perform any setup needed
+      },
+      Component: StepOne,
+    },
+    {
+      id: 'step2',
+      onBeforeActive: async () => {
+        // Async operations are supported
+        await fetchStepData();
+        console.log('Step 2 data loaded');
+      },
+      Component: StepTwo,
+    },
+  ];
+}
+```
+
 ## Props
 
 | Prop | Type | Required | Default | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cds-mcp-server",
-  "version": "8.27.0",
+  "version": "8.27.1",
   "description": "Coinbase Design System - MCP Server",
   "repository": {
     "type": "git",