Dreamwidth Development

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();
  

  } );

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.