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. They live on the project's prototype branch, one per feature, and the feature's target-stack build has its own view, where Revise prototype builds it again (after asking) and Remove prototype takes it out.

Both are on the feature's Preview tab: Design for the design options, Target Stack for the build, and — once the feature has code to run — Implementation, described below.

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.

The shared preview

Your view of a preview is your own, but what it shows runs in one preview environment for the whole project: one set of containers, one database and one set of installed dependencies, serving every feature's target-stack prototype. The environment's controls sit in the Env menu beside the preview's status, apart from the buttons that act on the prototype you are looking at:

• Restart brings the preview back quickly, reusing what is already installed. Use it when the preview is stuck or showing something stale.
• Reinstall dependencies & restart runs the project's install step again first. It is slower; use it when the preview fails on a missing or broken library.
• Stop shuts the preview down until someone starts it again.
• Add test data…, first in the menu, fills the preview's database, so screens that read real data have rows to show. It works like the same item on a feature's implementation (see below), with two differences: the seed file is committed on the prototype branch, so every feature's screens have the rows after any later start, and a request waits for a prototype change that is in progress before it runs. Screens still built on placeholder data do not read the database, so they do not change. The item is off, and says why, when the preview runs without a database.

Restart, the reinstall and Stop each ask first, because they affect every feature's prototype at once. Nothing is deleted by any of them. When the preview is not running, the next step (Start preview, Retry, or Cancel while it starts) is shown where the preview would be. A failed start also offers Reinstall dependencies & retry.

The same menu is on the Navigation & Shell page's target-stack section, since it is the same preview.

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 the implementation has produced a branch to run, Implementation is greyed out, with the reason.

• 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: 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 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 and for a merged feature, whose test data is added on Main in UAT Tools. Adding test data needs the Editor role.

• 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.

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 project's prototype environment could not be prepared, so no agent ran — says that nothing was changed; try it again, and that message clears by itself as soon as a prototype job on the project gets past that point.

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 tracks the code that ships, so it does not drift into being a screenshot of something that no longer exists.
• 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. It is generated once and reproduced by the implementation agents, so features do not each invent their own navigation.