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

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:

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

Or if using a local path:

@import 'path/to/cadence';

Define Time Classes

$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

// 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

$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

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

Use States

.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.

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

Subtle Palette

Low intensity, muted colors suitable for minimal interfaces.

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

Vibrant Palette

High intensity, bold colors suitable for dynamic interfaces.

@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