sveltejs · khromov · Sep 28, 2025 · Sep 28, 2025 · Sep 28, 2025 · Sep 28, 2025
diff --git a/documentation/docs/01-introduction/01-overview.md b/documentation/docs/01-introduction/01-overview.md
@@ -1,5 +1,6 @@
 ---
 title: Overview
+use_cases: "always: understanding Svelte fundamentals, component-based architecture, reactive UI framework basics"
 ---
 
 Svelte is a framework for building user interfaces on the web. It uses a compiler to turn declarative components written in HTML, CSS and JavaScript...

diff --git a/documentation/docs/01-introduction/02-getting-started.md b/documentation/docs/01-introduction/02-getting-started.md
@@ -1,5 +1,6 @@
 ---
 title: Getting started
+use_cases: "always: project setup, creating new Svelte apps, configuring build tools, initial development environment"
 ---
 
 We recommend using [SvelteKit](../kit), which lets you [build almost anything](../kit/project-types). It's the official application framework from the Svelte team and powered by [Vite](https://vite.dev/). Create a new project with:

diff --git a/documentation/docs/01-introduction/03-svelte-files.md b/documentation/docs/01-introduction/03-svelte-files.md
@@ -1,5 +1,6 @@
 ---
 title: .svelte files
+use_cases: "always: component structure, organizing HTML/CSS/JavaScript, single-file components, component templates"
 ---
 
 Components are the building blocks of Svelte applications. They are written into `.svelte` files, using a superset of HTML.

diff --git a/documentation/docs/01-introduction/04-svelte-js-files.md b/documentation/docs/01-introduction/04-svelte-js-files.md
@@ -1,5 +1,6 @@
 ---
 title: .svelte.js and .svelte.ts files
+use_cases: "reusable reactive logic, shared state modules, composable reactive utilities, reactive helper functions"
 ---
 
 Besides `.svelte` files, Svelte also operates on `.svelte.js` and `.svelte.ts` files.

diff --git a/documentation/docs/02-runes/01-what-are-runes.md b/documentation/docs/02-runes/01-what-are-runes.md
@@ -1,5 +1,6 @@
 ---
 title: What are runes?
+use_cases: "always: understanding Svelte 5 reactivity, reactive primitives, modern Svelte syntax"
 ---
 
 > [!NOTE] **rune** /ruːn/ _noun_

diff --git a/documentation/docs/02-runes/02-$state.md b/documentation/docs/02-runes/02-$state.md
@@ -1,5 +1,6 @@
 ---
 title: $state
+use_cases: "always: reactive variables, component state management, form inputs, counters, toggles, data models"
 ---
 
 The `$state` rune allows you to create _reactive state_, which means that your UI _reacts_ when it changes.

diff --git a/documentation/docs/02-runes/03-$derived.md b/documentation/docs/02-runes/03-$derived.md
@@ -1,5 +1,6 @@
 ---
 title: $derived
+use_cases: "computed values, calculated properties, derived state, reactive expressions, data transformations"
 ---
 
 Derived state is declared with the `$derived` rune:

diff --git a/documentation/docs/02-runes/04-$effect.md b/documentation/docs/02-runes/04-$effect.md
@@ -1,5 +1,6 @@
 ---
 title: $effect
+use_cases: "side effects, API calls, DOM manipulation, third-party library integration, analytics, canvas drawing, websockets"
 ---
 
 Effects are functions that run when state updates, and can be used for things like calling third-party libraries, drawing on `<canvas>` elements, or making network requests. They only run in the browser, not during server-side rendering.

diff --git a/documentation/docs/02-runes/05-$props.md b/documentation/docs/02-runes/05-$props.md
@@ -1,5 +1,6 @@
 ---
 title: $props
+use_cases: "always: component inputs, parent-child communication, prop validation, default values, component APIs"
 ---
 
 The inputs to a component are referred to as _props_, which is short for _properties_. You pass props to components just like you pass attributes to elements:

diff --git a/documentation/docs/02-runes/06-$bindable.md b/documentation/docs/02-runes/06-$bindable.md
@@ -1,5 +1,6 @@
 ---
 title: $bindable
+use_cases: "two-way binding, form components, controlled inputs, synchronized state, custom input components"
 ---
 
 Ordinarily, props go one way, from parent to child. This makes it easy to understand how data flows around your app.

diff --git a/documentation/docs/02-runes/07-$inspect.md b/documentation/docs/02-runes/07-$inspect.md
@@ -1,5 +1,6 @@
 ---
 title: $inspect
+use_cases: "development only: debugging reactive state, logging state changes, development tools"
 ---
 
 > [!NOTE] `$inspect` only works during development. In a production build it becomes a noop.

diff --git a/documentation/docs/02-runes/08-$host.md b/documentation/docs/02-runes/08-$host.md
@@ -1,5 +1,6 @@
 ---
 title: $host
+use_cases: "web components, custom elements, dispatching custom events, component libraries"
 ---
 
 When compiling a component as a [custom element](custom-elements), the `$host` rune provides access to the host element, allowing you to (for example) dispatch custom events ([demo](/playground/untitled#H4sIAAAAAAAAE41Ry2rDMBD8FSECtqkTt1fHFpSSL-ix7sFRNkTEXglrnTYY_3uRlDgxTaEHIfYxs7szA9-rBizPPwZOZwM89wmecqxbF70as7InaMjltrWFR3mpkQDJ8pwXVnbKkKiwItUa3RGLVtk7gTHQXRDR2lXda4CY1D0SK9nCUk0QPyfrCovsRoNFe17aQOAwGncgO2gBqRzihJXiQrEs2csYOhQ-7HgKHaLIbpRhhBG-I2eD_8ciM4KnnOCbeE5dD2P6h0Dz0-Yi_arNhPLJXBtSGi2TvSXdbpqwdsXvjuYsC1veabvvUTog2ylrapKH2G2XsMFLS4uDthQnq2t1cwKkGOGLvYU5PvaQxLsxOkPmsm97Io1Mo2yUPF6VnOZFkw1RMoopKLKAE_9gmGxyDFMwMcwN-Bx_ABXQWmOtAgAA)):

diff --git a/documentation/docs/03-template-syntax/01-basic-markup.md b/documentation/docs/03-template-syntax/01-basic-markup.md
@@ -1,5 +1,6 @@
 ---
 title: Basic markup
+use_cases: "always: HTML templates, component structure, attributes, events, text interpolation"
 ---
 
 Markup inside a Svelte component can be thought of as HTML++.

diff --git a/documentation/docs/03-template-syntax/02-if.md b/documentation/docs/03-template-syntax/02-if.md
@@ -1,5 +1,6 @@
 ---
 title: {#if ...}
+use_cases: "conditional rendering, showing/hiding elements, user permissions, feature flags, loading states"
 ---
 
 ```svelte

diff --git a/documentation/docs/03-template-syntax/03-each.md b/documentation/docs/03-template-syntax/03-each.md
@@ -1,5 +1,6 @@
 ---
 title: {#each ...}
+use_cases: "lists, arrays, iterations, product listings, user lists, data tables, galleries, menus"
 ---
 
 ```svelte

diff --git a/documentation/docs/03-template-syntax/04-key.md b/documentation/docs/03-template-syntax/04-key.md
@@ -1,5 +1,6 @@
 ---
 title: {#key ...}
+use_cases: "forcing re-renders, resetting component state, animations on value change"
 ---
 
 ```svelte

diff --git a/documentation/docs/03-template-syntax/05-await.md b/documentation/docs/03-template-syntax/05-await.md
@@ -1,5 +1,6 @@
 ---
 title: {#await ...}
+use_cases: "async data fetching, loading states, error handling, API calls, promises"
 ---
 
 ```svelte

diff --git a/documentation/docs/03-template-syntax/06-snippet.md b/documentation/docs/03-template-syntax/06-snippet.md
@@ -1,5 +1,6 @@
 ---
 title: {#snippet ...}
+use_cases: "reusable markup, component composition, render props, slot alternatives, template patterns"
 ---
 
 ```svelte

diff --git a/documentation/docs/03-template-syntax/[email protected] b/documentation/docs/03-template-syntax/[email protected]
@@ -1,5 +1,6 @@
 ---
 title: {@render ...}
+use_cases: "rendering snippets, dynamic content, component composition"
 ---
 
 To render a [snippet](snippet), use a `{@render ...}` tag.

diff --git a/documentation/docs/03-template-syntax/[email protected] b/documentation/docs/03-template-syntax/[email protected]
@@ -1,5 +1,6 @@
 ---
 title: {@html ...}
+use_cases: "raw HTML rendering, CMS content, markdown rendering, rich text, third-party HTML"
 ---
 
 To inject raw HTML into your component, use the `{@html ...}` tag:

diff --git a/documentation/docs/03-template-syntax/[email protected] b/documentation/docs/03-template-syntax/[email protected]
@@ -1,5 +1,6 @@
 ---
 title: {@attach ...}
+use_cases: "DOM manipulation, third-party libraries, tooltips, popovers, advanced interactions"
 ---
 
 Attachments are functions that run in an [effect]($effect) when an element is mounted to the DOM or when [state]($state) read inside the function updates.

diff --git a/documentation/docs/03-template-syntax/[email protected] b/documentation/docs/03-template-syntax/[email protected]
@@ -1,5 +1,6 @@
 ---
 title: {@const ...}
+use_cases: "template calculations, local variables in loops, derived values in blocks"
 ---
 
 The `{@const ...}` tag defines a local constant.

diff --git a/documentation/docs/03-template-syntax/[email protected] b/documentation/docs/03-template-syntax/[email protected]
@@ -1,5 +1,6 @@
 ---
 title: {@debug ...}
+use_cases: "development only: debugging templates, inspecting values, troubleshooting"
 ---
 
 The `{@debug ...}` tag offers an alternative to `console.log(...)`. It logs the values of specific variables whenever they change, and pauses code execution if you have devtools open.

diff --git a/documentation/docs/03-template-syntax/12-bind.md b/documentation/docs/03-template-syntax/12-bind.md
@@ -1,5 +1,6 @@
 ---
 title: bind:
+use_cases: "forms, inputs, two-way binding, checkboxes, selects, textareas, media elements, dimensions"
 ---
 
 Data ordinarily flows down, from parent to child. The `bind:` directive allows data to flow the other way, from child to parent.

diff --git a/documentation/docs/03-template-syntax/13-use.md b/documentation/docs/03-template-syntax/13-use.md
@@ -1,5 +1,6 @@
 ---
 title: use:
+use_cases: "third-party integrations, DOM libraries, custom directives, legacy code integration"
 ---
 
 > [!NOTE]

diff --git a/documentation/docs/03-template-syntax/14-transition.md b/documentation/docs/03-template-syntax/14-transition.md
@@ -1,5 +1,6 @@
 ---
 title: transition:
+use_cases: "animations, page transitions, element enter/leave effects, smooth UI changes"
 ---
 
 A _transition_ is triggered by an element entering or leaving the DOM as a result of a state change.

diff --git a/documentation/docs/03-template-syntax/15-in-and-out.md b/documentation/docs/03-template-syntax/15-in-and-out.md
@@ -1,5 +1,6 @@
 ---
 title: in: and out:
+use_cases: "asymmetric animations, different enter/exit effects, one-way transitions"
 ---
 
 The `in:` and `out:` directives are identical to [`transition:`](transition), except that the resulting transitions are not bidirectional — an `in` transition will continue to 'play' alongside the `out` transition, rather than reversing, if the block is outroed while the transition is in progress. If an out transition is aborted, transitions will restart from scratch.

diff --git a/documentation/docs/03-template-syntax/16-animate.md b/documentation/docs/03-template-syntax/16-animate.md
@@ -1,5 +1,6 @@
 ---
 title: animate:
+use_cases: "list reordering animations, drag and drop, sortable lists, smooth transitions"
 ---
 
 An animation is triggered when the contents of a [keyed each block](each#Keyed-each-blocks) are re-ordered. Animations do not run when an element is added or removed, only when the index of an existing data item within the each block changes. Animate directives must be on an element that is an _immediate_ child of a keyed each block.

diff --git a/documentation/docs/03-template-syntax/17-style.md b/documentation/docs/03-template-syntax/17-style.md
@@ -1,5 +1,6 @@
 ---
 title: style:
+use_cases: "dynamic styles, inline CSS, responsive design, theming, style calculations"
 ---
 
 The `style:` directive provides a shorthand for setting multiple styles on an element.

diff --git a/documentation/docs/03-template-syntax/18-class.md b/documentation/docs/03-template-syntax/18-class.md
@@ -1,5 +1,6 @@
 ---
 title: class
+use_cases: "dynamic CSS classes, conditional styling, state-based styles, utility classes"
 ---
 
 There are two ways to set classes on elements: the `class` attribute, and the `class:` directive.

diff --git a/documentation/docs/03-template-syntax/19-await-expressions.md b/documentation/docs/03-template-syntax/19-await-expressions.md
@@ -1,5 +1,6 @@
 ---
 title: await
+use_cases: "async components, SSR with async data, synchronized UI updates, data fetching"
 ---
 
 As of Svelte 5.36, you can use the `await` keyword inside your components in three places where it was previously unavailable:

diff --git a/documentation/docs/04-styling/01-scoped-styles.md b/documentation/docs/04-styling/01-scoped-styles.md
@@ -1,5 +1,6 @@
 ---
 title: Scoped styles
+use_cases: "always: component-specific styles, CSS encapsulation, preventing style conflicts"
 ---
 
 Svelte components can include a `<style>` element containing CSS that belongs to the component. This CSS is _scoped_ by default, meaning that styles will not apply to any elements on the page outside the component in question.

diff --git a/documentation/docs/04-styling/02-global-styles.md b/documentation/docs/04-styling/02-global-styles.md
@@ -1,5 +1,6 @@
 ---
 title: Global styles
+use_cases: "app-wide styles, CSS resets, typography, third-party CSS integration"
 ---
 
 ## :global(...)

diff --git a/documentation/docs/04-styling/03-custom-properties.md b/documentation/docs/04-styling/03-custom-properties.md
@@ -1,5 +1,6 @@
 ---
 title: Custom properties
+use_cases: "theming, design tokens, dynamic CSS variables, component customization"
 ---
 
 You can pass CSS custom properties — both static and dynamic — to components:

diff --git a/documentation/docs/04-styling/04-nested-style-elements.md b/documentation/docs/04-styling/04-nested-style-elements.md
@@ -1,5 +1,6 @@
 ---
 title: Nested <style> elements
+use_cases: "dynamic runtime styles, conditional CSS, user-generated styles"
 ---
 
 There can only be one top-level `<style>` tag per component.

diff --git a/documentation/docs/05-special-elements/01-svelte-boundary.md b/documentation/docs/05-special-elements/01-svelte-boundary.md
@@ -1,5 +1,6 @@
 ---
 title: <svelte:boundary>
+use_cases: "error boundaries, async loading states, error handling, resilient UIs"
 ---
 
 ```svelte

diff --git a/documentation/docs/05-special-elements/02-svelte-window.md b/documentation/docs/05-special-elements/02-svelte-window.md
@@ -1,5 +1,6 @@
 ---
 title: <svelte:window>
+use_cases: "window events, scroll handling, keyboard shortcuts, resize detection, online/offline"
 ---
 
 ```svelte

diff --git a/documentation/docs/05-special-elements/03-svelte-document.md b/documentation/docs/05-special-elements/03-svelte-document.md
@@ -1,5 +1,6 @@
 ---
 title: <svelte:document>
+use_cases: "document events, visibility changes, fullscreen handling, global clicks"
 ---
 
 ```svelte

diff --git a/documentation/docs/05-special-elements/04-svelte-body.md b/documentation/docs/05-special-elements/04-svelte-body.md
@@ -1,5 +1,6 @@
 ---
 title: <svelte:body>
+use_cases: "body events, mouse enter/leave, global interactions, body classes"
 ---
 
 ```svelte

diff --git a/documentation/docs/05-special-elements/05-svelte-head.md b/documentation/docs/05-special-elements/05-svelte-head.md
@@ -1,5 +1,6 @@
 ---
 title: <svelte:head>
+use_cases: "SEO, meta tags, page titles, OpenGraph, structured data, external scripts"
 ---
 
 ```svelte

diff --git a/documentation/docs/05-special-elements/06-svelte-element.md b/documentation/docs/05-special-elements/06-svelte-element.md
@@ -1,5 +1,6 @@
 ---
 title: <svelte:element>
+use_cases: "dynamic HTML elements, CMS rendering, configurable components, polymorphic components"
 ---
 
 ```svelte

diff --git a/documentation/docs/05-special-elements/07-svelte-options.md b/documentation/docs/05-special-elements/07-svelte-options.md
@@ -1,5 +1,6 @@
 ---
 title: <svelte:options>
+use_cases: "component configuration, custom elements setup, compiler options, namespace settings"
 ---
 
 ```svelte

diff --git a/documentation/docs/06-runtime/01-stores.md b/documentation/docs/06-runtime/01-stores.md
@@ -1,5 +1,6 @@
 ---
 title: Stores
+use_cases: "reactive state management, cross-component state, async data streams, RxJS patterns"
 ---
 
 <!-- - how to use

diff --git a/documentation/docs/06-runtime/02-context.md b/documentation/docs/06-runtime/02-context.md
@@ -1,5 +1,6 @@
 ---
 title: Context
+use_cases: "component communication, dependency injection, avoiding prop drilling, theme providers"
 ---
 
 Context allows components to access values owned by parent components without passing them down as props (potentially through many layers of intermediate components, known as 'prop-drilling'). The parent component sets context with `setContext(key, value)`...

diff --git a/documentation/docs/06-runtime/03-lifecycle-hooks.md b/documentation/docs/06-runtime/03-lifecycle-hooks.md
@@ -1,5 +1,6 @@
 ---
 title: Lifecycle hooks
+use_cases: "initialization logic, cleanup, DOM access, third-party library setup"
 ---
 
 <!-- - onMount/onDestroy

diff --git a/documentation/docs/06-runtime/04-imperative-component-api.md b/documentation/docs/06-runtime/04-imperative-component-api.md
@@ -1,5 +1,6 @@
 ---
 title: Imperative component API
+use_cases: "programmatic component control, testing, framework integration, dynamic component creation"
 ---
 
 <!-- better title needed?

diff --git a/documentation/docs/07-misc/02-testing.md b/documentation/docs/07-misc/02-testing.md
@@ -1,5 +1,6 @@
 ---
 title: Testing
+use_cases: "unit testing, integration testing, E2E testing, test-driven development, CI/CD"
 ---
 
 Testing helps you write and maintain your code and guard against regressions. Testing frameworks help you with that, allowing you to describe assertions or expectations about how your code should behave. Svelte is unopinionated about which testing framework you use — you can write unit tests, integration tests, and end-to-end tests using solutions like [Vitest](https://vitest.dev/), [Jasmine](https://jasmine.github.io/), [Cypress](https://www.cypress.io/) and [Playwright](https://playwright.dev/).

diff --git a/documentation/docs/07-misc/03-typescript.md b/documentation/docs/07-misc/03-typescript.md
@@ -1,5 +1,6 @@
 ---
 title: TypeScript
+use_cases: "type safety, IDE support, component APIs, prop validation, large applications"
 ---
 
 <!-- - [basically what we have today](https://svelte.dev/docs/typescript)

diff --git a/documentation/docs/07-misc/04-custom-elements.md b/documentation/docs/07-misc/04-custom-elements.md
@@ -1,5 +1,6 @@
 ---
 title: Custom elements
+use_cases: "web components, framework-agnostic components, micro-frontends, design systems"
 ---
 
 <!-- - [basically what we have today](https://svelte.dev/docs/custom-elements-api) -->

diff --git a/documentation/docs/07-misc/06-v4-migration-guide.md b/documentation/docs/07-misc/06-v4-migration-guide.md
@@ -1,5 +1,6 @@
 ---
 title: Svelte 4 migration guide
+use_cases: "upgrading from Svelte 3, migration, breaking changes, version updates"
 ---
 
 This migration guide provides an overview of how to migrate from Svelte version 3 to 4. See the linked PRs for more details about each change. Use the migration script to migrate some of these automatically: `npx svelte-migrate@latest svelte-4`

diff --git a/documentation/docs/07-misc/99-faq.md b/documentation/docs/07-misc/99-faq.md
@@ -1,5 +1,6 @@
 ---
 title: Frequently asked questions
+use_cases: "troubleshooting, best practices, common questions, learning resources"
 ---
 
 ## I'm new to Svelte. Where should I start?

diff --git a/documentation/docs/98-reference/20-svelte.md b/documentation/docs/98-reference/20-svelte.md
@@ -1,5 +1,6 @@
 ---
 title: svelte
+use_cases: "always: main API reference, core functions, component utilities"
 ---
 
 > MODULE: svelte
diff --git a/documentation/docs/98-reference/21-svelte-action.md b/documentation/docs/98-reference/21-svelte-action.md
@@ -1,5 +1,6 @@
 ---
 title: svelte/action
+use_cases: "legacy actions, DOM manipulation, typing actions"
 ---
 
 This module provides types for [actions](use), which have been superseded by [attachments](@attach).

diff --git a/documentation/docs/98-reference/21-svelte-animate.md b/documentation/docs/98-reference/21-svelte-animate.md
@@ -1,5 +1,6 @@
 ---
 title: svelte/animate
+use_cases: "flip animations, list transitions, keyed blocks"
 ---
 
 > MODULE: svelte/animate
diff --git a/documentation/docs/98-reference/21-svelte-attachments.md b/documentation/docs/98-reference/21-svelte-attachments.md
@@ -1,5 +1,6 @@
 ---
 title: svelte/attachments
+use_cases: "DOM manipulation, third-party libraries, modern alternative to actions"
 ---
 
 > MODULE: svelte/attachments
diff --git a/documentation/docs/98-reference/21-svelte-compiler.md b/documentation/docs/98-reference/21-svelte-compiler.md
@@ -1,5 +1,6 @@
 ---
 title: svelte/compiler
+use_cases: "build tools, preprocessors, custom compilation, bundler plugins"
 ---
 
 > MODULE: svelte/compiler
diff --git a/documentation/docs/98-reference/21-svelte-easing.md b/documentation/docs/98-reference/21-svelte-easing.md
@@ -1,5 +1,6 @@
 ---
 title: svelte/easing
+use_cases: "animation curves, transition timing, smooth animations"
 ---
 
 > MODULE: svelte/easing