Package Exports

@v1b3x0r/mds-core

Readme

Material Definition System (MDS) v3.0

Think in materials, not CSS properties

Status: ✅ v3.0 | Published to npm | Zero dependencies | CDN available Reality: System works perfectly. Built-in materials (@mds/glass, @mds/paper, @mds/liquid-silicone) are minimal/subtle because I'm not good at visual design. You Can: Create much better-looking materials easily - see guide below!

What is MDS?

Material Definition System is a JavaScript library that lets you declare materials through JSON manifests instead of writing repetitive CSS properties.

Traditional CSS approach:

<div class="bg-white/10 backdrop-blur-xl border border-white/20 shadow-2xl">
  Content
</div>

MDS approach:

<div data-material="@mds/glass">
  Content
</div>

Quick Start

Installation

npm (Recommended)

npm install @v1b3x0r/mds-core

import '@v1b3x0r/mds-core'
// or
import MaterialSystem from '@v1b3x0r/mds-core'

CDN (unpkg)

<!-- UMD (ready to use) -->
<script src="https://unpkg.com/@v1b3x0r/mds-core@latest/dist/mds.umd.js"></script>

<!-- ESM (for modules) -->
<script type="module">
  import MaterialSystem from 'https://unpkg.com/@v1b3x0r/mds-core@latest/dist/mds.esm.js'
</script>

CDN (jsDelivr)

<!-- UMD -->
<script src="https://cdn.jsdelivr.net/npm/@v1b3x0r/mds-core@latest/dist/mds.umd.js"></script>

<!-- ESM -->
<script type="module">
  import MaterialSystem from 'https://cdn.jsdelivr.net/npm/@v1b3x0r/mds-core@latest/dist/mds.esm.js'
</script>

Basic Usage

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/@v1b3x0r/mds-core@latest/dist/mds.umd.js"></script>
</head>
<body>
  <!-- Use built-in materials -->
  <div data-material="@mds/glass">Glass element</div>
  <div data-material="@mds/paper">Paper element</div>

  <script>
    // Load materials from manifests
    async function loadMaterials() {
      const [glass, paper] = await Promise.all([
        fetch('https://unpkg.com/@v1b3x0r/mds-core@latest/manifests/@mds/glass.mdm.json').then(r => r.json()),
        fetch('https://unpkg.com/@v1b3x0r/mds-core@latest/manifests/@mds/paper.mdm.json').then(r => r.json())
      ])

      MaterialSystem.register('@mds/glass', glass)
      MaterialSystem.register('@mds/paper', paper)
      MaterialSystem.apply()
    }

    loadMaterials()
  </script>
</body>
</html>

Live Demo

Interactive Demo → - Runtime Material Switcher

Experience the material system with tactile physics in action:

Liquid Silicone with elastic deformation (K=22, D=18 spring simulation)
Real-time material switching - Change materials without page reload
Tactile response - Press and drag to feel elastic deformation (no positional movement)
Different material types - Switch between silicone (tactile), glass (static), and paper (static)
60fps animations - Smooth, GPU-accelerated transforms

Try pressing the button and moving your pointer to see the tactile simulation in action!

What Works vs What Needs Your Help

What Works (System is Solid)

The core system is production-ready and battle-tested:

✅ Manifest-driven architecture - JSON to CSS pipeline works perfectly
✅ Theme system - Light/dark auto-switching works flawlessly
✅ State management - Hover, active, focus, disabled all work
✅ Material inheritance - Extend and override works as expected
✅ customCSS support - ~90% CSS property coverage
✅ TypeScript types - Full type safety, zero runtime errors
✅ Zero dependencies - Standalone, no external CSS required
✅ CDN support - Load materials from remote sources (unpkg, jsDelivr)
✅ Published to npm - @v1b3x0r/mds-core

What Needs Creative Designers (I'm Not Good at This Part)

The built-in materials need visual improvement:

⚠️ Visual appeal: @mds/glass and @mds/paper are too subtle/minimal
💡 Reason: I'm a normal nerd guy with diet coke, not a visual designer
🎨 Solution: You can create much better materials! See MATERIAL_GUIDE.md
🛠️ Available: 28+ properties (opacity, blur, shadows, textures) + customCSS for advanced effects

TL;DR: Think of MDS as a "material compiler" - it compiles JSON to CSS perfectly. The sample materials I created are just boring examples. You can make way better ones!

Built-in Materials (Reference Only)

`@mds/glass`

Simplified glass effect - intentionally minimal to serve as a starting point

Visual: Very subtle (my design skills). Use as reference, create better ones!

`@mds/paper`

Matte paper with subtle noise texture

Visual: Minimal contrast (again, not my strength). You can do better!

What You Can Build (Beyond My Boring Defaults)

The built-in materials are intentionally minimal, but with 28+ properties + customCSS, you can create stunning effects:

Advanced Glass Effect

{
  "name": "dramatic-glass",
  "optics": {
    "blur": "40px",
    "saturation": "200%",
    "brightness": "130%",
    "tint": "rgba(255, 255, 255, 0.2)"
  },
  "surface": {
    "radius": "16px",
    "shadow": [
      "0 8px 32px rgba(0, 0, 0, 0.3)",
      "inset 0 1px 0 rgba(255, 255, 255, 0.5)"
    ]
  }
}

Neumorphic Material

{
  "name": "neumorphic",
  "optics": { "opacity": 1 },
  "surface": { "radius": "20px" },
  "customCSS": {
    "background": "linear-gradient(145deg, #e6e6e6, #ffffff)",
    "box-shadow": "20px 20px 60px #d9d9d9, -20px -20px 60px #ffffff"
  }
}

Animated Gradient

{
  "name": "gradient-animated",
  "surface": { "radius": "12px" },
  "customCSS": {
    "background": "linear-gradient(270deg, #ff0080, #7928ca, #0070f3)",
    "background-size": "600% 600%",
    "animation": "gradient 8s ease infinite"
  }
}

See MATERIAL_GUIDE.md for 7 complete examples and all 28+ properties.

Creating Custom Materials

See MATERIAL_GUIDE.md for comprehensive documentation on:

All 28+ available properties
Complete examples (beginner to advanced)
Validation rules and common mistakes
customCSS field for CSS experts
Theme and state variations

Quick example:

{
  "name": "my-material",
  "optics": {
    "opacity": 0.95,
    "tint": "#ffffff"
  },
  "surface": {
    "radius": "12px",
    "border": "1px solid rgba(255, 255, 255, 0.2)",
    "shadow": "0 8px 32px rgba(0, 0, 0, 0.1)"
  },
  "states": {
    "hover": {
      "optics": { "opacity": 1 }
    }
  }
}

API Reference

`MaterialSystem.register(name, material)`

MaterialSystem.register('@mds/custom', {
  optics: { tint: '#ff0000' },
  surface: { radius: '8px' }
})

`MaterialSystem.registerFromManifest(manifest)`

const manifest = await fetch('./my-material.mdm.json').then(r => r.json())
MaterialSystem.register(manifest.name, manifest)

`MaterialSystem.extend(name, baseName, overrides)`

Extend existing material.

MaterialSystem.extend('glass-blue', '@mds/glass', {
  optics: { tint: '#0066ff' }
})

`MaterialSystem.setTheme(theme)`

Set theme mode.

MaterialSystem.setTheme('dark')   // Force dark
MaterialSystem.setTheme('light')  // Force light
MaterialSystem.setTheme('auto')   // Follow system preference

`MaterialSystem.getTheme()`

Get current resolved theme ('light' or 'dark').

const theme = MaterialSystem.getTheme()  // 'light' | 'dark'

`MaterialSystem.apply(root?)`

Apply materials to elements (automatically called on DOM changes).

MaterialSystem.apply()  // Apply to document
MaterialSystem.apply(document.querySelector('#container'))  // Apply to subtree

Interop API (for External Behavior Engines)

New in v3: Methods for behavior libraries (like UICP) to integrate with MDS.

`MaterialSystem.getMaterial(element)`

Get material definition for element.

const material = MaterialSystem.getMaterial(element)
if (material) {
  console.log('Material:', material.name)
}

`MaterialSystem.getState(element)`

Get current visual state.

const state = MaterialSystem.getState(element)  // 'base' | 'hover' | 'press' | etc.

`MaterialSystem.setState(element, state)`

Manually set visual state (for behavior engines to drive material state).

// Behavior engine can programmatically transition visual states
MaterialSystem.setState(element, 'hover')
MaterialSystem.setState(element, 'press')

`MaterialSystem.hasTactilePhysics(element)`

Check if element has tactile physics enabled.

if (MaterialSystem.hasTactilePhysics(element)) {
  // Element has physics - behavior engine can respond accordingly
}

`MaterialSystem.getPhysicsParams(element)`

Get physics parameters (for behavior engines to match feel).

const params = MaterialSystem.getPhysicsParams(element)
if (params) {
  console.log('Elasticity:', params.elasticity)
  console.log('Viscosity:', params.viscosity)
  // Behavior engine can use these to match movement to deformation feel
}

Architecture

┌─────────────────┐
│  JSON Manifest  │  ← Material definition (.mdm.json)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  MaterialSystem │  ← Runtime engine (25KB ESM, 12KB UMD gzipped)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   DOM Element   │  ← data-material="name"
└─────────────────┘

File Structure

@v1b3x0r/mds-core/
├── dist/
│   ├── mds.esm.js       # ESM bundle (25KB gzipped)
│   ├── mds.umd.js       # UMD bundle (12KB gzipped)
│   └── index.d.ts       # TypeScript types
├── manifests/@mds/
│   ├── glass.mdm.json   # Built-in glass material
│   └── paper.mdm.json   # Built-in paper material
└── package.json

Architecture Philosophy

Material vs Behavior: Separation of Concerns

MDS v3 clearly separates two architectural layers:

Material Layer (MDS Responsibility)

What it is: Visual appearance + tactile response (HOW it feels to touch)

Includes:

Optics: Visual properties (opacity, tint, blur, saturation, etc.)
Surface: Geometry properties (radius, border, shadows, texture)
Tactile Simulation: Deformation response to pointer events (elastic, viscous, friction)
- Example: Liquid silicone deforms (skew/scale) when pressed, then springs back
- Critical: Tactile physics NEVER moves the element positionally (no translate)

Example:

<div data-material="@mds/liquid-silicone">
  <!-- Material defines: "This looks like translucent silicone and deforms elastically when pressed" -->
</div>

External Interaction Layer (UICP/Other Libraries)

What it is: Functional behavior (WHAT the element does, WHERE it moves)

Includes:

Positional dragging (translate across screen)
Drawer/modal mechanics
Scroll behaviors
Click/gesture handlers
Layout changes

Example:

<div data-material="@mds/liquid-silicone" data-behavior="drawer">
  <!-- Material: Visual + deform response -->
  <!-- Behavior: Drawer slide-out mechanics (external library handles this) -->
</div>

Why This Separation?

Before (v2): Built-in drag system caused conflicts

MDS had positional drag logic (transform: translate)
External physics had tactile deform logic (transform: skew/scale)
Result: Race condition, elements "dragging across screen"

After (v3): Clean architectural boundary

MDS: Handles visual + tactile substrate (deformation only)
External layer: Handles functional interactions (movement, gestures)
Result: No conflicts, each layer has clear responsibility

Interop API for Behavior Engines

MDS exposes public methods for external behavior systems to integrate:

// Query material state
MaterialSystem.getMaterial(element)      // Get material definition
MaterialSystem.getState(element)         // Get current visual state
MaterialSystem.hasTactilePhysics(element) // Check if has physics
MaterialSystem.getPhysicsParams(element) // Get physics parameters

// Drive material state
MaterialSystem.setState(element, 'hover') // Set visual state programmatically

Use case: Behavior engine can query tactile parameters to match its movement feel to the material's deformation feel.

Philosophy

Think in Materials, Not Properties

Traditional CSS thinking:

"I need backdrop-filter: blur(20px)"
"Add opacity: 0.8"
"Box-shadow: 0 8px 32px..."

MDS thinking:

"This is glass"
"This is paper"
"This should feel like metal"

Separation of Concerns

Layer	Responsibility	Example
HTML	Structure	`<div>`, `<button>`
CSS/Tailwind	Layout/Typography	`px-4`, `flex`, `text-lg`
MDS	Material Properties	`data-material="glass"`

Do NOT mix:

<!-- ❌ Bad - visual properties in CSS -->
<div class="bg-white/10 backdrop-blur-xl" data-material="@mds/glass">

<!-- ✅ Good - clean separation -->
<div class="px-4 py-2 rounded-xl" data-material="@mds/glass">

Advanced Usage

Custom CSS for Experts

For CSS properties not covered by optics/surface/behavior, use customCSS:

{
  "name": "advanced-material",
  "optics": { "tint": "#fff" },
  "customCSS": {
    "clip-path": "polygon(0 0, 100% 0, 100% 95%, 50% 100%, 0 95%)",
    "mix-blend-mode": "multiply",
    "filter": "drop-shadow(0 0 10px rgba(0,0,0,0.5))"
  }
}

Coverage: ~90% of CSS properties (vs ~40-50% without customCSS)

Limitations: No pseudo-elements, @keyframes, or dynamic values

See MATERIAL_GUIDE.md for full documentation.

Built-in Material Limitations (Not System Limitations)

What	Built-in Materials	What You Can Build
Visual contrast	Too subtle (my fault)	High contrast with proper opacity/shadows
Dramatic effects	Minimal (boring defaults)	Unlimited with 28+ properties
Advanced CSS	Basic only (@mds/glass)	~90% CSS coverage with customCSS
Neumorphism	Not included	Easy with customCSS
Animated gradients	Not included	Easy with customCSS + keyframes
Dynamic lighting	CSS limitation*	Requires WebGL (not MDS's job)
Mouse tracking	CSS limitation*	Requires custom JS (not MDS's job)

Key point: The system supports advanced effects. My sample materials just happen to be boring.

* These are CSS/DOM limitations, not MDS limitations. MDS does what CSS can do.

FAQ

Why are @mds/glass and @mds/paper so hard to see?

Honest answer: I'm a systems engineer, not a visual designer. I focused on making the architecture solid, but my design skills are... not great.

The good news: You don't have to use my materials! The system supports:

28+ visual properties: opacity, tint, blur, saturation, brightness, contrast, shadows, textures, borders, radius
customCSS: ANY CSS property not covered by the core 28 properties
Full state control: hover, active, focus, disabled - each can have different styles
Theme variants: Automatic light/dark mode with custom overrides

Check MATERIAL_GUIDE.md to create materials that look way better than mine.

Is this production-ready?

System: ✅ Yes

Architecture is solid (manifest to runtime to DOM)
TypeScript types are correct and complete
Theme system works flawlessly
State management tested
Zero known bugs
Published to npm with zero dependencies
CDN available (unpkg, jsDelivr)
CI/CD setup with GitHub Actions

Built-in materials: ⚠️ Use for reference only, create your own for production

Think of it like: React ships with boring default styles, but you build beautiful UIs with it. Same here - MDS is the compiler, you bring the creativity.

Can I use this in my project right now?

Yes! The package is:

✅ Published to npm as @v1b3x0r/mds-core
✅ Available via CDN (unpkg, jsDelivr)
✅ Zero runtime dependencies
✅ TypeScript types included
✅ Browser-tested (Chrome 90+, Firefox 88+, Safari 14+)

Just create your own materials (don't use @mds/glass/@mds/paper as-is) and follow the MATERIAL_GUIDE.md for best practices.

Browser Support

Chrome/Edge 90+
Firefox 88+
Safari 14+

Required CSS features:

backdrop-filter (glass materials)
CSS variables
MutationObserver (dynamic content)

Contributing

I Need Help With Visual Design

The system architecture is solid, but I'm terrible at making things look good. If you're a designer or have good visual taste:

Share your materials:

Create beautiful materials and PR them to /manifests/@community/
Show what's possible with the 28+ properties + customCSS
Help others learn by example

Improve the defaults:

Make @mds/glass and @mds/paper actually visible and usable
Create variants (frosted glass, glossy paper, etc.)
Better shadows, better contrast, better everything

Create examples:

Advanced customCSS usage
Neumorphic designs
Animated materials
Theme-aware materials

Code Contributions

Bug fixes: Always welcome
New features: Open an issue first to discuss
Performance improvements: Appreciated
Documentation: Help make it clearer

The architecture is done. Now it needs creative people to make beautiful things with it!

Package Info

# Install
npm install @v1b3x0r/mds-core

# Package size
- ESM: 25.12 KB (gzipped: 6.64 KB)
- UMD: 12.38 KB (gzipped: 4.53 KB)

# Dependencies: 0
# TypeScript: Included
# CDN: Available (unpkg, jsDelivr)

Documentation

MATERIAL_GUIDE.md - How to create materials (complete reference)
CLAUDE.md - AI assistant context (project state, decisions, future work)
npm package - npm registry page
GitHub repo - Source code

License

MIT © v1b3x0r

Acknowledgments

Built with honesty about limitations. The system architecture is production-ready, but the built-in materials are minimal/subtle due to my lack of visual design skills.

You can build beautiful materials with the 28+ properties + customCSS support. The system just needs creative designers to show what's possible!

For true photorealistic materials with dynamic lighting, consider:

Three.js (WebGL-based)
Babylon.js (PBR materials)

MDS focuses on declarative material definitions for DOM elements - it's a different approach that prioritizes simplicity and ease of use over photorealism.