@shinkofa/tokens

Canonical business token values for the Shinkofa ecosystem — Ki, Wellness, Priority, Energy.

This package is the single source of truth for the values of Shinkofa's cross-cutting business vocabulary: the Ki scale and its difficulty costs, the priority levels and their ordering, the wellness dimensions and their scales, and the energy bands. Apps import these instead of re-declaring constants.

Why this package exists

The business vocabulary was scattered: copied by hand in Michi-Shinkofa, mixed with colors in @shinkofa/ui, implied in @shinkofa/types. Centralising the values here keeps @shinkofa/ui free of Shinkofa-specific business meaning so it can stay publishable as open source (NLNet), and gives every app one place to read the canonical numbers and keys.

Frontier — what goes where

| Package | Owns | Example | |---------|------|---------| | @shinkofa/tokens | Business values: scales, bounds, ordering, i18n keys | KI_SCALE = { min: 0, max: 10 }, PRIORITY_ORDER | | @shinkofa/types | TypeScript shapes: interfaces, unions | interface Task { priority: Priority } | | @shinkofa/ui | Presentation: colors, icons, components | PRIORITY_COLORS, <TaskCard> | | @shinkofa/i18n | Text: FR/EN/ES labels | wellness:ki.executive → "Exécutif" | | @shinkofa/holistic-core (planned) | Logic: budget math, derivation | calculateKiBudget() |

Rule of thumb: a number, a bound, an ordering, or an i18n key is a token → it lives here. A type lives in @shinkofa/types. A color or component lives in @shinkofa/ui. A function that computes something lives in @shinkofa/holistic-core. This package contains zero logic — values only.

Labels are NOT here

Tokens carry an i18n key per value (e.g. KI_I18N_KEYS.executive === 'wellness:ki.executive'), never the translated text. The words live in @shinkofa/i18n. This keeps value and text decoupled and trilingual.

What's inside

| Module | Exports | |--------|---------| | ki | KI_TYPES, KiType, KI_SCALE, KI_DEFAULT_LEVEL, DIFFICULTY_LEVELS, DifficultyLevel, DIFFICULTY_KI_COST, KI_I18N_KEYS | | priority | PRIORITY_LEVELS, Priority, PRIORITY_ORDER, PRIORITY_I18N_KEYS | | wellness | WELLNESS_DIMENSIONS, WellnessDimension, MEAL_QUALITY_SCALE, HYDRATION_SCALE, SPORT_INTENSITY_SCALE, SLEEP_QUALITY_SCALE, WELLNESS_SCALES, WELLNESS_I18N_KEYS | | energy | ENERGY_BANDS, EnergyBand, ENERGY_SCALE, ENERGY_DEFAULT_LEVEL, ENERGY_BAND_I18N_KEYS |

The Priority, KiType, DifficultyLevel, WellnessDimension and EnergyBand types are derived from their value arrays (as const), so the values and the type can never drift apart.

Install

"@shinkofa/tokens": "github:shinkofa/Shinkofa-Shared#main&path=packages/tokens"

Usage

import {
  KI_TYPES,
  KI_SCALE,
  DIFFICULTY_KI_COST,
  PRIORITY_LEVELS,
  PRIORITY_ORDER,
  ENERGY_BANDS,
} from '@shinkofa/tokens';

// Order tasks by canonical priority rank (never hardcode the order)
tasks.sort((a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority]);

// Clamp a check-in value to the canonical Ki scale
const level = Math.min(KI_SCALE.max, Math.max(KI_SCALE.min, raw));

// Default Ki cost for a "complex" task
const cost = DIFFICULTY_KI_COST.complex; // 4

Combine with @shinkofa/i18n to render labels:

import { KI_I18N_KEYS } from '@shinkofa/tokens';
import { useTranslation } from '@shinkofa/i18n';

const { t } = useTranslation();
const label = t(KI_I18N_KEYS.executive); // "Exécutif" / "Executive" / "Ejecutivo"

Scripts

| Command | What | |---------|------| | pnpm build | Bundle CJS + ESM + types (tsup) | | pnpm test | Run the value-invariant tests (vitest) | | pnpm type-check | tsc --noEmit (strict) |

Status

0.1.0 — initial extraction of Ki, Priority, Wellness, Energy tokens.

Consumers still holding hand-copied values (notably Michi-Shinkofa) will migrate to import from here in a dedicated pass; that migration is intentionally separate so each consumer's tests can prove parity on its own.