Creates foundation documentation

16/umbraco-cms/customizing/foundation/README.md

@@ -1,39 +1,82 @@
 ---
 description: >-
-  In this section, you will learn about the general framework of Backoffice. How
-  to integrate and communicate and make your own reactive UI.
+  Learn about the core framework of the Umbraco Backoffice, including how to
+  integrate, communicate, and build reactive UIs for your extensions.
 ---
 
 # Foundation
 
-## [Terminology](terminology.md)
+In this section, you will find comprehensive resources about the foundational concepts and tools for building Backoffice extensions. These topics cover everything from basic terminology to advanced patterns for data management and UI development.
 
-Get an overview of the general terms in the Umbraco Backoffice and what they represent.
+## Core Concepts
 
-## [Umbraco Element](umbraco-element/)
+### [Terminology](terminology.md)
 
-The Umbraco element brings what you need to integrate your UI.
+Get an overview of the general terms used in the Umbraco Backoffice and what they represent.
 
-## [Lit Element](lit-element.md)
+### [Umbraco Element](umbraco-element/)
 
-Learn about Lit Element, the Web Component Framework that most examples and most of the Backoffice are based upon.
+The Umbraco Element provides the foundation you need to integrate your custom UI components.
 
-## [Context API](context-api/)
+### [Umbraco Controller](umbraco-controller/)
+
+Contain or reuse logic across elements. Controllers enable you to separate business logic while remaining connected to the element life cycle.
+
+### [Lit Element](lit-element.md)
+
+Learn about Lit Element, the Web Component framework that most examples and the majority of the Backoffice are built upon.
+
+## Communication and Data Management
+
+### [Context API](context-api/)
 
 Learn how to communicate with the rest of the application, whether you want to retrieve data or manipulate it.
 
-## [States — Make reactive UI](states.md)
+### [Contexts](contexts/)
+
+Explore specific context implementations, including the Property Dataset Context that connects Property Editors with Workspaces.
+
+### [Fetching Data](fetching-data/)
+
+Learn how to request data when extending the Backoffice, using either the Fetch API or the Umbraco HTTP Client.
+
+### [Repositories](repositories.md)
+
+Discover how to use repositories to manage data operations in a structured way, abstracting the data access layer for easier maintenance and scalability.
+
+## UI Development
+
+### [States — Make Reactive UI](states.md)
+
+Bring life to your UI by ensuring it stays up to date with the current data through reactive state management.
+
+### [Icons](icons.md)
+
+Learn how to use icons in the Umbraco Backoffice, based on Lucide Icons and Simple Icons.
+
+### [Localization](localization.md)
+
+Discover how to manage and use Backoffice UI localization files to translate your extensions into different languages.
+
+### [Integrate Validation](integrate-validation.md)
+
+Learn how to bind and use the validation system when working with Form Controls and custom Property Editors.
+
+### [Sorting](sorting.md)
+
+Create a UI that users can sort via drag and drop functionality.
+
+### [Routes](routes.md)
 
-Bring life into your UI by ensuring it's up to date with the current data.
+Implement routes in your UI, enabling users to deep link directly into your custom interfaces.
 
-## [Sorting](sorting.md)
+## Additional Resources
 
-Create a UI that the user can sort via Drag and Drop.
+### [Community Resources](https://github.com/umbraco/Umbraco.Packages/tree/main/bellissima)
 
-## [Routes](routes.md)
+An overview of community articles and packages related to the Umbraco Backoffice.
 
-Implements routes into your UI, enabling Users to deep link into your UI.
 
-## [Community Resources](https://github.com/umbraco/Umbraco.Packages/tree/main/bellissima)
+### [Next-Level  Backoffice](https://www.youtube.com/watch?v=P0xxTIlHayg)
 
-An overview of community articles related to the New backoffice "Bellissima".
+Watch Niels Lyngsø's Codegarden 2025 talk about next-level Umbraco Backoffice

17/umbraco-cms/customizing/foundation/README.md

@@ -1,39 +1,81 @@
 ---
 description: >-
-  In this section, you will learn about the general framework of Backoffice. How
-  to integrate and communicate and make your own reactive UI.
+  Learn about the core framework of the Umbraco Backoffice, including how to
+  integrate, communicate, and build reactive UIs for your extensions.
 ---
 
 # Foundation
 
-## [Terminology](terminology.md)
+In this section, you will find comprehensive resources about the foundational concepts and tools for building Backoffice extensions. These topics cover everything from basic terminology to advanced patterns for data management and UI development.
 
-Get an overview of the general terms in the Umbraco Backoffice and what they represent.
+## Core Concepts
 
-## [Umbraco Element](umbraco-element/)
+### [Terminology](terminology.md)
 
-The Umbraco element brings what you need to integrate your UI.
+Get an overview of the general terms used in the Umbraco Backoffice and what they represent.
 
-## [Lit Element](lit-element.md)
+### [Umbraco Element](umbraco-element/)
 
-Learn about Lit Element, the Web Component Framework that most examples and most of the Backoffice are based upon.
+The Umbraco Element provides the foundation you need to integrate your custom UI components.
 
-## [Context API](context-api/)
+### [Umbraco Controller](umbraco-controller/)
+
+Contain or reuse logic across elements. Controllers enable you to separate business logic while remaining connected to the element life cycle.
+
+### [Lit Element](lit-element.md)
+
+Learn about Lit Element, the Web Component framework that most examples and the majority of the Backoffice are built upon.
+
+## Communication and Data Management
+
+### [Context API](context-api/)
 
 Learn how to communicate with the rest of the application, whether you want to retrieve data or manipulate it.
 
-## [States — Make reactive UI](states.md)
+### [Contexts](contexts/)
+
+Explore specific context implementations, including the Property Dataset Context that connects Property Editors with Workspaces.
+
+### [Fetching Data](fetching-data/)
+
+Learn how to request data when extending the Backoffice, using either the Fetch API or the Umbraco HTTP Client.
+
+### [Repositories](repositories/)
+
+Discover how to use repositories to manage data operations in a structured way, abstracting the data access layer for easier maintenance and scalability.
+
+## UI Development
+
+### [States — Make Reactive UI](states.md)
+
+Bring life to your UI by ensuring it stays up to date with the current data through reactive state management.
+
+### [Icons](icons.md)
+
+Learn how to use icons in the Umbraco Backoffice, based on Lucide Icons and Simple Icons.
+
+### [Localization](localization.md)
+
+Discover how to manage and use Backoffice UI localization files to translate your extensions into different languages.
+
+### [Integrate Validation](integrate-validation.md)
+
+Learn how to bind and use the validation system when working with Form Controls and custom Property Editors.
+
+### [Sorting](sorting.md)
+
+Create a UI that users can sort via drag and drop functionality.
 
-Bring life into your UI by ensuring it's up to date with the current data.
+### [Routes](routes.md)
 
-## [Sorting](sorting.md)
+Implement routes in your UI, enabling users to deep link directly into your custom interfaces.
 
-Create a UI that the user can sort via Drag and Drop.
+## Additional Resources
 
-## [Routes](routes.md)
+### [Community Resources](https://github.com/umbraco/Umbraco.Packages/tree/main/bellissima)
 
-Implements routes into your UI, enabling Users to deep link into your UI.
+An overview of community articles and packages related to the Umbraco Backoffice.
 
-## [Community Resources](https://github.com/umbraco/Umbraco.Packages/tree/main/bellissima)
+### [Next-Level  Backoffice](https://www.youtube.com/watch?v=P0xxTIlHayg)
 
-An overview of community articles related to the New backoffice "Bellissima".
+Watch Niels Lyngsø's Codegarden 2025 talk about next-level Umbraco Backoffice

17/umbraco-cms/customizing/foundation/context-api/README.md

@@ -1,9 +1,34 @@
 ---
-description: The Context API is your tool to integrate with the application
+description: >-
+  Learn about using the Context API for sharing data and functionality between
+  backoffice extensions through the component hierarchy.
 ---
 
 # Context API
 
-The Context API enables receiving APIs. Depending on where your code is executed from, it affects which and what instances of APIs can be received. The DOM structure defines the scope of who can gain access to what APIs. This is because the APIs are provided via an element and can then only be consumed by code running on itself or descendant elements.
+The Context API is a powerful communication system in Umbraco's backoffice. It enables extensions to share data and functionality through the component hierarchy without tight coupling. Think of it as a way for different parts of your UI to talk to each other and access shared services.
 
-##
+Contexts are used throughout the Umbraco backoffice to provide access to workspace data, notifications, user information, and many other services. When building custom extensions, you will often need to consume existing contexts or create your own to share functionality between your components.
+
+## Key Concepts
+
+The Context API is built on a few core principles:
+
+* **Provider-Consumer Pattern**: Parent elements provide contexts that descendant elements can consume
+* **Loose Coupling**: Components don't need direct references to each other
+* **Hierarchical**: Contexts flow down through the DOM tree
+* **Type-Safe**: Context Tokens ensure you get the right context
+
+The Context API provides a structured way to access and share functionality when building property editors, workspace extensions, dashboards, or any other backoffice UI.
+
+## [Context API Fundamentals](context-api-fundamentals.md)
+
+Learn the core concepts, terminology, and flow mechanisms of the Context API. Understand how contexts are provided and consumed through the element hierarchy, and explore common context types used throughout Umbraco.
+
+## [Consume a Context](consume-a-context.md)
+
+Learn how to consume contexts in your extensions using one-time references or subscriptions. This guide covers consuming contexts in UI elements, services, and non-UI classes, with practical code examples for each scenario.
+
+## [Provide a Context](provide-a-context.md)
+
+Learn how to create and provide your own custom contexts. Make your data and functionality available to descendant elements in the component hierarchy.

17/umbraco-cms/customizing/foundation/context-api/context-api-fundamentals.md

@@ -0,0 +1,74 @@
+---
+description: >-
+  Learn about the Context API fundamentals, terminology, and how it enables
+  communication between elements in the Umbraco backoffice through hierarchy.
+---
+
+# Context API fundamentals
+The Context API is a powerful communication system in Umbraco's backoffice. It enables elements to share data and functionality without tight coupling. This article covers the core concepts, terminology, and flow mechanisms you need to understand before working with contexts.
+
+Whether you're building custom property editors, workspace extensions, or complex UI components, understanding the Context API is essential. It provides a structured way to access shared state, services, and functionality throughout the element hierarchy.
+
+## What is the Context API?
+The Umbraco backoffice is a collection of DOM elements like any web application. Elements can be anything: a button, a property editor, a section, a menu option, or a tree. These elements have a hierarchy and form the entire DOM tree that makes up the Umbraco application.
+
+The Context API in Umbraco is a communication system. It allows elements to share data and functionality through their hierarchy in a `context`. Parent elements can provide contexts that their descendant elements can request and use. 
+
+When an element needs access to some data or functionality, it requests the appropriate context. It does this by using the context's identifier. The system finds the nearest provider up the element hierarchy. This creates loose coupling between elements. Descendants don't need direct references to their dependencies as they can declare what type of context they need and the system handles the connection. 
+
+This approach is similar to dependency injection in managing dependencies automatically. However, the Context API works specifically through the element structure rather than a central container. For example, a custom property editor can request the `workspace context` to access information about the current document. Information that can be accessed includes the document's name, content type, or publication status.
+
+The Context API exists to solve common problems in complex user interfaces:
+
+* Avoiding prop drilling: Instead of passing data through multiple layers of components, child elements can directly request what they need.
+* Loose coupling: Elements don't need direct references to their dependencies. This makes the codebase more modular and maintainable.
+* Shared state management: Multiple elements can access and react to the same state without complex wiring.
+
+## Terminology
+To understand the Context API, it's important to understand the terminology that is used in the rest of the documentation.
+
+### Context
+An object that encapsulates both data and methods to interact with that data. This object can be provided to descending DOM elements. A context represents a specific capability or state that multiple elements might need to access. Examples include workspace context, content data, user permissions, or specialized services. Contexts encapsulate both data and methods, making them more than data containers. Unlike repositories, a context is always only available within the scope of a certain element and its descendants.
+
+### Context provider
+An element that creates and makes a context available to its descending elements. The provider is responsible for the context's lifecycle. One element can provide multiple different contexts if needed.
+
+### Context consumer
+Any element that requests and consumes a context provided by one of its ancestor elements. An element becomes a consumer by requesting a context. The element does not need to know which specific ancestor provides the context nor implement any special interfaces. The consuming element receives callbacks when the requested context becomes available or unavailable. This allows the element to react appropriately to changes in the element hierarchy.
+
+### Context Token
+A unique identifier used to request a specific context. Context tokens serve as contracts between providers and consumers. They define exactly which context is being requested and ensure that the right provider responds. Using a context token prevents conflicts when multiple contexts might have similar names and makes clear what functionality is being shared.
+
+## Context consuming flow
+Each DOM element can be a context provider. Each descendant in the DOM hierarchy can consume that context if desired. When an element wants to consume a context, the following happens:
+
+1. An element requests a context by a given Context Token.
+2. The Context API dispatches an event that starts at the element that requested the context. The event bubbles up the DOM tree to each parent element until an element is found that responds to the event.
+3. An instance of the context is provided back to the element that requested the context.
+
+![Context API Flow](images/umbraco_context_api_flow.png)
+
+If no context could be found and the event reaches the top-level element (the document), no context is consumed.
+
+## Common contexts
+Although every element can be a context provider, the most important contexts are registered at specific hierarchy levels. These levels are also explicit extension points in the Umbraco manifest. 
+
+The most common hierarchy levels to which the contexts can be registered are:
+
+* Global
+* Section
+* Workspace
+* Property
+
+**Global contexts** are registered at the highest level and are always available anywhere in the backoffice. Examples of global contexts:
+* `Notification context`: used for displaying notifications in the backoffice. This context is consumable in elements anywhere in the DOM tree.
+* `Current user context`: has information about the currently logged in user. This context is consumable anywhere in the DOM tree.
+
+**Section contexts** are available in the context of a section. That is everything in the backoffice except the menubar. Examples of section contexts:
+* `Section context`: provides information about the section, like path, alias, and label.
+* `Sidebar menu section context`: holds information about the sidebar menu, like which menu is currently selected.
+
+**Workspace contexts** work on a workspace, the part of Umbraco that is next to the tree. Example for this level:
+* `Workspace context`: holds information about the current entity being edited in the workspace. This holds minimal information about an entity and the entity type. There are specific workspace contexts per entity type. For instance, the `Document workspace context` for documents and `Media workspace context` for media.
+
+**Property contexts** are contexts that work at the property level. They can work on one or more property editors. An example is the clipboard functionality where blocks can be copied and pasted between block grids and block lists. Because these contexts are scoped at the property level, they are typically not consumed directly.

17/umbraco-cms/customizing/foundation/icons.md

@@ -1,6 +1,6 @@
 # Icons
 
-The icons in the Umbraco backoffice are based on [Lucide Icons](https://lucide.dev/) and [Simple Icons](https://simpleicons.org/). The syntax for using an icon starts with `icon-`. You can find the full list of available icons in the [All Icons article in the UI documentation](https://apidocs.umbraco.com/v16/ui/?path=/docs/umb-icons--docs).
+The icons in the Umbraco backoffice are based on [Lucide Icons](https://lucide.dev/) and [Simple Icons](https://simpleicons.org/). The syntax for using an icon starts with `icon-`. You can find the full list of available icons in the [All Icons article in the UI documentation](https://apidocs.umbraco.com/v17/ui/?path=/docs/umb-icons--docs).
 
 ## Example