# iOS Screenshot Annotation Features --- Requirements Brief

## Context

- **Source inspiration:** CleanShot X (macOS screenshot annotation tool)
- **Target platform:** iOS app
- **User:** Vinay (product founder)
- **Purpose:** These features are the user's top-used annotation tools from CleanShot X, prioritized by frequency of use. The goal is to bring the same experience to an iOS app.
- **Reference screenshots:** Located in `frames/` as `step_XXXX.jpg` files (extracted from a screen recording of the user demonstrating each feature in CleanShot X)

---

## Feature 1: Blur/Redact (HIGHEST PRIORITY)

**Reference screenshots:** `frames/step_0040.jpg`, `frames/step_0050.jpg`

### What it does

User selects a rectangular area on a screenshot and applies a blur or pixelation effect to hide sensitive information. The blur intensity is adjustable via a slider, ranging from a light blur to heavy pixelation. This is the user's single most-used feature.

### User's exact words

> "The first one I always start with is blurring. If I want to redact this, I apply this --- look how easy it is. I can reduce the blurring effect depending on how little or how more I want. This is one of my top used features because it helps me redact anything I don't want people to see."

### Specific behaviors

- Drag to select a rectangular area on the screenshot
- Blur applies immediately upon completing the selection
- The selected region shows resize handles (blue corner dots) so the user can adjust the area after placement
- A slider control adjusts blur intensity after placement (from light gaussian blur to heavy pixelation)
- Multiple blur regions can be placed on the same image independently
- The blurred area must look professional --- not a flat colored box, but an actual blur/pixelation of the underlying content
- Primary use case: redacting names, admin views, personal data, email addresses, URLs

---

## Feature 2: Spotlight/Highlight (HIGH PRIORITY)

**Reference screenshots:** `frames/step_0070.jpg`, `frames/step_0090.jpg`

### What it does

Dims or darkens the entire screenshot EXCEPT for the user-defined spotlight area. The highlighted region remains at full brightness, creating a natural focal point that draws the viewer's eye. The opacity of the darkening overlay is adjustable.

### User's exact words

> "The second most important feature --- I want to bring their attention. I want to highlight, hey, this is my workspace. I can control the opacity. I want to bring their attention to the latest demo."

### Specific behaviors

- Tap or drag to define the spotlight area (rectangular)
- Everything outside the spotlight area gets covered by a semi-transparent dark overlay
- The spotlight area is "cut out" of the overlay, showing the original screenshot at full brightness
- Adjustable darkening opacity via slider (from a subtle dim to very dark, nearly opaque)
- Multiple spotlight regions should be possible on the same image
- The spotlight shape is rectangular, potentially with soft or slightly rounded edges
- Used to direct attention to specific UI elements, buttons, sections of a screen

---

## Feature 3: Counter/Numbered Steps (HIGH PRIORITY)

**Reference screenshots:** `frames/step_0110.jpg`, `frames/step_0130.jpg`, `frames/step_0140.jpg`

### What it does

Places numbered circular markers on the screenshot to create step-by-step guides. Numbers auto-increment with each tap. Each marker is a filled circle with the number centered inside.

### User's exact words

> "If I want to bring their attention to the steps I want them to take --- this is my brand color, but I'll select red. You can see numbering, lettering, whatnot. Start with selecting your workspace. Then go to dashboard..."

### Specific behaviors

- Tap anywhere on the screenshot to place a numbered marker
- Numbers auto-increment starting from 1 (first tap places "1", second places "2", etc.)
- Customizable marker color (user mentions brand color, selected red for the demo)
- Customizable marker size (user selected size 20 in the demo)
- Each marker is a filled circle with the number centered inside in a contrasting color (white on dark backgrounds)
- Markers should have a slight shadow or outline so they remain visible on any background color
- Support for lettering mode as well (A, B, C instead of 1, 2, 3)
- Markers can be repositioned after placement by dragging
- Use case: creating step-by-step walkthrough guides on a single annotated screenshot

---

## Feature 4: Arrow Annotations (MEDIUM PRIORITY)

**Reference screenshots:** `frames/step_0190.jpg`

### What it does

Draws directional arrows on the screenshot to point from one element to another, or to direct the viewer's attention to a specific area.

### User's exact words

> "Sometimes I might also use arrows. This is very rare, but I use it --- hey, make sure you're looking at here or this specific thing."

### Specific behaviors

- Drag from a start point to an end point to draw an arrow
- The arrow has a clear pointed head at the end (destination) of the line
- Customizable color (should match the overall annotation color theme the user has selected)
- Thick, clearly visible stroke weight
- The arrow in the demo is a large red arrow with a solid fill
- Arrows can be repositioned or resized after placement
- Use case: directing attention, connecting two related UI elements, pointing at a specific button or label

---

## Feature 5: Background Beautify/Export (MEDIUM PRIORITY)

**Reference screenshots:** `frames/step_0210.jpg`, `frames/step_0240.jpg`, `frames/step_0260.jpg`

### What it does

Wraps the annotated screenshot in a visually appealing background with gradient colors, padding, inset, corner radius, and shadow. Provides aspect ratio presets for social media export.

### User's exact words

> "Add background --- beautiful! Look how gorgeous this is. I select the one closest to my branding. The padding is important. Even more important is inset --- instead of this cramped thing, I can do an inset. I always keep it at 20. I bring corners to 3 or 4. If I'm sharing on LinkedIn, I select 4:3."

### Specific behaviors

- **Gradient backgrounds:** Multiple gradient presets to choose from (the user picks one closest to their brand)
- **Plain color backgrounds:** Solid single-color option
- **Wallpaper/blurred backgrounds:** Option for textured or blurred background fills
- **Padding control:** Adjusts how much space surrounds the screenshot within the background frame
- **Inset control:** The screenshot shrinks within the frame, creating breathing room --- user's preferred value is ~20
- **Corner radius:** Rounds the corners of the screenshot itself --- user prefers 3-4
- **Shadow:** Drop shadow on the screenshot to create depth against the background
- **Auto-balance toggle:** Automatically adjusts padding, inset, and shadow for a balanced look
- **Aspect ratio presets:**
  - Auto (fits content)
  - 4:3 (LinkedIn --- user's most common export ratio)
  - 16:9 (widescreen/presentations)
  - 1:1 (square/Instagram)
- **Alignment options:** Control where the screenshot sits within the background frame

---

## User's Workflow (Order of Operations)

This is the order the user follows when annotating a screenshot. The UI should support this flow naturally:

1. **Capture or import** a screenshot into the app
2. **Blur/redact** sensitive areas (names, data, admin views)
3. **Spotlight** the area of focus to draw the viewer's eye
4. **Add numbered step counters** to create a walkthrough
5. **(Occasionally)** Add arrows to point at specific elements
6. **Apply background beautification** with gradient, padding, inset, and corner radius
7. **Export/save** the final annotated image

---

## User's Preferences and Design Sensibilities

- **Dark UI theme:** The user's workspace is dark-themed; the annotation tool UI should respect the app's existing theme
- **Brand colors matter:** The user wants to set and use their brand color for annotations (markers, arrows, highlights)
- **Professional output is non-negotiable:** The result must look polished and share-ready, not "just functional." This is a tool for public-facing content
- **LinkedIn is the primary sharing platform:** 4:3 aspect ratio is the most common export format
- **Speed and minimal taps:** CleanShot X is fast and fluid. The iOS version must match that speed --- minimal menus, quick access to tools, immediate visual feedback
- **Annotation tools should be easily accessible** from a toolbar or tool palette, not buried in menus

---

## What NOT to Specify (Let the AI Decide)

- Do NOT prescribe which Swift frameworks to use (Core Graphics, UIKit drawing, PencilKit, Metal, Core Image, etc. --- let the AI choose based on the codebase)
- Do NOT prescribe architecture patterns (MVC, MVVM, etc. --- let the existing codebase guide this)
- Do NOT prescribe specific UI layout details beyond what is described above (let the AI match existing app patterns)
- Do NOT prescribe data models or persistence strategies
- The user wants the **features and behaviors**, not the implementation. Trust the AI coding assistant to determine the best technical approach.
