Skip to content

docs(core): improve Signals conceptual guidance#69204

Open
LuEsc wants to merge 4 commits into
angular:mainfrom
LuEsc:docs/signals-mental-model
Open

docs(core): improve Signals conceptual guidance#69204
LuEsc wants to merge 4 commits into
angular:mainfrom
LuEsc:docs/signals-mental-model

Conversation

@LuEsc
Copy link
Copy Markdown

@LuEsc LuEsc commented Jun 6, 2026

PR Checklist

Please check if your PR fulfills the following requirements:

PR Type

What kind of change does this PR introduce?

  • Bugfix
  • Feature
  • Code style update (formatting, local variables)
  • Refactoring (no functional changes, no api changes)
  • Build related changes
  • CI related changes
  • Documentation content changes
  • angular.dev application / infrastructure changes
  • Other... Please describe:

What is the current behavior?

The Signals overview guide explains the core APIs and reactive concepts, but it provides limited guidance on how to reason about Signals when designing applications.

In particular, the guide does not clearly explain:

  • The mental model behind Signals as a reactive state graph.
  • When to use computed versus effect.
  • Why derived state should generally be modeled with computed.
  • The conceptual distinction between Signals and RxJS.

Issue Number: N/A

What is the new behavior?

This PR adds conceptual guidance to the Signals overview guide, including:

A new "Mental model" section.
Guidance on preferring derivation over synchronization.
Recommendations for choosing between computed and effect.
A conceptual comparison between Signals and RxJS focused on use cases rather than APIs.

The goal is to help developers adopt the Signals programming model more effectively and avoid common architectural misunderstandings.

Does this PR introduce a breaking change?

  • Yes
  • No

Other information

This is a documentation-only change.

@pullapprove pullapprove Bot requested a review from atscott June 6, 2026 02:41
@google-cla

This comment was marked as outdated.

@angular-robot angular-robot Bot added area: docs Related to the documentation area: core Issues related to the framework runtime labels Jun 6, 2026
@ngbot ngbot Bot added this to the Backlog milestone Jun 6, 2026
@atscott atscott requested review from bencodezen and removed request for atscott June 6, 2026 19:00
Comment thread adev/src/content/guide/signals/overview.md Outdated
Comment thread adev/src/content/guide/signals/overview.md Outdated
Comment thread adev/src/content/guide/signals/overview.md Outdated
Copy link
Copy Markdown
Contributor

@bencodezen bencodezen left a comment

Choose a reason for hiding this comment

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

Thanks for the PR @LuEsc! There is a larger effort to rewrite the signal guides since there is a lot going on especially in the overview section. That said, this is good guidance to have for now. I've added some suggestions to improve what you wrote. Please let me know if you have any questions!

LuEsc and others added 3 commits June 8, 2026 14:04
Co-authored-by: Ben Hong <ben@bencodezen.io>
Co-authored-by: Ben Hong <ben@bencodezen.io>
Co-authored-by: Ben Hong <ben@bencodezen.io>
@LuEsc LuEsc force-pushed the docs/signals-mental-model branch from 5364583 to 4ee07e6 Compare June 8, 2026 19:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: core Issues related to the framework runtime area: docs Related to the documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants