Initial feedback

[andrejilderda]

Initial thoughts

Wow, way to go @allmarkedup, very impressive what you have done so far!

Did you have any difficulties getting the prototype demo up and running?

No, works like a charm. I'm also happily surprised with the documentation so far.

Were your initial gut feelings about the prototype direction positive or negative?

Very positive. Simpler to setup, more flexible and powerful.

Do you think this prototype represents a good development direction for the next version of Fractal?

Yes, definitely.

Components

v1-style 'single file components' are no longer supported. Does that pose any difficulties for you?

I'm not sure what you mean by 'single file components', so I guess not. ;) Do you mean a component should now always have a config-file associated with it? Having a single view template in a folder still seems to work.

Do you have any thoughts on the naming of configuration properties?

Props is definitely better than context data. Your rationale to use ‘scenarios’ over ‘variants’ makes sense, so I’d say let’s stick with it.

Only thing that made me raise an eyebrow was the term ‘front matter’ that I had never heard before (even though I've used it). The first paragraph in the Jekyll docs explains it clearly. Shall we add something similar or a simple code example to the doc?

Adapters

Which template engines/frameworks would you most like to see integration with? (2 - 3 max)

• DustJS
• HAML
• Handlebars
• Marko
• Mustache
• Nunjucks
• Pug
• React
• Twig
• Vue
• Other - please specify below

I think it'd be wise to also support React since it's so popular.

For developers...

Does the plugin model make sense to you? Any questions/queries about it?

I've managed to get the example author-info plugin to work and it all seems straightforward. But I must admit I need to dive into the architecture some more to discover the possibilities.

Are there customisations that you'd like to make that you think might not be possible in the current plugin system implementation?

Maybe, see below my notes on the nice to have's.

Do you think the monorepo approach is a good route future Fractal development?

Yes, definitely!

Other

Is there anything missing from the prototype that currently exists in v1 and that you think should be part of the core of any future versions (i.e. not implemented as a plugin)?

• Unrendered view template (as suggested by Benoît Feature request: Panel displaying view template source code #10)
• Statuses? But maybe better as a plugin.

Any other comments/suggestions/ideas?

👇

Design system ‹ › Component library

I primarily have been looking at the prototype from a front-end/designers perspective with an interest in using Fractal as a design system tool. I think v2 has great potential to become the open-source tool to quickly get (the technical part of) a design system up and running. V1 missed some flexibility, especially in terms of customizing the component UI. For me this mainly had to do with the separation between documentation and component pages, where in design systems the components are usually part of a documentation page (including its variants, ahum… scenario’s ;)). To illustrate the difference between a design system and a component library, compare Carbon’s and Gov.uk with Fractal v1 and Storybook’s way of presenting a button. As a documentation tool the ‘design system’ is preferred, while working on components the latter view is. This is why I was excited about the idea of the ‘workbench’ view vs. the built ‘presentation’ view that was outlined earlier. Is that still part of the general idea? Maybe this is possible since the overall setup is more flexible, but I can’t connect the dots yet on how to achieve this.

Just a few of the things I like

• Easy to setup
• Multiple scenario previews
• Search aliases for components
• The way the nav is build and can be customized easily
• Reference tags
• Being able to (optionally) run Markdown through the Nunjucks parser and vice versa is really handy. Works great in my tests so far.
• The new preview features are great! Wrap(), wrapEach(), inject js and css. It might clutter the config-file, but I guess you can always import if necessary.
• The auto-rewriting of url’s

Nice to have’s

• Reference tag for rendering the components iframe (so that we’re able to create more dynamic documentation pages). Like {iframe:button/next}/{include:button/next}/{render:button/next} or whatever we want to call it.
• That you can’t click on the top level component when there are multiple scenario’s/variants has always kinda bugged me.
  • It’s not possible to directly open the component when there are children (it then expands the tree). How about opening the default scenario + expand the tree when the title is clicked? This would save a click.
• I see a lot of design systems having only top-level components documentation pages where all variants are rendered onto this page, like fe. Carbon. How about an extra optional view file specifically for component documentation purposes? Like having an optional *.page.*-file besides a *.view.*-file in the component folder which is used as a component documentation page (in which you could include the component scenario’s with the relevant documentation yourself as in previous sub-bullet). I’m not sure if my explanation is clear, but I think this could be huge for component documentation pages as you often see in design systems.

*Do you know about the props editor in Storybook called ‘knobs’ (see here)? I haven’t used it myself and could totally live without, but I’m just curious.

[allmarkedup]

Hey @ajilderda - many thanks for this feedback, lots of good points in there. I'll try to go through them here:

I'm not sure what you mean by 'single file components', so I guess not. ;)

In v1 you can create a component without needing a parent directory - ie. components/button.hbs instead of components/button/button.hbs. Occasionally useful but makes the component parsing (and documentation!) much more complex which is why I felt it better to drop it for this version.

Only thing that made me raise an eyebrow was the term ‘front matter’ that I had never heard before (even though I've used it).

Ah that is interesting - I thought that it was quite a common term but you are right, it could do with some more thorough explanation in the docs. I've opened an issue for that.

Unrendered view template (as suggested by Benoît #10)

Yup, agreed - I've added issue #10 to track that.

Statuses? But maybe better as a plugin.

Yes I think a plugin is the way to go for this but it could also then be included in the core - we can make a decision on that later. I've opened issue #17 to track this.

This is why I was excited about the idea of the ‘workbench’ view vs. the built ‘presentation’ view that was outlined earlier. Is that still part of the general idea? Maybe this is possible since the overall setup is more flexible, but I can’t connect the dots yet on how to achieve this.

I totally agree about the difference between 'documentation' and 'component library', and I'd definitely eventually like Fractal(lite) to be able to service both needs. However the current focus has been on providing a UI that leans more towards the 'component library/workbench' side of things, but that still allows some documentation to be included (via 'pages') - unlike Storybook that is more heavily dev-focussed.

However, with the new architecture (the core component parser/compiler is now a completely standalone package) building a (separate) documentation-focussed tool that uses the same component structure should be totally possible - in my mind I'm envisaging something more like a Fractal-powered version of Docz. That way components could be developed in a more structured way (in the current UI - the 'workbench') and then bespoke documentation built to showcase them in a more 'fluid' way with a custom look and feel more like the Carbon/Gov.uk examples you linked to. The previous iteration I outlined tried to solve this via different themes for the same tool, but actually I think it needs a separate tool built on the same foundations to make the workflow intuitive and the tool performant.

I'm not going to open a feature request for this as I think it's a larger discussion point, but let me know if my reasoning above makes sense!

Reference tag for rendering the components iframe (so that we’re able to create more dynamic documentation pages). Like {iframe:button/next}/{include:button/next}/{render:button/next} or whatever we want to call it.

Yes this is definitely something that needs to be added. I'm not sure if a reference tag is the correct way to do it (they are really intended for property access rather than HTML generation) but I'll have a think about the best way to do it. I've opened issue #18 to track progress/feedback on this.

That you can’t click on the top level component when there are multiple scenario’s/variants has always kinda bugged me. It’s not possible to directly open the component when there are children (it then expands the tree). How about opening the default scenario + expand the tree when the title is clicked? This would save a click.

Yes I like this - makes a lot of sense! I've opened issue #19 and will try and get that implemented ASAP as it's quite a small change :-)

I see a lot of design systems having only top-level components documentation pages where all variants are rendered onto this page, like fe. Carbon. How about an extra optional view file specifically for component documentation purposes? Like having an optional .page.-file besides a .view.-file in the component folder which is used as a component documentation page (in which you could include the component scenario’s with the relevant documentation yourself as in previous sub-bullet). I’m not sure if my explanation is clear, but I think this could be huge for component documentation pages as you often see in design systems.

I think this ties in with the discussion about workbench/documentation above. This is certainly one way that the docs side of things could be handled.

*Do you know about the props editor in Storybook called ‘knobs’ (see here)? I haven’t used it myself and could totally live without, but I’m just curious.

Yep and a few people have mentioned this! It's possible but given the need to support multiple template languages/frameworks it is not straightforward. However I've opened issue #20 to track it and see if we can figure out a nice way to get it implemented.

Happy to continue the discussion on any of the points above - either here or on the issues I've opened regarding them. And thanks again for taking the time to get all this feedback down 👍