foxfirefey: A guy looking ridiculous by doing a fashionable posing with a mouse, slinging the cord over his shoulders. (geek)
[personal profile] foxfirefey
So, lately I've been doing a bunch of SASS work for our Foundation revamp. It can get tricky debugging CSS problems sometimes when the CSS is generated by SASS because the line output doesn't really have an easily found relation to the definition you originally made! Fortunately, there are ways to remedy this, so you can get the line number of the rule in the SASS instead of the resulting CSS.

First, you need to compile the CSS with source maps. It adds in the extra information to the CSS output for the debuggers that can read it. Add this to the bottom of config.rb, in dw-free and dw-nonfree, then recompile:

sass_options = {:debug_info => true}

Now you just need to enable the SASS line number output for the browser you are in. For FireFox, use FireSASS. Here are instructions for Chrome. I am sure other browsers have other methods!
fu: Close-up of Fu, bringing a scoop of water to her mouth (Default)
[personal profile] fu
Sooo I just filed a new bug to fix the contrast for some text on Foundation pages: http://bugs.dwscoalition.org/show_bug.cgi?id=5286

It seems like a good way to get started learning how to use Foundation/SCSS, so I'm putting it out here!
fu: Close-up of Fu, bringing a scoop of water to her mouth (Default)
[personal profile] fu

SCSS directory structure

All our SCSS files are in htdocs/scss/; compiled versions are automatically placed in htdocs/stc/css. We care about the former when editing, and the latter when including them in the webpage itself.

One of the things that SCSS is really good for is making it easy to organize CSS. I'd like us to move away from CSS for individual pages, and instead concentrate on having components that are used on multiple pages.

  • htdocs/scss/foundation - stylesheets from the Foundation library. The main files to touch here are foundation.scss, which specifies the components we'll be using on all pages, and _variables.scss, which sets default behavior / appearance variables that are common to all site skins.

    _variable.scss should not contain any colors, because we have to take into account dark-on-light vs light-on-dark skins. Sizes / measurements are perfectly acceptable here!

  • htdocs/scss/components - stylesheets for individual components. These are included only on the pages that need them, but contain all the styling that's required within. Everything here should have a corresponding example of the HTML structure over on /dev/style-guide

    This folder also contains Foundation components that aren't used on enough pages to warrant being included on all of them (htdocs/scss/foundation/foundation.scss), but that we still need on individual pages. htdocs/scss/components/progress-bars is an example.

    For components where you want access to variables, useful for things like line-height, include the following code at the top:

    $include-html-classes: false;
    @import "foundation/variables", "foundation/components/global";

    That won't work for colors though! Things that specify colors will have to go into the site skins.

    To use a component from a .tt file:

    [% dw.need_res( { group => "foundation" }, "stc/css/components/component-name.css" ); %]
    
  • htdocs/scss/mixins - mixins are fragments of code that can be used by multiple elements. Currently we have one mixin which hides elements visually but keeps them visible to screenreader. This replaces the... three or four different ways we were doing it before

    To use a mixin, from an SCSS file:

    @import "mixins/screenreader-friendly";
    .element-name {
        @extend %screenreader-friendly;
    }
  • htdocs/scss/pages - stylesheets for individual pages. Directory should mirror the URL structure of your pages as much as possible. But really we should try not to have anything here...

  • htdocs/scss/skins - stylesheets for site skins. Includes the actual skins and shared files, e.g., skiplinks, alert colors

JS directory structure

There's a lot more of the old JS hanging around in htdocs/js, but new files should follow the same basic structure as above:

  • htdocs/js/foundation - scripts from the Foundation library

  • htdocs/js/jquery - scripts from the jQuery / jQuery UI library

  • htdocs/js/components - individual components, suitable for inclusion on multiple pages

  • htdocs/js/pages - onload for individual pages; no examples yet. Preferably just the bare minimum of

    $(document).load( function() {
        $(".element").someComponent();
    

    } );

fu: Close-up of Fu, bringing a scoop of water to her mouth (Default)
[personal profile] fu

Found this quick intro to why sass. (For our purposes SASS == SCSS, which I talked about in my previous entry)

fu: Close-up of Fu, bringing a scoop of water to her mouth (Default)
[personal profile] fu

So I'm here to present to you all our new style guide. That's on my public dev server, not yet on dreamwidth.org, so don't worry if it's a bit slow.

That page contains the components that we'll be using across the site. The goal is to have every component documented there and to have as little per-page styling as possible. That does two things: make appearance / interactions consistent across the site (good for users); make it easy to refer to design decisions when writing pages (good for developers, especially those of us who aren't really frontend people)

We've used the Foundation framework as our basis for our redesign. That gives us a clean, responsive design that is really easy to make work on large and small screens -- we've had a huge problem with our site headers and certain pages on phones / tablets; it's about time to fix that.

I recommend going over the Foundation documentation btw. They have excellent documentation. It's a good way to get started.

All our Foundation work uses SCSS. SCSS is a CSS preprocessor and it works like CSS but with additional features. You can have variables, if statements, mixins (fragments of code that are used by more than one thing).

It requires an additional compilation step to get all this goodness, but that's possible with one command. Try the following:

  • pull in the latest changes on develop

  • Go to /dev/style-guide on your 'hack. It'll be completely unstyled

  • Run this command:

    compass compile
    

    A couple lines will scroll by, looking like this:

    ...
    create htdocs/stc/css/foundation.scss
    create htdocs/stc/css/normalize.scss
    ...
    create htdocs/stc/css/skins/celerity.scss
    create htdocs/stc/css/skins/gradation/gradation-horizontal.scss
    create htdocs/stc/css/skins/gradation/gradation-vertical.scss
    create htdocs/stc/css/skins/lynx.scss
    

    That's good: that means your SCSS files have been turned into CSS, which you can now use.

The SCSS files themselves are in htdocs/scss. These are the files you'll be touching. After they've been compiled, the generated files are placed in htdocs/stc/css. These are the files that you'll be including on the page.

So if you have a file:

    htdocs/scss/components/foo.scss

You include it by doing this:

    [% dw.need_res( "stc/css/components/foo.css" ) %]

One last thing, the compass compile command is good, but when you're developing, the last thing you want is to have to constantly switch from the file you're editing to your terminal window to run a command. Luckily, someone's thought of that. What you can do instead is this:

     compass watch

That watches for any changes in the SCSS files, and compiles them into .css files automatically. Leave that running in a separate window and it'll just do its thing. Just make sure you stop it after you're done developing for a session (just like you do with your Apache servers), because it does use up some resources!

Note: it's magical but not completely so. If you're working on something in dw-nonfree, you'll have to run compass watch separately in that directory:

    cd $LJHOME/ext/dw-nonfree
    compass watch

But if you're not touching anything in dw-nonfree, then you only need to run it the once.

Please jump in, poke around! Play with things. I'm happy to answer any questions :)

I plan on making several entries on the ongoing conversion. Soon to come: error handling for forms, directory structure for CSS / JS, easier way to format messages for email, etc.

Profile

dw_dev: The word "develop" using the Swirly D logo.  (Default)
Dreamwidth Open Source Development

March 2017

S M T W T F S
   1234
5678 91011
12131415161718
1920212223 2425
262728293031 

Syndicate

RSS Atom

Most Popular Tags

Style Credit

Expand Cut Tags

No cut tags
Page generated Mar. 26th, 2017 05:25 am
Powered by Dreamwidth Studios