Mockups & Wireframes

Attaching Mockups to User Stories: The Complete Spec Package

Combine user stories, acceptance criteria, mockup descriptions, and technical constraints into the complete spec package format.

The Complete Spec Package

The Spec Package is the deliverable that combines everything into a single, actionable document:

  1. User Story: The intent — who, what, why
  2. Acceptance Criteria: The behavior — Given/When/Then format
  3. Mockup/Wireframe: The appearance — layout, components, states
  4. Technical Constraints: The implementation — stack, libraries, patterns

A complete spec package serves two purposes simultaneously: it is a team communication tool that aligns designers, developers, and product managers, and it is an AI prompt that produces working code in one pass.

Annotating Mockups with Story References

When you create mockups, add annotations that reference specific user story IDs and acceptance criterion numbers. This creates a traceable link:

  • The "Submit" button annotation: "UC-1.6: Triggers checkout flow. AC-3: Disabled when form has validation errors."
  • The error message area: "AC-7a: Payment declined. AC-7b: Network error. See extensions section."
  • The confirmation modal: "AC-5: Appears on successful submission. Contains order number."

This traceability means any developer looking at the mockup can immediately find the behavioral specification behind any visual element.

Where Teams Store Spec Packages

Notion: Excellent for teams that want story + wireframe + mockup + acceptance criteria in a single document. Embed Figma mockups directly in the page. Database views let you filter by status, sprint, or feature area.

Confluence: Enterprise wiki with deep Jira integration. Spec documents live next to their Jira tickets. Good for large organizations where documentation is a compliance requirement.

Linear: Modern project management where issues support full markdown descriptions with image uploads. Spec packages live inside the issue. Links to Figma files, acceptance criteria as tasks within the issue.

GitHub Issues: Markdown descriptions with image attachments. Labels for categorization. Links to PRs that implement the spec. Good for developer-first teams that live in GitHub.

Complete Worked Example: User Edits Their Profile

User Story

As a user, I want to edit my profile information so that I can keep my account details current.

Acceptance Criteria

  1. Given I am on my profile page, when I click "Edit Profile", then an edit form appears with my current information pre-populated
  2. Given the edit form is open, when I change my display name and click "Save", then my profile updates and I see a success toast "Profile updated"
  3. Given the edit form is open, when I submit with an empty display name, then an inline error "Display name is required" appears and the save is blocked
  4. Given I am editing my avatar, when I upload an image, then I see a crop/preview before saving
  5. Given the edit form is open, when I click "Cancel", then the form closes with no changes saved

Mockup Description

Layout: Modal overlay (max-width 560px), centered. Dark card background.

Header: "Edit Profile" title + X close button top-right.

Avatar section: Current avatar image (80px circle) + "Change photo" button below.

Form fields: Display name (text input, required), Bio (textarea, max 160 chars, character counter), Website URL (text input, optional).

Footer: Cancel (ghost button, left) + Save Changes (amber primary button, right).

Error state: Red border on invalid inputs, error text below.

Loading state: Save button shows spinner, form disabled during save.

Technical Constraints

  • Stack: React, TypeScript, Tailwind CSS
  • Form library: React Hook Form with Zod validation
  • Image upload: Supabase Storage, crop with react-image-crop
  • Toast: Existing toast component at src/components/ui/Toast
  • Pattern: Follow same modal pattern as ConfirmDialog.tsx

Assembled as Bolt.new Prompt

> Add a profile edit feature to my React app. User clicks "Edit Profile" to open a modal with their current info. Fields: display name (required), bio (max 160 chars with counter), website URL (optional), avatar with image upload and crop preview. On save, validate with Zod (display name required, URL must be valid format or empty, bio max 160 chars). Show inline validation errors. Success toast on save. Cancel closes without saving. Tech: React + TypeScript + Tailwind + React Hook Form + Zod + Supabase Storage.

Key Takeaways

  • A Spec Package combines user story + acceptance criteria + mockup description + technical constraints
  • Annotate mockups with story and acceptance criteria references for full traceability
  • Notion, Confluence, Linear, and GitHub Issues are all valid homes for spec packages
  • A complete spec package serves as both team communication and a highly effective AI prompt
  • The spec package format is the foundation of the SDD pipeline for multi-feature projects

Example

markdown
# Complete Spec Package Template

## Story
As a [role],
I want [goal],
so that [benefit].

## Acceptance Criteria
1. Given [...], when [...], then [...]
2. Given [...], when [...], then [...]
(5+ criteria covering happy path, validation, errors)

## Mockup
Layout:     [describe layout structure]
Components: [list key UI elements and their behavior]
States:
  - Default: [description]
  - Empty:   [description]
  - Loading: [spinner location, disabled elements]
  - Error:   [error display, recovery action]
  - Success: [confirmation message, next state]

## Technical Constraints
Stack:     [React/Vue/etc + TypeScript + CSS approach]
Libraries: [specific libraries required]
Patterns:  [follow existing pattern at src/components/X]
API:       [endpoint or service to use]
Validation:[validation library and rules]
Try it yourself — MARKDOWN