Guidemark React

Guidemark is clarity infrastructure for React apps: a developer-first SDK for turning confusing product moments into guided clarity flows users can complete, developers can maintain, and answer engines can understand.

@guidemark/react is a commercial React SDK with 0 runtime dependencies, type-safe flow definitions, stable DOM anchors, and silent hosted license validation designed to fail open when the validator is slow or unavailable.

Try the live IdeaBrowser demo: https://share.guidemark.dev/ideabrowser/

This repository is the public developer hub linked from the @guidemark/react npm package. It contains the support surface developers expect on GitHub: a quick package overview, a runnable example, issue tracking, security guidance, and release notes.

The canonical docs live at https://guidemark.dev/docs. The package source is maintained privately, and the published npm package is the supported distribution.

Install

pnpm add @guidemark/react

You can try Guidemark for free on local development origins such as localhost, 127.0.0.1, and .local. A commercial license is required before using Guidemark on a hosted production origin.

Quick Start

Add a stable anchor to the product moment you want to clarify:

<button data-demo-id="invite-user-button">Invite user</button>

Create a guided clarity flow:

import type { GuidemarkFlowDefinition } from "@guidemark/react";

export const gettingStartedFlow: GuidemarkFlowDefinition = {
  id: "getting-started",
  version: 1,
  name: "Getting Started",
  steps: [
    {
      id: "welcome",
      title: "Welcome",
      body: "This flow clarifies the main workflow.",
      viewId: "dashboard",
      placement: "center",
    },
    {
      id: "invite-users",
      title: "Invite teammates",
      body: "Use this control to add your first teammates.",
      viewId: "dashboard",
      anchorId: "invite-user-button",
      placement: "bottom",
    },
  ],
};

Mount GuidemarkFlow around your app:

import { GuidemarkFlow } from "@guidemark/react";
import { gettingStartedFlow } from "./getting-started-flow";

export function AppShell() {
  return (
    <GuidemarkFlow
      currentView="dashboard"
      navigateToView={(viewId) => {
        console.log("navigate", viewId);
      }}
      flow={gettingStartedFlow}
      autoStart
      licenseKey={import.meta.env.VITE_PUBLIC_GUIDEMARK_LICENSE_KEY ?? ""}
      licenseProductName="Getting Started flow"
    >
      <App />
    </GuidemarkFlow>
  );
}

For a complete copy-paste project, see examples/basic-vite.

For the full setup guide and API reference, use https://guidemark.dev/docs.

Theme Integration

Guidemark follows the host app's theme by default. The overlay reads common real-color tokens such as --gm-surface-1, --gm-text-strong, --gm-text-body, --gm-accent, --color-popover, --color-popover-foreground, --color-primary, --color-secondary, and --color-border when they exist, so dark products should not get a forced white tour card.

For product-specific styling, define the Guidemark overlay variables in your app CSS:

:root {
  --guidemark-overlay-bg: hsl(var(--popover));
  --guidemark-overlay-fg: hsl(var(--popover-foreground));
  --guidemark-overlay-body: hsl(var(--muted-foreground));
  --guidemark-overlay-border: hsl(var(--border));
  --guidemark-overlay-primary-bg: hsl(var(--primary));
  --guidemark-overlay-primary-fg: hsl(var(--primary-foreground));
}

If no theme variables are present, the SDK falls back to a clean light default.

Why Guidemark

• 0 runtime dependencies in the published SDK.
• Type-safe authoring with plain TypeScript flow objects.
• Stable DOM anchors through data-demo-id, without coupling guidance to CSS selectors.
• Clarity-first positioning for teams cleaning up activation leaks caused by confusing product moments.
• Silent hosted licensing with a 200ms validator timeout and fail-open behavior for slow or unavailable validation.
• Localhost preview so teams can integrate and test before purchasing a production license.
• React 18 and React 19 support through a peer dependency.

Licensing

Guidemark license keys used in browser apps are site-bound public keys. They are expected to be visible in browser bundles, and Guidemark validates them against the licensed allowed origins.

Do not put private credentials in browser-exposed environment variables. Never place API keys, admin tokens, Stripe secrets, webhook secrets, or other confidential credentials in VITE_* variables.

Production use requires a commercial license. See:

• Purchase: https://guidemark.dev/#pricing
• Start page: https://guidemark.dev/start
• Terms: https://guidemark.dev/terms
• License overview: COMMERCIAL-LICENSE.md

Public Hub Contents

• https://guidemark.dev/docs - canonical docs and API reference
• examples/basic-vite - minimal Vite + React example
• SECURITY.md - vulnerability reporting and license-key handling
• CHANGELOG.md - public release notes

Support

Use GitHub Issues for reproducible bugs, documentation gaps, and example requests.

For sales, licensing, or account questions, use https://guidemark.dev/contact.