@toolr/ui-design 0.1.0

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

@@ -0,0 +1,27 @@
+import { useEffect, type RefObject } from 'react'
+
+/**
+ * Close a menu/dropdown when clicking outside its ref element.
+ * If ref is null, closes on any mousedown event.
+ */
+export function useClickOutside(
+  ref: RefObject<HTMLElement | null> | null,
+  isOpen: boolean,
+  onClose: () => void
+): void {
+  useEffect(() => {
+    if (!isOpen) return
+
+    const handleClick = (event: MouseEvent) => {
+      if (!ref) {
+        onClose()
+        return
+      }
+      if (ref.current && !ref.current.contains(event.target as Node)) {
+        onClose()
+      }
+    }
+    document.addEventListener('mousedown', handleClick)
+    return () => document.removeEventListener('mousedown', handleClick)
+  }, [ref, isOpen, onClose])
+}

package/components/hooks/use-dropdown-max-height.ts

@@ -0,0 +1,20 @@
+import { useLayoutEffect, useRef } from 'react'
+
+/**
+ * Constrains a dropdown menu's height to fit within the viewport.
+ * Sets max-height = viewport bottom - element top - margin, and enables vertical scrolling.
+ */
+export function useDropdownMaxHeight<T extends HTMLElement>(isOpen: boolean, margin = 16) {
+  const ref = useRef<T>(null)
+
+  useLayoutEffect(() => {
+    if (isOpen && ref.current) {
+      const rect = ref.current.getBoundingClientRect()
+      ref.current.style.maxHeight = `${window.innerHeight - rect.top - margin}px`
+      ref.current.style.overflowY = 'auto'
+      ref.current.style.overscrollBehavior = 'contain'
+    }
+  }, [isOpen, margin])
+
+  return ref
+}

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

@@ -0,0 +1,94 @@
+/** Hook for managing back/forward navigation history with a breadcrumb segment stack. */
+
+import { useState, useCallback } from 'react'
+import type { BreadcrumbSegment } from '../ui/breadcrumb.tsx'
+
+interface NavigationState {
+  backStack: BreadcrumbSegment[][]
+  current: BreadcrumbSegment[] | null
+  forwardStack: BreadcrumbSegment[][]
+}
+
+export interface UseNavigationHistoryReturn {
+  current: BreadcrumbSegment[] | null
+  canGoBack: boolean
+  canGoForward: boolean
+  push: (segments: BreadcrumbSegment[]) => void
+  goBack: () => void
+  goForward: () => void
+  goTo: (index: number) => void
+  history: BreadcrumbSegment[][]
+}
+
+export function useNavigationHistory(
+  initial?: BreadcrumbSegment[],
+  maxEntries = 50,
+): UseNavigationHistoryReturn {
+  const [state, setState] = useState<NavigationState>({
+    backStack: [],
+    current: initial ?? null,
+    forwardStack: [],
+  })
+
+  const push = useCallback((segments: BreadcrumbSegment[]) => {
+    setState(prev => ({
+      backStack: prev.current
+        ? [...prev.backStack, prev.current].slice(-maxEntries)
+        : prev.backStack,
+      current: segments,
+      forwardStack: [],
+    }))
+  }, [maxEntries])
+
+  const goBack = useCallback(() => {
+    setState(prev => {
+      if (prev.backStack.length === 0) return prev
+      const backStack = prev.backStack.slice(0, -1)
+      const entry = prev.backStack[prev.backStack.length - 1]
+      return {
+        backStack,
+        current: entry,
+        forwardStack: prev.current
+          ? [prev.current, ...prev.forwardStack]
+          : prev.forwardStack,
+      }
+    })
+  }, [])
+
+  const goForward = useCallback(() => {
+    setState(prev => {
+      if (prev.forwardStack.length === 0) return prev
+      const [entry, ...rest] = prev.forwardStack
+      return {
+        backStack: prev.current
+          ? [...prev.backStack, prev.current]
+          : prev.backStack,
+        current: entry,
+        forwardStack: rest,
+      }
+    })
+  }, [])
+
+  const goTo = useCallback((index: number) => {
+    setState(prev => {
+      const fullHistory = [...prev.backStack, ...(prev.current ? [prev.current] : [])]
+      if (index < 0 || index >= fullHistory.length) return prev
+      return {
+        backStack: fullHistory.slice(0, index),
+        current: fullHistory[index],
+        forwardStack: [...fullHistory.slice(index + 1), ...prev.forwardStack],
+      }
+    })
+  }, [])
+
+  return {
+    current: state.current,
+    canGoBack: state.backStack.length > 0,
+    canGoForward: state.forwardStack.length > 0,
+    push,
+    goBack,
+    goForward,
+    goTo,
+    history: [...state.backStack, ...(state.current ? [state.current] : [])],
+  }
+}

package/components/lib/ai-tools.tsx

@@ -0,0 +1,44 @@
+export const AI_TOOL_LOGOS = {
+  claude: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABwAAAAcCAMAAABF0y+mAAAAJFBMVEVHcEzZd1fZd1fZd1fZd1fad1jZd1fZd1fZd1fZd1fZd1fZd1deZDooAAAADHRSTlMA//F3mhLfyjpWsiMDGU5mAAABH0lEQVQokXVSWXbEIAzDuw33v28FJCnpTP3BA6+yRGvbLK39a0F9RUvHZ5CIazZwkm+VpCi1nZP1GpJEnq2NdabzU594N0XpzInRhq/7jvm8wsOjFfVmcQG4guTWZKYL8HSiA1XFHDjgHMqCpKfpNPgIXiZVVvSJ9yazOJARxBiYf/ZMoIUxrYGjRHs/di2nbdzDZxIb1maPriold3QlyFJCAonMd08A7/WhkN19PWDolSeiXU7URWPm8S3ewMCuvGpB+kigVXvWZKlgIVycF0Hjl6DIoVRCGKz9pE8W0QKXkgkIEmjzUDuh11TSuVkn348DLHs1Y7/kzTi+ksX8GLn0wBRrdvCQS949C43fstj6FhfM8Unfqqwv3gf3+/kDMJgHC0kwnjEAAAAASUVORK5CYII=',
+  copilot: 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjgiIGhlaWdodD0iMjgiIHZpZXdCb3g9IjAgMCAyOCAyOCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cmVjdCB3aWR0aD0iMjgiIGhlaWdodD0iMjgiIHJ4PSI2IiBmaWxsPSIjMWYxZjFmIi8+PHBhdGggZD0iTTE0IDVjLTQuOTcgMC05IDQuMDMtOSA5IDAgMy45NyAyLjU2IDcuMzQgNi4xMiA4LjUzLjQ1LjA4LjYxLS4xOS42MS0uNDN2LTEuNjdjLTIuNDkuNTQtMy4wMS0xLjA2LTMuMDEtMS4wNi0uNDEtMS4wNC0uOTktMS4zMS0uOTktMS4zMS0uODEtLjU2LjA2LS41NC4wNi0uNTQuOS4wNiAxLjM3LjkyIDEuMzcuOTIuOCAxLjM3IDIuMDkuOTggMi42Ljc0LjA4LS41OC4zMS0uOTguNTctMS4yLTEuOTktLjIzLTQuMDgtLjk5LTQuMDgtNC40MiAwLS45OC4zNS0xLjc4LjkyLTIuNDEtLjA5LS4yMy0uNC0xLjE0LjA5LTIuMzcgMCAwIC43NS0uMjQgMi40Ni45Mi43MS0uMiAxLjQ4LS4zIDIuMjQtLjNzMS41My4xIDIuMjQuMzFjMS43MS0xLjE2IDIuNDYtLjkyIDIuNDYtLjkyLjQ5IDEuMjMuMTggMi4xNC4wOSAyLjM3LjU3LjYzLjkyIDEuNDMuOTIgMi40MSAwIDMuNDQtMi4xIDQuMTktNC4wOSA0LjQxLjMyLjI4LjYxLjgyLjYxIDEuNjZ2Mi40NmMwIC4yNC4xNi41MS42MS40M0MxOS40NCAyMS4zNCAyMiAxOC4wMyAyMiAxNGMwLTQuOTctNC4wMy05LTktOVoiIGZpbGw9IiNmZmYiLz48L3N2Zz4=',
+  codex: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAAAP1BMVEVHcEwAgPgAgPgAgPcAgPcAgPcAgPcAgPcAgPcAgPcAd/dzsvq+2/2Kvvtfpvru+P/Z6/77/v83lvmnzfwbjPhuMd/TAAAACnRSTlMAF0adyun/9k+LLZxzywAAAXZJREFUeAFkUlmWwyAMC03qZITxAtz/rPNiaLpEvwhJCC1vpMe6PYn2bT3Sckf6e9KF55pux/SDvy9K2uiG7YNx7BQAgDdjP677r/PMXOhN2tOXPkSN2byUkis+XV75vBFA7mqugpE0BKY+M0DNuQIoXgbjlFinv1Zk0wxUAppeEin66ebe4Q2o7J6pq4zG0nLEfTPRDhUUNSlu3fKQeAwH0V5PQlPV1kHFfcZcl20GPAnuuWe1DIjx7HPZw+EkEOJ1cDcBtCBCLBGhGVVlimTQ3FxQbHgEgaoLuoVx6FiG+CQ8h4RWUFYVdHYhy8iDsEfI6IEjvTlrEJgxQq7DQ8W0kbgKgiAu85mPQYiiPZo+LdRnUcesGsZAzxVozp2MBa+q5293bx2gs2kgK2hgvb4b4mpsWgggbS9C+hgMcmtFrRT2ck37e9IAajHjjJ9hz9FO0n201+wn7rP/H76MQzjrIZQwI2deTqz5m4OZhR0oycLMhCQNACpMHlEZrAKTAAAAAElFTkSuQmCC',
+  gemini: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAEMklEQVR4Ab2XA5AkSRSGv5ddXb095t2tbdu2bW/wbNsXONuBs23bttY2p2e7Kt/1VNQZ3cMv4o9U46+XrxJCSIvLduTv0ezjPTGzfaGNCk5KWAEVyMVSrKFQSsJ6UUolWAp9j5i3j2hK7sG9uMl9Ke0NtQ8nuS+ZKn+IeAceSLj2qtZ3X7sHQACaXLC3434n/rQvNLWiSNk21CZR0ZQIFEUprJDalIKSgoo6QTuo1/PKiHr7A7nJoCQalnG/jPriB2ZSfSv3+zKh+ZO3fCfBk/t5n1uhaeTn54m9dw1m70Zqg/r1sjiySSvG5uXgeGUrdyTzuslhF5Sf70Ui5wR//tIZgFKbCHBxq/aMy42jas8xKmY2Cm7qyUGpbRS4fu1KrHEwyGyjmNbmwFZk30bqivXlCbZ6igptDYqD71HXJDCAcY0Aki5ssRwQoSaxxglkhPSUtxrJzvn3kGwzGsRQE6hUGIhiUJA0uScKfkkbdk+4DH/xA7jtJyHGqXYEfBPNLAKCIApqYU9hcxhzDvWXPEhp5xkYx62qgTACpI9AZNsPODtXYxQ8YLsY9uQ1oHDYyfRNGWnTfR7RaLzyBsTBiJKWyJZvyL97FrnPnU506w8kVCpMBNqXXUrzgUcxc8kD9O+1hHgsNzMDEiYhgJABanF/fIGCexeQ/8TxJDZ/zTYxbAuNHIgX0KXPCo5bfC9Tey8mN5aTJgIRbJgDlUMVd+Ub5N+3DH3kSHas/4RtSEphRNwc+vVcQq8WA9NEIBpEwAlzoEqYtR9QntL6+p2xvZYSa9qPGBAzDuVOFv+HBkkoGFGqTXLjl6x95gx+/PqJ33MjIZLRQuRQTTQaJ9F5JvHuC7DZRWxTHxdDAkmbhL4x4RRQeTSWS3nnuZR1m4+XVUBClBiWmFaUcMD6GUQgEk6BkjEaLyTZ5yj2L3yaRJ8j0HqF4fogbMewZct3fPHM6az6+vGM1gFHEDIi+xD8zkvw2s/ARuNgFBOatwjuuo+IfXgH+9e8V6l1wCETGg3CjrgCdaKIgCgYCxjFWf0O7se342z8rEq7oSMKmm4zipdgxP3jg9ZiVr+C89ntmG3fVWs3dADSToOCUVDfx6x6FueLO2HXL9XcDUMDkkkO2oPww0PI13cie9fX6IHEQSGdCf3lmUBVI815wICHONQ1ESdeYeKgEfRHiZdCTn3qitLcQ8nJLsEz7vdG4AEQpOdxgFDbiAhT+iwlmAJxHzT5yd1XirCKZmNh2GWQ04DaIj+vPvPGnEOXFsPwJbqyrLDgKgHocPreDgec7KctNFNRNLE1vJwSyIZlMMbf+gj7hd+VE15iK1QQ1kuMQ8N4YXCjzrfeSrUHxs85u8X3Qkir8zTPet7xvjGzFW3jG4kqYP9uICj/3h+OhX0xlGJseIUPhSZT7e+LsA/4ZVx9zHnFewB+BQL7BcuXk7EZAAAAAElFTkSuQmCC',
+  opencode: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAAXNSR0IArs4c6QAAAERlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAA6ABAAMAAAABAAEAAKACAAQAAAABAAAAIKADAAQAAAABAAAAIAAAAACshmLzAAABl0lEQVRYCe1XS2rDMBAd/70xBJoubJqVF83Sm+YooVcIPUDJTUpOUHIa71Ov0ht4Y/yJ6zEYHFnyZBKKNx4IkTSjNw/pzQhrT4tFDROaPmHuNvVMYPITMCkNVFVFhYz6DcMY9SsJ1HUNmqbB1+EAYRiOgqicSZLAx24HHZYsTkmgC46iCF7X627K+vc8j4wnNVAUBQmiCrhlL3kCIjilCerORTwWgTzP4X27hd/zGcRESOxltYLv4xFs2xbzKOcsAiimn9MJUFymeb21LEvIsqwVnDKbxHGNIgkQl8ymrDC5SADj0Mc1NgGjSW5Z1oAAliz6uMbaoes6vG027V3LNOD7PmAMx1gEENhxHHBdVypC9HGNTQCF2P36yWRrfb9qzDsvFcoD6zMBtgaw48nasWqduh0WAaz1IAjAalqtIZRbdbnA83LZPuFU0r6fRQC73+d+398/GP97H+AmGDAUFsgqwLZ7r92yl7yCOI4hTdO7OOCrSZlGfRnJFE+B9v3im9H34Zg8AQpABOTOSQ1wAbnxM4HJT+APfgFr0DSNhC0AAAAASUVORK5CYII=',
+} as const
+
+export type AiToolKey = 'claude' | 'gemini' | 'codex' | 'copilot' | 'opencode'
+
+export const AI_TOOL_NAMES: Record<AiToolKey, string> = {
+  claude: 'Claude Code',
+  gemini: 'Gemini CLI',
+  codex: 'Codex CLI',
+  copilot: 'GitHub Copilot',
+  opencode: 'Opencode',
+}
+
+export function AiToolIcon({ tool, size, showName, className, style }: {
+  tool: string
+  size?: number
+  showName?: boolean
+  className?: string
+  style?: React.CSSProperties
+}) {
+  const src = AI_TOOL_LOGOS[tool as keyof typeof AI_TOOL_LOGOS]
+  if (!src) return null
+  const img = (
+    <img
+      src={src}
+      alt=""
+      {...(size ? { width: size, height: size } : {})}
+      className={className}
+      style={{ objectFit: 'contain', ...style }}
+    />
+  )
+  if (!showName) return img
+  return (
+    <span style={{ display: 'inline-flex', flexDirection: 'column', alignItems: 'center', gap: 4 }}>
+      {img}
+      <span className="text-[11px] text-neutral-400">{AI_TOOL_NAMES[tool as AiToolKey] ?? tool}</span>
+    </span>
+  )
+}

package/components/lib/cn.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/components/lib/form-colors.ts

@@ -0,0 +1,32 @@
+export type FormColor =
+  | 'blue' | 'green' | 'red' | 'orange' | 'cyan' | 'yellow'
+  | 'purple' | 'indigo' | 'emerald' | 'amber' | 'violet' | 'neutral' | 'sky'
+
+interface FormColorConfig {
+  /** Idle border class (e.g. 'border-blue-500/30') */
+  border: string
+  /** Hover classes (e.g. 'hover:bg-blue-500/20 hover:border-blue-500/40') */
+  hover: string
+  /** Focus border class (e.g. 'focus:border-blue-500') */
+  focus: string
+  /** Selected row background (e.g. 'bg-blue-600/20') */
+  selectedBg: string
+  /** Accent text for icons/checks (e.g. 'text-blue-400') */
+  accent: string
+}
+
+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' },
+  red: { border: 'border-red-500/30', hover: 'hover:bg-red-500/20 hover:border-red-500/40', focus: 'focus:border-red-500', selectedBg: 'bg-red-600/20', accent: 'text-red-400' },
+  orange: { border: 'border-orange-500/30', hover: 'hover:bg-orange-500/20 hover:border-orange-500/40', focus: 'focus:border-orange-500', selectedBg: 'bg-orange-600/20', accent: 'text-orange-400' },
+  cyan: { border: 'border-cyan-500/30', hover: 'hover:bg-cyan-500/20 hover:border-cyan-500/40', focus: 'focus:border-cyan-500', selectedBg: 'bg-cyan-600/20', accent: 'text-cyan-400' },
+  yellow: { border: 'border-yellow-500/30', hover: 'hover:bg-yellow-500/20 hover:border-yellow-500/40', focus: 'focus:border-yellow-500', selectedBg: 'bg-yellow-600/20', accent: 'text-yellow-400' },
+  purple: { border: 'border-purple-500/30', hover: 'hover:bg-purple-500/20 hover:border-purple-500/40', focus: 'focus:border-purple-500', selectedBg: 'bg-purple-600/20', accent: 'text-purple-400' },
+  indigo: { border: 'border-indigo-500/30', hover: 'hover:bg-indigo-500/20 hover:border-indigo-500/40', focus: 'focus:border-indigo-500', selectedBg: 'bg-indigo-600/20', accent: 'text-indigo-400' },
+  emerald: { border: 'border-emerald-500/30', hover: 'hover:bg-emerald-500/20 hover:border-emerald-500/40', focus: 'focus:border-emerald-500', selectedBg: 'bg-emerald-600/20', accent: 'text-emerald-400' },
+  amber: { border: 'border-amber-500/30', hover: 'hover:bg-amber-500/20 hover:border-amber-500/40', focus: 'focus:border-amber-500', selectedBg: 'bg-amber-600/20', accent: 'text-amber-400' },
+  violet: { border: 'border-violet-500/30', hover: 'hover:bg-violet-500/20 hover:border-violet-500/40', focus: 'focus:border-violet-500', selectedBg: 'bg-violet-600/20', accent: 'text-violet-400' },
+  neutral: { border: 'border-neutral-500/30', hover: 'hover:bg-neutral-500/20 hover:border-neutral-500/40', focus: 'focus:border-neutral-500', selectedBg: 'bg-neutral-600/20', accent: 'text-neutral-400' },
+  sky: { border: 'border-sky-500/30', hover: 'hover:bg-sky-500/20 hover:border-sky-500/40', focus: 'focus:border-sky-500', selectedBg: 'bg-sky-600/20', accent: 'text-sky-400' },
+}

package/components/lib/theme-engine.ts

@@ -0,0 +1,97 @@
+import type { FormColor } from './form-colors.ts'
+
+/* ── Neutral scale types ──────────────────────────────────── */
+
+export const SCALE_KEYS = ['black', '950', '900', '800', '700', '600', '500', '400', '300', '200'] as const
+export type ScaleKey = (typeof SCALE_KEYS)[number]
+
+/* ── Theme definitions ────────────────────────────────────── */
+
+export type ThemeId = 'oled' | 'dark' | 'night' | 'soft' | 'bright' | 'paper' | 'muted'
+
+export const DARK_THEMES: ThemeId[] = ['oled', 'dark', 'night', 'soft']
+export const LIGHT_THEMES: ThemeId[] = ['bright', 'paper', 'muted']
+
+export const BASE_THEMES: Record<ThemeId, { label: string; maxSat: number; lightness: Record<ScaleKey, number> }> = {
+  oled:   { label: 'OLED',   maxSat: 4,  lightness: { black: 0,   '950': 0,   '900': 2,  '800': 4,  '700': 10, '600': 20, '500': 40, '400': 60, '300': 80, '200': 88 } },
+  dark:   { label: 'Dark',   maxSat: 8,  lightness: { black: 0,   '950': 1.5, '900': 4,  '800': 7,  '700': 13, '600': 22, '500': 41, '400': 61, '300': 81, '200': 88 } },
+  night:  { label: 'Night',  maxSat: 12, lightness: { black: 0,   '950': 3,   '900': 7,  '800': 11, '700': 17, '600': 25, '500': 43, '400': 62, '300': 82, '200': 89 } },
+  soft:   { label: 'Soft',   maxSat: 15, lightness: { black: 0,   '950': 5,   '900': 10, '800': 15, '700': 22, '600': 30, '500': 46, '400': 64, '300': 83, '200': 90 } },
+  bright: { label: 'Bright', maxSat: 6,  lightness: { black: 100, '950': 98,  '900': 96, '800': 92, '700': 85, '600': 68, '500': 52, '400': 40, '300': 24, '200': 14 } },
+  paper:  { label: 'Paper',  maxSat: 10, lightness: { black: 98,  '950': 96,  '900': 93, '800': 88, '700': 82, '600': 65, '500': 50, '400': 38, '300': 22, '200': 12 } },
+  muted:  { label: 'Muted',  maxSat: 14, lightness: { black: 95,  '950': 93,  '900': 89, '800': 84, '700': 78, '600': 62, '500': 48, '400': 36, '300': 20, '200': 10 } },
+}
+
+/* ── Accent definitions ───────────────────────────────────── */
+
+export interface AccentDef {
+  id: FormColor
+  hue: number | null
+  dotColor: string
+}
+
+export const ACCENT_DEFS: AccentDef[] = [
+  { id: 'blue',    hue: 220, dotColor: '#3b82f6' },
+  { id: 'violet',  hue: 260, dotColor: '#8b5cf6' },
+  { id: 'orange',  hue: 25,  dotColor: '#f97316' },
+  { id: 'cyan',    hue: 185, dotColor: '#06b6d4' },
+  { id: 'emerald', hue: 155, dotColor: '#10b981' },
+  { id: 'amber',   hue: 38,  dotColor: '#f59e0b' },
+  { id: 'sky',     hue: 200, dotColor: '#0ea5e9' },
+  { id: 'indigo',  hue: 235, dotColor: '#6366f1' },
+  { id: 'purple',  hue: 275, dotColor: '#a855f7' },
+  { id: 'green',   hue: 142, dotColor: '#22c55e' },
+  { id: 'yellow',  hue: 55,  dotColor: '#eab308' },
+  { id: 'red',     hue: 0,   dotColor: '#ef4444' },
+  { id: 'neutral', hue: null, dotColor: '#737373' },
+]
+
+/* ── Color utilities ──────────────────────────────────────── */
+
+export function satCurve(l: number): number {
+  return Math.min(l / 15, 1) * Math.max(0, 1 - l / 110)
+}
+
+export function hslToHex(h: number, s: number, l: number): string {
+  const a = (s / 100) * Math.min(l / 100, 1 - l / 100)
+  const f = (n: number) => {
+    const k = (n + h / 30) % 12
+    const c = l / 100 - a * Math.max(Math.min(k - 3, 9 - k, 1), -1)
+    return Math.round(255 * Math.max(0, Math.min(1, c))).toString(16).padStart(2, '0')
+  }
+  return `#${f(0)}${f(8)}${f(4)}`
+}
+
+export function generateScale(theme: ThemeId, hue: number | null, maxSat: number): Record<ScaleKey, string> {
+  const lightness = BASE_THEMES[theme].lightness
+  const result = {} as Record<ScaleKey, string>
+  for (const key of SCALE_KEYS) {
+    const l = lightness[key]
+    if (hue === null || maxSat === 0) {
+      const g = Math.round(255 * l / 100).toString(16).padStart(2, '0')
+      result[key] = `#${g}${g}${g}`
+    } else {
+      result[key] = hslToHex(hue, maxSat * satCurve(l), l)
+    }
+  }
+  return result
+}
+
+/* ── Theme application helpers ────────────────────────────── */
+
+export function isLightTheme(themeId: ThemeId): boolean {
+  return LIGHT_THEMES.includes(themeId)
+}
+
+export function applyTheme(themeId: ThemeId, accentHue: number | null, root: HTMLElement = document.documentElement): void {
+  const scale = generateScale(themeId, accentHue, BASE_THEMES[themeId].maxSat)
+  const light = isLightTheme(themeId)
+
+  for (const key of SCALE_KEYS) {
+    const prop = key === 'black' ? '--color-black' : `--color-neutral-${key}`
+    root.style.setProperty(prop, scale[key])
+  }
+  root.style.setProperty('--color-white', light ? '#0a0a0a' : '#ffffff')
+  root.style.setProperty('--color-neutral-100', light ? '#1a1a1a' : '#f0f0f0')
+  root.style.setProperty('--color-neutral-50', light ? '#0f0f0f' : '#fafafa')
+}

package/components/lib/toolr-brand.tsx

@@ -0,0 +1,31 @@
+export type ToolrAppId = 'toolr' | 'configr' | 'reviewr' | 'vibr' | 'learnr' | 'planr' | 'seedr'
+
+export const TOOLR_APPS: Record<ToolrAppId, { name: string; color: string }> = {
+  toolr: { name: 'Toolr', color: '#60a5fa' },
+  configr: { name: 'Configr', color: '#a78bfa' },
+  reviewr: { name: 'Reviewr', color: '#fb923c' },
+  learnr: { name: 'Learnr', color: '#facc15' },
+  seedr: { name: 'Seedr', color: '#2dd4bf' },
+  planr: { name: 'Planr', color: '#f472b6' },
+  vibr: { name: 'Vibr', color: '#f87171' },
+}
+
+export function ToolrAppLogo({ app, color: colorOverride, size, className }: { app?: ToolrAppId; color?: string; size?: number; className?: string }) {
+  const color = colorOverride ?? (app ? TOOLR_APPS[app]?.color : undefined) ?? '#60a5fa'
+  return (
+    <svg
+      {...(size ? { width: size, height: size } : {})}
+      viewBox="0 0 32 32"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      className={className}
+    >
+      <path d="M5 26V4H16C21.5 4 26 8 26 13C26 18 21.5 22 16 22H5" stroke={color} strokeWidth="3.5" strokeLinecap="round" strokeLinejoin="round" />
+      <path d="M14 22L24 28" stroke={color} strokeWidth="3.5" strokeLinecap="round" />
+      <rect x="3" y="29" width="5.5" height="2.5" rx="0.5" fill={color} />
+      <rect x="10" y="29" width="5.5" height="2.5" rx="0.5" fill={color} opacity={0.7} />
+      <rect x="17" y="29" width="5.5" height="2.5" rx="0.5" fill={color} opacity={0.45} />
+      <rect x="24" y="29" width="5.5" height="2.5" rx="0.5" fill={color} opacity={0.25} />
+    </svg>
+  )
+}

package/components/sections/ai-tools-paths/index.ts

@@ -0,0 +1,37 @@
+/**
+ * AI Tools Paths — Section barrel export
+ *
+ * This section provides a complete, reusable AI tool binary path configuration
+ * panel. It handles tool detection, path validation, enable/disable toggles,
+ * and per-tool refresh — all via an API adapter interface.
+ *
+ * File structure:
+ * - tools-paths-panel.tsx — Main panel component (drop-in usage)
+ * - use-tools-paths.ts    — Detection state & actions hook (used by panel, also standalone)
+ * - types.ts              — Shared types and API adapter interface
+ *
+ * Quick start for consuming apps:
+ *   import { ToolsPathsPanel, type ToolsPathsApi, type AiToolConfig } from '@toolr/ui-design'
+ *
+ *   const api: ToolsPathsApi = {
+ *     detectAll: () => invoke('detect_all_tools'),
+ *     detectTool: (id) => invoke('detect_tool', { toolId: id }),
+ *     validatePath: (path) => invoke('validate_binary_path', { path }),
+ *   }
+ *
+ *   <ToolsPathsPanel
+ *     api={api}
+ *     tools={toolConfigs}
+ *     onToolConfigChange={(id, partial) => updateTool(id, partial)}
+ *     renderToolIcon={(id) => <AiToolIcon tool={id} size={20} />}
+ *   />
+ */
+
+// Main panel component
+export { ToolsPathsPanel, type ToolsPathsPanelProps } from './tools-paths-panel.tsx'
+
+// Hook for custom UIs
+export { useToolsPaths, type UseToolsPathsOptions, type UseToolsPathsReturn } from './use-tools-paths.ts'
+
+// Types and API interface
+export type { AiToolConfig, ToolDetectionResult, ToolsPathsApi } from './types.ts'

package/components/sections/ai-tools-paths/tools-paths-panel.tsx

@@ -0,0 +1,212 @@
+/**
+ * ToolsPathsPanel — AI tool binary path configuration panel
+ *
+ * Part of: Sections > AI Tools Paths
+ *
+ * This is the main "drop in and it works" component. Provide an API adapter,
+ * tool configs, and a change callback — it handles the full detection and
+ * configuration UI.
+ *
+ * Usage:
+ *   <ToolsPathsPanel
+ *     api={toolsPathsApi}
+ *     tools={toolConfigs}
+ *     onToolConfigChange={(id, partial) => updateTool(id, partial)}
+ *   />
+ *
+ * AI agent notes:
+ * - Replicates the configr Settings > AI Tools > Paths page layout
+ * - Each tool row shows: icon, name, status badge, toggle, path input, refresh
+ * - The component manages detection state internally via useToolsPaths hook
+ * - Tool configs (enabled, path, detected) are owned by the consumer
+ * - The renderToolIcon prop allows each app to provide its own tool icons
+ * - Uses ui-design components (Input, Toggle, IconButton, Tooltip)
+ */
+
+import type { ReactNode } from 'react'
+import { Check, X, RefreshCw, Terminal } from 'lucide-react'
+import { cn } from '../../lib/cn.ts'
+import { Input } from '../../ui/input.tsx'
+import { Toggle } from '../../ui/toggle.tsx'
+import { IconButton } from '../../ui/icon-button.tsx'
+import { useToolsPaths } from './use-tools-paths.ts'
+import type { AiToolConfig, ToolsPathsApi } from './types.ts'
+
+export interface ToolsPathsPanelProps {
+  /** API adapter for backend operations (detection, validation) */
+  api: ToolsPathsApi
+  /** Current tool configurations */
+  tools: AiToolConfig[]
+  /** Called when a tool's config changes. Consumer updates their state. */
+  onToolConfigChange: (toolId: string, config: Partial<AiToolConfig>) => void
+  /** Optional render function for tool icons. Receives tool ID, returns ReactNode. */
+  renderToolIcon?: (toolId: string) => ReactNode
+  className?: string
+}
+
+export function ToolsPathsPanel({
+  api,
+  tools,
+  onToolConfigChange,
+  renderToolIcon,
+  className,
+}: ToolsPathsPanelProps) {
+  const {
+    isDetecting,
+    hasScanned,
+    refreshingTools,
+    scannedTools,
+    detectAll,
+    detectTool,
+    validateAndUpdatePath,
+    toggleEnabled,
+  } = useToolsPaths({ api, tools, onToolConfigChange })
+
+  return (
+    <div className={cn('w-full', className)}>
+      {/* Header */}
+      <div className="flex items-center justify-between mb-4">
+        <p className="text-xs text-[#6c7086] leading-relaxed max-w-xl">
+          Configure CLI paths for AI coding assistants. Specify executable locations
+          to enable integration with your development workflow.
+        </p>
+        <IconButton
+          icon={
+            isDetecting ? (
+              <RefreshCw className="w-4 h-4 animate-spin" />
+            ) : hasScanned ? (
+              <Check className="w-4 h-4" />
+            ) : (
+              <RefreshCw className="w-4 h-4" />
+            )
+          }
+          onClick={detectAll}
+          disabled={isDetecting}
+          size="sm"
+          color={hasScanned ? 'green' : 'neutral'}
+          tooltip={{
+            title: hasScanned ? 'Scan complete' : 'Scan for tools',
+            description: hasScanned ? 'CLI tools detected' : 'Auto-detect CLI tool locations',
+          }}
+        />
+      </div>
+
+      {/* Tool list */}
+      <div className="bg-[#181825] border border-[#313244] rounded-lg divide-y divide-[#313244]">
+        {tools.map((tool) => {
+          const isRefreshing = refreshingTools.has(tool.id)
+          const isEnabled = tool.enabled
+          const displayPath = tool.binaryPath || tool.detectedPath || ''
+          const hasBeenScanned = scannedTools.has(tool.id) && tool.detected
+
+          return (
+            <div
+              key={tool.id}
+              className={cn('p-4 space-y-2', !tool.detected && 'opacity-60')}
+            >
+              {/* Name + status + toggle row */}
+              <div className="flex items-center justify-between">
+                <div className="relative flex items-center gap-2">
+                  {renderToolIcon?.(tool.id)}
+                  <span
+                    className={cn(
+                      'font-medium',
+                      tool.detected && !isEnabled ? 'text-[#6c7086]' : 'text-[#cdd6f4]',
+                    )}
+                  >
+                    {tool.name}
+                  </span>
+                  {tool.detected && !isEnabled && (
+                    <div
+                      className="absolute inset-0 flex items-center pointer-events-none"
+                      aria-hidden="true"
+                    >
+                      <div className="w-full h-0.5 bg-[#f38ba8]/70 rounded-full" />
+                    </div>
+                  )}
+                </div>
+                <div className="flex items-center gap-3">
+                  {tool.detected ? (
+                    <span className="flex items-center gap-1 text-xs text-green-400">
+                      <Check className="w-3.5 h-3.5" />
+                      Installed
+                    </span>
+                  ) : (
+                    <span className="flex items-center gap-1 text-xs text-[#6c7086]">
+                      <X className="w-3.5 h-3.5" />
+                      Not Found
+                    </span>
+                  )}
+                  {tool.detected && (
+                    <Toggle
+                      checked={isEnabled}
+                      onChange={() => toggleEnabled(tool.id)}
+                    />
+                  )}
+                </div>
+              </div>
+
+              {/* Path input row */}
+              <div className="space-y-1">
+                <div className="flex items-center gap-2">
+                  <Terminal className="w-3 h-3 text-[#6c7086]" />
+                  <div className="flex-1">
+                    <Input
+                      value={displayPath}
+                      onChange={(newPath) => validateAndUpdatePath(tool.id, newPath)}
+                      placeholder={`/usr/local/bin/${tool.id}`}
+                      size="sm"
+                      className={displayPath ? 'text-white' : 'text-[#a6adc8]'}
+                    />
+                  </div>
+                  <IconButton
+                    icon={
+                      isRefreshing ? (
+                        <RefreshCw className="w-3 h-3 text-[#cdd6f4] animate-spin" />
+                      ) : hasBeenScanned ? (
+                        <Check className="w-3 h-3 text-green-400" />
+                      ) : (
+                        <RefreshCw className="w-3 h-3 text-[#cdd6f4]" />
+                      )
+                    }
+                    onClick={() => detectTool(tool.id)}
+                    disabled={isRefreshing}
+                    color={hasBeenScanned ? 'green' : 'neutral'}
+                    size="sm"
+                    tooltipPosition="bottom"
+                    tooltip={{
+                      title: hasBeenScanned ? 'Scan complete' : `Scan for ${tool.name}`,
+                      description: hasBeenScanned ? 'Click to re-scan' : 'Check if CLI tool is installed',
+                    }}
+                  />
+                </div>
+
+                {/* Helper text */}
+                {isEnabled && !displayPath?.includes('/') && !tool.detected && (
+                  <p className="text-xs text-red-400 pl-5">
+                    Path required when enabled. Enter full path to binary.
+                  </p>
+                )}
+                {tool.detected && !tool.binaryPath && (
+                  <p className="text-xs text-[#6c7086] pl-5">Using auto-detected path</p>
+                )}
+                {!isEnabled && !displayPath?.includes('/') && !tool.detected && (
+                  <p className="text-xs text-[#6c7086] pl-5">
+                    Tool disabled. Enter path to enable.
+                  </p>
+                )}
+              </div>
+
+              {/* Disabled warning */}
+              {tool.detected && !isEnabled && (
+                <p className="text-xs text-yellow-500">
+                  Tool disabled — enable to use in your workflow
+                </p>
+              )}
+            </div>
+          )
+        })}
+      </div>
+    </div>
+  )
+}