stadgent / fractal_styleguide_gent-base-archive

Archive for the styleguide for sites made by city of Ghent.

Styleguide Gent Base

This style guide contains the SASS library and needed assets to be able to style a web application in the corporate identity for the city of Ghent..

Roadmap

Style guide version 3.x

• A major overhaul with an entirely new style for all components.
• Probably a full CSS grid implementation throughout all the style guide components.
• We will probably drop jQuery in favor for native Javascript or another.

Upcoming: 2.7.x

• General changes and fixes to the style guide.

Licenses

If you are building something for the City of Ghent (Stad Gent) or Digipolis, you can contact the web team at Digipolis or open an issue here to get the necessary licenses thar are required for your project. For more info on what licenses you need see below.

License: Expressway font

The Expressway font is a paying font used by the style guide of the City of Ghent. It needs to be included through Typekit.

License: Light Gallery plugin for jQuery

It is important to note that anyone that wants to use this style guide or fork this repository for commercial purposes, should pay for a license!

Folder structure

When installing this package, you will get a directory structure like this.

.
├── CHANGELOG.md
├── LICENSE
├── README.md
├── build
│   └── styleguide
│       └── sass
└── package.json

The build directory contains all SASS source files and all asset files needed to be able to style a web application in the corporate identity for the city of Ghent..

Implementing this style guide in your own project

This style guide aims to be technology independent. This means you should be able to use it inside your project with any technology you want. It utilizes SASS to style its components, so you will have to use that in your project.

Setup

After installing the style guide through npm install gent_styleguide you''ll get a folder structure like this:

.
├── node_modules
│   └── gent_styleguide
│   └── breakpoint-sass
├── package-lock.json
└── package.json

Now, to use the style guide SASS partials you just need to import them into your main SASS file at the top so they get loaded before your own code.

@import 'node_modules/gent_styleguide/build/sass/00-settings/reset';
@import 'node_modules/gent_styleguide/build/sass/00-settings/vars';
@import 'node_modules/gent_styleguide/build/sass/01-mixins/**/*';
@import 'node_modules/gent_styleguide/build/sass/11-base/**/*';
@import 'node_modules/gent_styleguide/build/sass/21-atoms/**/*';
@import 'node_modules/gent_styleguide/build/sass/31-molecules/**/*';
@import 'node_modules/gent_styleguide/build/sass/41-organisms/**/*';

Note: we use this structure to allow you to override anything you wish in your own custom project. The way to do this, is to add the imports above to your main SASS file and add imports of your own overriding files in between.

If you don't need to be able to change the molecules for your project and instead just want to import the style guide and use it as it is, you can use the main.scss file instead of using the following approach.

Example:

@import 'node_modules/gent_styleguide/build/sass/00-settings/reset';
@import 'node_modules/gent_styleguide/build/sass/00-settings/vars';
@import '/sass/00-vars-overrides/**/*';
@import 'node_modules/gent_styleguide/build/sass/01-mixins/**/*';
@import '/sass/01-mixins-overrides/**/*';
@import 'node_modules/gent_styleguide/build/sass/11-base/**/*';
@import '/sass/11-base-overrides/**/*';
@import 'node_modules/gent_styleguide/build/sass/21-atoms/**/*';
@import '/sass/21-atom-overrides/**/*';
@import 'node_modules/gent_styleguide/build/sass/31-molecules/**/*';
@import '/sass/31-molecule-overrides/**/*';
@import 'node_modules/gent_styleguide/build/sass/41-organisms/**/*';
@import '/sass/41-organism-overrides/**/*';

Note: When using the style guide you will need to add breakpoint-sass as an includePath inside your gulpfile.js

Example:

    .pipe(sass({
      outputStyle: 'compressed',
      includePaths: ['node_modules/breakpoint-sass/stylesheets']
    })).on('error', sass.logError)

This includePaths path may vary depending on your setup!

Fonts

You need to make sure the Expressway font is included in your project somehow. This would be done by including the Typescript script in your project and requesting a license / Typekit kit from the web team at Digipolis.

Example:

<script>
  (function(d) {
    var config = {
          kitId: 'kgt4wbp',
          scriptTimeout: 3000,
          async: true
        },
        h=d.documentElement,t=setTimeout(function(){h.className=h.className.replace(/\bwf-loading\b/g,"")+"wf-inactive";},config.scriptTimeout),tk=d.createElement("script"),f=false,s=d.getElementsByTagName("script")[0],a;h.className+="wf-loading";tk.src='https://use.typekit.net/'+config.kitId+'.js';tk.async=true;tk.onload=tk.onreadystatechange=function(){a=this.readyState;if(f||a&&a!="complete"&&a!="loaded")return;f=true;clearTimeout(t);try{Typekit.load(config)}catch(e){}};s.parentNode.insertBefore(tk,s)
  })(document);
</script>

So in this example you would need to change the kitId to the ID you got from the web team of Digipolis.

Third party support

AngularJS CLI support (no SASS globbing)

We provide a main_cli.scss file that is essentially the same as main.scss, but includes all SASS partials the style guide needs without SASS globbing.

IMPORTANT

We recommend using the main_cli.scss file only when you need to support Angular CLI.

fractal_styleguide_gent-base-archive's Issues

Consideration: Using BEM (or a custom variant) to define classes throughout the styleguide

Should be use BEM or a custom variant of it to define classes inside the styleguide or not?
A change like this will require refactoring and might break subthemes!

No Typeahead functionality available

Is it possible to add a typeahead functionality to the library

Input type 'datetime' not working

The input type 'datetime' is not working as expecting.

https://stijlgids.stad.gent/components/detail/input-datetime.html

box-sizing: border-content doesn't exist

It should probably be content-box

Support for Angular CLI

The main.scss file uses import globbing statements, which is, by default, not supported for use with Angular CLI. Is it possible to create a main_cli.scss file with all the necassary references without globs?

Environment

• Version used: 2.7.0
• Project: Digitale Front Office Inname Publieke ruimte

Rewrite INSTALL.md docs to clarify how to implement the Stad Gent Styleguide.

We should clarify inside the Stad Gent Styleguide repo how to implement the styleguide in your project.

Keep mixins global or add to specific components?

Should we keep the mixins in a global folder or add them to their component specific folders in Fractal?

Re-enable MD033

Can be done when markdownlint/markdownlint#189 is fixed.

Add an automated check that checks WCAG2AA compliance

To make sure atoms, molecules, ... are WCAG2AA compliant.

Migrate grunt to gulp

Migration from Grunt to Gulp.

Proposition: Using a grid system like Susy.

Just an idea:
Using a grid system like Susy allows for better semantics. It also removes a lot of divs Bootstrap needs to define a grid. No more row wrappers are needed etc...
It generally makes the HTML cleaner.

Document globally defined mixins

Add option to extract sass library from this styleguide

What is in the scss folder and the public folder after grunt compile ATM. That should be an exportable/separate asset.

Restructuring of the current style guide.

I propose we change the structure of the style guide to the following:

• Global
  • Colors
  • Fonts
• Atoms
  • Headings
    • h1 (@H1)
    • h2 (@h2)
    • h3 (@h3)
    • h4 (@h4)
    • h5 (@h5)
    • h6 (@H6)
  • paragraph text (@paragraph)
    • small text paragraph text (@paragraph—small)
    • caption text (@paragraph-caption)
    • centered paragraph text (@paragraph—centered)
    • left paragraph text (@paragraph—left)
    • right paragraph text (@paragraph—right)
  • Button (@button)
    • default (@button—default)
      • sm (@button—default—sm)
      • md (default) (@button—default—md)
      • large (@button—default—lg)
    • inverse (@button—inverse)
      • sm (@button—inverse—sm)
      • md (default) (@button—inverse—md)
      • large (@button—inverse—lg)
    • highlighted (@button—highlighted)
      • sm (@button—highlighted—sm)
      • md (default) (@button—highlighted—md)
      • large (@button—highlighted—lg)
  • Image (@image)
    • default (@image)
    • no-styling (@image—no-styling)
    • circle (@image—circle)
  • Textfield (@Textfield)
  • Password (@password)
  • Date (@Date)
  • Datetime (@datetime)
  • Email (@email)
  • Url (@url)
  • File (@file)
  • Textarea (@textarea)
  • Checkbox (@checkbox)
  • Radio button (@radiobutton)
  • Select (@select)
  • Multiselect (@multiselect)
  • Icon (@ICON)
  • List (@list)
    • default (@list)
    • no-styling (@list—no-styling)
    • links (@list—link)
  • Logo (@logo)
• Molecules
  • Section (@section)
    • default (@section)
    • inverse (@section—inverse)
    • highlighted (@section—highlighted)
    • ascent (@section—ascent)
    • wrapper (@section—wrapper)
  • Island (@island)
    • Gentinfo island (@island—gentinfo)
  • Pagination (@Pagination)
  • Breadcrumbs (@breadcrumbs)
  • Disclaimer block (@disclaimer)
  • Post Address Block (@postaddress)
  • Search (@search)
  • Social media block (@socialmedia)
• Orgamisms
  • Header (@Header)
  • Footer (@footer)
• Templates
  • Index (general overview = all elements)
  • Grids overview
  • Images overview
  • Form elements
  • Icon overview
  • Islands overview
  • Blocks overview
  • Sections overview
  • Buttons overview
  • Lists overview
  • Molecules overview
  • Helper classes overview

By defining components and their variants in their own twig files we can start to reuse these components in other components with more ease, which allows us to better keep the style guide up to date and allows for better Drupal 8 integration in the future.

Some things to refactor:

• Give each component it's own handle name (defined in the component config file) for easier referencing in other components.
• Create templates to show of groups of components or entire pages as an example for people who want to integrate the style guide in their app.
• Make references to other components with the following syntax: {% include ‘@text-styles’ %}.
• Rename component subfolders and use the order key in their config files to define the Fractal navigation order.

Some references, inspiration:

• http://styleguides.io/examples.html

• http://ux.mailchimp.com/patterns/forms#buttons

• http://patterns.frostfinery.com/

Links inside h-tags should get styling

Currently when a h-tag (h1,... h6) contains a link it will be styled as a link...
This should be part of the heading atoms imo, that when they contain a link, they should style that link the same way as the heading atom it is in.

NPM installation fails

The installation of the package over npm still fails due to the postinstall script.
Can you please fix this?

Changing the way sections define atoms and molecules.

I propose a different approach on how we should let sections define theming for atoms, molecules and organisms.

In this article there is a section called "The block mixin approach".

The idea is that they use a SASS map where they define the colors that themes should override.
They also use a mixin themify() that automatically creates the CSS that components need based on a wrapper class (e.g. the section it's contained in).

This would let us create atoms, molecules and organisms without having to manually change code in the new-sections() mixin each time, thus removing duplicate code and making it easier to maintain the style guide.

It would then be the responsibility of the developer to include the themify() mixin for all properties of a component that need different theming based on the section they are in.
But once this is implemented, the code for all theme variations for that component would be compiled automatically by SASS.