@fragments-sdk/cli 0.7.12 → 0.7.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/cli",
-  "version": "0.7.12",
+  "version": "0.7.14",
   "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";
@@ -27,14 +26,12 @@ import { useAllFigmaUrls } from "./FigmaEmbed.js";
 import { ActionCapture } from "./ActionCapture.js";
 
 // Fragments UI
-import { Header, Stack, Text, Separator, Tooltip, Button, EmptyState, Box, Alert, Input, ThemeToggle } from "@fragments-sdk/ui";
+import { Header, Stack, Text, Separator, Tooltip, Button, EmptyState, Box, Alert, Input, ThemeToggle, FragmentsLogo } from "@fragments-sdk/ui";
 import { DeviceMobile, GridFour, Rows } from "@phosphor-icons/react";
 
 // Icons
 import { EmptyIcon, FigmaIcon, CompareIcon } from "./Icons.js";
 
-// Logo
-import { fragmentsLogo } from "../assets/fragments-logo.js";
 
 function GitHubIcon() {
   return (
@@ -65,16 +62,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,
@@ -386,6 +381,7 @@ export function App({ fragments }: AppProps) {
           activeFragment && !uiState.showHealthDashboard ? (
             <TopToolbar
               fragment={activeFragment}
+              viewSettings={viewSettings}
               uiState={uiState}
               uiActions={uiActions}
               figmaUrl={figmaUrl}
@@ -450,19 +446,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"
@@ -470,7 +453,6 @@ export function App({ fragments }: AppProps) {
                   flex: 1,
                   overflow: 'auto',
                   position: 'relative',
-                  ...(uiState.showMatrixView ? {} : getBackgroundStyle(viewSettings.background)),
                 }}
               >
                 {variantCount === 0 ? (
@@ -482,7 +464,6 @@ export function App({ fragments }: AppProps) {
                     variants={variants}
                     focusedVariantIndex={safeVariantIndex}
                     zoom={viewSettings.zoom}
-                    background={viewSettings.background}
                     viewport={viewSettings.viewport}
                     customSize={viewSettings.customSize}
                     previewTheme={resolvedTheme}
@@ -500,7 +481,6 @@ export function App({ fragments }: AppProps) {
                     variant={activeVariant}
                     variants={variants}
                     zoom={viewSettings.zoom}
-                    background={viewSettings.background}
                     viewport={viewSettings.viewport}
                     customSize={viewSettings.customSize}
                     previewTheme={resolvedTheme}
@@ -566,6 +546,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;
@@ -622,7 +603,7 @@ function ViewerHeader({ showHealth, searchQuery, onSearchChange, searchInputRef
       <Header.Trigger />
       <Header.Brand>
         <Stack direction="row" gap="sm" align="center">
-          <img src={fragmentsLogo} alt="" width={20} height={20} style={{ display: 'block' }} />
+          <FragmentsLogo size={20} />
           <Text weight="medium" size="sm">{BRAND.name}</Text>
           <Text size="xs" color="tertiary">{showHealth ? 'health dashboard' : 'preview'}</Text>
         </Stack>
@@ -764,6 +745,7 @@ function PreviewAside({
 
 function TopToolbar({
   fragment,
+  viewSettings,
   uiState,
   uiActions,
   figmaUrl,
@@ -777,7 +759,7 @@ function TopToolbar({
       <Header.Trigger />
       <Header.Brand>
         <Stack direction="row" align="center" gap="sm">
-          <img src={fragmentsLogo} alt="" width={20} height={20} style={{ display: 'block' }} />
+          <FragmentsLogo size={20} />
           <Text weight="medium" size="sm">{fragment.fragment.meta.name}</Text>
           <Text size="xs" color="tertiary">{fragment.fragment.meta.category}</Text>
         </Stack>
@@ -785,6 +767,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"}>
@@ -851,93 +875,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"];
@@ -955,7 +898,6 @@ function AllVariantsPreview({
   variants,
   focusedVariantIndex,
   zoom,
-  background,
   viewport,
   customSize,
   previewTheme,
@@ -994,7 +936,6 @@ function AllVariantsPreview({
               variant={variant}
               variants={variants}
               zoom={zoom}
-              background={background}
               viewport={viewport}
               customSize={customSize}
               previewTheme={previewTheme}

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/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/ThemeProvider.tsx

@@ -1,96 +1,42 @@
-import { createContext, useContext, useEffect, useState, useCallback, type ReactNode } from 'react';
+import type { ReactNode } from 'react';
+import {
+  ThemeProvider as FragmentsThemeProvider,
+  useTheme as useFragmentsTheme,
+} from '@fragments-sdk/ui';
 import { BRAND } from '../../core/index.js';
 
 type Theme = 'light' | 'dark' | 'system';
 
-interface ThemeContextValue {
+interface ViewerThemeContextValue {
   theme: Theme;
   resolvedTheme: 'light' | 'dark';
   setTheme: (theme: Theme) => void;
 }
 
-const ThemeContext = createContext<ThemeContextValue | null>(null);
-
 const STORAGE_KEY = `${BRAND.storagePrefix}theme`;
 
-function getSystemTheme(): 'light' | 'dark' {
-  if (typeof window === 'undefined') return 'light';
-  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
-}
-
-function getStoredTheme(): Theme {
-  if (typeof window === 'undefined') return 'system';
-  const stored = localStorage.getItem(STORAGE_KEY);
-  if (stored === 'light' || stored === 'dark' || stored === 'system') {
-    return stored;
-  }
-  return 'system';
-}
-
+/**
+ * Viewer theme adapter that reuses the shared UI ThemeProvider while preserving
+ * existing viewer storage keys and API shape.
+ */
 export function ThemeProvider({ children }: { children: ReactNode }) {
-  const [theme, setThemeState] = useState<Theme>(getStoredTheme);
-  const [resolvedTheme, setResolvedTheme] = useState<'light' | 'dark'>(() => {
-    const stored = getStoredTheme();
-    return stored === 'system' ? getSystemTheme() : stored;
-  });
-
-  const setTheme = useCallback((newTheme: Theme) => {
-    setThemeState(newTheme);
-    localStorage.setItem(STORAGE_KEY, newTheme);
-
-    // Immediately update resolved theme to avoid timing issues
-    const resolved = newTheme === 'system' ? getSystemTheme() : newTheme;
-    setResolvedTheme(resolved);
-
-    // Immediately apply to document
-    if (resolved === 'dark') {
-      document.documentElement.classList.add('dark');
-    } else {
-      document.documentElement.classList.remove('dark');
-    }
-  }, []);
-
-  // Update resolved theme and apply to document
-  useEffect(() => {
-    const resolved = theme === 'system' ? getSystemTheme() : theme;
-    setResolvedTheme(resolved);
-
-    if (resolved === 'dark') {
-      document.documentElement.classList.add('dark');
-    } else {
-      document.documentElement.classList.remove('dark');
-    }
-  }, [theme]);
-
-  // Listen for system theme changes
-  useEffect(() => {
-    if (theme !== 'system') return;
-
-    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
-    const handler = (e: MediaQueryListEvent) => {
-      setResolvedTheme(e.matches ? 'dark' : 'light');
-      if (e.matches) {
-        document.documentElement.classList.add('dark');
-      } else {
-        document.documentElement.classList.remove('dark');
-      }
-    };
-
-    mediaQuery.addEventListener('change', handler);
-    return () => mediaQuery.removeEventListener('change', handler);
-  }, [theme]);
-
   return (
-    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme }}>
+    <FragmentsThemeProvider
+      defaultMode="system"
+      storageKey={STORAGE_KEY}
+      attribute="class"
+    >
       {children}
-    </ThemeContext.Provider>
+    </FragmentsThemeProvider>
   );
 }
 
-export function useTheme() {
-  const context = useContext(ThemeContext);
-  if (!context) {
-    throw new Error('useTheme must be used within a ThemeProvider');
-  }
-  return context;
+export function useTheme(): ViewerThemeContextValue {
+  const { mode, setMode, resolvedMode } = useFragmentsTheme();
+
+  return {
+    theme: mode,
+    resolvedTheme: resolvedMode,
+    setTheme: setMode,
+  };
 }

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/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 };
 }