devbridge / styleguide Goto Github PK

License: MIT License

JavaScript 65.50% HTML 15.08% SCSS 19.42%

styleguide's Introduction

Styleguide

Devbridge Styleguide helps you create, share, and automate a living visual style library of your brand. Share your digital brand standards, improve team collaboration, and implement an independent easily-extendable modular structure.

Installation:

Make sure you have following components installed on your machine:

node.js
gulp or grunt

#1 Install Styleguide node package to your local project's directory:

npm install devbridge-styleguide --save-dev

Note, do not download files directly from git repository, unless you know what you are doing.

#2 Make sure you have installed it globally:

npm install devbridge-styleguide -g

#3 Initialize styleguide:

styleguide initialize

Note, make sure you run command inside your project directory.

Copy of the styleguide will be generated and placed in your project's root directory under '/styleguide/' folder. If you want to change folder name run styleguide initialize folder-name

#4 Setup Gulp task:

var styleguide = require('devbridge-styleguide');

gulp.task('start-styleguide', function () {
  styleguide.startServer();
});

If your styleguide is placed in different directory than /styleguide/ you need to specified it in the task:

styleguide.startServer({
    styleguidePath: 'folder-name'
});

Run styleguide server: gulp start-styleguide

For Grunt users:

Setup grunt task:

module.exports = function (grunt) {
	var styleguide = require('devbridge-styleguide');
	grunt.registerTask('start-styleguide', function () {
		var done = this.async();
		styleguide.startServer().then(function (instance) {
			instance.on('close', done);
		});
	});
}

Run styleguide server: grunt start-styleguide

For Plain CLI usage:

Enter command:

styleguide start

Note, the purpose of the styleguide server is to expose API for styleguide data manipulation ONLY. In order to view the styleguide in the browser, you need to setup and run your own project’s server. We recommend using simple http server - live-server.

Open your project in the browser and navigate to /styleguide/ directory. Happy styleguideing!!

Usage:

The Styleguide component has two modes - “view only” and “edit”.

"View only" mode does not have editing controls and is meant for presentation. It is a purely client-side application without any backend dependencies (html, css, and javascript only). It is delightly easy to share, publish, move, or export!

In order to switch to “Edit” mode and see all additional controls for editing, you need to run the styleguide server.

- To manage categories:

Categories can be managed on your styleguide web page by clicking menu in the right top corner. You will be able to create, delete or modify categories.

- To work with Snippets:

All snippet management is done in the browser, on your styleguide web page. While styleguide server is running, you should be able to see additional controls for editing.

- To scrape scss variables:

Scraping scss files you can automatically generate color palette or create a list of fonts used in the project.

First you need to add smart comment tags to your scss file to identify your variables:

For color variables:

//-- colors:start --//
$color-black: #000000;
$color-dark: #141823;
$red-lighter: #d26262;
//-- colors:end --//

For font variables:

//-- typo:start --//
$font-proxima: 'Neue Helvetica W01', helvetica, sans-serif; // 300, 700
$font-proxima-alternative: 'Neue Helvetica W01', helvetica, sans-serif; // 400, 400 italic
$font-newsgothic: 'Neue Helvetica W01', helvetica, sans-serif; // 700
//-- typo:end --//

Next, declare scss, less or styl file path references in styleguide config file:

"cssVariables": ["/path/to/your/project/scss/file.scss"]
Lastly, open styleguide web page and select from the menu 'Scrape Variables'. Note, make sure you have styleguide server running.

- To add CSS resources of the project to the styleguide:

Styleguide snippets are loaded through iframe using template.html file. All css references should be defined there.

- To modify styleguide settings:

You can add project name, project logo or change settings modifying config.txt file, located in your styleguide directory:

{
  "projectName": "", //Project name
  "projectUrl": "",  //Domain name of your project
  "projectLogo": "", //path to your project logo
  "jsResources": [], //Javascript resources that's going to be included into the snippets
  "viewportWidths": [ //Predefinded viewport breakpoints
    480,
    768,
    1200
  ],
  "serverPort": 8889, //Default server port for styleguide component
  "snippetTemplate": "styleguide/template.html", //HTML template which will be used to wrap and show html snippets. Project CSS resources of the project should be placed in this template as well.
  "cssVariables": [], //Paths to your scss variables files
  "maxSassIterations": 2000,
  "database": "styleguide/db",
  "categories": "styleguide/db/categories.txt",
  "uniques": "styleguide/db/uniques.txt",
  "sassData": "styleguide/db/sassdata.txt",
  "extension": ".txt"
}

styleguide's People

Contributors

Stargazers

Watchers

Forkers

valiooo joewellmade marufsiddiqui carlosvarela chaabni designtips hamnetdeui quatmo stanleyhlng ajay786singh nomli smillea alispx guypod sobingt sainraja montogeek nullnotfound fabianjaehnke sagarsys schmittjoh cybernetics llev seoyoochan tanzhengyu imraphox dany2or prakhar625 hafezoa motivemedia nuwud puterakahfi ridjohansen iamnotpd yashilanka pdw-studio iarnaud crearcdesign dnwhte kevinrodbe mpons iced-tea plainspace x472622902 laurenancona sourcemedium hackhackhackhack hackur yumyo sanhnx tusharkalan holdicon jqueryalmeida oliverastro kiina andrewkdouglas herus02 jrogodel webdesignberlin crudbug sanjeevpraja modulexcite ronniechong jpaulinoger gregorynicholas chrisemoulton konstantinskiy tobiasschmitz-prev diomari drinkcerealmilk sparkinzy leolujuyi spockbrat co0kie jamesvulling timothydang didgugan sahil505 chavince aldhous immanuelsun matt-daniel-brown domnic17 grace-snow spitfiresatya forklifters isabella232

styleguide's Issues

Review and remove uneeded ddependencies

Fix typography section (boldd, regular, italic) representation

Fix Sass scraping.

When scraping sass and there are variables referencing to other variables - app crashes, because somehow a function is inserted into colors object.

Add copy to clipboard functionality.

Add a button in snippet code preview to copy to clipboard that code.

Make "device" button active if clicked and deactivate if custom viewport is selected

Sort colors in color panel using RGB scale

Add devbridge favicon

Add config file

Styleguide component should have config.json file with following options:

admin Domains - a list of domains that allows to show edit functionality
categories - a list of categories of the snippets with unique id
watch urls - a list of pages that can be scraped or used for performance testing
css resources - [future feature] we need to provide project's css assets. We can scrape them directly from the site but then we need to define which domain is the main one.
path to styleguide
path to scss variables file

Add "Test component in layout" mode

Can be useful feature:

User defines urls to templates
Custom markers defines, where elements can be inserted into layout.
User can drag/drop and remove multiple items to defined area and component can be tested in real situations.

For example, you have home layout, and defined component area in header. You can grab a slider and drop it in header area and test how component works with layout.

create html template

Loading of font-awesome

Probably need to load font-awesome from cdn, if available. Because IIS refuses to serve .woff2 extension files by default.

create category file

Categories will be manages by config file.
Each category going to have separate file in which snippets information will be held.
On client side going to be list of categories in the header for navigation between the pages.

Clean up config

We need to include CSS resources into config file as manditory option because without CSS Styleguide component becomes useless. All other options could have default values and would be as optional options.

To have Styleguide up and running user would have minimal config like this:

{
    "cssResources":[
        "/site.css",
        "/webfonts.css"
    ]
  }

Full config with default options:

{
  "cssResources":[],
  "jsResources": [],
  "categories": [
    {
      "name": "undefined",
      "id": 0
    }
  ],
  "scrapeUrls": [],
  "sassVariables": [], //renamed from sassResources  
  "resolutions": [
    1200,1024,768,480,320  //removed naming
  ],
  "database": "styleguide/db",
  "uniques": "styleguide/db/uniques.txt",
  "sassData": "styleguide/db/sassdata.txt",
  "extension": ".txt",
  "maxSassIterations": 3,
  "snippetTemplate": "styleguide/template.html",
  "serverPort": 8000
}

Add transitions to iframes, then size is changed

Check validity of HTML in styleguide template

Ability to create new category from the browser

As of right now we can only create new categories updating config file. Would be nice to have such functionality in the browser.

Move creation form to top of snippet

Change edit icon

Change edit icon, Now it looks like settings

Add default snippet wrapper css to all snippets edit mode

snippet {

}

Show warning message when invalid (css/html) snippet is submitted for the first time

For the first time, show warning message and prevent snippet submission. Let user force snippet submission on his own risk.

Variables assigned to colors are not visible.

We don't see variables assigned to colors in color pallete after new theme.

Copying of png files

Need to fix copying of your-logo.png, because it becomes corrupted after copying.

Check viewport assigment function if it returns correct results

http://stackoverflow.com/questions/19291873/window-width-not-the-same-as-media-query

Live snippet editing feature

Typing code and Inline css, snippet view should auto update

Create snippet functionality

Snippets will have following information:

Name
Unique id
Category name (Snippet can be assigned to only one category)
Snippet code
Description (optional)
Inline CSS (optional)

Manual snippets creation and modification will done via browser window:

Creating new snippet we need to generate unique id. We could have dedicated json file, where we could retrieve and store snippets ids.

Snippet is not visible when editing.

Now, when in edit mode - snippet is not visible, so the live css/html editing feature is useless, we can't see the changes we are making.

Setup free npm account

Remove deleted snippets category

We need to remove deleted snippets category from category list. Users can access deleted page if needed but it would be invisible from navigation.

Create scss scrape functionality

Path to scss files will be defined in config file
To identify variables types comments will be used e.g.
//-- Color:begin --//
$color-red: #ff0000
//-- Color:end --//
//-- Fonts:begin --//
$font-avenir: 'Avenir W01', sans-serif;
//-- Fonts:end --//

Create snippets scraping functionality

We need to have a away automatically create and update snippets. We going to wrap our snippets with html comments so we could later check if they were modified e.g. snippet code .

Apply project css to home page typography section

Typography section should be hardcoded and should reflect project default headings and body styles

Home page if no sass scrape available

If sass variables are not scraped we still need to show about and typography sections to the user.

Add success/error messsages if snippet is created/removed/edited

Separate width from width units in resizing input (overhead changing values)

Add item count in category menu

In category meniu, we should display numbers of items in category.
Especially, this will be helpful for undefined category.

Sort undefined category to the end of the list, change visual apperance to stand out from other items.

Improve setup process

We need to improve setup process.
I think step by step guidance is not needed because most of the users want to get straight to config file.
We need to determine most critical steps that require styleguide to work.
As of right now, i see following flow:

download and install module.
setup config. It could be a part of start-styleguide task. Also, we need to cleanup config file, make it simpler, I will create new topic about that.
start server.