MDN Web Docs Front-End style guide
This has been merged into the main MDN Web Docs code repository at https://github.com/mdn/yari/
MDN Web Docs Front-End style guide
Home Page: https://mdn-fiori.netlify.app/
License: MIT License
MDN Web Docs Front-End style guide
This has been merged into the main MDN Web Docs code repository at https://github.com/mdn/yari/
The benefits of switching to a SVG icon system over a icon font system are numerous, for example:
To stay consistent with the current design, the icons will still be those from the FontAwesome set, but will be inlined SVG instead of an icon font.
Bugzilla: https://bugzilla.mozilla.org/show_bug.cgi?id=1451261
I have been doing some reading on why one would put GA at the top of the page. The general consensus is that it is because Google said so, but there really is no good reason for it.
Worst case you loose tracking of page views where the user navigated away before the page loaded. I agree with the general feeling here that, for the performance implication, losing these "views" is not worth it.
h5bp/html5-boilerplate@2dfb903#commitcomment-16054505
https://mathiasbynens.be/notes/async-analytics-snippet#comment-50
I therefore propose that we move DNTHelper and the GA code to the bottom of the HTML source and mark them as async
This prevents the current blocking behaviour. Thoughts?
Original Bugzilla Ticket: https://bugzilla.mozilla.org/show_bug.cgi?id=1458197
There is still code left on Kuma that managed the display between the dev needs survey and the payments banner. Seeing that the payments banner is no longer used, the conditional code can be removed.
The dnt-helper
utility almost never changes and it currently blocks rendering because of the HTTP request. It is therefore best to uglify and inline directly in the head of the document.
This is an item identified by @tkadlec as part of the performance audit
The homepage currently loads two GIF background images that could be better optimized if they were served as PNG’s.
https://developer.mozilla.org/static/img/home-bg.ca67b4ee8675.gif
As a gif: 9.6kb
As an 8-color PNG: 2.2kb
https://developer.mozilla.org/static/img/home-dino.4c4029f73eb9.gif
As a gif: 26.7kb
As an 8-color PNG: 9.2kb
This involves a rethink of the entire header of MDN Web Docs including location and interaction model for breadcrumbs, search, toc, quick lang switcher, page editing tools
Concepts have been proposed here:
https://bugzilla.mozilla.org/show_bug.cgi?id=1446291
Currently, line wrapping when rendering the site allows the line to wrap between the external-link icon and the link's text. This shouldn't happen.
See the attached screenshot for an example taken from https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism (it's up to you to adjust your width until it wraps).
Screenshot:
https://screenshots.firefox.com/jew3SKOddjyBUutL/developer.mozilla.org
Bugzilla: https://bugzilla.mozilla.org/show_bug.cgi?id=1391440
What is the current interaction with the following component?
It feels like this is duplicate content that is already available at the bottom of the same page. It also generally feels out of place hanging there in seemingly the middle of nowhere ;)
It also adds 13.7kb and 223ms in image load time to the overall load time of the homepage. I would vote to remove this widget if the interaction is low, and cleanup the content at the bottom of the page.
Move it so it is side by side with the Hacks blog feed on desktop, dropping to below the feed on tablet and lower.
Mockup provided here: https://bugzilla.mozilla.org/show_bug.cgi?id=1450922
Most people simply stick GA in the header because "Google said so", but there really is no good reason for it. DNTHelper is in the header because it needs to be before we load GA.
When the one moves down, the other can move along with it.
Worst case you loose tracking of page views where the user navigated away before the page loaded. I agree with the general feeling here that, for the performance implication, losing these "views" is not worth it.
h5bp/html5-boilerplate@2dfb903#commitcomment-16054505
https://mathiasbynens.be/notes/async-analytics-snippet#comment-50
I therefore propose that we move DNTHelper and the GA code to the bottom of the HTML source and mark them as async
This prevents the current blocking behaviour.
Bugzilla: https://bugzilla.mozilla.org/show_bug.cgi?id=1458197
Can this be changed to Mozilla, or to a dual copyright?
While this might not affect a large portion of our audience, it is another large dependency we no longer have to think about. This task requires a couple of individual tasks:
Initially this will mostly be focused on compiling and bundling SaSS and replacing some SaSS functionality with PostCSS. As our JS codebase moves to using modern vanilla JS, Webpack can take over from plain Babeljs, to add additional tooling.
The most clearly definable benefit of this is better tooling, that leads to enhanced developer productivity. This sets up a modern workflow that allows for easier adoption of new features of the platform.
[1] https://webpack.js.org/loaders/
[2] https://webpack.js.org/loaders/sass-loader/
[3] https://webpack.js.org/loaders/postcss-loader/
Most used page of this type:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach
Propose Yup/Nope widget design
As of January 1 2019, Mozilla requires that all GitHub projects include this CODE_OF_CONDUCT.md file in the project root. The file has two parts:
If you have any questions about this file, or Code of Conduct policies and procedures, please see Mozilla-GitHub-Standards or email [email protected].
(Message COC001)
As a precursor to using Webpack, or in tandem while the JS is being converted, we should start using Babeljs as part of our front end toolchain.
This will allow us to use modern JavaScript, take advantage of the new syntax, features, and improved performance. Because we do not have to support a wide array of old browser versions, we can use a preset-env and target a specific list of browser/version combinations[2].
This will ensure that our compiled JS is still small enough to get performance gains over and above those we will gain during parsing and execution.
[1] https://babeljs.io/
[2] https://babeljs.io/docs/plugins/preset-env/#export-with-various-targets
This is an item identified by @tkadlec as part of the performance audit
Since it’s unlikely users are hopping back and forth between different languages or locales, there doesn’t seem to be much of a caching benefit to having these fonts include full language support in one big file. Instead, can we subset these files to include on the characters necessary for each language option and load them selectively as is done already for locales with specific fonts?
The gains would be significant. For example, my estimate is that subsetting the OpenSans fonts and ZillaSlab fonts to Latin Extended would reduce font weight (currently ~350kb) by around 70% (bringing it down to ~100kb).
Add “Link to section” functionality i.e. On Github for example, when you hover over one of the top level headings in a md file an icon is revealed as below:
Even though the pages are “set-up” for this on MDN, we are not taking advantage of it. Currently, if you wish to share a link to a specific section of a piece of documentation, say the examples section of https://developer.mozilla.org/en-US/docs/Web/CSS/mask, you have to:
The idea here is to make these links as on Github that will update the URL with the hash. A possible enhancement to this can be that the new URL is automatically copied to the user’s clipboard.
The link color contrast for soapbox messages is to low.
All functionality can be replaced with modern JavaScript that will result in an overall smaller sized codebase, and allows us to take advantage of modern JS engines, and best practices.
SVGO works amazing as a tool to optimise SVG. There is one small downside though. The output of SVGO when not passing --pretty removes the new line at the end of the file. This is not ideal because
Therefore we need to write a little Nodejs util that wraps SVO processing and adds the missing \n at the end of the file.
This is an item identified by @tkadlec as part of the performance audit
Locale-en-us.css (as well as other locales) are all tiny files (700-900 bytes) that load in whatever the fonts should be for that specific locale. Though they’re tiny, it’s still an HTTP request that has to be made which can really add up on slower connections.
Inline the contents of locale-*.css
Because they’re so small, inlining the contents of the locale font files makes sense provided that the files rarely change. You’re adding less than 1kb of data to each page load and saving a request for anyone without a pre-warmed cache.
There are a couple of reasons for this:
We can adopt modern JavaScript, and use Babeljs to compile our JS down to a baseline. When we cut out everything less than IE11, our baseline generally has better support for modern JS. This means less down compilation. The result being a much smaller kb size for the resulting JS files.
Lower cost for users of low end hardware and old tech without blocking them from content.
Serve only HTML with one simple CSS file that hides elements on the page that requires JavaScript to function.
Having analysed some data during the recent performance audit, we noticed that instead of improving performance, the preload
hints are having a detrimental effect on performance.
It looks to be causing a double download, or at the very least another set of requests from within the iframe
. Because the iframe
is not on the same domain as MDN Web Docs, it might very well be that they are not using the same browser cache. This means the preload really has no benefit.
Also, having done a test using local overrides in Chrome dev tools, the page showed a load performance improvement of 250ms with those preload
hints removed. It is therefore best to remove them.
Determine the feasibility and potential performance improvement impact of adding service workers to MDN generally, and specifically the minimally viable service worker strategy/lib - (https://adactio.com/journal/13540)
The a11y of MDN Web Docs is pretty good already, thanks in large part to the work done by @stephaniehobson. There is still room for improvement and, we need to keep in check so it does not slide.
First step is to get a lay of the land, and then also incorporate tools that will monitor this in as automated manner as possible. As a first step, we need to add Pa11y[1] to our tool chain and do an audit of key pages.
Once we have identified the biggest a11y problems that currently exist, we need to log them, prioritise and then decide an a path to resolve these.
Bugzilla: https://bugzilla.mozilla.org/show_bug.cgi?id=1537956
Go to https://developer.mozilla.org/en-US/docs/Glossary
Notice that the top border of the H2 makes a lot of vertical space, and runs into the "Learn a new term" callout.
The H1 border should not cut into the callout. It would be better in general if it didn't take up so much vertical space.
The problem on this particular page might be solved by adjusting the CSS of the callout. But the general issue of vertical space would not. See for example, https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/HTML_basics
The user who reported this via IRC suggested the following:
.text-content article[id=wikiArticle]>div:not([class])>h2:after, .text-content article[id=wikiArticle]>h2:after {
border-top: 3px solid #3d7e9a;
content: '';
display: block;
position: absolute;
width: 100%;}
This is currently underway in this project and can be viewed at:
https://mdn.github.io/mdn-fiori/
This will cover(not finite):
Common components found in the MDN Web Docs code base with:
Bugzilla: https://bugzilla.mozilla.org/show_bug.cgi?id=1542834
@peterbe I actually didn't dare to actually print it out on paper so I used the Print to PDF on my mac. Could be that it looks different when sent to the actual HP printer.
![https://bug1542834.bmoattachments.org/attachment.cgi?id=9056645]
Bugzilla: https://bugzilla.mozilla.org/show_bug.cgi?id=1542817
Steps to reproduce
ReferenceError: ga is not defined
The screenshot mentioned line is referencing line 91 which isn't right but very near is the line ga('send', 'pageview', {'hitCallback': removeUtms}); which I suspect gets called after window.onload even though ga might not have been created successfully (in the lines above).
I noticed, it happens on https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach but not https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray
Clicking around, it seems quite random. Repeatable when you refresh the page but varying depending on the page.
Currently there are no unit tests for the JavaScript on MDN Web Docs. As we move to a more functional, modern, modular(all that buzz though ;)) JavaScript codebase, we need to take the opportunity to add unit tests.
This should be done in tandem with new code and rewrites. As a new piece of code lands, or a rewrite of an existing piece, it needs to be accompanied with tests.
Jest enjoys large adoption and comes with baked in support for everything we might need so, this is the suggested framework to adopt.
There are many mentions of Cupper in the repo, including in CONTRIBUTING.md. Is the conversion to an MDN project complete?
Add file type icons to search results to clearly distinguish between CSS, JS, HTML, Rust, Web Extensions etc. Makes skimming over the results much easier
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.