@toolr/ui-design 0.1.5 → 0.1.6

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/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/sections/ai-tools-paths/tools-paths-panel.tsx

@@ -66,7 +66,7 @@ export function ToolsPathsPanel({
     <div className={cn('w-full', className)}>
       {/* Header */}
       <div className="flex items-center justify-between mb-4">
-        <p className="text-xs text-neutral-500 leading-relaxed max-w-xl">
+        <p className="text-sm text-neutral-500 leading-relaxed max-w-xl">
           Configure CLI paths for AI coding assistants. Specify executable locations
           to enable integration with your development workflow.
         </p>
@@ -127,12 +127,12 @@ export function ToolsPathsPanel({
                 </div>
                 <div className="flex items-center gap-3">
                   {tool.detected ? (
-                    <span className="flex items-center gap-1 text-xs text-green-400">
+                    <span className="flex items-center gap-1 text-sm text-green-400">
                       <Check className="w-3.5 h-3.5" />
                       Installed
                     </span>
                   ) : (
-                    <span className="flex items-center gap-1 text-xs text-neutral-500">
+                    <span className="flex items-center gap-1 text-sm text-neutral-500">
                       <X className="w-3.5 h-3.5" />
                       Not Found
                     </span>
@@ -183,15 +183,15 @@ export function ToolsPathsPanel({
 
                 {/* Helper text */}
                 {isEnabled && !displayPath?.includes('/') && !tool.detected && (
-                  <p className="text-xs text-red-400 pl-5">
+                  <p className="text-sm text-red-400 pl-5">
                     Path required when enabled. Enter full path to binary.
                   </p>
                 )}
                 {tool.detected && !tool.binaryPath && (
-                  <p className="text-xs text-neutral-500 pl-5">Using auto-detected path</p>
+                  <p className="text-sm text-neutral-500 pl-5">Using auto-detected path</p>
                 )}
                 {!isEnabled && !displayPath?.includes('/') && !tool.detected && (
-                  <p className="text-xs text-neutral-500 pl-5">
+                  <p className="text-sm text-neutral-500 pl-5">
                     Tool disabled. Enter path to enable.
                   </p>
                 )}
@@ -199,7 +199,7 @@ export function ToolsPathsPanel({
 
               {/* Disabled warning */}
               {tool.detected && !isEnabled && (
-                <p className="text-xs text-yellow-500">
+                <p className="text-sm text-yellow-500">
                   Tool disabled — enable to use in your workflow
                 </p>
               )}

package/components/sections/captured-issues/captured-issues-panel.tsx

@@ -75,7 +75,7 @@ export function CapturedIssuesPanel({
           <div className="flex items-center justify-between">
             <div className="flex items-center gap-2">
               <AlertTriangle className="w-4 h-4 text-red-400" />
-              <span className="text-sm text-neutral-300">
+              <span className="text-md text-neutral-300">
                 {errorCount > 0 && (
                   <span className="text-red-400">
                     {errorCount} error{errorCount !== 1 ? 's' : ''}
@@ -93,10 +93,10 @@ export function CapturedIssuesPanel({
 
           {/* Error List */}
           <div className="space-y-2">
-            <p className="text-sm text-neutral-400">Captured Errors</p>
+            <p className="text-md text-neutral-400">Captured Errors</p>
             <div className="max-h-48 overflow-y-auto bg-neutral-950 border border-neutral-700 rounded-lg p-3 space-y-1">
               {errors.map((error) => (
-                <div key={error.fingerprint} className="text-xs font-mono break-words">
+                <div key={error.fingerprint} className="text-sm font-mono break-words">
                   <span className={cn('mr-2 shrink-0', error.level === 'warning' ? 'text-yellow-400' : 'text-red-400')}>
                     {error.count > 1 ? `\u00d7${error.count}` : '\u2022'}
                   </span>
@@ -108,7 +108,7 @@ export function CapturedIssuesPanel({
 
           {/* Optional Details */}
           <div className="space-y-3">
-            <p className="text-sm text-neutral-400">Add context (optional)</p>
+            <p className="text-md text-neutral-400">Add context (optional)</p>
             <Input
               value={title}
               onChange={setTitle}
@@ -119,7 +119,7 @@ export function CapturedIssuesPanel({
               onChange={(e) => setDescription(e.target.value)}
               placeholder="What were you doing when this happened?"
               rows={3}
-              className="w-full px-3 py-1.5 bg-neutral-750 border border-neutral-600 rounded-lg text-neutral-300 placeholder-neutral-500 focus:outline-none focus:border-blue-500 transition-colors resize-none text-sm"
+              className="w-full px-3 py-1.5 bg-neutral-750 border border-neutral-600 rounded-lg text-neutral-300 placeholder-neutral-500 focus:outline-none focus:border-blue-500 transition-colors resize-none text-md"
             />
             <Input
               type="text"
@@ -163,8 +163,8 @@ export function CapturedIssuesPanel({
               <Check className="w-5 h-5 text-green-400" />
             </div>
             <div>
-              <h3 className="text-sm text-neutral-300 font-medium">No Issues Captured</h3>
-              <p className="text-sm text-neutral-500">Everything is running smoothly.</p>
+              <h3 className="text-md text-neutral-300 font-medium">No Issues Captured</h3>
+              <p className="text-md text-neutral-500">Everything is running smoothly.</p>
             </div>
           </div>
         </div>
@@ -177,8 +177,8 @@ export function CapturedIssuesPanel({
             <summary className="flex items-center justify-between p-4 cursor-pointer hover:bg-neutral-850 transition-colors">
               <div className="flex items-center gap-2">
                 <Check className="w-4 h-4 text-green-400" />
-                <span className="text-sm text-neutral-300">Previously Reported</span>
-                <span className="text-xs text-neutral-500">({submittedErrors.length})</span>
+                <span className="text-md text-neutral-300">Previously Reported</span>
+                <span className="text-sm text-neutral-500">({submittedErrors.length})</span>
               </div>
               <ChevronDown className="w-4 h-4 text-neutral-500 transition-transform group-open:rotate-180" />
             </summary>
@@ -191,12 +191,12 @@ export function CapturedIssuesPanel({
                   <Check className="w-4 h-4 text-green-400 mt-0.5 shrink-0" />
                   <div className="flex-1 min-w-0">
                     <p
-                      className="text-sm text-neutral-300 font-mono truncate"
+                      className="text-md text-neutral-300 font-mono truncate"
                       title={error.message}
                     >
                       {error.message}
                     </p>
-                    <div className="flex items-center gap-3 mt-1 text-xs text-neutral-500">
+                    <div className="flex items-center gap-3 mt-1 text-sm text-neutral-500">
                       {error.count > 0 && (
                         <span className="text-yellow-400/80">+{error.count} since</span>
                       )}