@repobit/dex-system-design 0.24.8 → 0.24.10

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.24.10](https://github.com/bitdefender/dex-core/compare/@repobit/dex-system-design@0.24.9...@repobit/dex-system-design@0.24.10) (2026-09-08)
+
+**Note:** Version bump only for package @repobit/dex-system-design
+
+
+
+
+
+## [0.24.9](https://github.com/bitdefender/dex-core/compare/@repobit/dex-system-design@0.24.8...@repobit/dex-system-design@0.24.9) (2026-09-08)
+
+### Bug Fixes
+
+* **DEX-1014:** new AI Bitdefender components and anchor nav changes
+
+
 ## [0.24.8](https://github.com/bitdefender/dex-core/compare/@repobit/dex-system-design@0.24.7...@repobit/dex-system-design@0.24.8) (2026-09-08)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repobit/dex-system-design",
-  "version": "0.24.8",
+  "version": "0.24.10",
   "description": "Design system based on Web Components.",
   "author": "Iordache Matei Cezar <miordache@bitdefender.com>",
   "homepage": "https://github.com/bitdefender/dex-core#readme",
@@ -74,8 +74,8 @@
     "url": "https://github.com/bitdefender/dex-core/issues"
   },
   "dependencies": {
-    "@repobit/dex-store": "1.6.24",
-    "@repobit/dex-store-elements": "2.0.29",
+    "@repobit/dex-store": "1.6.26",
+    "@repobit/dex-store-elements": "2.0.31",
     "lit": "^3.3.2"
   },
   "devDependencies": {
@@ -92,5 +92,5 @@
   "volta": {
     "node": "24.14.0"
   },
-  "gitHead": "bf388f1fa589bd68fb763b66bb7ed9e2e598724c"
+  "gitHead": "bed8fc04b957945c0fccba6068d9395f768cfd5a"
 }

package/src/components/ai-guardian-demo.stories.js

@@ -93,6 +93,7 @@ function aiGuardianBody() {
         aria-label="Page sections"
         cta-label="Download BETA Today"
         cta-href="#download"
+        sticky-top="65px"
         .items=${[
           { title: "Overview" },
           { title: "Compatibility" },
@@ -498,6 +499,7 @@ function skillScannerBody() {
     <div style="max-width: 1200px; margin: 0 auto;">
       <bd-anchor-nav
         aria-label="Skill Scanner sections"
+        sticky-top="65px"
         .items=${[
           { title: "Install" },
           { title: "Overview" },
@@ -1034,11 +1036,15 @@ switches, in place, between two full "pages" without any real navigation —
 clicking a tab intercepts the anchor click and swaps local state instead of
 following the href (which has no route in Storybook and would 404).
 
+Both anchor-nav bars use \`sticky-top="65px"\` so they pin themselves *below*
+the sticky page-switcher instead of overlapping it once scrolled. That value
+is an estimate — measure bd-page-switcher's real rendered height in DevTools
+and adjust if the two bars still overlap or leave a gap.
+
 **AI Guardian** page: \`bd-header-code\`, \`bd-quick-answer\`, sticky \`bd-anchor-nav\`
 (9 items) wrapping \`bd-overview\`, \`bd-compatibility-table\` (default variant), the
 "Protections" section (\`bd-bento-grid\` + \`bd-comparison-panel\`), \`bd-process-steps\`,
-\`bd-compatibility-table\` (\`variant="outcome"\`), two chevron \`bd-accordion-item\`s
-revealing \`bd-compatibility-table\` (\`variant="risk"\` / \`variant="light"\`), an FAQ
+\`bd-compatibility-table\` (\`variant="risk"\` / \`variant="light"\`), an FAQ
 section (\`bd-accordion-bg\`, 9 questions), \`bd-cta-banner\`, \`bd-agent-endpoints\`,
 and \`bd-trust-panel\`.
 
@@ -1049,8 +1055,9 @@ Install, Overview, What it detects, How it works, Privacy, FAQ) wrapping
 a \`bd-compatibility-table\` inside a chevron accordion, a \`bd-bento-grid\` +
 \`bd-process-steps\` + another \`bd-compatibility-table\` for "How it works",
 another \`bd-install-options\` (generic-slot variant: table + checklist + note)
-for "Privacy", and a \`bd-trust-panel\` under "FAQ". The FAQ accordion itself
-(actual questions) is still a placeholder — content not provided yet.
+for "Privacy", a \`bd-trust-panel\` + \`bd-accordion-bg\` FAQ (7 questions) under
+"FAQ", a \`bd-cta-banner\`, and \`bd-agent-endpoints\` with legal copy in its
+\`rows\` slot.
 
 Both pages share the same \`bd-footer\` at the bottom.
         `

package/src/components/anchor/anchor-nav.css.js

@@ -11,14 +11,17 @@ export const anchorNavStyles = css`
 
   :host(.is-sticky) {
     position: fixed;
-    top: 0;
+    top: var(--sticky-top, 0);
     left: var(--sticky-left, 0);
     width: var(--sticky-width, 100%);
     box-shadow: var(--shadow-sm);
     z-index: 1000;
   }
 
-  /* Border-urile sunt pe nav - full width */
+  :host(.is-sticky) nav {
+    background: var(--color-neutral-0);
+  }
+
   nav {
     display: block;
     margin: var(--spacing-0);
@@ -29,11 +32,6 @@ export const anchorNavStyles = css`
     border-bottom: var(--border-width-1) solid var(--color-neutral-100);
   }
 
-  /* Când e sticky, păstrăm aceleași border-uri */
-  :host(.is-sticky) nav {
-    background: var(--color-neutral-0);
-  }
-
   .bd-anchor-nav__inner {
     display: flex;
     flex-wrap: wrap;
@@ -48,7 +46,6 @@ export const anchorNavStyles = css`
     box-sizing: border-box;
   }
 
-  /* Restul codului tău CSS rămâne identic de aici în jos */
   
   .anchor-link:focus-visible,
   .bd-anchor-nav__cta:focus-visible,
@@ -118,19 +115,19 @@ export const anchorNavStyles = css`
     text-decoration: none !important;
   }
 
-  .anchor-link::after {
-    content: "";
+
+  .anchor-indicator {
     position: absolute;
-    left: var(--spacing-0);
+    left: 0;
     bottom: calc(-1 * var(--spacing-14));
-    width: 0%;
+    width: 0;
     height: var(--border-width-3);
     background-color: var(--color-blue-500);
-    transition: width var(--transition-duration-slow) var(--transition-easing-ease-out);
-  }
-
-  .anchor-link.active::after {
-    width: 100%;
+    transform: translateX(0);
+    transition:
+      transform var(--transition-duration-slow) var(--transition-easing-ease-out),
+      width var(--transition-duration-slow) var(--transition-easing-ease-out);
+    pointer-events: none;
   }
 
   .bd-anchor-nav__dropdown {
@@ -299,10 +296,11 @@ export const anchorNavStyles = css`
   }
 
   @media (prefers-reduced-motion: reduce) {
-    .anchor-link::after,
+    .anchor-indicator,
     .bd-anchor-nav__dropdown-chevron,
     .bd-cta,
     .bd-anchor-nav__dropdown-label--swap {
+      transition: none !important;
       animation: none !important;
     }
   }

package/src/components/anchor/anchor-nav.js

@@ -33,7 +33,12 @@ class BdAnchorNav extends LitElement {
     ctaLabel          : { type: String, attribute: "cta-label" },
     ctaHref           : { type: String, attribute: "cta-href" },
     items             : { type: Array },
-    maxWidth          : { type: String, attribute: "max-width" }
+    maxWidth          : { type: String, attribute: "max-width" },
+    // How far from the viewport top this nav sticks once pinned — set this
+    // to the rendered height of whatever sticky element sits above it (e.g.
+    // a page-switcher), so the two don't stack on top of each other at
+    // top:0. Accepts any CSS length, e.g. "64px", "4rem".
+    stickyTop         : { type: String, attribute: "sticky-top" }
   };
 
   static styles = [tokens, anchorNavStyles];
@@ -48,6 +53,7 @@ class BdAnchorNav extends LitElement {
     this.ctaHref                     = "";
     this.items                       = null;
     this.maxWidth                    = "";
+    this.stickyTop                   = "0px";
     this._panelId                    = `bd-anchor-nav-panel-${Math.random().toString(36)
       .slice(2, 11)}`;
     this._onScrollSpy                = this._onScrollSpy.bind(this);
@@ -61,6 +67,10 @@ class BdAnchorNav extends LitElement {
     this._stickyPlaceholder          = null;
     this._onStickyScroll             = null;
     this._handleResize               = this._handleResize.bind(this);
+    // sliding underline indicator: false until the first successful
+    // measurement + placement, so it doesn't visibly animate in from the
+    // left edge on first paint.
+    this._indicatorReady             = false;
   }
 
   connectedCallback() {
@@ -85,8 +95,76 @@ class BdAnchorNav extends LitElement {
     this._destroySticky();
   }
 
+  updated(changedProperties) {
+    super.updated(changedProperties);
+
+    if (changedProperties.has("stickyTop")) {
+      this.style.setProperty("--sticky-top", this.stickyTop || "0px");
+      // the scroll-spy offset (how far to scroll past the sticky bar when
+      // clicking a link) depends on this too, since the nav's own visible
+      // top now sits lower than the viewport top while stuck.
+      this._runScrollSpy();
+    }
+
+    if (changedProperties.has("activeId") || changedProperties.has("items")) {
+      // wait a frame so the .active class has actually painted before
+      // measuring its box — requestAnimationFrame is enough here, no need
+      // for updateComplete since nothing else in render() depends on this.
+      requestAnimationFrame(() => this._updateIndicator());
+    }
+
+    if (!changedProperties.has("activeId")) return;
+    const prev = changedProperties.get("activeId");
+    if (prev === undefined || prev === "") return;
+    if (prev === this.activeId) return;
+    queueMicrotask(() => this._playMobileDropdownLabelSwap());
+  }
+
+  firstUpdated() {
+    const resolved = this._resolvedItems();
+    if (resolved.length) {
+      this.activeId = "anchor-1";
+      this.requestUpdate();
+    }
+    queueMicrotask(() => this._runScrollSpy());
+    this._handleMobileFullWidth();
+    requestAnimationFrame(() => this._updateIndicator());
+  }
+
+  // Positions the sliding underline under the currently active desktop
+  // link. Reads offsetLeft/offsetWidth directly off the active bd-link —
+  // as a flex item it's block-level regardless of its own :host display,
+  // so these are reliable without any extra math against a bounding rect.
+  _updateIndicator() {
+    const indicator = this.renderRoot?.querySelector(".anchor-indicator");
+    const activeLink = this.renderRoot?.querySelector(
+      ".anchor-links--desktop .anchor-link.active"
+    );
+    if (!indicator || !activeLink) return;
+
+    const left  = activeLink.offsetLeft;
+    const width = activeLink.offsetWidth;
+
+    if (!this._indicatorReady) {
+      // first placement: skip the transition so it doesn't slide in from
+      // the left edge on initial paint, then re-enable it next frame.
+      indicator.style.transition = "none";
+      indicator.style.transform  = `translateX(${left}px)`;
+      indicator.style.width      = `${width}px`;
+      // force a style flush before removing the transition override
+      void indicator.offsetWidth;
+      indicator.style.transition = "";
+      this._indicatorReady = true;
+      return;
+    }
+
+    indicator.style.transform = `translateX(${left}px)`;
+    indicator.style.width     = `${width}px`;
+  }
+
   _handleResize() {
     this._handleMobileFullWidth();
+    this._updateIndicator();
   }
 
   _handleMobileFullWidth() {
@@ -109,6 +187,7 @@ class BdAnchorNav extends LitElement {
 
   _initSticky() {
     this._stickyOriginalTop = null;
+    this.style.setProperty("--sticky-top", this.stickyTop || "0px");
 
     this._onStickyScroll = () => {
       const parent     = this.parentElement;
@@ -118,14 +197,15 @@ class BdAnchorNav extends LitElement {
       const navHeight  = this._stickyPlaceholder
         ? this._stickyPlaceholder.offsetHeight
         : this.offsetHeight;
+      const stickyTopPx = parseLengthToPx(this.stickyTop) || 0;
 
       if (this._stickyOriginalTop === null) {
         const rect = this.getBoundingClientRect();
-        this._stickyOriginalTop = rect.top + window.scrollY;
+        this._stickyOriginalTop = rect.top + window.scrollY - stickyTopPx;
       }
 
       const passedTop = window.scrollY >= this._stickyOriginalTop;
-      const parentExited = parentRect.bottom <= navHeight;
+      const parentExited = parentRect.bottom <= navHeight + stickyTopPx;
 
       if (passedTop && !parentExited) {
         if (!this.classList.contains("is-sticky")) {
@@ -297,25 +377,6 @@ class BdAnchorNav extends LitElement {
     }
   }
 
-  firstUpdated() {
-    const resolved = this._resolvedItems();
-    if (resolved.length) {
-      this.activeId = "anchor-1";
-      this.requestUpdate();
-    }
-    queueMicrotask(() => this._runScrollSpy());
-    this._handleMobileFullWidth();
-  }
-
-  updated(changedProperties) {
-    super.updated(changedProperties);
-    if (!changedProperties.has("activeId")) return;
-    const prev = changedProperties.get("activeId");
-    if (prev === undefined || prev === "") return;
-    if (prev === this.activeId) return;
-    queueMicrotask(() => this._playMobileDropdownLabelSwap());
-  }
-
   _playMobileDropdownLabelSwap() {
     if (typeof window === "undefined") return;
     if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) return;
@@ -334,10 +395,11 @@ class BdAnchorNav extends LitElement {
 
   _stickyOffsetPx() {
     const barPx    = this.offsetHeight;
+    const stickyTopPx = parseLengthToPx(this.stickyTop) || 0;
     const insetRaw = getComputedStyle(this).getPropertyValue("--spacing-8")
       .trim();
     const insetPx  = parseLengthToPx(insetRaw) || 8;
-    if (barPx > 0) return barPx + insetPx;
+    if (barPx > 0) return barPx + insetPx + stickyTopPx;
     const fallback = getComputedStyle(this).getPropertyValue("--spacing-128")
       .trim();
     return parseLengthToPx(fallback) || 128;
@@ -413,6 +475,7 @@ class BdAnchorNav extends LitElement {
             >${title}</bd-link>
           `;
         })}
+        <span class="anchor-indicator" aria-hidden="true"></span>
       </div>
     `;
 

package/src/components/anchor/anchor.stories.js

@@ -27,6 +27,9 @@ prin \`ResizeObserver\` — fără a fi necesară setarea manuală a \`max-width
 - Când navul iese din viewport, devine \`position: fixed\` full-width
 - Border-ul și background-ul sunt full-width
 - Conținutul (linkuri + CTA) rămâne centrat și aliniat cu cel mai lat sibling
+- Dacă mai există un alt element sticky **deasupra** lui (ex. un header/page-switcher
+  propriu sticky la \`top: 0\`), setează \`sticky-top\` cu înălțimea acelui element —
+  altfel cele două se suprapun, fiindcă implicit navul se lipește tot la \`top: 0\`.
 
 ---
 
@@ -76,6 +79,18 @@ prin \`ResizeObserver\` — fără a fi necesară setarea manuală a \`max-width
 ></bd-anchor-nav>
 \`\`\`
 
+### Utilizare cu \`sticky-top\` (nav secundar sub un header sticky propriu)
+\`\`\`html
+<my-sticky-header></my-sticky-header>
+
+<bd-anchor-nav sticky-top="64px" cta-label="Buy now" cta-href="#pricing">
+  <bd-anchor-nav-item title="Overview" href="#overview"></bd-anchor-nav-item>
+  <bd-anchor-nav-item title="Pricing"  href="#pricing"></bd-anchor-nav-item>
+</bd-anchor-nav>
+\`\`\`
+\`64px\` trebuie să fie înălțimea reală (măsurată în DevTools) a elementului sticky de deasupra —
+nu-i o valoare universală, depinde de conținutul acelui header.
+
 ---
 
 ### Atribute \`bd-anchor-nav\`
@@ -85,6 +100,7 @@ prin \`ResizeObserver\` — fără a fi necesară setarea manuală a \`max-width
 | \`cta-href\`   | String | \`"#section-pricing"\`   | href-ul butonului CTA fallback                   |
 | \`aria-label\` | String | \`"Section navigation"\` | Label accesibil pentru \`<nav>\`                 |
 | \`items\`      | Array  | —                        | \`{ title, href }[]\` — suprascrie child items   |
+| \`sticky-top\` | String | \`"0px"\`                | Cât de departe de vârful viewport-ului se lipește navul când devine sticky — setează-l la înălțimea oricărui alt element sticky de deasupra, ca să nu se suprapună |
 
 ### Atribute \`bd-anchor-nav-item\`
 | Atribut | Tip    | Descriere                                              |
@@ -114,6 +130,12 @@ Pe mobile devine automat full-width prin \`::slotted([slot="cta"])\`.
       control    : "object",
       description: "Array de { title, href } — suprascrie child elements",
       table      : { type: { summary: "{ title: string, href: string }[]" }, category: "Content" }
+    },
+    stickyTop: {
+      name       : "sticky-top",
+      control    : "text",
+      description: "Cât de departe de vârful viewport-ului se lipește navul când devine sticky — setează-l la înălțimea oricărui element sticky de deasupra (ex. un header propriu), ca sa nu se suprapună la scroll",
+      table      : { type: { summary: "string" }, defaultValue: { summary: "0px" }, category: "Sticky" }
     }
   }
 };
@@ -404,6 +426,65 @@ export const WithScrollTargets = {
   }
 };
 
+export const StickyBelowFixedHeader = {
+  name  : "Sticky sub un header propriu — sticky-top",
+  render: () => html`
+    <div>
+      <!-- Simuleaza un header sticky separat (ex. bd-page-switcher), la fel
+           pozitionat: position: sticky; top: 0. Fara sticky-top pe nav,
+           cele doua s-ar suprapune identic la scroll. -->
+      <div style="
+        position: sticky; top: 0; z-index: 200;
+        background: #0a1a2f; color: #fff;
+        padding: 16px 24px; box-sizing: border-box;
+        font-family: sans-serif; font-weight: 700; font-size: 18px;
+        display: flex; align-items: center; justify-content: space-between;
+      ">
+        <span>Mock Header (simulează bd-page-switcher, ~64px înălțime)</span>
+        <span style="opacity: .7; font-weight: 400; font-size: 13px;">Tab A · Tab B</span>
+      </div>
+
+      <bd-anchor-nav
+        sticky-top="64px"
+        cta-label="Buy now"
+        cta-href="#anchor-3-section"
+      >
+        <bd-anchor-nav-item title="Overview" href="#anchor-1-section"></bd-anchor-nav-item>
+        <bd-anchor-nav-item title="Features" href="#anchor-2-section"></bd-anchor-nav-item>
+        <bd-anchor-nav-item title="Pricing"  href="#anchor-3-section"></bd-anchor-nav-item>
+      </bd-anchor-nav>
+
+      <div style="max-width: 800px; margin: 0 auto;">
+        <div id="anchor-1-section" style="min-height: 60vh; padding: 80px 24px; background: #EDF9FF;">
+          <bd-h as="h2">Overview Section</bd-h>
+          <bd-p kind="regular">
+            Scroll în jos: mock header-ul de sus rămâne fix la top: 0, iar
+            bd-anchor-nav se lipește exact sub el (la 64px), nu peste el.
+          </bd-p>
+        </div>
+        <div id="anchor-2-section" style="min-height: 60vh; padding: 80px 24px; background: #fff;">
+          <bd-h as="h2">Features Section</bd-h>
+        </div>
+        <div id="anchor-3-section" style="min-height: 60vh; padding: 80px 24px; background: #EDF9FF;">
+          <bd-h as="h2">Pricing Section</bd-h>
+        </div>
+      </div>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: `Reproduce cazul real din demo-ul AI Guardian / Skill Scanner: un header sticky
+        propriu deasupra (aici simulat printr-un \`<div>\`, în producție \`bd-page-switcher\`)
+        și \`bd-anchor-nav\` cu \`sticky-top="64px"\`. Fără acest atribut, ambele s-ar
+        fixa la \`top: 0\` și s-ar suprapune perfect la scroll. Valoarea \`64px\` trebuie
+        să corespundă înălțimii reale a elementului sticky de deasupra — verifică în
+        DevTools dacă diferă la tine.`
+      }
+    }
+  }
+};
+
 export const MobileView = {
   name      : "Mobile View",
   render    : () => renderWithSlotCta(["Overview", "Features", "Reviews", "Pricing"]),
@@ -420,9 +501,10 @@ export const MobileView = {
 export const Playground = {
   name: "Playground",
   args: {
-    ctaLabel: "Buy now",
-    ctaHref : "#section-pricing",
-    items   : [
+    ctaLabel : "Buy now",
+    ctaHref  : "#section-pricing",
+    stickyTop: "0px",
+    items    : [
       { title: "Overview", href: "#anchor-1-section" },
       { title: "Features", href: "#anchor-2-section" },
       { title: "Reviews",  href: "#anchor-3-section" },
@@ -433,13 +515,14 @@ export const Playground = {
     <bd-anchor-nav
       cta-label=${args.ctaLabel}
       cta-href=${args.ctaHref}
+      sticky-top=${args.stickyTop}
       .items=${args.items}
     ></bd-anchor-nav>
   `,
   parameters: {
     docs: {
       description: {
-        story: "Playground interactiv. Editează `items`, `ctaLabel` și `ctaHref` din Controls."
+        story: "Playground interactiv. Editează `items`, `ctaLabel`, `ctaHref` și `sticky-top` din Controls."
       }
     }
   }

package/src/components/cta-banner/cta-banner.stories.js

@@ -0,0 +1,122 @@
+import { html } from "lit";
+import "../button/button.js";
+import "./cta-banner.js";
+
+export default {
+  title     : "Components/CtaBanner",
+  tags      : ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs  : {
+      description: {
+        component: `
+Full-width closing call-to-action banner on a blue gradient background —
+centered title, description, one or two buttons, and an optional small
+mono caption underneath.
+
+\`\`\`html
+<bd-cta-banner
+  title="Run your AI agents with a guardrail"
+  description="AI Guardian is in open BETA on macOS. Download the BETA and secure your agentic workflows."
+  caption="Downloads the macOS BETA (.dmg). Free during BETA."
+>
+  <bd-button-link slot="primary-button" kind="white" strong>Download BETA Today</bd-button-link>
+  <bd-button-link slot="secondary-button" kind="outline-white" strong>Read the docs</bd-button-link>
+</bd-cta-banner>
+\`\`\`
+
+### Attribute table
+| Attribute / slot | Type | Description |
+|---|---|---|
+| \`title\` / \`slot="title"\` | String | Large centred heading |
+| \`description\` / \`slot="description"\` | String | Paragraph under the title |
+| \`slot="primary-button"\` | — | First button, typically \`kind="white"\` |
+| \`slot="secondary-button"\` | — | Second button, typically \`kind="outline-white"\` |
+| \`caption\` / \`slot="caption"\` | String | Optional small mono line under the buttons |
+
+Buttons are expected to use \`bd-button-link\` with \`kind="white"\` /
+\`kind="outline-white"\` and \`strong\`, so they read against the blue
+background — that pairing isn't enforced by the component, just the
+convention used everywhere it's been placed so far.
+        `
+      }
+    }
+  }
+};
+
+// ─── Cu caption (AI Guardian) ──────────────────────────────────────────────
+
+export const WithCaption = {
+  name  : "Cu caption",
+  render: () => html`
+    <bd-cta-banner
+      title="Run your AI agents with a guardrail"
+      description="AI Guardian is in open BETA on macOS. Download the BETA and secure your agentic workflows."
+      caption="Downloads the macOS BETA (.dmg). Free during BETA."
+    >
+      <bd-button-link
+        slot="primary-button"
+        label="Download BETA Today"
+        kind="white"
+        size="md"
+        strong
+      >Download BETA Today</bd-button-link>
+
+      <bd-button-link
+        slot="secondary-button"
+        label="Read the docs"
+        kind="outline-white"
+        size="md"
+        strong
+      >Read the docs</bd-button-link>
+    </bd-cta-banner>
+  `
+};
+
+// ─── Fara caption (Skill Scanner) ──────────────────────────────────────────
+
+export const WithoutCaption = {
+  name  : "Fără caption",
+  render: () => html`
+    <bd-cta-banner
+      title="Scan before you trust"
+      description="A skill is code you hand to your agent. One command stands between you and running it blind."
+    >
+      <bd-button-link
+        slot="primary-button"
+        label="Install with npx"
+        kind="white"
+        size="md"
+        strong
+      >Install with npx</bd-button-link>
+
+      <bd-button-link
+        slot="secondary-button"
+        label="View on GitHub"
+        kind="outline-white"
+        size="md"
+        strong
+      >View on GitHub</bd-button-link>
+    </bd-cta-banner>
+  `
+};
+
+// ─── Un singur buton ────────────────────────────────────────────────────────
+
+export const SingleButton = {
+  name  : "Un singur buton",
+  render: () => html`
+    <bd-cta-banner
+      title="Ready to get started?"
+      description="Free during BETA, no waitlist and no licence key."
+    >
+      <bd-button-link
+        slot="primary-button"
+        label="Install now"
+        kind="white"
+        size="md"
+        strong
+      >Install now</bd-button-link>
+    </bd-cta-banner>
+  `
+};

package/src/components/install-options/install-options.stories.js

@@ -0,0 +1,219 @@
+import { html } from "lit";
+import "../compatibility-table/compatibility-table.js";
+import "../heading/heading.js";
+import "../paragraph/paragraph.js";
+import "./install-options.js";
+
+export default {
+  title     : "Components/InstallOptions",
+  tags      : ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs  : {
+      description: {
+        component: `
+Section container (eyebrow + title + description on a light blue background)
+for "how to get this" style pages. Three ways to fill it, usable on their
+own or combined:
+
+1. **Cards grid** (\`.cards\`) — a row of install-method cards, each with an
+   optional badge, a copyable code block, and a link.
+2. **"Then just ask" prompt panel** (\`prompt-panel\` + slots) — a copyable
+   prompt block with a label, a warning-style note, and a footer line.
+3. **Generic default slot** — anything else (a table, a checklist, a note)
+   that doesn't fit the cards grid, while still getting the shared
+   eyebrow/title/description header.
+
+\`\`\`html
+<!-- Cards + Works in pills -->
+<bd-install-options
+  eyebrow="Get it"
+  title="Three ways to install"
+  description="..."
+></bd-install-options>
+
+<!-- Generic slot instead of cards -->
+<bd-install-options eyebrow="Trust & transparency" title="What leaves your machine">
+  <bd-compatibility-table variant="risk" .columns=\${["Mode", "Transmitted"]} .rows=\${[...]}></bd-compatibility-table>
+</bd-install-options>
+\`\`\`
+
+### Attribute / property table
+| Name | Type | Default | Description |
+|---|---|---|---|
+| \`eyebrow\` | String | — | Small blue label above the title |
+| \`title\` | String | — | Section heading |
+| \`description\` | String | — | Paragraph under the title |
+| \`.worksIn\` | Array | \`[]\` | \`[{ label, initial, color }]\` — pill row. \`initial\`/\`color\` are placeholders (a letter on a solid circle) until real brand marks are available |
+| \`.cards\` | Array | \`[]\` | \`[{ title, badge, description, code, linkLabel, linkHref }]\` — rendered only if non-empty |
+| *(default slot)* | — | — | Anything else — renders between the description/works-in row and the cards grid |
+| \`prompt-panel\` | Boolean | \`false\` | Shows the "Then just ask" sub-panel below the cards |
+| \`prompt-label\` | String | — | Small mono label above the prompt code block |
+
+### Slots (only used when \`prompt-panel\` is set)
+| Slot | Description |
+|---|---|
+| \`prompt-title\` | Heading of the sub-panel |
+| \`prompt-description\` | Paragraph under that heading |
+| \`prompt\` | The copyable prompt text — the Copy button reads this slot's \`textContent\` |
+| \`prompt-note\` | Warning-style note box |
+| \`prompt-footer\` | Closing line (e.g. uninstall instructions) |
+        `
+      }
+    }
+  }
+};
+
+// ─── Carduri + Works in (cazul principal: "Three ways to install") ────────
+
+export const CardsWithWorksIn = {
+  name  : "Carduri + Works in",
+  render: () => html`
+    <bd-install-options
+      eyebrow="Get it"
+      title="Three ways to install"
+      description="Agent Skill Scanner installs in under a minute with npx via skills.sh, by cloning the GitHub repository, or as a zip archive you drop into your skills directory. It runs inside your agent harness and installs its own Python dependencies on first use."
+      .worksIn=${[
+        { label: "Claude Code", initial: "✻", color: "#d97706" },
+        { label: "Codex", initial: "◒", color: "#111827" },
+        { label: "OpenClaw", initial: "▣", color: "#dc2626" },
+        { label: "opencode", initial: "▪", color: "#111827" },
+        { label: "Hermes Agent", initial: "H", color: "#111827" }
+      ]}
+      .cards=${[
+        {
+          title      : "With npx, from skills.sh",
+          badge      : "Recommended",
+          description: "One command via the skills.sh installer. Works for any supported harness.",
+          code       : "npx skills add bitdefender/agent-skill-scanner",
+          linkLabel  : "View on skills.sh",
+          linkHref   : "#"
+        },
+        {
+          title      : "From GitHub",
+          description: "Clone the repository and copy the inner agent-skill-scanner/ folder into your skills directory.",
+          code       : "git clone https://github.com/bitdefender/agent-skill-scanner.git\ncp -r agent-skill-scanner/agent-skill-scanner ~/.claude/skills/",
+          linkLabel  : "View the repository",
+          linkHref   : "#"
+        },
+        {
+          title      : "As a zip archive",
+          description: "Download the archive, unzip it, and move the inner agent-skill-scanner/ folder into your skills directory.",
+          linkLabel  : "Download the zip",
+          linkHref   : "#"
+        }
+      ]}
+    ></bd-install-options>
+  `
+};
+
+// ─── Carduri + prompt panel ("Then just ask") ──────────────────────────────
+
+export const WithPromptPanel = {
+  name      : "Carduri + prompt panel",
+  parameters: {
+    docs: {
+      description: {
+        story: "Aceleași carduri, plus sub-panelul \"Then just ask\" activat prin `prompt-panel`. Butonul Copy citește textul din `slot=\"prompt\"` la click, indiferent de markup."
+      }
+    }
+  },
+  render: () => html`
+    <bd-install-options
+      eyebrow="Get it"
+      title="Three ways to install"
+      description="Agent Skill Scanner installs in under a minute with npx via skills.sh, by cloning the GitHub repository, or as a zip archive you drop into your skills directory."
+      .cards=${[
+        {
+          title      : "With npx, from skills.sh",
+          badge      : "Recommended",
+          description: "One command via the skills.sh installer.",
+          code       : "npx skills add bitdefender/agent-skill-scanner",
+          linkLabel  : "View on skills.sh",
+          linkHref   : "#"
+        },
+        {
+          title      : "From GitHub",
+          description: "Clone the repository into your skills directory.",
+          code       : "git clone https://github.com/bitdefender/agent-skill-scanner.git",
+          linkLabel  : "View the repository",
+          linkHref   : "#"
+        }
+      ]}
+      prompt-panel
+      prompt-label="Prompt for your agent"
+    >
+      <span slot="prompt-title">Then just ask</span>
+      <span slot="prompt-description">There is no command to learn. Once installed, paste this prompt into your agent; it handles invocation, target resolution and update checks.</span>
+      <span slot="prompt">Scan the &lt;skill name or path&gt; skill for security risks and show me the report.</span>
+      <bd-p slot="prompt-note" kind="small">Requires Python 3.12 or 3.13 (3.13 recommended). Dependencies install on first use.</bd-p>
+      <span slot="prompt-footer">To uninstall, delete the agent-skill-scanner folder from your skills directory.</span>
+    </bd-install-options>
+  `
+};
+
+// ─── Slot generic in loc de carduri (tabel + checklist + nota) ────────────
+
+export const GenericSlotContent = {
+  name      : "Slot generic (tabel + checklist + notă)",
+  parameters: {
+    docs: {
+      description: {
+        story: "Aceeași secțiune (eyebrow + titlu + descriere pe fundal albastru), dar fără `.cards` deloc — în schimb, orice conținut arbitrar prin slotul generic: aici un `bd-compatibility-table` (variant `risk`, cu antete custom prin `.columns`), o casetă cu checklist, și o notă de avertizare, scrise ca markup simplu în locul consumator."
+      }
+    }
+  },
+  render: () => html`
+    <bd-install-options
+      eyebrow="Trust &amp; transparency"
+      title="What leaves your machine"
+      description="Two modes, both agent-driven. Scan is the default: only hashes, extracted indicators and metadata are transmitted, and full files are never uploaded. Submit is opt-in: the complete skill archive is uploaded for deeper analysis, and only when you explicitly ask for it."
+    >
+      <bd-compatibility-table
+        variant="risk"
+        .columns=${["Mode", "Transmitted"]}
+        .rows=${[
+          {
+            category: "Scan (default)",
+            coverage: "File hashes (SHA-256/MD5), extracted indicators and pattern matches. Full file contents are not transmitted."
+          },
+          {
+            category: "Submit (opt-in)",
+            coverage: "The complete skill archive, uploaded for deep analysis. The agent will not do this unless you explicitly ask."
+          }
+        ]}
+      ></bd-compatibility-table>
+
+      <div style="background: var(--color-neutral-0); border: 1px solid var(--color-neutral-100); border-radius: var(--radius-xl); padding: 24px; box-sizing: border-box; margin-top: 24px;">
+        <bd-h as="h3" style="margin: 0 0 16px;">The contract the agent is held to</bd-h>
+        <ul style="list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 16px;">
+          <li style="display: flex; align-items: flex-start; gap: 12px;">
+            <span aria-hidden="true" style="flex-shrink: 0; width: 20px; height: 20px; border-radius: 999px; background: var(--color-green-600, #16a34a); color: #fff; display: flex; align-items: center; justify-content: center; font-size: 12px; font-weight: 700; margin-top: 2px;">✓</span>
+            <bd-p kind="regular" style="margin:0;">Scan mode is the default: a casual request never uploads your files.</bd-p>
+          </li>
+          <li style="display: flex; align-items: flex-start; gap: 12px;">
+            <span aria-hidden="true" style="flex-shrink: 0; width: 20px; height: 20px; border-radius: 999px; background: var(--color-green-600, #16a34a); color: #fff; display: flex; align-items: center; justify-content: center; font-size: 12px; font-weight: 700; margin-top: 2px;">✓</span>
+            <bd-p kind="regular" style="margin:0;">Submit is opt-in only: the agent won't upload the full archive unless you explicitly ask.</bd-p>
+          </li>
+        </ul>
+      </div>
+
+      <div style="background: var(--color-yellow-50, #fffbeb); border: 1px solid var(--color-yellow-300, #fcd34d); border-radius: var(--radius-md); padding: 16px 20px; color: var(--color-yellow-800, #92400e); margin-top: 24px;">
+        <bd-p kind="small" style="margin:0;">A scan that returns no findings means no known threat patterns were detected — not that the skill is safe.</bd-p>
+      </div>
+    </bd-install-options>
+  `
+};
+
+// ─── Doar header, fara carduri si fara slot ────────────────────────────────
+
+export const HeaderOnly = {
+  name  : "Doar header (fără carduri, fără slot)",
+  render: () => html`
+    <bd-install-options
+      eyebrow="Get it"
+      title="Coming soon"
+      description="Installation instructions will appear here once the package is published."
+    ></bd-install-options>
+  `
+};