@portfoliablejs/valence 0.1.0

package/src/stories/molecules/NavigationMenu/NavigationMenu.stories.js

@@ -0,0 +1,295 @@
+import { html } from 'lit';
+import { expect, fn, userEvent } from 'storybook/test';
+import './NavigationMenu.js';
+
+export default {
+  title: 'Molecules/Navigation Menu [v1.1.0]',
+  component: 'ds-navigation-menu',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'Top navigation molecule with avatar, icon actions, tooltips, and contextual menus for language and accessibility controls.',
+      },
+    },
+  },
+  argTypes: {
+    languageTooltip: { control: 'text', table: { category: 'Tooltips' } },
+    languageKbdLabel: { control: 'text', table: { category: 'Tooltips' } },
+    languageKbdKey: { control: 'text', table: { category: 'Tooltips' } },
+    languageKbdShowPlus: { control: 'boolean', table: { category: 'Tooltips', defaultValue: { summary: 'true' } } },
+    languageAriaLabel: { control: 'text', table: { category: 'Accessibility' } },
+
+    accessibilityTooltip: { control: 'text', table: { category: 'Tooltips' } },
+    accessibilityKbdLabel: { control: 'text', table: { category: 'Tooltips' } },
+    accessibilityKbdKey: { control: 'text', table: { category: 'Tooltips' } },
+    accessibilityKbdShowPlus: { control: 'boolean', table: { category: 'Tooltips', defaultValue: { summary: 'true' } } },
+    accessibilityAriaLabel: { control: 'text', table: { category: 'Accessibility' } },
+
+    aboutTooltip: { control: 'text', table: { category: 'Tooltips' } },
+    aboutKbdLabel: { control: 'text', table: { category: 'Tooltips' } },
+    aboutKbdKey: { control: 'text', table: { category: 'Tooltips' } },
+    aboutKbdShowPlus: { control: 'boolean', table: { category: 'Tooltips', defaultValue: { summary: 'true' } } },
+    aboutAriaLabel: { control: 'text', table: { category: 'Accessibility' } },
+
+    avatarSrc: { control: 'text', table: { category: 'Avatar' } },
+    avatarAlt: { control: 'text', table: { category: 'Avatar' } },
+    disabled: { control: 'boolean', table: { category: 'Core', defaultValue: { summary: 'false' } } },
+
+    onLanguage: { action: 'ds-navigation-menu-language', table: { category: 'Events' } },
+    onAccessibility: { action: 'ds-navigation-menu-accessibility', table: { category: 'Events' } },
+    onAbout: { action: 'ds-navigation-menu-about', table: { category: 'Events' } },
+    onLanguageSelect: { action: 'ds-navigation-menu-language-select', table: { category: 'Events' } },
+    onAccessibilitySelect: { action: 'ds-navigation-menu-accessibility-select', table: { category: 'Events' } },
+  },
+  args: {
+    languageTooltip: 'Language',
+    languageKbdLabel: 'Ctrl',
+    languageKbdKey: 'L',
+    languageKbdShowPlus: true,
+    languageAriaLabel: 'Language',
+
+    accessibilityTooltip: 'Accessibility',
+    accessibilityKbdLabel: 'Ctrl',
+    accessibilityKbdKey: 'A',
+    accessibilityKbdShowPlus: true,
+    accessibilityAriaLabel: 'Accessibility',
+
+    aboutTooltip: 'About',
+    aboutKbdLabel: 'Ctrl',
+    aboutKbdKey: 'I',
+    aboutKbdShowPlus: true,
+    aboutAriaLabel: 'About',
+
+    avatarSrc: 'https://thispersondoesnotexist.com/random-person.jpeg',
+    avatarAlt: 'Profile face',
+    disabled: false,
+
+    onLanguage: fn(),
+    onAccessibility: fn(),
+    onAbout: fn(),
+    onLanguageSelect: fn(),
+    onAccessibilitySelect: fn(),
+  },
+  render: (args) => html`
+    <div style="padding: 16px; min-height: 560px; width: fit-content; display: inline-flex; align-items: flex-start; background: var(--color-bg, #ffffff);">
+      <ds-navigation-menu
+        language-tooltip=${args.languageTooltip}
+        language-kbd-label=${args.languageKbdLabel}
+        language-kbd-key=${args.languageKbdKey}
+        ?language-kbd-show-plus=${args.languageKbdShowPlus}
+        language-aria-label=${args.languageAriaLabel}
+
+        accessibility-tooltip=${args.accessibilityTooltip}
+        accessibility-kbd-label=${args.accessibilityKbdLabel}
+        accessibility-kbd-key=${args.accessibilityKbdKey}
+        ?accessibility-kbd-show-plus=${args.accessibilityKbdShowPlus}
+        accessibility-aria-label=${args.accessibilityAriaLabel}
+
+        about-tooltip=${args.aboutTooltip}
+        about-kbd-label=${args.aboutKbdLabel}
+        about-kbd-key=${args.aboutKbdKey}
+        ?about-kbd-show-plus=${args.aboutKbdShowPlus}
+        about-aria-label=${args.aboutAriaLabel}
+
+        avatar-src=${args.avatarSrc}
+        avatar-alt=${args.avatarAlt}
+        ?disabled=${args.disabled}
+        @ds-navigation-menu-language=${args.onLanguage}
+        @ds-navigation-menu-accessibility=${args.onAccessibility}
+        @ds-navigation-menu-about=${args.onAbout}
+        @ds-navigation-menu-language-select=${args.onLanguageSelect}
+        @ds-navigation-menu-accessibility-select=${args.onAccessibilitySelect}>
+      </ds-navigation-menu>
+    </div>
+  `,
+};
+
+export const Default = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Default navigation menu with avatar, language menu, and accessibility menu. Includes interaction checks for open/close behavior, alignment, and tooltip visibility states.',
+      },
+    },
+  },
+  play: async ({ canvasElement, step }) => {
+    const nav = canvasElement.querySelector('ds-navigation-menu');
+    const languageBtn = nav.shadowRoot.querySelector('.language-btn');
+    const accessibilityBtn = nav.shadowRoot.querySelector('.accessibility-btn');
+    const avatarBtn = nav.shadowRoot.querySelector('.avatar-button');
+    const languageTooltip = nav.shadowRoot.querySelector('.language-tooltip');
+    const accessibilityTooltip = nav.shadowRoot.querySelector('.accessibility-tooltip');
+    const languageMenu = nav.shadowRoot.querySelector('.language-menu');
+    const accessibilityMenu = nav.shadowRoot.querySelector('.accessibility-menu');
+
+    await step('Verify controls use simplified ds-button props contract', async () => {
+      expect(languageBtn.getAttribute('variant')).toBe('tertiary');
+      expect(languageBtn.getAttribute('has-text')).toBe('false');
+      expect(languageBtn.hasAttribute('has-icon')).toBe(true);
+
+      expect(accessibilityBtn.getAttribute('variant')).toBe('tertiary');
+      expect(accessibilityBtn.getAttribute('has-text')).toBe('false');
+      expect(accessibilityBtn.hasAttribute('has-icon')).toBe(true);
+
+      expect(avatarBtn.getAttribute('variant')).toBe('tertiary');
+      expect(avatarBtn.getAttribute('has-text')).toBe('false');
+      expect(avatarBtn.hasAttribute('has-image')).toBe(true);
+    });
+
+    await step('Verify avatar appears on the left and menus are initially closed', async () => {
+      const firstGroup = nav.shadowRoot.querySelector('.menu-profile');
+      const firstMenuItem = firstGroup.querySelector('.menu-item');
+      expect(firstMenuItem.contains(avatarBtn)).toBe(true);
+      expect(languageMenu.hasAttribute('open')).toBe(false);
+      expect(accessibilityMenu.hasAttribute('open')).toBe(false);
+    });
+
+    await step('Open language menu and choose Portuguese', async () => {
+      await userEvent.click(languageBtn);
+      expect(languageMenu.hasAttribute('open')).toBe(true);
+      expect(getComputedStyle(languageTooltip).display).toBe('none');
+
+      const languageCloseBtn = languageMenu.shadowRoot.querySelector('.close-btn');
+      const accessibilityCloseBtn = accessibilityMenu.shadowRoot.querySelector('.close-btn');
+      expect(languageCloseBtn).toBeTruthy();
+      expect(accessibilityCloseBtn).toBeTruthy();
+
+      const languageCard = languageMenu.shadowRoot.querySelector('.menu-card');
+      const accessibilityCard = accessibilityMenu.shadowRoot.querySelector('.menu-card');
+      expect(getComputedStyle(languageCard).width).toBe(getComputedStyle(accessibilityCard).width);
+
+      const ptRow = Array.from(languageMenu.shadowRoot.querySelectorAll('ds-item-row')).find((row) => row.getAttribute('label') === 'Portuguese');
+      expect(ptRow).toBeTruthy();
+      const ptRowAction = ptRow.shadowRoot.querySelector('.a11y-row');
+      await userEvent.click(ptRowAction);
+      expect(languageMenu.hasAttribute('open')).toBe(false);
+    });
+
+    await step('Open accessibility menu and toggle Text Size', async () => {
+      await userEvent.click(accessibilityBtn);
+      expect(accessibilityMenu.hasAttribute('open')).toBe(true);
+      expect(getComputedStyle(accessibilityTooltip).display).toBe('none');
+
+      const menuRect = accessibilityMenu.getBoundingClientRect();
+      const buttonRect = accessibilityBtn.getBoundingClientRect();
+      expect(menuRect.top).toBeGreaterThan(buttonRect.bottom - 1);
+      expect(Math.abs(menuRect.right - buttonRect.right)).toBeLessThan(2);
+
+      const textSizeRow = Array.from(accessibilityMenu.shadowRoot.querySelectorAll('ds-item-row')).find((row) => row.getAttribute('label') === 'Text Size');
+      expect(textSizeRow).toBeTruthy();
+      const textSizeAction = textSizeRow.shadowRoot.querySelector('.a11y-row');
+      await userEvent.click(textSizeAction);
+      expect(accessibilityMenu.hasAttribute('open')).toBe(true);
+    });
+
+    await step('Click avatar button to emit about action and close menus', async () => {
+      await userEvent.click(avatarBtn);
+      expect(languageMenu.hasAttribute('open')).toBe(false);
+      expect(accessibilityMenu.hasAttribute('open')).toBe(false);
+      expect(getComputedStyle(languageTooltip).display).not.toBe('none');
+      expect(getComputedStyle(accessibilityTooltip).display).not.toBe('none');
+
+      const avatarImage = avatarBtn.shadowRoot.querySelector('.btn-image');
+      expect(avatarImage.getAttribute('src')).toBe('https://thispersondoesnotexist.com/random-person.jpeg');
+    });
+  },
+};
+
+export const PortugueseExample = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Localized variant demonstrating translated tooltip labels and the same interactive behavior for both contextual menus.',
+      },
+    },
+  },
+  args: {
+    languageTooltip: 'Idioma',
+    languageKbdLabel: 'Ctrl',
+    languageKbdKey: 'L',
+    accessibilityTooltip: 'Acessibilidade',
+    accessibilityKbdLabel: 'Ctrl',
+    accessibilityKbdKey: 'A',
+    aboutTooltip: 'Sobre',
+    aboutKbdLabel: 'Ctrl',
+    aboutKbdKey: 'I',
+    languageAriaLabel: 'Idioma',
+    accessibilityAriaLabel: 'Acessibilidade',
+    aboutAriaLabel: 'Sobre',
+  },
+  play: async ({ canvasElement, step }) => {
+    const nav = canvasElement.querySelector('ds-navigation-menu');
+    const languageBtn = nav.shadowRoot.querySelector('.language-btn');
+    const languageTooltip = nav.shadowRoot.querySelector('.language-tooltip');
+    const accessibilityBtn = nav.shadowRoot.querySelector('.accessibility-btn');
+
+    await step('Verify localized tooltip labels are applied', async () => {
+      expect(languageTooltip.getAttribute('text')).toBe('Idioma');
+    });
+
+    await step('Open localized language menu and select English', async () => {
+      await userEvent.click(languageBtn);
+      const languageMenu = nav.shadowRoot.querySelector('.language-menu');
+      expect(languageMenu.hasAttribute('open')).toBe(true);
+
+      const enRow = Array.from(languageMenu.shadowRoot.querySelectorAll('ds-item-row')).find((row) => row.getAttribute('label') === 'English');
+      expect(enRow).toBeTruthy();
+      const enRowAction = enRow.shadowRoot.querySelector('.a11y-row');
+      await userEvent.click(enRowAction);
+      expect(languageMenu.hasAttribute('open')).toBe(false);
+    });
+
+    await step('Open accessibility menu from localized scenario', async () => {
+      await userEvent.click(accessibilityBtn);
+      const accessibilityMenu = nav.shadowRoot.querySelector('.accessibility-menu');
+      expect(accessibilityMenu.hasAttribute('open')).toBe(true);
+    });
+  },
+};
+
+export const LanguageMenuBehavior = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Focused interaction story for language menu single-select check behavior. Verifies that selection changes from English to Portuguese and menu closes after selection.',
+      },
+    },
+  },
+  play: async ({ canvasElement, step }) => {
+    const nav = canvasElement.querySelector('ds-navigation-menu');
+    const languageBtn = nav.shadowRoot.querySelector('.language-btn');
+
+    await step('Open language menu', async () => {
+      await userEvent.click(languageBtn);
+      const languageMenu = nav.shadowRoot.querySelector('.language-menu');
+      expect(languageMenu.hasAttribute('open')).toBe(true);
+    });
+
+    await step('Verify English starts selected', async () => {
+      const languageMenu = nav.shadowRoot.querySelector('.language-menu');
+      const enRow = Array.from(languageMenu.shadowRoot.querySelectorAll('ds-item-row')).find((row) => row.getAttribute('label') === 'English');
+      expect(enRow).toBeTruthy();
+      expect(enRow.hasAttribute('selected')).toBe(true);
+    });
+
+    await step('Select Portuguese and verify close', async () => {
+      const languageMenu = nav.shadowRoot.querySelector('.language-menu');
+      const ptRow = Array.from(languageMenu.shadowRoot.querySelectorAll('ds-item-row')).find((row) => row.getAttribute('label') === 'Portuguese');
+      expect(ptRow).toBeTruthy();
+      const ptRowAction = ptRow.shadowRoot.querySelector('.a11y-row');
+      await userEvent.click(ptRowAction);
+      expect(languageMenu.hasAttribute('open')).toBe(false);
+    });
+
+    await step('Re-open and confirm Portuguese is selected', async () => {
+      await userEvent.click(languageBtn);
+      const languageMenu = nav.shadowRoot.querySelector('.language-menu');
+      const ptRow = Array.from(languageMenu.shadowRoot.querySelectorAll('ds-item-row')).find((row) => row.getAttribute('label') === 'Portuguese');
+      const enRow = Array.from(languageMenu.shadowRoot.querySelectorAll('ds-item-row')).find((row) => row.getAttribute('label') === 'English');
+      expect(ptRow.hasAttribute('selected')).toBe(true);
+      expect(enRow.hasAttribute('selected')).toBe(false);
+    });
+  },
+};

package/src/stories/molecules/NavigationMenu/navigation-menu.css

@@ -0,0 +1,88 @@
+:host {
+  display: inline-flex;
+  align-items: center;
+  overflow: visible;
+}
+
+.navigation-menu {
+  display: inline-flex;
+  align-items: center;
+  height: var(--size-height-sm);
+  --ds-navigation-visual-size: var(--size-icon-lg, 24px);
+  gap: var(--ds-navigation-menu-gap, var(--space-sm));
+  font-family: var(--font-family, inherit);
+  overflow: visible;
+}
+
+.menu-group {
+  display: inline-flex;
+  align-items: center;
+  height: 100%;
+  gap: var(--space-sm);
+}
+
+.menu-item {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  height: 100%;
+}
+
+.menu-item ds-contextual-menu {
+  position: absolute;
+  top: calc(100% + var(--space-sm));
+  right: 0;
+  left: auto;
+  transform: none;
+  z-index: var(--z-dropdown, 50);
+}
+
+.menu-item-language ds-contextual-menu {
+  --ds-contextual-menu-width: var(--ds-navigation-contextual-width, 260px);
+}
+
+.menu-item-accessibility ds-contextual-menu {
+  --ds-contextual-menu-width: var(--ds-navigation-contextual-width, 260px);
+}
+
+:host([language-menu-open]) .language-tooltip {
+  display: none;
+}
+
+:host([accessibility-menu-open]) .accessibility-tooltip {
+  display: none;
+}
+
+.menu-actions ds-button {
+  --color-text-muted: var(--ds-navigation-icon-color, var(--color-gray-dark));
+  --ds-button-hover-bg: var(--ds-navigation-icon-hover-bg, rgba(0, 0, 0, 0.08));
+  --ds-button-active-bg: var(--ds-navigation-icon-active-bg, rgba(0, 0, 0, 0.14));
+}
+
+.menu-divider {
+  display: inline-flex;
+  align-items: center;
+  height: 100%;
+}
+
+.menu-divider ds-divider {
+  height: var(--ds-navigation-visual-size);
+  --ds-divider-margin: 0 var(--space-sm);
+}
+
+.avatar-button {
+  --ds-button-image-size: var(--ds-navigation-visual-size);
+  --ds-button-bg: var(--ds-navigation-avatar-bg, var(--color-bg));
+  --ds-button-border-width: var(--border-width-none);
+  --ds-button-border-color: transparent;
+  --a11y-focus-outline: none;
+  --a11y-focus-offset: 0;
+  flex: 0 0 var(--ds-navigation-visual-size);
+}
+
+:host([a11y-reduce-motion]) * {
+  transition-duration: 0s !important;
+  transition-delay: 0s !important;
+  animation-duration: 0s !important;
+  animation-delay: 0s !important;
+}

package/src/stories/molecules/Summary/Summary.Architecture.mdx

@@ -0,0 +1,186 @@
+import { Meta, Story, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as SummaryStories from './Summary.stories';
+
+<Meta title="Molecules/Summary/Architecture" />
+
+# `ds-summary`
+
+The `ds-summary` component is a **stateless (presentational)** Molecule designed for rendering summaries, executive briefs, and key case study findings using glassmorphic audio-player container styles and controllable slotted metric grids.
+
+---
+
+## Principles
+
+### Unidirectional Data Flow
+The component strictly implements the **Unidirectional Data Flow** pattern:
+* **State In (`text`, `active`, `label-header`, `show-metrics`):** The host application binds primitive text and active state attributes downstream onto the host element.
+* **Events Out (`ds-summary-complete`):** Emits a custom DOM event when the dynamic typing sequence finishes rendering text and reveals slotted metric cards.
+* **Passive Presentation:** The component contains zero business logic and relies on direct attribute bindings for localizable header labels.
+
+<mermaid-diagram chart={`
+  flowchart LR
+      subgraph Host["Host SPA / App Shell"]
+          direction TB
+          State["App State / i18n Pipeline"]
+      end
+
+      subgraph WebComp["Presentational Web Component"]
+          Summary["ds-summary"]
+      end
+
+      State -->|"1. State In<br/>text = '...', active = true, show-metrics = true"| Summary
+      Summary -->|"2. Event Out<br/>ds-summary-complete"| 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 Summary fill:#ffffff,stroke:#93c5fd,color:#1e3a8a
+`} />
+
+---
+
+## Slot Architecture
+
+The `ds-summary` component provides a default `<slot>` channel inside a two-column CSS grid to project `ds-metric-card` child atoms.
+
+### 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>`ds-metric-card`</td>
+      <td>Projects summary KPI cards into a 2-column grid beneath the primary text body.</td>
+      <td>Collapses grid wrapper if no metric cards are slotted or if `show-metrics="false"`.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## 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>`text`</td>
+      <td>`text`</td>
+      <td>`string`</td>
+      <td>`''`</td>
+      <td>Primary summary body copy rendered inside the block.</td>
+    </tr>
+    <tr>
+      <td>`active`</td>
+      <td>`active`</td>
+      <td>`boolean`</td>
+      <td>`false`</td>
+      <td>When set to `true`, triggers the thinking dots and typing animation sequence.</td>
+    </tr>
+    <tr>
+      <td>`labelHeader`</td>
+      <td>`label-header`</td>
+      <td>`string`</td>
+      <td>`'Summary'`</td>
+      <td>Localizable header title displayed at the top of the block.</td>
+    </tr>
+    <tr>
+      <td>`showMetrics`</td>
+      <td>`show-metrics`</td>
+      <td>`boolean`</td>
+      <td>`true`</td>
+      <td>Toggles visibility of the slotted metric cards grid.</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-summary-complete`</td>
+      <td>`true` / `true`</td>
+      <td>`{ text: string }`</td>
+      <td>Emitted when the dynamic typing animation finishes and reveals slotted metric cards.</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>`--ds-summary-bg`</td>
+      <td>`var(--overlay-glass-bg, rgba(235, 235, 240, 0.6))`</td>
+      <td>Overrides background container surface color.</td>
+    </tr>
+    <tr>
+      <td>`--ds-summary-border-color`</td>
+      <td>`var(--color-surface-border, rgba(0, 0, 0, 0.08))`</td>
+      <td>Overrides summary block border color.</td>
+    </tr>
+    <tr>
+      <td>`--ds-summary-header-color`</td>
+      <td>`var(--color-accent, #2B71F0)`</td>
+      <td>Overrides header label font color.</td>
+    </tr>
+    <tr>
+      <td>`--ds-summary-text-color`</td>
+      <td>`var(--color-black, #000000)`</td>
+      <td>Overrides summary body copy font color.</td>
+    </tr>
+    <tr>
+      <td>`--ds-summary-padding`</td>
+      <td>`12px 16px`</td>
+      <td>Overrides internal container padding.</td>
+    </tr>
+  </tbody>
+</table>
+
+---
+
+## Accessibility & Host ARIA Delegation
+
+* **ARIA Scrubbing:** Purges host-level `aria-label` attributes and delegates them downstream onto the internal Shadow DOM summary container.
+* **Live Regions:** Renders `aria-live="polite"` on the summary text container to inform screen readers as dynamic typing updates finish.
+* **Global Accessibility Propagation:** Listens to class changes on `document.documentElement` via `MutationObserver` to sync accessibility modes:
+  * `.a11y-dark-mode`: Adjusts glass container, border, and text contrast levels.
+  * `.a11y-high-contrast`: Enforces solid black background and 2px solid white borders.
+  * `.a11y-large-text`: Scales body copy font size to 18px and header to 13px.
+  * `.a11y-dyslexia`: Applies high-legibility letter spacing and font stacks.

package/src/stories/molecules/Summary/Summary.Changelog.mdx

@@ -0,0 +1,34 @@
+import { Meta, Subtitle, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Molecules/Summary/Changelog" />
+
+# Changelog
+
+<br />
+
+## [1.0.0] - 2026-07-20
+
+<br />
+
+### Initial Release
+
+The stable debut of the presentational summary molecule (`ds-summary`) featuring audio-player glassmorphic styling, localizable text attributes, typing animations, controllable metric grid toggles, and full Storybook metrics integration.
+
+<br />
+
+### Added
+- **Presentational Summary Molecule:** Created `<ds-summary>` composing slotted `ds-metric-card` children.
+- **Glassmorphic Audio-Player Styling:** Aligned container borders, padding, radii, and backdrop filters with `audio-player.css` design token specifications.
+- **Header Label & Icon Clean Up:** Removed AI icon in favor of clean typographic header defaulting to `"Summary"`.
+- **Metrics Toggle Prop:** Added `show-metrics` boolean attribute allowing host applications to turn the slotted metric cards grid on and off.
+- **Full Storybook Metrics Control Integration:** Exposed controls for all slotted `ds-metric-card` props directly inside the Storybook controls panel.
+- **Upstream Completion Event:** Added `ds-summary-complete` CustomEvent payload emitted when typing animation finishes.
+- **Root Class Syncing:** Configured passive `MutationObserver` on `document.documentElement` reflecting global setting cascades (`a11y-dark-mode`, `a11y-high-contrast`, `a11y-large-text`, etc.) downstream as host element boolean attributes.
+
+### Fixed
+- **Sub-Atomic Token Hooks:** Refactored generic variables in `summary.css` to adhere to the `--ds-summary-*` layout standard (`--ds-summary-bg`, `--ds-summary-border-color`, `--ds-summary-header-color`, `--ds-summary-text-color`, `--ds-summary-padding`).
+- **Preview Canvas Clean Up:** Removed canvas prewire wrapper tags from Storybook stories so `<ds-summary>` renders directly inside iframe viewports.
+
+---
+
+*This changelog is specific to the `<ds-summary>` component. For design system global releases, refer to the main [Getting Started/Changelog](?path=/docs/getting-started-changelog--docs).*