All features
Feature library
Real features from SaaS products built with CraftHQ.

Sign-in

Users & access

Customers & imports

Files

Review & records

Platform

Feature breakdown · built with CraftHQ

PlatformUI

In-app help tips

Size

not sized in FP (content change)

IFPUG does not size a copy/content change as a transaction.

PR review & merge~17 mintime from pull request opened to merged (includes review)

Every screen explains itself inline, in plain language, so there is no separate manual to read.

Workflow

How it moved through the workflow

Select a stage. The build shipped, so every stage is complete; a person approved the merge.

Request

Rewrite the help-tip wording across the product in plain language, so each screen explains itself.

Questions

One decision was recorded before building: keep the long explainer banners, or fold them into title-level tips with the content preserved.

Approved

The product owner signs off the breakdown by moving the story into the approved state, and the build runs against that reference.

Definition of ready

The questions are answered.
The acceptance criteria are testable.
The size is estimated.
The scope is checked for splitting.
The product owner has signed off.

Building

This change shipped as one pull request. CraftHQ's build agents made the change with its tests; a failing check halts the work until it passes.

Checks

Three checks run on every pull request: one on the product owner's machine as CraftHQ builds, one on the engineer's machine before review, and a code-quality scan in CI. Merging is gated by the CI check passing and a person's approval, enforced by branch protection.

Review

An engineer reviews the pull request and merges it.

Merged

The pull request is merged to main after a person approves it. Nothing merges without that approval.

Definition of done

Every acceptance criterion is checked; where a scenario has a dedicated test it is cited, and where it was verified by review that is stated.
The three checks are green.
A person approved the merge.

Breakdown

The feature breakdown

Business first, then the engineering view. Tab through it.

Overview

The gap it closes

A screen that needs a manual is a screen people get wrong. The help has to be inline, short, and in plain words.

Who uses it

Every user of the product, on any screen.

User story

As a user, I want a short, plain-language help tip where I need it so that I can use a screen without training.

Examples

Example 1

A user is unsure what a field is for. They open the help tip beside it and read a one-line explanation in plain language, without leaving the screen.

Example 2

A user opens a tip by keyboard, reads it, and closes it with Escape. The tip text is always in the page and announced to a screen reader, so it works without a mouse.

Dependencies & risks

Depends on

A single shared info-tip component used across every screen. The tip text is written into each screen's markup, not loaded from a content system.

Risk & mitigation

Tips written in jargon would not help. Reduced by keeping the wording short and plain and by holding the behaviour in one shared, accessible component.

How it works

Simplified diagrams of the parts involved, the steps of one request, and where it runs.

Architecture

People
Userneeds help on a screen
Your app
Screena page in the product
Help-tip componentshared, product-wide
Tip renderingin the DOM, announced via aria
  • 1views
  • 2opens a tip
  • 3reveals in place, announced via aria
Simplified.

Sequence

Browserthe user
Web appthe shared tip component
  • 1open a help tip
  • 2reveal the tip; its text is in the DOM and announced
  • 3the tip, revealed in place and announced to a screen reader
Simplified.

Infrastructure

Client (untrusted)
Web apprenders in the browser
Your app
App serverserves the pages; authenticates, pins the tenant
  • 1page request
Simplified.

Acceptance criteria

Each scenario is written as a Gherkin spec. The Engineering tab shows the test that covers each one, or notes where it was verified by review.

@platform @ui @help

Feature: In-app help tips

  As a user

  I want a short, plain-language help tip where I need it

  So that I can use a screen without training

  Every screen explains itself inline with a short tip in plain language, so there is no separate manual to read.

  Background:

    Given a screen uses the shared help-tip component



  Rule: Help is available inline and in plain language



    Scenario: A help tip opens where the user needs it

      Given a field or a title has a help tip

      When the user opens the tip

      Then a short explanation is shown in plain language next to it



  Rule: The tip reveals, pins and is announced



    Scenario: The tip reveals on hover or focus and pins on click

      Given a field or a title has a help tip

      When the user hovers or focuses the trigger

      Then the tip is revealed, and a click pins it until Escape or an outside click closes it



    Scenario: The tip text is in the page and announced

      Given a help tip

      When the page is read by a screen reader

      Then the tip text is present in the page and announced through aria-describedby, not the title attribute



  Rule: The tip is reachable without a mouse



    Scenario: A tip opens and closes by keyboard

      Given keyboard focus is on a help-tip trigger

      When the user activates it from the keyboard

      Then the tip opens

      And pressing Escape closes it

      And the trigger carries a screen-reader description



  Rule: A folded explainer banner keeps its content in a title tip



    Scenario: Opening a title tip shows the former banner content

      Given a screen's explainer banner was folded into a title-level tip

      When the user opens the title tip

      Then the former banner content is shown

      And none of the content is lost

    @edge-cases



    Scenario Outline: The tip opens and closes by the expected inputs

      Given a help tip

      When the user "<input>"

      Then the result is "<result>"

      Examples:

        | input | result |

        | hovers the trigger | the tip is revealed |

        | clicks the trigger | the tip is pinned |

        | presses Escape | the tip closes |

        | clicks outside the tip | the tip closes |

Questions

Questions raised in planning, each with the decision taken.

Should long explainer banners stay, or fold into title-level help tips?

Long banners take up the screen and push the real work down. A title-level tip keeps the explanation but hands the screen back to the user.

AFold them into title-level tips, keeping all the content, so the screen stays clear. · recommended
BKeep the long explainer banners on the screen.
Decided: Fold them into title info-tips, content preserved (option A).

Components touched

Shared info-tip component

One inline info-tip used across every screen: it reveals on hover or keyboard focus, pins on click, and unpins on Escape or an outside click. Its text is always in the DOM and announced via aria-describedby (not the title attribute), so it works for touch and screen readers.

In-screen content

The tip text is written into each screen's markup. It is not data-driven and has no server or content-management source.

Content rewrites

The tip wording is plain, short and jargon-free; long banners fold into title-level tips with the content kept.

Data touched

Noneread

This feature is presentation and content only; it reads and writes no business data.

Security decisions

  • This feature reads and writes no business data, so it adds no new data-access surface.

Subtasks

  • A shared info-tip component used product-wide, with hover and keyboard reveal, click-to-pin, and Escape or outside-click to close.
  • aria-describedby wiring so the text is in the DOM and announced.
  • Rewrite the content in plain language and fold banners into title tips.

How each scenario is verified

  • The tip renders with an accessible name and its text in the DOM
    A unit test renders the trigger with an accessible name and the bubble in the DOM, and checks it starts unpinned.
  • A link-variant tip anchors its bubble
    A unit test checks a link variant right-anchors its bubble and carries rich markup.
  • Keyboard open and Escape close
    Verified by review of the component's reveal, pin, keyboard and aria behaviour.

Notes

  • The shared component holds the behaviour; the tip text is written into each screen, not loaded from a content system.
  • The tip is reachable by keyboard, closes on Escape, and is announced through aria-describedby.

Risk tier

UI A person approves every merge. This is a UI-tier change; it is checked by review and the component unit tests. Content and layout were verified by review, as the content is static.

Activity

Pull-request window for rewriting the tip wording.

  • Pull request opened: rewrite the help tips in plain language
  • Merged to main after a person approved

Start here

Want this on your backlog?

Get a free baseline report on one repository, or scope a 3-month pilot measured against what your team’s work costs today.

Measured from your own git history
Every pull request tested before review
A person approves every merge
Get a baseline reportScope a 3-month pilot
Next feature: Responsive / mobile layout →All features