Skip to content

Revamp the essential style guide and mark others as legacy#3370

Open
haoqunjiang wants to merge 3 commits intovuejs:mainfrom
haoqunjiang:revamp-essential-style-guide
Open

Revamp the essential style guide and mark others as legacy#3370
haoqunjiang wants to merge 3 commits intovuejs:mainfrom
haoqunjiang:revamp-essential-style-guide

Conversation

@haoqunjiang
Copy link
Member

This PR updates the Style Guide in a deliberately narrow way instead of attempting a full rewrite.

The diff:

  • rewrites Priority A: Essential around a small set of human-facing Vue 3 rules
  • updates the style guide overview to reflect that narrower scope
  • marks Priority B, C, and D as legacy reference content
  • removes the old keyed v-for and v-if with v-for entries from the essential section and leaves those checks to tooling
  • drops multi-word-component-names from the essential section
  • does not rewrite Priority B, C, or D beyond legacy notices
  • does not bring the style guide back to the top nav yet, since this PR only revises the essential section

The essential rules in this draft are:

  • Use detailed prop definitions
  • Declare emitted events (new)
  • Keep parent-child data flow explicit (new)
  • Use component-scoped styling
  • Use computed for derived state; use watchers/effects/hooks for side effects (new)

Taken together, these rules define the core boundaries of a Vue component: its contract, its communication model, its styling boundary, and its reactive semantics.

Why This Direction

I think the guide should stay small, stable, and principle-driven, and leave mechanical concerns to tooling.

In practice, that means:

  • keeping the guide small enough that a volunteer team can realistically review and maintain it
  • preferring durable rules over a large set of detailed conventions that may age quickly
  • leaving automatable rules to tools, which are easier to update than the guide itself

This is also partly motivated by vuejs/eslint-plugin-vue#3060: the outdated guide is starting to create friction for tooling and keeps outdated rules in circulation.

It is also informed by the last large style guide revamp attempt in vuejs/v2.vuejs.org#2839, where the scope was broad enough that review became difficult to finish.

@netlify
Copy link

netlify bot commented Mar 19, 2026

Deploy Preview for vuejs ready!

Name Link
🔨 Latest commit 3575ca0
🔍 Latest deploy log https://app.netlify.com/projects/vuejs/deploys/69bc0f26b0728200088b7ff9
😎 Deploy Preview https://deploy-preview-3370--vuejs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@ubugeeei
Copy link
Member

I'll definitely check it!

And every team members should check also!
/cc @vuejs/active-team-members @vuejs/core-committers

@ubugeeei
Copy link
Member

And since these are important changes, they should ultimately be decided by @yyx990803

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.

2 participants