ubccm / ubc-def Goto Github PK
View Code? Open in Web Editor NEWUniversity of British Columbia Digital Experience Framework (previously known as UBC-CLF)
License: MIT License
University of British Columbia Digital Experience Framework (previously known as UBC-CLF)
License: MIT License
Please perform a cursory search before reporting an issue.
Describe the bug in detail
The current gulp task runner has lots of vulnerable dependencies, as reported in Snyk and Github security. Some of these dependencies are not recommended anymore as they haven't been updated by the maintainer for over a year.
Latest vulnerabilities:
To Reproduce
Steps to reproduce the behavior:
Run "npm audit" to get currently list of vulnerable packages reported by Snyk.
Expected behavior
Update and replace vulnerable packages
Right now, we have the following structure:
src > sass > MAIN.scss
This adds all scss files, and when gulp is run, resaves it as:
I'd like to propose we change the naming and change the gulp task to do things slightly differently.
Name: we should use a much more generic name for the output. And, ideally, use the same name for input and output to aid in clarity. I suggest styles-all.scss
. This would be accompanied by a styles-minimal.scss
file that outputs the bare minimum of base styles and helpers.
Gulp Task: we should remove the explicit file references and allow the tasks to be run on any scss/sass files in the src directory. We should also include a file to allow a single component or set of styles (ie. grid) to be rendered on its own. These should be kept in the same directory as the component itself and simply include the needed @import
statements.
We should also indicate that file versions with sourcemaps (and the sourcemaps themselves) are not for deployment. I suggest adding a .dev suffix to the filename to indicate this, but perhaps moving them to a subdirectory would make more sense. Minified versions of files get a .min suffix.
The minify task may be irrelevant if we do this (and we'd want to come up with a better task name than 'components', but it will do for illustration purposes).
If we do this, the result would be:
src > sass > styles-all.scss
compiles to:
And components such as:
src > sass > components > component.navigation.drawer.scss
compile to:
I'll attach a pull request with the proposed changes to the dev branch.
Please perform a cursory search before reporting an issue.
Describe the bug in detail
The current gulp task runner has lots of vulnerable dependencies, as reported in Snyk and Github security. Some of these dependencies are not recommended anymore as they haven't been updated by the maintainer for over a year.
Vulnerable packages:
To Reproduce
Steps to reproduce the behavior:
Run "npm audit" to get currently list of vulnerable packages reported by Snyk.
Expected behavior
Update and replace vulnerable packages
Is your feature request related to a problem? Please describe.
The current defined browser support list, last 6 versions
, support browsers that are not officially support by the vendor (e.g. IE 6, IE Mobile 10, etc). Would suggest to revisit the list of browser support for autoprefix.
Describe the solution you'd like
With the direction of supporting all browsers > 1.5% global usage, would suggest the following autoprefix support.
defaults
- Browserslist’s default browsers (> 0.5%, last 2 versions, Firefox ESR, not dead)
Describe alternatives you've considered
> 1.5%
global usage will only cover 77.96% of browsers, above defaults will support the last two versions of all active browsers.
Is your feature request related to a problem? Please describe.
The project currently has no handling for javascript. As Bootstrap is not being used and jQuery is something we want to avoid, we need to identify and implement a suitable replacement.
Describe the solution you'd like
I think there are several parts to this initial step:
Bootstrap 2 (current) | Needed (TBC) | Material | Gov.UK | USWDS | AGDS | Bootstrap 4 |
---|---|---|---|---|---|---|
affix | N (sticky) | N | N | N | N | N (deprecated I think) |
alert | Y | Y (Dialog, snackbar) | Y (warning) | Y | N | Y |
animation | ? | Y | N | N | Y | N (deprecated I think) |
button | ? | Y | ? | N | N | Y |
carousel | Y | N | N | N | N | Y |
collapse | Y | Y | Y | Y | Y | Y |
dropdown | Y | Y | N | Y | N | Y |
modal | Y | Y (Dialog) | N | N | N | Y |
popover | Y | Y | N | N | N | Y |
scrollspy | ? | N | N | N | N | Y |
tabs | Y | Y | Y | N | N | Y |
tooltip | ? | N | N | N | N | Y |
Other | ||||||
Snackbar | ? | Y | N | Y (toast) | ||
Drawers | Y | N | N | |||
Progress bar | ? | Y | N | Y | ||
… |
Framework | Complete (as per above) | Modular | Well-documented | Easy to use | License | Well maintained | Dependencies | Light | WCAG 2.1 |
---|---|---|---|---|---|---|---|---|---|
Material | Almost | Y | Y | node | MIT | Y | N | N | |
Gov.UK | N | Y | Y | node | MIT | Y | Y | Y | |
USWDS | N | Y | Y | node | Mixed MIT, SIL, Public Domain | Y | Y | Y | |
AGDS | N | Y | Y | ? | MIT | Y | Y | Y | |
Bootstrap 4 | Y | Y | Y | Y | MIT | Y | jQuery, popper.js | N | ? |
Material.io https://github.com/material-components/material-components-web
Gov.UK https://github.com/alphagov/govuk-frontend
USWDS https://github.com/uswds/uswds
ACDS https://github.com/govau/design-system-components/
Bootstrap 4 https://github.com/twbs/bootstrap
This could be altered depending on the approach we take, but my assumption at this point is we will need Babel and one of jslint / eslint / etc.
Describe alternatives you've considered
It is possible to write our own js from scratch, but this seems like a worst case scenario in terms of initial and ongoing effort.
Problem
CSS naming and style conventions are difficult to manage without a collective understanding of how to approach alterations and additions. Additionally, namespace collision between various frameworks and contexts can collide if no rules exist to take this into account.
Proposed solution
With that in mind, I propose we adopt the following naming conventions:
Components (ie. accordions, cards) use BEM, ie.
.accordion__content--small
BEM has been agreed upon by the project team as a strategy for dealing with components. It is especially well-suited to minimize scope and provide a standard set of rules to extend with variants when needed.
Utilities are hyphenated when required, ie.
.text-small
Utility classes are not suited to the BEM convention as they are intentionally abstracted from structure. .text-white
is not and should not be confined to a particular component or markup structure (as is required by BEM).
Javscript class hooks are prefixed with .js-
, ie.
.js-reveal__trigger
For clarity, hooks for javascript classes should be kept separate from styling considerations.For example, when clicking a button turns an element blue, the javascript event modify attributes of the target element (adding a new .text-blue
class for example) as opposed to inserting those styles into javascript. The javascript class itself should contain no styling (such as toggling between display: none;
and display: block;
).
Media query classes are prefixed with the query and two dashes, ie.
.md--text-small
State based utilities are comprised of a prefix followed by two dashes. This makes some sense through a BEM structure (the --
indicates a modifier). States are based on media queries, hover, focus, group-hover (state changes in child elements when the parent is hovered over).
Additional context
Another convention to further reduce scope and prevent namespace collisions would be to prefix all styles. For example, .text-white
could become .ubc-text-white
. I think this is still an outstanding question as to whether or not this is necessary, so I've not proposed a prefix above. If we do decide to do this, it would best be done via postcss.
Problem
The dev toolchain for updating and contributing styles and markup is unnecessarily complicated could be a barrier to contributors. Sass requires a level of expertise beyond vanilla CSS.
Additionally, gulp is increasingly being dropped (and support becoming more of a concern) for packages that don't require the additional layer of interpretation (ie. gulp-sass vs node-sass).
Proposed solution
As we've discussed internally, removing gulp and migrating to node packages is a better long term solution in terms of support and reducing dependencies.
Packages I'm suggesting are:
postcss-cli - adds cli commands
postcss-custom-properties - allows the use of CSS variables (--color-primary: #5c6ac4;
) with fallback for unsupported browsers.
postcss-import - allows the use of @import to concatenate CSS files
postcss-simple-vars - allows the use of sass-like variables in CSS - $myvar
syntax
We will already be using postcss for autoprefixer (tailwind, purgecss).
The sample package.json is here and the sample postcss.config.js is here.
Alternatives considered
Vanilla CSS
This is unsatisfactory as we don't have the ability to run basic checks. It will leave us in our current (CLF7) state.
Additional context
None
Problem description
Breadcrumb navigation provides persistent navigation that is intended to reflect the user's current 'depth' within the website's page structure. It is not intended to serve as primary navigation, but rather supplement it.
Typically, the navigation appears early in the page to orient users prior to engaging in the page's content.
Proposed solution
https://codepen.io/occupant/pen/rNVpGbo
https://www.w3.org/TR/wai-aria-practices-1.1/#breadcrumb
Breadcrumb navigation should be contained within a nav
element (the landmark) with the aria-label="breadcrumb"
attribute applied. Individual links should be presented as items in an ordered list (ol
) with the final list item providing a link to the current page and having the aria-current="page"
attribute attached to the a
element.
Each breadcrumb element has a separator to aid in isolating the links visually, however the separators are rendered using pseudo elements to prevent screen readers from interpreting them as text.
Alternatives considered
None
Additional context
https://codepen.io/occupant/pen/rNVpGbo
Special consideration should be used to ensure the navigation aid is used in a reasonable space before primary content so as not to confuse it for other navigation contexts or mechanisms.
Feature Review Checklist:
The open nature of the project means a clear workflow is required for reviewing and approving changes to the project. The danger is that we don't have a clear or timely approval system, so there's no clarity on what constitutes an acceptable PR, who needs to approve it and what criteria they should use.
A clear set of steps / requirements for submitting a change / fix / enhancement.
Problem description
One of the most used components in the current CLF, the accordion allows content editors to create collapsible content regions.
The accordion component allows for progressive disclosure of content that is intentionally triggered by the user and allows the content editor to display critical content first.
Proposed solution
Accordions can come in two varieties:
The proposed solution is keyboard accessible. If the requisite JavaScript fails(or is slow) to load, the content will default to be visible - i.e. all accordions on the page will be in their 'open' state.
Consideration for responsive behaviour
There is no special responsive behaviour considerations as the width of the accordion is the width of its containing element.
The proposed solution uses class-based triggers. There will need to be extra considerations made to allow for unique IDs to be passed in a URL to be able to link to a specific accordion (and open it).
The entire title-containing element - a heading tag - should be a trigger to open/close its attached content container. The proposed solution incorporates a button element within the title element in order to provide as accessible a component as possible.
Tabbing to an accordion title will give that title focus and pressing the space bar or return will trigger the accordion.
Content within an accordion should not be focusable without the accordion being in its active state.
The accordion components allows for nested accordions with recommendations for the nested accordion titles to be one level of heading tag lower than its parent.
Consideration for accessibility
aria-expanded
on the button(within the heading) is toggled depending on the state of the accordion.
The hidden
attribute on the accordion content container is toggled depending on the state of the accordion. For browsers that do not support this attribute, display: none;
is toggled via CSS.
In terms of visual indicator, a plus/minus icon is appended to each accordion's title. This is done via CSS and is therefore override-able by developers using this component.
Alternatives considered
Using https://github.com/matthiasott/a11y-accordion-tabs as a homogenous component which would work across tabs (which condense to accordions on smaller screens) and the two accordion scenarios outlined above was considered.
However, a11y-accordion-tabs
enforces a grouped behaviour which was considered a blocker for this component.
Additional context
For demo, please see: https://codepen.io/richardtape/pen/abOEyWw
Feature Review Checklist:
I've created a branch (https://github.com/occupant/ubc-clf8/tree/integrate-travisci-snyk) with Travis CI integrated that does a few simple things on every commit.
npm install
task with both the latest stable release and v.4 of node (our minimum as per our current dependencies).gulp styles
and gulp minify
tasks.This is really just the simplest integration - we could also have it kick off some tests with Saucelabs once there are some visual front end elements to test.
Adding as an issue so we can discuss as a group.
Assuming we've landed on MIT. I've attached the current MIT license boilerplate
LICENSE.txt
Problem
We would benefit from a CI tool to automate testing and eliminate manual checks wherever possible. This should be a service that is free for open source projects, without unrealistic limits for activity.
Proposed Solution
A POC was created in a retired branch with Travis and Saucelabs, but more investigation is required to find a relatively simple, extendable solution. Possible candidates are:
Saucelabs
Browserstack
Snyk
Alternatives considered
Additional context
Problem description
A badge provides a consistent visual labelling system for inline meta information. i.e. Number of articles, highlighting when something is 'new' etc.
Proposed solution
https://codepen.io/richardtape/pen/QWbaqEd?editors=1100
In its isolated form, the badge component has practically no unique accessibility considerations (beyond what is expected for all components in the DEF) - it's simply a box with some text in it. However, for the vast majority of the time the badge component will be providing meta information to the item that surrounds it and thus will need to include appropriate attributes or content that give the badge context.
The proposed CSS for the badge component uses inline-flex as value for the display property. This will make vertically centring this component within a parent element considerably easier.
Alternatives considered
https://getbootstrap.com/docs/4.4/components/badge/ and https://github.com/DavideTriso/aria-badge were looked at and both provide the same markup and considerations that is provided in the proposed solution here.
Additional context
https://codepen.io/richardtape/pen/QWbaqEd?editors=1100
The badge component as proposed here differs slightly from the CLF 7 badge component which used the label
class, which caused issues with the label
element in some contexts.
Feature Review Checklist:
Problem description
The current design spec defines a series of button styles and ways to extend. We need to define, code and document the method for adding these consistently with a variety of markup (ie. a
, button
, p
, div
tags).
When adding icons within / before / after buttons or links, we additionally need to decide if these are inline elements (ie. an svg, which would allow any image to be added) or a set of background image elements (meaning we will have a limited set of icons that will be managed and included with CSS).
Proposed solution
In an initial attempt to replicate these styles, I have taken the approach of constructing these styles with an additive approach. For example, to produce this:
Instead of single class to output all required styling:
.unit-button--blue-w-envelope-separator
I've used a series of classes that can be combined as required:
.unit-button unit-button--light unit-button--has-icon-right unit-button--has-separator-right
and an inline svg for the envelope.
eg.
<a href="#" class="unit-button unit-button--has-icon-right unit-button--animate-icon unit-button--light">Unit button: light <svg role="presentation" class="unit-button__icon" viewBox="0 0 64 64"><use xlink:href="#icon-arrow-circle"></use> </svg></a>
<button class="unit-button unit-button--has-icon-right unit-button--animate-icon unit-button--light">Unit button: light <svg role="presentation" class="unit-button__icon" viewBox="0 0 64 64"> <use xlink:href="#icon-arrow-circle"></use> </svg></button>
We could provide a few classes to simplify common use cases (a button with an arrow on the right) as a compromise between simplicity and flexibility.
Additional context
Example css can be found here. Example markup can be found here.
Problem
As part of a modern shared web dev toolchain, a linter is a critical tool for maintaining CSS consistency and cleanliness. It can help identify and prevent common issues from moving into production code, as well as make the code more readable.
Proposed solution
There are number of packages we could consider. The most commonly used are listed on npm trends.
I suggest using stylelint for now, as it is very well maintained, has a well-established community with pre-built configurations that can be extended as needed. Additionally, unlike a tool like sass-lint that simply reports errors, there is a flag that can automatically fix most errors. This can be done within many filetypes (sass, less, css, js, etc), although some require postcss.
Alternatives Considered
Previously we considered sass-lint, however this package is currently unmaintained.
clean-css currently has more downloads and looks to be very well used, however I'm admittedly not as familiar with it. It looks to be very flexible, however I haven't come across something similar to the shared configurations (meaning we manage more). Totally open to discussing this though.
Problem description
Spinner is a UI component to indicate the loading state of certain actions inside application such as Initialization, Async request and etc.
Proposed solution
https://codepen.io/xucongzhe/pen/WNvdZWX
The spinner component is simply a container with screen reader text in it. The animation is done by CSS which is overridable by developers.
Accessibility consideration:
Alternatives considered
https://getbootstrap.com/docs/4.4/components/spinners/ and https://codepen.io/stuartjnelson/pen/xWyLGR share simillar markups, the later one provides better accessibility.
Additional context
Feature Review Checklist:
Type should follow a rhythm / scale. Suggest using: http://devinhunt.github.io/typebase.css/ (https://github.com/devinhunt/typebase.css/blob/master/src/typebase.scss) as a starting point. It has a SCSS version, defines type in REM units and is light.
Current Usage:
https://caniuse.com/#feat=rem
As a sample:
https://github.com/occupant/sass-lint/blob/develop/CONTRIBUTING.md
This is much more restrictive than we need to be, but has some interesting ideas, esp. the Developer Certificate of Origin. Basically it's asking you to go through self-verification.
The git message guideline are also nice - recommended tense (present, declarative I think?).
Problem description
Content editors often have the need to highlight content to inform users of something important or specific. An alert or message component provides a way for content editors to bring some piece of content to a user's attention.
Success messages (i.e. for form submissions), alerts, and error notices are examples of why this component would be useful.
Proposed solution
https://codepen.io/richardtape/pen/LYVeOPE
The role
of status
is used to afford users of assistive technologies the ability to be updated when a status change happens on the page in a non-obtrusive, yet still-useful way. As per: https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA22.html
Inline SVG icons are used as part of an icon set (specifically limited to one icon in this proposed solution) to allow for the commonly used svgs to be cached and used with ease across different use-cases.
There are some small responsive behaviour considerations with regards to padding and the size of the icon for smaller screens, but in general this component appears and is used in a practically identical way regardless of screen size.
There will need to be JavaScript to hide each instance of this component on the screen. Additional considerations include the ability to 'remember' this action so that the same instance of that message isn't shown upon page refresh for a user who has explicitly closed that alert/message.
Alternatives considered
This proposed component is practically identical to the examples provided by the w3.
Additional context
https://codepen.io/richardtape/pen/LYVeOPE
Feature Review Checklist:
I must have glossed right over this, but I don't think this is correct:
indent_style = tab
indent_size = 4
I think it should be either:
indent_style = space
indent_size = 4
or just:
indent_style = tab
Problem description
When creating web pages and applications, a button style is needed to visually emphasize possible user actions. These styles are applied as an addition to already interactive elements such as links and user inputs.
The button style is expected to remain visually consistent across several different HTML elements, including, but not limited to:
a
button
input[type="button"
], input[type="reset"]
, input[type="submit"]
Proposed solution
https://codepen.io/occupant/pen/WNvZrLO
The button style relies upon a base class of unit-button
. This class provides the default styles for all other button variants but has very few style decisions attached to it. Visual space is provided with some default padding
, The background-color
is inherited, a border of 1px is defined and the button is set to display as an inline-flex
item, which aids in text alignment and icon / trigger placement within a button.
Additional styles are for color / style:
unit-button--light
unit-button--dark
unit-button--simple
for layout:
unit-button--block
for internal elements
unit-button--has-icon-left
unit-button--has-icon-right
unit-button--has-separator-left
unit-button--has-separator-right
and for child elements
unit-button__icon
Additional styles required can be added via utilities as needed (ie. text-lg
, bg-black
, text-white
, md--text-3xl
).
Responsive behaviour considerations
By default, the base styles for buttons would have no preference for font-size or line height - these would be inherited by the page styles. Modifications would be applied with utilities. The utilities are responsive in nature, so we can alter any styling or behaviour based on viewport.
Accessibility considerations and test conducted
WCAG 2.0 AAA check passes
The title attribute (for a and button tags) is not recommended - instead, descriptive, meaningful text should be used.
Color variables supplied in the button component are not assumed to be final, and are easily overridable by redeclaring the CSS variable. However, as tested, they are AAA accessible.
Alternatives considered
Alternatives considered have been eschewing the additive base-class + modifier-class approach for a more fully-controlled single class payload with all styles defined. This would be preferable if there were a single set of styles, however since we expect these styles to be used in a wide variety of implementations, flexibility is preferred.
Feature Review Checklist:
Problem
We need a way to accommodate contributed HTML, both in terms of documentation and outputting code / pages.
This HTML format should be a superset of HTML so as not to impede novice users (if they want to just write HTML, we shouldn't discourage that).
Should allow the use of includes / nested templates so that code can be isolated and reused.
Proposed Solution
Alternatives considered
Plain HTML - poor choice due to high maintenance cost, error prone
Markdown - poor choice due to limits of class / attribute additions
Pug / Jade - poor choice due to not being easy to use plain HTML
Additional context
Happy to consider any other alternatives - these are just the ones I'm most familiar with.
Problem description
Proposed solution
hidden
attribute can be used to trigger content displayaria-expanded
added to the selector, hidden
attribute on the content blockNote:
Alternatives considered
Additional context
Demo: https://codepen.io/hazuremon/pen/zYGpPOX
Feature Review Checklist:
Problem
We need to establish a consistent set of recommendations for boilerplate HTML documents. These should be cognizant of current best practices and indicate how to extend the document and in a clear, consistent way.
Proposed solution
I've created a postcss branch on my fork of the project that has a proposed markup pattern. The starting point for this markup was HTML5 boilerplate, with additions as needed.
This directory has:
Alternatives Considered
From my understanding, HTML5 Boilerplate is still the defacto point of reference for best practice and is extensively tested, so this has been the sole option I've considered. This is really just a shared jumping off point and will not be complete for:
Additional context
It's worth noting that an alternative boilerplate would be needed for things like HTML email, AMP, etc.
I've integrated https://snyk.io vulnerability testing for node.js into a branch on my fork of the project. What this does is scans your node_modules files for known security issues (https://snyk.io/vuln?type=npm) and can create fixes via a pull request. The status is output as a badge (ie. https://github.com/occupant/ubc-clf8/tree/integrate-travisci-snyk).
You can set the scan to run daily, weekly or on request. It's free for open source, and seems like both good housekeeping and best practice.
Adding this as an issue before sending a pull request so we can discuss.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.