diff --git a/src/style-guide/index.md b/src/style-guide/index.md
index 8f7b747f60..714d0c14ba 100644
--- a/src/style-guide/index.md
+++ b/src/style-guide/index.md
@@ -4,42 +4,46 @@ outline: deep
# Style Guide {#style-guide}
-::: warning Note
-This Vue.js Style Guide is outdated and needs to be reviewed. If you have any questions or suggestions, please [open an issue](https://github.com/vuejs/docs/issues/new).
+::: warning Status
+This section is under active revision. Priority A: Essential is currently the maintained section of the guide. Priority B, C, and D are retained as legacy reference content.
:::
-This is the official style guide for Vue-specific code. If you use Vue in a project, it's a great reference to avoid errors, bikeshedding, and anti-patterns. However, we don't believe that any style guide is ideal for all teams or projects, so mindful deviations are encouraged based on past experience, the surrounding tech stack, and personal values.
+This is the official style guide for Vue-specific code. It is meant to help teams make sound architectural, semantic, and maintainability decisions in modern Vue applications. However, no style guide is ideal for every team or project, so mindful deviations are still encouraged when they are deliberate and well understood.
-For the most part, we also avoid suggestions about JavaScript or HTML in general. We don't mind whether you use semicolons or trailing commas. We don't mind whether your HTML uses single-quotes or double-quotes for attribute values. Some exceptions will exist however, where we've found that a particular pattern is helpful in the context of Vue.
+This guide focuses on a small set of human-facing Vue rules. It is not intended to mirror every rule that lint tooling may enforce. Tools such as [eslint-plugin-vue](https://eslint.vuejs.org/), formatters, and other static analysis can still cover broader mechanical correctness and consistency checks.
-Finally, we've split rules into four categories:
+For the most part, we avoid suggestions about JavaScript or HTML in general. We will not set explicit guidelines around formatting decisions like semicolons, quote styles, etc. These are decisions that are personal to each team and we recommend setting your own conventions with tools like [Prettier](https://prettier.io/) or [Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html).
+
+Our goal is to provide guidance around patterns that are important within the context of Vue.
+
+## How to use this guide {#how-to-use-this-guide}
+
+- Start with the [essential rules](./rules-essential). They are the primary maintained part of this guide and focus on component contracts, explicit data flow, component boundaries, and the Vue mental model.
+- Treat Priority B, C, and D as legacy reference pages. They may still contain useful conventions, but they are not part of the current maintained scope.
+- If your team uses [eslint-plugin-vue](https://eslint.vuejs.org/), expect tooling to enforce additional syntax, correctness, and consistency rules that are not all repeated here.
## Rule Categories {#rule-categories}
-### Priority A: Essential (Error Prevention) {#priority-a-essential-error-prevention}
+### Priority A: Essential (Maintained) {#priority-a-essential-error-prevention}
-These rules help prevent errors, so learn and abide by them at all costs. Exceptions may exist, but should be very rare and only be made by those with expert knowledge of both JavaScript and Vue.
+These rules focus on component contracts, explicit data flow, component boundaries, and the Vue mental model. They are written to guide human decisions, not to duplicate every lint rule.
- [See all priority A rules](./rules-essential)
-### Priority B: Strongly Recommended {#priority-b-strongly-recommended}
+### Priority B: Strongly Recommended (Legacy Reference) {#priority-b-strongly-recommended}
-These rules have been found to improve readability and/or developer experience in most projects. Your code will still run if you violate them, but violations should be rare and well-justified.
+This page is preserved for historical reference. Its recommendations may still be useful, but they are not part of the current maintained scope.
- [See all priority B rules](./rules-strongly-recommended)
-### Priority C: Recommended {#priority-c-recommended}
-
-Where multiple, equally good options exist, an arbitrary choice can be made to ensure consistency. In these rules, we describe each acceptable option and suggest a default choice. That means you can feel free to make a different choice in your own codebase, as long as you're consistent and have a good reason. Please do have a good reason though! By adapting to the community standard, you will:
+### Priority C: Recommended (Legacy Reference) {#priority-c-recommended}
-1. Train your brain to more easily parse most of the community code you encounter
-2. Be able to copy and paste most community code examples without modification
-3. Often find new hires are already accustomed to your preferred coding style, at least in regards to Vue
+This page is also preserved as legacy reference content. It may help teams that want additional conventions, but it is not part of the current maintained scope.
- [See all priority C rules](./rules-recommended)
-### Priority D: Use with Caution {#priority-d-use-with-caution}
+### Priority D: Use with Caution (Legacy Reference) {#priority-d-use-with-caution}
-Some features of Vue exist to accommodate rare edge cases or smoother migrations from a legacy code base. When overused however, they can make your code more difficult to maintain or even become a source of bugs. These rules shine a light on potentially risky features, describing when and why they should be avoided.
+This page remains available as historical guidance on risky patterns, but it is not part of the current maintained scope.
- [See all priority D rules](./rules-use-with-caution)
diff --git a/src/style-guide/rules-essential.md b/src/style-guide/rules-essential.md
index 0872dc499e..0c59ca6229 100644
--- a/src/style-guide/rules-essential.md
+++ b/src/style-guide/rules-essential.md
@@ -1,51 +1,16 @@
# Priority A Rules: Essential {#priority-a-rules-essential}
-::: warning Note
-This Vue.js Style Guide is outdated and needs to be reviewed. If you have any questions or suggestions, please [open an issue](https://github.com/vuejs/docs/issues/new).
-:::
-
-These rules help prevent errors, so learn and abide by them at all costs. Exceptions may exist, but should be very rare and only be made by those with expert knowledge of both JavaScript and Vue.
-
-## Use multi-word component names {#use-multi-word-component-names}
-
-User component names should always be multi-word, except for root `App` components. This [prevents conflicts](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name) with existing and future HTML elements, since all HTML elements are a single word.
-
-
-
Bad
-
-```vue-html
-
-
-
-
-
-```
-
-
-
-
-
Good
-
-```vue-html
-
-
-
-
-
-```
-
-
+These rules define the most important boundaries in Vue components: what a component exposes, how data flows through it, how its styles are contained, and how derived state is kept separate from side effects. Follow them by default to keep components easier to understand, maintain, and evolve.
## Use detailed prop definitions {#use-detailed-prop-definitions}
-In committed code, prop definitions should always be as detailed as possible, specifying at least type(s).
+In committed code, props should be treated as a key part of the component's contract and be defined in as much detail as possible.
-::: details Detailed Explanation
-Detailed [prop definitions](/guide/components/props#prop-validation) have two advantages:
+::: details Why this matters
+Detailed [prop definitions](/guide/components/props#prop-validation) make a component's API easier to understand, easier to use correctly, and easier to change safely.
+:::
-- They document the API of the component, so that it's easy to see how the component is meant to be used.
-- In development, Vue will warn you if a component is ever provided incorrectly formatted props, helping you catch potential sources of error.
- :::
+In TypeScript, a type-based `defineProps()` declaration can also be used when the prop contract is fully described by its types.
-## Use keyed `v-for` {#use-keyed-v-for}
+## Declare emitted events {#declare-emitted-events}
+
+Treat emitted events as part of a component's public contract, and declare them explicitly.
+
+::: details Why this matters
+Explicit [event declarations](/guide/components/events) document how a component communicates outward and make parent-child interactions easier to follow.
+:::
+
+In Options API, declare events with the [`emits`](/guide/components/events#declaring-emitted-events) option. In [`
+
+
+
+
```
-
+```vue
+
-**Never use `v-if` on the same element as `v-for`.**
+
+
+
+```
-There are two common cases where this can be tempting:
+
-- To filter items in a list (e.g. `v-for="user in users" v-if="user.isActive"`). In these cases, replace `users` with a new computed property that returns your filtered list (e.g. `activeUsers`).
+
-- To avoid rendering a list if it should be hidden (e.g. `v-for="user in users" v-if="shouldShowUsers"`). In these cases, move the `v-if` to a container element (e.g. `ul`, `ol`).
+## Keep parent-child data flow explicit {#keep-parent-child-data-flow-explicit}
-::: details Detailed Explanation
-When Vue processes directives, `v-if` has a higher priority than `v-for`, so that this template:
+Pass data down with props, and communicate requested changes back up with emitted events.
-```vue-html
-
-
- {{ user.name }}
-
-
-```
+::: details Why this matters
+Vue components are easier to understand and maintain when state ownership is clear. Prop mutation and other implicit parent-child coupling make updates harder to reason about and components harder to reuse.
+:::
-Will throw an error, because the `v-if` directive will be evaluated first and the iteration variable `user` does not exist at this moment.
+This includes `v-model`, which still follows the same prop-and-event communication pattern with shorthand syntax.
-This could be fixed by iterating over a computed property instead, like this:
+If a child needs editable local state, derive or initialize it from the prop instead of mutating the prop itself.
-## Use component-scoped styling {#use-component-scoped-styling}
-
-For applications, styles in a top-level `App` component and in layout components may be global, but all other components should always be scoped.
-
-This is only relevant for [Single-File Components](/guide/scaling-up/sfc). It does _not_ require that the [`scoped` attribute](https://vue-loader.vuejs.org/guide/scoped-css.html) be used. Scoping could be through [CSS modules](https://vue-loader.vuejs.org/guide/css-modules.html), a class-based strategy such as [BEM](http://getbem.com/), or another library/convention.
-
-**Component libraries, however, should prefer a class-based strategy instead of using the `scoped` attribute.**
+
-This makes overriding internal styles easier, with human-readable class names that don't have too high specificity, but are still very unlikely to result in a conflict.
+## Use component-scoped styling {#use-component-scoped-styling}
-::: details Detailed Explanation
-If you are developing a large project, working with other developers, or sometimes include 3rd-party HTML/CSS (e.g. from Auth0), consistent scoping will ensure that your styles only apply to the components they are meant for.
+Keep component styles within the component boundary unless a style is intentionally global.
-Beyond the `scoped` attribute, using unique class names can help ensure that 3rd-party CSS does not apply to your own HTML. For example, many projects use the `button`, `btn`, or `icon` class names, so even if not using a strategy such as BEM, adding an app-specific and/or component-specific prefix (e.g. `ButtonClose-icon`) can provide some protection.
+::: details Why this matters
+Component-scoped styling reduces accidental coupling, makes style ownership clearer, and lowers the chance that a change in one component will unexpectedly affect another.
:::
@@ -405,22 +354,91 @@ Beyond the `scoped` attribute, using unique class names can help ensure that 3rd
```
-```vue-html
-
-
-
+
diff --git a/src/style-guide/rules-recommended.md b/src/style-guide/rules-recommended.md
index 0ea2695433..57d4992ecd 100644
--- a/src/style-guide/rules-recommended.md
+++ b/src/style-guide/rules-recommended.md
@@ -1,7 +1,7 @@
-# Priority C Rules: Recommended {#priority-c-rules-recommended}
+# Priority C Rules: Recommended (Legacy Reference) {#priority-c-rules-recommended}
-::: warning Note
-This Vue.js Style Guide is outdated and needs to be reviewed. If you have any questions or suggestions, please [open an issue](https://github.com/vuejs/docs/issues/new).
+::: warning Legacy Reference
+This page is retained for historical reference while the style guide is being revamped. It is not part of the current essential-only scope, and its recommendations should not be treated as reaffirmed guidance.
:::
Where multiple, equally good options exist, an arbitrary choice can be made to ensure consistency. In these rules, we describe each acceptable option and suggest a default choice. That means you can feel free to make a different choice in your own codebase, as long as you're consistent and have a good reason. Please do have a good reason though! By adapting to the community standard, you will:
diff --git a/src/style-guide/rules-strongly-recommended.md b/src/style-guide/rules-strongly-recommended.md
index 8b5c910d97..d8a35fad55 100644
--- a/src/style-guide/rules-strongly-recommended.md
+++ b/src/style-guide/rules-strongly-recommended.md
@@ -1,11 +1,47 @@
-# Priority B Rules: Strongly Recommended {#priority-b-rules-strongly-recommended}
+# Priority B Rules: Strongly Recommended (Legacy Reference) {#priority-b-rules-strongly-recommended}
-::: warning Note
-This Vue.js Style Guide is outdated and needs to be reviewed. If you have any questions or suggestions, please [open an issue](https://github.com/vuejs/docs/issues/new).
+::: warning Legacy Reference
+This page is retained for historical reference while the style guide is being revamped. It is not part of the current essential-only scope, and its recommendations should not be treated as reaffirmed guidance.
:::
These rules have been found to improve readability and/or developer experience in most projects. Your code will still run if you violate them, but violations should be rare and well-justified.
+## Use multi-word component names {#use-multi-word-component-names}
+
+**In most projects, user component names should always be multi-word, except for root `App` components.**
+
+This [prevents conflicts](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name) with existing and future HTML elements, since all HTML elements are a single word.
+
+In [Single-File Components](/guide/scaling-up/sfc), string templates, and [JSX](/guide/extras/render-function#jsx-tsx), [PascalCase component tags](#component-name-casing-in-templates) can also help make user components more clearly distinct from native elements. In in-DOM templates, where tags must be kebab-case, that distinction is no longer available, so the case for multi-word names is even stronger.
+
+That said, there can be pragmatic exceptions, such as route components in file-based routing.
+
+
+
Bad
+
+```vue-html
+
+
+
+
+
+```
+
+
+
+
+
Good
+
+```vue-html
+
+
+
+
+
+```
+
+
+
## Component files {#component-files}
**Whenever a build system is available to concatenate files, each component should be in its own file.**
diff --git a/src/style-guide/rules-use-with-caution.md b/src/style-guide/rules-use-with-caution.md
index d8afbc0604..73b0e6a927 100644
--- a/src/style-guide/rules-use-with-caution.md
+++ b/src/style-guide/rules-use-with-caution.md
@@ -1,7 +1,7 @@
-# Priority D Rules: Use with Caution {#priority-d-rules-use-with-caution}
+# Priority D Rules: Use with Caution (Legacy Reference) {#priority-d-rules-use-with-caution}
-::: warning Note
-This Vue.js Style Guide is outdated and needs to be reviewed. If you have any questions or suggestions, please [open an issue](https://github.com/vuejs/docs/issues/new).
+::: warning Legacy Reference
+This page is retained for historical reference while the style guide is being revamped. It is not part of the current essential-only scope, and its recommendations should not be treated as reaffirmed guidance.
:::
Some features of Vue exist to accommodate rare edge cases or smoother migrations from a legacy code base. When overused however, they can make your code more difficult to maintain or even become a source of bugs. These rules shine a light on potentially risky features, describing when and why they should be avoided.