@brad-frost-web/eddie-web-components 0.18.0 → 0.19.0

package/.storybook/components/system-docs/system-docs.stories.ts

@@ -1,8 +1,8 @@
 import '@brad-frost-web/eddie-web-components/components/layout-container/layout-container';
 import MarkdownIt from 'markdown-it';
-import Code from '../../../docs/CODE_GUIDELINES.md?raw';
-import ThemingDocus from '../../../docs/THEMING.md?raw';
-import TokenDocs from '../../../docs/TOKENS.md?raw';
+import Code from '../../../../../docs/CODE_GUIDELINES.md?raw';
+import ThemingDocus from '../../../../../docs/THEMING.md?raw';
+import TokenDocs from '../../../../../docs/TOKENS.md?raw';
 import './system-docs';
 
 export default {

package/.storybook/components/tier-2-tokens/colors.ts

@@ -66,6 +66,10 @@ export class Tier2Colors extends LitElement {
     return filtered;
   }
 
+  getAccentNumbers() {
+    return [1, 2, 3, 4, 5, 6, 7, 8];
+  }
+
   render() {
     return html`<ed-section>
         <ed-heading slot="header" tagName="h2" variant="headline-lg">Background Colors</ed-heading>
@@ -145,6 +149,45 @@ export class Tier2Colors extends LitElement {
             </ed-grid>
           </ed-grid-item>
         </ed-grid>
+      </ed-section>
+
+      <ed-section>
+        <ed-heading slot="header" tagName="h2" variant="headline-lg">On-Accent Token Demos</ed-heading>
+        <ed-text-passage slot="header">
+          <p>Each accent background is paired with its <code>on-accent</code> content and border tokens to ensure proper contrast. The background uses <code>--ed-theme-color-background-accent-N</code>, the text uses <code>--ed-theme-color-content-on-accent-N</code>, and the inner border uses <code>--ed-theme-color-border-on-accent-N</code>.</p>
+        </ed-text-passage>
+        <ed-grid>
+          <ed-grid-item>
+            <ed-grid variant="1-3up">
+              ${this.getAccentNumbers().map((n) => {
+                const bgToken = `--ed-theme-color-background-accent-${n}`;
+                const contentToken = `--ed-theme-color-content-on-accent-${n}`;
+                const borderToken = `--ed-theme-color-border-on-accent-${n}`;
+                return html`
+                  <ed-grid-item>
+                    <div class="on-accent-demo">
+                      <div class="on-accent-demo__swatch" style="background-color: var(${bgToken}); padding: 1.5rem;">
+                        <div class="on-accent-demo__inner" style="border: 3px solid var(${borderToken}); padding: 1rem; border-radius: 4px;">
+                          <p class="on-accent-demo__text" style="color: var(${contentToken}); margin: 0; font-weight: 700;">
+                            On Accent ${n}
+                          </p>
+                          <p class="on-accent-demo__subtext" style="color: var(${contentToken}); margin: 0.25rem 0 0; font-size: 0.875rem; opacity: 0.85;">
+                            Content and border contrast
+                          </p>
+                        </div>
+                      </div>
+                      <div class="on-accent-demo__info">
+                        <code class="on-accent-demo__token">bg: ${bgToken}</code>
+                        <code class="on-accent-demo__token">content: ${contentToken}</code>
+                        <code class="on-accent-demo__token">border: ${borderToken}</code>
+                      </div>
+                    </div>
+                  </ed-grid-item>
+                `;
+              })}
+            </ed-grid>
+          </ed-grid-item>
+        </ed-grid>
       </ed-section>`;
   }
 }

package/.storybook/components/tier-2-tokens/tier-2-tokens.scss

@@ -13,3 +13,50 @@ ul {
 li {
   margin-block-end: 1rem;
 }
+
+/**
+ * On-accent demo styles
+ */
+.on-accent-demo {
+  border: 1px solid var(--ed-theme-color-border-subtle);
+  overflow: hidden;
+}
+
+.on-accent-demo__swatch {
+  min-height: 6rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.on-accent-demo__inner {
+  width: 100%;
+}
+
+.on-accent-demo__text {
+  font-family: var(--ed-theme-typography-label-default-font-family, sans-serif);
+  font-size: 1.125rem;
+}
+
+.on-accent-demo__subtext {
+  font-family: var(--ed-theme-typography-body-sm-font-family, sans-serif);
+}
+
+.on-accent-demo__info {
+  padding: 0.75rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.on-accent-demo__token {
+  display: block;
+  font-size: 0.75rem;
+  background: rgb(242, 242, 242);
+  color: rgb(235, 87, 87);
+  padding: 0.15rem 0.3rem;
+  border-radius: 3px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}

package/.storybook/main.ts

@@ -4,8 +4,8 @@ const config: StorybookConfig = {
   stories: [
     './components/**/*.stories.@(js|jsx|ts|tsx|mdx)',
     '../components/**/*.stories.@(js|jsx|mjs|ts|tsx)',
-    './recipes/**/*.stories.@(js|jsx|mjs|ts|tsx)',
     './pages/**/*.stories.@(js|jsx|mjs|ts|tsx)',
+    '../../eddie-recipes/recipes/**/*.stories.@(js|jsx|mjs|ts|tsx)',
   ],
   addons: ['@chromatic-com/storybook', '@storybook/addon-docs', '@storybook/addon-themes', '@storybook/addon-a11y', '@storybook/addon-vitest'],
   framework: {

package/.storybook/pages/homepage/homepage.ts

@@ -9,9 +9,9 @@ import '../../../components/layout-container/layout-container';
 import '../../../components/main/main';
 import '../../../components/page-header/page-header';
 import '../../../components/text-passage/text-passage';
-import '../../recipes/promo-block/promo-block';
-import '../../recipes/site-footer/site-footer';
-import '../../recipes/site-header/site-header';
+import '@brad-frost-web/eddie-recipes/recipes/common/promo-block/promo-block';
+import '@brad-frost-web/eddie-recipes/recipes/common/site-footer/site-footer';
+import '@brad-frost-web/eddie-recipes/recipes/common/site-header/site-header';
 
 export class Homepage extends LitElement {
   handleCloseBlackFridayDrawer(event: CustomEvent) {
@@ -20,13 +20,13 @@ export class Homepage extends LitElement {
   render() {
     return html`
       <div style="display: flex; flex-direction: column; min-height: 100vh;">
-        <site-header></site-header>
+        <ed-r-site-header></ed-r-site-header>
         <ed-main class="ed-u-display-block ed-u-margin-bottom-xl">
           <ed-hero imgSrc="images/1200x650.svg" imgAlt="Hero Alt Text">
             <ed-heading tagName="h2">Hero title</ed-heading>
             <ed-text-passage>This is the hero description</ed-text-passage>
           </ed-hero>
-          <promo-block class="ed-u-display-block ed-u-margin-bottom-xl"></promo-block>
+          <ed-r-promo-block class="ed-u-display-block ed-u-margin-bottom-xl"></ed-r-promo-block>
           <ed-layout-container>
             <ed-grid variant="1-3up">
               <ed-grid-item>
@@ -56,7 +56,7 @@ export class Homepage extends LitElement {
             </ed-grid>
           </ed-layout-container>
         </ed-main>
-        <site-footer></site-footer>
+        <ed-r-site-footer></ed-r-site-footer>
       </div>
     `;
   }

package/README.md

@@ -1,45 +1,57 @@
-# Eddie Design System
+# Eddie Web Components
 
-Eddie Design System provides presentational UI components to be consumed by [COMPANY NAME] web applications.
+`@brad-frost-web/eddie-web-components` — the core Lit web component library for Eddie Design System.
 
-## Developing Locally
+This package provides presentational UI components (buttons, cards, forms, navigation, layout, etc.) organized by [atomic design](https://atomicdesign.bradfrost.com/chapter-2/#the-atomic-design-methodology): Atoms, Molecules, and Organisms.
 
-First, clone the repository and install the project dependencies:
+## Usage
 
 ```bash
-npm install --legacy-peer-deps
+npm install @brad-frost-web/eddie-web-components
 ```
 
-Note, because of a peer dependency issue with `reach/router` it is necessary to install with `--legacy-peer-deps` for the
-time being. This will no longer be necessary once Storybook updates to 6.4, tracked here:
-https://github.com/storybookjs/storybook/issues/14619.
+```js
+import '@brad-frost-web/eddie-web-components/components/button/button';
+```
+
+```html
+<ed-button text="Click me" variant="primary"></ed-button>
+```
+
+## Development
+
+See the [root README](../../README.md) for monorepo setup instructions and the [code guidelines](../../docs/CODE_GUIDELINES.md) for conventions.
 
-Then, run the project with the following command
+### Scaffold a new component
 
 ```bash
-npm start
+npm run eddie-web-components:plop
 ```
 
-This will build the project and open Storybook at http://localhost:6006 in your browser.
+### Run tests
 
-## Working with the library
+```bash
+npx vitest
+```
 
-Please read the [code guidelines documentation](docs/CODE_GUIDELINES.md) in order to successfully develop with and contribute to the library.
+## Component structure
 
-If you use VS Code, we highly recommend the [lit-plugin extension](https://marketplace.visualstudio.com/items?itemName=runem.lit-plugin), which enables some extremely useful features for lit-html templates:
+Each component lives in `components/<name>/`:
 
-- Syntax highlighting
-- Type-checking
-- Code completion
-- Hover-over docs
-- Jump to definition
-- Linting
-- Quick Fixes
+```
+components/button/
+├── button.ts              # Component class extending EdElement
+├── button.scss            # Scoped BEM styles
+├── button.stories.ts      # Storybook stories
+└── test/
+    └── button.test.ts     # Unit tests
+```
 
-## Build
+## Base classes
 
-TODO
+- **`EdElement`** — Root base class extending `LitElement`. Provides `componentClassNames()`, `slotEmpty()`, and `dispatch()`.
+- **`EdFormElement`** — Extends `EdElement` for form-associated components with `ElementInternals` support.
 
-## Support
+## Editor support
 
-TODO
+The [lit-plugin extension](https://marketplace.visualstudio.com/items?itemName=runem.lit-plugin) for VS Code / Cursor provides syntax highlighting, type-checking, code completion, hover docs, and linting for Lit templates.

package/cdn/eddie-autoloader.ts

@@ -0,0 +1,197 @@
+/**
+ * Eddie Autoloader
+ *
+ * Watches the DOM for any `ed-*` custom elements and automatically
+ * lazy-loads their component definitions on demand. This means you
+ * only pay for the components you actually use in your HTML.
+ *
+ * Usage (CDN):
+ *   <script type="module" src="https://cdn.jsdelivr.net/npm/@brad-frost-web/eddie-web-components@VERSION/cdn/eddie-autoloader.js"></script>
+ *
+ * Usage (local):
+ *   <script type="module" src="./node_modules/@brad-frost-web/eddie-web-components/cdn/eddie-autoloader.js"></script>
+ */
+
+// Tag → module path mapping. The autoloader resolves paths relative to itself.
+const COMPONENT_MAP: Record<string, string> = {
+  'ed-accordion': './components/accordion/accordion.js',
+  'ed-accordion-panel': './components/accordion-panel/accordion-panel.js',
+  'ed-alert': './components/alert/alert.js',
+  'ed-badge': './components/badge/badge.js',
+  'ed-band': './components/band/band.js',
+  'ed-black-friday-banner': './components/black-friday-banner/black-friday-banner.js',
+  'ed-black-friday-modal': './components/black-friday-modal/black-friday-modal.js',
+  'ed-box': './components/box/box.js',
+  'ed-breadcrumbs': './components/breadcrumbs/breadcrumbs.js',
+  'ed-breadcrumbs-item': './components/breadcrumbs-item/breadcrumbs-item.js',
+  'ed-button': './components/button/button.js',
+  'ed-button-group': './components/button-group/button-group.js',
+  'ed-card': './components/card/card.js',
+  'ed-checkbox-field': './components/checkbox-field/checkbox-field.js',
+  'ed-checkbox-field-item': './components/checkbox-field-item/checkbox-field-item.js',
+  'ed-counter': './components/counter/counter.js',
+  'ed-drawer': './components/drawer/drawer.js',
+  'ed-feature': './components/feature/feature.js',
+  'ed-field-note': './components/field-note/field-note.js',
+  'ed-file-upload': './components/file-upload/file-upload.js',
+  'ed-footer': './components/footer/footer.js',
+  'ed-global-nav': './components/global-nav/global-nav.js',
+  'ed-global-nav-item': './components/global-nav-item/global-nav-item.js',
+  'ed-grid': './components/grid/grid.js',
+  'ed-grid-item': './components/grid-item/grid-item.js',
+  'ed-header': './components/header/header.js',
+  'ed-heading': './components/heading/heading.js',
+  'ed-hero': './components/hero/hero.js',
+  'ed-hr': './components/hr/hr.js',
+  'ed-icon': './components/icon/icon.js',
+  'ed-icon-link-list': './components/icon-link-list/icon-link-list.js',
+  'ed-icon-link-list-item': './components/icon-link-list-item/icon-link-list-item.js',
+  'ed-inline-checkbox': './components/inline-checkbox/inline-checkbox.js',
+  'ed-key-value-table': './components/key-value-table/key-value-table.js',
+  'ed-key-value-table-row': './components/key-value-table-row/key-value-table-row.js',
+  'ed-layout': './components/layout/layout.js',
+  'ed-layout-container': './components/layout-container/layout-container.js',
+  'ed-layout-section': './components/layout-section/layout-section.js',
+  'ed-linelength-container': './components/linelength-container/linelength-container.js',
+  'ed-link-list': './components/link-list/link-list.js',
+  'ed-link-list-item': './components/link-list-item/link-list-item.js',
+  'ed-list': './components/list/list.js',
+  'ed-list-item': './components/list-item/list-item.js',
+  'ed-loading-indicator': './components/loading-indicator/loading-indicator.js',
+  'ed-logo': './components/logo/logo.js',
+  'ed-main': './components/main/main.js',
+  'ed-media-block': './components/media-block/media-block.js',
+  'ed-modal': './components/modal/modal.js',
+  'ed-nav-container': './components/nav-container/nav-container.js',
+  'ed-page-header': './components/page-header/page-header.js',
+  'ed-pagination': './components/pagination/pagination.js',
+  'ed-pagination-item': './components/pagination-item/pagination-item.js',
+  'ed-primary-nav': './components/primary-nav/primary-nav.js',
+  'ed-primary-nav-item': './components/primary-nav-item/primary-nav-item.js',
+  'ed-radio-field': './components/radio-field/radio-field.js',
+  'ed-radio-field-item': './components/radio-field-item/radio-field-item.js',
+  'ed-search-form': './components/search-form/search-form.js',
+  'ed-section': './components/section/section.js',
+  'ed-select-field': './components/select-field/select-field.js',
+  'ed-show-hide': './components/show-hide/show-hide.js',
+  'ed-show-more': './components/show-more/show-more.js',
+  'ed-skeleton': './components/skeleton/skeleton.js',
+  'ed-tab': './components/tab/tab.js',
+  'ed-table': './components/table/table.js',
+  'ed-table-body': './components/table-body/table-body.js',
+  'ed-table-cell': './components/table-cell/table-cell.js',
+  'ed-table-header': './components/table-header/table-header.js',
+  'ed-table-header-cell': './components/table-header-cell/table-header-cell.js',
+  'ed-table-object': './components/table-object/table-object.js',
+  'ed-table-row': './components/table-row/table-row.js',
+  'ed-tabs': './components/tabs/tabs.js',
+  'ed-tag': './components/tag/tag.js',
+  'ed-tag-list': './components/tag-list/tag-list.js',
+  'ed-text-field': './components/text-field/text-field.js',
+  'ed-text-link': './components/text-link/text-link.js',
+  'ed-text-passage': './components/text-passage/text-passage.js',
+  'ed-textarea-field': './components/textarea-field/textarea-field.js',
+  'ed-toast': './components/toast/toast.js',
+  'ed-toggle': './components/toggle/toggle.js',
+  'ed-toolbar': './components/toolbar/toolbar.js',
+  'ed-tooltip': './components/tooltip/tooltip.js',
+  'ed-tooltip-trigger': './components/tooltip-trigger/tooltip-trigger.js',
+  'ed-utility-nav': './components/utility-nav/utility-nav.js',
+  'ed-utility-nav-item': './components/utility-nav-item/utility-nav-item.js'
+};
+
+// Detect the base path from this script's location
+let basePath: string;
+
+function getBasePath(): string {
+  if (basePath !== undefined) return basePath;
+
+  // Try to detect from the current script's src attribute
+  const scripts = document.querySelectorAll('script[src]');
+  for (const script of scripts) {
+    const src = script.getAttribute('src') || '';
+    if (src.includes('eddie-autoloader')) {
+      basePath = src.substring(0, src.lastIndexOf('/') + 1);
+      return basePath;
+    }
+  }
+
+  // Fallback: try import.meta.url
+  if (import.meta.url) {
+    basePath = import.meta.url.substring(0, import.meta.url.lastIndexOf('/') + 1);
+    return basePath;
+  }
+
+  // Last resort
+  basePath = '';
+  return basePath;
+}
+
+/**
+ * Override the base path for component resolution.
+ * Useful when self-hosting Eddie assets at a custom location.
+ */
+export function setBasePath(path: string): void {
+  basePath = path.endsWith('/') ? path : path + '/';
+}
+
+// Track which components are currently being loaded
+const loading = new Set<string>();
+
+async function loadComponent(tagName: string): Promise<void> {
+  if (loading.has(tagName)) return;
+  if (customElements.get(tagName)) return;
+
+  const modulePath = COMPONENT_MAP[tagName];
+  if (!modulePath) return;
+
+  loading.add(tagName);
+
+  try {
+    const resolvedPath = getBasePath() + modulePath;
+    await import(resolvedPath);
+  } catch (err) {
+    console.error(`[Eddie] Failed to load component: ${tagName}`, err);
+  }
+}
+
+// Scan existing DOM for undefined ed-* elements
+function scanDOM(root: ParentNode = document.body): void {
+  const undefinedElements = root.querySelectorAll(':not(:defined)');
+  for (const el of undefinedElements) {
+    const tagName = el.tagName.toLowerCase();
+    if (tagName.startsWith('ed-') && COMPONENT_MAP[tagName]) {
+      loadComponent(tagName);
+    }
+  }
+}
+
+// Watch for new ed-* elements added to the DOM
+const observer = new MutationObserver((mutations) => {
+  for (const mutation of mutations) {
+    for (const node of mutation.addedNodes) {
+      if (node instanceof HTMLElement) {
+        const tagName = node.tagName.toLowerCase();
+        if (tagName.startsWith('ed-') && COMPONENT_MAP[tagName]) {
+          loadComponent(tagName);
+        }
+        // Also scan children of the added node
+        scanDOM(node);
+      }
+    }
+  }
+});
+
+// Start observing once DOM is ready
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', () => {
+    scanDOM();
+    observer.observe(document.body, { subtree: true, childList: true });
+  });
+} else {
+  scanDOM();
+  observer.observe(document.body, { subtree: true, childList: true });
+}
+
+// Export version info
+export const EDDIE_VERSION = '__EDDIE_VERSION__';

package/cdn/eddie.ts

@@ -0,0 +1,100 @@
+/**
+ * Eddie — Full Bundle
+ *
+ * Imports and registers ALL Eddie web components at once.
+ * Use this when you want everything available immediately
+ * without waiting for lazy loading.
+ *
+ * Usage:
+ *   <script type="module" src="https://cdn.jsdelivr.net/npm/@brad-frost-web/eddie-web-components@VERSION/cdn/eddie.js"></script>
+ *
+ * For lazy loading (better performance), use eddie-autoloader.js instead.
+ */
+
+// All components — auto-register on import
+import '../components/accordion/accordion';
+import '../components/accordion-panel/accordion-panel';
+import '../components/alert/alert';
+import '../components/badge/badge';
+import '../components/band/band';
+import '../components/black-friday-banner/black-friday-banner';
+import '../components/black-friday-modal/black-friday-modal';
+import '../components/box/box';
+import '../components/breadcrumbs/breadcrumbs';
+import '../components/breadcrumbs-item/breadcrumbs-item';
+import '../components/button/button';
+import '../components/button-group/button-group';
+import '../components/card/card';
+import '../components/checkbox-field/checkbox-field';
+import '../components/checkbox-field-item/checkbox-field-item';
+import '../components/counter/counter';
+import '../components/drawer/drawer';
+import '../components/feature/feature';
+import '../components/field-note/field-note';
+import '../components/file-upload/file-upload';
+import '../components/footer/footer';
+import '../components/global-nav/global-nav';
+import '../components/global-nav-item/global-nav-item';
+import '../components/grid/grid';
+import '../components/grid-item/grid-item';
+import '../components/header/header';
+import '../components/heading/heading';
+import '../components/hero/hero';
+import '../components/hr/hr';
+import '../components/icon/icon';
+import '../components/icon-link-list/icon-link-list';
+import '../components/icon-link-list-item/icon-link-list-item';
+import '../components/inline-checkbox/inline-checkbox';
+import '../components/key-value-table/key-value-table';
+import '../components/key-value-table-row/key-value-table-row';
+import '../components/layout/layout';
+import '../components/layout-container/layout-container';
+import '../components/layout-section/layout-section';
+import '../components/linelength-container/linelength-container';
+import '../components/link-list/link-list';
+import '../components/link-list-item/link-list-item';
+import '../components/list/list';
+import '../components/list-item/list-item';
+import '../components/loading-indicator/loading-indicator';
+import '../components/logo/logo';
+import '../components/main/main';
+import '../components/media-block/media-block';
+import '../components/modal/modal';
+import '../components/nav-container/nav-container';
+import '../components/page-header/page-header';
+import '../components/pagination/pagination';
+import '../components/pagination-item/pagination-item';
+import '../components/primary-nav/primary-nav';
+import '../components/primary-nav-item/primary-nav-item';
+import '../components/radio-field/radio-field';
+import '../components/radio-field-item/radio-field-item';
+import '../components/search-form/search-form';
+import '../components/section/section';
+import '../components/select-field/select-field';
+import '../components/show-hide/show-hide';
+import '../components/show-more/show-more';
+import '../components/skeleton/skeleton';
+import '../components/tab/tab';
+import '../components/table/table';
+import '../components/table-body/table-body';
+import '../components/table-cell/table-cell';
+import '../components/table-header/table-header';
+import '../components/table-header-cell/table-header-cell';
+import '../components/table-object/table-object';
+import '../components/table-row/table-row';
+import '../components/tabs/tabs';
+import '../components/tag/tag';
+import '../components/tag-list/tag-list';
+import '../components/text-field/text-field';
+import '../components/text-link/text-link';
+import '../components/text-passage/text-passage';
+import '../components/textarea-field/textarea-field';
+import '../components/toast/toast';
+import '../components/toggle/toggle';
+import '../components/toolbar/toolbar';
+import '../components/tooltip/tooltip';
+import '../components/tooltip-trigger/tooltip-trigger';
+import '../components/utility-nav/utility-nav';
+import '../components/utility-nav-item/utility-nav-item';
+
+export const EDDIE_VERSION = '__EDDIE_VERSION__';

package/components/accordion/accordion.stories.ts

@@ -3,11 +3,21 @@ import {spread} from '../../directives/spread';
 import '../accordion-panel/accordion-panel';
 import './accordion';
 
+/**
+ * Accordion component for organizing collapsible content panels.
+ *
+ * Accordions group content into expandable/collapsible sections. One panel can be open at a time,
+ * with smooth height animations when toggling. Compose with `ed-accordion-panel` children, using the `header` slot for titles and the default slot for content.
+ */
 export default {
   title: 'Organisms/Interactive/Accordion',
   component: 'ed-accordion',
 };
 
+/**
+ * Default accordion with multiple panels. First panel is expanded by default.
+ * Demonstrates the standard accordion composition and smooth open/close interactions.
+ */
 export const Default = (args) =>
   html`<ed-accordion ${spread(args)}>
     <ed-accordion-panel ?isActive=${true}>
@@ -29,6 +39,10 @@ export const Default = (args) =>
     </ed-accordion-panel>
   </ed-accordion>`;
 
+/**
+ * Accordion with inverted colors for dark backgrounds.
+ * Use on dark surfaces where the default colors would not have sufficient contrast.
+ */
 export const Inverted = () =>
   html` <div style="background: #000; padding: 1rem;">
     <ed-accordion ?inverted=${true}>

package/components/accordion/accordion.ts

@@ -4,9 +4,23 @@ import { EdElement } from '@brad-frost-web/eddie-web-components/components/EdEle
 import styles from './accordion.scss?inline';
 
 /**
- * @slot - The component content
+ * An accordion container that groups collapsible panels for progressive content disclosure.
+ * Renders as semantic `<dl>` element with accordion-panel children.
+ * Panels can be independently toggled open/closed with smooth height animations.
+ * Only the active panel is expanded; clicking another panel closes the previously active one.
+ *
+ * Use accordions to:
+ * - Organize large content sections (FAQs, product features, documentation)
+ * - Show/hide detailed information progressively
+ * - Create expandable content lists with clear interactions
+ * - Group related information hierarchically
+ *
+ * Each accordion-panel contains:
+ * - A header slot with the panel title (rendered in a button trigger)
+ * - Default slot content that expands/collapses
+ *
+ * @slot - Accordion panels (ed-accordion-panel elements)
  */
-
 export class EdAccordion extends EdElement {
   static get styles() {
     return unsafeCSS(styles.toString());

package/components/accordion-panel/accordion-panel.ts

@@ -6,7 +6,20 @@ import styles from './accordion-panel.scss?inline';
 import '../icon/icon';
 
 /**
- * @slot - The component content
+ * An accordion panel for use within ed-accordion containers.
+ * Each panel has a collapsible header section and expandable content body with smooth height animation.
+ * Panels render as semantic `<dl>` > `<dt>` (header) + `<dd>` (content) elements.
+ *
+ * Use slots:
+ * - `header`: The panel title/heading (rendered in a clickable button)
+ * - default: The panel content body (expands/collapses with animation)
+ *
+ * Properties:
+ * - `isActive`: Set to true to expand the panel (expands on init and toggle)
+ * - `fullyOpen`: Internal state for animation completion (do not set directly)
+ *
+ * @slot header - Panel title/heading
+ * @slot - Panel content body (expands/collapses)
  */
 export class EdAccordionPanel extends EdElement {
   static get styles() {