release: Storybook v0.2.0 - Major syntax and features update
BREAKING CHANGES: - Relationship syntax now requires blocks for all participants - Removed self/other perspective blocks from relationships - Replaced 'guard' keyword with 'if' for behavior tree decorators Language Features: - Add tree-sitter grammar with improved if/condition disambiguation - Add comprehensive tutorial and reference documentation - Add SBIR v0.2.0 binary format specification - Add resource linking system for behaviors and schedules - Add year-long schedule patterns (day, season, recurrence) - Add behavior tree enhancements (named nodes, decorators) Documentation: - Complete tutorial series (9 chapters) with baker family examples - Complete reference documentation for all language features - SBIR v0.2.0 specification with binary format details - Added locations and institutions documentation Examples: - Convert all examples to baker family scenario - Add comprehensive working examples Tooling: - Zed extension with LSP integration - Tree-sitter grammar for syntax highlighting - Build scripts and development tools Version Updates: - Main package: 0.1.0 → 0.2.0 - Tree-sitter grammar: 0.1.0 → 0.2.0 - Zed extension: 0.1.0 → 0.2.0 - Storybook editor: 0.1.0 → 0.2.0
This commit is contained in:
429
design/visual-design.md
Normal file
429
design/visual-design.md
Normal file
@@ -0,0 +1,429 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user