From 3dffd375423607c77e36198d1474acb7539cb314 Mon Sep 17 00:00:00 2001 From: Angelos Chalaris Date: Mon, 3 Apr 2017 23:48:49 +0300 Subject: [PATCH] Initial commit of customization docs Created a new folder, 'customization', under which the new Customization documentation will be added (replaces wiki). All the old page navigation links have been updated to point to it, while the old 'customization.html' page now redirects to the new one. --- docs/card.html | 2 +- docs/contextual.html | 2 +- docs/core.html | 2 +- docs/customization.html | 173 +--------------------------------- docs/customization/index.html | 92 ++++++++++++++++++ docs/flavors.html | 2 +- docs/grid.html | 2 +- docs/index.html | 2 +- docs/input_control.html | 2 +- docs/modules.html | 2 +- docs/navigation.html | 2 +- docs/progress.html | 2 +- docs/quick_reference.html | 2 +- docs/tab.html | 2 +- docs/table.html | 2 +- docs/utility.html | 2 +- docs/v2/DEVLOG.md | 3 + 17 files changed, 110 insertions(+), 186 deletions(-) create mode 100644 docs/customization/index.html diff --git a/docs/card.html b/docs/card.html index 35c97c8..a8a130f 100644 --- a/docs/card.html +++ b/docs/card.html @@ -28,7 +28,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/contextual.html b/docs/contextual.html index bbea86b..7347172 100644 --- a/docs/contextual.html +++ b/docs/contextual.html @@ -28,7 +28,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/core.html b/docs/core.html index d9847f6..352d8c2 100644 --- a/docs/core.html +++ b/docs/core.html @@ -28,7 +28,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/customization.html b/docs/customization.html index 67d904b..29fccc2 100644 --- a/docs/customization.html +++ b/docs/customization.html @@ -12,176 +12,5 @@ - + - -
- -
- Introduction Modules - Flavors Customization - Quick Reference -  Github -
-
- -
-
-
-

Customization

-

mini.css is built in such a way that customizing it is really simple. You can try out one of the pre-defined flavors, if you want to start learning and build something quickly. We strongly suggest, however, that you customize an existing flavor or build your own, by tweaking variables and using mixins, in order to create your own, unique style. In this page, we will try to give you some guidelines and tips on how to do so and explain a few more things about the inner workings of mini.css.


-

Introduction & basics

-

mini.css is written using Sass, a very popular CSS preprocessor. We use Sass to do four things:

-
    -
  • Make the code modular
    • -
  • Create variables that can be changed on the fly
    • -
  • Optimize the code
    • -
  • Create reusable mixins
    • -
-
-
-
-
-

Modules & file structure

-

At the heart of mini.css are modules - groups of classes and styles that aim to solve one set of needs. There are 10 modules in mini.css, which have been already written for you. All of the modules are built using partial files, named _module_name.scss and placed in the src/mini folder. You can edit any of the modules' code and/or add your own modules, following the same structure. The only thing you need to remember to do, in order to add your module to your flavor, is to add an @import statement after all the required variable declarations towards the bottom of your flavor file and it will be compiled along with the rest of mini.css. Similarly, to disable a module, just comment out its @import statement from the flavor file.

-
-
-

Variables

-

Everything in mini.css is based on Sass variables. We try to make our variable names as descriptive as possible, usually using names like $block-element-property-name, but some things might vary a little bit. Changing the values of variables should be reasonably easy, simply navigate to the src/flavors/flavor-name.scss file for a pre-defined flavor and you will see a list of variables that you can tweak. Change the values as you see fit and your finalized stylesheet will reflect the changes you have made. We did our best to make everything as customizable as possible, so that different people can build entirely different flavors using the same building blocks.

-
-
-
-
-

Code optimization

-

Building mini.css was no small task. Making it lightweight and customizable made things even harder, because these two things don't go well together most of the time. What we did was put more of the load on the preprocessor, instead of the final file. In order to accomplish this, we optimized as much of the code as possible, using conditions, flags and other tricks, so that compiling a flavor file might take one second longer, but loading won't. If you add any code to a flavor yourself, remember not only to make it customizable, but also to optimize it as best as possible.

-
-
-

Mixins

-

A lot of elements and components can be styled in many ways and most of the time we want a few styles to be available, without having to rewrite everything. We utilized the @mixin directive of Sass wherever we could to make it possible for you to easily create styles for pre-existing components and elements without having to tweak the base code for said elements or components. To use a mixin, simply @include it, passing values to at least its mandatory parameters. We recommend you write mixins wherever possible, if you create any new modules for mini.css.

-
-
-
-
-
-

Building a flavor

-

Creating your own flavor can be as easy or as complicated as your needs. Adding and removing modules is as simple as adding an @import statement or commenting it out, after declaring all the required variables. In this section, we will briefly walk you through most of the variables usually present in a flavor, along with some flags and mixins. This section serves as a complementary documentation to the comment column present in our pre-defined flavors, instead of a replacement and should be always viewed alongside it.


-
-

Core

-
-

The core module uses a lot of variables, most of which are pretty straightforward. Some of the most important ones are as follows:

-
    -
  • $fore-color - base text color
    • -
  • $back-color - base background color or image
    • -
  • $base-font-family - font stack
    • -
  • $base-root-font-size - font size of the page's root element, must be specified in px units
    • -
  • $base-line-height - base line height for the page's text
    • -
  • $body-margin - margin of the <body> element
    • -
-

Apart from the above variables, you should take note of the boolean $apply-defaults-to-all, which will reset font styling for all elements, utilizing the value of $base-font-size in the process. Certain elements like headings, horizontal rules and code blocks have some opinionated "modern" styles which can be turned on or off, using the boolean variables $make-heading-smalltext-block, $horizontal-rule-fancy-style and $add-pre-element-sidebar. The $style-samp-element and $include-dfn-fix boolean variables will either add styling for the elements they affect or completely omit it. This is part of the code optimization process, as most websites rarely use these elements. Finally, there are two boolean variables for link styling, $apply-link-underline and $apply-link-hover-fade.

-
-
-
-

Grid

-
-

The grid module contains three important variables, the booleans $use-four-step-grid which determines if the grid has 3 or 4 breakpoints and $include-parent-layout which determines if predefined layouts should be included and the integer $grid-column-count which determines the amount of vertical columns used for the grid's layout. Apart from those, there are a few variables that set the names for the grid system's classes, prefixes and suffixes and the grid's screen size breakpoint definitions.

-
-
-
-

Navigation

-
-

The navigation module contains a plethora of variables used in the styling of the navigational elements. Most of them concern colors, spacing and sizing or similar things. Bear in mind that the presentation of buttons inside the <header> element will be affected by the styling of all button elements, as defined in the input_control module. The variables that stand out in this module are $nav-sublink-depth which determines how deep a navigational hierarchy tree can be, along with the $include-header-sticky and $include-footer-sticky booleans that determine if sticky elements should be included for headers and footers respectively.

-
-
-
-

Input Control

-
-

The input_control module is one of the larger modules, containg a lot of variables to style a multitude of elements. Forms and textual <input> elements utilize variables that concern color, spacing, sizing etc. One important variable concerning forms is the boolean $include-fluid-input-group, whose value determines if fluid input groups will be available. Button variables are more interesting, especially the ones concerning the opacity of button elements ($button-back-opacity and $button-hover-back-opacity). The $hide-file-inputs boolean variable determines how <input type="file"> elements will be handled. Checkboxes and radio buttons also use a few variables concerning basic styling, but special attention needs to be paid to the $checkbox-size variable, as it determines a few attributes of both elements.

-

There are two mixins in the input_control module, specifically:

-
    -
  • make-button-alt-color - button color variants
    • -
  • make-button-alt-style - button size and spacing variants
    • -
-
-
-
-

Table

-
-

The table module's variables deal mostly with basic table styling. The $table-mobile-breakpoint is very important as it determines the breakpoint for responsive tables' mobile view, along with $table-mobile-card-label which determines the attribute that will be used to display the table headings on mobile devices. Finally, $include-horizontal-table determines if horizontal tables will be included.

-
-
-
-

Card

-
-

The card modules' variables mostly deal with things like class names, spacing, sizing and colors. Cards offer a handful of mixins, specifically:

-
    -
  • make-card-alt-size - card size variants
    • -
  • make-card-alt-color - card color variants
    • -
  • make-card-section-alt-color - card section color variants
    • -
  • make-card-section-alt-style - card section size and spacing variants
    • -
-
-
-
-

Tab

-
-

The tab module utilizes a few naming and color variables, along with some sizing and spacing variables to deal with presentation and functionality. Many of the sizing variables are very dependent on each other's values. The $tab-stacked-breakpoint variable is especially important, as it determines the mobile view breakpoint for the tabs component.

-
-
-
-

Contextual

-
-

The contextual module features, apart from basic naming and styling variables, a few things of note. The boolean variable $alert-include-animated determines if animated alerts will be inluded or not. Likewise, the boolean variable $include-tooltip determines if tooltips shoud be included. There is also a handful of mixins, which are the most important part of the contextual module as they are what makes it useful:

-
    -
  • make-mark-alt-color - mark color variants
    • -
  • make-mark-alt-style - mark size and spacing variants
    • -
  • make-alert-alt-color - alert color variants
    • -
  • make-alert-alt-style - alert size and spacing variants
    • -
  • make-tooltip-alt-color - tooltip color variants
    • -
  • make-tooltip-alt-style - tooltip size and spacing variants
    • -
-
-
-
-

Progress

-
-

The progress module contains lots of variables that affect basic styling, but it also features a few interesting mixins:

-
    -
  • make-progress-inline - inline progress variant
    • -
  • make-progress-alt-color - progress color variants
    • -
  • make-progress-alt-style - progress size and spacing variants
    • -
  • make-spinner-donut-alt-color - spinner donut color variants
    • -
  • make-spinner-donut-alt-style - spinner donut size and spacing variants
    • -
-
-
-
-

Utility

-
-

The utility module contains a few variables dealing with naming and basic styling, while some boolean variables like $include-floats, $include-clearfix and $include-center-block can be toggled on or off to enable or disable legacy features. The most important feature of this module, however, are its mixins:

-
    -
  • make-border-generic - generic border
    • -
  • make-border-radial-style - border radius variants
    • -
  • make-box-shadow-generic - generic shadow variants
    • -
  • make-margin-responsive - responsive margins
    • -
  • make-padding-responsive - responsive paddings
    • -
-
-
-
-
-
-
-

If you would rather use one of the pre-defined flavors, check out our flavors page for a list of all flavors currently available.

-
-
-
-
- - - - diff --git a/docs/customization/index.html b/docs/customization/index.html new file mode 100644 index 0000000..6bacd75 --- /dev/null +++ b/docs/customization/index.html @@ -0,0 +1,92 @@ + + + + + + mini.css - Customization + + + + + + + + + + + +
+ +
+ Introduction Modules + Flavors Customization + Quick Reference +  Github +
+
+
+ Core Grid + Navigation Input Control + Table Card + Tab Contextual + Progress Utility +
+ +
+
+
+

Customization

+

mini.css is built in such a way that customization is really simple. You could try out one of the pre-defined flavors, if you want, in order to get used to the framework and build something quickly and easily. However, many projects require custom styles and color palettes, which is when you need to get your hands dirty and start creating your own flavor by customizing an existing one and using mixins and variables to create your own, unique style for your brand or product. This page, along with the rest of the Customization section is aimed at developers who want to tweak the code provided with mini.css to create their own flavors for their projects, as well as active maintainers of the framework and people who just want to understand the inner workings of the codebase.


+

Use the menu at the top to quickly jump to the documentation of any module that you want to check out. We strongly recommend, however, that you read the general information provided below before you start exploring the modules' code, especially if you are not familiar with the way mini.css is structured.


+

+

+

Introduction & basics

+

mini.css is written using Sass, a very popular CSS preprocessor. We use Sass to do four things:

+
    +
  • Make the code modular
    • +
  • Create variables that can be changed on the fly
    • +
  • Optimize the code
    • +
  • Create reusable mixins
    • +
+
+
+
+
+

Modules & file structure

+

At the heart of mini.css are modules - groups of classes and styles that aim to solve one set of needs. There are 10 modules in mini.css, which have been already written for you. All of the modules are built using partial files, named _module_name.scss and placed in the src/mini folder. You can edit any of the modules' code and/or add your own modules, following the same structure. The only thing you need to remember to do, in order to add your module to your flavor, is to add an @import statement after all the required variable declarations towards the bottom of your flavor file and it will be compiled along with the rest of mini.css. Similarly, to disable a module, just comment out its @import statement from the flavor file.


+
+
+

Variables

+

Everything in mini.css is based on Sass variables. We try to make our variable names as descriptive as possible, usually using names like $block-element-property-name, but some things might vary a little bit. Changing the values of variables should be reasonably easy, simply navigate to the src/flavors/flavor-name.scss file for a pre-defined flavor and you will see a list of variables that you can tweak. Change the values as you see fit and your finalized stylesheet will reflect the changes you have made. We did our best to make everything as customizable as possible, so that different people can build entirely different flavors using the same building blocks.


+
+
+
+
+

Code optimization

+

Building mini.css was no small task. Making it lightweight and customizable made things even harder, because these two things don't go well together most of the time. What we did was put more of the load on the preprocessor, instead of the final file. In order to accomplish this, we optimized as much of the code as possible, using conditions, flags and other tricks, so that compiling a flavor file might take one second longer, but loading won't. If you add any code to a flavor yourself, remember not only to make it customizable, but also to optimize it as best as possible.


+
+
+

Mixins

+

A lot of elements and components can be styled in many ways and most of the time we want a few styles to be available, without having to rewrite everything. We utilized the @mixin directive of Sass wherever we could to make it possible for you to easily create styles for pre-existing components and elements without having to tweak the base code for said elements or components. Each module's mixins can be found in the corresponding _module_name_mixins.scss file in the src/mini folder. To use a mixin, simply @import its file and then @include the mixin itself, passing values to at least its mandatory parameters. We recommend you write mixins wherever possible, if you create any new modules for mini.css.


+
+
+
+
+

To read more about the inner workings of mini.css, please choose a module from the top navigation bar to view its documentation.

+
+
+
+
+ + + + diff --git a/docs/flavors.html b/docs/flavors.html index 542ac56..f387c49 100644 --- a/docs/flavors.html +++ b/docs/flavors.html @@ -25,7 +25,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/grid.html b/docs/grid.html index e4f9c33..0e943e5 100644 --- a/docs/grid.html +++ b/docs/grid.html @@ -30,7 +30,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/index.html b/docs/index.html index 0bd5b69..997c3aa 100644 --- a/docs/index.html +++ b/docs/index.html @@ -38,7 +38,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/input_control.html b/docs/input_control.html index d4ed7f0..715ac13 100644 --- a/docs/input_control.html +++ b/docs/input_control.html @@ -29,7 +29,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/modules.html b/docs/modules.html index 6c0b905..8f2a959 100644 --- a/docs/modules.html +++ b/docs/modules.html @@ -23,7 +23,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/navigation.html b/docs/navigation.html index 88cd14b..8597d97 100644 --- a/docs/navigation.html +++ b/docs/navigation.html @@ -28,7 +28,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/progress.html b/docs/progress.html index efbf76d..e7f3bb7 100644 --- a/docs/progress.html +++ b/docs/progress.html @@ -30,7 +30,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/quick_reference.html b/docs/quick_reference.html index 46dea5f..7687920 100644 --- a/docs/quick_reference.html +++ b/docs/quick_reference.html @@ -27,7 +27,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/tab.html b/docs/tab.html index 38960f5..6c1c583 100644 --- a/docs/tab.html +++ b/docs/tab.html @@ -28,7 +28,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/table.html b/docs/table.html index 6c1ace2..ef27506 100644 --- a/docs/table.html +++ b/docs/table.html @@ -34,7 +34,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/utility.html b/docs/utility.html index da1d668..abeaff8 100644 --- a/docs/utility.html +++ b/docs/utility.html @@ -28,7 +28,7 @@
Introduction Modules - Flavors Customization + Flavors Customization Quick Reference  Github
diff --git a/docs/v2/DEVLOG.md b/docs/v2/DEVLOG.md index 2639c1f..494b5d0 100644 --- a/docs/v2/DEVLOG.md +++ b/docs/v2/DEVLOG.md @@ -937,3 +937,6 @@ - Started developing `mini-lite` flavor (`lite`) as a very lightweight barebones base for the framework, using the default style for the most part. Size is under `5KB` for starters. - Updated `lite`, removed extra stuff, made it as simple as possible, still under `5KB`. - Tested `lite` using a quick demo in `Codepen` (*TODO* actually make a demo of it in a Codepen), no problems found, runs great. +- Started documenting the `customization` pages which will serve as a replacement for the old *wiki*. Created `index.html` in the new `customization` folder and added most of the basic info. +- Updated all old navigation links for `Customization` to point to the new folder and its `index.html` page. +- Removed content from old `customization.html` page and added a redirection directive to take visitors to the new page.