loomcss 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9bafb0241e1e64d7707e380e064e7f1f17f90826
+  data.tar.gz: be482943e6db2b6ce17a6408a561467d5b98de6d
+SHA512:
+  metadata.gz: 9ec5ec232699d3373c8cb9e0e0eebc9d9536567979fd74657122d8221f9caf964d086ad245a9239d4269086e74424844c9e18866a14ce37c964ea262703c3941
+  data.tar.gz: d9026998087e2ae18be24ef263873d746584058229ff2f982ed57b6a030ee33c9cd42fb9113a66d69523f0b5ad0e5780dfcc983d65f9bcc0907eca439a4c8f0f

data/.gitignore

@@ -0,0 +1,16 @@
+.sass-cache/
+*.css.map
+
+node_modules
+
+css/
+
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.nvmrc

@@ -0,0 +1 @@
+v6.6.0

data/.stylelintrc

@@ -0,0 +1,6 @@
+{
+  "extends": "stylelint-config-standard",
+  "rules": {
+    "declaration-block-properties-order": "alphabetical"
+  }
+}

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in loomcss.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 Charlie Owen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,161 @@
+# Loom
+
+Loom lets you easily build your own design systems. Organised around [ITCSS](https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture/) it gives you a quick way of scaffolding sites, and then a more nuanced way of developing your own components.
+
+Highly modular, Loom lets you easily extend it with your own modules and classes.
+
+# Example
+
+```scss
+.c-fancy-button {
+  @include button(get-color(white), get-color(primary-brand));
+  @include font-size(large);
+  padding: get-spacing(xsmall) get-spacing(small);
+}
+```
+
+# Manifesto
+
+Loom's manifesto and opinions:
+
+- Loom tries to make things *easier* for a developer.
+- Loom doesn't come with a "theme" or a prebuilt pattern library. Loom helps you to weave _your own_ pattern libraries.
+- Loom is a tool and isn't designed to "drop in and go". It is something to help professional designer/developers in their everyday tasks.
+- Loom is very opinionated about:
+  - Being an integral part of a design system. Therefore in Loom all colour, spacing and font values originate from centralised settings and are accessed only via getter functions.
+  - Keeping styling separate from structure. Loom only provides minimal styling to HTML elements and leaves everything else up to classes.
+  - Keeping specificity low. Loom is structured around ITCSS, so a selectors specificity should come from its source order, and nothing else. That also means:
+    - No `@extend`s. These so, so, so easily mess up the source order of a project. Because ITCSS, the core of this, is source order dependent, it's best to avoid any use of `@extend`.
+    - No nesting. Loom really doesn't like nesting. Nesting makes for horrible specificity problems.
+    - No IDs. IDs make for even more horrible specificity problems. Just... no.
+  - Being modular. If you don't like the way something works in Loom, you can remove it or use your own module instead.
+- Loom doesn't care about:
+  - How you name your CSS selectors. Yes, it's opinionated about Sass structure, but kinda indifferent to your CSS output.
+  - Wether you want to use atomic or utility classes.
+  - Vendor prefixes - let's leave that up to Autoprefixer.
+
+# Installation
+
+Eventually this will be an npm module, a bower module and gem. For now it's installable via npm:
+
+```bash
+$ npm install loomcss --save-dev
+```
+Or go old-school and copy/paste the contents of the `assets` folder into your project. Hey, whatever works, right?
+
+# Usage
+
+Once installed, you will need to add the installation path to your own build system. This will probably be something like `node_modules/loomcss/assets`.
+
+Once you have made that folder available to your build you can access the Loom layers using:
+
+```scss
+@import 'loom/10-global-settings/misc';
+// etc
+```
+Please DON'T just link to `main.scss`! This will prevent you getting access to the interweaved layers of the ITCSS stack (it's there as an example only). Instead, copy [the list of imports](https://github.com/sonniesedge/loom/blob/master/assets/main.scss) from `main.scss` into your main project file. Yes, it feels unusual, but you'll gain a lot of power by doing so.
+
+This library is a basis for your own design system and won't give you much visually out of the box!
+
+# Organisation layers
+
+The Sass in the project is arranged in layers, with specificity and scope increasing as you decend from layer 10 to 100. Layers at the top (10) are extremely broad in scope and of low specificity, and those at the bottom (100) being extremely specific and high specificity.
+
+You can add your own layers, but the default ones are as follows:
+
+## 10 - Global settings
+Sass global variables. Should only contain those things used by multiple layers and modules.
+
+## 20 - Tools
+Mixins and functions to support the lower layers.
+
+## 30 - Generic
+Generic CSS, imported Normalize and Reset CSS. Things that aren't really visual, but have a lot of impact across the project.
+
+## 40 - Base elements
+Specific simple styling for base elements. Loom gives some extremely simple styling to those elements that have a standard visual "state" and are not normally styled with the aid of classes (`<p>`, `<ul>`, `<dl>`, etc).
+
+Headings (`<h1>` to `<h6>`) are the exception to this, as they are often used to provide semantic meaning, and so have their styling removed by default.
+
+In general styling for must be added via a module from the Objects, UI Components or Utilities layers.
+
+## 50 - Layouts
+Layer modules that provide layout-specific styling. They are used on *wrapper* containers that themselves contain Objects or UI Components.
+
+NOTE: Complications will likely occur if a Layout module and a lower layer module are used on the same HTML element!
+
+## 60 - Objects
+Complex chunks of CSS that are used as the base for UI Component modules. Each object is defined as a mixin and expressed as a class, and each class can be used on its own.
+
+The classes can be used for quick scaffolding, anchoring their classnames directly to CSS. (However, Loom opines that they should eventually be converted into UI Components, which directly consume the Object mixins. But Loom has some funny ideas and talks about The War a lot).
+
+Some things might stay as class-based objects, and be used as a base for skinning, in true OOCSS style. For example, `.button` can serve as the OO base for `.c-button` and `.c-button--primary`.
+
+```html
+<button class="o-button c-button c-button--primary">Continue</button>
+```
+
+Or `.c-button` might consume `@include o-button` directly:
+
+```scss
+.c-button {
+  @include button();
+}
+```
+
+```html
+<button class="c-button c-button--primary">Continue</button>
+```
+
+Your choice!
+
+## 70 - UI components
+These are highly visual components built from Object mixins, Loom settings and custom CSS.
+
+This layer will probably form the core of your own projects! :D
+
+## 80 - Utilities
+Utility modules provide classes that do one thing. While most visual styling should come from the component layer, there are always occasions where a separate class is needed to quickly nudge a component into shape.
+
+Loom thinks that these should be used with caution, and that excessive use of these implies that a component or setting is lacking.
+
+## 90 - Trumps
+"Trumps" as in "a trump card". Extremely high specificity selectors live here!
+
+Anything in this layer is used with some embarrassment. An example use might be to override CSS coming from external sources.
+
+The only layer that `!important` is permitted in a module.
+
+# Selector notation
+By default this project uses BEM notation for the optional CSS selectors.
+
+# Fonts
+You can specify fonts via the `$LOOM-fonts`. By default there is a `primary` and a `secondary` font. The default usage is secondary for headings and primary for everything else.
+
+Each of these has a `base` and a `webfont` variant. These are for use with a font-observer system, that will add the class specified in `$LOOM-fonts-loaded` to the HTML element, allowing webfonts to be used without FOIC occurring.
+
+# Naming conventions
+The naming convention for internal variables and classes is as follows:
+
+```
+object-property-variant-state
+```
+
+- `object` is the thing being operated on.
+- `property` is the aspect of object that is being altered.
+- `variant` is a version of the object.
+- `state` is a state change, such as being active, or a breakpoint.
+
+So examples of this might be:
+
+- `.margin-left-small {}` Object = margin; property = left; variant = small;
+- `$padding-top-large` Object = padding; property = top; variant = large;
+- `.button-background-primary {}` Object = button; property = background; variant = primary;
+- `$button-background-color-hover` Object = button; property = background-color; state = hover; (note that background-color is one word. Hyphens are used to match the CSS property naming convention).
+
+# Developing
+Always looking for fellow conspirators.
+
+# Reading
+- http://www.hongkiat.com/blog/basics-of-object-oriented-css/
+- https://www.sitepoint.com/atomic-oobemitscss/

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/assets/loom/10-global-settings/_box-sizing.scss

@@ -0,0 +1,5 @@
+/// Global box sizing setting.
+///
+/// @group 10-global-settings
+/// @type string
+$LOOM-box-sizing: border-box !default;

data/assets/loom/10-global-settings/_breakpoints.scss

@@ -0,0 +1,22 @@
+/// Definition map of breakpoint sizes.
+///
+/// Name your breakpoints in a way that creates a ubiquitous language
+/// across team members. It will improve communication between
+/// stakeholders, designers, developers, and testers.
+///
+/// @group 10-global-settings
+/// @type map
+$LOOM-mq-breakpoints: (
+  small:      320px,
+  medium:     740px,
+  large:      980px,
+  xlarge:     1300px
+) !default;
+
+/// Customize the media type (e.g. `@media screen` or `@media print`)
+/// By default sass-mq uses an "all" media type (`@media all and …`)
+///
+/// @group 10-global-settings
+/// @type String
+/// @link https://github.com/sass-mq/sass-mq#changing-media-type Full documentation and examples
+$LOOM-mq-media-type: all !default;

data/assets/loom/10-global-settings/_color.scss

@@ -0,0 +1,79 @@
+/// The central, default, global color list.
+///
+/// Retrieve theme colours defined here with get-color(name).
+///
+/// @group 10-global-settings
+/// @type map
+/// @example scss - Using a colour map
+///   $LOOM-colors-theme: (
+///     'brand-primary': #ed3d68,
+///     'brand-secondary': #30bbba,
+///     'white': #fff,
+///     'black': #000,
+///     'meta': #e4e4e4
+///   )
+/// @example scss - Using a colour map with predfined variables
+///   $color-pink: #ed3d68;
+///   $color-green: #30bbba;
+///   $color-light-gray: #e4e4e4
+///
+///   $LOOM-colors-theme: (
+///     'brand-primary': $color-pink,
+///     'brand-secondary': $color-green,
+///     'white': #fff,
+///     'black': #000,
+///     'meta': $color-light-gray
+///   )
+$LOOM-colors-theme: (
+  'black': #000,
+  'white': #fff
+) !default;
+
+/// Use your own colour map as the default global color list for use by the get-color() function.
+///
+/// @group 10-global-settings
+$LOOM-colors-list: $LOOM-colors-theme !default;
+
+// LOOM COLORS
+//
+// Okay, so you should always use get-color() when building your own system. However, Loom needs some "safe" colour variables to work with, as the colours defined in $LOOM-colors-list could be overridden by the end-user. These colours are used as to provide "default" defaults for several objects and mixins.
+
+/// Default color - black
+///
+/// Provide a default colour for some Loom objects.
+///
+/// @access private
+/// @group 10-global-settings
+$LOOM-color-black: #000 !default;
+
+/// Default color - white
+///
+/// Provide a default colour for some Loom objects.
+///
+/// @access private
+/// @group 10-global-settings
+$LOOM-color-white: #fff !default;
+
+/// Default color - medium gray
+///
+/// Provide a default colour for some Loom objects.
+///
+/// @access private
+/// @group 10-global-settings
+$LOOM-color-medium-gray: #999595 !default;
+
+/// Default color - dark gray
+///
+/// Provide a default colour for some Loom objects.
+///
+/// @access private
+/// @group 10-global-settings
+$LOOM-color-dark-gray: #444 !default;
+
+/// Default color - light gray
+///
+/// Provide a default colour for some Loom objects.
+///
+/// @access private
+/// @group 10-global-settings
+$LOOM-color-light-gray: #e5e5e5 !default;

data/assets/loom/10-global-settings/_icons.scss

@@ -0,0 +1,5 @@
+$LOOM-icon-sizes: (
+  'small': 0.5em,
+  'default': 1em,
+  'large': 2em
+) !default;

data/assets/loom/10-global-settings/_misc.scss

@@ -0,0 +1,89 @@
+/// Will object mixins have their own classes generated?
+///
+/// @group 10-global-settings
+/// @type boolean
+$LOOM-use-object-classes: true !default;
+
+/// Will utility modules have their own classes generated?
+///
+/// @group 10-global-settings
+/// @type boolean
+$LOOM-use-utility-classes: true !default;
+
+/// The default border-radius for various objects.
+///
+/// @group 10-global-settings
+/// @type number
+$LOOM-border-radius: 5px !default;
+
+/// The default border-radius for circular objects.
+///
+/// @group 10-global-settings
+/// @type number
+$LOOM-border-radius-circle: 50% !default;
+
+/// The default z-index layers used by the get-z() function.
+///
+/// @group 10-global-settings
+/// @see {function} get-z
+/// @type map
+$LOOM-z-layers: (
+  "top":          2,
+  "default":      1,
+  "below":        -1,
+) !default;
+
+/// The default list of breakpoints that is used to generate display-none classes.
+///
+/// @group 10-global-settings
+/// @type list
+$LOOM-display-none-breakpoints: (
+  small,
+  large
+) !default;
+
+/// The default time that all animations takes to complete.
+///
+/// @group 10-global-settings
+/// @type time
+$LOOM-transition-duration: 0.2s !default;
+
+/// The default timing/easing function that all animations will use.
+///
+/// @group 10-global-settings
+/// @type string
+$LOOM-transition-timing-function: ease-in-out !default;
+
+/// Default numbe of columns inside a grid container.
+/// @group 10-global-settings
+$LOOM-grid-columns: (12) !default;
+
+/// Default numbe of columns inside a grid container when combined with breakpoints.
+/// @group 10-global-settings
+$LOOM-grid-columns-responsive: (12) !default;
+
+/// Default gutter size for grid elements.
+/// @group 10-global-settings
+$LOOM-grid-gutter: xsmall !default; // NOTE: will be consumed by get-spacing()
+
+/// Breakpoints defined here will be used to generate breakpoints in the grid system.
+///
+/// @group 10-global-settings
+$LOOM-grid-breakpoints: (
+  'small',
+  'medium',
+  'large',
+  'xlarge'
+) !default;
+
+/// Default border width.
+/// @group 10-global-settings
+$LOOM-border-width: 1px !default;
+
+/// Default border style
+/// @group 10-global-settings
+$LOOM-border-style: solid !default;
+
+/// Default width of single-column content
+/// @group 10-global-settings
+$LOOM-single-column-width: 55rem !default;

data/assets/loom/10-global-settings/_spacing.scss

@@ -0,0 +1,20 @@
+/// Global list of sizing units
+///
+/// @group 10-global-settings
+$LOOM-spacing-list: (
+  'xsmall':     0.5rem,
+  'small':      1rem,
+  'default':    2rem,
+  'large':      3rem,
+  'xlarge':     4rem
+) !default;
+
+/// Change this to your own list if you wish. This is used by many functions as a default.
+/// @group 10-global-settings
+$LOOM-spacing: $LOOM-spacing-list !default;
+
+/// Default vertical spacing value.
+///
+/// Intended to be overridden by user choices.
+/// @group 10-global-settings
+$LOOM-spacing-vertical: 1rem !default;