Feature breakdown · built with CraftHQ

PlatformUI

Responsive / mobile layout

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

The product's layout reflows through CSS media queries, with a collapsible shell rail and horizontal-overflow wrappers on tables. The measured window here is one change: making the sign-in logo responsive.

Workflow

How it moved through the workflow

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

Request

Make the sign-in logo scale to the screen rather than sit at a fixed size, as the first step in making the layout work at phone width.

Questions

One decision was recorded before building: fixed sizing or fluid, clamped sizing for the sign-in logo.

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 layout built only for desktop breaks on a phone: things overflow, and the page scrolls sideways.

Who uses it

Every user who opens the product on a phone or in a narrow window.

User story

As a user on a small screen, I want the layout to reflow so that I can use the product on a phone or a narrow window.

Examples

Example 1

A user opens the sign-in screen on a phone. It fits the width, the logo scales to the screen, and there is no sideways scroll.

Example 2

A user opens a wide table on a narrow window. It scrolls horizontally within its own wrapper, so the page itself does not scroll sideways.

Dependencies & risks

Depends on

The product's shared layout stylesheet (CSS media queries, no CSS framework or JS media-query hook), the collapsible shell rail, and horizontal-overflow wrappers on tables.

Risk & mitigation

A new wide component could overflow on a phone. Reduced by the shared media-query rules, the collapsible rail, and table overflow wrappers, so a fix in one place carries across.

How it works

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

Architecture

People

Useron a phone or desktop

Your app

Shared layoutCSS media queries, collapsible rail

Grid and tablehorizontal-overflow wrapper

1opens at any width
2reflow rules

Simplified.

Sequence

Browserreports its width

Web appthe shared layout

1open at a given width
2apply fluid sizing and reflow rules
3a layout that fits the width

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
Feature: Responsive and mobile layout
  As a user on a small screen
  I want the layout to reflow
  So that I can use the product on a phone or a narrow window

  The layout reflows through CSS media queries, with a collapsible shell rail and horizontal-overflow wrappers on tables. The timed change here is the sign-in logo; the rail and the mobile-grid work shipped separately.

  Background:
    Given the product is open in a browser

  Rule: The sign-in logo scales to the screen

    Scenario: The sign-in logo is clamped to fit
      Given a user opens the sign-in screen on a narrow window
      When the screen renders
      Then the logo is clamped to a size that fits the screen rather than a fixed size

  Rule: The layout reflows through CSS media queries

    Scenario: The layout reflows at narrower widths
      Given the product is viewed at a narrower width
      When the page renders
      Then the layout reflows through its CSS media queries, with a reduced-motion rule honoured

  Rule: A wide table scrolls within its own wrapper

    Scenario: A wide table does not scroll the whole page
      Given a wide table on a narrow screen
      When the table is wider than the viewport
      Then it scrolls horizontally within its own overflow wrapper, so the page itself does not scroll sideways

  Rule: The staff shell rail collapses behind an accessible toggle

    Scenario: The staff rail collapses behind a labelled toggle
      Given the staff shell on a narrow screen
      When the user opens the navigation
      Then a labelled hamburger toggle carrying aria-expanded and aria-controls opens and closes the rail

    Scenario: The customer shell has no rail
      Given the customer shell
      When it renders
      Then it has no collapsible rail

Questions

Questions raised in planning, each with the decision taken.

Should the sign-in logo be a fixed size, or scale to the screen?

A fixed size looks right on desktop but can crowd a phone; a scaled size fits both.

AFluid: scale the logo to the screen, clamped to a sensible range. · recommended

BFixed: keep one size at every width.

Decided: Fluid, clamped to a sensible range (option A).

Components touched

Fluid sizing (CSS media queries)

Sizes that scale to the viewport, clamped to a sensible range, so elements like the logo fit both desktop and phone. The layout is plain CSS media queries in one design-token stylesheet, with a reduced-motion rule, and no CSS framework or JS media-query hook.

Collapsible shell rail

The staff shell has a collapsible left rail with a labelled hamburger toggle carrying aria-expanded and aria-controls; the customer shell has no rail.

Table overflow wrappers

Wide tables scroll horizontally within their own wrapper on narrow screens, so the page itself does not scroll sideways.

Data touched

Noneread

This feature is presentation 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

Fluid, clamped sizing for the sign-in logo (the timed change).
A collapsible shell rail with an accessible hamburger toggle (a separate change).
Horizontal-overflow wrappers on wide tables (a separate change).

How each scenario is verified

The rail toggle is accessible
A behaviour test covers the nav toggle (open and closed, aria-expanded, Escape) and confirms the hamburger is a real labelled button and the customer shell is rail-less.
Sign-in reflows at phone width with no horizontal scroll
Verified by review of the media-query layout.

Notes

Layout changes are scoped to the shared stylesheet, so one fix carries across the product.

Risk tier

UI A person approves every merge. This is a UI-tier change; it is checked by review and the nav-toggle and shell behaviour tests.

Activity

Pull-request window for one change (the sign-in logo).

Pull request opened: scale the sign-in logo to the screen
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 report Scope a 3-month pilot