www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/paragraphs/css/README.md

   1 ## Contributing to paragraphs CSS code
   2
   3 Paragraphs are currently using Gulp and SASS tools for more efficient CSS
   4 development. For the people that wants to contribute to paragraphs CSS code you
   5 have two options:
   6
   7 1. If you want to propose CSS improvement but do not want to use our Gulp/SASS
   8    toolchain then just change compiled CSS and create a issue with a patch from
   9    it. When patch is accepted we will then transfer your changes to SASS and
  10    recompile CSS files.
  11 2. Instead of manually changing CSS files, recommended way is to reuse our
  12    Gulp/SASS process and do changes in appropriate SASS files and then recompile
  13    it to CSS.
  14
  15
  16 ## Preparing your development environment for Gulp/SASS toolchain
  17
  18 If you want to do __step 2.__ but do not have needed Gulp/SASS experience do not
  19 worry, process is not that difficult and is explained in next steps:
  20
  21 - First thing you need to have is nodejs server on your machine. Please check
  22   https://nodejs.org/en/download/package-manager/ and follow steps of nodejs
  23   server installation for your operating system.
  24
  25 - Then change directory to paragraphs CSS folder
  26
  27   `$ cd paragraphs/css`
  28
  29 - Before compiling SASS files with gulp you need to install required
  30   dependencies with node package manager tool. In the same folder execute
  31
  32   `$ npm install`
  33
  34   The list of dependencies are defined in `paragraphs/css/package.json` JSON
  35   file.
  36
  37 - You are now able to compile paragraphs CSS from our SASS source files. In the
  38   same folder execute
  39
  40   `$ gulp`
  41
  42 If you did not get any error your local machine is now ready and with last
  43 command you already compiled paragraphs SASS files to CSS.
  44
  45 For closer look at our Gulp configuration and tasks check
  46 paragraphs/css/gulpfile.js.
  47
  48
  49 ## Doing changes in CSS over SASS
  50
  51 Now you are ready to do necessary changes to paragraphs CSS. First locate the
  52 CSS selector rule you want to change in CSS and then locate this rule in
  53 appropriate SASS file. Do the change in SASS file, save it and just execute
  54 again `$ gulp` from your console.
  55
  56 When you are satisfied with result in CSS files, create Drupal paragraphs issue
  57 and a patch in standard way.
  58
  59
  60 ## Making sure that your changes are aligned with CSS code standards
  61
  62 If you are getting warning when executing `$ gulp` that are coming from
  63 stylelint do not worry.
  64 This warnings are coming from stylelint postcss plugin which is doing statical
  65 checking of generated CSS files and this simply means that generated CSS code is
  66 not compatible with paragraphs CSS coding standards.
  67
  68 Generally before accepting SASS/CSS change you need to be sure that all warnings
  69 are fixed.
  70 But in some cases warnings can not be avoided, in that case please use turning
  71 rules off from SASS like explained in https://github.com/stylelint/stylelint/blob/master/docs/user-guide/configuration.md#turning-rules-off-from-within-your-css. Note that you can use also `//`
  72 comment syntax instead of `/* ... */`
  73
  74 You can also just run gulp sass lint task:
  75
  76 `$ gulp sass:lint`
  77
  78
  79 ## Resources
  80
  81 SASS is a very powerful tool and its always good option to know your tools
  82 better. Please check http://sass-lang.com/guide for more information on SASS
  83 syntax and it features.