@portfoliablejs/valence 0.1.0

package/src/stories/contributing/DocumentingArchitecture.mdx

@@ -0,0 +1,216 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Contributing/Documenting: Architecture" />
+
+# Universal Component Architecture Documentation Standard
+
+This document defines the architectural specification and template for authoring component-level architecture files (`[ComponentName].Architecture.mdx`). Every component in the **Valence Design System**—regardless of its atomic tier—must include a dedicated architecture file alongside its `.js`, `.css`, and `.stories.js` files.
+
+---
+
+## Architectural Blueprint
+
+Architecture documentation bridges the gap between basic UI controls and full software integration. While standard Storybook stories (`.stories.js`) document visual states and argTypes, the `.Architecture.mdx` file details:
+
+* **Data Ownership & Flow:** Unidirectional data flow contracts (State In / Events Out).
+* **Composition & Slots:** Slot hierarchy, child constraints, and sub-component synergy.
+* **API Contracts:** Typed data schemas, custom event detail payloads, and CSS property hooks.
+* **Accessibility Engine Mechanics:** Host ARIA scrubbing, keyboard focus loops, and root class propagation.
+* **Host Application Wiring:** Concrete SPA integration examples.
+
+---
+
+## MDX Template
+
+Component authors can copy the Markdown template below when creating a new component architecture document.
+
+```mdx
+  import { Meta, Story, Canvas, Controls } from '@storybook/addon-docs/blocks';
+  import * as ComponentStories from './[ComponentName].stories';
+
+  <Meta title="[tier]s/[ComponentName]/Architecture"/>
+
+  # `ds-[component-name]`
+
+  The `ds-[component-name]` component is a **[stateless / controlled / composite]** 
+  [Atom / Molecule / Organism / Template] designed for 
+  [primary functional purpose in the application].
+
+  ---
+
+  ## Principles
+
+  ### Unidirectional Data Flow
+  The component strictly adheres to the **State In / Events Out** pattern:
+  * **State In (Attributes / Properties):** The host application binds primitive attributes or complex properties onto the host element.
+  * **Events Out (`ds-[component]-*`):** User interactions trigger custom DOM events containing immutable event detail payloads.
+  * **Encapsulated State:** The component never mutates external application state or history directly.
+
+  <mermaid-diagram chart={`
+    flowchart LR
+        subgraph Host["Host Application / App Shell"]
+            direction TB
+            State["State Manager / Router"]
+        end
+
+        subgraph WebComp["Valence Web Component"]
+            Component["<ds-[component-name]>"]
+        end
+
+        State -->|"1. State In<br/><code>.property = value</code>"| Component
+        Component -->|"2. Event Out<br/><code>ds-[component]-event</code>"| State
+
+        %% Styling
+        style Host fill:#f8fafc,stroke:#94a3b8,stroke-width:2px,color:#0f172a
+        style WebComp fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
+        style State fill:#ffffff,stroke:#cbd5e1,color:#0f172a
+        style Component fill:#ffffff,stroke:#93c5fd,color:#1e3a8a
+  `} />
+
+  ## Slot Architecture
+
+  [Detail how default and named slots behave inside the Shadow DOM wrapper, including sub-component dependencies]
+
+  ### Slot Hierarchy Table
+
+  <table>
+    <thead>
+      <tr>
+        <th>Slot Name</th>
+        <th>Type / Allowed Children</th>
+        <th>Description</th>
+        <th>Fallback Behavior</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>`default`</td>
+        <td>Text / HTML Subtree</td>
+        <td>Primary content area (e.g., button label, modal body)</td>
+        <td>Renders fallback text or remains empty</td>
+      </tr>
+      <tr>
+        <td>`[slot-name]`</td>
+        <td>`ds-[sub-component]`</td>
+        <td>Named slot target for modular component composition</td>
+        <td>Slot wrapper is collapsed if unassigned</td>
+      </tr>
+    </tbody>
+  </table>
+
+
+  ## Data Model
+
+    ```typescript
+    // Define key TypeScript interfaces for component properties or custom event payloads
+    export interface [Component]Data {
+      id: string;
+      label: string;
+      [key: string]: any;
+    }
+    
+
+  ## API Contract
+
+  ### Properties & Attributes
+
+  <table>
+    <thead>
+      <tr>
+        <th>Property</th>
+        <th>Attribute</th>
+        <th>Type</th>
+        <th>Default</th>
+        <th>Description</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>`variant`</td>
+        <td>`variant`</td>
+        <td>`'primary' | 'secondary' | ...`</td>
+        <td>`'primary'`</td>
+        <td>Determines the visual styling variant.</td>
+      </tr>
+      <tr>
+        <td>`disabled`</td>
+        <td>`disabled`</td>
+        <td>`boolean`</td>
+        <td>`false`</td>
+        <td>Disables interactive states when set.</td>
+      </tr>
+    </tbody>
+  </table>
+
+  ### Emitted Custom Events
+
+  <table>
+    <thead>
+      <tr>
+        <th>Event Name</th>
+        <th>Bubbles / Composed</th>
+        <th>Detail Payload</th>
+        <th>Description</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>`ds-[component]-select`</td>
+        <td>`true` / `true`</td>
+        <td>`{ id: string, origin: HTMLElement }`</td>
+        <td>Emitted when a primary user selection action is triggered.</td>
+      </tr>
+    </tbody>
+  </table>
+
+  ### Sub-Atomic CSS Custom Property Hooks
+
+  <table>
+    <thead>
+      <tr>
+        <th>CSS Custom Property</th>
+        <th>Fallback Default</th>
+        <th>Description</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>`--*-radius`</td>
+        <td>`var(--radius-pill)`</td>
+        <td>Overrides corner radius geometry.</td>
+      </tr>
+      <tr>
+        <td>`--*-bg`</td>
+        <td>`var(--color-black)`</td>
+        <td>Overrides background surface fill color.</td>
+      </tr>
+    </tbody>
+  </table>
+
+  ## Accessibility & Host ARIA Delegation
+
+  * **ARIA Scrubbing:** Attribute delegation logic strips `aria-*` attributes applied to the outer host custom element tag and delegates them to the inner focusable primitive element.
+  * **Keyboard Navigation:** Native keyboard interactions supported (`Tab`, `Enter`, `Space`, `Escape`, Arrow Keys).
+  * **Global Accessibility Propagation:** Listens to class changes on `document.documentElement` via `MutationObserver` to sync accessibility modes:
+  * `.a11y-dark-mode`: Inverts contrast boundary scales.
+  * `.a11y-high-contrast`: Applies 21:1 binary contrast ratios.
+  * `.a11y-forced-colors`: Applies system active `Canvas` / `Highlight` palette maps.
+  * `.a11y-reduce-motion`: Suppresses CSS animation transitions.
+
+  ## Examples
+
+  ### Basic Integration Example
+
+  ```javascript
+    import 'valence/ds-[component-name]';
+
+    const element = document.createElement('ds-[component-name]');
+    element.setAttribute('variant', 'primary');
+
+    element.addEventListener('ds-[component]-select', (e) => {
+      console.log('Event received:', e.detail);
+    });
+
+    document.body.appendChild(element);
+  ```
+  ```

package/src/stories/contributing/DocumentingChangelog.mdx

@@ -0,0 +1,162 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Contributing/Documenting: Changelog" />
+
+# Changelog Documentation Standards
+
+This document defines the orientation and structure for authoring component changelog documents in Valence. Changelogs should help designers, developers, and contributors understand what changed, why it changed, and how it affects the component.
+
+<br />
+
+## 1. Purpose of a Changelog
+
+Every component with a stable public surface area should have a dedicated changelog document alongside its Storybook documentation. Changelogs are intended to:
+
+- record release milestones and notable updates;
+- summarize user-facing changes in clear language;
+- support design system maintainers during audits and reviews;
+- provide a consistent history for future contributors.
+
+<br />
+
+## 2. File Placement & Naming
+
+Changelog files should follow the component's storybook location and use a predictable naming pattern:
+
+- File pattern: `[ComponentName].Changelog.mdx`
+- Storybook title pattern: `[Tier]/[ComponentName] [vX.Y.Z]/Changelog`
+
+Example:
+
+- [src/stories/molecules/Breadcrumb/Breadcrumb.Changelog.mdx](src/stories/molecules/Breadcrumb/Breadcrumb.Changelog.mdx)
+- [src/stories/molecules/CaseNavigator/CaseNavigator.Changelog.mdx](src/stories/molecules/CaseNavigator/CaseNavigator.Changelog.mdx)
+
+<br />
+
+## 3. Required Structure
+
+A changelog should be concise, scannable, and structured around release intent.
+
+### Recommended Sections
+
+1. **Version Header**
+   - Use a heading such as `## [1.0.0] - YYYY-MM-DD`.
+   - Include the release date.
+
+2. **Release Summary**
+   - Open with a short paragraph describing the release theme.
+   - Highlight whether the release is an initial release, a stabilization pass, or a fix-focused update.
+
+3. **Summary of Changes**
+   - Use a table when the changelog includes several distinct updates.
+   - Columns should be: Classification, Scope / Context, Description.
+
+4. **Added / Fixed / Changed / Removed**
+   - Group related updates under clear headings.
+   - Keep bullets short and direct.
+
+5. **Reference Note**
+   - If relevant, link back to the global changelog for cross-system release context.
+
+<br />
+
+## 4. Writing Guidelines
+
+### Tone
+
+- Use clear, neutral, and release-oriented language.
+- Prefer plain English over internal jargon.
+- Focus on outcome and impact rather than implementation detail alone.
+
+### Classification
+
+Use standard labels consistently:
+
+- `Added` for new capabilities or features
+- `Fixed` for bug fixes and compliance corrections
+- `Changed` for behavior or API adjustments
+- `Removed` for deprecated or retired functionality
+
+### Scope
+
+Mention the affected component, file, or subsystem when useful. Examples:
+
+- `ds-button`
+- `CaseNavigator.js`
+- `_observeRootAccessibility`
+
+### Avoid
+
+- vague statements without context;
+- duplicate bullets that repeat the same point;
+- overly verbose implementation notes unless they matter to the user.
+
+<br />
+
+## 5. MDX Template
+
+Use the template below as a starting point for new component changelog documents.
+
+```mdx
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Molecules/[ComponentName] [v1.0.0]/Changelog" />
+
+# Changelog
+
+<br />
+
+## [1.0.0] - YYYY-MM-DD
+
+<br />
+
+### Initial Release
+
+A short summary of the component release and its key purpose.
+
+<br />
+
+### Summary of Changes
+
+<table>
+  <thead>
+    <tr>
+      <th>Classification</th>
+      <th>Scope / Context</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Added</td>
+      <td>ds-[component-name]</td>
+      <td>Added the initial stable release of the component.</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+### Added
+- **Feature Name:** Added a new capability or experience.
+
+### Fixed
+- **Issue Name:** Resolved a bug, validation issue, or accessibility concern.
+
+---
+
+*This changelog is specific to the component. For design system global releases, refer to the main Getting Started changelog.*
+```
+
+<br />
+
+## 6. Checklist for a Complete Changelog
+
+Before publishing or merging a changelog, confirm that it:
+
+- [ ] uses a clear version heading and date;
+- [ ] explains the release purpose in one short summary;
+- [ ] groups changes under consistent classifications;
+- [ ] mentions impacted component or scope clearly;
+- [ ] avoids unresolved or placeholder wording;
+- [ ] remains readable for both contributors and downstream consumers.

package/src/stories/contributing/DocumentingComponents.mdx

@@ -0,0 +1,248 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Contributing/Documenting: Components" />
+
+# Component Documentation & Source Structure Standards
+
+This document defines the architectural guidelines, file organization rules, design token integration standards, and Storybook best practices required for documenting Valence design system components.
+
+<br />
+
+## 1. Anatomy of a Standard Component File Set
+
+Every Atomic design system component exists as a self-contained folder under its hierarchy (`Atoms`, `Molecules`, `Organisms`). Each component folder consists of three core files following a strict naming convention:
+
+<table style={{ width: '100%', borderCollapse: 'collapse' }}>
+  <thead>
+    <tr>
+      <th style={{ textAlign: 'left' }}>File Pattern</th>
+      <th style={{ textAlign: 'left' }}>Role & Responsibility</th>
+      <th style={{ textAlign: 'left' }}>Primary Standards Reference</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>`[component-name].css`</code></td>
+      <td>Encapsulated Shadow DOM layout, variants, states, and accessibility themes.</td>
+      <td>Stateography, Chromography, Curvography, Accessibility CSS</td>
+    </tr>
+    <tr>
+      <td><code>`[ComponentName].js`</code></td>
+      <td>Web Component JavaScript class, attribute observed lifecycle, theme observer.</td>
+      <td>Web Component Architecture, ARIA Delegation</td>
+    </tr>
+    <tr>
+      <td><code>`[ComponentName].stories.js`</code></td>
+      <td>Storybook CSF3 configuration, Controls schema, and automated <code>play</code> tests.</td>
+      <td>Storybook Testing, Autodocs Configuration</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+## 2. Stylesheet Structure Guidelines (`*.css`)
+
+Component stylesheets strictly consume sub-atomic design tokens to ensure full compliance across visual states, light mode, dark mode, high contrast mode, and color vision deficiency simulations.
+
+### Section Order & Organization
+Component stylesheets must organize rules into logical blocks using standardised section headers:
+
+1. **Host Geometry (`:host`, `:host([disabled])`)**: Define inline display, root positioning, and host-level disabled cursor states.
+2. **Base Primitive Structure**: Structural flex properties, resets, token transitions, focus indicators, and layout gaps.
+3. **Interactive States (Stateography)**: Standard `:focus`, `:focus-visible`, `:hover`, and `:disabled` rules.
+4. **Light Mode Variant Styles**: Visual definitions for default surface variants (`primary`, `secondary`, `text`, `icon`, `floating`).
+5. **Accessibility Overrides**: Dedicated attribute blocks for `:host([a11y-dark-mode])`, `:host([a11y-high-contrast])`, and `:host([a11y-forced-colors])` / `@media (forced-colors: active)`.
+6. **Typography, Motion & Vision Suppression**: Dyslexia mode overrides (`:host([a11y-dyslexia])`), Reduced Motion suppression blocks (`:host([a11y-reduce-motion])`), and Colorblindness matrix compatibility.
+
+### Key CSS Rules & Pitfalls
+* **Disabled States & Cursors**: Avoid placing `pointer-events: none` on internal focusable primitives (`<button>`, `<input>`) as it prevents browser hover detection and suppresses `cursor: not-allowed`. Rely on native `disabled` attributes alongside host cursor definitions:
+  <br />
+  ```css
+  :host([disabled]) {
+    cursor: not-allowed !important;
+  }
+  
+  button:disabled,
+  :host([disabled]) button {
+    opacity: var(--opacity-disabled, 0.38);
+    cursor: not-allowed !important;
+  }
+  ```
+
+  > Note: Declare attribute-reflected host selectors and native `@media` queries in separate blocks to avoid CSS parsing errors)*:
+
+  ```css
+  /* Forced Colors Mode Override Pattern */
+
+  /* 1. Attribute Reflected State (Storybook / DOM Toggle) */
+  :host([a11y-forced-colors]) .variant-primary {
+    forced-color-adjust: none !important;
+    background: Highlight !important;
+    color: HighlightText !important;
+    border: var(--border-width-thin) var(--border-style-solid) Highlight !important;
+  }
+
+  /* 2. Native OS Media Query */
+  @media (forced-colors: active) {
+    .variant-primary {
+      forced-color-adjust: none !important;
+      background: Highlight !important;
+      color: HighlightText !important;
+      border: var(--border-width-thin) var(--border-style-solid) Highlight !important;
+    }
+  }
+
+  ```
+
+Storybook provides global toolbar controls that attach root classes onto `document.documentElement`. These trigger real-time simulations for accessibility modes and visual debugging utilities:
+
+* **Theme & Visual Modes**: Dark mode (`.a11y-dark-mode`), High Contrast mode (`.a11y-high-contrast`), and Forced Colors mode (`.a11y-forced-colors`).
+* **Reading & Navigation Preferences**: Large Text (`.a11y-large-text`), Dyslexia font (`.a11y-dyslexia`), Reduced Motion (`.a11y-reduce-motion`), and High-Visibility Focus Rings (`.a11y-focus-mode`).
+* **Assistive Technology Debuggers**: Live Region Debugger (`.a11y-show-live-regions`) visually highlights `[aria-live]`, `[role="alert"]`, and `[role="status"]` elements with a dashed pink outline (`#ff007f`) and programmatic politeness badge to inspect dynamic screen reader announcements during audits.
+* **Vision Deficiency Simulators**: SVG color matrix transformation filters for Deuteranopia, Protanopia, Tritanopia, Achromatopsia, and Low Vision Blur.
+
+## 4. Web Component Implementation Guidelines (`*.js`)
+
+Web Components encapsulate Shadow DOM boundaries and observe global DOM mutations to pass root accessibility states down to shadow nodes.
+
+* **Dynamic Announcements & Live Regions**: Components that render dynamic status updates or notifications (such as toasts, alerts, or progress bars) must explicitly define `role="status"` / `aria-live="polite"` or `role="alert"` / `aria-live="assertive"` on their internal Shadow DOM wrapper:
+```javascript
+// For polite status updates (e.g., toast notification, search results count)
+<div class="toast-wrapper" role="status" aria-live="polite">
+  <slot></slot>
+</div>
+
+```
+
+
+
+### Component Class Template Requirements
+
+* **Observed Attributes**: Core state attributes must be explicitly declared in `static get observedAttributes()`:
+```javascript
+static get observedAttributes() {
+  return ['variant', 'aria-label', 'disabled', 'icon', 'icon-position'];
+}
+
+```
+
+
+* **Layout Slot Hygiene**: Template strings inside `constructor()` must be compressed to eliminate whitespace text nodes around slots and icons:
+```javascript
+constructor() {
+  super();
+  this.attachShadow({ mode: 'open' });
+  this.shadowRoot.innerHTML = `<style>${css}</style><button type="button"><ds-icon class="btn-icon" style="display: none;"></ds-icon><slot></slot></button>`;
+}
+
+```
+
+
+* **Accessibility Root Reflection Observer**: Web Components observe root `<html>` class changes via a `MutationObserver` to reflect boolean attributes onto the host element (including `a11y-forced-colors`), bypassing Safari's lack of `:host-context()` support:
+```javascript
+_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-focus-mode', root.classList.contains('a11y-focus-mode'));
+    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'] });
+}
+
+```
+
+
+* **ARIA Delegation & Host Scrubbing**: Descriptive ARIA properties like `aria-label` applied to custom host elements must be delegated to the internal focusable control and scrubbed from the host wrapper tag to prevent `aria-prohibited-attr` validation errors:
+```javascript
+if (ariaLabel) {
+  this.buttonEl.setAttribute('aria-label', ariaLabel);
+  this.removeAttribute('aria-label');
+}
+
+```
+
+
+
+## 5. Storybook Configuration & Testing Standards (`*.stories.js`)
+
+Stories document component usage options, provide interactive Controls, and execute automated interaction testing.
+
+### Story Metadata & ArgTypes Layout
+
+* **Meta Configuration**: Enable `autodocs` and centered layout decorators.
+* **Categorized ArgTypes Schema**: Group Storybook controls into clear category and subcategory tables with a clear `description` for **every Story**:
+1. **Core & Variant Controls**: Variant selectors, label text, ARIA input strings, disabled toggles.
+2. **Sub-Atomic Props**: Dynamic CSS custom property overrides (`radius`, `backgroundColor`, `borderWidth`, `borderColor`).
+3. **Event Listeners**: Actions mapped to event triggers (like `onClick`).
+
+
+
+### Storybook Play Functions & Interaction Testing
+
+Interaction tests verify states, keyboard focus, ARIA attribute delegation, and tooltip triggers using `storybook/test` utilities:
+
+```javascript
+export const PrimaryButton = {
+  args: {
+    variant: 'primary',
+    label: 'Play Video',
+    hasIcon: true,
+    icon: 'play',
+    iconPosition: 'left',
+  },
+  play: async ({ canvasElement, step }) => {
+    const button = canvasElement.querySelector('ds-button');
+
+    await step('Hover button to verify interaction feedback', async () => {
+      await userEvent.hover(button);
+    });
+
+    await step('Verify keyboard focus capability', async () => {
+      const internalButton = button.shadowRoot.querySelector('button');
+      internalButton.focus();
+      expect(document.activeElement).toBe(button);
+    });
+
+    await step('Click primary action target', async () => {
+      await userEvent.click(button);
+    });
+  },
+};
+
+```
+
+## 6. Documentation Checklist for System Components
+
+When introducing or updating a design system component, ensure all mandatory checklist criteria are met:
+
+* [ ] **Styles (`*.css`)**:
+  * [ ] Consumes sub-atomic variables (`var(--color-*)`, `var(--space-*)`, `var(--radius-*)`).
+  * [ ] Implements `:focus-visible` with high-contrast accessibility focus rings.
+  * [ ] Declares dark mode (`:host([a11y-dark-mode])`) and 21:1 high contrast mode (`:host([a11y-high-contrast])`) state scales.
+  * [ ] Defines explicit system keywords (`Canvas`, `CanvasText`, `Highlight`) and `forced-color-adjust: none !important` under separate `:host([a11y-forced-colors])` and `@media (forced-colors: active)` blocks.
+  * [ ] Tested under vision deficiency simulator modes (Deuteranopia, Protanopia, Tritanopia, Achromatopsia).
+  * [ ] Preserves `cursor: not-allowed !important` on disabled states without hiding cursors.
+
+
+* [ ] **JavaScript (`*.js`)**:
+  * [ ] `observedAttributes` syncing configured.
+  * [ ] Shadow DOM HTML strings compressed onto a single line without extraneous whitespace.
+  * [ ] `MutationObserver` active on `document.documentElement` for cross-browser WebKit support.
+  * [ ] Reflects `a11y-forced-colors` attribute in `_observeRootAccessibility()`.
+  * [ ] `aria-label` delegated down to internal primitives and scrubbed from host tag.
+  * [ ] Defines `role="status"` (`aria-live="polite"`) or `role="alert"` (`aria-live="assertive"`) on dynamic status/notification wrappers.
+
+
+* [ ] **Storybook (`*.stories.js`)**:
+  * [ ] `tags: ['autodocs']` enabled.
+  * [ ] Sub-atomic control overrides configured.
+  * [ ] Automated `play` function tests cover hover, focus, and click steps.

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

@@ -0,0 +1,47 @@
+import { Meta, Subtitle, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Getting Started/Changelog" />
+
+# Changelog
+
+All notable changes to the **Valence** design system will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Added
+- **`<ds-gallery>` Organism:** New component to manage the home screen's horizontal gallery, encapsulating drag and wheel-scroll physics.
+- **`<ds-frame>` Atom:** New foundational component for displaying media within a device mockup (e.g., `iphone-17`) or a simple aspect-ratio container (e.g., `16:9`).
+- **`CONTRIBUTING.mdx`:** Added a comprehensive guide for new contributors to the Storybook documentation.
+
+### Changed
+- **Architectural Shift:** Re-classified `Summary` (formerly `AiSummary`), `ComboCard`, and `GalleryItem` from Organisms to Molecules to better align with Atomic Design principles.
+- **`<ds-toast>` (formerly `<ds-resume-toast>`):** Refactored the component to be universal, now accepting slotted content for broader use cases like tutorial prompts.
+- **`<ds-audio-player>`:** Enhanced with new controls for "Hide on Scroll" and "Auto-scroll" functionality, dispatching `ds-audio-hide-toggle` and `ds-audio-autoscroll-toggle` events.
+- **`<ds-gallery-item>`:** Simplified to use the new `<ds-frame>` component, removing all internal device-specific styling and logic.
+
+### Fixed
+- **Storybook Booleans:** Corrected the `render` function in `GalleryItem.stories.js` to properly handle boolean attributes, ensuring Storybook controls work as expected.
+- **Storybook Viewport:** Fixed an issue in `VideoPlayer.stories.js` where the preview iframe would collapse by wrapping the component in a container with a defined height.
+
+---
+
+## [1.0.0] - 2024-XX-XX
+
+<Subtitle>Initial Release</Subtitle>
+
+### Added
+- **Initial Component Library:** First stable release of all foundational atoms, molecules, and organisms, including:
+  - **Foundations:** Colors, Typography, Spacing, Animations, Overlays, Accessibility themes.
+  - **Atoms:** Button, Check, Divider, Icon, Kbd, Loader, Pill, Tab, Toggle, Tooltip.
+  - **Molecules:** AudioPlayer, Breadcrumb, ItemRow, MetricCard, SearchInput, VideoControls.
+  - **Organisms:** Header, Modal, VideoPlayer, CaseSlide.
+- **Storybook Documentation:** Initial setup of interactive documentation for all components.
+- **`portfoliable` Integration:** First successful integration with the `portfoliable` consumer application.
+
+---
+
+*This changelog serves as a high-level overview. For detailed changes, please refer to the commit history on our [GitHub repository](https://github.com/schimanko/valence).*