npm package: @rhavenside/cadence
Description: Rules, not effects. A framework for consistent animation and color behavior.
Author: rhavenside
Latest version: 1.0.1

# Cadence Framework

**Rules, not effects. Consistency in feeling, not appearance.**

Cadence defines rules for animation and color, not preset effects. It ensures consistency in feeling across an entire system, not just visual consistency.

## Core Principles

1. **Motion is Communication**  
   Every animation says something. If it says nothing, it's noise.

2. **Color Amplifies Meaning**  
   Color without context is decoration. With context, it's a signal.

3. **Time is a Design Material**  
   Milliseconds are as relevant as pixels.

4. **Repetition Builds Trust**  
   Same states must always behave the same way.

## Framework Goal

Cadence defines rules, not effects.

**Not:**
- "Fade in from left"
- "Bounce animation"
- "Beautiful color palette"

**But:**
- How fast may something appear?
- When is movement allowed?
- Which color changes feel calm, which alarming?
- How do color and motion behave together?

## Core Assumption

Humans don't perceive movement and color separately.

A fast color change feels more aggressive than the same change done slowly.

Cadence treats animation + color as coupled systems.

## Installation

### As npm package

```bash
npm install @rhavenside/cadence
```


## Project Structure

```
baseline-cadence/
├── scss/
│   ├── _variables.scss          # Time classes, color zone variables
│   ├── _motion-intentions.scss   # Mixins for Instant, Response, Transition, Ambient
│   ├── _time-classes.scss        # Time class definitions
│   ├── _motion-character.scss    # Motion character (Linear, Soft, Firm, Sharp)
│   ├── _color-zones.scss         # Color zone structure (Base, Content, Focus, Accent, Signal)
│   ├── _color-transitions.scss   # Allowed color transitions
│   ├── _coupling-rules.scss      # Coupling rules: Color × Motion
│   ├── _states.scss              # State model (Neutral, Hover, Active, etc.)
│   ├── palettes/                 # Color palette variants
│   │   ├── _palette-default.scss # Default intensity palette
│   │   ├── _palette-subtle.scss  # Subtle (low intensity) palette
│   │   └── _palette-vibrant.scss # Vibrant (high intensity) palette
│   └── cadence.scss              # Main import file
├── src/
│   ├── components/               # React demo components
│   └── styles/                    # Application styles
└── README.md
```

## Usage

### Import Cadence

If installed via npm:

```scss
@import '@rhavenside/cadence/scss/cadence';
```

Or if using a local path:

```scss
@import 'path/to/cadence';
```

### Define Time Classes

```scss
$time-immediate: 0ms;
$time-short: 150ms;
$time-medium: 300ms;
$time-long: 500ms;
```

### Define Color Zones

You can either use a predefined palette or define your own colors:

**Option 1: Use a predefined palette**

```scss
// Import a palette before importing cadence
@import '@rhavenside/cadence/scss/palettes/palette-default';
@import '@rhavenside/cadence/scss/cadence';
```

Available palettes:
- `palette-default` - Medium intensity, balanced colors
- `palette-subtle` - Low intensity, muted colors
- `palette-vibrant` - High intensity, bold colors

**Option 2: Define your own colors**

```scss
$color-zone-base: #f5f5f5;
$color-zone-content: #333333;
$color-zone-focus: #0066cc;
$color-zone-accent: #ff9900;
$color-zone-signal-success: #00aa00;
$color-zone-signal-warning: #ffaa00;
$color-zone-signal-error: #cc0000;
```

### Use Motion Intentions

```scss
.button {
  @include motion-response();
  // Response: Direct answer to user action
  // Allowed time: Immediate or Short
  // Allowed character: Soft, Firm, or Linear
}
```

### Use States

```scss
.button {
  @include state-neutral();
  
  &:hover {
    @include state-hover();
  }
  
  &:active {
    @include state-active();
  }
  
  &.error {
    @include state-error();
  }
}
```

## Motion Intentions

Every animation must have exactly one intention.

### Instant
No transition. State appears immediately.  
**Use for:** System reactions, errors, security states  
**Allowed time:** Immediate only  
**Allowed character:** Any (typically Linear or Sharp)

### Response
Direct answer to a user action.  
**Use for:** Click, focus, toggle  
**Allowed time:** Immediate or Short  
**Allowed character:** Soft, Firm, or Linear

### Transition
Switch between two stable states.  
**Use for:** Page changes, mode switches  
**Allowed time:** Short, Medium, or Long  
**Allowed character:** Soft or Firm

### Ambient
Background movement without user reference.  
**Use for:** Loading indicators, subtle status signals  
**Allowed time:** Short, Medium, or Long (never Immediate)  
**Allowed character:** Soft or Linear (never Sharp)

## Time Classes

Time windows for animations:

- **Immediate** - Below conscious perception threshold
- **Short** - Noticeable but not disruptive
- **Medium** - Consciously perceivable
- **Long** - Only for rare, significant transitions

### Intention → Time Class Mapping

- **Instant:** Only Immediate
- **Response:** Immediate or Short
- **Transition:** Short, Medium, or Long
- **Ambient:** Short, Medium, or Long (never Immediate)

## Motion Character

Easing functions for different motion characters:

- **Linear** - Technical, neutral
- **Soft** - Calm, human
- **Firm** - Clear, decisive
- **Sharp** - Warning, harsh

**WARNING:** Sharp character is never allowed with Signal colors or Ambient intention.

## Color Zones

Colors exist in zones, not as individual values:

- **Base** - Background, surfaces
- **Content** - Text, primary information
- **Focus** - Active interaction
- **Accent** - Emphasis, secondary
- **Signal** - Success, warning, error

**WARNING:** Signal colors must never be used for decoration or non-semantic purposes.

### Allowed Transitions

- Base → Focus
- Focus → Accent
- Accent → Signal
- Focus → Base

### Forbidden Transitions

- Base → Signal (must use intermediate zones)
- Content → Signal (must use intermediate zones or instant change)

## Coupling Rules: Color × Motion

### Intensity Rule

The stronger the color, the calmer the motion.

- Signal colors → only Soft or Firm
- No Sharp motion with Signal colors
- Fast motion → only Base or Accent

### Perception Rule

Never two strong stimuli simultaneously.

**Forbidden:**
- Strong color contrast + long animation
- Signal color + Bounce / Overshoot
- Color change + direction change simultaneously

## State Model

Cadence defines exactly these states:

- **Neutral** - Default state
- **Hover** - Pointer over element
- **Active** - Element is being activated
- **Focused** - Element has keyboard focus
- **Disabled** - Element is disabled
- **Success** - Success state
- **Warning** - Warning state
- **Error** - Error state

Each state defines:
- Allowed color zone
- Allowed motion intention
- Allowed time class

## Audit Process

The audit answers one question: Does the behavior of color and motion conform to Cadence rules?

### Audit Levels

1. **Intention Audit** - Why is this moving?
2. **Time Audit** - Does the duration match the intention?
3. **Color Audit** - Is the element in the correct color zone?
4. **Coupling Audit** - Are color and motion simultaneously appropriate?
5. **State Audit** - Do same states always behave the same?

### Audit Results

- **Conformant** - All rules are followed
- **Non-conformant - Correctable** - Rules violated but can be corrected
- **Non-conformant - Rule Break** - Hard rule violation, must be fixed

## Explicitly Forbidden

1. Animation without intention
2. Different animations for same states
3. Signal colors as decoration
4. Movement that demands attention without meaning
5. Simultaneous change of color, size, and position
6. Endless animations outside of Ambient
7. Different durations for same actions
8. "Feeling-based" adjustments without rule reference
9. Component-specific special animations
10. "Just make it pretty"

## Color Palettes

Cadence includes three predefined color palettes with different intensity variants. All palettes follow Cadence zone rules and maintain proper relationships between zones.

### Default Palette
Medium intensity, balanced colors suitable for most applications.

```scss
@import '@rhavenside/cadence/scss/palettes/palette-default';
```

### Subtle Palette
Low intensity, muted colors suitable for minimal interfaces.

```scss
@import '@rhavenside/cadence/scss/palettes/palette-subtle';
```

### Vibrant Palette
High intensity, bold colors suitable for dynamic interfaces.

```scss
@import '@rhavenside/cadence/scss/palettes/palette-vibrant';
```

All palettes define:
- Base zone (backgrounds, surfaces)
- Content zone (text, primary information)
- Focus zone (active interaction)
- Accent zone (emphasis, secondary)
- Signal zones (success, warning, error)

## License

MIT