CalmUI

A calm, intentional UI kit for WinForms applications
"MacOS for operators who deserve dignity"

What is CalmUI?

CalmUI is a comprehensive design system and component library for Windows Forms that brings modern, human-centered UX principles to desktop applications. It transforms traditional WinForms into calm, predictable, and delightful experiences.

Core Principles

• Calm - Breathing room, gentle neutrals, no harsh edges or visual noise
• Intentional - Motion with purpose, no bouncing or flourish
• Local & Sovereign - On your machine, for your mission
• Predictable - Stable regions, consistent hierarchy
• Human - Plain language errors, safest action first

Features

Complete Design System

• 8px spacing system with consistent padding and margins
• Semantic color palette (Red/Yellow/Green/Blue for meaning, grayscale for everything else)
• Typography hierarchy with whispered weights
• Motion timings (200ms slides, 140ms fades, smooth easing)

Form Input Components (11)

• CalmButton - Semantic buttons with hover states
• CalmTextBox - Rounded inputs with focus rings
• CalmDropdown - Semantic dropdown with focus states
• CalmCheckbox - Animated checkboxes with grouping
• CalmRadioButton - Circular radio buttons with groups
• CalmToggleSwitch - iOS-style sliding toggles
• CalmDatePicker - Calendar date selection
• CalmTimePicker - Hour/minute time selection
• CalmSearchBox - Search with autocomplete dropdown
• CalmSlider - Single value slider with draggable thumb
• CalmRating - Interactive star ratings

Data Display Components (13)

• CalmProgressBar - Horizontal progress with indeterminate state
• CalmCircularProgress - Circular/ring progress indicator
• CalmBadge - Pill-shaped tags with dismiss option
• CalmNumericBadge - Notification count badges
• CalmBadgeGroup - Badge container with flow layout
• CalmAvatar - User avatars with images or initials
• CalmIcon - Icon display with semantic coloring
• CalmAlert - Inline notification boxes
• CalmBanner - Page-level message banners
• PromptCard - Cognitive guidance cards
• GuidanceStrip - Contextual assistant panel
• BottomStatusBar - Context-aware status display
• ToastNotification - Quiet, auto-dismissing toasts

Layout & Navigation Components (11)

• CalmTabControl - Custom tab control with owner draw
• CalmCloseableTabControl - Tabs with close buttons
• CalmAccordion - Collapsible sections with animation
• CalmAccordionGroup - Accordion container
• CalmSplitContainer - Resizable split panels with visual grip
• CalmCollapsibleSplitContainer - Split container with collapse button
• CalmTooltip - Owner-drawn tooltips with semantic colors
• CalmModal - Draggable overlay dialogs
• CalmBreadcrumb - Navigation breadcrumbs
• LeftRail - Collapsible navigation
• TopCalmBar - Application bar with workspace selector

Specialized Components (6)

• CalmSearchBox - Advanced search with autocomplete
• CalmSlider - Value slider with smooth dragging
• CalmRangeSlider - Min/max range selector
• CalmRating - Star rating component
• CalmBreadcrumb - Navigation hierarchy
• CalmContextMenu - Right-click context menus

Animation Framework

• SlidePanel - Smooth slide transitions
• FadePanel - Content fade effects
• WhySourcesDrawer - Explanatory drawer

Form Templates

• CalmChildForm - Base template for tool windows
• WelcomeOnboardingForm - First-run experience

Messaging System

• HumanMessages - Plain language error dialogs
• ToastNotification - Quiet, auto-dismissing toasts
• CalmAlerts - Helper class for quick alerts
• CalmModals - Helper class for dialogs

Installation

NuGet Package Manager

Install-Package CalmUI

.NET CLI

dotnet add package CalmUI

Package Reference

<PackageReference Include="CalmUI" Version="1.0.0" />

Quick Start

1. Basic Button

Imports CalmUI

Dim saveButton As New CalmButton With {
    .Text = "Save",
    .IsPrimary = True,
    .Width = 130
}

2. Text Input

Dim textBox As New CalmTextBoxContainer With {
    .PlaceholderText = "Enter your text...",
    .Width = 300
}

3. Create a Tool Form

Public Class MyToolForm
    Inherits CalmChildForm
    
    Public Sub New()
        MyBase.New()
        
        Me.FormTitle = "My Tool"
        Me.FormSubtitle = "Description"
        Me.SensitivityLevel = "Internal"
        
        ' Create sections
        Dim section = CreateSection("Section Title")
        Dim textBox As New CalmTextBoxContainer
        Dim group = CreateFieldGroup("Label", textBox, "Helper text")
        
        section.Controls.Add(group)
        group.Dock = DockStyle.Top
        AddSectionToWorkArea(section)
    End Sub
End Class

4. Human Messages

' Instead of MessageBox
HumanMessages.ShowSuccess("Saved", "Your data has been saved successfully.")

' Error with suggested action
HumanMessages.OperationFailed(
    "save data",
    "The database connection was lost.",
    "Retry"
)

' Access denied
HumanMessages.AccessDenied("Edit Settings")

' Confirm destructive action
If HumanMessages.ConfirmDelete("User Account") = DialogResult.OK Then
    ' User confirmed
End If

5. Toast Notifications

ToastNotification.ShowSuccess("Saved successfully")
ToastNotification.ShowError("Connection failed")
ToastNotification.ShowInfo("Searching...")
ToastNotification.ShowCaution("Review required")

Documentation

Theme Access

' Colors
Dim bg = CalmTheme.Colors.GetPrimaryBackground()
Dim blue = CalmTheme.Colors.GetSemantic(SemanticType.Primary)

' Fonts
Dim titleFont = CalmTheme.Typography.GetFont(FontLevel.AppTitle)

' Spacing
Dim padding = CalmTheme.Spacing.PanelInternalPadding

Semantic Types

SemanticType.None          ' Neutral
SemanticType.Destructive   ' Red - dangerous/irreversible
SemanticType.Caution       ' Yellow - review needed
SemanticType.Success       ' Green - safe/complete
SemanticType.Info          ' Blue - informational
SemanticType.Primary       ' Blue - primary action

Creating Sections

' In a CalmChildForm-derived class
Dim section = CreateSection("Section Title")

Dim textBox As New CalmTextBoxContainer
Dim group = CreateFieldGroup(
    "Field Label",
    textBox,
    "Optional helper text"
)

section.Controls.Add(group)
group.Dock = DockStyle.Top
AddSectionToWorkArea(section)

Adding Guidance

GuidanceStrip.AddPrompt(
    "Missing evidence",
    "Add one supporting source before exporting.",
    SemanticType.Caution,
    "Add source...",
    "Remind me later",
    showWhy:=True
)

Design Guidelines

Color Usage

• Everything is grayscale except semantic states
• Red = destructive/blocked/error
• Yellow = caution/review needed
• Green = safe/complete/success
• Blue = continuity/primary action/info

Typography

• Use sentence case everywhere (no ALLCAPS)
• Prefer weight differences over size jumps
• Line height: 1.4-1.5 for readability

Spacing

• Base unit: 8px
• Outer padding: 24px
• Panel padding: 20px
• Section gaps: 24-28px
• Field spacing: 6px (label to field, field to helper)

Motion

• Panel slides: 200ms
• Content fades: 140ms
• Hover transitions: 100ms
• Smooth cubic easing (no bounce)

Error Messages

? Don't: "Error: NullReferenceException at line 42"
? Do: "Couldn't save your data. The connection was lost. [Retry]"

Architecture

CalmUI/
??? Theme/
?   ??? CalmTheme.vb          # Design system foundation
??? Components/
?   ??? CalmButton.vb         # Semantic buttons
?   ??? CalmTextBox.vb        # Rounded inputs
?   ??? CalmControls.vb       # Layout helpers
?   ??? PromptCard.vb         # Guidance cards
?   ??? GuidanceStrip.vb      # Assistant panel
?   ??? LeftRail.vb           # Navigation rail
?   ??? TopCalmBar.vb         # Application bar
?   ??? BottomStatusBar.vb    # Status display
?   ??? AnimatedPanels.vb     # Animation framework
?   ??? WhySourcesDrawer.vb   # Explanatory drawer
??? Forms/
?   ??? CalmChildForm.vb      # Base template
?   ??? WelcomeOnboardingForm.vb
??? Messaging/
    ??? CalmMessageBox.vb     # Human dialogs
    ??? ToastNotification.vb  # Quiet toasts

Examples

See the Examples folder for complete sample applications showing:

• Basic form with controls
• MDI application with shell
• Decision support tool
• Data entry form
• Settings panel

Requirements

• .NET 10.0-windows or later
• Windows Forms enabled
• Visual Studio 2022 or later (for development)

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with ?? for operators who deserve dignity. Inspired by the philosophy:
"MacOS for operators who deserve dignity"

Support

• ?? Full Documentation
• ?? Issue Tracker
• ?? Discussions

---

CalmUI - Bringing calm, intentional design to Windows Forms applications.