engine/theme_spec library

The theme data model (spec §5.1; docs/m3-theme-engine-design.md).

A ThemeSpec is a pure function of (seed, family, engineVersion , accessible). Every field is an integer, a bool, a string or an enum, so toJson and ThemeSpec.stableHash are identical on every run and platform. Colours are opaque-or-translucent int ARGB (0xAARRGGBB). Dimensions are integers in hundredths of a dp (…Cdp), fractions in thousandths (…Permille), angles in tenths of a degree (…Tenths).

Enums serialise by name: never rename an enum value used here (add new ones instead), or shared themes stop decoding.

Classes

BackgroundSpec
Background (spec §5.1 Background).
EffectsSpec
Optional ambient effect (spec §5.1 Effects). M3 families use none. Effects never animate behind the display text (spec §5.4).
KeyColors
Face, label and edge colours of one key role.
KeyShapeSpec
Key outline (spec §5.1 KeyShape).
KeyStyleSpec
How key faces are drawn (spec §5.1 KeyStyle).
MotionSpec
Per-theme motion tokens (spec §5.1 Motion; motion brief §2.3, §2.6). Integers only. Runtime adjustments (Reduce Motion, input amplitude, battery tier) are applied by the render layer and never stored here.
Palette
Every colour role of a theme, as final quantised ARGB (what the guardrails checked).
SpringToken
Mass-1 spring, integer-encoded so hashing stays bit-exact (motion brief §2.6). Convert with SpringDescription.withDampingRatio(mass: 1, stiffness: k, ratio: zetaPermille / 1000) in the render layer.
SpringTokens
The shared spring scale (motion brief §2.1), as integers.
ThemeSpec
A complete theme (spec §5.1). Immutable; == compares every field; hashCode is stableHash, identical on every run and platform.
TypeSpec
Typography (spec §5.1 Typography). Font ids are the stable strings of BundledFont.id (lib/themes/render/fonts.dart), see FontIds.

Enums

BackgroundKind
Background kind (spec §5.1 Background).
BackgroundPattern
Overlay pattern for BackgroundKind.pattern (or on top of gradients).
EffectKind
Optional ambient effect (spec §5.1 Effects). M3 ships none.
EntryStyle
Display glyph entry (motion brief §2.3).
ImpactStyle
iOS impact style (Android maps intents; motion brief §3).
KeyGroup
The four key colour groups (see KeyRole → group mapping in the resolver: digit/decimal/sign → digit; operator → operator; equals → equals; everything else → function).
KeyShapeKind
Key outline geometry (spec §5.1 KeyShape; motion brief §6.3).
KeyStyleKind
How a key face is drawn (spec §5.1 KeyStyle). Descriptive: renderers are chosen by family, never by style. glass also marks Y2K / Frutiger Aero's opaque gel and chrome keys; outlined is drawn by Neo-brutalism (with a hard shadow) and Paper & ink (sketched, without one).
M3eShape
Material 3 Expressive shape-library ids (material_new_shapes MaterialShapes), used when KeyShapeKind.m3eMorph.
MotionScheme
Which spatial spring scale a family's UI motion uses.
OperatorCue
A non-colour cue that distinguishes operator / = keys from digits (spec §5.4). none means the colour/contrast rule alone must pass. A family that records any other cue verifies it in its own validator.
PressFx
Extra press effect (motion brief §2.6).
PressVerb
Press verb at p = 1 (motion brief §2.3, §2.6).
SoundPackId
Sound pack ids (research sound.md §1; motion brief §2.3).
ThemeBrightness
Light or dark base.
ThemeFamily
Theme families. id is the stable 5-bit number used in share codes and JSON — never use index. Ids 30 (reserved) and 31 (hero, see share_code.dart) are never families.
ThemeVariant
Generated, hand-crafted hero, or device-derived variant.

Functions

argbFromHex(Object? hex) → int
"aarrggbb" (or "#aarrggbb") → 0xAARRGGBB.
argbToHex(int argb) → String
0xAARRGGBB → "aarrggbb".
stableHash32(String s) → int
FNV-1a-32 over the UTF-8 encoding of s (32-bit safe on the web).