Directory Structure
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();
} );