Skip to content

Unify starter and tutorial design with system dark mode - #5440

Closed
wasp-bot wants to merge 2 commits into
mainfrom
bot/5383-unify-starter-design
Closed

wasp-bot wants to merge 2 commits into
mainfrom
bot/5383-unify-starter-design

Conversation

@wasp-bot

Copy link
Copy Markdown
Collaborator

Description

Fixes #5383

Give the starters, tutorial, and development API server page a consistent, calmer design using the existing Wasp palette:

  • Use system sans-serif for UI text and monospace for code, consistent spacing/radii, and thin neutral borders instead of heavy offset shadows.
  • Keep yellow accents on welcome content; make task/tag/auth controls neutral and reusable.
  • Replace the basic starter's expanding walkthrough with a static list of steps and examples, eliminating the shifting reading area.
  • Follow the system light/dark preference, including inputs, password visibility buttons, feedback messages, tags, and dialogs.
  • Align control typography and sizing; make small screens wrap rather than overflow.
  • Keep color choices keyboard-accessible. Fix the backdrop-click handler interpreting keyboard clicks at (0, 0) as clicks outside the dialog.
  • Keep basic/minimal base CSS identical and synchronize both tutorial examples, the latest CSS snippet/patch, and three tutorial screenshots.

The branded standalone server screen is called wrong-port in the current source tree; this PR updates that screen, without introducing new router/404 behavior. This is a consistency pass using today's palette, not a replacement for the designer's upcoming brand direction. No UI dependency added.

Browser previews

Full gallery: welcome, tasks, auth, minimal starter, tutorial, mobile, and server page.
The separate preview branch holds review images only and is not intended to be merged.

Light application UI Dark application UI
Tasks in light mode Tasks in dark mode

Validation

  • mise run build
  • SDK core type checks and all 86 unit tests.
  • Real Chromium runs of the starter Playwright tests against freshly generated apps: 13 basic + 4 minimal passed. These use a temporary local config pointing at loopback-only app servers rather than the Docker/MailCrab orchestration.
  • New regression coverage: system colors at 320px, no horizontal overflow, themed Auth UI/password controls, matching input/submit heights, static welcome steps, keyboard color selection without closing the dialog, and starter/tutorial CSS synchronization.
  • wasp install and wasp compile for isolated copies of both tutorial examples.
  • Updated tutorial CSS patch applied successfully; its output exactly matches the example CSS.
  • Docs production build, Markdown snapshot regeneration, and all 8 Markdown snapshot checks.
  • Compiler snapshots regenerated using mise run test:waspc:e2e:accept-all (with TASTY_PATTERN='Snapshot Tests').
  • Changed-file Prettier checks and git diff --check.

Existing validation limitation: full tutorial action generation gets past the changed CSS patch, then fails at the unchanged 07-auth__wasp-file-auth.patch, whose context pins Wasp ^0.26.0 while the starter generates ^0.27.0. That unrelated patch is left unchanged.

Session: http://swarm:4096/server/aHR0cDovL3N3YXJtOjQwOTY/session/ses_e05446f37ffeba0Ybl2ccSttph

Agreement

Type of change

  • 🔧 Just code/docs improvement
  • 🐞 Bug fix
  • 🚀 New/improved feature
  • 💥 Breaking change

Checklist

  • I tested my change in a Wasp app to verify that it works as intended.

  • 🧪 Tests and apps:

    • I added unit tests for my change.
    • (if you fixed a bug) I added a regression test for the bug I fixed.
    • (if you added/updated a feature) I added/updated e2e tests in examples/kitchen-sink/e2e-tests.
    • (if you added/updated a feature) I updated the starter templates in waspc/data/Cli/templates, as needed.
    • (if you added/updated a feature) I updated the example apps in examples/, as needed.
      • (if you updated examples/tutorials) I updated the tutorial in the docs (and vice versa).
  • 📜 Documentation:

    • (if you added/updated a feature) I added/updated the documentation in web/docs/.
  • 🆕 Changelog: (if change is more than just code/docs improvement)

    • I updated waspc/ChangeLog.md with a user-friendly description of the change.
    • (if you did a breaking change) I added a step to the current migration guide in web/docs/migration-guides/.
    • I bumped the version in waspc/waspc.cabal to reflect the changes I introduced.

@Martinsos

Copy link
Copy Markdown
Member

Nice work @wasp-bot ! Did you use any of the skills we have in the repo? E.g. review skill?

@wasp-bot
wasp-bot deployed to fly-deploy-test November 20, 2026 21:15 — with GitHub Actions Active
@wasp-bot
wasp-bot deployed to railway-deploy-test November 20, 2026 21:15 — with GitHub Actions Active
@wasp-bot

Copy link
Copy Markdown
Collaborator Author

Thanks! No—I didn’t invoke any repository skills for this pass, including wasp-review.

I followed AGENTS.md, inspected the diffs myself, ran the compiler/unit/browser/docs checks, and opened the Chromium screenshots for visual inspection. But that was an ad hoc self-review, not a structured review using the review skill. So that dedicated review step hasn’t been done yet.

@pullfrog pullfrog Bot 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.

Important

Before merging, preserve readable Auth UI defaults for existing apps and give the tag color picker a focus indicator distinct from its selected state.

Approach: System-driven CSS variables and a static walkthrough fit the starter refresh; the shared Auth UI also needs defaults that work without starter-specific overrides.

Reviewed changes across the starter templates, tutorial, Auth SDK, and standalone development server page.

  • Starters: System colors, responsive control styling, a static walkthrough, and keyboard-selectable tag colors.
  • Shared Auth UI: Customizable field colors, aligned controls, and updated headings and feedback styling.
  • Tutorial and server page: Matching tutorial styles and screenshots, plus an inline theme for the existing wrong-port page without routing changes.
  • Validation: Verified tutorial patch applicability and CSS parity, and reproduced the Auth UI and keyboard focus issues in isolated Chromium fixtures. I did not rerun the full app suites.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using gpt-6.2-sol | 𝕏

--color-submitButtonText: black;
--color-formErrorText: var(--color-darkRed);
--color-inputBackground: #f8f4ff;
--color-inputText: currentColor;

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.

On an existing dark app that sets body { color: white; background: #111 } without overriding the new tokens, the default Auth UI now paints white input text and a white reveal icon over the unchanged pale-purple field. Chromium computes 1.08:1 contrast for the field text; before this change the same field used black text. The dummy email notice has the same mismatch with its new inherited foreground.

Technical details
# Pair default Auth UI foregrounds with their backgrounds

## Affected sites
- `packages/libs/sdk-core/src/browser/auth/forms/auth-styles.css:27-28` — the default background is fixed and pale, but the default foreground follows the surrounding app.
- `packages/libs/sdk-core/src/browser/auth/forms/FormPasswordInput.module.css:9` — the reveal button now uses the same foreground token.
- `waspc/data/Generator/templates/sdk/wasp/auth/forms/internal/email/DummyEmailSenderNotice.module.css:5-6` — the notice also uses a pale default background with inherited text.

## Required outcome
- Keep default foreground/background pairs readable without app overrides. A dark default foreground for the light field would preserve the existing behavior; let the starter and tutorial continue to override both tokens together. Pair the notice's foreground and background as well.

"hover:outline-2 hover:outline-offset-2 hover:outline-black",
checked && "outline-2 outline-offset-2 outline-black",
"border-line flex size-8 cursor-pointer items-center justify-center rounded-md border",
"peer-focus-visible:outline-ink peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2",

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.

Tabbing from the tag name into the color group lands on the checked swatch, but its outline looks exactly the same before and after focus. Give selection a separate visual cue, such as a checkmark, and reserve the outer outline for :focus-visible so keyboard users can tell when they have entered or left the group.

id={id}
className={twJoin(
"w-full border-2 border-black bg-white px-4 py-3 text-black placeholder:text-gray",
"border-line bg-surface text-ink placeholder:text-gray w-full rounded-md border px-3 py-2.5",

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.

The new border-line gives the task and tag text fields less than 2:1 contrast against the surrounding colors in both themes, making the editable area hard to distinguish. The same decorative border color is now used for the starter Auth UI and tutorial fields; give input borders their own token that reaches 3:1 against the adjacent surface without darkening every divider.

Technical details
# Distinguish editable fields from their surroundings

## Affected sites
- `waspc/data/Cli/starters/basic/src/shared/components/Input.tsx:22` — task and tag fields use `border-line`.
- `waspc/data/Cli/starters/basic/src/Main.css:59` and the matching minimal and tutorial copies — `--color-gray600` maps the Auth UI field border to `--line`.
- `examples/tutorials/TodoApp/src/Main.css:232` and `examples/tutorials/TodoAppTs/src/Main.css:232` — the task input gets `--line` through `--border`; its styling is also in the chapter snippet and patch.

## Required outcome
- Keep input boundaries visible before focus in both themes. Share the stronger field-border color across these consumers while leaving decorative borders unchanged.

@pkg-pr-new

pkg-pr-new Bot commented Nov 20, 2026

Copy link
Copy Markdown

Open in StackBlitz

@wasp/spec

npx https://pkg.pr.new/@wasp/spec@5440

@wasp/cli

npx https://pkg.pr.new/@wasp/cli@5440

@wasp/cli-darwin-arm64-unknown

npx https://pkg.pr.new/@wasp/cli-darwin-arm64-unknown@5440

@wasp/cli-linux-arm64-glibc

npx https://pkg.pr.new/@wasp/cli-linux-arm64-glibc@5440

@wasp/cli-linux-x64-glibc

npx https://pkg.pr.new/@wasp/cli-linux-x64-glibc@5440

@wasp/cli-linux-x64-musl

npx https://pkg.pr.new/@wasp/cli-linux-x64-musl@5440

commit: 65cbcda

@wasp-bot wasp-bot closed this Nov 20, 2026
@wasp-bot
wasp-bot deleted the bot/5383-unify-starter-design branch November 20, 2026 21:32

This branch was successfully deployed

2 active deployments
fly-deploy-test — 65cbcda6 Deployed Nov 20, 2026 by wasp-bot via deploy-test / Test Fly deployment #15784
railway-deploy-test — 65cbcda6 Deployed Nov 20, 2026 by wasp-bot via deploy-test / Test Railway deployment #15784
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.

Unify and fix design across starters, tutorial, 404 page, etc

2 participants