bobbin

Module: Bobbin

Generated by Cicadas Bootstrap on 2026-03-22.

Purpose

Bobbin (@aprovan/patchwork-bobbin) is a React-based visual DOM inspector and style editor. It provides runtime element selection with hover/click targeting, spacing and layout overlays (margin/padding visualization), and a comprehensive edit panel for modifying styles using design tokens. It's the "dev tools" layer that lets Builders visually inspect and tweak widget UI without touching code.

Interfaces

Exports:

• <Bobbin> — Main React component wrapping target content with inspector capabilities
• useBobbin() — Hook for programmatic access to inspector state and actions
• useElementSelection() — Hook for DOM element targeting (hover, click, keyboard)
• useChangeTracker() — Hook tracking style mutations with undo/redo
• useClipboard() — Hook for copying element styles
• changeSerializer — Serializes style changes to CSS/JSON for persistence
• Design token sets: colors, spacing, typography, borders, shadows

Dependencies:

• React 18
• No dependency on other Patchwork packages

Subsystems

Core Hooks

• useBobbin.ts — Central state management: selected element, edit mode, theme, overlay visibility
• useElementSelection.ts — Mouse/keyboard event handling for element targeting; manages hover highlights and click-to-select
• useChangeTracker.ts — Tracks applied style changes with full undo/redo stack
• useClipboard.ts — Copy computed or applied styles to clipboard

Components

• Overlay/SelectionOverlay.tsx — Blue outline around selected/hovered elements
• Overlay/MarginPaddingOverlay.tsx — Color-coded margin (orange) and padding (green) visualization
• Overlay/ControlHandles.tsx — Drag handles for resizing and repositioning
• EditPanel/EditPanel.tsx — Side panel containing all style editing sections
• EditPanel/sections/ — Modular sections: Layout, Size, Spacing, Typography, Background, Effects, Annotations
• EditPanel/controls/ — Reusable controls: ColorPicker, SliderInput, TokenDropdown, SpacingControl, ToggleGroup
• Inspector/Inspector.tsx — Element property inspector showing computed styles
• Pill/Pill.tsx — Floating label showing element tag/class on hover
• ThemeToggle/ThemeToggle.tsx — Light/dark theme switcher

Design Tokens

• tokens/colors.ts — Color palette tokens
• tokens/spacing.ts — Spacing scale tokens
• tokens/typography.ts — Font family, size, weight, line-height tokens
• tokens/borders.ts — Border width, radius, style tokens
• tokens/shadows.ts — Box shadow preset tokens

Utilities

• utils/dom.ts — DOM traversal and measurement helpers
• utils/selectors.ts — CSS selector generation from DOM elements
• utils/animation.ts — Transition/animation helpers for overlays

Key Decisions

• Design tokens over raw CSS values: Edit panel controls present token-based options (e.g., spacing scale, color palette) rather than arbitrary pixel/hex inputs, ensuring visual consistency.
• Non-invasive overlay approach: Overlays are rendered as absolutely-positioned elements in a separate layer, never modifying the target DOM structure.
• Change serialization for persistence: Style changes are serialized to a portable format so they can be applied back to source code or stored as patches.