Skip to content

feat(installer): add reusable wizard design gallery - #198

Closed
weastler wants to merge 5 commits into
weastler-azure-deployment-wizardfrom
weastler-microsoft-wizard-design-tooling
Closed

weastler wants to merge 5 commits into
weastler-azure-deployment-wizardfrom
weastler-microsoft-wizard-design-tooling

Conversation

@weastler

@weastler weastler commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Why

Contributors need a repeatable way to review every wizard screen offline as its design evolves. This PR builds on #197 and preserves the existing 100-state design catalog without running deployment operations or reading private installation files.

What changes

npm run wizard:design --prefix infrastructure renders the real terminal components with synthetic data and serves a loopback capture workflow for an ordinary browser. Choosing Generate all screens and PDF exports individual PNGs, visible-text transcripts, an offline gallery, and an annotated PDF with linked contents. Generated files stay in a unique ignored output directory, not in Git. The command needs no Copilot browser host or browser installation.

The live preview and offline gallery keep Previous, the screen selector and Next together, with annotations beside the screen. The preview fits the available width without changing the full-size PNG exports. Navigation and generation cannot overlap on the shared terminal. PDF export returns to the selected screen, leaves completed generation disabled, and links to the PDF, original PNGs and transcripts.

One canonical catalog supplies sequential screen numbers for the dropdown, navigation, manifest, and PDF. Stable semantic IDs identify files and links without retaining old screenshot numbers, fixing the recovery-chapter ordering. Each screen explains its purpose, required decision or default, consequence, and source. Field validation and deployment receipts use production definitions and formatting; cloud results remain explicitly fabricated. Source-copy drift stops generation until affected fixtures and annotations are reviewed, including the local writer-lock and ambiguous database-provisioning messages.

Open the complete private URL printed by the command, including its access fragment. The token is not returned by the public catalog; export requests require that token and the exact loopback origin. The server rejects oversized requests, invalid PNGs, and incomplete captures instead of creating a partial PDF. Deployment, release, sign-in, lock recovery, and private configuration remain outside this tool. The infrastructure design guide documents regeneration and catalog maintenance. Synthetic captures illustrate presentation, not live Azure behavior or an accessibility audit.

The actual generated offline gallery below shows the restored layout, with navigation and the PDF link. Browser viewport: 1368 × 1349; terminal data is synthetic.

Restored offline gallery with Previous and Next navigation, side-by-side annotations and PDF link — synthetic — 1368 × 1349 browser viewport

The refreshed CLI-help capture includes the underlying wizard's clean-checkout requirement and separate consent for state-network changes. Terminal viewport: 112 columns × 24 rows.

084 CLI help with separate network consent and clean-checkout warning — synthetic — 112 columns × 24 rows

These final generated gallery cards identify the real sources of the local writer-lock and ambiguous-provisioning messages. Browser viewport: 1368 × 1349. Their errors, paths and cloud outcomes are synthetic.

087 local writer lock gallery with corrected source annotation — synthetic — 1368 × 1349 browser viewport

090 ambiguous database provisioning gallery with corrected source annotation — synthetic — 1368 × 1349 browser viewport

@weastler
weastler requested review from a team and nshki as code owners November 6, 2026 18:29
Copilot AI adaptive review requested due to automatic review settings November 6, 2026 18:29

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved export races, incomplete source-drift checks, and unauthenticated token exposure can produce incorrect or stale captures and let other local users overwrite exports or prematurely finish runs.

3 open issues
1 file not reviewed
  • infrastructure/package-lock.json: Generated file
What changed in this PR

Adds an offline design-review workflow for the Azure deployment wizard introduced in #197, using real terminal components with synthetic data rather than running deployment operations.

Changes:

  • Defines a canonical 100-state catalog with stable IDs, annotations, and source-copy drift checks.
  • Adds browser-based capture and export of PNGs, transcripts, an offline gallery, and a linked PDF.
  • Documents regeneration and adds catalog, capture-server, and output tests.
File Description
infrastructure/​README.md Introduces the design-gallery command.
infrastructure/​package.json Adds the command and capture dependencies.
infrastructure/​package-lock.json Locks the new dependencies.
infrastructure/​installer/​design-gallery/​types.ts Defines scene and capture contracts.
infrastructure/​installer/​design-gallery/​server.ts Serves loopback previews and coordinates export.
infrastructure/​installer/​design-gallery/​server.test.ts Covers request guards and export completion.
infrastructure/​installer/​design-gallery/​scenes.ts Defines 100 annotated scenes and source bindings.
infrastructure/​installer/​design-gallery/​render.ts Renders production terminal components with synthetic inputs.
infrastructure/​installer/​design-gallery/​output.ts Validates captures and builds gallery and PDF outputs.
infrastructure/​installer/​design-gallery/​output.test.ts Covers image validation, navigation, and generated files.
infrastructure/​installer/​design-gallery/​index.ts Provides command entry and argument handling.
infrastructure/​installer/​design-gallery/​command.ts Coordinates rendering, output directories, and server lifecycle.
infrastructure/​installer/​design-gallery/​catalog.ts Validates catalog order and checks source hashes.
infrastructure/​installer/​design-gallery/​catalog.test.ts Covers scene identity, ordering, and source bindings.
infrastructure/​installer/​design-gallery/​capture.js Implements browser preview and capture submission.
infrastructure/​installer/​design-gallery/​capture.html Adds the browser capture interface.
infrastructure/​docs/​terminal-design.md Documents regeneration, maintenance, and evidence limits.
infrastructure/​.gitignore Excludes generated design packs.

Review effort: Balanced (auto)

@weastler
weastler marked this pull request as draft November 6, 2026 18:37
@weastler

weastler commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

The restored gallery layout from b3a6d83. This is the actual generated offline gallery, not another terminal simulation: Previous/Next and the selector stay together, annotations sit beside the screen, and the annotated PDF remains available. Browser viewport:1368 x1349. All terminal data is synthetic; this is not cloud evidence. This PR remains draft.

Restored offline gallery with Previous and Next navigation, side-by-side annotations and PDF link - synthetic - 1368 by 1349 browser viewport

@weastler
weastler added this pull request to stack #199 November 6, 2026 18:42
@weastler

weastler commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Final synthetic design evidence from 8dd45ce after merging the reviewed wizard layer. The generated offline gallery retains Previous/Next and PDF access; scenes 087 and 090 now identify their real copy sources. Browser viewport: 1368 × 1349. Scene 084 shows the refreshed automation consent warning at 112 columns × 24 rows. These are fabricated design states, not deployment, live recovery, sign-in or accessibility verification.

087 local writer lock gallery with corrected source annotation — synthetic — 1368 × 1349 browser viewport

090 ambiguous database provisioning gallery with corrected source annotation — synthetic — 1368 × 1349 browser viewport

084 CLI help with separate network consent and clean-checkout warning — synthetic — 112 columns × 24 rows

@weastler
weastler marked this pull request as ready for review November 6, 2026 19:47
@weastler
weastler force-pushed the weastler-azure-deployment-wizard branch from fd0cb97 to d55c603 Compare November 10, 2026 22:21
@weastler
weastler force-pushed the weastler-microsoft-wizard-design-tooling branch from 8dd45ce to 0f9edc0 Compare November 10, 2026 22:32
weastler and others added 5 commits November 12, 2026 10:03
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Bind local-session and ambiguous-provisioning fixture copy to their actual sources.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Retain the source bindings, source locations and diagnostic annotations from the reviewed lower-layer synchronization after replaying only the tooling commits.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@weastler
weastler force-pushed the weastler-microsoft-wizard-design-tooling branch from 0f9edc0 to b86b067 Compare November 12, 2026 18:03

@nshki nshki left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is a really useful tool, but I'd love to be able to somehow use Storybook for this. If the primary use case is to be able to see all the different visual states of the wizard, I think Storybook instead of a bespoke tool is a better fit since we already have it in the codebase. What do you think?

@weastler

Copy link
Copy Markdown
Contributor Author

I think this is a really useful tool, but I'd love to be able to somehow use Storybook for this. If the primary use case is to be able to see all the different visual states of the wizard, I think Storybook instead of a bespoke tool is a better fit since we already have it in the codebase. What do you think?

Yeah, I think that is fair, especially since it is react based so this should totally be possible. I'll remove this one from the stack and come back eventually with a Storybook based version.

@weastler
weastler removed this pull request from stack #199 November 12, 2026 20:49
@weastler weastler closed this Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants