Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs: theme system rules + node-X tokens + strict naming conventions
trohitg49331b887c4a
diff --git a/CLAUDE.md b/CLAUDE.mdindex c5446895..bc3a519c 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -375,7 +375,42 @@ LOG_FORMAT=text # text or json- **Cleanup in finally blocks** - Ensure resources are released even on error- **No orphan prevention hacks** - Trust the existing lifecycle management-### 7. Cache System Architecture (n8n Pattern)+### 7. Frontend Design + Theme System (strict)++**Always use the existing design and theme systems.** Tribal styling reintroduced anywhere defeats the migration. The following rules are non-negotiable for any new or edited frontend file:++1. **Compose shadcn primitives** from [client/src/components/ui/](./client/src/components/ui/) — `Button`, `Badge`, `Alert`, `AlertDialog`, `Dialog`, `DropdownMenu`, `Select`, `Popover`, `Tooltip`, `Tabs`, `Card`, `Input`, `Textarea`, `Switch`, `Checkbox`, `Slider`, `Label`, `Form`, `Collapsible`, `Accordion`, `Skeleton`, `Sonner`. **Do not hand-roll** modals, dropdowns, menus, toasts, dialogs, or buttons when a primitive exists. Add `npx shadcn@latest add <name>` if the primitive is missing.+2. **Action buttons → `<ActionButton tone="...">`** ([client/src/components/ui/action-button.tsx](./client/src/components/ui/action-button.tsx)). Never re-introduce the `actionButtonStyle()` / hand-built colored buttons.+3. **Style with Tailwind classes**, not `style={{...}}`. Inline `style` is allowed only for genuinely dynamic values (React Flow `<Handle>` positioning, runtime-computed coordinates, dynamic per-definition `nodeColor` on canvas nodes).+4. **Use the token tier table** in [docs-internal/frontend_architecture.md](./docs-internal/frontend_architecture.md#tokens--theming):+ - Generic chrome / status → shadcn semantic tokens (`bg-card`, `text-muted-foreground`, `border-border`, `text-success`, `bg-destructive`, `text-warning`, `text-info`, `bg-accent`, etc.)+ - Node-type-themed surfaces → `--node-X` role tokens (`bg-node-agent`, `bg-node-model-soft`, `border-node-skill-border`, `text-node-trigger`, `text-node-workflow`, `bg-node-tool-soft`)+ - Action-button palette → `<ActionButton tone="green|purple|pink|cyan|orange|yellow|red">` only+5. **No opacity arithmetic at call sites.** `bg-primary/10`, `border-node-agent/30`, `${color}25` template literals are forbidden. If a unique tint is needed, add a new variant to the theme (e.g., `--node-X-soft`, `--node-X-border`) and use it by name.+6. **No theme-locked names in non-decorative code.** Avoid `bg-dracula-purple`, `text-dracula-cyan`, etc. unless the constant accent is intentional (action-button palette). Prefer the role token (`bg-node-agent`) so future themes redefine without code edits.+7. **No `useAppTheme()` in new files.** It is grandfathered for the canvas node components and `EdgeConditionEditor` only because they interpolate per-definition `nodeColor`. Every other surface uses Tailwind + the tokens above.+8. **Icons → `lucide-react`.** Inline SVGs are reserved for non-iconographic graphics (charts, decorative shapes). Replace any `<svg>...</svg>` icon you encounter while editing.++When in doubt, read [docs-internal/frontend_architecture.md](./docs-internal/frontend_architecture.md) before introducing new patterns.++### 8. Naming Conventions (strict)++| Layer | Convention | Examples |+|---|---|---|+| Python identifier (function, variable, module, file) | `snake_case` | `get_user_settings`, `auth_service`, `node_allowlist.py` |+| JSON config key (read by Python) | `snake_case` | `enabled_nodes`, `default_llm_provider`, `compaction_ratio` |+| WebSocket message type (Python ↔ TS wire) | `snake_case` | `get_node_allowlist`, `save_user_settings`, `validate_api_key` |+| Database column / SQLModel field | `snake_case` | `created_at`, `auto_save_interval`, `examples_loaded` |+| Python class | `PascalCase` | `NodeAllowlistService`, `WorkflowExecutor` |+| TypeScript identifier | `camelCase` | `useNodeAllowlist`, `enabledNodes`, `isVisible` |+| TypeScript file (React hook) | `camelCase` starting with `use` | `useNodeAllowlist.ts`, `useWebSocket.ts` |+| Node type identifier | stored verbatim — **do not transform** | `aiAgent`, `httpRequest`, `openaiChatModel` (currently camelCase in this repo) |++**Crossing the wire**: payload keys between Python and TS are always `snake_case` (Python writes the payload). The TS hook receives `snake_case` keys and binds them to local `camelCase` variables; do not auto-transform across languages with a serializer.++Do not invent kebab-case or PascalCase variants for any of the rows above. The existing codebase is internally consistent — match it.++### 9. Cache System Architecture (n8n Pattern)The cache system follows n8n's pattern with automatic fallback:```@@ -531,74 +566,26 @@ AI model nodes route through `SquareNode` via `Dashboard.tsx`'s `COMPONENT_BY_KI- `src/store/useAppStore.ts` - Zustand application state with localStorage persistence for UI settings### Theme System-- `src/styles/theme.ts` - Unified theme with Solarized + Dracula color palettes-- `src/hooks/useAppTheme.ts` - Dynamic theme hook for dark/light mode-- `src/contexts/ThemeContext.tsx` - Theme context with `isDarkMode` and `toggleTheme`-- `src/index.css` - Global CSS including dark mode scrollbar styles--#### Color Palettes-The theme system uses two complementary color palettes:--**Solarized** (backgrounds and text):-- `theme.colors.*` - Dynamic colors based on light/dark mode-- `theme.accent.*` - Solarized accent colors (blue, cyan, green, yellow, orange, red, magenta, violet)--**Dracula** (vibrant action colors):-- `theme.dracula.green` (#50fa7b) - Run/Success actions-- `theme.dracula.purple` (#bd93f9) - Start/Save actions-- `theme.dracula.pink` (#ff79c6) - Cancel/Stop actions-- `theme.dracula.cyan` (#8be9fd) - Info/Alternative actions-- `theme.dracula.red` (#ff5555) - Error/Danger states-- `theme.dracula.orange` (#ffb86c) - Settings/Warning-- `theme.dracula.yellow` (#f1fa8c) - Credentials/Highlight--#### UI Components Using Dracula Theme-- **TopToolbar Action Buttons**: Run (green), Start (purple), Stop (pink), Save (cyan)-- **TopToolbar Icon Buttons**: Settings (orange), Credentials (yellow), Theme Toggle (yellow/purple)-- **TopToolbar File Button**: Cyan text with medium font size and semibold weight, colorful dropdown menu items-- **ParameterPanel Buttons**: Run (green), Save (purple), Cancel (pink)-- **React Flow Edges**: Default (cyan), Selected/Executing (purple), Completed (green), Error (red), Pending (cyan)-- **Node Execution Glow**: Purple glow animation during execution--#### File Operations Menu Styling-The File dropdown menu uses per-item Dracula colors:-```typescript-// In TopToolbar.tsx-{[- { label: 'New Workflow', icon: '...', action: onNew, color: theme.dracula.green },- { label: 'Open', icon: '...', action: onOpen, color: theme.accent.blue },- { label: 'Export', icon: '...', action: onExportFile, color: theme.accent.cyan },- { label: 'Import', icon: '...', action: onImportJSON, color: theme.accent.cyan },- { label: 'Copy as JSON', icon: '...', action: onExportJSON, color: theme.dracula.purple },-].map(...)}--// File button style-const textButtonStyle: React.CSSProperties = {- color: theme.dracula.cyan,- border: `1px solid ${theme.dracula.cyan}40`,- fontSize: theme.fontSize.md,- fontWeight: theme.fontWeight.semibold,- ...-};-```-#### Button Style Pattern-Action buttons use a consistent pattern with Dracula colors:-```typescript-const actionButtonStyle = (color: string, isDisabled = false) => ({- backgroundColor: isDisabled ? `${theme.colors.primary}15` : `${color}25`,- color: isDisabled ? theme.colors.primary : color,- border: `1px solid ${isDisabled ? `${theme.colors.primary}40` : `${color}60`}`,-});-```--#### Edge Styles-React Flow edges use dynamic Dracula colors via `getEdgeStyles(theme.dracula)`:-- Default edges: `theme.dracula.cyan`-- Selected/executing: `theme.dracula.purple` with glow animation-- Completed: `theme.dracula.green`-- Error: `theme.dracula.red`-- Pending: `theme.dracula.cyan` with dash animation+Single source of truth: [client/src/index.css](./client/src/index.css). All tokens are HSL channel triplets (no `hsl()` wrapper) so Tailwind composes alpha via `bg-primary/50`, `text-foreground/80`, etc.++**Token tiers** (pick the most specific that fits):++1. **shadcn semantic tokens** — `background`, `foreground`, `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `success`, `warning`, `info`, `border`, `input`, `ring`. Each rotates per theme.+2. **Node-type role tokens** — `--node-agent`, `--node-model`, `--node-skill`, `--node-tool`, `--node-trigger`, `--node-workflow`. Each exposes three variants:+ - `bg-node-X` / `text-node-X` — solid (icons, badges, accents)+ - `bg-node-X-soft` — tinted surface (cards, tinted backgrounds)+ - `border-node-X-border` — tinted outline+ Themes redefine these in their own scope without touching call sites. **Never use opacity arithmetic at the call site** (`bg-node-agent/10`); add a new `-soft` / `-border` variant if you need a different opacity.+3. **Dracula raw accents** — `--dracula-green/purple/pink/cyan/red/orange/yellow`. Same value across light + dark themes; reserved for the action-button palette (`<ActionButton tone="green">` etc.). Avoid in new code unless you specifically need the constant accent across themes.++**Action buttons** — use [ActionButton](./client/src/components/ui/action-button.tsx) (CVA primitive with `tone` variants: `green | purple | pink | cyan | orange | yellow | red`). Replaces the old `actionButtonStyle()` helper.++**shadcn primitives** — full set under `client/src/components/ui/` (Button, Badge, Alert, Dialog, DropdownMenu, Select, Popover, Tooltip, Tabs, Card, Input, Textarea, Switch, Checkbox, Slider, Label, Form, Sonner, Skeleton, Collapsible, Accordion, AlertDialog). New code composes these with Tailwind classes.++**`useAppTheme()`** ([src/styles/theme.ts](./client/src/styles/theme.ts), [src/hooks/useAppTheme.ts](./client/src/hooks/useAppTheme.ts)) is grandfathered for the canvas node components (`AIAgentNode`, `SquareNode`, `TriggerNode`, `StartNode`, `ToolkitNode`, `TeamMonitorNode`, `BaseChatModelNode`, `ModelNode`, `GenericNode`) and `EdgeConditionEditor` — they interpolate per-definition `nodeColor` into gradients, borders, and React Flow `<Handle>` styles. Every other surface uses Tailwind + the tokens above.++**Theme switching** — `[data-theme="dark"]` + Tailwind's `.dark` class, both set by `App.tsx`'s `useEffect` on `isDarkMode`. See [docs-internal/frontend_architecture.md](./docs-internal/frontend_architecture.md#tokens--theming) for the full token table and migration patterns.### WebSocket-First ArchitectureThe project uses WebSocket as the primary communication method between frontend and backend, replacing most REST API calls:diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.mdindex b848de46..dcb579d9 100644--- a/docs-internal/frontend_architecture.md+++ b/docs-internal/frontend_architecture.md@@ -208,6 +208,18 @@ Single source of truth: [src/index.css](../client/src/index.css).--dracula-green: 135 94% 65%;--dracula-purple: 265 89% 78%;/* ...pink, cyan, red, orange, yellow */++ /* Node-type role tokens — base + soft (tinted bg) + border (tinted outline).+ * Themes redefine these in their own scope; call sites use bg-node-X /+ * bg-node-X-soft / border-node-X-border directly with no opacity arithmetic. */+ --node-agent: 265 89% 78%;+ --node-agent-soft: 265 89% 78% / 0.08;+ --node-agent-border: 265 89% 78% / 0.3;+ --node-model: 191 97% 77%; /* + -soft / -border */+ --node-skill: 135 94% 65%; /* + -soft / -border */+ --node-tool: 135 94% 65%; /* + -soft / -border */+ --node-trigger: 326 100% 74%; /* + -soft / -border */+ --node-workflow: 27 100% 71%; /* + -soft / -border */}[data-theme="dark"] {@@ -242,7 +254,29 @@ Rules:root.dataset.theme = isDarkMode ? 'dark' : 'light';}, [isDarkMode]);```-4. `styles/theme.ts` (`theme.dracula.*`, `theme.colors.*`) is still exported for legacy call sites. New code should prefer Tailwind classes (`bg-primary`, `text-dracula-green`) or `hsl(var(--...))` inline.+4. `styles/theme.ts` (`theme.dracula.*`, `theme.colors.*`) is still exported for the canvas node components and `EdgeConditionEditor`. New code should prefer Tailwind classes (`bg-primary`, `text-dracula-green`, `bg-node-agent-soft`) or `hsl(var(--...))` inline.++### Token tier — pick the most specific that fits++| Tier | Tokens | Use for |+|---|---|---|+| **shadcn semantic** | `background`, `foreground`, `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `success`, `warning`, `info`, `border`, `input`, `ring` | App-wide chrome, status colors, generic actions. Each rotates per theme. |+| **Node-type role** | `node-agent`, `node-model`, `node-skill`, `node-tool`, `node-trigger`, `node-workflow` (+ paired `-soft` and `-border` variants) | Anywhere a node type's identity should drive color: palette icons, parameter-panel sections, draggable variable cards, status badges, edge label tints. |+| **Dracula raw** | `dracula-green`, `dracula-purple`, `dracula-pink`, `dracula-cyan`, `dracula-red`, `dracula-orange`, `dracula-yellow` | Action-button palette (`<ActionButton tone="green">`). Constant across themes by design. Avoid in new code unless you specifically need that. |++### No opacity arithmetic at call sites++`bg-primary/10` and `border-node-agent/30` are forbidden in new code. Themes own the exact tint per role:++```tsx+// ❌ Don't+<Card className="bg-node-agent/10 border-node-agent/30" />++// ✅ Do — themes can redefine --node-agent-soft / -border independently+<Card className="bg-node-agent-soft border-node-agent-border" />+```++Add a new `-soft` / `-border` (or other named) variant to `--node-X` if a unique opacity is needed; never inline the math at the call site.## Component primitives@@ -476,3 +510,5 @@ The `MACHINAOS_INSTALLING=true` env var suppresses the recursive project postins## Migration history (for context)This architecture is the post-migration state. Pre-migration was antd + `styled-components` + a custom theme.ts-driven palette. See [ui_migration_plan.md](./ui_migration_plan.md) for the phase-by-phase transition and the 17 commits that executed it.++**`useAppTheme()` is grandfathered** for the canvas node components (`AIAgentNode`, `SquareNode`, `TriggerNode`, `StartNode`, `ToolkitNode`, `TeamMonitorNode`, `BaseChatModelNode`, `ModelNode`, `GenericNode`) and `EdgeConditionEditor` only — they interpolate per-definition `nodeColor` into gradients, borders, and React Flow `<Handle>` styles. Every other surface uses Tailwind + the token tiers above.