[docs] improve onboarding of frontenders who want to use Volto Light Theme

[fredvd]

Intro, Scope

As Volto light theme is distilled from multiple projects at kitconcept that were designed implemented and improved in the last 2-3 years, there is quite a bit of 'assumed' or expected behavior in the theme by design but also constructs in the source that is not obvious to frontenders without previous volto theming knowledge.

Second: for frontenders with Volto experience they have to pay close attention to the changes compared to the docs.plone.org and training.plone.org docs. We use a relative new features of add'ons as theme, we use scss instead of less, we phase out semantic UI components and we try to avoid component shadowing by importing components directly and/or registering them on the config.js object in the componet registry or other relevant config. At least that is my impression

Third: the tooling has advanced, both on core volto with the improved cookiecutter-plone-starter, this theming add'ons feature and it is not trivial to start using volto light theme and wondering if you are doing it 'right'.

I've been trying for the last 4-6 months to use a bit of volto light theme and beginning of this year I'm assisting two frontenders without previous Volto knowledge for a new Plone 6 project to use volto light theme. So I'd like to document my and our misundesrstandings or 'gaps' in knowledge that we find along the way.

It is essential for me to document these as soon as they surface, otherwise "the "curse of knowledge" kicks in and I and my colleagues on this project will not understand anymore and forget why we didn't understand things. :-P

Use of narrow, default and layout width

I must have read this paragraph in the main VLT readme at least 3 times.

Since FZJ/DLR projects we've been trying a new concept in layout for Volto. This new layout uses three widths for the content elements:

* Narrow (text)
* Default (blocks)
* Layout (main screen elements like Header, Footer)

But whenever I found narrow, layout and default in the source code and in for example the mixins I was totally confused by these. I was associating the narrow and default and layout words with 'technical' things or required mixins in the theme, like the viewport and the side bar or menu bar small and wide expansion settings. Or maybe it is for responsiveness. But it's just 3 different widths INSIDE the main content area for categories of blocks that have 3 different default widths. They're all three defaults.

Just like pressing enter to create a new empty block that you can convert into any other block type, it is so obvious once you know, that I already don't understand anymore after 30 minutes why I didn't pick this up. But analysing my thoughts, imho narrow, default and layout is very rather bad naming.

And how your personal taste changes your perception: in most projects I would set narrow and Default to the same width, as for my personal taste the 'narrow' text blocks are totally ugly :-P But seeing it again on latest 3.0 alpha releases in light-theme.kitconcept.io I realised: "they" must be doing this on purpose!

Adding Volto light theme to a freshly scaffolded Volto 6 project with cookiecutter-plone-starter

Most developers will start with the cookiecutter template and then try to install volto light theme. I did that here for training/demo purposes: https://github.com/fredvd/vlt-demo

• The template already scaffolds a project add'on. Which is also set up as theme. But with mentionning of less. And now I have to wriggle in VLT.

• I've created an issue for the core volto docs, where building a re-usable theme or adding an 'project' tweak-theme are handled in the same section and confused the heck out of me, https://6.docs.plone.org/volto/addons/theme.html , issue is https://github.com/plone/volto/issues/5713

• the template scaffolds an addon/src/theme/theme.config. Should I still keep this file when I want to extend on VLT instead? It contains the same info as the theme.config in volto-light-theme itself. When I remove it everything still works, so I probably don't need this. It also mentions less, but vlt uses sass. Confusing.

• so core Volto is all less, but when I drop a _main.scss in a src/theme folder in my 'project' theme, it suddenly gets processed as SASS. Magic, but confusing. How/why?

• _main.scss is bundled with all other add'ons in the addon loading stack and merged in 'after' VLT scss. Is there some tree shaking going on here that actually removes css from volto-light theme if I override it?

• _variables.scss is the othe rmagic entrypoint. I have a hard time understanding if/how this is handled differently from the _main.scss merge process. are first all _variables.scss collected from all add'ons and then inserted at the start and before the main bundling process that looks at all _main.scss'es?

How do I fix /apply the narrow, layout and default width to customised/added components?

• The description block is still active when I add volto light theme to a project, but it's width is almost the viewport, so probably falls back to Layout width. How do I fix / amend this best in css for other community add'ons or my custom blocks?

• Same goes for fixed views that I add for custom content types without the blocks editor

• When I create a variation on an existing core block, like the listing block where I want to add a table like variant, the variant doesn't stick to the same widths as the existing variants? Why, and how can I fix that?

• A more advanced question where I'm not yet, but can see it relevant in the near future or for frontend add'on authors:

• How can I create a frontend addo'n that supports both core Volto and also works out of the box in VLT?

Ecosystem

• Volto Light Theme is opinionated which is fine, but it expects an ecosystem of add'on s with blocks that extend but also work as replacements for core volto blocks. I assume the introduction block should be a replacement for the description block. But as already mentioned above the description block is active in a volto+vlt scaffolded site and visually jumps out of the expected viewport/margin.

... to be expanded.

[fredvd]

@sneridagh @danalvrz @iFlameing @tisto I've written down some questions and misunderstandings I've experienced so far while trying to understand and use Volto Light Theme (VLT).

These are not just VLT 'only' issues, most of them are in relation to core Volto and core Volto documentation and the cookiecutter-templates that we have available at the moment.

Looking from the view point of a frontend developer that wants to start a project but has heard that Volto Light Theme provides a much nicer and 'complete' basis than core Volto, the things I stumbled over can be indicative for others.

If we want to improve adoption of VLT, this is where we can likely improve our documentation, but maybe also collect feedback from others that tried to use VLT for the first time.

[fredvd]

I can totally understand when you frown about this issue because you have been explaining many of these topics to the community already. Now that I understand what I did't understand I suddenly start to see the same answers and explanations everywhere :blush:

I'm collecting interesting video's for my colleagues, and I found back the Volto light theme talk from PloneConf 2023 that explains at least half of the 'insights' I'm describing and questions I have. But I'm not a video person and go for text/documentation first. Also getting ill just after the PloneConf for some weeks didn't help.

Why isn't this video linked yet to the top of the README? I'll create a PR.

https://www.youtube.com/watch?v=t2X2NO62J-8&list=PLGN9BI-OAQkSXMXVBXLWQAQr0AF2xM_NU&index=47