DESIGN.md
Langflow is a visual AI workflow builder where users compose LLM-powered applications by dragging, connecting, and configuring modular components on an infinite canvas. The design language is that of a professional developer tool -- clean, information-dense, and deliberately restrained. Color is earned, not decorative; every hue in the system carries semantic meaning.
The aesthetic sits between a code editor and a node-based creative tool. The core UI is strictly monochromatic -- black primary on white, with a warm zinc-gray scale for layering. This neutral foundation lets the data type color system (14 distinct hues encoding connection compatibility) and accent families (emerald for success, indigo for selection, pink for components) communicate meaning without competing for attention. The result is an interface that feels focused and engineered: complexity emerges from the user's composition, not from the UI itself.
Light and dark themes are fully supported via class-based toggling (.dark on root). The dark theme uses a deep zinc-black (#18181B) as its foundation, not a tinted dark blue, keeping the neutral character consistent across both modes.
The palette is built in concentric layers: a monochromatic core, semantic accent families, status colors, and the domain-specific data type system.
Accents that serve as background / foreground pairs for badges, tags, and contextual surfaces. Both colors in each pair must meet WCAG AA contrast (4.5:1):
Standalone accent references (used for text color, icons, and links -- not as bg/fg pairs):
Used for build status indicators, connection health, and real-time feedback dots:
Langflow uses 14 distinct hues to encode the type of data flowing through node connections. Each type has a saturated foreground and a light-tint background. In light mode, the base token is the saturated color (used for port dots and connection lines) and the -foreground token is the light tint (used for backgrounds). In dark mode, these roles swap -- the base becomes the light tint and the foreground becomes the saturated color. This ensures readability against both light and dark surfaces.
| Data Type | Color Name | Hex (saturated) | Used For |
|---|---|---|---|
| str / Text / Message | indigo | #4F46E5 | String data, text, messages |
| Document | lime | #65A30D | Document objects |
| Data / JSON | red | #DC2626 | Structured data, JSON |
| Embeddings | emerald | #059669 | Vector embeddings |
| LanguageModel | fuchsia | #C026D3 | LLM model objects |
| Prompt | violet | #7C3AED | Prompt templates |
| Tool | cyan | #0891B2 | Tool definitions |
| Agent | purple | #9333EA | Agent objects |
| number | purple | #9333EA | Numeric values |
| DataFrame / Table | pink | #DB2777 | Tabular data |
| chains | orange | #EA580C | Chain compositions |
| memories | yellow | #CA8A04 | Memory objects |
| unknown | gray | #4B5563 | Untyped or unknown |
| inputs | emerald | #059669 | Input components |
Sticky notes on the canvas use soft pastel backgrounds: amber (#FCE68A), neutral (#E4E4E7), rose (#FECDD3), blue (#BFDBFE), lime (#D9F99D).
Used for flow icon gradients, tool-mode indicators, and decorative color swatches. These are high-saturation, high-energy colors intentionally outside the normal UI palette:
Three font families serve distinct roles in the interface.
Inter (sans-serif, variable, 14-32 optical size): The primary UI typeface. Used for all headings, body text, labels, navigation, buttons, and form elements. Its large optical-size range and variable weight (100-900) provide precise control without font-switching. The neutral, geometric character keeps the UI professional and out of the way.
JetBrains Mono (monospace, variable): Used exclusively for code -- code blocks, JSON editors, API keys, component IDs, and any machine-readable content. Its programming ligatures and distinct character shapes (especially 0 vs O, 1 vs l) aid readability in dense technical contexts. Never used for UI labels or headings.
Chivo (display, variable): Reserved for marketing-facing or splash contexts (landing pages, onboarding screens). Its slightly condensed, geometric character adds personality at large sizes. Never used within the application workspace.
The type scale is compact. The application uses 11px (xxs) through 16px (base) for the vast majority of UI. Headlines rarely exceed 24px inside the workspace. Density is preferred over visual hierarchy through size alone -- hierarchy is communicated through weight, color, and spatial grouping.
The application follows a sidebar + infinite canvas model. A collapsible left sidebar (19rem when expanded, 4rem when collapsed to icons) holds navigation, component search, and category panels. The main area is a pannable, zoomable ReactFlow canvas where nodes live.
Spacing follows a strict 4px base grid:
xs): Micro-adjustments -- icon padding within buttons, badge margins, tight inline spacing.sm): Standard internal padding for compact components, gaps between inline elements.md): Card content padding, standard gaps between sibling elements, default component padding.lg): Section margins, dialog padding, sidebar header/footer padding.xl): Major layout divisions, generous whitespace between sections.2xl - 3xl): Page-level margins, hero spacing.Breakpoints:
mdd: 45rem (720px) -- medium-density layout shiftxl: 1200px -- wide layout2xl: 1400px -- container max-width3xl: 1500px -- extra-wideThe canvas itself is unbounded -- nodes can be placed anywhere. The sidebar is the only fixed-width structural element.
Elevation is minimal and functional. The design avoids heavy shadows, instead using border-based containment and tonal shifts to communicate layering. Depth is communicated through three levels:
The infinite workspace background. A dotted grid pattern provides spatial orientation without visual noise.
Content containers that sit on the canvas. White background with a soft ambient shadow.
0 0px 15px -3px rgba(0,0,0,0.1), 0 0px 6px -4px rgba(0,0,0,0.1) -- barely perceptible, just enough to lift nodes off the grid.0 0 10px 2px rgba(128,190,230,0.5) shadow with a 2px rgba(128,190,219,0.86) border and frosted overlay. Signals the node is locked from editing.Overlaid surfaces that demand attention. White background with shadow-lg and a border.
cubic-bezier(0.16, 1, 0.3, 1) easing (spring-like overshoot).Interactive feedback is communicated through micro-animations rather than shadow changes:
active:scale-[0.97] -- a subtle inward squeeze.ring token (black in light, white in dark).The shape language is subtly rounded -- not pill-shaped, not sharp. The base radius is 8px (--radius: 0.5rem), which gives cards, buttons, and containers a modern but not toy-like feel.
Borders are thin. Standard weight is 1px. Occasional 1.5px or 1.75px for emphasis on selected or focus states. All borders use the border token color -- never a hard black or white line.
The button system uses 7 semantic variants:
All buttons share: 40px default height, rounded-lg (8px), font-medium (500 weight), text-sm (14px). Focus state is a 1px ring. Disabled state is opacity-70 with pointer-events-none. The active:scale-[0.97] press effect is optional but recommended for primary actions.
Size variants: lg (44px), default (40px), md (32px), sm (36px), xs (compact), and three icon sizes (iconMd 6px padding, icon 4px padding, iconSm 2px padding).
Inline status indicators and tags. Always pill-shaped (rounded-full) with font-semibold text. Available in 6 semantic variants: default (primary fill), gray, secondary (muted fill), destructive, emerald (success), pink, purple (outlined), and error (light red fill). Three size tiers: sm (16px height, 12px text), md (20px height, 14px text), lg (24px height, 16px text), plus tag (18px height, 11px text) for compact inline labels.
Content containers on surfaces. rounded-lg border on muted background with shadow-sm. Internal structure: header (16px padding, title in semi-bold 16px, optional description in muted 14px), content area (16px horizontal padding), footer (16px padding, flex row). The title uses leading-tight tracking-tight for density.
Text inputs use a bordered white background with rounded-lg corners. Placeholder text is in muted gray (#A1A1AA). Three interaction states: default (border color), hover (border darkens to muted-foreground), focus (border goes to foreground, placeholder becomes transparent). Disabled inputs get muted background and reduced text. A compact input-edit-node variant is used for inline editing within nodes.
Select triggers are 32px height with border and right-aligned chevron. Dropdown content uses the popover surface with shadow-md, rounded-md, and slide-in animation from the opening side. Items highlight with the accent background on focus. Separators use a 1px muted line.
Fixed-position overlays with a white rounded-xl container, 24px padding, and shadow-lg. Enter with a 400ms spring animation (scale 0.95 to 1.0 with clip-path reveal). Close button in the top-right corner. Title in 18px semi-bold, description in muted 14px. Footer uses flex-row with right-aligned actions.
Inline tab bars with no background. The active tab gets a 2px bottom border in currentColor (primary). Inactive tabs show text in muted-foreground, hovering to primary. No rounded backgrounds on tab triggers -- the underline is the sole active indicator.
Checkbox: 16px square, rounded-sm (4px), border in muted-foreground. Checked state fills with primary and shows a white check icon. Switch: 44x24px track with a 16px thumb. Unchecked track uses the input color; checked track uses primary. Thumb slides 20px with a transition. Radio: 16px circle with primary border, filled center dot when selected.
Bordered popover surface (not solid black as one might expect) with rounded-md, shadow-md, 14px text, and directional slide-in animation. Content is z-[99] to sit above all other UI.
Rounded bordered containers with icon + text layout. Default variant uses standard foreground colors. Destructive variant tints the border and text with the destructive red, and the icon inherits that color.
The core UI element of Langflow. Each node is a white rounded card on the canvas containing typed input/output ports, configuration fields, and a status indicator.
node-selected: #4F46E5) replacing the standard border.rounded-xl container with icon buttons, 1px border, and shadow-sm.Collapsible panel (19rem expanded, 4rem icon-only) with smooth 300ms width transitions. Menu buttons are 32px height, rounded-md, with accent background on hover and active states. Supports nested sub-menus with left border indicators. In dark mode, the sidebar has its own dedicated color tokens (darker surface, brighter primary) for visual separation from the canvas.