add guidelines to claude.md (#7007)

* add brand guidelines to claude.md

* add component description

* add component description

frontend/CLAUDE.md

@@ -15,48 +15,13 @@
 - **Use Windmill's theming classes** for consistent colors and surfaces
 - **Avoid custom styles** - prefer Tailwind utility classes
 - **Follow existing patterns** - look at other components for reference
+- **Respect design guidelines** - rules are defined in 'brand-guidelines.md'
 
-### Windmill Theme Classes
+### UI Components
 
-Use these semantic color classes that automatically handle light/dark modes:
-
-#### Backgrounds
-
-- `bg-surface` - Main surface background
-- `bg-surface-secondary` - Secondary/elevated surfaces
-- `bg-surface-hover` - Hover states for interactive elements
-
-#### Text Colors
-
-- `text-primary` - Primary text color
-- `text-secondary` - Secondary text (less prominent)
-- `text-tertiary` - Tertiary text (subtle/muted)
-
-#### Borders
-
-- `border-gray-200 dark:border-gray-700` - Standard borders that adapt to theme
-
-#### Status Colors
-
-Use standard Tailwind color classes with dark mode variants:
-
-- Success: `text-green-500`, `bg-green-100 dark:bg-green-900/30`
-- Error: `text-red-500`, `bg-red-50 dark:bg-red-900/20`
-- Warning: `text-yellow-500`, `bg-yellow-100 dark:bg-yellow-900/30`
-- Info: `text-blue-500`, `bg-blue-100 dark:bg-blue-900/30`
-
-#### Typography
-
-- `font-mono` - For code/technical content
-- `text-xs`, `text-sm`, `text-2xs` - Standard text sizes
-- Use `font-medium`, `font-semibold` for emphasis
-
-### Layout Guidelines
-
-- Use Tailwind spacing utilities (`p-3`, `m-2`, `gap-2`, etc.)
-- Use flexbox/grid utilities for layouts
-- Use `transition-colors` for smooth hover effects
-- Use `overflow-hidden`, `rounded-md` for consistent card styles
+- Use the component TextInput for all text inputs
+- Form components (TextInputs, ToggleButtons, Select ...) should all use the same size when put together, using the unified size system.
+- Read carefully components props JSDoc before using them
 
 ## Backend API
 

frontend/brand-guidelines.md

@@ -0,0 +1,815 @@
+# Windmill Brand Guidelines
+
+_This document contains the complete brand guidelines for Windmill, including visual identity, design system, and communication standards._
+
+# Voice & Communication
+
+This section defines how your brand communicates across all channels and touchpoints.
+
+# Tone of Voice
+
+Your tone of voice should match the serious, professional, no-nonsense character of the product and brand.
+
+## Suggested Content Structure
+
+| **Approach**                                                                  | **✅ Do This**                                          | **❌ Not This**                                         |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------- |
+| **Direct & Honest** – Say exactly what the product does, no marketing fluff.  | "Deploy complex workflows in minutes."                  | "Experience seamless automation magic."                 |
+| **Technical & Precise** – Speak like your audience: developers and engineers. | "Scale scripts without worrying about dependencies."    | "Your team will love our easy drag-and-drop interface." |
+| **Confident & Assertive** – Show that the product can handle anything.        | "No limitations. Every workflow is fully customizable." | "Works well for most use cases."                        |
+| **Minimalist & Functional** – Avoid unnecessary adjectives or filler words.   |                                                         |                                                         |
+
+# Visual Identity
+
+This section covers all visual elements that make up your brand identity.
+
+## Overview
+
+Visual Identity includes:
+
+- Logo: Usage guidelines, variations, and spacing requirements
+- Color System: Primary, secondary, and semantic colors with specifications
+- Typography: Font families, hierarchy, and implementation guidelines
+  Use the navigation on the left to explore each subsection and add your specific visual identity content.
+
+# Color system
+
+Our color system is designed for **reliability, clarity, and trust**. Windmill is destined to be used by big companies, so colors must convey a sense of professionalism and seriousness. We stay away from vibrant colors in the application interface and use monochromatic tones with purposeful accent colors.
+
+## Design Principles
+
+- **Meaningful, not decorative**: Every color serves a functional purpose
+- **Reliability over vibrancy**: Muted tones convey trust and professionalism
+- **Context-aware**: Different palettes for app vs marketing contexts
+- **Accessible**: All colors meet WCAG AA contrast requirements
+- **Consistent**: Systematic approach to color usage across all interfaces
+
+## Color Philosophy
+
+**Colors are meaningful and never decorative.** We distinguish between:
+
+- **App palette**: Less vibrant colors for the core application interface
+- **Web palette**: More vibrant colors for marketing and brand recognition
+- **Monochromatic scale**: Nord-based neutrals for surfaces and backgrounds
+
+## Color Palette Overview
+
+Our complete color system in action, showing how all color categories work together across light and dark themes:
+![Complete Windmill color palette (Light mode)](./static/brand-guidelines-assets/example-color-palette-light.svg)
+_Light mode example_
+
+## Accent Colors
+
+The **luminance-blue** is our primary accent color, used throughout the app for interactive elements, active states, and user actions.
+_[Color palette display - see original documentation for interactive colors]_
+**When to use:**
+
+- Call-to-action buttons
+- Active navigation items
+- Toggle switches (on state)
+- Progress bars
+- Interactive links
+- Selected states
+
+## Surface Colors
+
+Surface colors create depth and layout structure with clear hierarchy between different interface levels.
+_[Color palette display - see original documentation for interactive colors]_
+
+## Text Colors
+
+Text colors provide clear hierarchy and readability across light and dark themes.
+_[Color palette display - see original documentation for interactive colors]_
+
+## Border Colors
+
+Border colors define element separation and structure.
+_[Color palette display - see original documentation for interactive colors]_
+
+## Feedback Colors
+
+Standard semantic colors for system feedback and status communication.
+_[Color palette display - see original documentation for interactive colors]_
+
+## Reserved Colors
+
+These colors are exclusively reserved for specific features and should not be used elsewhere.
+_[Color palette display - see original documentation for interactive colors]_
+**Usage:**
+
+- AI-powered script generation
+- Magic wand icons
+- AI assistance features
+- Smart suggestions
+
+## Web/Marketing Colors
+
+More vibrant colors used exclusively for marketing materials and the website (not in the core application).
+_[Color palette display - see original documentation for interactive colors]_
+**Important:** These colors should **never** be used in the core application interface. They are reserved for:
+
+- Marketing website
+- Landing pages
+- Documentation site headers
+- Brand materials
+- Social media assets
+
+## Color Reference
+
+Complete color system with usage guidelines, hex values, and Tailwind classes:
+**Implementation Rule:** Always use the provided Tailwind classes in your components. Never use hex values directly in styles - this ensures consistency and theme switching compatibility.
+
+```jsx
+// ✅ Correct - use Tailwind classes
+Save
+Content
+// ❌ Wrong - don't use hex values
+Save
+```
+
+## Do's and Don'ts
+
+### ✅ Do
+
+- Use provided Tailwind classes for all color implementations
+- Use `accent-primary` sparingly for important actions
+- Rely on surface colors for most interface backgrounds
+- Apply text colors according to content hierarchy
+- Use proper border colors for element separation
+- Apply feedback colors consistently for their semantic meaning
+- Test color combinations for accessibility compliance
+- Reserve AI purple exclusively for AI features
+- Follow the defined color token structure
+
+### ❌ Don't
+
+- Use hex values directly in component styles or CSS
+- Mix web/marketing colors with app interface colors
+- Use AI purple for non-AI features
+- Create custom color variations between defined tokens
+- Use color alone to convey meaning (pair with icons/text)
+- Apply accent colors to large surface areas
+- Use marketing blue (`#3B82F6`) in the app interface
+- Use `accent-primary` for large backgrounds
+- Mix different color token categories inappropriately
+
+### Color-Blind Considerations
+
+- Never use color alone to convey information
+- Pair color with icons, text, or patterns
+- Test designs with color-blind simulation tools
+- Ensure sufficient contrast in monochrome
+
+## Quick Reference
+
+| Token                    | Light Mode | Dark Mode | Tailwind Class             | Usage                                                  |
+| ------------------------ | ---------- | --------- | -------------------------- | ------------------------------------------------------ |
+| **Accent Colors**        |            |           |                            |                                                        |
+| accent-primary           | #758ff8    | #7085db   | `accent-primary`           | Primary accent color for buttons, links, active states |
+| accent-hover             | #5074f6    | #5670d5   | `accent-hover`             | Hover state for interactive accent elements            |
+| accent-clicked           | #2c5beb    | #425bbd   | `accent-clicked`           | Active/pressed state for accent elements               |
+| accent-secondary         | #293676    | #e8ebfb   | `accent-secondary`         | Secondary accent for strong emphasis                   |
+| accent-secondary-hover   | #1e255f    | #c3c9df   | `accent-secondary-hover`   | Hover state for accent secondary elements              |
+| accent-secondary-clicked | #303f82    | #9da6ca   | `accent-secondary-clicked` | Active/pressed state for accent secondary elements     |
+| accent-selected          | #bfdbfe4c  | #6790c44c | `accent-selected`          | Selected state background                              |
+|                          |            |           |                            |                                                        |
+| **Surface Colors**       |            |           |                            |                                                        |
+| surface-primary          | #fbfbfd    | #2e3441   | `surface-primary`          | Main application background                            |
+| surface-secondary        | #efeff4    | #272c35   | `surface-secondary`        | Secondary backgrounds, sections                        |
+| surface-tertiary         | #ffffff    | #353c4a   | `surface-tertiary`         | Cards, modals, elevated surfaces                       |
+| surface-hover            | #cfcfe233  | #7784a119 | `surface-hover`            | Hover states for neutral elements                      |
+| surface-selected         | #ffffff    | #434c5e   | `surface-selected`         | Selected neutral elements                              |
+| surface-disabled         | #d8d8e433  | #212732   | `surface-disabled`         | Disabled elements, inactive states                     |
+| surface-sunken           | #e8e8ef    | #242832   | `surface-sunken`           | Sunken or inset surfaces                               |
+| surface-input            | #ffffff    | #292e38   | `surface-input`            | Input field backgrounds                                |
+|                          |            |           |                            |                                                        |
+| **Text Colors**          |            |           |                            |                                                        |
+| text-primary             | #3d4758    | #d4d7dd   | `text-primary`             | Default text, body content                             |
+| text-emphasis            | #1d2430    | #eeeff2   | `text-emphasis`            | Headers, labels, emphasized content                    |
+| text-secondary           | #718096    | #a9b0ba   | `text-secondary`           | Supporting information, metadata                       |
+| text-tertiary            | #505c70    | #a8aeb7   | `text-tertiary`            | Subtle text, captions                                  |
+| text-hint                | #8d93a1    | #8d93a1   | `text-hint`                | Placeholders, tooltips, hints                          |
+| text-disabled            | #a0aec0    | #9098a2   | `text-disabled`            | Disabled states, unavailable options                   |
+| text-accent              | #5074f6    | #c7cefc   | `text-accent`              | Accent colored text, links                             |
+|                          |            |           |                            |                                                        |
+| **Border Colors**        |            |           |                            |                                                        |
+| border-light             | #e5e7eb    | #374457   | `border-light`             | Subtle borders, dividers                               |
+| border-normal            | #9ca3af    | #a9b0ba   | `border-normal`            | Standard borders, form inputs                          |
+| border-accent            | #2c5beb    | #a0affa   | `border-accent`            | Accent borders, focus states                           |
+| border-selected          | #a0affa    | #6475b7   | `border-selected`          | Selected element borders                               |
+|                          |            |           |                            |                                                        |
+| **Reserved Colors**      |            |           |                            |                                                        |
+| ai-primary               | #a02cde    | #f0c6fb   | `ai-primary`               | AI features, magic wand icon, AI-powered functionality |
+|                          |            |           |                            |                                                        |
+| **Feedback Colors**      |            |           |                            |                                                        |
+| success                  | #22c55e    | #22c55e   | `green-500`                | Success states, positive feedback, completed actions   |
+| warning                  | #eab308    | #eab308   | `yellow-500`               | Warning states, caution messages, pending actions      |
+| error                    | #ef4444    | #ef4444   | `red-500`                  | Error states, failed actions, destructive operations   |
+| info                     | #3b82f6    | #3b82f6   | `blue-500`                 | Information states, neutral notifications              |
+|                          |            |           |                            |                                                        |
+
+Remember: **Colors are meaningful, not decorative.** Every color choice should serve a clear functional purpose in the user interface.
+
+# Elevation
+
+Windmill uses a **minimal elevation system** based on surface colors and strategic shadows. We prioritize clarity and simplicity over complex layering effects.
+
+## Elevation Principles
+
+- **Surface colors create depth**: Darker surfaces appear deeper than lighter ones
+- **Shadows only for overlays and movement**: Not for making elements stand out
+- **Light borders for grouping**: Preferred over shadows for content separation
+- **Use sparingly**: Limit elevation to avoid visual noise
+
+## Surface Depth System
+
+We use surface colors from our color system to create depth hierarchy:
+
+- **`surface-primary`** (#FBFBFD): Default elevation, main backgrounds
+- **`surface-secondary`** (#EFEFF4): Sunken surfaces, recessed areas
+- **`surface-tertiary`** (#FFFFFF): Elevated cards and content areas
+
+## Shadow Usage
+
+### When to Use Shadows
+
+**✅ Use shadows for:**
+
+- **Overlays**: Modals, dropdowns, tooltips (`shadow-lg`)
+- **Moving elements**: Drag and drop, active states (`shadow-md`)
+  **❌ Don't use shadows for:**
+- Making buttons or elements stand out
+- Content grouping or separation
+- Decorative purposes
+- Permanent interface elements
+
+### Shadow Specifications
+
+- **`shadow-md`**: For moving elements and temporary elevation
+- **`shadow-lg`**: For overlays and floating content
+- **Light borders**: `border-light` (#E5E7EB) for grouping instead of shadows
+
+## Examples
+
+### Overlay Elevation
+
+Modals, dropdowns, and floating content use `shadow-lg` with light borders:
+![Overlay elevation example showing modal with shadow](./static/brand-guidelines-assets/elevation-overlay.svg)
+
+### Sunken Surface
+
+Recessed areas use `surface-secondary` to appear deeper than the main background:
+![Sunken surface example showing recessed area](./static/brand-guidelines-assets/elevation-sunken.svg)
+
+## Do's and Don'ts
+
+### ✅ Do
+
+- Use `surface-secondary` for sunken or recessed areas
+- Apply `shadow-lg` only to overlays (modals, dropdowns)
+- Use `shadow-md` for elements being moved or dragged
+- Prefer light borders (`border-light`) for content grouping
+- Keep elevation simple and purposeful
+- Use `surface-tertiary` for elevated cards when needed
+
+### ❌ Don't
+
+- Use shadows to make buttons or static elements stand out
+- Combine multiple elevation techniques unnecessarily
+- Create custom shadow values outside the system
+- Use elevation purely for decoration
+- Apply heavy shadows that distract from content
+- Overuse elevation effects throughout the interface
+  Remember: **Elevation should enhance usability, not create visual complexity.** When in doubt, use surface colors instead of shadows for depth.
+
+# Typography
+
+Our typography system is designed for **clarity, efficiency, and minimalism**. With limited screen space in a complex developer tool, we prioritize readability and information density over decorative hierarchy.
+
+## Design Principles
+
+- **Space-efficient**: Default to 12px for body text to maximize content visibility
+- **Minimal hierarchy**: Only 3 header levels to avoid confusion
+- **Weight over size**: Use font-weight to create hierarchy, not excessive size changes
+- **Functional**: Every style has a clear, specific purpose
+
+## Font Family
+
+We use **Inter** for all UI text due to its excellent readability at small sizes and professional appearance.
+For technical content (IDs, code snippets, JSON), use the system **monospace** font.
+
+## Text Colors
+
+_[Color palette display - see original documentation for interactive colors]_
+
+### Color Philosophy
+
+We use a **lighter default** with a **darker emphasis option** to:
+
+- Reduce eye strain during extended use
+- Create clear visual hierarchy without relying on size
+- Make emphasized content truly stand out
+- Align with modern developer tool aesthetics
+  **Key principle:** Use `text-primary` for most content, reserve `text-emphasis` for true importance.
+
+## Type Styles
+
+### Typography Scale Overview
+
+### App Page Title
+
+**When to use**: Main application page titles, primary navigation headings
+
+```tsx
+class = 'font-semibold text-2xl text-emphasis';
+```
+
+- **Size**: 24px (`text-2xl`)
+- **Weight**: 600 (`font-semibold`)
+- **Color**: `text-emphasis`
+- **Example**: "Job Orchestrator", "Flow Builder", "Resource Manager"
+
+---
+
+### Page Title
+
+**When to use**: Top-level page headings, modal titles, main view names
+
+```tsx
+class = 'text-lg font-semibold text-emphasis';
+```
+
+- **Size**: 18px (`text-lg`)
+- **Weight**: 600 (`font-semibold`)
+- **Color**: `text-emphasis`
+- **Example**: "Job Orchestrator Dashboard", "Edit Flow Configuration"
+
+---
+
+### Section Header
+
+**When to use**: Panel headers, card titles, collapsible section names, sidebar groups
+
+```tsx
+class = 'text-sm font-semibold text-emphasis';
+```
+
+- **Size**: 14px (`text-sm`)
+- **Weight**: 600 (`font-semibold`)
+- **Color**: `text-emphasis`
+- **Example**: "Active Jobs", "Configuration", "Environment Variables"
+
+---
+
+### Body
+
+**When to use**: Default text throughout the application - descriptions, content, list items, table cells
+
+```tsx
+class = 'text-xs font-normal text-primary';
+```
+
+- **Size**: 12px (`text-xs`)
+- **Weight**: 400 (`font-normal`)
+- **Color**: `text-primary`
+- **Example**: Form descriptions, paragraph content, dialog text
+  **This is your default**. When in doubt, use this style.
+
+---
+
+### Body Emphasized
+
+**When to use**: Important labels, form field labels, tab labels, emphasis within body text
+
+```tsx
+class = 'text-xs font-semibold text-emphasis';
+```
+
+- **Size**: 12px (`text-xs`)
+- **Weight**: 600 (`font-semibold`)
+- **Color**: `text-emphasis`
+- **Example**: "Job Name:", "Status:", button labels
+
+---
+
+### Secondary Text
+
+**When to use**: Supporting information, metadata, timestamps, status descriptions
+
+```tsx
+class = 'text-xs font-normal text-secondary';
+```
+
+- **Size**: 12px (`text-xs`)
+- **Weight**: 400 (`font-normal`)
+- **Color**: `text-secondary`
+- **Example**: "Last run 2 hours ago", "Created by John Doe", file sizes
+
+---
+
+### Caption
+
+**When to use**: Helper text below inputs, table column headers, inline annotations, badges
+
+```tsx
+class = 'text-2xs font-normal text-secondary';
+```
+
+- **Size**: 11px (`text-2xs`)
+- **Weight**: 400 (`font-normal`)
+- **Color**: `text-secondary`
+- **Example**: "Optional field", "Max 100 characters", column headers
+
+---
+
+### Hint
+
+**When to use**: Input placeholders, tooltip content, empty state messages, subtle guidance
+
+```tsx
+class = 'text-2xs font-normal text-hint';
+```
+
+- **Size**: 11px (`text-2xs`)
+- **Weight**: 400 (`font-normal`)
+- **Color**: `text-hint`
+- **Example**: "Enter job name...", "Search flows", tooltip text
+
+---
+
+### Code/Monospace
+
+**When to use**: Job IDs, code snippets, file paths, API endpoints, JSON keys, technical identifiers
+
+```tsx
+class = 'text-2xs font-mono font-normal text-emphasis';
+```
+
+- **Size**: 11px (`text-2xs`)
+- **Weight**: 400 (`font-normal`)
+- **Color**: `text-emphasis`
+- **Font**: System monospace
+- **Example**: `job_id_12345`, `/api/v1/jobs`, `ENV_VAR_NAME`
+  **Note**: Use `text-emphasis` for code to ensure technical values stand out and are easily scannable.
+
+---
+
+## Usage Guidelines
+
+### Creating Hierarchy
+
+Use these methods in order of preference:
+
+1. **Font weight** - Semibold (600) for headers and emphasis, normal (400) for body
+2. **Color** - Primary for main content, secondary for supporting info, hint for subtle guidance
+3. **Size** - Only change size for true hierarchy levels (page title vs section header vs body)
+   **Don't** create hierarchy by:
+
+- Making text larger than 24px (except for App Page Titles)
+- Using more than 3 header levels
+- Adding excessive spacing or borders
+
+## Creating Visual Hierarchy - Priority Order
+
+1. **Font Weight** - Use semibold (600) for emphasis
+2. **Color** - Use textEmphasis for important content
+3. **Position & Spacing** - Group related content, add white space
+4. **Size** - Only use defined type styles, never custom sizes
+
+### ❌ Don't
+
+- Increase font size to make something "stand out"
+- Create one-off font sizes for special cases
+- Use large headers in dense UI areas
+
+### ✅ Do
+
+- Use font-weight to emphasize within the same size
+- Use textEmphasis color for important content
+- Add spacing around important elements
+
+## Text Casing
+
+### Primary Rule: Use Sentence Case
+
+Use sentence case for all UI text—capitalize only the first word and proper nouns. This approach improves readability and is faster to implement consistently.
+**Examples:**
+
+- ✅ "Create new flow"
+- ✅ "Edit Windmill resource"
+- ❌ "Create New Flow"
+- ❌ "SAVE CHANGES"
+
+### Casing by Component Type
+
+**Page titles and headings**
+
+- Use sentence case: "Job orchestrator dashboard"
+  **Buttons and actions**
+- Use sentence case: "Save changes", "Delete job"
+  **Form labels**
+- Use sentence case: "Job name", "Resource type"
+  **Navigation items**
+- Use sentence case: "User settings", "Resource manager"
+  **Error messages and notifications**
+- Use sentence case: "Job completed successfully"
+
+### Always Capitalize
+
+- **Proper nouns**: Windmill, Docker, Python, GitHub
+- **Acronyms**: API, HTTP, JSON, SQL
+- **First word** of any sentence or UI element
+
+### Special Cases
+
+- **Technical identifiers**: Keep original casing (`job_id_123`, `ENV_VAR`)
+- **Brand names**: Follow brand guidelines (iPhone, macOS)
+- **Abbreviations**: Use standard forms (ID, URL, vs.)
+
+### Accessibility Note
+
+Avoid ALL CAPS text except for very short labels (2-3 characters max). All caps text is slower to read and can appear aggressive to users.
+
+## Decision Tree
+
+Not sure which style to use? Follow this:
+Is it a main application page title?
+→ **Yes**: App Page Title (24px, semibold)
+→ **No**: Continue
+Is it a page or modal title?
+→ **Yes**: Page Title (18px, semibold)
+→ **No**: Continue
+Is it a section/panel header?
+→ **Yes**: Section Header (14px, semibold)
+→ **No**: Continue
+Is it technical data (ID, code, path)?
+→ **Yes**: Code/Monospace (11px, mono)
+→ **No**: Continue
+Is it a placeholder or tooltip?
+→ **Yes**: Hint (11px, hint color)
+→ **No**: Continue
+Is it helper text or a table header?
+→ **Yes**: Caption (11px, secondary color)
+→ **No**: Continue
+Is it metadata or supporting info?
+→ **Yes**: Secondary Text (12px, secondary color)
+→ **No**: Continue
+Is it a label or needs emphasis?
+→ **Yes**: Body Emphasized (12px, semibold weight, emphasis color)
+→ **No**: Body (12px, normal, primary color) ← **DEFAULT**
+
+## Accessibility
+
+- All text colors meet contrast requirements on standard backgrounds
+- Never use font size alone to convey meaning
+- Ensure disabled text (`text-disabled`) is paired with visual disabled states
+
+## Common Mistakes
+
+❌ **Don't** create custom font sizes between defined styles
+✅ **Do** use the defined type styles
+❌ **Don't** use Section Header inside table cells
+✅ **Do** use Caption for table headers
+❌ **Don't** use Body Emphasized everywhere for "importance"
+✅ **Do** reserve it for labels and truly emphasized content
+❌ **Don't** make job IDs or code bold/colored
+✅ **Do** use monospace font with text-emphasis for technical identifiers
+❌ **Don't** use text-emphasis for body paragraphs
+✅ **Do** use text-primary for most content, text-emphasis for headers/labels
+
+# Design System
+
+This section covers the complete design system including components, layouts, and interaction patterns.
+
+## Overview
+
+Design System includes:
+
+- Iconography: Icon library and usage guidelines
+- Spacing & Grid: Layout fundamentals and spacing scales
+- Components: Reusable UI components and specifications
+- Layout: Page structure and content organization principles
+  Use the navigation on the left to explore each subsection and add your specific design system content.
+
+# Components
+
+## Core Rules
+
+### 1. Always Use the Component Library
+
+**Never create custom components.** Use only the provided components from Windmill's library. If you need functionality that doesn't exist, request it from the design system team.
+
+### 2. No Style Hacking
+
+**Do not override component styles.** Components provide props for all supported variants and configurations. If you need a different appearance, use the appropriate prop variant.
+
+```jsx
+// ✅ Correct - use provided variants
+// ❌ Wrong - don't add custom styles
+```
+
+### 3. Check Guidelines First
+
+**Always consult these component guidelines** before implementing. Each component section specifies:
+
+- When to use each variant
+- Proper implementation patterns
+- Accessibility requirements
+- Common mistakes to avoid
+
+## Quick Reference
+
+### Before You Code
+
+1. Check if a component exists for your use case
+2. Read the component's specific guidelines
+3. Use only the documented props and variants
+4. Test accessibility with keyboard navigation
+
+## Buttons
+
+Windmill uses **4 button types** with clear hierarchy. Each button type comes in 3 variants (text, icon+text, icon-only) and supports multiple states including hover, active, disabled, and selected (default and subtle only).
+**Button Hierarchy:**
+
+- **Accent Secondary** (Highest Priority): Main conversion CTAs on landing pages - "Sign up", "Get started", "Download"
+- **Accent** (High Priority): Most important action per view - "Save", "Submit", "Create" (only one per screen)
+- **Default** (Standard Priority): Secondary actions and most UI interactions - "Cancel", "Edit", "Delete"
+- **Subtle** (Low Priority): Tertiary actions in dense interfaces - toolbars, button groups
+  **Button States:**
+- **Default**: Standard button appearance
+- **Hover**: Interactive feedback when cursor hovers over button
+- **Active/Pressed**: Visual feedback when button is clicked or pressed
+- **Disabled**: Non-interactive state for unavailable actions
+- **Selected**: Active selection state (available only for Default and Subtle variants)
+  **Usage Rules:**
+- ✅ Use appropriate hierarchy, provide tooltips for icon-only buttons, test all states including disabled and selected
+- ❌ Don't use multiple Accent buttons per view, use Accent Secondary outside marketing, create custom styles, or use selected state on Accent variants
+
+## Implementation Notes
+
+When implementing any component:
+
+1. **Follow the design system**: Use only the components and variants documented here
+2. **Accessibility first**: All components include built-in accessibility features
+3. **Test thoroughly**: Verify functionality across different states and themes
+4. **Ask questions**: When in doubt, consult the design system team before creating custom solutions
+
+# Iconography
+
+We use the **[Lucide icon library](https://lucide.dev/)** to ensure a consistent, modern, and lightweight visual language. Icons are line-only, aligning with our clean and technical aesthetic.
+
+## Do's and Don'ts
+
+### ✅ Do
+
+- Use Lucide icons consistently throughout the interface
+- Maintain the original 2px stroke width and style
+- Use semantic colors from our color system
+- Pair icons with text labels when possible
+- Use standard sizes (16px, 20px, 24px, 32px)
+- Ensure sufficient contrast for accessibility
+
+### ❌ Don't
+
+- Mix different icon libraries or styles
+- Modify the stroke width or visual style
+- Use icons as pure decoration without function
+- Use icons alone for complex or uncommon actions
+- Scale icons to arbitrary sizes
+- Create custom icons unless absolutely necessary
+  Icons should enhance usability and clarity, not complicate the interface. When in doubt, prioritize clear text labels over icons alone.
+
+# Layout
+
+Our layout system ensures **consistency, clarity, and usability** across all interfaces. These guidelines establish standardized patterns for organizing content and interface elements.
+
+## Form
+
+Forms are fundamental building blocks of our application. They should be clear, efficient, and follow consistent patterns to reduce cognitive load and improve user experience.
+
+### Design Principles
+
+- **Predictable structure**: Consistent vertical hierarchy helps users scan and complete forms efficiently
+- **Clear communication**: Every element serves a purpose in guiding users toward successful completion
+- **Minimal cognitive load**: Use established patterns and clear visual hierarchy
+- **Accessible by default**: Follow semantic HTML and proper labeling conventions
+
+### Vertical Layout Guidelines
+
+All form elements follow a consistent top-to-bottom hierarchy:
+**Label → Description → Input → Validation/Hint**
+This predictable order allows users to quickly understand what information is needed and how to provide it correctly.
+
+### Spacing Guidelines
+
+Use consistent spacing to create clear relationships between form elements:
+
+- **4px gap (`gap-y-1`)** between all adjacent form elements:
+- Label to Description
+- Description to Input
+- Input to Validation/Hint
+  This tight, consistent spacing groups related elements while maintaining clear separation between form fields.
+
+### Typography Guidelines
+
+Follow our established [typography system](../../visual_identity/3_typography/index.mdx) for form elements:
+
+#### Label
+
+- **Style**: Body emphasized (`text-xs font-semibold text-emphasis`)
+- **Purpose**: Clearly identify what information is required
+- **Example**: "Job name:", "Resource type:", "Environment variables:"
+
+#### Description
+
+- **Style**: Body (`text-xs font-normal text-secondary`)
+- **Purpose**: Provide additional context or instructions
+- **Example**: "Choose a descriptive name for your automation job"
+
+#### Validation/Hint
+
+- **Style**: Caption (`text-2xs font-normal text-hint`)
+- **Purpose**: Guide users with requirements or feedback
+- **Example**: "Required field", "Must be at least 8 characters", "Optional field"
+
+### Writing Guidelines
+
+#### Descriptions
+
+- Keep descriptions concise and actionable
+- Focus on the outcome or benefit, not the technical process
+- Use sentence case and avoid unnecessary punctuation
+- Example: ✅ "Choose the Python version for your script execution" vs ❌ "This dropdown allows you to select which Python version will be used when executing your script."
+
+#### Helper Text and Hints
+
+- Be specific about requirements upfront
+- Use positive language when possible
+- Provide examples for complex inputs
+- Example: ✅ "Use lowercase letters, numbers, and hyphens only" vs ❌ "Invalid characters not allowed"
+
+### Tooltip Usage
+
+Use tooltips sparingly for **additional context** that would otherwise clutter the interface:
+
+- Complex terminology or concepts that need definition
+- Background information that helps with decision-making
+- Links to relevant documentation or resources
+  **Don't use tooltips for**:
+- Essential information needed to complete the form
+- Error messages or validation feedback
+- Basic instructions that should be in the description
+
+### Visual Example
+
+![Form layout pattern showing proper hierarchy and spacing (Light mode)](./static/brand-guidelines-assets/form-light.svg)
+_Light mode example_
+
+### Implementation Notes
+
+- Always include proper semantic HTML (`, `, etc.)
+- Associate labels with inputs using `for` attributes or wrapping
+- Maintain consistent spacing using Tailwind's `gap-y-1` utility
+- Test form layouts across different viewport sizes
+- Ensure sufficient color contrast for all text elements
+
+# Spacing & Layout
+
+Windmill uses **Tailwind CSS spacing utilities** and **flex containers** to create consistent, responsive layouts across all interfaces.
+
+## Spacing Scale
+
+Our spacing system follows **Tailwind's default spacing scale** based on 4px increments:
+
+- **`space-1`** (4px): Micro spacing between related elements
+- **`space-2`** (8px): Base unit for component padding and margins
+- **`space-4`** (16px): Standard spacing between components
+- **`space-6`** (24px): Section spacing and larger gaps
+- **`space-8`** (32px): Page margins and major sections
+- **`space-12`** (48px): Large spacing for visual breaks
+- **`space-16`** (64px): Maximum spacing for major layout divisions
+
+## Layout System
+
+We use **Tailwind's flex utilities** for responsive layouts:
+
+- **Flex containers**: `flex flex-col` or `flex flex-row` for layout direction
+- **Spacing**: `space-x-4` and `space-y-4` for consistent gaps between elements
+- **Max width**: `max-w-6xl` (1152px) for content areas
+
+## Do's and Don'ts
+
+### ✅ Do
+
+- Use Tailwind spacing utilities (`p-4`, `m-6`, `space-x-4`) for all measurements
+- Use flex responsive classes (`flex-col md:flex-row`, `justify-between`)
+- Apply consistent container patterns (`container mx-auto px-8`)
+- Use `space-x-*` and `space-y-*` for gaps between flex items
+- Leverage Tailwind's responsive breakpoints (`sm:`, `md:`, `lg:`, `xl:`)
+
+### ❌ Don't
+
+- Use arbitrary spacing values with square brackets `[32px]`
+- Mix CSS spacing with Tailwind utilities in the same component
+- Use fixed pixel values instead of responsive utilities
+- Break responsive design patterns with custom CSS

frontend/src/lib/components/AddUser.svelte

@@ -75,7 +75,7 @@
 
 <Popover placement="bottom-end">
 	{#snippet trigger()}
-		<Button variant="accent" size="xs" nonCaptureEvent={true} startIcon={{ icon: UserPlus }}>
+		<Button variant="accent" unifiedSize="md" nonCaptureEvent={true} startIcon={{ icon: UserPlus }}>
 			Add new user
 		</Button>
 	{/snippet}

frontend/src/lib/components/Popover.svelte

@@ -1,4 +1,8 @@
 <script lang="ts">
+	/**
+	 * @deprecated Use `$lib/components/meltComponents/Popover.svelte` instead.
+	 * This legacy popover component will be removed in a future version.
+	 */
 	import { createPopperActions, type PopperOptions } from 'svelte-popperjs'
 	import type { PopoverPlacement } from './Popover.model'
 	import Portal from '$lib/components/Portal.svelte'

frontend/src/lib/components/Tooltip.svelte

@@ -1,4 +1,8 @@
 <script lang="ts">
+	/**
+	 * @deprecated Use `$lib/components/meltComponents/Tooltip.svelte` instead.
+	 * This legacy tooltip component will be removed in a future version.
+	 */
 	import Markdown from 'svelte-exmarkdown'
 	import type { PopoverPlacement } from './Popover.model'
 	import Popover from './Popover.svelte'

frontend/src/lib/components/common/button/Button.svelte

@@ -25,20 +25,41 @@
 		id?: string
 		aiId?: string | undefined
 		aiDescription?: string | undefined
+		/**
+		 * @deprecated Use `unifiedSize` instead
+		 */
 		size?: ButtonType.Size
+		/**
+		 * @deprecated Use `unifiedSize` instead
+		 */
 		spacingSize?: ButtonType.Size
+		/**
+		 * Unified sizing: sm (28px), md (32px), lg (40px)
+		 */
 		unifiedSize?: ButtonType.UnifiedSize
 		/**
-		 * @description Extended size for App only, do not use
+		 * @description Extended size for App editor only
 		 */
 		extendedSize?: ButtonType.ExtendedSize
 		/**
 		 * @deprecated Use `variant` instead
 		 */
 		color?: ButtonType.Color | string
+		/**
+		 * Button style: accent, accent-secondary, default, subtle
+		 */
 		variant?: ButtonType.Variant
+		/**
+		 * Additional classes. Do NOT use for colors/fonts - use for layout only
+		 */
 		btnClasses?: string
+		/**
+		 * Wrapper classes. Do NOT use for colors/fonts - use for positioning only
+		 */
 		wrapperClasses?: string
+		/**
+		 * Wrapper styles. Avoid unless absolutely necessary
+		 */
 		wrapperStyle?: string
 		disabled?: boolean
 		selected?: boolean

frontend/src/lib/components/common/button/model.ts

@@ -13,6 +13,9 @@ export const BUTTON_COLORS = [
 ] as const
 
 export namespace ButtonType {
+	/**
+	 * @deprecated Use `UnifiedSize` instead
+	 */
 	export type Size = 'xs3' | 'xs2' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
 	export type UnifiedSize = 'sm' | 'md' | 'lg'
 	export type ExtendedSize = 'xs2' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'