Philosophy

Design Principles

1. Svelte 5 Native

MDSV components are built from scratch for Svelte 5, not ported from Svelte 4. This means:

  • Runes everywhere: $state, $derived, $props, $effect
  • Snippets over slots: Type-safe content composition
  • MediaQuery reactivity: Using Svelte 5’s reactive MediaQuery class
  • No legacy syntax: Clean, modern codebase

2. Type Safety First

Every component is written in TypeScript with strict mode enabled:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true
  }
}

This catches bugs at compile time and provides excellent IDE autocomplete.

3. Specification-Driven Development

Each component starts with a detailed specification document that defines:

  • Purpose - Why does this component exist?
  • API - What props, events, and snippets does it expose?
  • Behavior - How does it handle edge cases?
  • Examples - Real-world use cases

Code follows the spec, not the other way around.

4. Test-Driven Quality

Every component includes:

  • Unit tests - Logic and calculations
  • Integration tests - File structure and imports
  • Edge case tests - Validation and error handling

Target: 95+ tests per component with 200+ assertions.

5. Zero Framework Lock-in

Components are distributed as:

  • Source files - Import the .svelte file directly
  • Type definitions - Full TypeScript support
  • Minimal deps - Only peer dependency is Svelte 5

No build step required. No framework magic. Just Svelte components.

Why “MDSV”?

Modern Design SVelte - Components for the modern web, built with Svelte 5.

The name emphasizes:

  • Modern: Uses latest Svelte 5 features
  • Design: Thoughtfully designed APIs
  • Svelte: Purpose-built for Svelte ecosystem

Component Naming

Components follow a simple naming convention:

  • Lowercase package names: @mdsv/ratio, @mdsv/grid
  • PascalCase component names: Ratio, Grid
  • Descriptive prop names: defaultMode, currentMode, onmodeChange

This makes it easy to remember and type-safe to use.

Documentation Philosophy

Caveats vs. Design Decisions

The docs only list true caveats - unavoidable technical limitations:

✅ Include: Browser support gaps, unconfigurable constraints, unavoidable side effects

❌ Exclude: Intentional design decisions, configurable behavior, solvable problems

If something can be fixed or configured, it’s not a caveat - it’s a feature request.

Example-Driven

Every component includes multiple real-world examples:

  • Video Player - Maintaining aspect ratios for media
  • Flashcard App - Enforcing content constraints
  • Dashboard - Responsive layouts

This helps developers understand when and why to use each component.

Future Direction

MDSV will grow to include:

  • Layout components - Grid, Stack, Flex
  • Form components - Input, Select, Checkbox (with validation)
  • Data components - Table, List, Tree
  • Feedback components - Toast, Modal, Dialog
  • Navigation components - Tabs, Breadcrumbs, Pagination

All following the same principles: Svelte 5 native, type-safe, well-tested, and documented.