storybook/design/visual-design.md

# Storybook Editor Visual Design System

> A synthesis of Teenage Engineering's bold minimalism and Dieter Rams' functionalist precision.

## Design Principles

### Core Tenets

1. **Functional First** - Every element serves a purpose. No decoration for decoration's sake.
2. **Grid-Based Precision** - All elements align to an 8px base grid. Spacing is deliberate.
3. **Restrained + Energetic** - Sophisticated aubergine foundation with bold gold accents.
4. **Tactile Clarity** - Interactions feel deliberate. Buttons have weight. Feedback is immediate.
5. **Honest Materials** - Code is monospace. Text is sans-serif. No skeuomorphism.
6. **Long-Lasting** - Timeless aesthetic that won't feel dated in 5 years.

### The Rams x TE Synthesis

| Dieter Rams (Braun) | Teenage Engineering | Our Synthesis |
|---------------------|---------------------|---------------|
| "Less, but better" | Bold, playful color | Minimal structure, bold accents |
| Neutral grays | Signature orange | Aubergine + gold |
| Pure function | Emotional response | Functional with character |
| Unobtrusive | Visual delight | Delightful when needed |
| Grid systems | Grid systems | 8px base grid |

## Color System

### Primary Palette

```
Aubergine Foundation:
├─ aubergine-900  #1a0f1e  Background (darkest)
├─ aubergine-800  #2b1a33  Surface (cards, panels)
├─ aubergine-700  #3d2447  Surface hover
├─ aubergine-600  #4f2e5b  Borders
├─ aubergine-500  #61386f  Subtle highlights
├─ aubergine-400  #805793  Active elements
└─ aubergine-300  #9f76a7  Muted text

Gold Accents:
├─ gold-500       #f4a261  Primary accent (TE orange-gold)
├─ gold-400       #f6b47a  Hover state
└─ gold-300       #f8c594  Pressed state

Supporting:
├─ cream          #fdf8f3  High contrast text
├─ warm-gray-100  #e8e3dd  Secondary text
├─ warm-gray-400  #8b8680  Muted text
└─ warm-gray-700  #4a4845  Disabled elements
```

### Semantic Colors

```
Success:  #6a994e  Muted olive green (validation passed)
Warning:  #f4a261  Gold (reuse accent)
Error:    #d62828  Deep red (parse errors)
Info:     #9f76a7  Light aubergine (hints)
```

### Usage Guidelines

- **Backgrounds**: Always aubergine-900 or aubergine-800
- **Text**: Cream for primary, warm-gray-100 for secondary
- **Accents**: Gold only for interactive elements and key information
- **Borders**: aubergine-600 for subtle division, gold-500 for focus
- **Code**: Syntax highlighting uses muted versions of semantic colors

## Typography

### Typeface Stack

```
UI Text (Sans-Serif):
Primary: Geist, system-ui, -apple-system, sans-serif
Weights: 400 (regular), 500 (medium), 600 (semibold)

Code (Monospace):
Primary: "Monaspace Neon", "Monaspace", monospace
Weights: 400 (regular), 600 (semibold)
Features: Enable 'calt' for texture healing, ligatures
Fallback: "JetBrains Mono", "Fira Code", Consolas, monospace

Headings (Sans-Serif):
Primary: Same as UI but always semibold (600)
```

### Type Scale (8px base grid)

```
Heading 1:  24px / 32px  semibold  (Panel titles)
Heading 2:  20px / 28px  semibold  (Section headers)
Heading 3:  16px / 24px  semibold  (Subsections)

Body:       14px / 20px  regular   (Default text)
Body Small: 12px / 16px  regular   (Secondary info)
Caption:    11px / 16px  regular   (Labels, metadata)

Code:       13px / 20px  regular   (Monospace content)
```

### Guidelines

- **Line Height**: 1.4–1.6 for readability
- **Letter Spacing**: Default for body, +0.02em for labels/captions
- **Hierarchy**: Size + weight + color (don't rely on size alone)
- **Monospace**: Only for code, file paths, and data values

## Spacing System

### 8px Base Grid

```
Micro:   4px   (Icon padding, tight spacing)
Small:   8px   (Default gap between related elements)
Medium:  16px  (Section spacing)
Large:   24px  (Panel padding)
XLarge:  32px  (Major section separation)
XXLarge: 48px  (Page margins, hero spacing)
```

### Application

- All element sizes divisible by 8px
- Padding and margins follow the scale above
- Icons are 16px or 24px
- Buttons have 8px vertical padding, 16px horizontal
- Panel padding is 24px

## Component Patterns

### Buttons

```
Primary (Gold):
├─ Background: gold-500
├─ Text: aubergine-900 (dark text on light button)
├─ Padding: 8px 16px
├─ Border Radius: 4px
├─ Hover: gold-400
└─ Active: gold-300

Secondary (Ghost):
├─ Background: transparent
├─ Border: 1px solid aubergine-600
├─ Text: cream
├─ Hover: aubergine-700 background
└─ Active: aubergine-600 background

Tertiary (Text Only):
├─ Background: transparent
├─ Text: gold-500
├─ Hover: gold-400
└─ Underline on hover
```

### Input Fields

```
Text Input:
├─ Background: aubergine-800
├─ Border: 1px solid aubergine-600
├─ Text: cream
├─ Placeholder: warm-gray-400
├─ Focus: Border gold-500, glow 0 0 0 2px gold-500/20%
├─ Padding: 8px 12px
└─ Border Radius: 4px

Code Input (Textarea):
├─ Background: aubergine-900
├─ Font: JetBrains Mono 13px
├─ Padding: 16px
└─ Syntax highlighting with muted semantic colors
```

### Panels/Cards

```
Surface:
├─ Background: aubergine-800
├─ Border: 1px solid aubergine-600
├─ Border Radius: 8px
├─ Padding: 24px
└─ Shadow: 0 2px 8px rgba(0,0,0,0.3)

Nested Surface:
├─ Background: aubergine-700
└─ Same border/radius but lighter
```

### Lists

```
File List / Tree:
├─ Item height: 32px (divisible by 8)
├─ Hover: aubergine-700 background
├─ Selected: aubergine-600 + gold-500 left border (4px)
├─ Text: cream for name, warm-gray-400 for metadata
└─ Indent: 16px per level

Data List:
├─ Row height: 40px
├─ Alternating backgrounds: aubergine-800 / aubergine-750
├─ Border: 1px solid aubergine-600 between rows
└─ Hover: gold-500/10% overlay
```

### Status Indicators

```
Validation Badge:
├─ Success: 20px circle, green background, white checkmark
├─ Error: 20px circle, red background, white X
├─ Warning: 20px circle, gold background, dark !
└─ Position: Top-right corner of validated element

Loading Spinner:
├─ Size: 16px or 24px
├─ Color: gold-500
├─ Animation: Smooth rotation, 1s duration
└─ Use sparingly (only for async operations)
```

## Layout Architecture

### Grid System

```
Base Grid: 8px
Columns: 12 or 24 column system
Gutter: 16px
Max Width: 1600px (ultra-wide consideration)
```

### Panel Proportions

```
Three-Column Layout (File Browser | Editor | Inspector):
├─ File Browser: 240px–320px (fixed, resizable)
├─ Editor: Flex-grow (takes remaining space)
└─ Inspector: 280px–400px (fixed, resizable)

Two-Column Layout (File Browser | Editor):
├─ File Browser: 240px–320px
└─ Editor: Flex-grow

Diagnostics Panel (Bottom):
├─ Height: 200px–400px (resizable)
└─ Full width
```

### Z-Index Layers

```
1. Base (0):           Background, surfaces
2. Content (1):        Text, images, forms
3. Overlays (10):      Dropdowns, tooltips
4. Modals (100):       Dialogs, confirmations
5. Notifications (1000): Toast messages, alerts
```

## Interaction Design

### Animation Principles

1. **Fast but Noticeable** - 150–200ms for most transitions
2. **Easing**: ease-out for entrances, ease-in for exits
3. **Purpose-Driven** - Animate only to provide feedback or guide attention
4. **Consistent** - Same animation for same action across the app

### Micro-interactions

```
Button Click:
└─ 100ms scale down to 0.98, then return

Hover:
└─ 150ms background color transition

Focus:
└─ Immediate gold border + glow (no delay)

Panel Resize:
└─ Live (no animation) - functional over flashy

Tab Switch:
└─ 200ms fade (crossfade if content changes)
```

### Feedback Patterns

- **Click**: Immediate visual response (scale/color change)
- **Hover**: Subtle background change (150ms transition)
- **Success**: Green flash + success icon (500ms)
- **Error**: Red border pulse + shake animation (300ms)
- **Loading**: Gold spinner appears after 300ms delay (don't flash for quick ops)

## Accessibility

### Contrast Ratios

- **Body text (cream on aubergine-900)**: 15.2:1 (AAA)
- **Secondary text (warm-gray-100 on aubergine-900)**: 11.8:1 (AAA)
- **Gold accent on aubergine-900**: 7.1:1 (AA Large)
- **Buttons**: Ensure 4.5:1 minimum

### Keyboard Navigation

- **Tab order**: Logical, follows visual layout
- **Focus indicators**: Gold border + glow (always visible)
- **Shortcuts**: Display in tooltips, use standard conventions
- **Escape**: Always closes modals/dialogs

### Screen Readers

- Semantic HTML where possible
- ARIA labels for custom components
- Status announcements for validation/errors
- Descriptive button text (no "click here")

## Icon System

### Style

- **Outline style** (not filled) - more Rams than TE
- **Stroke width**: 1.5px
- **Sizes**: 16px, 24px (following grid)
- **Color**: Inherits text color unless accent needed

### Common Icons

```
Navigation:
├─ Folder (closed/open)
├─ File
├─ Search
├─ Settings
└─ Home

Actions:
├─ Plus (add)
├─ X (close/remove)
├─ Check (confirm)
├─ Edit (pencil)
└─ Save (disk or checkmark)

States:
├─ Success (checkmark circle)
├─ Error (X circle)
├─ Warning (! triangle)
└─ Info (i circle)
```

## Dark Mode (Primary Mode)

The aubergine palette is designed dark-first. Light mode is not planned for v1, but if needed:

```
Light Mode Palette (Future):
├─ Background: cream (#fdf8f3)
├─ Surface: warm-gray-100 (#f5f1ec)
├─ Text: aubergine-900
├─ Accent: Slightly deeper gold (#e89350)
└─ Borders: warm-gray-400
```

## Responsive Considerations

### Breakpoints

```
Compact:  < 1024px  (Single panel focus mode)
Standard: 1024–1440px (Two panels)
Wide:     > 1440px  (Three panels comfortable)
```

### Adaptive Layout

- **< 1024px**: File browser as overlay/drawer
- **1024–1440px**: Two-panel default (browser + editor)
- **> 1440px**: Three-panel comfortable

## Implementation Notes

### Iced Styling

```rust
// Example theme structure
pub struct StorybookTheme {
    pub palette: Palette,
    pub spacing: Spacing,
    pub typography: Typography,
}

pub struct Palette {
    pub aubergine_900: Color,
    pub gold_500: Color,
    // etc.
}
```

### File Organization

```
storybook-editor/src/
├─ theme/
│  ├─ mod.rs         (Theme struct)
│  ├─ colors.rs      (Color constants)
│  ├─ typography.rs  (Font definitions)
│  └─ components.rs  (Component styles)
├─ components/
│  ├─ button.rs
│  ├─ input.rs
│  └─ panel.rs
└─ ui/
   └─ (Application views)
```

## References

- **Teenage Engineering**: Bold minimalism, grid precision, playful accents
- **Dieter Rams**: "Less but better", functionalism, longevity
- **Apple HIG**: Clarity, depth, deference
- **Linear**: Modern dev tool aesthetic
- **Figma**: Panel-based interface patterns

---

*Version 1.0 - Initial design system for Storybook Editor*