@flamingo-stack/openframe-frontend-core 0.0.403 → 0.0.404-snapshot.20260711053526

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.403",
+  "version": "0.0.404-snapshot.20260711053526",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/.announcement-bar.md

@@ -1,40 +1,42 @@
-<!-- source-hash: cbe120bea34edef14f05fff077b0b285 -->
-A client-side React component that renders a dismissible announcement banner, fetching active announcements from a configured API endpoint with localStorage-based caching and per-announcement dismissal persistence.
+<!-- source-hash: pending-regeneration -->
+A dismissible platform announcement bar with DUAL MODE support: SSR-seeded (Next hosts) and client-only (bare React apps without SSR). Single-line 44px strip, contrast handled by scoping content with the ODS theme classes, event-driven freshness (no polling).
 
 ## Key Components
 
 | Export/Function | Description |
 |----------------|-------------|
-| `AnnouncementBar` | Main component — renders the announcement banner or `null` if hidden/dismissed |
-| `fetchActiveAnnouncement` | Fetches the active announcement from `announcementsUrl`, updates state and localStorage cache |
-| `handleDismiss` | Marks the current announcement as dismissed in localStorage and hides the bar |
-| `handleCtaClick` | Navigates to the CTA URL, respecting `_blank` target for new-tab behavior |
-| `renderIcon` | Renders either a PNG `<Image>` or an SVG icon based on `announcement.icon_type` |
-| `getSvgIcon` | Thin wrapper around `renderSvgIcon` applying size-appropriate Tailwind classes |
+| `AnnouncementBar` | Main component — renders the bar or `null` when there is nothing to show |
+| `initialAnnouncement` prop | SSR mode seed (nullable): server resolved announcement + dismissal cookie; skips the mount fetch |
+| `previewMode` prop | Render-only (admin live preview): no fetch, inert dismiss, no storage side effects |
+
+## Modes
+
+- **SSR mode** (hub / any Next host): the server passes `initialAnnouncement` (already dismissal-filtered via the cookie helpers in `announcement-storage.ts`). The bar is in the first HTML byte — zero layout shift, no flash for dismissed users, zero mount fetch.
+- **Client-only mode** (Vite/CRA embeds, no SSR — the react-embedding-example structure): mount the bar PROP-LESS inside an EndpointsRuntime provider; `announcementsUrl` is a fixed suffix under the embedder's one content base (`${CONTENT}/announcements/active`). No provider → renders nothing, never fetches. Appearance animates in (grid `0fr -> 1fr`). Deliberately NO per-component URL or platform knobs: the platform is never sent as a parameter — each server returns its own announcement via `currentPlatform()`.
 
 ## Behavior Notes
 
-- **Instant paint**: On mount, the cached announcement from localStorage is applied synchronously before the API response arrives.
-- **Polling**: Refreshes every 5 minutes via `setInterval`; interval restarts if `announcementsUrl` changes.
-- **No provider fallback**: When `useEndpointsRuntime` returns no URL, polling is skipped entirely — cached data still renders.
-- **Platform-scoped keys**: localStorage keys are prefixed with the platform type (via `getAppType()`) to prevent key collisions across apps.
-- **Responsive CTA**: The CTA button is desktop-only; on mobile, tapping the content area triggers `handleCtaClick` directly.
-
-## Usage Example
-
-```typescript
-// Wrap your app with the endpoints provider, then drop in the bar:
-import { AnnouncementBar } from './announcement-bar';
-import { EndpointsRuntimeProvider } from '../contexts/endpoints-runtime-context';
-
-function AppShell() {
-  return (
-    <EndpointsRuntimeProvider announcementsUrl="/api/announcements/active">
-      <AnnouncementBar />
-      <main>{/* app content */}</main>
-    </EndpointsRuntimeProvider>
-  );
+- **No polling**: freshness is visibility-driven — `useSelfFetch`'s `revalidateOnVisibleAfterMs` refetches on tab refocus when held data is older than 60s. Idle tabs make zero requests.
+- **Dismissal**: cookie is the SSOT (`<platform>-announcement-dismissed=<id>`, id-match); localStorage is read-only legacy. Storage reads happen only in effects (hydration safety).
+- **Contrast**: the admin background's tone selects `.theme-light`/`.theme-dark` around the content; all colors resolve from the active ODS theme's Tier-1 primitives.
+- **Responsive**: single truncating line (description hidden < sm); CTA is desktop-only, the whole bar is the tap target on mobile.
+
+## Usage Examples
+
+```tsx
+// SSR mode (Next server component resolves the seed):
+<AnnouncementBar initialAnnouncement={announcementOrNull} />
+
+// Client-only mode (react-embedding-example structure): one content base,
+// endpoints built once, bar mounted prop-less inside the provider.
+const endpointsRuntime: EndpointsRuntime = {
+  announcementsUrl: `${CONTENT}/announcements/active`,
+  accessCode: { validateUrl: `${CONTENT}/validate-access-code`, consumeUrl: `${CONTENT}/consume-access-code` },
+  contactUrl: `${CONTENT}/contact`,
 }
-```
 
-> **Note:** The component renders nothing (`null`) when no active announcement exists, when the fetch URL is unconfigured, or when the user has previously dismissed the current announcement.
+<EndpointsRuntimeContext.Provider value={endpointsRuntime}>
+  <AnnouncementBar />
+  <main>{/* app content */}</main>
+</EndpointsRuntimeContext.Provider>
+```

package/src/components/announcement-bar.tsx

@@ -1,221 +1,266 @@
 "use client";
 
-import { useState, useEffect } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import { X } from 'lucide-react';
 import { Button } from './ui/button';
 import { EntityIcon } from './icon-display';
 import {
-  setStoredAnnouncement,
-  getStoredAnnouncement,
-  clearStoredAnnouncement,
+  dismissAnnouncement,
+  isAnnouncementDismissed,
+  clearLegacyAnnouncementCache,
 } from '../utils/announcement-storage';
-import { Announcement } from '../types/announcement';
+import type { AnnouncementBarProps, AnnouncementResponse } from '../types/announcement';
 import { getAppType } from '../utils/app-config';
 import { useEndpointsRuntime } from '../contexts/endpoints-runtime-context';
+import { useSelfFetch } from '../hooks/use-self-fetch';
+import { pickReadableTextColor } from '../utils/color-analysis';
 
-export function AnnouncementBar() {
-  const [announcement, setAnnouncement] = useState<Announcement | null>(null);
-  const [isVisible, setIsVisible] = useState<boolean>(false);
-
-  // Get the platform type for platform-specific localStorage keys
+/**
+ * Platform announcement bar — DUAL MODE, works with or without SSR.
+ *
+ * SSR mode (Next hosts, e.g. the hub): the server resolves the announcement
+ * and the dismissal cookie, then passes `initialAnnouncement` (nullable).
+ * The bar renders in the first HTML byte (zero layout shift, no flash for
+ * dismissed users) and skips the mount fetch.
+ *
+ * Client-only mode (bare React apps without SSR: Vite/CRA embeds — see
+ * react-embedding-example): omit `initialAnnouncement` and mount the bar
+ * PROP-LESS inside an EndpointsRuntime provider; it self-fetches from the
+ * provider's `announcementsUrl` (a fixed suffix under the embedder's one
+ * content base). No provider → renders nothing, never fetches (silent
+ * no-op). Appearance animates in (grid 0fr→1fr) so there is no hard layout
+ * jump. Deliberately NO per-component URL or platform knobs: the embedder
+ * is platform-agnostic — each server returns ITS OWN announcement via
+ * currentPlatform(); the platform is never sent as a parameter.
+ *
+ * Both modes: freshness is event-driven, no polling — `useSelfFetch`'s
+ * visibility revalidation re-fetches on tab refocus when the held data is
+ * >60s old (matching the server cache TTL by convention); idle tabs make
+ * zero requests. Dismissal cookie is the SSOT (`announcement-storage.ts`);
+ * storage reads happen ONLY in effects (a render-time read would desync
+ * hydration in SSR mode).
+ */
+export function AnnouncementBar({
+  initialAnnouncement,
+  previewMode = false,
+  className,
+}: AnnouncementBarProps = {}) {
+  // Namespace for the dismissal cookie/legacy keys. Next hosts inline
+  // NEXT_PUBLIC_APP_TYPE (matching the server's currentPlatform(), which the
+  // hub layout uses for the SSR cookie read); platform-agnostic embeds get
+  // the fallback — fine, cookies are domain-scoped and an embed domain
+  // serves one platform's announcements.
   const platform = getAppType();
 
-  // Optional endpoint runtime: when no provider is mounted (e.g. on a
-  // bare React-tree page that doesn't wrap with HubRuntimeProvider),
-  // the bar silently skips its fetch instead of throwing. Apps that DO
-  // mount the provider get the configured URL — typically
-  // '/api/announcements/active' in the hub, or a proxied path in an
-  // embedded host.
+  // Optional endpoint runtime: no provider → no URL → fetching disabled.
   const endpoints = useEndpointsRuntime();
-  const announcementsUrl = endpoints?.announcementsUrl;
-
-  // Helper to determine dismissal key for localStorage
-  const getDismissKey = (id: string) => `${platform}-announcement-${id}-dismissed`;
-  
-  // Helper to get platform-specific cache key
-  const getCacheKey = () => `${platform}-announcement-cache`;
-
-  // Fetch active announcement from API and update state + LS
-  const fetchActiveAnnouncement = async () => {
-    // No provider mounted → no URL configured → skip fetch silently.
-    // Cached announcement from previous sessions still renders if present.
-    if (!announcementsUrl) return;
-    try {
-      // Server-side platform injection - no URL parameter needed
-      const response = await fetch(announcementsUrl);
-      
-      if (response.ok) {
-        const data = await response.json();
-        if (data.announcement) {
-          setAnnouncement(data.announcement);
-
-          // persist latest announcement for quick future loads with platform-specific key
-          setStoredAnnouncement(getCacheKey(), data.announcement);
-
-          // Check if this specific announcement was dismissed
-          const isDismissed = localStorage.getItem(getDismissKey(data.announcement.id));
-          setIsVisible(!isDismissed);
-        } else {
-          // No announcement available - clean up localStorage and hide bar
-          setAnnouncement(null);
-          setIsVisible(false);
-          
-          // Use utility function to properly clear platform-specific announcement data
-          clearStoredAnnouncement(getCacheKey());
-        }
-      } else {
-        // Network or other error - hide announcement and clean up
-        console.error(`❌ [${platform.toUpperCase()}] Error fetching announcement: ${response.status}`);
-        setAnnouncement(null);
-        setIsVisible(false);
-        
-        // Clear stale data on network errors too
-        clearStoredAnnouncement(getCacheKey());
-      }
-    } catch (error) {
-      console.error('Error fetching active announcement:', error);
-      setAnnouncement(null);
-      setIsVisible(false);
-      
-      // Clear stale data on exceptions too
-      clearStoredAnnouncement(getCacheKey());
-    }
-  };
+  const url = previewMode ? null : endpoints?.announcementsUrl ?? null;
 
-  // Initial load: use cached announcement synchronously for instant paint
-  useEffect(() => {
-    const cached = getStoredAnnouncement(getCacheKey());
-    if (cached) {
-      const isDismissed = localStorage.getItem(getDismissKey(cached.id));
-      setAnnouncement(cached);
-      setIsVisible(!isDismissed);
-    }
+  // MUST be memoized (the hook re-syncs on [initialData] identity — an inline
+  // literal per render would setData-loop) and strict-undefined-mapped:
+  // `null` (hub: dismissed / no active announcement) still seeds the hook and
+  // skips the mount fetch; only an ABSENT prop (embeds) enables self-fetch.
+  const initialData = useMemo<AnnouncementResponse | undefined>(
+    () => (initialAnnouncement === undefined ? undefined : { announcement: initialAnnouncement }),
+    [initialAnnouncement],
+  );
 
-    // No provider mounted → no URL → no fetch / no polling. Cached
-    // announcement still painted above. Skip scheduling the 5-min
-    // interval entirely to avoid an idle timer + repeated short-circuit
-    // calls.
-    if (!announcementsUrl) return;
+  const { data } = useSelfFetch<AnnouncementResponse>(url, {
+    initialData,
+    revalidateOnVisibleAfterMs: 60_000,
+  });
+  const announcement = data?.announcement ?? null;
 
-    // Always fetch latest on mount
-    fetchActiveAnnouncement();
+  // Expanded (height) state — initial value is a pure function of props so
+  // the SSR HTML and the hydration render agree for every cohort.
+  const [expandedState, setExpandedState] = useState<boolean>(() => initialAnnouncement != null);
+  // Preview always mirrors the draft directly (effects are disabled there).
+  const expanded = previewMode ? announcement != null : expandedState;
 
-    // Schedule refresh every 5 minutes. When announcementsUrl flips
-    // (e.g. provider value swap), the effect re-runs and restarts the
-    // interval against the new URL — no stale captured fetch.
-    const interval = setInterval(fetchActiveAnnouncement, 300_000);
-    return () => clearInterval(interval);
+  // One-time cleanup of the pre-refactor localStorage announcement cache.
+  useEffect(() => {
+    if (previewMode) return;
+    clearLegacyAnnouncementCache(platform);
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [announcementsUrl]);
+  }, []);
+
+  // Visibility reconciliation — runs on the seed and after EVERY completed
+  // fetch (keyed on `data` identity, not announcement id, so a refocus
+  // revalidation that returns the same announcement still re-checks the
+  // dismissal store: this is what keeps a bar dismissed seconds earlier in
+  // another tab from resurrecting). Also the legacy-migration point: an
+  // LS-only dismissal (no cookie — server couldn't see it) collapses once,
+  // animated, and backfills the cookie so the next SSR skips the bar.
+  useEffect(() => {
+    if (previewMode) return;
+    if (!announcement) {
+      setExpandedState(false);
+      return;
+    }
+    if (isAnnouncementDismissed(platform, announcement.id)) {
+      dismissAnnouncement(platform, announcement.id); // idempotent cookie backfill
+      setExpandedState(false);
+    } else {
+      setExpandedState(true);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [data]);
 
-  // helpers
   const handleDismiss = () => {
-    if (!announcement) return;
-    localStorage.setItem(getDismissKey(announcement.id), 'true');
-    setIsVisible(false);
+    if (previewMode || !announcement) return;
+    dismissAnnouncement(platform, announcement.id);
+    setExpandedState(false);
   };
 
   const handleCtaClick = () => {
-    if (!announcement?.cta_url) return;
+    if (previewMode || !announcement?.cta_url) return;
+    // Scheme guard: cta_url is admin-entered data — only http(s) (absolute or
+    // relative) may navigate. A `javascript:` value would otherwise execute
+    // via location.href / window.open (stored XSS).
+    let safeUrl: string;
+    try {
+      const parsed = new URL(announcement.cta_url, window.location.origin);
+      if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return;
+      safeUrl = parsed.href;
+    } catch {
+      return;
+    }
     announcement.cta_target === '_blank'
-      ? window.open(announcement.cta_url, '_blank', 'noopener,noreferrer')
-      : (window.location.href = announcement.cta_url);
+      ? window.open(safeUrl, '_blank', 'noopener,noreferrer')
+      : (window.location.href = safeUrl);
   };
 
-  const renderIcon = () => {
-    if (!announcement) return null;
-    // ONE unified display path (shared with the chat): uploaded image URL wins,
-    // else a library glyph by name (+ props), via <EntityIcon>.
-    return (
-      <EntityIcon
-        icon={{
-          name: announcement.icon_name || 'openframe-logo',
-          url: announcement.icon_url,
-          props: announcement.icon_props,
-        }}
-        size={32}
-        className="relative shrink-0 w-6 h-6 md:w-8 md:h-8"
-      />
-    );
-  };
+  // Nothing to show (and nothing to animate around): render nothing. The
+  // dismissed/deactivated case keeps the element mounted at 0fr so the
+  // collapse animates.
+  if (!announcement) return null;
+
+  // Contrast is solved with the ODS THEME system, not color literals: the
+  // admin background's tone selects which ODS theme scopes the bar's content
+  // (light-toned background needs dark-on-light = the light theme's values;
+  // dark-toned needs the dark theme's). `.theme-light` / `.theme-dark` are
+  // the design system's own scoping classes (ods-colors.css) and flip every
+  // Tier-1 `--ods-*` primitive for descendants.
+  const themeScope = pickReadableTextColor(announcement.background_color) === 'dark' ? 'theme-light' : 'theme-dark';
+
+  // Inside the scope, colors reference Tier-1 theme primitives directly
+  // (Tier-2 `--color-*` aliases resolve once at :root and do NOT re-resolve
+  // in a nested theme scope — verified). `--ods-system-greys-white` is the
+  // theme's primary-text primitive; `--ods-system-greys-black-hover/-action`
+  // are its quiet hover/active surfaces. Every value comes from the active
+  // ODS theme; nothing is hardcoded.
+  const barButtonClasses =
+    'text-[color:var(--ods-system-greys-white)] hover:bg-[var(--ods-system-greys-black-hover)] active:bg-[var(--ods-system-greys-black-action)]';
 
-  // If no announcement or dismissed => render nothing
-  if (!announcement || !isVisible) return null;
+  const hasCta = Boolean(announcement.cta_enabled && announcement.cta_url);
 
   return (
     <div
-      className="relative w-full z-50"
-      style={{ backgroundColor: announcement.background_color }}
+      role="region"
+      aria-label="Announcement"
+      aria-hidden={!expanded}
       data-announcement-bar
+      className={`relative w-full z-50 grid transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none ${className ?? ''}`}
+      style={{ gridTemplateRows: expanded ? '1fr' : '0fr' }}
     >
-      <div className="flex items-center w-full max-w-full">
-        {/* Mobile: Clickable content area, Desktop: Regular content */}
-        <div
-          className={`flex flex-row gap-2 md:gap-4 items-center pl-4 md:pl-6 py-1.5 md:py-2 flex-1 min-w-0 ${
-            announcement.cta_enabled && announcement.cta_url ? 'md:cursor-default cursor-pointer' : ''
-          }`}
-          onClick={(e) => {
-            // Only handle click on mobile (< 768px) and if CTA is enabled
-            if (window.innerWidth < 768 && announcement.cta_enabled && announcement.cta_url) {
-              e.preventDefault();
-              handleCtaClick();
-            }
-          }}
-        >
-          {renderIcon()}
-
-          <div className="flex-1 min-w-0 max-w-full">
-            <p className="font-body font-bold text-[14px] md:text-[18px] leading-tight tracking-tight mb-0 text-[#1A1A1A] truncate">
-              {announcement.title}
-            </p>
-            <p className="font-body text-[12px] md:text-[18px] leading-tight hidden md:block text-[#1A1A1A] truncate">
-              {announcement.description}
+      {/*
+        Bar anatomy follows the announcement-bar industry standard: ONE line of
+        text at 13-14px inside a 44px-tall strip (guides converge on 40-60px
+        with a single sentence; two stacked 18px rows blew past that), title +
+        description merged inline (description hidden on small screens), ONE
+        compact CTA on the right, and a ghost-icon dismiss (design-system
+        icon-sm: 32px target, >= the 24px WCAG 2.2 SC 2.5.8 AA floor).
+      */}
+      <div className={`min-h-0 overflow-hidden ${themeScope}`} style={{ backgroundColor: announcement.background_color }}>
+        <div className="flex items-center w-full max-w-full min-h-11 text-[color:var(--ods-system-greys-white)]">
+          {/* Mobile: Clickable content area, Desktop: Regular content */}
+          <div
+            className={`flex flex-row gap-2 md:gap-3 items-center pl-4 md:pl-6 py-1.5 flex-1 min-w-0 ${
+              hasCta ? 'md:cursor-default cursor-pointer' : ''
+            }`}
+            onClick={(e) => {
+              // Only handle click on mobile (< 768px) and if CTA is enabled
+              if (window.innerWidth < 768 && hasCta) {
+                e.preventDefault();
+                handleCtaClick();
+              }
+            }}
+          >
+            {/* ONE unified icon path (shared with the chat): uploaded image URL
+                wins, else a library glyph by name (+ props), via <EntityIcon>. */}
+            <EntityIcon
+              icon={{
+                name: announcement.icon_name || 'openframe-logo',
+                url: announcement.icon_url,
+                props: announcement.icon_props,
+              }}
+              size={24}
+              className="relative shrink-0 w-5 h-5 md:w-6 md:h-6"
+            />
+
+            {/* Single-line message: bold title + regular description inline,
+                truncating as one unit. Separator is a middot (house rule: no
+                en/em dashes in copy). */}
+            <p className="font-body flex-1 min-w-0 max-w-full text-[13px] md:text-sm leading-snug truncate mb-0">
+              <span className="font-semibold">{announcement.title}</span>
+              {announcement.description && (
+                <span className="hidden sm:inline opacity-80"> · {announcement.description}</span>
+              )}
             </p>
+
+            {/* CTA - the common Button in the bar's quiet treatment: ghost
+                surface, computed-foreground text, translucent fg-tint hover
+                (barButtonClasses) so nothing renders as a dark slab on the
+                admin color. The admin cta_button_* colors are NOT applied:
+                they were designed for the legacy bespoke treatment. Hidden
+                on mobile, where the whole bar is the tap target. */}
+            {hasCta && announcement.cta_text && (
+              <div className="hidden md:flex flex-shrink-0 ml-1">
+                <Button
+                  onClick={handleCtaClick}
+                  variant="transparent"
+                  size="small"
+                  className={barButtonClasses}
+                  tabIndex={expanded ? 0 : -1}
+                  leftIcon={
+                    announcement.cta_show_icon && announcement.cta_icon_name
+                      ? (
+                          <EntityIcon
+                            icon={{ name: announcement.cta_icon_name, props: announcement.cta_icon_props }}
+                            size={14}
+                            className="w-3.5 h-3.5"
+                          />
+                        )
+                      : undefined
+                  }
+                >
+                  {announcement.cta_text}
+                </Button>
+              </div>
+            )}
           </div>
 
-          {/* CTA Button - Hidden on mobile, shown on desktop */}
-          {announcement.cta_enabled && announcement.cta_text && announcement.cta_url && (
-            <div className="hidden md:flex flex-shrink-0 ml-1 md:ml-2">
-              <Button
-                onClick={handleCtaClick}
-                variant="outline"
-                size="small-legacy"
-                leftIcon={
-                  announcement.cta_show_icon && announcement.cta_icon_name
-                    ? (
-                        <EntityIcon
-                          icon={{ name: announcement.cta_icon_name, props: announcement.cta_icon_props }}
-                          size={16}
-                          className="w-3 h-3 md:w-4 md:h-4"
-                        />
-                      )
-                    : undefined
-                }
-                className="transition-opacity hover:opacity-90 text-xs md:text-sm whitespace-nowrap"
-                style={{
-                  backgroundColor: announcement.cta_button_background_color || undefined,
-                  color: announcement.cta_button_text_color || undefined,
-                  borderColor: announcement.cta_button_background_color || undefined,
-                }}
-              >
-                {announcement.cta_text}
-              </Button>
-            </div>
-          )}
+          {/* Dismiss - the common Button in its ghost-icon treatment
+              (size="icon-sm": 32px target, >= the 24px WCAG 2.5.8 AA floor,
+              16px glyph) with the bar's quiet tint hover. Inert in
+              previewMode. */}
+          <div className="flex-shrink-0 mr-1 md:mr-3">
+            <Button
+              onClick={(e) => {
+                e.stopPropagation(); // Prevent triggering the mobile CTA click
+                handleDismiss();
+              }}
+              variant="transparent"
+              size="icon-sm"
+              className={barButtonClasses}
+              aria-label="Dismiss announcement"
+              type="button"
+              tabIndex={expanded ? 0 : -1}
+            >
+              <X strokeWidth={2} />
+            </Button>
+          </div>
         </div>
-
-        {/* Dismiss button - always visible */}
-        <button
-          onClick={(e) => {
-            e.stopPropagation(); // Prevent triggering the mobile CTA click
-            handleDismiss();
-          }}
-          className="flex-shrink-0 w-8 h-8 md:w-10 md:h-10 flex items-center justify-center hover:bg-[#1A1A1A]/10 focus:outline-none focus:ring-2 focus:ring-[#1A1A1A] mr-2 md:mr-4"
-          aria-label="Dismiss announcement"
-          type="button"
-        >
-          <X className="w-4 h-4 text-[#1A1A1A]" strokeWidth={2} />
-        </button>
       </div>
     </div>
   );

package/src/components/faq/faq-section.tsx

@@ -316,11 +316,11 @@ function FaqSkeleton() {
   return (
     <div className="space-y-8 animate-pulse">
       <div className="h-12 md:h-14 w-2/3 rounded bg-ods-border" />
-      <div className="rounded-3xl border border-ods-border overflow-hidden bg-ods-card divide-y divide-ods-border w-full">
+      <div className="rounded-md border border-ods-border overflow-hidden bg-transparent divide-y divide-ods-border w-full">
         {Array.from({ length: 8 }).map((_, idx) => (
-          <div key={idx} className="flex items-center justify-between px-6 md:px-8 py-6">
+          <div key={idx} className="flex items-center justify-between gap-6 md:gap-10 px-6 py-4">
             <div className="h-6 w-5/6 rounded bg-ods-border" />
-            <div className="h-10 w-10 rounded-md bg-ods-border" />
+            <div className="size-6 rounded bg-ods-border" />
           </div>
         ))}
       </div>

package/src/components/faq-accordion.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 import React, { useRef, useState, useEffect, useCallback } from 'react'
-import { ChevronButton } from './ui/chevron-button'
+import { Chevron02DownIcon } from './icons-v2-generated/arrows/chevron-02-down-icon'
 import { cn } from "../utils/cn"
 import { faqItemAnchor } from "../utils/faq-anchor"
 
@@ -53,7 +53,7 @@ export function FaqAccordion({ items, defaultOpenIds = [] }: FaqAccordionProps)
   }
 
   return (
-    <div className="rounded-3xl border border-ods-border divide-y divide-ods-border bg-ods-card overflow-hidden">
+    <div className="rounded-md border border-ods-border divide-y divide-ods-border bg-transparent overflow-hidden">
       {items.map(item => {
         const isOpen = openSet.has(item.id)
         const { ref, maxHeight } = useMeasuredHeight(isOpen)
@@ -67,7 +67,7 @@ export function FaqAccordion({ items, defaultOpenIds = [] }: FaqAccordionProps)
             // sticky nav offset (matches `<section>`'s scroll-margin for
             // category anchors).
             id={faqItemAnchor(item.id)}
-            className={cn('group scroll-mt-24 transition-colors hover:bg-[#1E1E1E]', isOpen ? 'bg-ods-bg' : 'bg-transparent')}
+            className="scroll-mt-24 transition-colors hover:bg-ods-bg-hover"
           >
             {/* Header */}
             <div
@@ -81,33 +81,30 @@ export function FaqAccordion({ items, defaultOpenIds = [] }: FaqAccordionProps)
                 }
               }}
               aria-expanded={isOpen}
-              className="flex w-full items-center justify-between px-6 md:px-8 py-6 text-left focus:outline-none transition-colors cursor-pointer"
+              className="flex w-full items-center gap-6 md:gap-10 px-6 py-4 text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ods-focus transition-colors cursor-pointer"
             >
-              <div className="min-w-0 pr-4">
-                <h3>
-                  {item.question}
-                </h3>
-              </div>
-              <div className="flex-shrink-0">
-                <ChevronButton
-                  aria-label={isOpen ? 'Collapse question' : 'Expand question'}
-                  size="md"
-                  isExpanded={isOpen}
-                  backgroundColor="transparent"
-                  borderColor="#3A3A3A"
-                />
-              </div>
+              <h3 className="flex-1 min-w-0 break-words">
+                {item.question}
+              </h3>
+              <Chevron02DownIcon
+                aria-hidden="true"
+                size={24}
+                className={cn(
+                  'shrink-0 text-ods-text-primary transition-transform duration-300',
+                  isOpen && 'rotate-180',
+                )}
+              />
             </div>
             {/* Content wrapper with max-height animation */}
             <div
               style={{ maxHeight, transition: 'max-height 0.35s ease-in-out, opacity 0.35s ease-in-out', opacity: isOpen ? 1 : 0 }}
-              className="overflow-hidden group-hover:bg-[#1E1E1E]/30"
+              className="overflow-hidden"
             >
               {/* break-words: FAQ answers render as plain text, so a long URL or
                   token has no wrap opportunity — and the parent is overflow-hidden,
                   which would CLIP it past the viewport on mobile. Mirrors the
                   markdown-renderer overflow-wrap fix. */}
-              <div ref={ref} className="px-6 md:px-8 pb-6 text-ods-text-primary text-h4 break-words">
+              <div ref={ref} className="px-6 pb-4 text-ods-text-primary text-h4 break-words">
                 {item.answer}
               </div>
             </div>