Levels

The energy model has exactly five discrete levels: 100 | 75 | 50 | 25 | 0. Discrete rather than continuous because fewer choices mean less decision fatigue - critical exactly when energy is already low - and because clear boundaries make adaptation rules predictable.

The five levels

Cycle order is descending, wrapping at the bottom: 100 → 75 → 50 → 25 → 0 → 100.

Cognitive profiles

Each level carries a CognitiveProfile describing what the brain can handle there - not what the sidebar should do. Strategies read this to make informed decisions, and different apps can adapt differently from the same profile.

interface CognitiveProfile {
  readonly decisionCapacity: 'high' | 'moderate' | 'low' | 'minimal' | 'none'
  readonly focusDuration: 'extended' | 'moderate' | 'short' | 'minimal' | 'none'
  readonly taskComplexity: 'complex' | 'moderate' | 'routine' | 'simple' | 'consumption'
  readonly interruptionTolerance: 'high' | 'moderate' | 'low' | 'minimal' | 'none'
}

Reading level definitions

import { getEnergyLevels, getEnergyLevel, cycleEnergyLevel, isEnergyLevel } from '@kumbatio/energy-system'

getEnergyLevels() // all five definitions, ordered 100 → 0
getEnergyLevel(50) // { value: 50, key: 'steady', label: 'Steady', description, cognitiveProfile }

cycleEnergyLevel(25) // 0
isEnergyLevel(66) // false - runtime validation for untrusted input

Definitions are deeply frozen. Use label and description directly in your UI instead of re-inventing level names.

Can I customize the levels?

The scale itself is fixed - the values, keys, labels, and cognitive profiles are part of the package contract and cannot be redefined. This is deliberate: a shared, stable vocabulary is what lets strategies, presence maps, CSS attributes, and different apps interoperate.

What you can customize:

• Behavior per level - write your own adaptation strategy; the built-ins are defaults, not mandates.
• Presentation - the headless EnergyIndicator and the level definitions' label/description let you render levels however fits your product.
• External scales - if your existing app uses a different discrete scale (say 100 | 66 | 33 | 0), bridge it with createExternalLevelCompatibility instead of forking the model.