OpenNoodl/dev-docs/reference/UI-STYLING-GUIDE.md

UI Styling Guide for Noodl Editor

For Cline: Read this document before doing ANY UI/styling work in the editor.

Why This Document Exists

The Noodl editor has accumulated styling debt from 2015-era development. Many components use hardcoded hex colors instead of the design token system. This guide ensures consistent, modern styling.

Key Rule: NEVER copy patterns from legacy CSS files. They're full of hardcoded colors.

---

Part 1: Token System Architecture

Token Files Location

packages/noodl-editor/src/editor/src/styles/custom-properties/
├── colors.css      ← COLOR TOKENS (this is what's imported)
├── fonts.css       ← Typography tokens
├── animations.css  ← Motion tokens
├── spacing.css     ← Spacing tokens (add if missing)

Import Chain

The editor entry point (packages/noodl-editor/src/editor/index.ts) imports tokens from the editor's own copies, NOT from noodl-core-ui:

// What's actually used:
import '../editor/src/styles/custom-properties/colors.css';

---

Part 2: Design Token Reference

Background Colors (Dark to Light)

Token	Use For	Approximate Value
--theme-color-bg-0	Deepest black	#000000
--theme-color-bg-1	App/modal backdrops	#09090b
--theme-color-bg-2	Panel backgrounds	#18181b
--theme-color-bg-3	Cards, inputs	#27272a
--theme-color-bg-4	Elevated surfaces	#3f3f46
--theme-color-bg-5	Highest elevation	#52525b

Foreground Colors (Muted to Bright)

Token	Use For
--theme-color-fg-muted	Disabled text, placeholders
--theme-color-fg-default-shy	Secondary/helper text
--theme-color-fg-default	Normal body text
--theme-color-fg-default-contrast	Emphasized text
--theme-color-fg-highlight	Maximum emphasis (white)

Brand Colors

Token	Use For	Color
--theme-color-primary	CTA buttons, active states	Rose
--theme-color-primary-highlight	Primary hover states	Rose (lighter)
--theme-color-secondary	Secondary elements	Violet
--theme-color-secondary-highlight	Secondary hover	Violet (lighter)

Status Colors

Token	Use For
--theme-color-success	Success states
--theme-color-notice	Warnings
--theme-color-danger	Errors, destructive actions

Border Colors

Token	Use For
--theme-color-border-subtle	Light dividers
--theme-color-border-default	Standard borders
--theme-color-border-strong	Emphasized borders

---

Part 3: Hardcoded Color Replacement Map

When you encounter hardcoded hex colors, replace them using this table:

Backgrounds

If You See	Replace With
#000000	var(--theme-color-bg-0)
#0a0a0a, #09090b	var(--theme-color-bg-1)
#151515, #171717, #18181b	var(--theme-color-bg-2)
#1d1f20, #202020	var(--theme-color-bg-2)
#272727, #27272a, #2a2a2a	var(--theme-color-bg-3)
#2f3335, #303030	var(--theme-color-bg-3)
#333333, #383838, #3c3c3c	var(--theme-color-bg-4)
#444444, #4a4a4a	var(--theme-color-bg-5)
#555555	var(--theme-color-bg-5)

Text/Foregrounds

If You See	Replace With
#666666, #6a6a6a	var(--theme-color-fg-muted)
#888888	var(--theme-color-fg-muted)
#999999, #9a9a9a	var(--theme-color-fg-default-shy)
#aaaaaa, #aaa	var(--theme-color-fg-default-shy)
#b8b8b8, #b9b9b9	var(--theme-color-fg-default)
#c4c4c4, #cccccc, #ccc	var(--theme-color-fg-default-contrast)
#d4d4d4, #ddd, #dddddd	var(--theme-color-fg-default-contrast)
#f5f5f5, #ffffff, #fff	var(--theme-color-fg-highlight)

Legacy Brand Colors

If You See	Replace With
#d49517, #fdb314 (orange/yellow)	var(--theme-color-primary)
#f67465, #f89387 (salmon/coral)	var(--theme-color-danger)

---

Part 4: Spacing System

Use consistent spacing based on 4px/8px grid:

4px   // --spacing-1  (tight)
8px   // --spacing-2  (small)
12px  // --spacing-3  (medium-small)
16px  // --spacing-4  (default)
20px  // --spacing-5  (medium)
24px  // --spacing-6  (large)
32px  // --spacing-8  (extra-large)
40px  // --spacing-10
48px  // --spacing-12

---

Part 5: Typography Scale

/* Titles */
24px, weight 600, --theme-color-fg-highlight     // Dialog titles
18px, weight 600, --theme-color-fg-highlight     // Section titles
16px, weight 600, --theme-color-fg-default-contrast // Subsection headers

/* Body */
14px, weight 400, --theme-color-fg-default       // Normal text
14px, weight 400, --theme-color-fg-default-shy   // Secondary text

/* Small */
12px, weight 400, --theme-color-fg-muted         // Captions, hints

---

Part 6: Component Patterns

Use CSS Modules

ComponentName.tsx
ComponentName.module.scss  ← Use this pattern

Standard Component Structure

// ComponentName.module.scss

.Root {
  display: flex;
  flex-direction: column;
  background-color: var(--theme-color-bg-2);
  border: 1px solid var(--theme-color-border-subtle);
  border-radius: 8px;
  overflow: hidden;
}

.Header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 16px 20px;
  border-bottom: 1px solid var(--theme-color-border-subtle);
}

.Title {
  font-size: 18px;
  font-weight: 600;
  color: var(--theme-color-fg-highlight);
  margin: 0;
}

.Content {
  flex: 1;
  min-height: 0;
  overflow-y: auto;
  padding: 20px;
}

.Footer {
  display: flex;
  align-items: center;
  justify-content: flex-end;
  gap: 12px;
  padding: 16px 20px;
  border-top: 1px solid var(--theme-color-border-subtle);
}

Button Patterns

// Primary Button
.PrimaryButton {
  background-color: var(--theme-color-primary);
  color: white;
  border: none;
  border-radius: 6px;
  padding: 10px 20px;
  font-weight: 600;
  cursor: pointer;

  &:hover {
    background-color: var(--theme-color-primary-highlight);
  }

  &:disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }
}

// Secondary Button
.SecondaryButton {
  background-color: var(--theme-color-bg-3);
  color: var(--theme-color-fg-default);
  border: 1px solid var(--theme-color-border-default);
  border-radius: 6px;
  padding: 10px 20px;

  &:hover {
    background-color: var(--theme-color-bg-4);
    color: var(--theme-color-fg-highlight);
  }
}

---

Part 7: Legacy Files to Fix

These files contain hardcoded colors and need cleanup:

High Priority (Most Visible)

• packages/noodl-editor/src/editor/src/styles/popuplayer.css
• packages/noodl-editor/src/editor/src/styles/propertyeditor.css

Medium Priority

• Files in packages/noodl-editor/src/editor/src/views/nodegrapheditor/
• packages/noodl-editor/src/editor/src/views/ConnectionPopup/

Reference Files (Good Patterns)

• packages/noodl-core-ui/src/components/layout/BaseDialog/
• packages/noodl-core-ui/src/components/inputs/PrimaryButton/

---

Part 8: Pre-Commit Checklist

Before completing any UI task, verify:

• No hardcoded hex colors (search for # followed by hex)
• All colors use var(--theme-color-*) tokens
• Spacing uses consistent values (multiples of 4px)
• Hover states defined for interactive elements
• Focus states visible for accessibility
• Disabled states handled
• Border radius consistent (6px buttons, 8px cards)
• No new global CSS selectors that could conflict

---

Quick Grep Commands

# Find hardcoded colors in a file
grep -E '#[0-9a-fA-F]{3,6}' path/to/file.css

# Find all hardcoded colors in editor styles
grep -rE '#[0-9a-fA-F]{3,6}' packages/noodl-editor/src/editor/src/styles/

# Find usage of a specific token
grep -r "theme-color-primary" packages/

---

Last Updated: December 2024