After a long discussion with @kurkle on slack, we came up with a few proposals. I detailed all of them in this Gist so it's easier to review. My preferences: a >> c > b >> d > master (reasons detailed in the Gist):

@etimberg @stockiNail @benmccann @emmcbd (and whoever else is interested): thoughts?

@simonbrunel I had a look to your evaluation. Thanks a lot for the work done!

Comparing with the master implementation, animations is a concept which gatherers collection and properties concepts.
And that's good for me even if in my option these 2 concepts are not so clear to a normal user because it's not clear which properties you can use (apart the properties mentioned in the doc or in the samples). The risk is no user will really use it.

I have doubts about when animation and animations will be used. Maybe I'm wrong but the animation will be triggered by a mode (or transition) therefore I had the feeling that those 2 namespaces sounds like "defaults" for transitions.

Having a look to TS types, Animations is a map of Animation instances. Therefore, also Animation can (or must) define all properties that currently we have in the collections and properties (like keys), for the fallback. And therefore my doubt is if Animations is really needed due to you can configure the mode (which is already an extension of Animation) as you want. Sounds a redundant configuration level. But maybe I'm wrong.

Furthermore, mainly based on my mindset, to have 3 (or 2) namespaces at same level of configuration which are referring to the same topic (animation) sounds not so readable.

That said, my votes could be a bit different, but finally they didn't change the result.
Maybe if the animations namespace will be changed (or removed), the evaluation could change.

@simonbrunel @kurkle thanks for looking at a really detailed set of options. I can be on-board with option A in the gist.

@stockiNail Thank you for your feedback.

... those 2 namespaces sounds like "defaults" for transitions

Yes it is, however the fallback strategy requires to handle animation  and animations separately, which is easier if not nested. animation contain defaults for all animations, while animations represents the actual animation "items" (similar to scales). If animations: {} is empty, the chart is not animated.

Having a look to TS types, Animations is a map of Animation instances.

Actually, Animations is a bit more than a map of Animation because it also contain properties (e.g. animations.foo.properties: ['color']) - I will fix my Gist. So no, animation doesn't contain properties / collections, these are replaced by animations.

...to have 3 (or 2) namespaces at same level ... referring to the same topic (animation) sounds not so readable.

We could gather everything under animation:

// Proposal [a']: similar to [a] but one level deeper.
animation: {
  default: { duration: 200 },
  animations: { ... },
  transitions: { ... }
}

// Proposal [b']: similar to [b]:
animation: {
  duration: 200,
  animations: {...},
  transitions: {...}
}

If we decide to go with [b] then maybe it's better to also have transitions under animation (i.e. [b']). Though, it makes the fallback logic even more complicated and I'm not sure it really helps to understand the options hierarchy. If we go with [a] then I would not nested everything under a unique namespace (i.e. [a']).

@simonbrunel thank you very much for explanation.

I think make more sense to go to scenario "a".

We could gather everything under animation:

I have the feeling that even if I like to have a namespace for topic, putting everything in animation could be too verbose.
With animations namespace, the scenario "a" looks like anyway better than the others for all things that you reported.

Thanks again!

I've never been super on-top of the animation stuff - I disable animations in my charts because they're not necessary for my use case where I want to maximize performance. So I don't have much of an opinion and have no objections to any change if you all agree. I won't dive into it too much unless you really need someone to be a tie breaker

The documentation is still outdated, but other parts are good to review

rebased, had conflicts.

Docs updated too