@fragments-sdk/cli 0.7.11 → 0.7.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/cli",
-  "version": "0.7.11",
+  "version": "0.7.13",
   "license": "FSL-1.1-MIT",
   "description": "CLI, MCP server, and dev tools for Fragments design system",
   "author": "Conan McNicholl",

package/src/viewer/components/App.tsx

@@ -15,7 +15,6 @@ import { useToast } from "./Toast.js";
 
 // Toolbar
 import { PreviewToolbar } from "./PreviewToolbar.js";
-import { getBackgroundStyle } from "../constants/ui.js";
 
 // Preview & Rendering
 import { PreviewArea } from "./PreviewArea.js";
@@ -65,16 +64,14 @@ export function App({ fragments }: AppProps) {
   // UI state (modals, panels, view modes)
   const { state: uiState, actions: uiActions } = useAppState();
 
-  // View settings (zoom, background, viewport, theme)
+  // View settings (zoom, viewport, theme)
   const viewSettings = useViewSettings({
     initialState: {
       zoom: urlState.zoom as any,
-      background: urlState.background as any,
       viewport: urlState.viewport as any,
       customSize: { width: urlState.customWidth, height: urlState.customHeight },
     },
     onZoomChange: (zoom) => setUrlViewSettings({ zoom }),
-    onBackgroundChange: (bg) => setUrlViewSettings({ background: bg }),
     onViewportChange: (vp, size) => setUrlViewSettings({
       viewport: vp,
       customWidth: size?.width,
@@ -270,11 +267,6 @@ export function App({ fragments }: AppProps) {
     }
   }, [copyUrl, success, uiActions]);
 
-  const focusSearchInput = useCallback(() => {
-    searchInputRef.current?.focus();
-    searchInputRef.current?.select();
-  }, []);
-
   // Sorted fragment paths for keyboard navigation
   const sortedFragmentPaths = useMemo(() => {
     return [...fragments]
@@ -328,7 +320,7 @@ export function App({ fragments }: AppProps) {
       toggleResponsive: () => uiActions.setMultiViewport(!uiState.showMultiViewport),
       copyLink: handleCopyLink,
       showHelp: uiActions.toggleShortcutsHelp,
-      openSearch: focusSearchInput,
+      openSearch: () => uiActions.setCommandPalette(true),
       escape: () => {
         if (document.activeElement === searchInputRef.current) {
           if (searchQuery) {
@@ -391,6 +383,7 @@ export function App({ fragments }: AppProps) {
           activeFragment && !uiState.showHealthDashboard ? (
             <TopToolbar
               fragment={activeFragment}
+              viewSettings={viewSettings}
               uiState={uiState}
               uiActions={uiActions}
               figmaUrl={figmaUrl}
@@ -455,19 +448,6 @@ export function App({ fragments }: AppProps) {
           <div id="preview-layout" style={{ display: 'flex', height: '100%', flexDirection: panelDock === "bottom" ? 'column' : 'row' }}>
             {/* Main Content Area */}
             <div style={{ flex: 1, display: 'flex', flexDirection: 'column', minWidth: 0, minHeight: 0 }}>
-              <PreviewControlsBar
-                zoom={viewSettings.zoom}
-                background={viewSettings.background}
-                onZoomChange={viewSettings.setZoom}
-                onBackgroundChange={viewSettings.setBackground}
-                showMatrixView={uiState.showMatrixView}
-                showMultiViewport={uiState.showMultiViewport}
-                panelOpen={uiState.panelOpen}
-                onToggleMatrix={() => uiActions.setMatrixView(!uiState.showMatrixView)}
-                onToggleMultiViewport={() => uiActions.setMultiViewport(!uiState.showMultiViewport)}
-                onTogglePanel={uiActions.togglePanel}
-              />
-
               {/* Preview Area */}
               <div
                 id="preview-canvas"
@@ -475,7 +455,6 @@ export function App({ fragments }: AppProps) {
                   flex: 1,
                   overflow: 'auto',
                   position: 'relative',
-                  ...(uiState.showMatrixView ? {} : getBackgroundStyle(viewSettings.background)),
                 }}
               >
                 {variantCount === 0 ? (
@@ -487,7 +466,6 @@ export function App({ fragments }: AppProps) {
                     variants={variants}
                     focusedVariantIndex={safeVariantIndex}
                     zoom={viewSettings.zoom}
-                    background={viewSettings.background}
                     viewport={viewSettings.viewport}
                     customSize={viewSettings.customSize}
                     previewTheme={resolvedTheme}
@@ -505,7 +483,6 @@ export function App({ fragments }: AppProps) {
                     variant={activeVariant}
                     variants={variants}
                     zoom={viewSettings.zoom}
-                    background={viewSettings.background}
                     viewport={viewSettings.viewport}
                     customSize={viewSettings.customSize}
                     previewTheme={resolvedTheme}
@@ -571,6 +548,7 @@ export function App({ fragments }: AppProps) {
 // Top Toolbar Component
 interface TopToolbarProps {
   fragment: { path: string; fragment: FragmentDefinition };
+  viewSettings: ReturnType<typeof useViewSettings>;
   uiState: ReturnType<typeof useAppState>['state'];
   uiActions: ReturnType<typeof useAppState>['actions'];
   figmaUrl?: string;
@@ -614,7 +592,6 @@ function HeaderSearch({ value, onChange, inputRef }: HeaderSearchProps) {
         placeholder="Search components"
         aria-label="Search components"
         size="sm"
-        shortcut="⌘K"
         style={{ width: '240px' }}
       />
     </Header.Search>
@@ -723,11 +700,12 @@ function PreviewAside({
               </a>
               {variants.map((variant, index) => {
                 const active = index === focusedVariantIndex;
+                const anchorId = getVariantSectionId(fragment.meta.name, variant.name);
 
                 return (
                   <a
                     key={variant.name}
-                    href="#preview-canvas"
+                    href={`#${anchorId}`}
                     style={getLinkStyle(active)}
                     onClick={(event) => {
                       event.preventDefault();
@@ -769,6 +747,7 @@ function PreviewAside({
 
 function TopToolbar({
   fragment,
+  viewSettings,
   uiState,
   uiActions,
   figmaUrl,
@@ -790,6 +769,48 @@ function TopToolbar({
       <HeaderSearch value={searchQuery} onChange={onSearchChange} inputRef={searchInputRef} />
       <Header.Spacer />
       <Header.Actions>
+        <PreviewToolbar
+          zoom={viewSettings.zoom}
+          onZoomChange={viewSettings.setZoom}
+        />
+        <Separator orientation="vertical" style={{ height: '16px' }} />
+        <Tooltip content={uiState.showMatrixView ? "Disable matrix view" : "Enable matrix view"}>
+          <Button
+            variant="ghost"
+            size="sm"
+            aria-pressed={uiState.showMatrixView}
+            aria-label="Toggle matrix view"
+            onClick={() => uiActions.setMatrixView(!uiState.showMatrixView)}
+            style={uiState.showMatrixView ? { color: 'var(--color-accent)', backgroundColor: 'var(--bg-hover)' } : {}}
+          >
+            <GridFour size={16} />
+          </Button>
+        </Tooltip>
+        <Tooltip content={uiState.showMultiViewport ? "Disable responsive view" : "Enable responsive view"}>
+          <Button
+            variant="ghost"
+            size="sm"
+            aria-pressed={uiState.showMultiViewport}
+            aria-label="Toggle responsive view"
+            onClick={() => uiActions.setMultiViewport(!uiState.showMultiViewport)}
+            style={uiState.showMultiViewport ? { color: 'var(--color-accent)', backgroundColor: 'var(--bg-hover)' } : {}}
+          >
+            <DeviceMobile size={16} />
+          </Button>
+        </Tooltip>
+        <Tooltip content={uiState.panelOpen ? "Hide addons panel" : "Show addons panel"}>
+          <Button
+            variant="ghost"
+            size="sm"
+            aria-pressed={uiState.panelOpen}
+            aria-label="Toggle addons panel"
+            onClick={uiActions.togglePanel}
+            style={uiState.panelOpen ? { color: 'var(--color-accent)', backgroundColor: 'var(--bg-hover)' } : {}}
+          >
+            <Rows size={16} />
+          </Button>
+        </Tooltip>
+        <Separator orientation="vertical" style={{ height: '16px' }} />
         {figmaUrl && (
           <>
             <Tooltip content={uiState.showComparison ? "Hide Figma comparison" : "Compare with Figma design"}>
@@ -856,93 +877,12 @@ function getVariantSectionId(componentName: string, variantName: string): string
   return `preview-${normalizeAnchorSegment(componentName)}-${normalizeAnchorSegment(variantName)}`;
 }
 
-interface PreviewControlsBarProps {
-  zoom: ReturnType<typeof useViewSettings>["zoom"];
-  background: ReturnType<typeof useViewSettings>["background"];
-  onZoomChange: ReturnType<typeof useViewSettings>["setZoom"];
-  onBackgroundChange: ReturnType<typeof useViewSettings>["setBackground"];
-  showMatrixView: boolean;
-  showMultiViewport: boolean;
-  panelOpen: boolean;
-  onToggleMatrix: () => void;
-  onToggleMultiViewport: () => void;
-  onTogglePanel: () => void;
-}
-
-function PreviewControlsBar({
-  zoom,
-  background,
-  onZoomChange,
-  onBackgroundChange,
-  showMatrixView,
-  showMultiViewport,
-  panelOpen,
-  onToggleMatrix,
-  onToggleMultiViewport,
-  onTogglePanel,
-}: PreviewControlsBarProps) {
-  const toggleButtonStyle = (active: boolean): CSSProperties => (
-    active ? { color: 'var(--color-accent)', backgroundColor: 'var(--bg-hover)' } : {}
-  );
-
-  return (
-    <div style={{ padding: '8px 16px', borderBottom: '1px solid var(--border)', backgroundColor: 'var(--bg-primary)', flexShrink: 0 }}>
-      <Stack direction="row" gap="sm" align="center" justify="end">
-        <PreviewToolbar
-          zoom={zoom}
-          background={background}
-          onZoomChange={onZoomChange}
-          onBackgroundChange={onBackgroundChange}
-        />
-        <Separator orientation="vertical" style={{ height: '16px' }} />
-        <Tooltip content={showMatrixView ? "Disable matrix view" : "Enable matrix view"}>
-          <Button
-            variant="ghost"
-            size="sm"
-            aria-pressed={showMatrixView}
-            aria-label="Toggle matrix view"
-            onClick={onToggleMatrix}
-            style={toggleButtonStyle(showMatrixView)}
-          >
-            <GridFour size={16} />
-          </Button>
-        </Tooltip>
-        <Tooltip content={showMultiViewport ? "Disable responsive view" : "Enable responsive view"}>
-          <Button
-            variant="ghost"
-            size="sm"
-            aria-pressed={showMultiViewport}
-            aria-label="Toggle responsive view"
-            onClick={onToggleMultiViewport}
-            style={toggleButtonStyle(showMultiViewport)}
-          >
-            <DeviceMobile size={16} />
-          </Button>
-        </Tooltip>
-        <Tooltip content={panelOpen ? "Hide addons panel" : "Show addons panel"}>
-          <Button
-            variant="ghost"
-            size="sm"
-            aria-pressed={panelOpen}
-            aria-label="Toggle addons panel"
-            onClick={onTogglePanel}
-            style={toggleButtonStyle(panelOpen)}
-          >
-            <Rows size={16} />
-          </Button>
-        </Tooltip>
-      </Stack>
-    </div>
-  );
-}
-
 interface AllVariantsPreviewProps {
   componentName: string;
   fragmentPath: string;
   variants: FragmentVariant[];
   focusedVariantIndex: number;
   zoom: ReturnType<typeof useViewSettings>["zoom"];
-  background: ReturnType<typeof useViewSettings>["background"];
   viewport: ReturnType<typeof useViewSettings>["viewport"];
   customSize: ReturnType<typeof useViewSettings>["customSize"];
   previewTheme: ReturnType<typeof useTheme>["resolvedTheme"];
@@ -960,7 +900,6 @@ function AllVariantsPreview({
   variants,
   focusedVariantIndex,
   zoom,
-  background,
   viewport,
   customSize,
   previewTheme,
@@ -999,7 +938,6 @@ function AllVariantsPreview({
               variant={variant}
               variants={variants}
               zoom={zoom}
-              background={background}
               viewport={viewport}
               customSize={customSize}
               previewTheme={previewTheme}

package/src/viewer/components/CommandPalette.tsx

@@ -336,10 +336,16 @@ export function CommandPalette({
 function fuzzyScore(text: string, query: string): number {
   if (!query) return 1;
 
+  // Require substring match for short queries to avoid scattered single-char noise
+  if (query.length <= 3 && !text.includes(query)) {
+    return 0;
+  }
+
   let score = 0;
   let queryIndex = 0;
   let consecutiveBonus = 0;
   let lastMatchIndex = -2;
+  let maxGap = 0;
 
   for (let i = 0; i < text.length && queryIndex < query.length; i++) {
     if (text[i] === query[queryIndex]) {
@@ -351,6 +357,11 @@ function fuzzyScore(text: string, query: string): number {
         score += consecutiveBonus;
       } else {
         consecutiveBonus = 0;
+        // Track max gap between matches
+        if (lastMatchIndex >= 0) {
+          const gap = i - lastMatchIndex;
+          if (gap > maxGap) maxGap = gap;
+        }
       }
 
       // Bonus for matching at word start
@@ -366,6 +377,11 @@ function fuzzyScore(text: string, query: string): number {
   // Only return score if all query characters were found
   if (queryIndex < query.length) return 0;
 
+  // Penalize large gaps between matched characters
+  if (maxGap > 5) {
+    score -= maxGap;
+  }
+
   // Bonus for shorter results (more relevant)
   score += Math.max(0, 20 - text.length);
 
@@ -375,5 +391,5 @@ function fuzzyScore(text: string, query: string): number {
   // Bonus for starts with
   if (text.startsWith(query)) score += 30;
 
-  return score;
+  return Math.max(score, 0) || 0;
 }

package/src/viewer/components/IsolatedPreviewFrame.tsx

@@ -162,91 +162,88 @@ export const IsolatedPreviewFrame = memo(function IsolatedPreviewFrame({
       onMouseLeave={() => setIsHovered(false)}
     >
       {/* Skeleton loading overlay (initial load) */}
-      <div
-        style={{
-          position: 'absolute',
-          inset: 0,
-          zIndex: 10,
-          transition: 'opacity 150ms',
-          opacity: showSkeleton ? 1 : 0,
-          pointerEvents: showSkeleton ? 'auto' : 'none',
-          background: 'rgba(255, 255, 255, 0.95)',
-        }}
-      >
-        <PreviewSkeleton />
-      </div>
+      {showSkeleton && (
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            zIndex: 10,
+            background: 'var(--bg-primary, rgba(255, 255, 255, 0.95))',
+          }}
+        >
+          <PreviewSkeleton />
+        </div>
+      )}
 
       {/* Spinner overlay (subsequent renders) */}
-      <div
-        style={{
-          position: 'absolute',
-          inset: 0,
-          zIndex: 10,
-          display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'center',
-          transition: 'opacity 150ms',
-          opacity: showSpinner ? 1 : 0,
-          pointerEvents: showSpinner ? 'auto' : 'none',
-          background: 'rgba(255, 255, 255, 0.8)',
-        }}
-      >
-        <div style={{ display: 'flex', alignItems: 'center', gap: 8, color: '#6b7280', fontSize: 14 }}>
-          <LoadingSpinner />
-          <span>Rendering...</span>
+      {showSpinner && (
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            zIndex: 10,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            background: 'color-mix(in srgb, var(--bg-primary, white) 80%, transparent)',
+          }}
+        >
+          <div style={{ display: 'flex', alignItems: 'center', gap: 8, color: 'var(--text-tertiary, #6b7280)', fontSize: 14 }}>
+            <LoadingSpinner />
+            <span>Rendering...</span>
+          </div>
         </div>
-      </div>
+      )}
 
       {/* Error overlay */}
-      <div
-        style={{
-          position: 'absolute',
-          inset: 0,
-          zIndex: 10,
-          display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'center',
-          padding: '16px',
-          transition: 'opacity 150ms',
-          opacity: frameError && !isLoading ? 1 : 0,
-          pointerEvents: frameError && !isLoading ? 'auto' : 'none',
-          background: 'rgba(254, 242, 242, 0.95)',
-        }}
-      >
+      {frameError && !isLoading && (
         <div
           style={{
-            background: 'white',
-            border: '1px solid #fecaca',
-            borderRadius: 8,
-            padding: 16,
-            maxWidth: 400,
+            position: 'absolute',
+            inset: 0,
+            zIndex: 10,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            padding: '16px',
+            background: 'rgba(254, 242, 242, 0.95)',
           }}
         >
-          <div style={{ color: '#dc2626', fontWeight: 500, marginBottom: 8 }}>
-            Preview Error
-          </div>
-          <div style={{ color: '#991b1b', fontSize: 13, marginBottom: retryCount < MAX_RETRIES ? 12 : 0 }}>
-            {frameError}
+          <div
+            style={{
+              background: 'white',
+              border: '1px solid #fecaca',
+              borderRadius: 8,
+              padding: 16,
+              maxWidth: 400,
+            }}
+          >
+            <div style={{ color: '#dc2626', fontWeight: 500, marginBottom: 8 }}>
+              Preview Error
+            </div>
+            <div style={{ color: '#991b1b', fontSize: 13, marginBottom: retryCount < MAX_RETRIES ? 12 : 0 }}>
+              {frameError}
+            </div>
+            {retryCount < MAX_RETRIES && (
+              <button
+                onClick={handleRetry}
+                style={{
+                  padding: '6px 12px',
+                  fontSize: 13,
+                  fontWeight: 500,
+                  color: 'white',
+                  background: '#dc2626',
+                  border: 'none',
+                  borderRadius: 6,
+                  cursor: 'pointer',
+                }}
+              >
+                Retry ({MAX_RETRIES - retryCount} remaining)
+              </button>
+            )}
           </div>
-          {retryCount < MAX_RETRIES && (
-            <button
-              onClick={handleRetry}
-              style={{
-                padding: '6px 12px',
-                fontSize: 13,
-                fontWeight: 500,
-                color: 'white',
-                background: '#dc2626',
-                border: 'none',
-                borderRadius: 6,
-                cursor: 'pointer',
-              }}
-            >
-              Retry ({MAX_RETRIES - retryCount} remaining)
-            </button>
-          )}
         </div>
-      </div>
+      )}
 
       {/* The iframe */}
       <iframe

package/src/viewer/components/IsolatedRender.tsx

@@ -1,7 +1,7 @@
 import { useMemo, useEffect, useState } from "react";
 import type { FragmentDefinition } from "../../core/index.js";
 import { VariantRenderer } from "./VariantRenderer.js";
-import { getBackgroundStyle, type BackgroundOption, type ZoomLevel } from "../constants/ui.js";
+import { type ZoomLevel } from "../constants/ui.js";
 
 interface IsolatedRenderProps {
   fragments: Array<{ path: string; fragment: FragmentDefinition }>;
@@ -10,7 +10,7 @@ interface IsolatedRenderProps {
 /**
  * Isolated render component for screenshot capture and standalone viewing.
  * Renders a single variant with minimal UI for visual testing.
- * URL params: ?isolated=true&component=Name&variant=VariantName&zoom=100&bg=white&theme=light
+ * URL params: ?isolated=true&component=Name&variant=VariantName&zoom=100&theme=light
  */
 export function IsolatedRender({ fragments }: IsolatedRenderProps) {
   const [ready, setReady] = useState(false);
@@ -19,15 +19,11 @@ export function IsolatedRender({ fragments }: IsolatedRenderProps) {
   const params = useMemo(() => {
     const searchParams = new URLSearchParams(window.location.search);
     const zoomParam = parseInt(searchParams.get("zoom") || "100", 10);
-    const bgParam = searchParams.get("bg") || "white";
     return {
       component: searchParams.get("component"),
       variant: searchParams.get("variant"),
       theme: searchParams.get("theme") || "light",
       zoom: [50, 75, 100, 150, 200].includes(zoomParam) ? zoomParam as ZoomLevel : 100 as ZoomLevel,
-      background: ["white", "black", "checkerboard", "transparent"].includes(bgParam)
-        ? bgParam as BackgroundOption
-        : "white" as BackgroundOption,
     };
   }, []);
 
@@ -101,7 +97,7 @@ export function IsolatedRender({ fragments }: IsolatedRenderProps) {
         display: 'flex',
         alignItems: 'center',
         justifyContent: 'center',
-        ...getBackgroundStyle(params.background),
+        backgroundColor: 'var(--bg-primary)',
       }}
     >
       <div

package/src/viewer/components/LeftSidebar.tsx

@@ -14,16 +14,26 @@ function fuzzyMatch(text: string, pattern: string): FuzzyMatch | null {
   const textLower = text.toLowerCase();
   const patternLower = pattern.toLowerCase();
 
+  // Require substring match for short queries (<=3 chars) to avoid scattered single-char noise
+  if (patternLower.length <= 3 && !textLower.includes(patternLower)) {
+    return null;
+  }
+
   const indices: number[] = [];
   let patternIdx = 0;
   let score = 0;
   let consecutiveBonus = 0;
+  let maxGap = 0;
 
   for (let i = 0; i < textLower.length && patternIdx < patternLower.length; i++) {
     if (textLower[i] === patternLower[patternIdx]) {
       indices.push(i);
-      if (indices.length > 1 && indices[indices.length - 2] === i - 1) {
-        consecutiveBonus += 5;
+      if (indices.length > 1) {
+        const gap = i - indices[indices.length - 2];
+        if (gap === 1) {
+          consecutiveBonus += 5;
+        }
+        if (gap > maxGap) maxGap = gap;
       }
       if (i === 0 || text[i - 1] === ' ' || text[i - 1] === '-' || text[i - 1] === '_') {
         score += 10;
@@ -36,9 +46,19 @@ function fuzzyMatch(text: string, pattern: string): FuzzyMatch | null {
     return null;
   }
 
+  // Penalize large gaps between matched characters
+  if (maxGap > 5) {
+    score -= maxGap * 2;
+  }
+
   score += consecutiveBonus;
   score += (patternLower.length / textLower.length) * 20;
 
+  // Reject very low scores (scattered single-char matches)
+  if (score <= 0 && patternLower.length > 1) {
+    return null;
+  }
+
   return { score, indices };
 }
 
@@ -364,7 +384,7 @@ export function LeftSidebar({ fragments, activeFragment, searchQuery, onSelect,
       <Sidebar.Footer>
         <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', width: '100%' }}>
           <Text size="xs" color="tertiary">
-            {isFilterActive ? `${flatItems.length} / ${fragments.length}` : fragments.length} components
+            {isFilterActive || searchResults ? `${flatItems.length} of ${fragments.length}` : fragments.length} components
           </Text>
           <Sidebar.CollapseToggle />
         </div>

package/src/viewer/components/MultiViewportPreview.tsx

@@ -10,7 +10,6 @@ import { useState, type ReactNode } from "react";
 import { ErrorBoundary } from "./ErrorBoundary.js";
 import { IsolatedPreviewFrame } from "./IsolatedPreviewFrame.js";
 import { ChevronDownIcon } from "./Icons.js";
-import { getBackgroundStyle, type BackgroundOption } from "../constants/ui.js";
 
 interface ViewportConfig {
   name: string;
@@ -50,8 +49,6 @@ interface MultiViewportPreviewProps {
   renderContent: () => ReactNode;
   /** Preview theme */
   previewTheme: "light" | "dark";
-  /** Background option for preview */
-  background: BackgroundOption;
   /** Base zoom level (used for scaling if needed) */
   zoom: number;
   /** Whether to use iframe isolation */
@@ -64,7 +61,6 @@ export function MultiViewportPreview({
   variantName,
   renderContent,
   previewTheme,
-  background,
   zoom,
   useIframeIsolation = true,
 }: MultiViewportPreviewProps) {
@@ -207,7 +203,6 @@ export function MultiViewportPreview({
               variantName={variantName}
               renderContent={renderContent}
               previewTheme={previewTheme}
-              background={background}
               useIframeIsolation={useIframeIsolation}
             />
           ))}
@@ -224,7 +219,6 @@ interface ViewportPanelProps {
   variantName: string;
   renderContent: () => ReactNode;
   previewTheme: "light" | "dark";
-  background: BackgroundOption;
   useIframeIsolation: boolean;
 }
 
@@ -235,7 +229,6 @@ function ViewportPanel({
   variantName,
   renderContent,
   previewTheme,
-  background,
   useIframeIsolation,
 }: ViewportPanelProps) {
   if (viewport.type === "desktop") {
@@ -245,7 +238,6 @@ function ViewportPanel({
         height={viewport.height}
         label={viewport.name}
         previewTheme={previewTheme}
-        background={background}
         componentName={componentName}
         fragmentPath={fragmentPath}
         variantName={variantName}
@@ -262,7 +254,6 @@ function ViewportPanel({
       height={viewport.height}
       label={viewport.name}
       previewTheme={previewTheme}
-      background={background}
       componentName={componentName}
       fragmentPath={fragmentPath}
       variantName={variantName}
@@ -278,7 +269,6 @@ interface DeviceMockupProps {
   height: number;
   label: string;
   previewTheme: "light" | "dark";
-  background: BackgroundOption;
   componentName: string;
   fragmentPath: string;
   variantName: string;
@@ -292,7 +282,6 @@ function DeviceMockup({
   height,
   label,
   previewTheme,
-  background,
   componentName,
   fragmentPath,
   variantName,
@@ -302,7 +291,6 @@ function DeviceMockup({
   const isMobile = type === "mobile";
   const frameWidth = width + 24; // Add bezel width
   const screenHeight = height;
-  const backgroundStyle = getBackgroundStyle(background);
 
   return (
     <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center' }}>
@@ -479,7 +467,6 @@ interface DesktopMockupProps {
   height: number;
   label: string;
   previewTheme: "light" | "dark";
-  background: BackgroundOption;
   componentName: string;
   fragmentPath: string;
   variantName: string;
@@ -492,15 +479,12 @@ function DesktopMockup({
   height,
   label,
   previewTheme,
-  background,
   componentName,
   fragmentPath,
   variantName,
   renderContent,
   useIframeIsolation,
 }: DesktopMockupProps) {
-  const backgroundStyle = getBackgroundStyle(background);
-
   return (
     <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center' }}>
       {/* Label */}
@@ -568,7 +552,6 @@ function DesktopMockup({
               overflow: 'hidden',
               width: `${width}px`,
               height: `${height}px`,
-              ...backgroundStyle,
             }}
             data-theme={previewTheme}
           >

package/src/viewer/components/PreviewArea.tsx

@@ -13,7 +13,7 @@ import { FigmaEmbed } from './FigmaEmbed.js';
 import { VariantMatrix } from './VariantMatrix.js';
 import { MultiViewportPreview } from './MultiViewportPreview.js';
 import { IsolatedPreviewFrame } from './IsolatedPreviewFrame.js';
-import { getBackgroundStyle, getViewportWidth, type ZoomLevel, type BackgroundOption, type ViewportPreset, type ViewportSize } from '../constants/ui.js';
+import { getViewportWidth, type ZoomLevel, type ViewportPreset, type ViewportSize } from '../constants/ui.js';
 import type { PreviewTheme } from '../hooks/useViewSettings.js';
 
 interface PreviewAreaProps {
@@ -25,7 +25,6 @@ interface PreviewAreaProps {
 
   // View settings
   zoom: ZoomLevel;
-  background: BackgroundOption;
   viewport: ViewportPreset;
   customSize: ViewportSize;
   previewTheme: PreviewTheme;
@@ -151,11 +150,10 @@ const DeviceMockup = memo(function DeviceMockup({ type, width, children }: Devic
 interface PreviewContentProps {
   zoom: ZoomLevel;
   previewTheme: PreviewTheme;
-  background: BackgroundOption;
   children: ReactNode;
 }
 
-const PreviewContent = memo(function PreviewContent({ zoom, previewTheme, background, children }: PreviewContentProps) {
+const PreviewContent = memo(function PreviewContent({ zoom, previewTheme, children }: PreviewContentProps) {
   return (
     <div
       data-preview-container="true"
@@ -164,7 +162,6 @@ const PreviewContent = memo(function PreviewContent({ zoom, previewTheme, backgr
         width: '100%',
         height: '100%',
         overflow: 'auto',
-        backgroundColor: background === 'transparent' ? 'transparent' : undefined,
       }}
     >
       <div
@@ -188,7 +185,6 @@ export function PreviewArea({
   variant,
   variants,
   zoom,
-  background,
   viewport,
   customSize,
   previewTheme,
@@ -212,7 +208,6 @@ export function PreviewArea({
         fragmentPath={fragmentPath}
         zoom={zoom}
         previewTheme={previewTheme}
-        background={background}
         useIframeIsolation={useIframeIsolation}
         onSelectVariant={(index) => {
           onSelectVariant(index);
@@ -230,7 +225,6 @@ export function PreviewArea({
         variantName={variant.name}
         renderContent={renderContent}
         previewTheme={previewTheme}
-        background={background}
         zoom={zoom}
         useIframeIsolation={useIframeIsolation}
       />
@@ -240,7 +234,6 @@ export function PreviewArea({
   const viewportWidth = getViewportWidth(viewport, customSize);
   const viewportHeight = viewport === 'custom' ? customSize.height : null;
   const isDevice = viewport === 'tablet' || viewport === 'mobile';
-  const backgroundStyle = getBackgroundStyle(background);
 
   // Device mockup view (tablet/mobile)
   if (isDevice && viewportWidth && variant) {
@@ -252,7 +245,7 @@ export function PreviewArea({
           <div style={{ display: 'flex', gap: '16px', flex: 1 }}>
             <div style={{ flex: 1, display: 'flex', flexDirection: 'column' }}>
               <div style={{ fontSize: '12px', fontWeight: 500, color: 'var(--text-tertiary)', marginBottom: '8px', textAlign: 'center' }}>Rendered</div>
-              <div style={{ flex: 1, display: 'flex', alignItems: 'center', justifyContent: 'center', ...backgroundStyle }}>
+              <div style={{ flex: 1, display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
                 <DeviceMockup type={viewport as 'tablet' | 'mobile'} width={viewportWidth}>
                   {useIframeIsolation ? (
                     <IsolatedPreviewFrame
@@ -264,7 +257,7 @@ export function PreviewArea({
                       previewKey={previewKey}
                     />
                   ) : (
-                    <PreviewContent zoom={zoom} previewTheme={previewTheme} background={background}>
+                    <PreviewContent zoom={zoom} previewTheme={previewTheme}>
                       <ErrorBoundary key={previewKey} componentName={componentName} onRetry={onRetry}>
                         {renderContent()}
                       </ErrorBoundary>
@@ -285,7 +278,6 @@ export function PreviewArea({
                   borderRadius: '8px',
                   border: '1px solid var(--border)',
                   overflow: 'hidden',
-                  ...backgroundStyle,
                 }}
               />
             </div>
@@ -307,7 +299,7 @@ export function PreviewArea({
               previewKey={previewKey}
             />
           ) : (
-            <PreviewContent zoom={zoom} previewTheme={previewTheme} background={background}>
+            <PreviewContent zoom={zoom} previewTheme={previewTheme}>
               <ErrorBoundary key={previewKey} componentName={componentName} onRetry={onRetry}>
                 {renderContent()}
               </ErrorBoundary>
@@ -331,7 +323,6 @@ export function PreviewArea({
                 borderRadius: '8px',
                 border: '1px solid var(--border)',
                 overflow: 'auto',
-                ...backgroundStyle,
               }}
             >
               {useIframeIsolation ? (
@@ -383,7 +374,6 @@ export function PreviewArea({
                 borderRadius: '8px',
                 border: '1px solid var(--border)',
                 overflow: 'hidden',
-                ...backgroundStyle,
               }}
             />
           </div>

package/src/viewer/components/PreviewToolbar.tsx

@@ -1,85 +1,19 @@
 import { useEffect, useCallback } from 'react';
-import { Button, Menu, Stack, Separator } from '@fragments-sdk/ui';
-import {
-  ZOOM_LEVELS,
-  type ZoomLevel,
-  type BackgroundOption,
-} from '../constants/ui.js';
+import { Button, Menu, Stack } from '@fragments-sdk/ui';
+import { ZOOM_LEVELS, type ZoomLevel } from '../constants/ui.js';
 import { ZoomIcon, ChevronDownIcon } from './Icons.js';
 
 // Re-export types for consumers
-export type { ZoomLevel, BackgroundOption };
-export { getBackgroundStyle } from '../constants/ui.js';
-
-// Background options with display metadata
-const BACKGROUND_OPTIONS_UI: { value: BackgroundOption; label: string }[] = [
-  { value: 'white', label: 'White' },
-  { value: 'black', label: 'Black' },
-  { value: 'checkerboard', label: 'Checkerboard' },
-  { value: 'transparent', label: 'Transparent' },
-];
-
-function BackgroundSwatch({ background }: { background: BackgroundOption }) {
-  const baseStyle = {
-    width: '14px',
-    height: '14px',
-    borderRadius: '4px',
-    border: '1px solid var(--border)',
-    flexShrink: 0,
-  };
-
-  if (background === 'white') {
-    return <span aria-hidden="true" style={{ ...baseStyle, backgroundColor: '#ffffff' }} />;
-  }
-
-  if (background === 'black') {
-    return <span aria-hidden="true" style={{ ...baseStyle, backgroundColor: '#171717', borderColor: '#2a2a2a' }} />;
-  }
-
-  if (background === 'checkerboard') {
-    return (
-      <span
-        aria-hidden="true"
-        style={{
-          ...baseStyle,
-          backgroundColor: '#ffffff',
-          backgroundImage: `
-            linear-gradient(45deg, #d4d4d8 25%, transparent 25%),
-            linear-gradient(-45deg, #d4d4d8 25%, transparent 25%),
-            linear-gradient(45deg, transparent 75%, #d4d4d8 75%),
-            linear-gradient(-45deg, transparent 75%, #d4d4d8 75%)
-          `,
-          backgroundSize: '8px 8px',
-          backgroundPosition: '0 0, 0 4px, 4px -4px, -4px 0',
-        }}
-      />
-    );
-  }
-
-  return (
-    <span
-      aria-hidden="true"
-      style={{
-        ...baseStyle,
-        backgroundColor: 'transparent',
-        backgroundImage: 'linear-gradient(135deg, transparent 42%, var(--text-tertiary) 43%, var(--text-tertiary) 57%, transparent 58%)',
-      }}
-    />
-  );
-}
+export type { ZoomLevel };
 
 interface PreviewToolbarProps {
   zoom: ZoomLevel;
-  background: BackgroundOption;
   onZoomChange: (zoom: ZoomLevel) => void;
-  onBackgroundChange: (bg: BackgroundOption) => void;
 }
 
 export function PreviewToolbar({
   zoom,
-  background,
   onZoomChange,
-  onBackgroundChange,
 }: PreviewToolbarProps) {
   // Keyboard shortcuts for zoom
   const handleKeyDown = useCallback((e: KeyboardEvent) => {
@@ -114,7 +48,6 @@ export function PreviewToolbar({
 
   return (
     <Stack direction="row" gap="sm" align="center">
-      {/* Zoom dropdown */}
       <Menu>
         <Menu.Trigger asChild>
           <Button variant="ghost" size="sm" title="Zoom level (+/-/0)">
@@ -142,39 +75,6 @@ export function PreviewToolbar({
           </Menu.RadioGroup>
         </Menu.Content>
       </Menu>
-
-      {/* Divider */}
-      <Separator orientation="vertical" />
-
-      {/* Background selector */}
-      <Menu>
-        <Menu.Trigger asChild>
-          <Button variant="ghost" size="sm" title="Background color">
-            <Stack direction="row" gap="xs" align="center">
-              <BackgroundSwatch background={background} />
-              <span>{BACKGROUND_OPTIONS_UI.find(o => o.value === background)?.label}</span>
-              <span style={{ display: 'inline-flex', width: '12px', height: '12px' }}>
-                <ChevronDownIcon />
-              </span>
-            </Stack>
-          </Button>
-        </Menu.Trigger>
-        <Menu.Content side="bottom" align="start">
-          <Menu.RadioGroup
-            value={background}
-            onValueChange={(value: string) => onBackgroundChange(value as BackgroundOption)}
-          >
-            {BACKGROUND_OPTIONS_UI.map((option) => (
-              <Menu.RadioItem key={option.value} value={option.value}>
-                <Stack direction="row" gap="sm" align="center">
-                  <BackgroundSwatch background={option.value} />
-                  {option.label}
-                </Stack>
-              </Menu.RadioItem>
-            ))}
-          </Menu.RadioGroup>
-        </Menu.Content>
-      </Menu>
     </Stack>
   );
 }

package/src/viewer/components/VariantMatrix.tsx

@@ -17,7 +17,6 @@ import { ErrorBoundary } from "./ErrorBoundary.js";
 import { StoryRenderer, LoaderIndicator } from "./StoryRenderer.js";
 import { IsolatedPreviewFrame } from "./IsolatedPreviewFrame.js";
 import { ChevronDownIcon } from "./Icons.js";
-import { getBackgroundStyle, type BackgroundOption } from "../constants/ui.js";
 
 interface VariantMatrixProps {
   /** All variants to display */
@@ -30,8 +29,6 @@ interface VariantMatrixProps {
   zoom: number;
   /** Preview theme */
   previewTheme: "light" | "dark";
-  /** Background option */
-  background: BackgroundOption;
   /** Whether to use iframe isolation */
   useIframeIsolation?: boolean;
   /** Callback when a variant is clicked to focus on it */
@@ -63,7 +60,6 @@ export function VariantMatrix({
   fragmentPath,
   zoom,
   previewTheme,
-  background,
   useIframeIsolation = true,
   onSelectVariant,
 }: VariantMatrixProps) {
@@ -208,7 +204,6 @@ export function VariantMatrix({
                           scale={effectiveScale}
                           minHeight={gridConfig.minHeight}
                           previewTheme={previewTheme}
-                          background={background}
                           useIframeIsolation={useIframeIsolation}
                           isHovered={hoveredIndex === index}
                           onHover={() => setHoveredIndex(index)}
@@ -240,7 +235,6 @@ export function VariantMatrix({
                 scale={effectiveScale}
                 minHeight={gridConfig.minHeight}
                 previewTheme={previewTheme}
-                background={background}
                 useIframeIsolation={useIframeIsolation}
                 isHovered={hoveredIndex === index}
                 onHover={() => setHoveredIndex(index)}
@@ -263,7 +257,6 @@ interface VariantCardProps {
   scale: number;
   minHeight: string;
   previewTheme: "light" | "dark";
-  background: BackgroundOption;
   useIframeIsolation: boolean;
   isHovered: boolean;
   onHover: () => void;
@@ -279,15 +272,12 @@ function VariantCard({
   scale,
   minHeight,
   previewTheme,
-  background,
   useIframeIsolation,
   isHovered,
   onHover,
   onLeave,
   onClick,
 }: VariantCardProps) {
-  const backgroundStyle = getBackgroundStyle(background);
-
   return (
     <div
       style={{
@@ -373,7 +363,6 @@ function VariantCard({
           display: 'flex',
           alignItems: 'center',
           justifyContent: 'center',
-          ...backgroundStyle,
         }}
       >
         {useIframeIsolation ? (

package/src/viewer/constants/ui.ts

@@ -102,12 +102,6 @@ export function getRelationshipConfig(relationship: string) {
   return RELATIONSHIP_CONFIG[relationship as RelationshipType] || RELATIONSHIP_CONFIG.related;
 }
 
-/**
- * Preview background options.
- */
-export const BACKGROUND_OPTIONS = ['white', 'black', 'checkerboard', 'transparent'] as const;
-export type BackgroundOption = (typeof BACKGROUND_OPTIONS)[number];
-
 /**
  * Zoom level options.
  */
@@ -140,34 +134,6 @@ export function getViewportWidth(viewport: ViewportPreset, customSize: ViewportS
   return VIEWPORT_PRESETS[viewport]?.width ?? null;
 }
 
-/**
- * Get CSS background style for preview pane.
- */
-export function getBackgroundStyle(bg: BackgroundOption): React.CSSProperties {
-  switch (bg) {
-    case 'white':
-      return { backgroundColor: '#ffffff' };
-    case 'black':
-      return { backgroundColor: '#000000' };
-    case 'transparent':
-      return { backgroundColor: 'transparent' };
-    case 'checkerboard':
-      return {
-        backgroundColor: '#ffffff',
-        backgroundImage: `
-          linear-gradient(45deg, #e5e5e5 25%, transparent 25%),
-          linear-gradient(-45deg, #e5e5e5 25%, transparent 25%),
-          linear-gradient(45deg, transparent 75%, #e5e5e5 75%),
-          linear-gradient(-45deg, transparent 75%, #e5e5e5 75%)
-        `,
-        backgroundSize: '16px 16px',
-        backgroundPosition: '0 0, 0 8px, 8px -8px, -8px 0px',
-      };
-    default:
-      return { backgroundColor: '#ffffff' };
-  }
-}
-
 /**
  * Storage keys for localStorage persistence.
  */

package/src/viewer/hooks/useKeyboardShortcuts.ts

@@ -262,7 +262,7 @@ export const SHORTCUTS = [
   { keys: ["p"], description: "Toggle addons panel" },
   { keys: ["m"], description: "Matrix view" },
   { keys: ["v"], description: "Responsive view" },
-  { keys: ["/", "⌘K"], description: "Search" },
+  { keys: ["/", "⌘K"], description: "Command palette" },
   { keys: ["?"], description: "Show shortcuts" },
   { keys: ["Esc"], description: "Close / Clear" },
 ];

package/src/viewer/hooks/useUrlState.ts

@@ -5,9 +5,9 @@
  * - Component path
  * - Variant index/name
  * - Edited props
- * - View settings (zoom, background, viewport)
+ * - View settings (zoom, viewport)
  *
- * URL format: #/ComponentName/VariantName?props=base64&zoom=100&bg=white
+ * URL format: #/ComponentName/VariantName?props=base64&zoom=100
  */
 
 import { useState, useEffect, useCallback, useMemo } from "react";
@@ -21,7 +21,6 @@ export interface UrlState {
   props: Record<string, unknown>;
   /** View settings */
   zoom: number;
-  background: string;
   viewport: string;
   customWidth: number | null;
   customHeight: number | null;
@@ -32,7 +31,6 @@ const DEFAULT_STATE: UrlState = {
   variant: null,
   props: {},
   zoom: 100,
-  background: "transparent",
   viewport: "responsive",
   customWidth: null,
   customHeight: null,
@@ -99,11 +97,6 @@ function parseUrl(): UrlState {
       }
     }
 
-    const bg = params.get("bg");
-    if (bg && ["white", "black", "checkerboard", "transparent"].includes(bg)) {
-      state.background = bg;
-    }
-
     const viewport = params.get("viewport");
     if (viewport && ["responsive", "desktop", "tablet", "mobile", "custom"].includes(viewport)) {
       state.viewport = viewport;
@@ -155,10 +148,6 @@ function buildUrl(state: Partial<UrlState>): string {
     params.set("zoom", String(state.zoom));
   }
 
-  if (state.background && state.background !== "transparent") {
-    params.set("bg", state.background);
-  }
-
   if (state.viewport && state.viewport !== "responsive") {
     params.set("viewport", state.viewport);
   }
@@ -249,7 +238,6 @@ export function useUrlState() {
   const setViewSettings = useCallback(
     (settings: {
       zoom?: number;
-      background?: string;
       viewport?: string;
       customWidth?: number | null;
       customHeight?: number | null;

package/src/viewer/hooks/useViewSettings.ts

@@ -1,17 +1,16 @@
 /**
  * View settings state management.
- * Handles zoom, background, viewport, and theme settings with URL sync.
+ * Handles zoom, viewport, and theme settings with URL sync.
  */
 
 import { useReducer, useCallback, useMemo } from 'react';
-import type { ZoomLevel, BackgroundOption, ViewportPreset, ViewportSize } from '../constants/ui.js';
+import type { ZoomLevel, ViewportPreset, ViewportSize } from '../constants/ui.js';
 
 // Preview theme type (for canvas theming)
 export type PreviewTheme = 'light' | 'dark';
 
 interface ViewSettings {
   zoom: ZoomLevel;
-  background: BackgroundOption;
   viewport: ViewportPreset;
   customSize: ViewportSize;
   previewTheme: PreviewTheme;
@@ -19,7 +18,6 @@ interface ViewSettings {
 
 type ViewSettingsAction =
   | { type: 'SET_ZOOM'; payload: ZoomLevel }
-  | { type: 'SET_BACKGROUND'; payload: BackgroundOption }
   | { type: 'SET_VIEWPORT'; payload: ViewportPreset }
   | { type: 'SET_CUSTOM_SIZE'; payload: ViewportSize }
   | { type: 'SET_PREVIEW_THEME'; payload: PreviewTheme }
@@ -28,7 +26,6 @@ type ViewSettingsAction =
 
 interface ViewSettingsInit {
   zoom?: ZoomLevel;
-  background?: BackgroundOption;
   viewport?: ViewportPreset;
   customSize?: ViewportSize;
   previewTheme?: PreviewTheme;
@@ -37,7 +34,6 @@ interface ViewSettingsInit {
 function createInitialState(init?: ViewSettingsInit): ViewSettings {
   return {
     zoom: init?.zoom ?? 100,
-    background: init?.background ?? 'transparent',
     viewport: init?.viewport ?? 'responsive',
     customSize: init?.customSize ?? { width: null, height: null },
     previewTheme: init?.previewTheme ?? 'light',
@@ -48,8 +44,6 @@ function viewSettingsReducer(state: ViewSettings, action: ViewSettingsAction): V
   switch (action.type) {
     case 'SET_ZOOM':
       return { ...state, zoom: action.payload };
-    case 'SET_BACKGROUND':
-      return { ...state, background: action.payload };
     case 'SET_VIEWPORT':
       return { ...state, viewport: action.payload };
     case 'SET_CUSTOM_SIZE':
@@ -68,12 +62,11 @@ function viewSettingsReducer(state: ViewSettings, action: ViewSettingsAction): V
 interface UseViewSettingsOptions {
   initialState?: ViewSettingsInit;
   onZoomChange?: (zoom: ZoomLevel) => void;
-  onBackgroundChange?: (bg: BackgroundOption) => void;
   onViewportChange?: (viewport: ViewportPreset, customSize?: ViewportSize) => void;
 }
 
 export function useViewSettings(options: UseViewSettingsOptions = {}) {
-  const { initialState: init, onZoomChange, onBackgroundChange, onViewportChange } = options;
+  const { initialState: init, onZoomChange, onViewportChange } = options;
 
   const [state, dispatch] = useReducer(
     viewSettingsReducer,
@@ -86,11 +79,6 @@ export function useViewSettings(options: UseViewSettingsOptions = {}) {
     onZoomChange?.(zoom);
   }, [onZoomChange]);
 
-  const setBackground = useCallback((bg: BackgroundOption) => {
-    dispatch({ type: 'SET_BACKGROUND', payload: bg });
-    onBackgroundChange?.(bg);
-  }, [onBackgroundChange]);
-
   const setViewport = useCallback((viewport: ViewportPreset) => {
     dispatch({ type: 'SET_VIEWPORT', payload: viewport });
     onViewportChange?.(viewport);
@@ -111,12 +99,11 @@ export function useViewSettings(options: UseViewSettingsOptions = {}) {
 
   const actions = useMemo(() => ({
     setZoom,
-    setBackground,
     setViewport,
     setCustomSize,
     setPreviewTheme,
     toggleTheme,
-  }), [setZoom, setBackground, setViewport, setCustomSize, setPreviewTheme, toggleTheme]);
+  }), [setZoom, setViewport, setCustomSize, setPreviewTheme, toggleTheme]);
 
   return { ...state, ...actions };
 }