Moving Fractal forwards #197
Comments
|
Re: "Supporting multiple, concurrent view template languages", I would be happy to look into whether/how Fractal could use meta-template to convert templates from Nunjucks to other template systems automatically. (For instance, imagine if you could generate a directory of drop-in ERB or Django templates from a Fractal style guide with a single command!) This would really help me think through how collections of templates could be converted en masse while preserving partial references, etc. |
|
+💯 to "Supporting multiple component source directories"! This would make customizing or composing style guides easier, which is something we would love to support when we (eventually!) port the US Web Design Standards over to Fractal. |
allmarkedup
changed the title
|
About new features and contribution: Some time ago I was thinking about creating components in angular2 way - using angular-cli would speedup development process alot. My wishlist:
|
|
@shawnbot regarding meta-template integration - I'd love this! For me this seems like something that would be best suited to a bespoke CLI command however, rather than something integrated into core. I'm sure it would actually be possible with the current version of Fractal (although obviously Fractal wouldn't be able to display the converted templates). And the more I've been thinking about the multiple source directories the more excited I get about the possibilities. Things like being able to distribute a core set of components as an NPM package that other libraries can then build off/override would be very cool indeed. |
|
@tlenex I'm not actually familiar with Angular 2 components, but I'll take a look. I'd definitely like to get some CLI tasks added to Fractal for creating new components or updating/renaming/moving existing ones however, it would definitely cut down on a lot of repetition. And yes... test coverage and API docs is definitely needed and will certainly be made a priority for the next version of the component parser (and all the rest!). |
|
I'm in agreement with many – if not all – of your thoughts here Mark; thanks for taking the time to reflect on progress so far, and your plans for the future. One other piece of information that might be useful is what Fractal is not (or will not be), i.e. a prototyping tool, task runner, CMS etc. The focused nature of this project is a strength, and I believe it’s important to avoid any feature creep/bloat. I’m sure making the code more modular and creating a more pluggable architecture will help in this respect. |
|
@allmarkedup This looks great. I'm excited to see such a strong outline for moving Fractal forward. I've weighed in on a couple of the items you outlined already, but I'll chime in with my (unordered) priority wishlist.
In terms of documentation and getting started, I really appreciate well documented or intuitive examples. Referencing the demo project helped me get oriented to a lot of the basics. I think a good sample project is just as valuable as well written docs or tutorials. For communication, I personally prefer using Slack over Gitter, but don't have strong feelings. I think it's less important that chat rooms are publicly searchable though, and more important to have the relevant bits that maybe come out of discussions to be put into appropriate documentation. I think Framer offers a good model with their documentation, blog, and gallery. Obviously it is a more mature project, but the structure and quality seems worth referencing. |
|
@paulrobertlloyd great to hear Paul :-) And I think your comment about focus and communicating that focus is actually really important. I'll try and draft a concise description of what Fractal is and isn't going to be and add it add it to the post. Thanks. @ixley many thanks, that is all good info. I think that all your wishlist items are covered by the proposed additions above. The default content one is certainly high on my list but it's also not an easy problem to solve if also trying to make sure that templates can be picked up and used outside of Fractal without any hoop-jumping required. But i've got a few ideas that I still need to hammer out to get the ramifications clear in my head. I haven't looked at the Framer site in a very long time but you are right, they look like they are doing a great job with the mix of 'getting started' content and the technical deep-dive stuff. I'd love to eventually have something like that! Good inspiration for sure. |
|
@allmarkedup Really nice summary and I can only agree with it. I played a lot with theme and GUI to change. At start it was funny, but it's not so complicated. What was missing - is documentation. Maybe two little thing to think about
|
|
Thanks for asking for comments @allmarkedup. I think I agree with the direction things are heading in. In terms of custom theming, it would be nice to see a simpler method of customization rather then a completely new theme or even writing a CSS file with new rules. I't be helpful to override a set of variables, mostly for color and typography. When I themed our Fractal guide, that was mostly what I needed. |
|
|
@allmarkedup Hi Mark, great list. Do you have any specs yet around tooling? I've got a POC "New component" CLI command for a project I'm working on that just adds the basic scaffolding. Would be interested in hearing what you have in mind for this one and others. I'm happy to submit some PRs around this and other features... Jamie |
|
A big thank you for this tool. It's become vital to our workflow and my team has been able to leverage it for both small and large projects and across a variety of technologies. No small feat! We typically use Fractal to document the UI for a project, as a way to show our design team and our engineering team the individual UI components and the expected DOM structure. We have hopes of eventually integrating it into an Angular or React project, but so far we haven't quite found that level of configuration necessary. I'll try not to assume what the solution might be to the two pain points we encounter, but I'll outline them below in hopes it might help make this tool more useful down the road: Modifiers We use SMACSS (similar to BEM and others) to build our UI components. Usually they follow a structure similar to the one below in Fractal using variants:
Most often the variants are passing a new string of CSS classes via a modifiers property in the context:
We'll then use these variants in other components via the render helper:
The issue that arises now is that we're explicitly declaring the "is error" modifier in multiple places, so if we click on "Is Error" in fractal to view the error state, we're not aware of the other variants that use it, and where it might be rendered. For a simple project I can see the argument that this isn't a big deal, but we have some projects that might contain up to 20 variants with multiple "chains" of alternate styles and states. I think what we need is an elevated "modifier" property which we can reference via the render helper or when creating variants that is validated (so we can't reference modifiers that aren't explicitly declared) and can be easily printed as a space-separated list of class names. The tricky thing I imagine will be how these fold into variants, or if they're simply a property on variants that can be referenced by other variants or render helpers and ensure the reference is in place. Really the core ask here is: can we find a way to create a "modifier", and then use it within other variants and render helpers and keep the references in tact? Wrappers Sometimes we encounter components that do not have an inherit DOM structure of their own, and instead we use them as "wrapper components". The component's template will contain a class name along with modifiers:
Then we'll use it as follows within other components:
This is a workaround that seems to do fine. It allows us to create and declare a component and then use it and create references within Fractal for where its used. However, the preview and markup views for the component have to be handled. What we end up doing is creating a "none" preview that displays a message "This component has no preview" so when browsing Fractal you don't see demos that simply show text. We still want to be able to see the information in the assets, notes, and info tabs, but the preview and markup views aren't useful. Could we find a way to make the preview and markup views optional for components? |
|
Request: Docs about React integration would be highly appreciated. |
|
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. |
|
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. |
Over the last year and a half Fractal has evolved from an internal prototype at Clearleft into an open source project that we (and now many others) are using to create and manage component libraries. It’s been exciting to get validation of the core ideas behind the project and great to see all the different ways that others have been pushing at the boundaries of what is currently possible with it.
When we were developing Fractal our goal was to create a component library tool that was as agnostic as possible to things like build tool and template language choices, and also offer opportunities to build upon the core feature set to allow better integration and custom workflows for development teams. To some extent I think that we were successful in this; but it is also clear from the feedback over the last year or so that there is plenty of room for improvement!
After seeing how people are trying to fit Fractal into their development process, and thanks to some great input from the community, I’ve identified the following key areas to work on improving in 2017. Please chime in on the comments below if you think I’ve missed anything!
New features and usability improvements
Components
A number of great suggestions for potential improvements to the way that components are created and handled by Fractal have come up in the past year. The current system has proven to be able to serve a lot of fairly disparate use cases, but not always without compromising the clarity of the component configuration or the structure_organisation of view templates and their partials_includes.
At Clearleft we have also been talking a lot about how we might be able to use component libraries earlier on in the design/build process, perhaps by creating ‘placeholder’ components that do not have any code yet, but do have a README or a static mockup of a component. In this way you could quickly scaffold out a component library structure, and iterate on the organisation and design even before adding a line of code. Components could then be built out with the templates and other assets as the project progresses.
Proposed improvements
A detailed list of proposed improvements to the component system (with more technical detail) will be published as a separate issue for people to comment on. However the main suggestions will include:
Related issues
Pages/docs
The current documentation system is based on the same filesystem parsing, configuration logic and template engine handling as the component system is. The aim was to allow people to use a mix of markdown and templating language features to build docs and ‘styleguides’ that would complement the component library.
Whilst people have indeed been creating some nice examples of documentation/styleguides, the process is currently hampered somewhat by the lack of a standard ‘UI library’ of style guide components (such as colour swatches) and the inability to easily add custom styles to the documentation in the web UI. Additionally, the documentation system lacks ‘knowledge’ of the component library itself, which means that things like generating links to components, rendering components within the documentation or displaying ‘live’ information about components is currently not straightforward and requires significant technical knowledge.
Creating a UI library of ‘partials’ for style guide components and even helpers for linking to/displaying components is partly a significant challenge because of the flexibility Fractal offers when it comes to template engines and organisation of the component library.
Proposed improvements
While it’s clearly a key feature that Fractal supports multiple template languages for creating components, the use case for supporting the same functionality for the documentation generation is less clear. I propose switching Fractal to enforcing use of a single predetermined template engine (most likely Nunjucks) for generating documentation. This would make it considerably easier to create and document a canonical set of partials for creating styleguides/docs, and to tie in the components in the component library much more closely into the docs to allow for easier linking and embedding etc. This simplification would benefit less technical users of Fractal.
Related issues
Web UI/theming
The current model of theming was intended to give a lot of power to people that wanted to develop completely custom themes (right down to the URLs), completely distinct from the default ‘Mandelbrot’ theme that ships with Fractal. However, this was somewhat at the expense of making it really easy to customise the ‘look and feel’ of the theme itself without a fair bit of technical knowledge.
Since releasing Fractal, there has been considerable interest in customising the Mandelbrot theme, and very little interest in developing completely custom themes. This is understandable; Mandelbrot does a lot of the heavy lifting with regards to displaying previews, code etc and it would be a lot of work to re-implement this in a completely bespoke UI. (The custom theme route is also currently very under-documented which doesn’t help)
Proposed improvements
It seems to make sense to ‘pave the cow paths’ - double down on the 95% use case (customising Mandelbrot) and optimise that over the 5% use case (developing bespoke UIs).
To this end, future releases should concentrate on moving the current web UI server_builder_theme model in this direction. This would likely involve moving the responsibility for routing and view handling out of the theme and into the web UI server, which would simplify the theme templates significantly and have them act as more traditional simple static ‘view’ templates. This would decrease both the complexity of the the theme setup/configuration and mean that the templates require much less logic within them to handle rendering of components and displaying documentation pages.
The server instance itself should also be made available so that custom Express middleware can be added to extend the server functionality if required.
Related issues
Extensibility
Fractal currently lacks ways to customise its core parsing behaviour, or to extend the component configuration handling process. The result is that feature requests for additional functionality either have to be added to core, or not implemented at all. In the spirit of trying to keep the main codebase as focussed as possible this would be a key area to work on so that we can try and kick-start a plugin-based ecosystem for Fractal.
Proposed improvements: Add hooks to allow customisation of the core filesystem parsing behaviour, as well as a mechanism for extending the component, docs, sources and collection entities that are exposed via the API.
Related issues:
Tooling
Fractal’s in-built CLI currently has a very limited set of functionality, restricted to starting/stopping the web server and not much else. Given the availability of the API and the potential to build many more useful tasks, this is a shame.
Proposed improvements
Extending the list of built-in tasks to component scaffolding, renaming of components, ‘doctor’ tasks for identifying potential problems and much more would significantly increase the speed at which component libraries could be assembled and changes to existing components made.
Related issues
Codebase improvements and refactoring
To meaningfully be able to support many of the above changes going forward, the core codebase needs a significant overhaul. The current Fractal implementation suffers from the somewhat haphazard and ‘organic’ process from which it moved from prototype to open source project. This is also currently a pretty major blocker to getting more developers onboard with contributing to the project.
The following areas need to be addressed to make outside contribution easier and to have more confidence in releasing updates (and releasing with more regularity):
Other
‘First run’ experience
Fractal’s un-opinionated nature when it comes to build tools and template languages can also increase the complexity when it comes to less technical users setting up new projects. Some quick-start, pre-built ‘templates’ or generators for a Gulp-based project, a Grunt-based project, etc. would be a great help for getting people who are not interested in customising these aspects themselves up and running quickly.
Community communication and contributions
Currently the Slack channel and Github issues are the only way of communicating with the community regarding upcoming releases, important bug fixes and trying to solicit feedback on proposed features. How can this be improved?
Some thoughts would be:
We also need to provide better contribution guidelines and development information to help people get involved.
Better documentation and examples
This is an ongoing process, but apart from filling in the blanks in the Guide we need to look at how the docs are built and hosted. Currently it’s a pretty manual process but it would be good to open this up so that PRs can be quickly and easily pushed live.
Autogenerating API docs from Docblock comments or similar needs to be investigated as a way to keep these docs in sync with development.
An ‘official’ demo site is still sorely needed, as well as some sort of ‘tips and snippets’ repo/site where useful configuration examples and how-tos can quickly and easily be posted up.
We'll be adding 'Contributions' and 'Issue template' markdown files.
Related Issues
In closing
There is a lot of potential work described above, and much of it will require some significant changes to Fractal’s underlying codebase. It will also likely involve some major breaking changes to some parts of the existing Fractal APIs, although keeping compatibility with existing configuration file formats and filesystem/folder structures will be treated as a priority.
However none of the above is set in stone, and much of it may not even make its way into the next major release. Feedback is most welcome, including ideas on what should be prioritised and if any of the above causes people any concerns with regards to the way that they are currently using Fractal.
I’ll shortly be publishing a roadmap of how I see some of the above features fitting into the next few cycles of development, but until them please throw any questions or comments my way :-)
The text was updated successfully, but these errors were encountered: