su-sws / decanter Goto Github PK

View Code? Open in Web Editor NEW

39.0 27.0 8.0 33.06 MB

A collection of front end web resources.

License: GNU General Public License v3.0

JavaScript 37.04% CSS 1.65% HTML 61.31%

kss styleguide pattern-library

decanter's Introduction

Decanter

Version: 7

Changelog: CHANGELOG.md

Demo

To see a live demo of Decanter v7 elements please view the v7 demo site. For more documentation on Version 7 please visit https://decanter.stanford.edu

Description

Decanter is a web design and development system for Stanford University. It includes a responsive layout system and a browsable collection of design patterns that can be used in any Stanford project. For Decanter v7, instead of using SASS/SCSS with the BEM naming convention, we use Tailwind CSS to generate utility classes with some customization needed for our Stanford design system.

Assets

We have removed all assets from the repo in Decanter v7. Instead, we are using remote third party resources for our fonts and icons.

Fonts

We do not include any font assets with Decanter v7. If you want to use the Decanter fonts in your own projects, it is recommended that you use the font loading method that is optimized for your framework and only import the fonts that you need.
We provided two font css files that you can import into your own project so you get the latest update from us. font.css includes all the fonts that are referenced in the Decanter design system (sans-serif, serif, slab, monospace, Stanford ligature font for the logo). font-basic.css includes only the essential sans-serif, serif and Stanford ligature fonts.
For Source Sans 3, Source Serif 4, Roboto Slab, Roboto Mono - we include them using the @import method from Google Fonts.
The Stanford ligature font that we use for the logo is linked from the University Communications media CDN.

Icons

We have removed FontAwesome (dependency and asset) completely from Decanter v7. For those who would like to continue using FontAwesome, please feel free to do so and include them using methods that are suitable for your own projects.
We recommend using the heroicons package as Hero Icons are created by the Tailwind CSS team and are open source. They can be included as SVG or JSX elements.

Accessibility

This project conforms to level AA WCAG 2.0 standards as required by the university's accessibility policy. For more information on the policy please visit: https://ucomm.stanford.edu/policies/accessibility-policy.html.

decanter's People

Contributors

Stargazers

Watchers

Forkers

kgcreative epicfaace sparkbox chrispiech borisay iamrentman su-ucomm callinmullaney

decanter's Issues

Font Loading Strategy

Re: #4

Figure out a font loading strategy that is dynamic and light.
It would be nice to have conditional loads and on-demand imports.

Ems, Rems, and Pixels, Oh My!

I noticed you were resetting your body to 1em, so I wanted to give you a bit of insight regarding my decisions for font sizes.

REM units are calculated from the Root element of your document. This is the <html> element.
EM units are calculated from the EM element's parent (so in this case, if we set an em font-size on <body>, that size is calculated from the HTML parent.

In most browsers, the default font size is 16px. Most people, then, set a font size of 1em, or 100% on body.

In order to be sensitive to folks who may need larger font sizes for accessibility reasons, I prefer not to use any px units when declaring font sizes.

However, I find it a pain in the ass to have to constantly be dividing by 1.6 in order to figure out px -> rem conversions.

So:

$root-font-size: 10px (I set this so when I use the rem(16px) function from the unit conversion mixin, it calculates me down to 1.6rem) Most of the time, I don't really even need that. I know if I say font-size: 1.6rem that is equal to font-size: 16px.

Now, if I were to say:
html { font-size: $root-font-size } - that would technically do that for me.

However, because I want to be respectful of people who change their default browser font size (generally because they have accessibility needs) - Instead, I say:
html { font-size: 62.5% }

This means for 90% of users, html = 10px.

But, I don't want that for my responsive typography units. The CSS world pretty much exists in a 1em = 16px convention.

So.

Next, we have
$base-font-size: 16px
body { font-size: em($base-font-size, $root-font-size) }

Which gives us an equivalent of: body { font-size: 1.6em } (that is: 16px / 10px = 1.6)

$base-font-size is also the variable that them em() function uses in order to do px to em calculations.

With that set, then we can say:
p {font-size: modular-scale(0);} (equivalent to font-size: 1em)

and

p3 {font-size: modular-scale(3);} (equivalent to font-size: 1.953125 em -or- font-size: 31.25px, -or- 16px * 1.25 * 1.25 * 1.25)

We configured the modular scale increment in bourbon-settings, and in our case, we're using a 1.25 multiplier modular scale to proportionally grow and shrink all our fonts, as well as vertical rythm

What are the implications of this?

Well, we could, for example, set all our sizings, proportions, spacing, etc to be ideal in our LG breakpoint.

This gives us the minimal:

$root-font-size: 10px;
$base-font-size: 16px;

html {
  font-size: 62.5%; // proportionally equivalent to 10px
}

body {
  font-size: em($base-font-size, $root-font-size);
}

In the more advanced side of things, we can do something like:

$root-font-size: 10px;
$base-font-size: 18px;

html {
  font-size: 62.5%; // proportionally equivalent to 10px
}

body {
  @include grid-media($media-sm-max) {
    font-size: 1.6em; // 10px * 1.6em = 16px
  }
  @include grid-media($media-md-only) {
    font-size: 1.7em; // 10px * 1.7em = 17px
  }
  @include grid-media($media-lg-only) {
    font-size: 1.8em; // 10px * 1.8em = 18px
  }
  @include grid-media($media-xl) {
    font-size: 1.9em; // 10px * 1.9em = 19px
  }
}

p {
  font-size: 1em;
  }

.special-case-element {
  font-size: 1.5rem; // 10px * 1.5 = 15px
}

In the above example, paragraph text is 16px in small devices, 17px in the medium breakpoint, 18 desktops, and 19 on widescreens, but .special-case-element will always be 15px, regardless of it's parent element. The ONLY exception being if the user sets their user-agent to a different unit, in which case, that element will be proportionally equivalent to 15px. By doing the legwork in the HTML and body elements, our entire typography stack will proportionally grow and shrink as appropriate. Additionally, if a user sets their user-agent to a different font size than the default, we know that our entire font stack will respond gracefully to it.

Split up javascript in to individual components

Create accordion component (twig & sass)

Remove `grunt-contrib-sass` from npm dependencies.

sub-task of: #8

Create secondary navigation component (twig & sass)

Move alerts to proper atomic position in styleguide.

Pick atom or molecule

Create media block component (twig & sass)

Atom under SCSS

namespace rollup files

During integration, sometimes it's hard to know whether you are pulling a file from your own library, or from Decanter's. Refactor rollups to include decanter namespace.

Roadmap to Version 2.0

Version 1 has given us an opportunity to explore and learn about what this project should be. As a group we need to clearly define the goals of this project and be bound to our decisions. Please leave comments about the following topics.

Feedback / Lessons learned from version 1.0
High level goals for this project
Specific goals for this project
Other comments

From this thread we can then identify tasks and break them out in to tickets to put in to the project. If you don't have any comments specifically on any item just say as much and move along.

Thanks.

Add tables to the elements styleguide section.

Create a responsive table component or mixin

Create sidebar navigation component (twig & sass)

Secondary navigation component typically found in the left sidebar.

Notes:
There are slight visual differences between this element, and the dropdown/mobile navigation.

No light gray single pixel borders in between nav items
Level 1 text size should be 20px (instead of 18px)
I also don't think we need the extra padding to the left of the hover-state vertical border, as we do on mobile and on dropdowns.

Please also see the color tweak to the main navigation and mobile navigation here:
#422

Source: https://www.figma.com/file/Kmd4utmJFPRMVeCFEEBQhLtx/Stanford-Design-Library?node-id=2384%3A1177

In-page context for design:

Quote component

Determine if `decanter/themes` and `decanter/layout` need to exist

I can't think of anything that would go in themes/ or layout/ that we wouldn't address via a separate set of variables, or that wouldn't belong in base/, functions/ or mixins/

Those feel more like project-level folders. Let's determine if we should keep them, or get rid of them.

Add list styles to elements styleguide section

Colors and Typography in the Styleguide

Add grid system examples to styleguide

Create button 'atom' (twig & sass)

Please grant Alisha Ober access to this repo

Alisha Ober is the new front-end person in UComm. Please grant her access to this repo. Her github username is AlishaOber.

Create card component (twig & sass)

KSS global install

Find out wether or not this can be moved to a local install or document the heck out of it.

Add browser sync to grunt

Add live reload or some other tool for quick refreshed when working in decanter/lando

Refactor out third party vendor code and add as npm dependency.

This is a sub-task of: #8

Create skipnav component (twig & sass)

The skip link should be skip to content.

Add forms (input styles) as a section to the styleguide

This ticket needs to be broken up into the different form elements.

Add link styles to elements styleguide section

Create the ability to quickly and easily load Decanter's grid system without the rest of Decanter SASS.

sub-task of: #8

New Component: CTA button

Implement KSS as styleguide generator.

PR and discussion can be found here:
#53

Create main navigation component (twig & sass)

Establish a single main menu component with 1 variant. Design file TBD.

Breakpoint helper improvements

Breakpoint Helper should be changed to a mixin
It should consume a map
The mixin iterates over the map (a la responsive container) and outputs all the breakpoints and colors as defined in the map.

Responsive image component

File Naming conventions

This is something I noticed as i've been using neat much more extensively, and I think it's a pattern we can replicate.

_underscore variables, functions and mixins are meant to be private, and called from inside other functions/mixins. (Not file names, but the name of the actual mixin.)

For example:

the color function, calls a retrieve-color function.
This second function should be _retrieve-color.

If any mixins need internal variables, they should be _underscored.

This creates a system where, $variable, @mixin name(), @function name() are all intended to be used and called outside of decanter, while $_variable, @mixin _name() and @function _name() are all either called programatically, or used by our mixins. This helps us as developers to know what's intended to be called by the user, vs what we have available to use internally

Create alert messages component (twig & sass)

Create link 'atom` (twig & sass)

Investigate webpack

Investigate and prototype a structure for component based javascript.

Goal:

Submit a PR to add a javascript organization system.

Create and set "base" styles for html elements.

@josephgknox do you think this can be marked as done?

Shadow error

Whenever I compile sass, I get this error:

WARNING: Material shadow supports a range from 1-12, or the keywords "flat, shallow, medium deep"
Backtrace:
node_modules/decanter/core/utilities/functions/_material-shadow.scss:47, in function material-shadow
node_modules/decanter/core/utilities/mixins/_material-shadow.scss:28, in mixin material-shadow
node_modules/decanter/core/components/cards/_card.scss:43, in mixin card
patterns/molecules/simple-card/scss/simple-card.component.scss:13

WARNING: Material shadow supports a range from 1-12, or the keywords "flat, shallow, medium deep"
Backtrace:
node_modules/decanter/core/utilities/functions/_material-shadow.scss:47, in function material-shadow
node_modules/decanter/core/utilities/mixins/_material-shadow.scss:28, in mixin material-shadow
node_modules/decanter/core/components/cards/_card.scss:43, in mixin card
patterns/molecules/simple-card/scss/simple-card.theme.scss:13

The offending code is located in this mixin: stanford_components/node_modules/decanter/core/components/cards/_card.scss line 8: $material-shadow: null,

I don't think material-shadow likes null

I don't actually need to do anything with shadows or simple-card, I just experienced this non-fatal error when I compiled. Not sure if I should submit a patch?

Clean up KSS and SCSS comments for uniformity; ensure files are organized as desired

Right-size breakpoints and sections

in Homesite, we have three possible content widths: edge-to-edge, full, and content. - Those correspond, at XL breakpoints, to a "max-width" container, a smaller inset size for centered content (like news stories, or pages, without a side bar), and, edge-to-edge should be fairly self-explanatory.

I've also pretty much extended a modified version of bootstrap's breakpoints.
(xs, sm, md, lg, xl), with min, max, and 'only' variants to give us flexibility when implementing complex responsive design patters.

The breakpoints variable file also has a corresponding "sections" file, that map responsive behavior of content widths to breakpoints, to allow the centered section mixin to be able to programatically run through and automagically create sections as needed.

While all of those are configurable, the question is how opinionated we want to be in Decanter regarding those. Is that a good set of defaults? Should we provide more? less? other?

This is one of the more potentially complex aspects of the framework to document, explain, and implement, but I feel that once we have a good handle of it, it will make building complex layouts a breeze.

Figure out a way of making modules aware of themselves
Figure out a module loading strategy that is dynamic and light.
It would be nice to have conditional loads and on-demand imports.

Implement the Stanford color palette in SCSS using global variables.

Is this complete?