UI prototypes

For a feature with a user interface, the design is settled before the code is written. A prototype is that design, made concrete enough to react to.

Why a prototype comes first

An agent asked to implement a screen has to decide what it looks like. Left to itself it will decide something reasonable and you will disagree with it after the code exists, which is the expensive moment to disagree. A prototype moves that conversation earlier, when changing your mind costs a regeneration instead of a rewrite.

Two kinds

HTML prototypes are standalone: fast to produce, fast to change, not running on your stack.

Target-stack prototypes are built and run on the project's own stack, so what you are looking at is the real thing. A feature's target-stack prototype is the first work on the feature's own branch: when the feature is implemented, the implementation continues from it on that same branch, replacing its placeholder parts with the real thing rather than starting the screen again.

Both are on the feature's Preview tab: Design for the design options, and Implementation for the feature's branch running on your stack — first its prototype, then its implementation. While the branch holds only the prototype, Rebuild from the design revises it and Remove prototype takes it off the branch, both after asking. Once implementation has started on top of it, those two go away and the implementation's own controls take over, because the prototype is now where the implementation started.

In the features list, a feature whose branch holds only its prototype shows the status Prototype, so you can always tell a prototype from an implementation.

Each reviewer gets their own target-stack preview. What you click, the screen you are on and the account you sign into the prototype with are yours alone, so a colleague reviewing the same feature does not move your screen. You can also keep several features' previews open side by side, each in its own browser tab.

The design source and whether a target-stack preview is built are independent project settings, so you can work from an HTML design and still have it reproduced on your stack.

Where a prototype runs

A target-stack prototype runs in the feature's own environment — the same one its implementation runs in later — so features' prototypes never wait for one another and can be built at the same time. Its controls are the Env menu's, described under the implementation below: Restart, Stop, and Add test data… to fill its database.

A prototype is built without the application shell when the shell was not yet on the base branch when the prototype was started, and the view says so. To include the shell, remove the prototype and build it again once the shell is merged.

Options, and choosing between them

A prototype comes as options rather than a single answer. You pick the one to carry forward, and the implementation agent reproduces the option the feature selected — not a fresh interpretation of the scenarios.

Options can be opened in their own browser tab when the embedded preview is too small to judge.

Seeing the implementation

Once a feature has code to run, the Preview tab's Implementation view shows the real thing: the feature's own branch, running in development mode on the feature's page, with the same dev configuration the target-stack prototype runs from. It does not need a UAT configuration, and you do not need to go to UAT Tools to find it.

• A feature waiting for your acceptance opens on it, and its implementation starts by itself. Each feature runs in an environment of its own, so starting yours never stops anyone else's. While it starts, the view lists each step and can show the log as it is written.

• A project that cannot run in development mode yet says why, in the same words as the target-stack preview's setting. When what is missing is the dev configuration, Generate the dev configuration creates it, and the implementation starts by itself once it is ready.

• The app is shown by a browser that runs beside it on the server, so it opens the app at the address the app itself expects — sign-in redirects and anything else that names its own address work as they do for the people who will use it. You can click, type, scroll and select in it as in any browser, with back, forward, reload and an address bar for the app's own routes. As with the target-stack preview, that browser is yours alone: a colleague looking at the same feature has their own, and does not move your screen or share your sign-in.

• Maximize fills the window with the app; Restore puts it back. The session is not reloaded either way, so you keep your place.

• When the app behaves, Write Tests, beside Revise implementation, writes and runs the feature's tests. The button shows the run's progress, and once the run finishes, pass or fail, each scenario's result and trace are on the feature's Test Results tab. Starting it needs the Editor role.

• Before a feature has a prototype or an implementation to run, Implementation offers Build on the target stack when the project builds designs on its stack, and is greyed out with the reason otherwise.

• While some of the prototype's placeholders are still in the implementation, the view says how many, so you can watch them go. A feature cannot be merged while one remains, so an implementation run that has not replaced them all by the end of its review rounds fails, listing the ones left, rather than finishing; revise the implementation or continue the run.

• A merged feature's Implementation runs the branch it was merged into: the repave branch when the project merges directly, or the base branch its pull requests target, as last fetched. That branch holds every merged feature, so every merged feature of the project shares the one environment. Restart picks up whatever has merged since it started. A merged feature is changed by reopening it, so Adjust and Revise implementation are off and say so.

• Once a merged feature is reopened, its Implementation runs the feature's own branch again. Merging removed the feature's working copy, so the first start after the reopen recreates it from the branch the feature merged into, which holds all of the feature's work. Opening the feature in Repave IDE does the same.

• Adjust works as it does on a target-stack prototype — on a branch that holds only its prototype, it is the prototype's Adjust, described under Giving feedback. Pin an element, say what should change, pin more on any screen, then Send to agent. Revise implementation does the same from a written instruction alone, with the feature's reference images. Either way an agent changes the feature's code on a branch of its own, updates the scenarios the change affects, runs them, has its work reviewed, and merges it into the feature's branch when its checks pass. A change no scenario describes — a colour, spacing, a layout — has no scenario to run, so a successful build is its check, and the review confirms nothing a scenario describes changed. With the browser on for the Implementation revision agent in Project Settings, which is its default, the agent starts the app and looks at the page it is changing. A feature built as part of a module is revised on the module's branch. The app on screen changes only when that lands, so you can keep using it — and keep pinning the next round — while the agent works.

• When the revision lands, each comment says what happened to it: addressed, not addressed with the agent's reason, or claimed but not verified with the reviewer agent's reason. Adjust again for what was missed brings the rest back to send again. A revision that changed scenarios says so, because a changed scenario needs approving again. A revision that changed the dependencies restarts the environment to install them. If it fails, nothing is merged and your comments are kept.

• Revising an accepted feature returns it to UAT for acceptance again, and both Adjust and the Revise dialog say so before you send. Revising is not available while the feature, its module or its verification is still running, or while another revision of it is; the controls say which. Revising needs the Editor role; a viewer can read a review but not send one.

• Accessibility checks the screen you are on, exactly as it is now — signed in, mid-journey, with whatever you have opened or filled in — and lists what it finds beside the app. A clean result covers that state of that screen and nothing else. Select findings and Send to agent to have them fixed in the same kind of revision, or dismiss the ones you decide not to fix. When the implementation changes after a check, the findings say they are out of date.

• If a start fails, the view shows why and the step it failed at, with its log, and Retry start tries again. Starting, retrying, restarting and stopping need the Editor role.

• While it runs, its controls are in the Env menu beside the app's address bar. Restart starts it again from scratch, dependencies included, and Stop ends it. The menu says whose environment it is: a feature built as part of a module runs the module's, so restarting or stopping it does so for every feature in the module. Neither asks first, because Start undoes both.

• Add test data…, first in the Env menu, fills the running implementation's database. Describe the rows you need, or upload a CSV, JSON, XLSX, SQL or dump file for an agent to map into the schema, then Generate data (or Inject data with files). The agent inserts in one transaction and commits what it inserted as a seed file on the feature's branch, so the next start has the same rows. The file travels with the branch, so the feature's UAT environment and, once merged, Main get the rows too when their UAT configuration applies seed files. When it finishes, the request shows what landed in each table and the app reloads to show it. You can close the dialog while it works. One test-data request runs at a time in a project, from here or from UAT Tools. The item is off, and says why, for an implementation that runs without a database. Adding test data needs the Editor role.

• On a merged feature the item reads Reopen and add test data…. A merged feature runs the branch it was merged into, so its data needs a branch of its own: after one confirmation the feature is reopened, its implementation starts on the feature's own branch, and the test-data dialog opens when it is running. Once the data is committed, and as long as the feature's Gherkin did not change after the reopen, the feature is Implemented again, and Create PR (or Merge to Repave Branch, in a project that merges directly) ships the data like any other change. If the request fails, the feature stays reopened and Close puts it back to merged. A feature merged as part of a module keeps its test data on Main, in UAT Tools.

• An implementation nobody has looked at for 30 minutes is stopped automatically, and the view says so when you come back.

UAT Tools keeps its own environments, run from the project's UAT configuration, for formal acceptance. The two are separate: stopping one does not stop the other.

Giving feedback

Pin it. Feedback attaches to the component it is about, on both HTML and target-stack prototypes, and several pinned problems can be reported from one session together. A pinned comment carries the context that a sentence in a chat box does not.

Everyone reviewing a prototype pins onto the same review, and Rebuild (or Update) sends every open comment in it, whoever wrote it. A comment someone else wrote carries their name. Anyone who can edit the project can delete any open comment, and Keep and Discard all act on all of them, but only a comment's author can change its wording. When the prototype changes after comments were written, the review asks you to keep the ones that still point at something before it rebuilds. On a target-stack prototype that happens whenever any feature in the project is built, since they share one app.

On a target-stack prototype, what you ask for does not stay in the preview. Once the Adjust run's code builds, the change is carried back to the design option the prototype was built from, and — only when it changes what the app does, such as a new rule or a different order — to the feature's To-Be scenarios. A changed scenario needs approving again; the others keep their approval. Each comment's result says what it changed, and a changed scenario opens side by side with what it said before.

A Figma design is changed in Figma itself, on the option's own page, and only after the code has built. While the run works you may see a copy of that page named "… · Adjust draft" in the file; the agent tries its change there, and the copy is removed when the run ends. The option's page is edited in place, so the layers the change does not touch keep your comments and links. If someone edits the page while the run works, it is left alone, and if Figma fails partway the page is put back as it was — or, when that cannot be confirmed, a copy of the page as it was is kept beside it, named "… · before Adjust", for you to compare. The connection to Figma set in Project settings must be able to edit the file; one that can only view it leaves the design as it was and says so.

Some changes are not carried back, and the result says why: a scenario that is already implemented (reopen it from the Gherkin tab), a feature that is already completed, scenarios or a design someone edited while the run worked, and a Figma file that could not be edited. Where the design does not show a change, implementation follows the preview for it rather than undoing it.

When a change fails, Show Errors says which way it failed. It sits in the panel's tab row, to the right of Remove prototype, and is hidden while there is nothing to read. A change whose code would not build is discarded, and the compiler's own output is shown for you to act on. A change that could not start — the feature's branch had uncommitted changes, or its environment could not be started, so no agent ran — says why and that nothing was changed; deal with the cause and try it again.

The design system

A design system is produced automatically by the shell and prototype flows and written to DESIGN.md in the modernized codebase. That is what keeps the fifth feature looking like the first: agents read it rather than re-deciding typography and spacing per screen.

Accessibility

Generated prototypes are checked for accessibility, deterministically, as they are produced. Whether that check gates a feature is a project setting — see Project settings.

Keeping a prototype honest

• When a feature's to-be scenario changes, its prototype can be regenerated, because a design for behaviour that has moved on is misleading.
• Revising a target-stack prototype reconciles it to a design that has moved.
• Adjusting a target-stack prototype updates the design, and the scenarios where behaviour changed, so the three never quietly disagree.
• The target-stack prototype is the start of the feature's branch, built on the code that ships, so it never drifts away from it; implementing the feature replaces its placeholders in place.
• Every prototype agent that can render its work looks at it, rather than reporting success on markup it never displayed.

Navigation and shell

Separately from individual features, the project has an application shell and a navigation map — the frame every screen sits in. The shell is designed like a feature's screens, in HTML or Figma, and you choose a design option on the Navigation & Shell page.

Implement shell on that page then builds the chosen design on your stack, checks that it builds and matches the design, and lands it on the base branch: as a pull request when the project merges through pull requests, or after you look at it running and click Merge when it merges directly. Once the shell is on the base branch, every feature built afterwards is built inside it.

In a new web application project, features cannot be implemented until the shell has merged, so every feature is built in the same frame; the implement button says so and links to the page. A batch job project has no user interface and so no shell, and is never held back by one. Implement shell runs once at a time, and is no longer offered once the shell has merged. Projects that existed before this was introduced are not held to it: their features can be implemented meanwhile, and are built without the shell until it merges.