@portfoliablejs/valence 0.1.0

package/src/stories/getting-started/DesignTokens.mdx

@@ -0,0 +1,47 @@
+import { Meta, Title } from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Design Tokens" />
+
+<Title>Design Tokens</Title>
+
+Design tokens are the foundational, indivisible values of our visual language. They are defined as CSS Custom Properties and are used by all components to ensure consistency. You should also use these tokens in your application for any custom styling.
+
+## Colors
+
+Our color palette is divided into base, grayscale, and semantic colors. To use a color token in your CSS:
+
+```css
+.my-custom-element {
+  background-color: var(--color-card-bg);
+  color: var(--color-accent);
+}
+```
+
+## Spacing & Radii
+We use a consistent 8-point based spacing scale for margins, padding, and layout. Radii are used for rounding corners.
+
+```css
+.my-card {
+  padding: var(--space-lg); /* 16px */
+  margin-bottom: var(--space-xxl); /* 32px */
+  border-radius: var(--radius-md); /* 8px */
+}
+```
+
+## Typography
+The typography scale defines the font families, sizes, and weights used throughout the application. While components handle their own typography, you can use these tokens for slotted content or custom elements.
+```css
+.my-custom-text {
+  font-family: var(--font-family-base);
+  font-size: var(--font-size-md);
+}
+````
+
+## Animations
+Animation tokens provide consistent timing and easing curves for transitions and motion.
+
+```css
+.my-interactive-element {
+  transition: transform var(--anim-normal) var(--anim-ease);
+}
+```

package/src/stories/getting-started/Disclaimers.mdx

@@ -0,0 +1,153 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Disclaimers" />
+
+# Legal, Brand & Software Rights Protection Disclaimer
+
+This document outlines the intellectual property rights, trademark ownerships, third-party software licensing, and non-affiliation statements regarding physical hardware frames, device mockups, brand designations, and open-source libraries integrated within the design system.
+
+---
+
+## 1. General Non-Affiliation & Trademark Disclaimer
+
+> **Notice:** All product names, logos, brands, trademarks, and registered trademarks displayed or referenced within this component library, mockup catalog, or generated portfolio previews are the property of their respective owners. 
+
+All company, product, and service names used in this software are for **identification, educational, and nominative presentation purposes only**. The use or depiction of these names, logos, product designs, and trademarks does not imply any endorsement, sponsorship, affiliation, or association with the respective rights holders.
+
+---
+
+## 2. Nominative Fair Use Statement
+
+The device frames and digital mockups included in the asset catalog (`.avif` vector/raster representations) are provided strictly to enable designers, developers, and creators to showcase user interfaces, software, and web applications in realistic, real-world hardware contexts. 
+
+* **No Claim of Ownership:** Neither the authors, contributors, nor the application platform claim any ownership or copyright over the physical design, industrial geometry, or trademarked branding of the depicted hardware devices.
+* **Nominative Fair Use:** Hardware names (e.g., "iPhone", "Galaxy", "MacBook") are utilized solely to accurately describe the specific form factor, screen ratio, and display viewport dimensions being rendered.
+
+---
+
+## 3. Brand & Manufacturer Specific Disclaimers
+
+Below are explicit trademark acknowledgments for all supported hardware ecosystems in the device catalog:
+
+<table style={{ width: '100%', borderCollapse: 'collapse' }}>
+  <thead>
+    <tr>
+      <th style={{ textAlign: 'left', width: '25%' }}>Rights Holder</th>
+      <th style={{ textAlign: 'left', width: '35%' }}>Protected Trademarks & Marks</th>
+      <th style={{ textAlign: 'left', width: '40%' }}>Explicit Disclaimer Notice</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><strong>Apple Inc.</strong></td>
+      <td>
+        <code>iPhone</code>, <code>iPad</code>, <code>MacBook</code>, <code>MacBook Pro</code>, <code>MacBook Air</code>, <code>iMac</code>, <code>Apple Watch</code>, <code>Apple TV</code>, <code>iOS</code>, <code>macOS</code>, <code>iPadOS</code>
+      </td>
+      <td>
+        iPhone, iPad, MacBook, and Apple Watch are registered trademarks of Apple Inc., registered in the U.S. and other countries and regions. This software is an independent open-source project and has not been authorized, sponsored, or otherwise approved by Apple Inc.
+      </td>
+    </tr>
+    <tr>
+      <td><strong>Samsung Electronics Co., Ltd.</strong></td>
+      <td>
+        <code>Samsung</code>, <code>Galaxy</code>, <code>Galaxy S</code>, <code>Galaxy Z Fold</code>, <code>Galaxy Z Flip</code>, <code>Galaxy Tab</code>, <code>One UI</code>
+      </td>
+      <td>
+        Samsung and Samsung Galaxy are registered trademarks of Samsung Electronics Co., Ltd. References to Samsung hardware devices are for compatibility and presentation contexts only and do not imply endorsement by Samsung.
+      </td>
+    </tr>
+    <tr>
+      <td><strong>Google LLC</strong></td>
+      <td>
+        <code>Google</code>, <code>Pixel</code>, <code>Pixel Fold</code>, <code>Pixel Watch</code>, <code>Pixel Tablet</code>, <code>Android</code>, <code>Chromebook</code>
+      </td>
+      <td>
+        Google, Google Pixel, and Android are trademarks or registered trademarks of Google LLC. Android is a trademark of Google LLC. This component is not affiliated with or endorsed by Google LLC.
+      </td>
+    </tr>
+    <tr>
+      <td><strong>Microsoft Corporation</strong></td>
+      <td>
+        <code>Microsoft</code>, <code>Surface</code>, <code>Surface Pro</code>, <code>Surface Laptop</code>, <code>Windows</code>, <code>Xbox</code>
+      </td>
+      <td>
+        Microsoft, Surface, and Windows are registered trademarks of Microsoft Corporation in the United States and/or other countries.
+      </td>
+    </tr>
+    <tr>
+      <td><strong>Sony Group Corporation</strong></td>
+      <td>
+        <code>Sony</code>, <code>PlayStation</code>, <code>Xperia</code>, <code>Bravia</code>
+      </td>
+      <td>
+        Sony, Xperia, and PlayStation are registered trademarks or trademarks of Sony Group Corporation or its affiliates.
+      </td>
+    </tr>
+    <tr>
+      <td><strong>LG Electronics Inc.</strong></td>
+      <td>
+        <code>LG</code>, <code>webOS</code>, <code>LG Gram</code>, <code>LG UltraFine</code>
+      </td>
+      <td>
+        LG and webOS are registered trademarks of LG Electronics Inc.
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## 4. Open-Source Software & Third-Party Dependencies
+
+This design system integrates independent open-source libraries and public infrastructure services to power visual diagramming, syntax highlighting, smooth interaction mechanics, documentation generation, and domain routing:
+
+<table style={{ width: '100%', borderCollapse: 'collapse' }}>
+  <thead>
+    <tr>
+      <th style={{ textAlign: 'left', width: '18%' }}>Service / Library</th>
+      <th style={{ textAlign: 'left', width: '18%' }}>License</th>
+      <th style={{ textAlign: 'left', width: '27%' }}>Author / Maintainer</th>
+      <th style={{ textAlign: 'left', width: '37%' }}>Functional Purpose</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><strong>JS.ORG</strong></td>
+      <td><code>Community / Open Source</code></td>
+      <td>Stefan Ledin & JS.ORG Community</td>
+      <td>Provides dedicated custom domain name resolution and sub-domain allocation (<code>*.js.org</code>) for open-source JavaScript projects and design system documentation hosting.</td>
+    </tr>
+    <tr>
+      <td><strong>Storybook</strong></td>
+      <td><code>MIT License</code></td>
+      <td>OpenJS Foundation / Chromatic & Contributors</td>
+      <td>Drives isolated component previewing, automated accessibility auditing, visual regression testing, and interactive documentation generation.</td>
+    </tr>
+    <tr>
+      <td><strong>Mermaid.js</strong></td>
+      <td><code>MIT License</code></td>
+      <td>Knut Sveidqvist & Contributors</td>
+      <td>Powers the <code>&lt;mermaid-diagram&gt;</code> web component for dynamic chart and architecture diagram rendering inside documentation and case study articles.</td>
+    </tr>
+    <tr>
+      <td><strong>Lenis</strong></td>
+      <td><code>MIT License</code></td>
+      <td>Darkroom Engineering</td>
+      <td>Drives smooth mouse wheel momentum scrolling and inertial motion physics across desktop viewports.</td>
+    </tr>
+    <tr>
+      <td><strong>Prism.js</strong></td>
+      <td><code>MIT License</code></td>
+      <td>Lea Verou & Contributors</td>
+      <td>Provides lightweight, real-time code syntax tokenization and syntax highlighting within the <code>ds-article</code> reading shell.</td>
+    </tr>
+  </tbody>
+</table>
+
+## 5. Guidelines for Portfolio Builders & End Users
+
+When using this component inside an open-source portfolio builder, Web application, or exported static site:
+
+1. **User Content Responsibility:** End users publishing portfolios are solely responsible for ensuring that the content, images, and artwork displayed inside the `screen-image` layer do not infringe upon any third-party copyrights or trademarks.
+2. **Commercial Distribution Notice:** If you choose to bundle or sell exported portfolio themes containing device mockup assets, verify that your redistribution complies with local trademark laws regarding commercial hardware depictions.
+3. **Opt-Out / Custom-Only Usage:** Users wishing to avoid displaying trademarked physical bezels entirely can enable the `custom-only` attribute on `<ds-thumbnail custom-only>` to hide all device overlays while preserving clean, unbranded container styling.

package/src/stories/getting-started/Installation.mdx

@@ -0,0 +1,71 @@
+import { Meta, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Installation & Usage" />
+
+# Installation & Usage
+
+Integrating Valence into your project is designed to be straightforward. As a package of native Web Components, although it was built specifically with the `portfoliable` open-source application in mind, it can be used in any HTML-based environment.
+
+## Installation
+
+First, add the Valence package to your project. If you are developing locally, you can use `npm link` or a local file path. For a published package, you would use:
+
+<Source code={`npm install valence-ds`} language="bash" />
+
+## Importing the Library
+
+To make the components available in your application, you need to import the main library entry point. This single import registers all the components and foundational styles.
+
+In your main JavaScript file (e.g., `main.js` or `App.js`):
+
+<Source code={`import 'valence-ds';`} language="js" />
+
+This will automatically load the necessary CSS design tokens and define all custom elements like `<ds-button>`, `<ds-header>`, etc., making them ready to use in your HTML.
+
+## Using a Component
+
+Once imported, you can use the components directly in your HTML like any standard element.
+
+For example, to use a button and an icon:
+
+<Source code={`
+<ds-button variant="primary" icon="play">
+  Play Video
+</ds-button>
+
+<ds-icon name="share" size="24"></ds-icon>
+`} language="html" />
+
+### Passing Data
+
+-   **Simple Data (Strings, Numbers):** Pass data using standard HTML attributes.
+    ```html
+    <ds-pill label="Repository" />
+    ```
+-   **Boolean States:** Use the presence or absence of an attribute to indicate a boolean `true` state.
+    ```html
+    <ds-toggle checked></ds-toggle>
+    ```
+-   **Complex Data (Arrays, Objects):** For complex data, it's best to set the data via a JavaScript property on the element.
+    ```js
+    const myHeader = document.querySelector('ds-header');
+    myHeader.menuItems = [
+      { id: 'case-1', label: 'First Case' },
+      { id: 'case-2', label: 'Second Case' }
+    ];
+    ```
+
+## Handling Events
+
+Valence components communicate with your application by dispatching standard `CustomEvent`. All events are prefixed with `ds-` for clarity.
+
+You can listen for these events using `addEventListener`:
+
+<Source code={`
+const modeToggle = document.querySelector('ds-mode-toggle');
+
+modeToggle.addEventListener('ds-mode-change', (event) => {
+  console.log('New mode selected:', event.detail.mode);
+  // Your application logic here...
+});
+`} language="js" />

package/src/stories/getting-started/Introduction.mdx

@@ -0,0 +1,51 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Introduction" />
+
+# Introduction to Valence
+
+Welcome to Valence, the Design System powering `portfoliable`, the open-source portfolio builder for designers, developers, creatives and companies around the world.
+
+Valence is a comprehensive library of reusable, accessible, and themeable Web Components built with a "native-first" philosophy. It is designed to provide the building blocks for creating beautiful, consistent, and high-performance portfolio applications. 
+
+## Core Principles
+
+Our system is built upon a few core principles that guide every component and decision:
+
+### Atomic Design
+
+Valence is structured using **Atomic Design** methodology. This means our components are organized by complexity, from the smallest, indivisible "atoms" to larger, composite "organisms".
+
+-   **Sub-atoms:** The core design tokens—colors, typography, spacing—that define the visual language.
+-   **Atoms:** The basic building blocks of our UI (e.g., Button, Icon, Pill). They are not useful on their own.
+-   **Molecules:** Simple groups of atoms functioning together as a unit (e.g., Search Input, which combines a button and an input field).
+-   **Organisms:** Complex UI components composed of molecules and atoms (e.g., Header, Gallery, Case Slide).
+-   **Templates:** Page-level objects that place organisms into a layout. *(Handled by the consumer application, `portfoliable`)*.
+
+This structure ensures scalability, maintainability, and a clear mental model for developers.
+
+### Encapsulated & Native
+
+Every component is a **native Web Component** with its styles and logic fully encapsulated within the Shadow DOM. This means:
+
+-   **No Style Conflicts:** Component styles will never leak out and interfere with your application's styles, and vice-versa.
+-   **Framework Agnostic:** While built with vanilla JavaScript, these components can be used in any framework (React, Vue, Svelte) or no framework at all.
+-   **Future-Proof:** By building on web standards, we ensure long-term stability and performance.
+
+### Accessibility First
+
+Accessibility is not an afterthought; it is a core requirement. Every component is designed and built to meet **WCAG 2.1 AA** standards. This includes:
+
+-   **Semantic HTML:** Using the correct elements for the job.
+-   **WAI-ARIA Roles:** Providing appropriate roles and states for screen readers.
+-   **Keyboard Navigation:** Ensuring every interactive element is fully operable with a keyboard.
+-   **Theming for A11y:** Built-in support for high-contrast, reduced-motion, and large-text modes.
+
+## How to Use This Documentation
+
+This Documentation, built in Storybook, is your interactive guide to the Valence Design System. Each component has its own "Docs" and "Canvas" tabs:
+
+-   **Docs:** Detailed documentation explaining the component's purpose, API, and best practices.
+-   **Canvas:** An interactive playground where you can manipulate component properties (`props` or `attributes`) and see the results in real-time.
+
+Use the sidebar to navigate through the Sub-atoms, Atoms, Molecules, and Organisms.

package/src/stories/getting-started/PortfoliableIntegration.mdx

@@ -0,0 +1,265 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="getting-started/Portfoliable Integration" />
+
+# Portfoliable Application Integration Guide
+
+>note: remember to place the no copy smooth scorlling rules here and to app
+
+The `portfoliable` application is an open-source, web-native portfolio builder designed as a single-page Web Component shell (`AppShell`). It dynamically consumes, orchestrates, and renders templates from the **Valence Design System** (`ds-*` Web Components).
+
+This document serves as the primary integration guide explaining how the host application interacts with Valence components, passes data through shadow boundaries, manages global accessibility cascades, and handles runtime state transitions.
+
+<br />
+
+## 1. Application Architecture & Component Shell
+
+The application entrypoint (`src/main.js`) mounts the root Web Component (`<app-shell>`) directly into the DOM viewport. `AppShell` encapsulated inside `src/App.js` maintains application state and renders Valence components into dedicated view containers (`#view-home`, `#view-case`, `#view-about`).
+
+<mermaid-diagram chart={`
+  flowchart TD
+      subgraph Entry ["DOM Mountpoint (main.js)"]
+          AppShell["&lt;app-shell&gt; (AppShell Class)"]
+      end
+
+      subgraph Shell ["App Shell Shadow DOM Boundary"]
+          Header["&lt;ds-header id='app-header'&gt;"]
+          Main["&lt;main&gt; Viewport Container"]
+          Toast["&lt;ds-toast id='app-toast'&gt;"]
+          ModalContainer["#modal-container"]
+          VideoPlayer["&lt;ds-video-player id='video-player'&gt;"]
+      end
+
+      subgraph Views ["Dynamic View Containers"]
+          HomeView["#view-home (&lt;ds-gallery&gt;)"]
+          CaseView["#view-case (#case-slider-container)"]
+      end
+
+      subgraph Components ["Valence Component Instances"]
+          GalleryItem["&lt;ds-gallery-item&gt;"]
+          CaseSlide["&lt;ds-case-slide&gt;"]
+          Modals["&lt;ds-modal&gt; / &lt;ds-item-row&gt;"]
+      end
+
+      AppShell --> Header
+      AppShell --> Main
+      AppShell --> Toast
+      AppShell --> ModalContainer
+      AppShell --> VideoPlayer
+
+      Main --> HomeView
+      Main --> CaseView
+
+      HomeView --> GalleryItem
+      CaseView --> CaseSlide
+      ModalContainer --> Modals
+
+      %% Styling
+      style Entry fill:#f8fafc,stroke:#94a3b8,stroke-width:2px,color:#0f172a
+      style Shell fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
+      style Views fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#14532d
+      style Components fill:#ffffff,stroke:#cbd5e1,color:#0f172a
+`} />
+
+---
+
+## 2. Component Consumption Model
+
+The `portfoliable` shell communicates with Valence custom elements using three primary web standards:
+
+### A. Primitive HTML Attributes
+Application state values are passed downstream by setting standard HTML attributes on custom elements during rendering cycles:
+
+<table>
+  <thead>
+    <tr>
+      <th>Component</th>
+      <th>Attribute</th>
+      <th>Type / Values</th>
+      <th>Application Source State</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>&lt;ds-header&gt;</code></td>
+      <td><code>view</code></td>
+      <td><code>'home' | 'case' | 'about'</code></td>
+      <td><code>this.state.currentView</code></td>
+    </tr>
+    <tr>
+      <td><code>&lt;ds-header&gt;</code></td>
+      <td><code>current-label</code></td>
+      <td><code>string</code></td>
+      <td>Active case title from <code>portfolioCases</code></td>
+    </tr>
+    <tr>
+      <td><code>&lt;ds-gallery-item&gt;</code></td>
+      <td><code>title</code>, <code>short-desc</code>, <code>read-time</code>, <code>thumb-src</code></td>
+      <td><code>string</code></td>
+      <td>Localized case metadata resolved via <code>this.getLang()</code></td>
+    </tr>
+    <tr>
+      <td><code>&lt;ds-gallery-item&gt;</code></td>
+      <td><code>device</code></td>
+      <td><code>'iphone-17' | 'iphone-12' | 'apple-watch'</code></td>
+      <td><code>caseData.deviceClass</code></td>
+    </tr>
+    <tr>
+      <td><code>&lt;ds-gallery-item&gt;</code></td>
+      <td><code>has-video</code>, <code>has-repo</code>, <code>has-live</code></td>
+      <td><code>'true' | 'false'</code></td>
+      <td>Boolean presence of URLs or video assets in case schema</td>
+    </tr>
+    <tr>
+      <td><code>&lt;ds-case-slide&gt;</code></td>
+      <td><code>title</code>, <code>year</code>, <code>thumb-src</code>, <code>device</code></td>
+      <td><code>string</code></td>
+      <td>Case study attributes mapped for slide layout</td>
+    </tr>
+    <tr>
+      <td><code>&lt;ds-toast&gt;</code></td>
+      <td><code>visible</code></td>
+      <td><code>'true' | 'false'</code></td>
+      <td><code>this.state.toast.visible</code></td>
+    </tr>
+  </tbody>
+</table>
+
+### B. Shadow DOM Slot Injection
+For complex, formatted content (such as rich case study bodies, code snippets, or inline telemetry cards), `AppShell` injects HTML subtrees directly into component `<slot>` targets:
+
+```javascript
+// Example: Injecting rich localized HTML into <ds-case-slide> slot
+const slide = document.createElement('ds-case-slide');
+slide.dataset.caseId = caseData.id;
+slide.setAttribute('title', this.getLang(caseData.title));
+
+// Choose executive vs recruiter content based on app state
+const descContent = this.state.isRecruiterMode ? caseData.descRecruiter : caseData.desc;
+
+// Slot injection target
+slide.innerHTML = `<div slot="description">${this.getLang(descContent)}</div>`;
+
+```
+
+### C. Upstream Custom Events (`ds-*`)
+
+User actions inside Valence components dispatch custom DOM events prefixed with `ds-`. `AppShell` listens to these events on its shadow root to mutate global application state:
+
+---
+
+## 3. Internationalization (`i18n`) Pipeline
+
+Multilingual support is managed via a lightweight `i18n.js` module and localized data schemas in `data.js`.
+
+### Multilingual Data Definition Schema
+
+Case study records define string attributes using a two-locale dictionary helper:
+
+```javascript
+// src/data.js
+const i18n = (en, pt) => ({ en, pt });
+
+export const holofante = {
+  id: "holofante",
+  title: i18n("Agentic AI Design", "Design de IA Agêntica"),
+  shortDesc: i18n("DesignOps automation cuts delivery latency by 70%.", "Automação de DesignOps reduz a latência de entrega em 70%."),
+  readTime: i18n("3 min", "3 min"),
+  // ...
+};
+
+```
+
+### Runtime Translation Resolution
+
+When rendering Valence components, `AppShell` invokes `this.getLang(property)` to evaluate the user's active locale (`window.currentLang`):
+
+```javascript
+// Language resolution helper inside AppShell
+getLang(prop) {
+  if (prop && prop[this.state.lang]) {
+    return prop[this.state.lang];
+  }
+  return (prop && prop['en']) ? prop['en'] : prop;
+}
+
+```
+
+---
+
+## 4. Dual-Persona Content Injection (Executive vs. Recruiter)
+
+To serve both executive hiring managers and technical recruiters, `portfoliable` dynamically mutates the content slotted into `<ds-case-slide>` based on `this.state.isRecruiterMode`:
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                             ds-header                                    │
+│  [Executive Mode] <----------------------------------> [Recruiter Mode]  │
+└────────────────────────────────────┬─────────────────────────────────────┘
+                                     │
+                             ds-mode-change
+                                     │
+                                     v
+                       AppShell.setState({ isRecruiterMode })
+                                     │
+            ┌────────────────────────┴────────────────────────┐
+            ▼                                                 ▼
+   [Executive View: desc]                          [Recruiter View: descRecruiter]
+   - Business Impact Metrics                       - System Architecture Flowcharts
+   - User Experience Storytelling                  - Client Runtime Memory Models
+   - High-contrast Asset Cards                     - Async Telemetry & Code Snippets
+
+```
+
+When switching modes, `AppShell` clears and re-populates the `#case-slider-container` children, swapping the slotted HTML template passed into `<ds-case-slide>` without altering component wrapper attributes.
+
+---
+
+## 5. Global Accessibility (`a11y`) Propagation Engine
+
+Accessibility settings configured inside `<ds-modal id="a11y-modal">` are stored in `localStorage` and synchronized across the entire DOM root.
+
+### State Mutation & Class Cascade
+
+When a user toggles an accessibility setting, `_handleA11yChange()` mutates `this.state.a11y` and calls `applyA11ySettings()`:
+
+```javascript
+// Reflects a11y preferences onto document.documentElement as root classes
+applyA11ySettings() {
+  const htmlEl = document.documentElement;
+  const settings = this.state.a11y;
+  
+  Object.entries(settings).forEach(([key, value]) => {
+    // Converts camelCase to kebab-case (e.g. darkMode -> a11y-dark-mode)
+    const className = `a11y-${key.replace(/([A-Z])/g, '-$1').toLowerCase()}`;
+    htmlEl.classList.toggle(className, value);
+  });
+}
+
+```
+
+### Valence Component Shadow DOM Observation
+
+Every Valence Web Component executes `_observeRootAccessibility()` during `connectedCallback()`. A `MutationObserver` monitors `document.documentElement` for class changes and reflects boolean attributes onto the component host tag:
+
+```javascript
+// Inside every Valence component class (e.g., Button.js, Header.js)
+_observeRootAccessibility() {
+  const root = this.ownerDocument.documentElement;
+  const sync = () => {
+    this.toggleAttribute('a11y-dark-mode', root.classList.contains('a11y-dark-mode'));
+    this.toggleAttribute('a11y-high-contrast', root.classList.contains('a11y-high-contrast'));
+    this.toggleAttribute('a11y-large-text', root.classList.contains('a11y-large-text'));
+    this.toggleAttribute('a11y-dyslexia', root.classList.contains('a11y-dyslexia'));
+    this.toggleAttribute('a11y-reduce-motion', root.classList.contains('a11y-reduce-motion'));
+    this.toggleAttribute('a11y-forced-colors', root.classList.contains('a11y-forced-colors'));
+  };
+
+  sync();
+  this._themeObserver = new MutationObserver(sync);
+  this._themeObserver.observe(root, { attributes: true, attributeFilter: ['class'] });
+}
+
+```
+
+This decoupled observer pattern ensures that all active design system components update their visual styling instantly without requiring full-page re-renders or main-thread state cycles.

package/src/stories/getting-started/Theming.mdx

@@ -0,0 +1,48 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Theming & Accessibility" />
+
+# Theming & Accessibility
+
+Valence is designed with theming and accessibility at its core. The entire system can adapt its appearance based on global classes applied to the `<html>` element.
+
+This allows the consuming application (`portfoliable`) to control the visual theme for all components from a single, central place.
+
+## Dark Mode
+
+To enable Dark Mode across all components, add the `a11y-dark-mode` class to the `<html>` tag. This will automatically activate the dark theme variants for all color tokens. Components will update their appearance without any additional configuration.
+
+```html
+<html class="a11y-dark-mode">
+  ...
+</html>
+```
+
+## High Contrast Mode
+For users who require higher contrast, add the `a11y-high-contrast` class to the `<html>` tag. This theme uses a pure black and white palette with enhanced borders to meet contrast requirements. It will automatically override Dark Mode if both are present.
+
+```html
+<html class="a11y-high-contrast">
+  ...
+</html>
+```
+
+## Large Text
+
+To increase the base font size across the application, add the `a11y-large-text` class. This applies a multiplier to foundational font sizes, making text more readable. Components that use rem or em units will scale accordingly.
+
+```html
+<html class="a11y-large-text">
+  ...
+</html>
+```
+
+### Other Accessibility Modes
+
+Valence also supports several other modes for enhanced accessibility:
+- `a11y-reduce-motion`: Disables all non-essential animations and transitions.
+- `a11y-dyslexia`: Applies a dyslexia-friendly font across all components and content.
+- `a11y-focus-mode`: Provides a highly visible, consistent focus ring on all interactive elements for keyboard users.
+
+## Implementation
+Your application's main controller should be responsible for toggling these classes on the `<html>` element based on user preferences stored in localStorage.