Skip to content

docs: align Hilla/React wording, theme tokens, and terminology in Building Apps and Getting Started - #6337

Merged
peholmst merged 1 commit into
mainfrom
claude/vaadin-docs-6293-fd561d
Oct 9, 2026
Merged

peholmst merged 1 commit into
mainfrom
claude/vaadin-docs-6293-fd561d

Conversation

@peholmst

@peholmst peholmst commented Oct 9, 2026

Copy link
Copy Markdown
Member

Closes #6293.

Four bullets in the issue were already fixed on main before this PR: the forms meta-descriptions (#6330), package-component.adoc (now recommends --vaadin-*), show-notification.adoc (now ButtonVariant.TERTIARY), and dialogs-and-drawers.adoc (no LumoUtility left).

Hilla vs React views

  • Convention: the Building Apps landing page now says the guides use Flow views unless they say otherwise. Instead of badging every Flow-only page, I removed the redundant Flow badges from callbacks.adoc, futures.adoc, and the AI quick start. The background-jobs overview says which options also work with React views.
  • architecture/layers.adoc, server-push/index.adoc, and the two consistency pages talk about Flow views and React views instead of Flow and Hilla. The diagram already said "Flow UI" and "React UI"; only its alt text changed.
  • interaction/reactive.adoc:
    • The Hilla-only constraints are now phrased for React views. The Flux-only warning still holds: Hilla's TransferTypesPlugin maps Flux but not Mono.
    • The deprecated com.vaadin.hilla.Nullable import is now org.jspecify.annotations.Nullable.
    • I removed the note saying sealed interfaces aren't supported. It's stale: Hilla supports polymorphic types through @JsonTypeInfo and @JsonSubTypes (its subtypes generator plugin).
  • Add a Form and Add a Grid point React readers to the Hilla forms and data grid guides.
  • Getting Started: the templates and Playground pages say React instead of Hilla. The IDE page explains that TypeScript support only matters if you add React views.

Lumo vs Aura vs --vaadin-*

Convention: examples use the theme-neutral --vaadin-* base style properties where they exist. Those don't cover accent colors, semantic colors (success/warning/error), or font sizes. For those, the examples use Aura, the default theme, and name the Lumo equivalent in one sentence.

  • ui-basics/add-styling.adoc: all examples converted. The intro no longer claims the examples are Lumo but work the same with Aura.
  • components/build-component.adoc: --vaadin-gap-xs and Aura status colors, with a note on the Lumo equivalents.
  • components/style-component.adoc: Aura is listed before Lumo and gets an example table like Lumo's.
  • forms-data/add-form/validation.adoc: LumoUtility.TextColor.ERROR, which has no effect under Aura, is replaced with a CSS class and a stylesheet rule.
  • responsive.adoc, css-grid.adoc, create-custom-field, and the PDF page already flag their Lumo assumption, so I left them as they are.

Smaller drift

  • Dev terms: the five IDE run pages said "Hot deploy of the frontend files is enabled automatically". That's wrong: hot deploy is an opt-in mode. run/index.adoc now defines live reload, hotswap, and hot deploy once, matching the Flow reference, and recommends hotswap.
  • Naming:
    • "Dev Environment" is now "Development Environment".
    • The quick start introduces Vaadin Copilot as unrelated to GitHub Copilot at first mention.
    • The View Builder page now spells "Vaadin Start Playground" with a capital P.
  • Xrefs: 15 pages that mixed <</...>> and <<{articles}/...>> now use {articles} throughout. Five xrefs lost their .adoc suffix.
  • Order and location: replace-h2.adoc moved to persistence/replace-h2.adoc (order 7, after Add Flyway), with a redirect. Persistence moved from order 10 to 20, so it no longer clashes with Add a Grid.
  • Front matter: added descriptions to react/add-view.adoc and react/call-services.adoc, and a page title and meta-description to server-push/reactive.adoc. Fixed a "use use" typo in threads.adoc.

Verification

  • Ran the docs locally and checked every internal link and anchor on all 46 changed pages: all resolve. The old Replace H2 URL returns a 301.
  • npm run check-redirects passes.
  • Vale reports nothing new; the remaining warnings were already in the text before this PR.

Not in this PR

The Getting Started tutorial calls LumoUtility.BoxShadow.MEDIUM in its drawer listings. That only works with Lumo and Lumo.UTILITY_STYLESHEET loaded. The quick start uses the same skeleton and its screenshots show Aura, so the shadow is probably a no-op today. Confirming that needs the real skeleton, so it's left for a separate change.

🤖 Generated with Claude Code

…lding Apps and Getting Started

Fixes #6293.

- Describe React views instead of Hilla in the architecture, server push,
  reactive streams, and consistency pages, and in Getting Started.
- State that Building Apps uses Flow views unless stated otherwise, and drop
  the redundant Flow badges.
- Use --vaadin-* base style properties in styling examples, with Aura for
  theme-specific colors and the Lumo equivalent named alongside.
- Define hotswap, live reload, and hot deploy once, and stop claiming hot
  deploy is enabled automatically.
- Move Replace H2 under Persistence with a redirect, fix the Persistence
  order clash, normalize xref styles, and fill front matter gaps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

Preview Deployment

This PR has been deployed for preview.

URL: https://docs-preview-pr-6337.fly.dev

Changed pages

Added content is highlighted in green; removed content is marked in red on each page.

Built from 81ea310

@peholmst peholmst added the target/v25.3 Automatically cherry-pick to the v25.3 branch label Oct 9, 2026
@peholmst
peholmst merged commit 6fce5e6 into main Oct 9, 2026
11 checks passed
@peholmst
peholmst deleted the claude/vaadin-docs-6293-fd561d branch October 9, 2026 11:22
peholmst added a commit that referenced this pull request Oct 9, 2026
…lding Apps and Getting Started (#6337) (CP: v25.3) (#6340)

Co-authored-by: Petter Holmström <petter@vaadin.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cherry-picked-v25.3 target/v25.3 Automatically cherry-pick to the v25.3 branch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Building Apps: inconsistent Hilla/React terminology, Lumo/Aura token usage, and badges

2 participants