mirror of
https://github.com/The-Low-Code-Foundation/OpenNoodl.git
synced 2026-01-11 23:02:56 +01:00
Working on the editor component tree
This commit is contained in:
Richard Osborne
308
dev-docs/reference/UI-STYLING-GUIDE.md
Normal file
308
dev-docs/reference/UI-STYLING-GUIDE.md
Normal file
@@ -0,0 +1,308 @@
|
||||
# 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:
|
||||
|
||||
```typescript
|
||||
// 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:
|
||||
|
||||
```scss
|
||||
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
|
||||
|
||||
```scss
|
||||
/* 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
|
||||
|
||||
```scss
|
||||
// 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
|
||||
|
||||
```scss
|
||||
// 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
|
||||
|
||||
```bash
|
||||
# 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_
|
||||
Reference in New Issue
Block a user