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

// 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