docs: Add Design Principles page (#445)

* docs: add notes to merged architecture page

* docs: remove ARCHITECTURE.md

* docs: add design principles page

* docs: fix readme links

README.md

@@ -101,7 +101,7 @@ Web components. @heff spoke about [the potential of web components for video](ht
 - Are compatible by default with Javascript frameworks (React, Angular, Svelte)
 - Can be used across players when using multiple in the same site, e.g Youtube & `<video>`. (Could even be used by players as their own built-in controls)
 
-## Architecture
+## Core Concepts
 
-- [Architecture Notes](./ARCHITECTURE.md)
-- [Architecture Diagrams](https://media-chrome.org/en/architecture-diagrams)
+- [Design Principles](https://media-chrome.org/en/design-principles)
+- [Architecture](https://media-chrome.org/en/architecture)

docs/src/config.ts

@@ -61,7 +61,8 @@ export const SIDEBAR: Sidebar = {
     ],
     'Core Concepts': [
       { text: 'Media controller', link: 'en/media-controller' },
-      { text: 'Architecture', link: 'en/architecture-diagrams' },
+      { text: 'Design Principles', link: 'en/design-principles' },
+      { text: 'Architecture', link: 'en/architecture' },
     ],
     Components: [
       { text: 'Airplay button', link: 'en/media-airplay-button' },

docs/src/pages/en/architecture-diagrams.md → docs/src/pages/en/architecture.md

@@ -1,6 +1,6 @@
 ---
 title: Architecture
-description: Architecture Diagrams
+description: Architecture
 layout: ../../layouts/MainLayout.astro
 ---
 

ARCHITECTURE.md → docs/src/pages/en/design-principles.md

@@ -1,9 +1,28 @@
-# Architecture Notes
+---
+title: Design Principles
+description: Design Principles
+layout: ../../layouts/MainLayout.astro
+---
 
 ## Components should feel like native HTML
 
 Web components allow us to "extend the browser", and in this project we take that seriously, to the degree of aligning the design of the components to the [design of native HTML elements](https://www.w3.org/TR/design-principles/). In some cases this can seem less ideal/progressive, but it creates an intutive and predictable interface for anyone familiar with HTML concepts.
 
+## Element Naming
+
+- Prefix with `media-` for scoping.
+- The suffix should make it clear what the primary user interaction is with the element, mapping to the matching native HTML element when possible. e.g. `-button`, `-range`, `-image`.
+  - Use `-container` for elements that are purely for laying out other elements. More specific layout names like `-bar` are acceptible when the name is clear and intentional.
+  - Use `-display` when the primary use is displaying a state or data detail. e.g. `media-duration-display`.
+
+## Element Independence
+
+A goal of this project is that each UI element could be used independently of the project, in the same way an HTML Button can be used independently of an HTML Form. This will make it possible for other players to share these base elements.
+
+## Support Unidirectional Data Flow
+
+Many js application frameworks today like React follow a "unidirectional data flow" pattern. We want to make sure media chrome elements are not blocked or complicated to use in these contexts.
+
 ## Connecting elements to the media
 
 Media chrome UI elements emit events to request media state changes. These events bubble up the DOM and are caught by a parent `<media-controller>` element. The media-controller handles the request and calls the appropriate API on a child media element, designated with the attribute `slot="media"`. A media element can be `<video>`, `<audio>`, or any element with a matching API.
@@ -18,18 +37,3 @@ UI elements that are not children of a media-controller can be associated with a
 > 2. A parent media-container injects a reference to a media element into all child UI elements
 >
 > Moving to a single centralized _controller_ handling all operations against the media element has made debugging, monitoring user interactions, and refactoring much easier.
-
-## Element Independence
-
-A goal of this project is that each UI element could be used independently of the project, in the same way an HTML Button can be used independently of an HTML Form. This will make it possible for other players to share these base elements.
-
-## Support Unidirectional Data Flow
-
-Many js application frameworks today like React follow a "unidirectional data flow" pattern. We want to make sure media chrome elements are not blocked or complicated to use in these contexts.
-
-## Element Naming
-
-- Prefix with `media-` for scoping.
-- The suffix should make it clear what the primary user interaction is with the element, mapping to the matching native HTML element when possible. e.g. `-button`, `-range`, `-image`.
-  - Use `-container` for elements that are purely for laying out other elements. More specific layout names like `-bar` are acceptible when the name is clear and intentional.
-  - Use `-display` when the primary use is displaying a state or data detail. e.g. `media-duration-display`.