FlowMark

A library to represent UX storyboards and user flows using Markdown.

Installation

Option 1: Install Globally (Recommended for CLI usage)

# Install globally from npm (when published)
npm install -g flowmark

# Then use anywhere
flowmark story.md

Option 2: Install Locally in Your Project

# Install as a project dependency
npm install flowmark

# Use with npx
npx flowmark story.md

# Or add to package.json scripts
# "scripts": { "build": "flowmark input.md -o output.html" }

Option 3: Install from Local Directory

If you have the source code locally:

# From the flowmark directory
npm install -g .

# Or link it for development
npm link

Option 4: Install from GitHub

# Install directly from GitHub
npm install -g github:simonwex/flowmark

# Or install a specific branch/tag
npm install -g github:simonwex/flowmark#main

For Development

# Clone the repository
git clone https://github.com/simonwex/flowmark.git
cd flowmark

# Install dependencies
npm install

# Link for local development
npm link

# Now you can use 'flowmark' command globally
flowmark example.md

Usage

# Password Reset Flow

## Scenario Details
* **Persona:** Jane Doe, infrequent user (40s, uses app monthly)
* **Scenario:** Jane needs to reset her password because she forgot it, but she also forgot the answer to her security question.
* **Goal:** Successfully reset password and log in.

---

## Step 1: Login Attempt Failed

> **Visual:** Jane sits at her messy home office desk late at night, frowning at her laptop screen which displays a prominent red "Incorrect Password" error message. She has one hand on the trackpad and the other resting on her forehead. Empty coffee mug nearby.

> **Caption:**
> *   **Action:** Enters username 'jdoe' and a guessed password. Clicks 'Log In'.
> *   **Emotion:** Annoyed, tired, slightly stressed.
> *   **Thought:** "Ugh, I thought that was it. Which password did I use for this?"
> *   **Environment:** Home office, late evening.

## Step 2: Initiates Password Reset

> **Visual:** Jane's screen now shows the password reset options. Her cursor is hovering over the "Forgot Password?" link. Her expression is neutral, focused.

> **Caption:**
> *   **Action:** Clicks the "Forgot Password?" link.
> *   **Emotion:** Neutral, task-focused.
> *   **Thought:** "Okay, let's get this over with."
> *   **Environment:** Same home office.

Command Line Interface

FlowMark includes a CLI for easy conversion of Markdown files to HTML:

# Basic usage - process a single file
npx flowmark story.md

# Specify output file
npx flowmark -i story.md -o story.html

# Watch mode (auto-regenerate when file changes)
npx flowmark -w -i story.md

# Process all markdown files in a directory
npx flowmark --dir storyboards --outdir html

# Process files in a directory and its subdirectories
npx flowmark -d storyboards -r --outdir html

# Create a new storyboard from template
npx flowmark init new-story.md

# Show help
npx flowmark --help

Programmatic Usage

const { parseStoryboard, generateHTML, processFile } = require('flowmark');

// Process a file
processFile('input.md', 'output.html');

// Or process markdown content directly
const markdown = `# My Storyboard\n## Scenario Details\n...`;
const storyboard = parseStoryboard(markdown);
const html = generateHTML(storyboard);

Contributing

Development

# Clone the repository
git clone https://github.com/simonwex/flowmark.git
cd flowmark

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode (useful during development)
npm run test:watch

# Generate test coverage report
npm run test:coverage

License

This project is licensed under the MIT License - see the LICENSE file for details.