Perfect css-framework. Maxmertkit widget manager - build your own framework

Good day!
As promised some time ago, I released a maxmertkit widget manager beta. I have long wanted npm or gem, but for css. I added several dependencies to the json-file, typed the command and everything was installed. It is fast and convenient. I have not found any good solutions, it is time to realize my own. Until he started, links to articles about how it all began - the first and second articles. You can not read, I will briefly retell everything here. You can immediately go to the portal and find out what's what, and also watch the video - www.maxmertkit.com .

Almost everything I describe below is in this video. I apologize for the sound quality, I will try to find a normal microphone.

Requirements

Before implementing any project, it is necessary to determine the basic requirements that this project must meet.

• Namespaces . For all classes of the framework.
  
  • - <widget -name > —name of the widget, for example -table, -btn, -tooltip
    
  • - <theme-name> - - the name of the theme for the widget, for example -primary-, -error-, -orange-
    
  • _ <size-name> - size, for example _tiny, _small, _huge, _divine
    
  • _ <modifier-name> _ - modifier, for example _top_, _active_, _hover_, _unclickable_
    
  
  
• Modularity What do I mean by modularity? There is a widget -btn button and it is used as part of the -group widget. First, when creating a group widget -group, you can specify a dependency on the -btn widget and not describe it again (this is easy to achieve with native css). Secondly, if I use the -btn widget with the -error- theme, I cannot use this theme as a group. Well, and vice versa, having applied a custom theme to the group, my button should not change. That is, widgets must be completely independent of each other. For css it is quite difficult to implement, but it is convenient and practical.
  
• Capture theme . When I apply a theme to a parent widget, children widgets should inherit the theme. For example, set the group theme -error- , and all elements within the group should change the colors to -error- . It is very convenient.
  

')
All these requirements are implemented in the mwm - maxmertkit widget manager. It works as npm for node.js or as a gem for ruby ​​on rails. His task is to download the widgets, themes, modifiers and animations you need, and then compose them for compilation. The first step is to install mwm. This needs to be done globally, so in order to avoid unnecessary questions I quote a command with sudo:

sudo npm install -g mwm 

After installation, make sure mwm is installed correctly by typing the help call:

 mwm -h 

If there is a list of commands, then everything is in order.
To initialize maxmertkit, let's move to the root of your project (namely, to the root, and not to the folder with your styles). Here we can create a configuration file that will tell mwm the path to the folder with your styles. File name: .mwmc . So far, mwm supports only one field:

 { "directory": "path-to-your-stylesheets-from-projects-root" } 

For example, if my styles relative to the root are in public / stylesheets , then

 { "directory": "public/stylesheets" } 

If you created a configuration file, then run mwm from the root of your project, if not, go to the folder with styles.
Next, you need to initialize maxmertkit with the following command:

 mwm init 

Mwm asks you about the title, tags and other stuff (which you have to fill out if you create a widget / theme / animation and are going to publish it) and create the files you need to compile, namely:

• _imports.sass - includes the listing of all connected widgets, themes, modifiers and animations.
• _params.sass - contains the parameters necessary for compiling the project
• _vars.sass - variables used in dependent widgets
• _myvars.sass - variables used in the current widget
• _index.sass - a file in which you can write your styles, just leave the imports
• maxmertkit.json - project configuration file

All these files, except for _index.sass and maxmertkit.json , do not need to be changed, touched, and ideally, you need not to know about their existence or not to notice.
Let's try to install the btn widget. To do this, add the dependences field to maxmertkit.json :

 { "type": "project", "name": "test", ... "dependences": { "btn": "0.0.9" } } 

Instead of version 0.0.9, you can specify * if you want the latest available version of this widget. Save and type in the terminal

 mwm install 

I didn’t teach mwm to compile sass files, so you need to compile _index.sass yourself. To do this, you can open a new terminal window, go to the folder with the styles (not the root) of the project and type

 sass -w _index.sass:index.css 

You can leave this terminal window, now sass will monitor changes in the file structure and recompile the project if necessary (it doesn’t track very well, so after mwm install recommend opening _index.sass and saving it so that the compiler realizes that you need to recompile the project). Widget button -btn installed. You can use it in html-code. To understand how, welcome to go to www.maxmert.com in the widgets section and read the documentation. In our case it is

 <a class="-btn"></a> 

OK, so how to set a specific theme for this widget? You need to change maxmertkit.json again:

 { ... "dependences": { "btn": { "version": "0.0.9", "themes": { "error": "*", "orange": "*" } } } } 

And dial again

 mwm install 

Now with the -btn widget, you can use the -error- and -orange- themes :

 <a class="-btn -error-">Error button</a> <a class="-btn -orange-">Orange button</a> <a class="-btn">Default button</a> 

That is, in fact, all that is needed to use mwm for your projects.
I will give an example of the maxmertkit.json file

 { "type": "widget", "name": "group", "version": "0.0.4", "description": "Standart group", "repository": "", "author": "maxmert", "themeUse": true, "tags": "button, buttons, group, input, label, appendix", "license": "BSD", "dependences": { "bourbon": "3.1.8", "object": "0.0.0", "btn": { "version": "0.0.9", "themes": { "primary": "*", "error": "*", "orange": "*" } }, "forms": "0.0.5", "caret": "0.0.4" }, "themes": { "default": "*", "disabled": "*", "primary": "*" }, "modifiers": { "tiny": "0.0.0", "small": "0.0.0", "minor": "0.0.0", "normal": "0.0.0", "major": "0.0.0", "big": "0.0.0", "huge": "0.0.0", "giant": "0.0.0", "divine": "0.0.0", "active": "*", "hover": "*", "unclickable": "*", "loading": "*", "unstyled": "*" }, "animation": { "loading": "0.0.2" } } 

Portal use

After sign up on maxmertkit.com you will have the following options (I won’t use your personal data at all, I promise):

• You can collect the project directly on the site and download styles in the archive.
• You can save the desired set of widgets / themes / modifiers / animations in the presets for deferred compilation or download.
• You can save to favorites so you don’t have to search for a long time (although there is a search) or simply report that you like this widget.
• You can create and publish your widgets, themes (themes - right on the site, very fast and cool), modifiers and animations.

All documentation for widgets is available on the site and without registration.

Creating a widget

Suppose you want to make and publish your widget. The first thing you need to do is to register at maxmertkit.com , enter your profile (click on your avatar in the sidebar) and create a developer password. It will be necessary when publishing your widget.
After that we create a folder in which our widget will be forged, go in there and type

 mwm init -w 

The -w flag means that we are initializing the widget, not the project. Mwm creates the necessary files, generally similar to the project files. In the maxmertkit.json file we add dependencies, modifiers and animations that our new widget will use (by analogy with the project, described above). Typing

 mwm install 

and then

 sass -w _index.sass:index.css 

and proceed to editing the main widget file _index.sass .

Rule _index.sass

_index.sass - the main widget file, which contains all the necessary styles for the widget. Initially, he is:

 @import "imports" @import "params" @import "myvars" @import "vars" %#{$test} @extend %object // Set _minor to default size $sizes: null!default @if $sizes @each $size in $sizes $sz: #{nth($size, 1)} @if $sz != _minor &.#{nth($size, 1)} font-size: nth($size,2) padding: nth($size,2)/3 nth($size,2)/2 @else font-size: nth($size,2) padding: nth($size,2)/3 nth($size,2)/2 // Modifiers // Themes $themes: null!default @if $themes @each $theme in $themes $index: 1 @if length( $themes ) != 1 $index: index( $themes, $theme ) $imp: "" @if $theme == "-disabled-" $imp: !important @if $theme != "default" &.#{$theme} color: nth( $color-invert, $index ) border-color: nth( $border-color-lighten, $index ) &:hover border-color: nth( $border-color-darken, $index )#{$imp} @else color: nth( $color-invert, $index ) border-color: nth( $border-color-lighten, $index ) &:hover border-color: nth( $border-color-darken, $index )#{$imp} @if $dependent == null .#{$test} @extend %#{$test} 

Instead of $ test will be the name of your widget, for example, if during initialization you said that the widget will be called superbutton , then instead of $ test there will be $ superbutton. But then we will assume that my widget will be called test.
Let's sort the code.

 %#{$test} 

% here is used to not add a class to css in case this widget is a dependency of another widget (this is the extend-only selector). I advise you to read about it here .

Dynamic dimensions

 $sizes: null!default @if $sizes @each $size in $sizes $sz: #{nth($size, 1)} @if $sz != _minor &.#{nth($size, 1)} font-size: nth($size,2) padding: nth($size,2)/3 nth($size,2)/2 @else font-size: nth($size,2) padding: nth($size,2)/3 nth($size,2)/2 

In case our future widget will have different sizes, you need to remember to include the widget sizes depending on and define the properties of our widget in this cycle. In this case, for each size (see the sizes widget) we define font-size and padding . Of course, other parameters can be defined by including nth ($ size, 2) in the value. Here nth ($ size, 2) is a specific value in px, corresponding to each of the sizes. It can be converted to your taste. As you can see, the code is duplicated here. But it is necessary to determine the default size after @else (the code can not be duplicated, but set, for example, some predefined values).

Dynamic themes

Now consider how to add topics.

  $themes: null!default @if $themes //     @each $theme in $themes //  sass    ,   ,     $index: 1 @if length( $themes ) != 1 $index: index( $themes, $theme ) //  -disabled-   ,    !important,     $imp: "" @if $theme == "-disabled-" $imp: !important //    default,    @if $theme != "default" &.#{$theme} //        //    –       color: nth( $color-invert, $index ) border-color: nth( $border-color-lighten, $index ) //  ,      :hover, :active //   ,  .#{$mod-active}      _active_ &:hover border-color: nth( $border-color-darken, $index )#{$imp} &.#{$mod-active} background-color: nth( $background-color, $index )#{$imp} //             @else color: nth( $color-invert, $index ) border-color: nth( $border-color-lighten, $index ) &:hover border-color: nth( $border-color-darken, $index )#{$imp} &.#{$mod-active} background-color: nth( $background-color, $index )#{$imp} 

I tried to give comments in source, but it is worth mentioning that in nth ($ background-color, $ index) # {$ imp} you just need to change the background-color to the name from the list present in each topic, for example here - error theme . These are, for example, color , color-invert-darken , background-color-invert-darkener and others. With this structure, themes will automatically be applied to your widget. Try to include a couple of topics depending and test them.

 @if $dependent == null .#{$test} @extend %#{$test} 

Check if your widget is dependency. If yes, then there is no need to create a class selector, but you can inherit from it. If not, then create a class selector.

Tests and documentation

Let's move on to the tests. To publish, you will need to create a test.html file and include the compiled index.css into it to check if everything compiles and works correctly. On the portal, your test.html will be displayed in the iframe after the documentation. If you specified the github repository of this widget in maxmertkit.json , then the README.md file will be taken from there. If the widget does not have a github repository, then create a README.md file with recommendations for its use. You can, of course, without him, but somehow this is bad. When everything is tested, written and ready, just type

 mwm publish 

Remember that your mwm name will be taken from the maxmertkit.json file, the author fields, but you will be asked to enter your password. You can then follow the mwm directions. Widget published. The unpublish command is present, but for test purposes, so the server will ignore it (it will soon disappear from mwm completely). If you suddenly realize that you made a mistake, you will have to correct it, upgrade the version in maxmertkit.json and publish the widget again. Mwm supports versioning well, so if someone is already using the old version of your widget, nothing will break.

Creating themes

Themes can be created directly on the site. It is fast and convenient. Log in using one of the social networks, in front of the themes menu will appear + , clicking on which will take you to the page for adding a theme. It is enough to enter the name and primary colors: main and inverted. The remaining fields can be left empty, they will be calculated automatically (see the placeholders of these fields).

Issues

For mwm - https://github.com/maxmert/mwm/issues
For widgets, themes, modifiers and animations (for sass and css) - https://github.com/maxmert/maxmertkit/issues
My problems with English or Russian (I beg you to help with editing the texts) - in PM at habrahabr or at me@maxmert.com .

Competition

I ask you, friends, to send me a ready-made UI to me at vetrenko.maxim@gmail.com (please specify the topic habrahabr - UI so that I can navigate) that you would like to see implemented in maxmertkit. As far as possible, starting with the most attractive ones, I will add them. It will be great! You can send jpg (in this case, when I start the implementation, most likely I will ask for psd) or immediately psd. I will update the post so that it is clear that it will appear in the near future.

PS : Friends, I ask for help with writing an English article for distribution in foreign blogs. The fact is that in English I write in Russian, sorry for the pun. Most likely I will take the text of such a competent article to the main page and point you as the author of the article. And unfortunately, I don’t have any accounts on foreign blogs with the relevant topics, so I’m asking for help with this too.