@toolr/ui-design 0.1.5 → 0.1.7

package/agent-rules.json

@@ -0,0 +1,91 @@
+{
+  "meta": {
+    "description": "Critical rules for AI agents building apps with @toolr/ui-design. These are the things agents commonly get wrong.",
+    "lastUpdated": "2026-03-05"
+  },
+  "categories": [
+    {
+      "name": "Setup",
+      "color": "#2dd4bf",
+      "rules": [
+        { "type": "do", "text": "body { background-color: var(--background); } — portals render at document.body with semi-transparent backgrounds; without this, white bleeds through" },
+        { "type": "do", "text": "@import \"@toolr/ui-design/tokens\" in app CSS — without it, all semantic tokens are undefined" },
+        { "type": "do", "text": "Add @utility text-xs { font-size: 11px; } in app CSS — Tailwind v4 @theme blocks in consuming apps don't inherit --font-size-xss from ui-design tokens" },
+        { "type": "do", "text": "Import from @toolr/ui-design barrel only, never deep paths like @toolr/ui-design/components/ui/input" }
+      ]
+    },
+    {
+      "name": "Typography",
+      "color": "#fbbf24",
+      "rules": [
+        { "type": "dont", "text": "Minimum font size is 11px (text-xs) — never go below" },
+        { "type": "do", "text": "text-neutral-300 is primary text, not white — white is for emphasis only" },
+        { "type": "do", "text": "font-medium (500) is the default weight — not semibold, not normal" }
+      ]
+    },
+    {
+      "name": "Components",
+      "color": "#60a5fa",
+      "rules": [
+        { "type": "do", "text": "Every IconButton must have a tooltip prop — tooltip={{ description: \"...\" }}, not a plain string" },
+        { "type": "do", "text": "onChange delivers the value directly, never a React event — onChange={setName} not onChange={(e) => setName(e.target.value))" },
+        { "type": "do", "text": "Icons are string names — icon=\"search\", not icon={<Search />} from lucide-react" },
+        { "type": "do", "text": "Use FilterDropdown for filtering (value \"all\" for unfiltered), SortDropdown for sorting — they are separate components" },
+        { "type": "dont", "text": "Never use Select with an \"All\" option for filtering — use FilterDropdown" },
+        { "type": "dont", "text": "Never use raw HTML <select>, <input type=\"checkbox\">, <button>, or inline dropdown implementations" },
+        { "type": "do", "text": "ConfirmModal for actions (confirm/cancel), AlertModal for info (dismiss only) — don't mix them" },
+        { "type": "do", "text": "Use cn() for class composition, never string concatenation — cn() resolves Tailwind conflicts" }
+      ]
+    },
+    {
+      "name": "Styling",
+      "color": "#c084fc",
+      "rules": [
+        { "type": "do", "text": "Use semantic tokens (--background, --surface, --border) for structure, Tailwind utilities for accent colors" },
+        { "type": "dont", "text": "Never hardcode hex values for accents — use Tailwind {color}-{shade} classes" },
+        { "type": "dont", "text": "Never use transition-all — specify the property (transition-colors, transition-transform)" },
+        { "type": "dont", "text": "Never use shadow-sm/shadow-md — use shadow-xl for dropdowns/tooltips, shadow-2xl for modals only" },
+        { "type": "dont", "text": "Never use rounded-full except for toggle knobs, checkmarks, and avatars — badges use rounded-lg" },
+        { "type": "dont", "text": "Never use CSS group-hover for tooltips — always use the portal-based Tooltip component" }
+      ]
+    },
+    {
+      "name": "Portals",
+      "color": "#fb923c",
+      "rules": [
+        { "type": "do", "text": "Select, Tooltip, Modal all render via createPortal to document.body — parent overflow:hidden and z-index don't affect them" },
+        { "type": "do", "text": "Popover background is rgba(0,0,0,0.8) — semi-transparent by design, which is why body background matters" },
+        { "type": "dont", "text": "Never wrap portal components in overflow:hidden expecting to clip them — they escape to document.body" }
+      ]
+    },
+    {
+      "name": "State & Data",
+      "color": "#4ade80",
+      "rules": [
+        { "type": "do", "text": "Zustand empty array selectors: use a module-level constant — const EMPTY: T[] = [], never inline []" },
+        { "type": "do", "text": "Immutable store updates: always spread nested state — { ...state.settings, key: value }" },
+        { "type": "dont", "text": "Never prop drill data available in stores — components should read from stores directly" },
+        { "type": "dont", "text": "Never call invoke() directly — use the central useTauri.ts wrapper (handles snake_case mapping)" }
+      ]
+    },
+    {
+      "name": "Code Hygiene",
+      "color": "#fb7185",
+      "rules": [
+        { "type": "dont", "text": "Never comment out code — delete it entirely. No // removed, no _unused renames" },
+        { "type": "dont", "text": "Never create abstractions for one-time operations — only when 3+ identical implementations exist" },
+        { "type": "do", "text": "Features only import from core, never from other features — cross-feature data flows through core stores" },
+        { "type": "do", "text": "Delete unused exports, types, and variables — no speculative interfaces or \"just in case\" code" }
+      ]
+    },
+    {
+      "name": "Sync Validation",
+      "color": "#22d3ee",
+      "rules": [
+        { "type": "dont", "text": "Never use --no-verify or --no-hooks to bypass the pre-commit sync check" },
+        { "type": "do", "text": "Run npm run sync-check before committing component or playground changes" },
+        { "type": "do", "text": "Keep playground page, App.tsx route, component-graph entry, and ai-manifest.json in sync within the same commit" }
+      ]
+    }
+  ]
+}

package/ai-manifest.json

@@ -0,0 +1,190 @@
+{
+  "meta": {
+    "package": "@toolr/ui-design",
+    "description": "Shared dark-theme design system for toolr apps. React + Tailwind CSS.",
+    "imports": {
+      "components": "@toolr/ui-design",
+      "tokens": "@toolr/ui-design/tokens",
+      "content": "@toolr/ui-design/content",
+      "diagrams": "@toolr/ui-design/diagrams",
+      "preset": "@toolr/ui-design/preset",
+      "manifest": "@toolr/ui-design/manifest"
+    },
+    "docs": {
+      "rules": "docs/rules/",
+      "files": [
+        "docs/rules/foundations.md",
+        "docs/rules/color-system.md",
+        "docs/rules/token-conventions.md",
+        "docs/rules/component-usage.md",
+        "docs/rules/icon-conventions.md",
+        "docs/rules/layout-patterns.md",
+        "docs/rules/content-conventions.md",
+        "docs/rules/diagram-conventions.md"
+      ]
+    },
+    "howToUse": "Import components from '@toolr/ui-design'. Import CSS tokens via @import '@toolr/ui-design/tokens' in your app CSS. Read the relevant docs/rules/ file for conventions. For full component interfaces, read the source file listed in each component entry."
+  },
+
+  "conventions": {
+    "onChange": "Receives the new value directly, never a React event",
+    "className": "Use cn() from @toolr/ui-design for conditional class composition (clsx + tailwind-merge)",
+    "icons": "Use IconButton with icon='name' string prop (lucide icon names). Do NOT import lucide-react directly",
+    "tooltips": "Always an object { description: string, title?: string, extra?: string }, never a plain string",
+    "colors": "Use Tailwind utilities for accents (text-blue-400, bg-green-500/20). Use CSS vars for structural colors (var(--surface)). Never raw hex",
+    "spacing": "4px grid: 0, 0.5, 1, 1.5, 2, 3, 4, 6 (= 0-24px). Never arbitrary values like mt-7 or px-9",
+    "typography": "text-xs (12px captions), text-sm (14px body), text-base (16px headings). text-xss (11px) for fine print",
+    "modals": "Use ConfirmModal/AlertModal/ActionDialog. Never window.alert/confirm/prompt"
+  },
+
+  "types": {
+    "FormColor": "blue | green | red | orange | cyan | yellow | purple | indigo | emerald | amber | violet | gray | sky",
+    "AccentColor": "blue | purple | orange | green | pink | amber | emerald | teal | sky",
+    "IconName": "string — any lucide icon name (e.g. 'save', 'trash', 'search', 'plus')",
+    "TooltipContent": "{ title?: string, description: string | ReactNode, extra?: string }",
+    "SelectOption<T>": "{ value: T, label: string, icon?: ReactNode }",
+    "ModalKind": "info | warning | error | success",
+    "ModalSize": "sm | md | lg | xl"
+  },
+
+  "components": {
+    "form": [
+      { "name": "Input", "description": "Text input with search mode, action slot, error state", "replaces": "input", "keyProps": "value, onChange, type?: text|search, variant?: filled|ghost, size?: sm|md, error?, mono?, actionSlot?", "file": "components/ui/input.tsx" },
+      { "name": "NumberInput", "description": "Numeric input with increment/decrement buttons", "replaces": "input[type=number]", "keyProps": "value, onChange, min?, max?, step?, size?: sm|md", "file": "components/ui/number-input.tsx" },
+      { "name": "Select", "description": "Portal dropdown with keyboard nav and check indicators", "replaces": "select", "keyProps": "value, onChange, options: SelectOption[], color?: FormColor, size?: sm|md, variant?: filled|ghost", "file": "components/ui/select.tsx" },
+      { "name": "FilterDropdown", "description": "Clearable single-select filter with 'All' default and optional search", "keyProps": "value, onChange, options, allLabel?, searchable?", "file": "components/ui/filter-dropdown.tsx" },
+      { "name": "SortDropdown", "description": "Field picker with direction toggle arrow", "keyProps": "field, ascending, fields: SortField[], onFieldChange, onToggleDirection", "file": "components/ui/sort-dropdown.tsx" },
+      { "name": "Toggle", "description": "iOS-style boolean switch", "replaces": "input[type=checkbox] (for on/off settings)", "keyProps": "checked, onChange, color?: FormColor, size?: sm|md|lg", "file": "components/ui/toggle.tsx" },
+      { "name": "Checkbox", "description": "Check-icon boolean for multi-select lists", "replaces": "input[type=checkbox] (for checklists)", "keyProps": "checked, onChange, color?: FormColor, size?: sm|md|lg", "file": "components/ui/checkbox.tsx" },
+      { "name": "SegmentedToggle", "description": "Horizontal icon-based mutually-exclusive toggle group", "keyProps": "options: SegmentedToggleOption[], value, onChange, color?: FormColor", "file": "components/ui/segmented-toggle.tsx" },
+      { "name": "ResizableTextarea", "description": "Textarea with drag-to-resize handle", "replaces": "textarea", "keyProps": "value, onChange, variant?: filled|ghost, minHeight?, maxHeight?", "file": "components/ui/resizable-textarea.tsx" },
+      { "name": "FormActions", "description": "Flex row for form buttons with optional nav slot", "keyProps": "padding?: compact|normal|modal, children", "file": "components/ui/form-actions.tsx" },
+      { "name": "SelectionGrid", "description": "Grid of selectable cards with icons and descriptions", "keyProps": "items: SelectionCardItem[], selected, onSelect", "file": "components/ui/selection-grid.tsx" }
+    ],
+
+    "action": [
+      { "name": "IconButton", "description": "Icon-only button with tooltip, badge, status indicator, href mode", "replaces": "button", "keyProps": "icon: IconName|ReactNode, tooltip: TooltipContent, color?: FormColor, size?: xss|xs|sm|lg, status?, badge?, href?, strikethrough?, disabled?", "file": "components/ui/icon-button.tsx" },
+      { "name": "CollapseButton", "description": "Animated chevron toggle button for expand/collapse", "keyProps": "isOpen, onToggle, tooltip: TooltipContent", "file": "components/ui/icon-button.tsx" },
+      { "name": "AiActionButton", "description": "Button with AI loading/success/error states for async AI operations", "keyProps": "icon, tooltip, status: AiActionStatus, onClick, completionResult?", "file": "components/ui/ai-action-button.tsx" },
+      { "name": "AiExecutionActionButtons", "description": "Run/stop/retry button group for AI execution workflows", "keyProps": "status: ExecutionStatus, onRun, onStop, onRetry", "file": "components/ui/ai-execution-action-buttons.tsx" },
+      { "name": "ConfirmBadge", "description": "Badge that requires click-confirmation before triggering action", "keyProps": "label, onConfirm, color?: ConfirmBadgeColor", "file": "components/ui/confirm-badge.tsx" }
+    ],
+
+    "display": [
+      { "name": "Label", "description": "Border-focused colored badge/tag with icon and tooltip", "keyProps": "text, color: LabelColor, icon?, tooltip?: TooltipContent, size?: xs|sm|md", "file": "components/ui/label.tsx" },
+      { "name": "Badge", "description": "Minimal inline badge for counts or short labels", "keyProps": "text, color?: BadgeColor", "file": "components/ui/badge.tsx" },
+      { "name": "ScopeBadge", "description": "Pre-configured Label for user/project/local/read-only scopes", "keyProps": "scope: ScopeType", "file": "components/ui/scope-badge.tsx" },
+      { "name": "Tooltip", "description": "Portal-based tooltip with auto-positioning and arrow", "keyProps": "content: TooltipContent, position?: top|bottom|left|right|auto, children", "file": "components/ui/tooltip.tsx" },
+      { "name": "TooltipButton", "description": "Icon button that toggles a persistent tooltip on click", "keyProps": "content: TooltipContent, icon?: IconName", "file": "components/ui/tooltip.tsx" },
+      { "name": "StatusCard", "description": "Card showing a list of status items with icons and values", "keyProps": "title, items: StatusItem[]", "file": "components/ui/status-card.tsx" },
+      { "name": "SnapshotCard", "description": "Card displaying snapshot metadata with timestamp and actions", "keyProps": "snapshot, onRestore?, onDelete?", "file": "components/ui/snapshot-card.tsx" }
+    ],
+
+    "layout": [
+      { "name": "CollapsibleSection", "description": "Section with animated expand/collapse and header actions", "keyProps": "title, defaultOpen?, children, actions?", "file": "components/ui/collapsible-section.tsx" },
+      { "name": "DetailSection", "description": "Key-value detail rows in a bordered section", "keyProps": "title, rows: DetailRow[]", "file": "components/ui/detail-section.tsx" },
+      { "name": "DetailViewWrapper", "description": "Standard wrapper for detail/edit views with header and back navigation", "keyProps": "title, onBack?, children, actions?", "file": "components/ui/detail-view-wrapper.tsx" },
+      { "name": "BottomPanelHeader", "description": "Tab bar header for bottom panels with status banner", "keyProps": "tabs: PanelTab[], activeTab, onTabChange, banner?: StatusBanner", "file": "components/ui/bottom-panel-header.tsx" },
+      { "name": "EditorToolbar", "description": "Toolbar row for editor panels with title, actions, and status", "keyProps": "title?, children, actions?", "file": "components/ui/editor-toolbar.tsx" },
+      { "name": "EditorPlaceholderCard", "description": "Centered placeholder card shown when no editor content is active", "keyProps": "icon, title, description", "file": "components/ui/editor-placeholder-card.tsx" },
+      { "name": "FrontmatterFormHeader", "description": "Form header for YAML frontmatter editing with field labels", "keyProps": "fields, onChange", "file": "components/ui/frontmatter-form-header.tsx" },
+      { "name": "FilesPanel", "description": "File list panel with add/remove actions", "keyProps": "files: FileEntry[], onAdd?, onRemove?", "file": "components/ui/files-panel.tsx" },
+      { "name": "SnippetsPanel", "description": "Panel displaying a list of text snippets with copy action", "keyProps": "snippets: Snippet[], onCopy?", "file": "components/ui/snippets-panel.tsx" }
+    ],
+
+    "navigation": [
+      { "name": "Breadcrumb", "description": "Breadcrumb trail with clickable segments", "keyProps": "segments: BreadcrumbSegment[], onNavigate", "file": "components/ui/breadcrumb.tsx" },
+      { "name": "NavigationBar", "description": "Top navigation bar with title, back button, and actions", "keyProps": "title, onBack?, children", "file": "components/ui/navigation-bar.tsx" },
+      { "name": "TabBar", "description": "Horizontal tab strip with optional badge counts", "keyProps": "tabs: Tab[], activeTab, onTabChange", "file": "components/ui/tab-bar.tsx" },
+      { "name": "LayoutTabBar", "description": "Tab bar for switching layout views (e.g. split/full)", "keyProps": "tabs: LayoutTab[], activeTab, onTabChange", "file": "components/ui/layout-tab-bar.tsx" },
+      { "name": "NavCard", "description": "Navigation card with icon, title, and description for app selection", "keyProps": "title, description, icon, onClick, color?", "file": "components/ui/nav-card.tsx" },
+      { "name": "ExtensionListCard", "description": "Card showing extension info with type indicator and actions", "keyProps": "title, type, description, actions?", "file": "components/ui/extension-list-card.tsx" }
+    ],
+
+    "modal": [
+      { "name": "ConfirmModal", "description": "Action confirmation dialog with confirm/cancel buttons", "replaces": "window.confirm", "keyProps": "isOpen, onClose, onConfirm, title, kind?: ModalKind, confirmLabel?, loading?, children", "file": "components/ui/modal.tsx" },
+      { "name": "AlertModal", "description": "Dismiss-only alert dialog", "replaces": "window.alert", "keyProps": "isOpen, onClose, title, kind?: ModalKind, children", "file": "components/ui/modal.tsx" },
+      { "name": "ActionDialog", "description": "Full-featured dialog with custom content and action buttons", "keyProps": "isOpen, onClose, title, size?: ModalSize, children, actions?", "file": "components/ui/action-dialog.tsx" }
+    ],
+
+    "section": [
+      { "name": "TabbedPromptEditor", "description": "Multi-tab prompt editor with variable insertion and dirty detection. Use with usePromptEditor() hook", "keyProps": "...usePromptEditor(), standalone?, className?", "hook": "usePromptEditor", "file": "components/sections/prompt-editor/index.ts" },
+      { "name": "FileTypeTabbedPromptEditor", "description": "Prompt editor variant with file type tabs", "keyProps": "...usePromptEditor(), fileTypes: FileTypeOption[]", "hook": "usePromptEditor", "file": "components/sections/prompt-editor/index.ts" },
+      { "name": "SimulatorPromptEditor", "description": "Prompt editor with scenario selector for testing prompts", "keyProps": "...usePromptEditor(), scenarios: ScenarioOption[]", "file": "components/sections/prompt-editor/index.ts" },
+      { "name": "RegistryBrowser", "description": "Browsable grid of registry items with search, filter, sort", "keyProps": "items, onSelect, selectedId?", "file": "components/ui/registry-browser.tsx" },
+      { "name": "RegistryDetail", "description": "Detail view for a single registry item with file structure", "keyProps": "item, onBack, onInstall?", "file": "components/ui/registry-detail.tsx" },
+      { "name": "RegistryCard", "description": "Card displaying a registry item with type badge and metadata", "keyProps": "item, onClick?, selected?", "file": "components/ui/registry-card.tsx" },
+      { "name": "GoldenSyncPanel", "description": "Golden snapshot sync panel with diff viewer. Use with useGoldenSync() hook", "keyProps": "...useGoldenSync()", "hook": "useGoldenSync", "file": "components/sections/golden-snapshots/index.ts" },
+      { "name": "SnapshotBrowserPanel", "description": "Browse and manage snapshots. Use with useSnapshotBrowser() hook", "keyProps": "...useSnapshotBrowser()", "hook": "useSnapshotBrowser", "file": "components/sections/snapshot-browser/index.ts" },
+      { "name": "SnippetsEditor", "description": "Create and edit text snippets. Use with useSnippetsEditor() hook", "keyProps": "...useSnippetsEditor()", "hook": "useSnippetsEditor", "file": "components/sections/snippets-editor/index.ts" },
+      { "name": "ReportBugForm", "description": "Bug report form with screenshot capture. Use with useReportBug() hook", "keyProps": "...useReportBug()", "hook": "useReportBug", "file": "components/sections/report-bug/index.ts" },
+      { "name": "ScreenshotUploader", "description": "Drag & drop multi-image upload with base64 encoding and preview thumbnails", "keyProps": "screenshots: Screenshot[], onChange, maxTotalSize?, disabled?", "file": "components/sections/report-bug/index.ts" },
+      { "name": "ToolsPathsPanel", "description": "AI tool path configuration panel. Use with useToolsPaths() hook", "keyProps": "...useToolsPaths()", "hook": "useToolsPaths", "file": "components/sections/ai-tools-paths/index.ts" },
+      { "name": "CapturedIssuesPanel", "description": "View and manage captured error issues. Use with useCapturedIssues() hook", "keyProps": "...useCapturedIssues()", "hook": "useCapturedIssues", "file": "components/sections/captured-issues/index.ts" },
+      { "name": "FileStructureSection", "description": "File tree with code preview, syntax highlighting, and copy", "keyProps": "files: FileTreeNode[], accentColor?: AccentColor", "file": "components/ui/file-structure-section.tsx" },
+      { "name": "FileTree", "description": "Expandable file/folder tree with selection", "keyProps": "nodes: FileTreeNode[], selectedPath?, onSelect", "file": "components/ui/file-tree.tsx" },
+      { "name": "ExecutionDetailsPanel", "description": "Panel showing execution result rows with expandable details", "keyProps": "rows: ExecutionDetailRow[]", "file": "components/ui/execution-details-panel.tsx" }
+    ],
+
+    "settings": [
+      { "name": "SettingsPanel", "description": "Full settings page with tree navigation and content area", "keyProps": "tree: SettingsTreeNode[], activePath, onNavigate, children", "file": "components/settings/index.ts" },
+      { "name": "SettingsTreeNav", "description": "Tree navigation sidebar for settings", "keyProps": "tree: SettingsTreeNode[], activePath, onNavigate", "file": "components/settings/index.ts" },
+      { "name": "SettingsHeader", "description": "Header for settings pages with breadcrumb", "keyProps": "path: string[], tree: SettingsTreeNode[]", "file": "components/settings/index.ts" },
+      { "name": "SettingRow", "description": "Single settings row with label, description, and control slot", "keyProps": "label, description?, children (control element)", "file": "components/ui/setting-row.tsx" },
+      { "name": "SettingsCard", "description": "Bordered card container for grouping settings", "keyProps": "title?, children", "file": "components/ui/settings-card.tsx" },
+      { "name": "SettingsInfoBox", "description": "Informational callout box within settings", "keyProps": "title?, children, color?: SettingsInfoBoxColor", "file": "components/ui/settings-info-box.tsx" },
+      { "name": "SettingsSectionTitle", "description": "Section heading for settings groups", "keyProps": "title, description?", "file": "components/ui/settings-section-title.tsx" }
+    ],
+
+    "brand": [
+      { "name": "ToolrAppLogo", "description": "App logo with icon and name for toolr suite apps", "keyProps": "appId: ToolrAppId, size?: sm|md|lg", "file": "components/lib/toolr-brand.tsx" },
+      { "name": "AiToolIcon", "description": "Logo icon for AI tools (Claude, GPT, Gemini, etc.)", "keyProps": "tool: AiToolKey, size?: number", "file": "components/lib/ai-tools.tsx" },
+      { "name": "CookieConsent", "description": "Cookie consent banner with accept/reject", "keyProps": "onConsent: (choice: ConsentChoice) => void", "file": "components/ui/cookie-consent.tsx" }
+    ]
+  },
+
+  "hooks": [
+    { "name": "usePromptEditor", "description": "State manager for TabbedPromptEditor — tabs, dirty detection, save, variables", "file": "components/sections/prompt-editor/index.ts" },
+    { "name": "useGoldenSync", "description": "State manager for GoldenSyncPanel — diff tree, sync status, file comparison", "file": "components/sections/golden-snapshots/index.ts" },
+    { "name": "useSnapshotBrowser", "description": "State manager for SnapshotBrowserPanel — snapshot list, categories, actions", "file": "components/sections/snapshot-browser/index.ts" },
+    { "name": "useSnippetsEditor", "description": "State manager for SnippetsEditor — CRUD operations on snippets", "file": "components/sections/snippets-editor/index.ts" },
+    { "name": "useReportBug", "description": "State manager for ReportBugForm — issue types, screenshots, submission", "file": "components/sections/report-bug/index.ts" },
+    { "name": "useToolsPaths", "description": "State manager for ToolsPathsPanel — AI tool detection, path configuration", "file": "components/sections/ai-tools-paths/index.ts" },
+    { "name": "useCapturedIssues", "description": "State manager for CapturedIssuesPanel — error list, submission, dismissal", "file": "components/sections/captured-issues/index.ts" },
+    { "name": "useClickOutside", "description": "Close menus/dropdowns when clicking outside the ref element", "file": "components/hooks/use-click-outside.ts" },
+    { "name": "useDropdownMaxHeight", "description": "Calculate max height for dropdowns to stay within viewport", "file": "components/hooks/use-dropdown-max-height.ts" },
+    { "name": "useNavigationHistory", "description": "Browser-like back/forward navigation state", "file": "components/hooks/use-navigation-history.ts" }
+  ],
+
+  "utilities": [
+    { "name": "cn", "description": "clsx + tailwind-merge for conditional class composition", "usage": "cn('base-class', condition && 'conditional-class', className)", "file": "components/lib/cn.ts" },
+    { "name": "FORM_COLORS", "description": "Color config map — FORM_COLORS[color].border/.hover/.focus/.selectedBg/.accent", "file": "components/lib/form-colors.ts" },
+    { "name": "applyTheme", "description": "Apply theme to document — applyTheme(themeId, accentHue)", "file": "components/lib/theme-engine.ts" },
+    { "name": "ACCENT_DEFS", "description": "Array of { id, label, hue } for all available accent colors", "file": "components/lib/theme-engine.ts" },
+    { "name": "iconMap", "description": "Map of icon name strings to lucide-react components", "file": "components/ui/icon-button.tsx" }
+  ],
+
+  "enforcement": {
+    "htmlReplacements": {
+      "button": "IconButton",
+      "input": "Input",
+      "select": "Select",
+      "textarea": "ResizableTextarea"
+    },
+    "allowedImportPaths": [
+      "@toolr/ui-design",
+      "@toolr/ui-design/tokens",
+      "@toolr/ui-design/content",
+      "@toolr/ui-design/diagrams",
+      "@toolr/ui-design/preset",
+      "@toolr/ui-design/manifest"
+    ],
+    "bannedImports": ["lucide-react"],
+    "bannedGlobals": ["alert", "confirm", "prompt"],
+    "bannedGlobalReplacements": {
+      "alert": "AlertModal",
+      "confirm": "ConfirmModal",
+      "prompt": "ConfirmModal with an Input"
+    }
+  }
+}

package/components/content/info-panel-primitives.tsx

@@ -10,7 +10,7 @@ import type { ReactNode } from 'react'
 // ─── Paragraph ──────────────────────────────────────────────────────
 
 export function P({ children }: { children: ReactNode }) {
-  return <p className="text-sm text-neutral-400 leading-relaxed mb-5">{children}</p>
+  return <p className="text-md text-neutral-400 leading-relaxed mb-5">{children}</p>
 }
 
 // ─── Section Header ─────────────────────────────────────────────────
@@ -18,7 +18,7 @@ export function P({ children }: { children: ReactNode }) {
 export function SectionHeader({ color, children }: { color?: string; children: ReactNode }) {
   const textColor = color ? `text-${color}-500/70` : 'text-neutral-500'
   return (
-    <p className={`${textColor} text-xs uppercase font-semibold pb-0.5 border-b border-neutral-700/50 mb-2.5`} style={{ letterSpacing: '0.8px' }}>
+    <p className={`${textColor} text-sm uppercase font-semibold pb-0.5 border-b border-neutral-700/50 mb-2.5`} style={{ letterSpacing: '0.8px' }}>
       {children}
     </p>
   )
@@ -38,10 +38,10 @@ export function DLRow({ term, children, even }: { term: ReactNode; children: Rea
   const bg = even ? 'bg-white/[0.015]' : ''
   return (
     <>
-      <div className={`py-2 border-b border-neutral-800/60 ${bg} font-semibold text-sm whitespace-nowrap`}>
+      <div className={`py-2 border-b border-neutral-800/60 ${bg} font-semibold text-md whitespace-nowrap`}>
         {term}
       </div>
-      <div className={`py-2 border-b border-neutral-800/60 ${bg} text-sm text-neutral-400`}>{children}</div>
+      <div className={`py-2 border-b border-neutral-800/60 ${bg} text-md text-neutral-400`}>{children}</div>
     </>
   )
 }
@@ -49,7 +49,7 @@ export function DLRow({ term, children, even }: { term: ReactNode; children: Rea
 // ─── Unordered List ─────────────────────────────────────────────────
 
 export function UL({ children }: { children: ReactNode }) {
-  return <ul className="text-sm text-neutral-400 space-y-2 mb-5">{children}</ul>
+  return <ul className="text-md text-neutral-400 space-y-2 mb-5">{children}</ul>
 }
 
 export function LI({ color, children }: { color: string; children: ReactNode }) {
@@ -69,7 +69,7 @@ export function OL({ children }: { children: ReactNode }) {
 
 export function OLI({ n, color, children }: { n: number; color: string; children: ReactNode }) {
   return (
-    <div className="flex items-start gap-2.5 text-sm">
+    <div className="flex items-start gap-2.5 text-md">
       <span className={`text-${color}-400 shrink-0 w-4 text-right font-bold`}>{n}.</span>
       <span className="text-neutral-400">{children}</span>
     </div>
@@ -105,7 +105,7 @@ export function getCalloutColors(color: string) {
 export function Callout({ color, children }: { color: string; children: ReactNode }) {
   const c = CALLOUT_COLORS[color] ?? CALLOUT_COLORS.blue
   return (
-    <div className={`border-l-4 ${c.borderL} border-y ${c.borderY} ${c.bg} px-3 py-2.5 rounded-r mb-5 text-sm text-neutral-400`}>
+    <div className={`border-l-4 ${c.borderL} border-y ${c.borderY} ${c.bg} px-3 py-2.5 rounded-r mb-5 text-md text-neutral-400`}>
       {children}
     </div>
   )
@@ -114,7 +114,7 @@ export function Callout({ color, children }: { color: string; children: ReactNod
 export function CalloutCode({ color, children }: { color: string; children: ReactNode }) {
   const c = CALLOUT_COLORS[color] ?? CALLOUT_COLORS.blue
   return (
-    <code className={`block bg-neutral-800/80 px-2 py-1 rounded mt-1.5 text-sm ${c.codeText}`}>
+    <code className={`block bg-neutral-800/80 px-2 py-1 rounded mt-1.5 text-md ${c.codeText}`}>
       {children}
     </code>
   )
@@ -128,7 +128,7 @@ export function CalloutDim({ children }: { children: ReactNode }) {
 
 export function CodeBlock({ children }: { children: ReactNode }) {
   return (
-    <div className="bg-neutral-900/60 rounded-md p-3 font-mono text-xs text-neutral-400 mb-5 whitespace-pre overflow-x-auto leading-normal">{children}</div>
+    <div className="bg-neutral-900/60 rounded-md p-3 font-mono text-sm text-neutral-400 mb-5 whitespace-pre overflow-x-auto leading-normal">{children}</div>
   )
 }
 
@@ -179,9 +179,9 @@ export function LocationItem({
         <span
           className={`w-2 h-2 rounded-full bg-${color}-500/50 border border-${color}-500 shrink-0`}
         />
-        <span className={`text-${color}-400 text-sm font-semibold`}>{label}</span>
+        <span className={`text-${color}-400 text-md font-semibold`}>{label}</span>
       </div>
-      <div className={`py-2 border-b border-neutral-800/60 ${bg} text-sm text-neutral-400`}>{children}</div>
+      <div className={`py-2 border-b border-neutral-800/60 ${bg} text-md text-neutral-400`}>{children}</div>
     </>
   )
 }
@@ -190,7 +190,7 @@ export function LocationItem({
 
 export function TitledLI({ color, title, children }: { color: string; title: string; children: ReactNode }) {
   return (
-    <li className="flex items-start gap-2 text-sm text-neutral-400">
+    <li className="flex items-start gap-2 text-md text-neutral-400">
       <span className={`text-${color}-400 shrink-0`} style={{ marginTop: '3px', fontSize: '18px', lineHeight: '14px' }}>&#x2022;</span>
       <span>
         <span className={`text-${color}-300 font-semibold`}>{title}</span>
@@ -204,7 +204,7 @@ export function TitledLI({ color, title, children }: { color: string; title: str
 
 export function CalloutDialog({ color, lines }: { color: string; lines: { speaker: string; text: string }[] }) {
   return (
-    <div className="bg-neutral-800/80 rounded px-2 py-1 mt-1.5 flex flex-col gap-0.5 text-sm">
+    <div className="bg-neutral-800/80 rounded px-2 py-1 mt-1.5 flex flex-col gap-0.5 text-md">
       {lines.map((line, idx) => (
         <div key={idx}>
           <span className={`text-${color}-300 font-semibold mr-1`}>{line.speaker}:</span>
@@ -238,7 +238,7 @@ export function StatusBadge({ value, badgeColor, label, children, even }: {
     <DLRow
       term={
         <span className="flex items-center gap-1.5">
-          <span className={`inline-flex items-center justify-center w-5 h-5 rounded-full bg-${badgeColor}-500/20 text-${badgeColor}-400 text-xss font-bold shrink-0`}>{value}</span>
+          <span className={`inline-flex items-center justify-center w-5 h-5 rounded-full bg-${badgeColor}-500/20 text-${badgeColor}-400 text-xs font-bold shrink-0`}>{value}</span>
           <span className={`text-${badgeColor}-400 font-semibold`}>{label}</span>
         </span>
       }

package/components/hooks/use-click-outside.ts

@@ -1,11 +1,13 @@
 import { useEffect, type RefObject } from 'react'
 
 /**
- * Close a menu/dropdown when clicking outside its ref element.
+ * Close a menu/dropdown when clicking outside its ref element(s).
+ * Accepts a single ref, an array of refs, or null.
+ * When given an array, closes only if the click is outside ALL refs.
  * If ref is null, closes on any mousedown event.
  */
 export function useClickOutside(
-  ref: RefObject<HTMLElement | null> | null,
+  ref: RefObject<HTMLElement | null> | RefObject<HTMLElement | null>[] | null,
   isOpen: boolean,
   onClose: () => void
 ): void {
@@ -17,7 +19,12 @@ export function useClickOutside(
         onClose()
         return
       }
-      if (ref.current && !ref.current.contains(event.target as Node)) {
+
+      const refs = Array.isArray(ref) ? ref : [ref]
+      const isOutsideAll = refs.every(
+        (r) => !r.current || !r.current.contains(event.target as Node)
+      )
+      if (isOutsideAll) {
         onClose()
       }
     }

package/components/hooks/use-modal-behavior.ts

@@ -0,0 +1,24 @@
+import { useEffect } from 'react'
+
+/**
+ * Shared modal behavior: Escape key to close + body overflow lock.
+ */
+export function useModalBehavior(isOpen: boolean, onClose: () => void): void {
+  // Escape key handler
+  useEffect(() => {
+    if (!isOpen) return
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    document.addEventListener('keydown', handler)
+    return () => document.removeEventListener('keydown', handler)
+  }, [isOpen, onClose])
+
+  // Body overflow lock
+  useEffect(() => {
+    if (!isOpen) return
+    const prev = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+    return () => { document.body.style.overflow = prev }
+  }, [isOpen])
+}

package/components/hooks/use-navigation-history.ts

@@ -1,6 +1,6 @@
 /** Hook for managing back/forward navigation history with a breadcrumb segment stack. */
 
-import { useState, useCallback } from 'react'
+import { useState, useCallback, useMemo } from 'react'
 import type { BreadcrumbSegment } from '../ui/breadcrumb.tsx'
 
 interface NavigationState {
@@ -81,6 +81,11 @@ export function useNavigationHistory(
     })
   }, [])
 
+  const history = useMemo(
+    () => [...state.backStack, ...(state.current ? [state.current] : [])],
+    [state.backStack, state.current],
+  )
+
   return {
     current: state.current,
     canGoBack: state.backStack.length > 0,
@@ -89,6 +94,6 @@ export function useNavigationHistory(
     goBack,
     goForward,
     goTo,
-    history: [...state.backStack, ...(state.current ? [state.current] : [])],
+    history,
   }
 }

package/components/hooks/use-resizable-sidebar.ts

@@ -0,0 +1,38 @@
+import { useState, useCallback, useRef } from 'react'
+
+export interface UseResizableSidebarOptions {
+  min: number
+  max: number
+  defaultWidth: number
+  /** 'left' = drag right shrinks (sidebar on right), 'right' = drag right grows (sidebar on left) */
+  direction?: 'left' | 'right'
+}
+
+export function useResizableSidebar({ min, max, defaultWidth, direction = 'right' }: UseResizableSidebarOptions) {
+  const [width, setWidth] = useState(defaultWidth)
+  const widthRef = useRef(defaultWidth)
+
+  const onPointerDown = useCallback((e: React.PointerEvent) => {
+    e.preventDefault()
+    const el = e.currentTarget as HTMLElement
+    el.setPointerCapture(e.pointerId)
+    const startX = e.clientX
+    const startW = widthRef.current
+
+    const onMove = (ev: PointerEvent) => {
+      const delta = direction === 'left' ? startX - ev.clientX : ev.clientX - startX
+      const next = Math.max(min, Math.min(max, startW + delta))
+      widthRef.current = next
+      setWidth(next)
+    }
+    const onUp = () => {
+      el.removeEventListener('pointermove', onMove)
+      el.removeEventListener('pointerup', onUp)
+      el.releasePointerCapture(e.pointerId)
+    }
+    el.addEventListener('pointermove', onMove)
+    el.addEventListener('pointerup', onUp)
+  }, [min, max, direction])
+
+  return { width, onPointerDown }
+}

package/components/lib/ai-tools.tsx

@@ -38,7 +38,7 @@ export function AiToolIcon({ tool, size, showName, className, style }: {
   return (
     <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: 4 }}>
       {img}
-      <span className="text-xss text-neutral-400">{AI_TOOL_NAMES[tool as AiToolKey] ?? tool}</span>
+      <span className="text-xs text-neutral-400">{AI_TOOL_NAMES[tool as AiToolKey] ?? tool}</span>
     </span>
   )
 }

package/components/lib/form-colors.ts

@@ -16,6 +16,46 @@ interface FormColorConfig {
   accent: string
 }
 
+export type AccentColor = FormColor
+
+export const ACCENT_TEXT: Record<AccentColor, string> = {
+  blue: 'text-blue-400',
+  green: 'text-green-400',
+  red: 'text-red-400',
+  orange: 'text-orange-400',
+  cyan: 'text-cyan-400',
+  yellow: 'text-yellow-400',
+  purple: 'text-purple-400',
+  indigo: 'text-indigo-400',
+  emerald: 'text-emerald-400',
+  amber: 'text-amber-400',
+  violet: 'text-violet-400',
+  neutral: 'text-neutral-400',
+  sky: 'text-sky-400',
+  pink: 'text-pink-400',
+  teal: 'text-teal-400',
+}
+
+export const ACCENT_ICON = ACCENT_TEXT
+
+export const ACCENT_NAV: Record<AccentColor, { bg: string; text: string }> = {
+  blue: { bg: 'bg-blue-500/10', text: 'text-blue-400' },
+  green: { bg: 'bg-green-500/10', text: 'text-green-400' },
+  red: { bg: 'bg-red-500/10', text: 'text-red-400' },
+  orange: { bg: 'bg-orange-500/10', text: 'text-orange-400' },
+  cyan: { bg: 'bg-cyan-500/10', text: 'text-cyan-400' },
+  yellow: { bg: 'bg-yellow-500/10', text: 'text-yellow-400' },
+  purple: { bg: 'bg-purple-500/10', text: 'text-purple-400' },
+  indigo: { bg: 'bg-indigo-500/10', text: 'text-indigo-400' },
+  emerald: { bg: 'bg-emerald-500/10', text: 'text-emerald-400' },
+  amber: { bg: 'bg-amber-500/10', text: 'text-amber-400' },
+  violet: { bg: 'bg-violet-500/10', text: 'text-violet-400' },
+  neutral: { bg: 'bg-neutral-500/10', text: 'text-neutral-400' },
+  sky: { bg: 'bg-sky-500/10', text: 'text-sky-400' },
+  pink: { bg: 'bg-pink-500/10', text: 'text-pink-400' },
+  teal: { bg: 'bg-teal-500/10', text: 'text-teal-400' },
+}
+
 export const FORM_COLORS: Record<FormColor, FormColorConfig> = {
   blue: { border: 'border-blue-500/30', hover: 'hover:bg-blue-500/20 hover:border-blue-500/40', focus: 'focus:border-blue-500', selectedBg: 'bg-blue-600/20', accent: 'text-blue-400' },
   green: { border: 'border-green-500/30', hover: 'hover:bg-green-500/20 hover:border-green-500/40', focus: 'focus:border-green-500', selectedBg: 'bg-green-600/20', accent: 'text-green-400' },