astro-component-kit 0.0.1 → 0.1.0

package/src/components/lib/feedback/GlassModal.astro

@@ -1,19 +1,104 @@
 ---
+/**
+ * GlassModal — A premium overlay dialog for critical confirmations or focused interactions.
+ * 
+ * @param {string} id - HTML ID for toggle and script and association.
+ * @param {string} title - Header text. Default is "Confirm Action".
+ * @param {string} confirmLabel - Label for the primary button. Default is "Confirm".
+ * @param {string} cancelLabel - Label for the secondary button. Default is "Cancel".
+ */
+interface Props {
+  id: string;
+  title?: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+}
+
+const { 
+  id, 
+  title = "Confirm Action", 
+  confirmLabel = "Confirm", 
+  cancelLabel = "Cancel" 
+} = Astro.props;
 ---
-<div class="modal-overlay">
-  <div class="modal-box anim-scale-up">
-    <div class="modal-header"><h3>Confirm Action</h3></div>
-    <div class="modal-body"><p>Are you sure you want to delete this resource? This cannot be undone.</p></div>
-    <div class="modal-footer"><button class="btn-sec">Cancel</button><button class="btn-pri">Confirm</button></div>
+
+<dialog id={id} class="modal-dialog">
+  <div class="modal-box">
+    <div class="modal-header"><h3>{title}</h3></div>
+    <div class="modal-body">
+      <slot />
+    </div>
+    <div class="modal-footer">
+      <form method="dialog">
+        <button class="modal-btn modal-btn--sec" type="submit">{cancelLabel}</button>
+      </form>
+      <button class="modal-btn modal-btn--pri" data-modal-confirm>{confirmLabel}</button>
+    </div>
   </div>
-</div>
+</dialog>
+
 <style>
-  .modal-overlay { position: fixed; inset: 0; background: rgba(0,0,0,0.3); backdrop-filter: blur(8px); display: grid; place-items: center; z-index: 2000; }
-  .modal-box { background: rgba(255,255,255,0.05); border: 1px solid rgba(255,255,255,0.1); border-radius: 24px; padding: 2rem; width: 100%; max-width: 400px; box-shadow: 0 30px 100px rgba(0,0,0,0.5); }
-  .modal-header h3 { margin: 0; color: #fff; }
-  .modal-body p { color: #94a3b8; font-size: 0.9rem; line-height: 1.6; }
-  .modal-footer { display: flex; justify-content: flex-end; gap: 1rem; margin-top: 2rem; }
-  button { padding: 0.6rem 1.2rem; border-radius: 10px; border: none; font-weight: 700; cursor: pointer; }
-  .btn-sec { background: transparent; color: #fff; border: 1px solid rgba(255,255,255,0.1); }
-  .btn-pri { background: #6366f1; color: #fff; }
+  .modal-dialog { 
+    background: transparent; 
+    border: none; 
+    padding: 0;
+    max-width: 400px;
+    width: 100%;
+    overflow: visible;
+  }
+  
+  .modal-dialog::backdrop {
+    background: rgba(0, 0, 0, 0.4);
+    backdrop-filter: blur(8px);
+    animation: fade-in 0.3s forwards;
+  }
+  
+  .modal-box { 
+    background: var(--c-bg-elev, rgba(255,255,255,0.05)); 
+    border: 1px solid var(--c-border, rgba(255,255,255,0.1)); 
+    border-radius: var(--r-xl, 24px); 
+    padding: var(--sp-8, 2rem); 
+    box-shadow: 0 30px 100px rgba(0,0,0,0.6);
+    color: var(--c-text-1, #fff);
+  }
+  
+  .animate-open { animation: scale-up 0.3s cubic-bezier(0.175, 0.885, 0.32, 1.275) forwards; }
+
+  .modal-header h3 { margin: 0 0 var(--sp-4, 1rem); color: var(--c-text-1, #fff); font-size: 1.25rem; }
+  
+  .modal-body { color: var(--c-text-2, #94a3b8); font-size: 0.95rem; line-height: 1.6; }
+  
+  .modal-footer { display: flex; justify-content: flex-end; gap: var(--sp-4, 1rem); margin-top: var(--sp-8, 2rem); }
+  
+  .modal-btn { 
+    padding: 0.7rem 1.4rem; 
+    border-radius: var(--r-md, 12px); 
+    border: none; 
+    font-weight: 700; 
+    cursor: pointer; 
+    font-family: inherit;
+    transition: 0.2s;
+  }
+  
+  .modal-btn--sec { background: transparent; color: var(--c-text-1, #fff); border: 1px solid var(--c-border, rgba(255,255,255,0.1)); }
+  .modal-btn--sec:hover { background: rgba(255,255,255,0.05); }
+  
+  .modal-btn--pri { 
+    background: var(--c-primary, #6366f1); 
+    color: #fff; 
+    box-shadow: 0 4px 15px rgba(99, 102, 241, 0.3);
+  }
+  .modal-btn--pri:hover { transform: translateY(-2px); filter: brightness(1.1); }
+  
+  @keyframes fade-in { from { opacity: 0; } to { opacity: 1; } }
+  @keyframes scale-up { 0% { transform: scale(0.8); opacity: 0; } 100% { transform: scale(1); opacity: 1; } }
 </style>
+
+<script>
+  // Add simple show/hide logic helper if needed, but <dialog> works natively
+  document.querySelectorAll('dialog').forEach(modal => {
+    modal.addEventListener('click', (e) => {
+      if (e.target === modal) modal.close();
+    });
+  });
+</script>

package/src/components/lib/feedback/GlassProgress.astro

@@ -1,10 +1,44 @@
 ---
-interface Props { value: number; }
+/**
+ * GlassProgress — A horizontal linear progress bar with glassmorphism and gradient fill.
+ * 
+ * @param {number} value - The current progress from 0 to 100.
+ * @param {string} label - Optional accessible label message.
+ */
+interface Props {
+  value: number;
+  label?: string;
+}
+
+const { value, label = "Progress bar" } = Astro.props;
 ---
-<div class="progress-container">
-  <div class="progress-fill" style={`width: ${Astro.props.value}%`}></div>
+
+<div 
+  class="progress-container" 
+  role="progressbar" 
+  aria-valuenow={value} 
+  aria-valuemin="0" 
+  aria-valuemax="100"
+  aria-label={label}
+>
+  <div class="progress-fill" style={`width: ${Math.min(100, Math.max(0, value))}%`}></div>
 </div>
+
 <style>
-  .progress-container { height: 10px; background: rgba(255,255,255,0.05); border-radius: 10px; overflow: hidden; border: 1px solid rgba(255,255,255,0.1); }
-  .progress-fill { height: 100%; background: linear-gradient(90deg, #6366f1, #c084fc); border-radius: inherit; transition: width 0.5s cubic-bezier(0.4, 0, 0.2, 1); box-shadow: 0 0 10px rgba(99,102,241,0.4); }
+  .progress-container { 
+    height: 10px; 
+    background: var(--c-bg-elev, rgba(255,255,255,0.05)); 
+    border-radius: var(--r-full, 10px); 
+    overflow: hidden; 
+    border: 1px solid var(--c-border, rgba(255,255,255,0.1)); 
+    width: 100%;
+  }
+  
+  .progress-fill { 
+    height: 100%; 
+    background: linear-gradient(90deg, var(--c-primary, #6366f1), var(--c-primary-light, #c084fc)); 
+    border-radius: inherit; 
+    transition: width 0.6s cubic-bezier(0.16, 1, 0.3, 1); 
+    box-shadow: 0 0 10px rgba(99,102,241,0.3); 
+  }
 </style>

package/src/components/lib/feedback/IndicatorBadgeMinimal.astro

@@ -1,10 +1,63 @@
 ---
+/**
+ * IndicatorBadgeMinimal — A small notification dot typically placed on the corner of an icon or avatar.
+ * 
+ * @param {string} color - CSS color for the indicator dot. Default is 'var(--c-primary)'.
+ * @param {string} position - Corner position (top-right|top-left|bottom-right|bottom-left). Default is 'top-right'.
+ * @param {boolean} pulse - If true, adds a glowing pulse animation.
+ */
+interface Props {
+  color?: string;
+  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+  pulse?: boolean;
+}
+
+const { 
+  color = 'var(--c-primary, #6366f1)', 
+  position = 'top-right',
+  pulse = false 
+} = Astro.props;
+
+const positionStyles = {
+  'top-right': 'top: 0; right: 0; transform: translate(25%, -25%);',
+  'top-left': 'top: 0; left: 0; transform: translate(-25%, -25%);',
+  'bottom-right': 'bottom: 0; right: 0; transform: translate(25%, 25%);',
+  'bottom-left': 'bottom: 0; left: 0; transform: translate(-25%, 25%);'
+};
 ---
+
 <div class="indicator-wrap">
   <slot />
-  <span class="dot-indicator"></span>
+  <span 
+    class:list={['dot-indicator', { 'dot-indicator--pulse': pulse }]} 
+    style={`background: ${color}; ${positionStyles[position]}`}
+    aria-hidden="true"
+  ></span>
 </div>
+
 <style>
-  .indicator-wrap { position: relative; width: fit-content; }
-  .dot-indicator { position: absolute; top: 0; right: 0; width: 10px; height: 10px; background: #6366f1; border: 2px solid #080b14; border-radius: 50%; }
+  .indicator-wrap { position: relative; width: fit-content; display: inline-flex; }
+  .dot-indicator { 
+    position: absolute; 
+    width: 10px; height: 10px; 
+    border: 2px solid var(--c-bg, #080b14); 
+    border-radius: var(--r-full, 50%); 
+    z-index: 10;
+  }
+  
+  .dot-indicator--pulse::after {
+    content: "";
+    position: absolute;
+    inset: -2px;
+    border-radius: inherit;
+    border: 2px solid inherit;
+    background: inherit;
+    opacity: 0.6;
+    animation: indicator-pulse 2s infinite;
+  }
+  
+  @keyframes indicator-pulse {
+    0% { transform: scale(1); opacity: 0.6; }
+    100% { transform: scale(2.5); opacity: 0; }
+  }
 </style>

package/src/components/lib/feedback/NeonSpinner.astro

@@ -1,7 +1,44 @@
 ---
+/**
+ * NeonSpinner — A sleek, glowing loading spinner with customizable color and size.
+ * 
+ * @param {string} color - CSS color for the primary spinning segment. Default is 'var(--c-primary)'.
+ * @param {'sm'|'md'|'lg'} size - Predetermined size variant. Default is 'md'.
+ */
+interface Props {
+  color?: string;
+  size?: 'sm' | 'md' | 'lg';
+}
+
+const { color = 'var(--c-primary, #6366f1)', size = 'md' } = Astro.props;
+
+const dimensions = {
+  sm: '24px',
+  md: '40px',
+  lg: '64px'
+};
 ---
-<div class="neon-ring"></div>
+
+<div 
+  class="neon-spinner" 
+  style={`--spinner-color: ${color}; --spinner-size: ${dimensions[size]};`}
+  role="status"
+  aria-label="Loading"
+></div>
+
 <style>
-  .neon-ring { width: 40px; height: 40px; border: 4px solid #111; border-top-color: #6366f1; border-radius: 50%; animation: spin 0.8s linear infinite; box-shadow: 0 0 10px rgba(99,102,241,0.5); }
-  @keyframes spin { to { transform: rotate(360deg); } }
+  .neon-spinner { 
+    width: var(--spinner-size); 
+    height: var(--spinner-size); 
+    border: 3px solid var(--c-bg-elev, #111); 
+    border-top-color: var(--spinner-color); 
+    border-radius: var(--r-full, 50%); 
+    animation: neon-spin 0.8s linear infinite; 
+    filter: drop-shadow(0 0 5px var(--spinner-color)); 
+  }
+  
+  @keyframes neon-spin { 
+    from { transform: rotate(0deg); }
+    to { transform: rotate(360deg); } 
+  }
 </style>

package/src/components/lib/feedback/PulseDot.astro

@@ -1,12 +1,56 @@
 ---
+/**
+ * PulseDot — A status indicator with a labeled text and a pulsing dot animation.
+ * 
+ * @param {string} label - Text label (e.g. "System Active").
+ * @param {string} color - CSS color for the pulse and text. Default is '#34d399' (Success).
+ */
+interface Props {
+  label: string;
+  color?: string;
+}
+
+const { label, color = '#34d399' } = Astro.props;
 ---
-<div class="status-wrap">
-  <div class="pulse-dot"></div>
-  <span>System Active</span>
+
+<div class="status-wrap" style={`--status-color: ${color};`}>
+  <div class="pulse-dot" aria-hidden="true"></div>
+  <span class="status-text">{label}</span>
 </div>
+
 <style>
-  .status-wrap { display: flex; align-items: center; gap: 0.6rem; color: #34d399; font-weight: 700; font-size: 0.75rem; text-transform: uppercase; }
-  .pulse-dot { width: 8px; height: 8px; background: #34d399; border-radius: 50%; position: relative; }
-  .pulse-dot::after { content: ""; position: absolute; inset: 0; border-radius: 50%; border: 2px solid #34d399; animation: pulse 1.5s infinite; }
-  @keyframes pulse { 100% { opacity: 0; transform: scale(3.5); } }
+  .status-wrap { 
+    display: flex; 
+    align-items: center; 
+    gap: var(--sp-3, 0.6rem); 
+    color: var(--status-color); 
+    font-weight: 700; 
+    font-size: 0.75rem; 
+    text-transform: uppercase; 
+    letter-spacing: 0.05em;
+  }
+  
+  .pulse-dot { 
+    width: 8px; 
+    height: 8px; 
+    background: var(--status-color); 
+    border-radius: var(--r-full, 50%); 
+    position: relative; 
+  }
+  
+  .pulse-dot::after { 
+    content: ""; 
+    position: absolute; 
+    inset: 0; 
+    border-radius: 50%; 
+    border: 2px solid var(--status-color); 
+    animation: status-pulse 1.8s infinite; 
+  }
+  
+  @keyframes status-pulse { 
+    0% { transform: scale(1); opacity: 0.8; }
+    100% { transform: scale(3.5); opacity: 0; } 
+  }
+  
+  .status-text { white-space: nowrap; }
 </style>

package/src/components/lib/feedback/RatingPill.astro

@@ -1,13 +1,43 @@
 ---
-interface Props { score: number; }
-const { score } = Astro.props;
+/**
+ * RatingPill — A compact badge displaying a numeric score or rating stars.
+ * 
+ * @param {number} score - The rating value (0 to 5).
+ * @param {boolean} showStar - If true, displays a star icon suffix. Default is true.
+ */
+interface Props {
+  score: number;
+  showStar?: boolean;
+}
+
+const { score, showStar = true } = Astro.props;
+
+const status = score >= 4 ? 'high' : score >= 3 ? 'mid' : 'low';
 ---
-<div class:list={["rate-pill", { "high": score >= 4, "mid": score >= 3 && score < 4, "low": score < 3 }]}>
-  {score.toFixed(1)} ★
+
+<div class:list={["rate-pill", `rate-pill--${status}`]}>
+  <span class="rate-pill__val">{score.toFixed(1)}</span>
+  {showStar && <span class="rate-pill__star" aria-hidden="true">★</span>}
 </div>
+
 <style>
-  .rate-pill { padding: 4px 12px; border-radius: 100px; font-weight: 800; font-size: 0.75rem; color: #fff; width: fit-content; }
-  .high { background: #10b981; }
-  .mid { background: #f59e0b; }
-  .low { background: #ef4444; }
+  .rate-pill { 
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    padding: var(--sp-1, 4px) var(--sp-3, 12px); 
+    border-radius: var(--r-full, 100px); 
+    font-weight: 800; 
+    font-size: 0.75rem; 
+    color: #fff; 
+    width: fit-content; 
+    box-shadow: 0 4px 10px rgba(0,0,0,0.1);
+  }
+  
+  .rate-pill--high { background: #10b981; }
+  .rate-pill--mid { background: #f59e0b; }
+  .rate-pill--low { background: #ef4444; }
+  
+  .rate-pill__star { font-size: 0.8rem; margin-top: -1px; }
+  .rate-pill__val { font-family: inherit; }
 </style>

package/src/components/lib/feedback/ShakeErrorGroup.astro

@@ -1,7 +1,48 @@
 ---
+/**
+ * ShakeError — A feedback container that shakes horizontally to indicate failure or invalid input.
+ * 
+ * @param {string} message - The error message to display.
+ * @param {boolean} active - If true, triggers the shake animation once.
+ */
+interface Props {
+  message: string;
+  active?: boolean;
+}
+
+const { message, active = false } = Astro.props;
 ---
-<div class="shake-box error"><span>Invalid Credentials</span></div>
+
+<div class:list={["shake-box", { "shake-box--active": active }]} role="alert">
+  <span class="shake-box__icon" aria-hidden="true">⚠️</span>
+  <span class="shake-box__msg">{message}</span>
+</div>
+
 <style>
-  .shake-box.error { animation: shake 0.4s cubic-bezier(.36,.07,.19,.97) both; background: rgba(239, 68, 68, 0.1); border: 1px solid #ef4444; color: #f87171; padding: 1rem; border-radius: 10px; text-align: center; font-weight: 600; }
-  @keyframes shake { 10%, 90% { transform: translateX(-1px); } 20%, 80% { transform: translateX(2px); } 30%, 50%, 70% { transform: translateX(-4px); } 40%, 60% { transform: translateX(4px); } }
+  .shake-box { 
+    display: flex; 
+    align-items: center; 
+    gap: var(--sp-3, 0.75rem);
+    background: rgba(239, 68, 68, 0.08); 
+    border: 1px solid var(--c-error, #ef4444); 
+    color: #f87171; 
+    padding: var(--sp-4, 1rem); 
+    border-radius: var(--r-md, 10px); 
+    text-align: center; 
+    font-weight: 600; 
+    width: 100%;
+    box-sizing: border-box;
+  }
+  
+  .shake-box--active { animation: shake-kb 0.5s cubic-bezier(.36,.07,.19,.97) both; }
+  
+  .shake-box__icon { font-size: 1rem; }
+  .shake-box__msg { font-size: 0.9rem; }
+
+  @keyframes shake-kb { 
+    10%, 90% { transform: translateX(-1px); } 
+    20%, 80% { transform: translateX(2px); } 
+    30%, 50%, 70% { transform: translateX(-4px); } 
+    40%, 60% { transform: translateX(4px); } 
+  }
 </style>

package/src/components/lib/feedback/SimpleTooltip.astro

@@ -1,10 +1,59 @@
 ---
+/**
+ * SimpleTooltip — A lightweight hover-based hint for buttons or icons.
+ * 
+ * @param {string} text - The tooltip content text.
+ * @param {'top'|'bottom'|'left'|'right'} position - Preferred placement relative to the child. Default is 'top'.
+ */
+interface Props {
+  text: string;
+  position?: 'top' | 'bottom' | 'left' | 'right';
+}
+
+const { text, position = 'top' } = Astro.props;
 ---
-<div class="tooltip-wrap" data-tip="Click to copy ID">
+
+<div class:list={["tooltip-wrap", `tooltip-wrap--${position}`]} data-tip={text}>
   <slot />
 </div>
+
 <style>
-  .tooltip-wrap { position: relative; display: inline-block; cursor: help; }
-  .tooltip-wrap::after { content: attr(data-tip); position: absolute; bottom: 125%; left: 50%; transform: translateX(-50%); padding: 5px 10px; background: #111; color: #fff; font-size: 0.75rem; border-radius: 6px; white-space: nowrap; opacity: 0; pointer-events: none; transition: 0.2s; border: 1px solid rgba(255,255,255,0.1); box-shadow: 0 5px 15px rgba(0,0,0,0.4); }
-  .tooltip-wrap:hover::after { opacity: 1; bottom: 110%; }
+  .tooltip-wrap { 
+    position: relative; 
+    display: inline-flex; 
+    cursor: help; 
+  }
+  
+  .tooltip-wrap::after { 
+    content: attr(data-tip); 
+    position: absolute; 
+    padding: var(--sp-2, 6px) var(--sp-3, 12px); 
+    background: var(--c-bg-elev, #111); 
+    color: var(--c-text-1, #fff); 
+    font-size: 0.72rem; 
+    font-weight: 600;
+    border-radius: var(--r-sm, 6px); 
+    white-space: nowrap; 
+    opacity: 0; 
+    pointer-events: none; 
+    transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1); 
+    border: 1px solid var(--c-border, rgba(255,255,255,0.1)); 
+    box-shadow: 0 10px 30px rgba(0,0,0,0.5); 
+    z-index: 100;
+  }
+  
+  /* Positions */
+  .tooltip-wrap--top::after { bottom: 125%; left: 50%; transform: translateX(-50%) translateY(5px); }
+  .tooltip-wrap--bottom::after { top: 125%; left: 50%; transform: translateX(-50%) translateY(-5px); }
+  .tooltip-wrap--left::after { right: 125%; top: 50%; transform: translateY(-50%) translateX(5px); }
+  .tooltip-wrap--right::after { left: 125%; top: 50%; transform: translateY(-50%) translateX(-5px); }
+
+  /* Hover States */
+  .tooltip-wrap:hover::after { 
+    opacity: 1; 
+  }
+  .tooltip-wrap--top:hover::after { transform: translateX(-50%) translateY(0); }
+  .tooltip-wrap--bottom:hover::after { transform: translateX(-50%) translateY(0); }
+  .tooltip-wrap--left:hover::after { transform: translateY(-50%) translateX(0); }
+  .tooltip-wrap--right:hover::after { transform: translateY(-50%) translateX(0); }
 </style>

package/src/components/lib/feedback/SkeletonList.astro

@@ -1,20 +1,66 @@
 ---
+/**
+ * SkeletonList — Shimmering loading placeholder for lists or feed items.
+ * 
+ * @param {number} count - Number of skeleton items to render. Default is 3.
+ */
+interface Props {
+  count?: number;
+}
+
+const { count = 3 } = Astro.props;
 ---
-<div class="skeleton-list">
-  {[1,2,3].map(() => (
-    <div class="skel-item">
-      <div class="skel-avatar"></div>
-      <div class="skel-lines"><div></div><div></div></div>
+
+<div class="skeleton-list" aria-hidden="true">
+  {Array.from({ length: count }).map(() => (
+    <div class="skeleton-item">
+      <div class="skeleton-avatar"></div>
+      <div class="skeleton-content">
+        <div class="skeleton-line skeleton-line--title"></div>
+        <div class="skeleton-line skeleton-line--body"></div>
+      </div>
     </div>
   ))}
 </div>
+
 <style>
-  .skel-item { display: flex; gap: 1rem; padding: 1rem 0; border-bottom: 1px solid rgba(255,255,255,0.05); }
-  .skel-avatar { width: 40px; height: 40px; border-radius: 50%; background: rgba(255,255,255,0.05); }
-  .skel-lines { flex: 1; display: flex; flex-direction: column; gap: 8px; }
-  .skel-lines div { height: 10px; background: rgba(255,255,255,0.05); border-radius: 5px; }
-  .skel-lines div:last-child { width: 60%; }
-  .skel-item div { position: relative; overflow: hidden; }
-  .skel-item div::after { content: ""; position: absolute; inset: 0; background: linear-gradient(90deg, transparent, rgba(255,255,255,0.03), transparent); animation: shimmer 1.5s infinite; }
-  @keyframes shimmer { 100% { transform: translateX(100%); } }
+  .skeleton-list { display: flex; flex-direction: column; width: 100%; }
+  
+  .skeleton-item { 
+    display: flex; gap: var(--sp-4, 1rem); 
+    padding: var(--sp-4, 1rem) 0; 
+    border-bottom: 1px solid var(--c-border, rgba(255,255,255,0.05)); 
+  }
+  
+  .skeleton-avatar { 
+    width: 48px; height: 48px; 
+    border-radius: var(--r-full, 50%); 
+    background: var(--c-bg-elev, rgba(255,255,255,0.05)); 
+    flex-shrink: 0;
+  }
+  
+  .skeleton-content { flex: 1; display: flex; flex-direction: column; gap: 10px; justify-content: center; }
+  
+  .skeleton-line { 
+    height: 12px; 
+    background: var(--c-bg-elev, rgba(255,255,255,0.05)); 
+    border-radius: var(--r-sm, 6px); 
+    position: relative; overflow: hidden;
+  }
+
+  .skeleton-line--title { width: 40%; height: 14px; }
+  .skeleton-line--body { width: 85%; }
+  
+  .skeleton-item div::after { 
+    content: ""; 
+    position: absolute; 
+    inset: 0; 
+    background: linear-gradient(90deg, transparent, rgba(255,255,255,0.04), transparent); 
+    animation: skeleton-shimmer 1.8s infinite; 
+    transform: translateX(-100%);
+  }
+  
+  @keyframes skeleton-shimmer { 
+    100% { transform: translateX(100%); } 
+  }
 </style>

package/src/components/lib/feedback/Spotlight.astro

@@ -1,9 +1,54 @@
 ---
+/**
+ * Spotlight — A visual emphasis component that dims the page and highlights its children.
+ * 
+ * @param {boolean} active - If true, the spotlight overlay is visible. Default is false.
+ * @param {number} opacity - Background overlay opacity (0 to 1). Default is 0.7.
+ */
+interface Props {
+  active?: boolean;
+  opacity?: number;
+}
+
+const { active = false, opacity = 0.7 } = Astro.props;
 ---
-<div class="spotlight">
-  <div class="focused-content"><slot /></div>
+
+<div class:list={["spotlight-wrap", { "spotlight-wrap--active": active }]} style={`--spotlight-opacity: ${opacity};`}>
+  <div class="spotlight-content">
+    <slot />
+  </div>
 </div>
+
 <style>
-  .spotlight { position: relative; z-index: 100; border-radius: 12px; box-shadow: 0 0 0 9999px rgba(0,0,0,0.7); }
-  .focused-content { background: #fff; border-radius: inherit; overflow: hidden; }
+  .spotlight-wrap { 
+    position: relative; 
+    display: inline-block;
+    transition: z-index 0.3s;
+  }
+  
+  .spotlight-wrap--active { z-index: 2000; }
+  
+  .spotlight-wrap--active::after {
+    content: "";
+    position: fixed;
+    inset: 0;
+    background: rgba(0,0,0,var(--spotlight-opacity));
+    backdrop-filter: blur(4px);
+    z-index: -1;
+    animation: spotlight-fade 0.3s forwards;
+    pointer-events: none;
+  }
+  
+  .spotlight-content { 
+    position: relative;
+    border-radius: var(--r-md, 12px); 
+    transition: transform 0.3s;
+  }
+  
+  .spotlight-wrap--active .spotlight-content {
+    transform: scale(1.05);
+    box-shadow: 0 0 50px rgba(255,255,255,0.1);
+  }
+
+  @keyframes spotlight-fade { from { opacity: 0; } to { opacity: 1; } }
 </style>