0.3.0

Changelog for the official Nord website and documentation

This version focused on the responsive web design, core & base component as well as base HTML elements as components of Nord Docs. It includes the base layout which initially consists of the header that provides the global navigation links.
Another focus was the handling of exceptional & special states like empty states and the 404 error state.

Features

Base Media Query Setup — #61 ⇄ #62 (⊶ 6b78d69)
↠ The basic setup for components with responsive styles through media queries has been implemented based on the “Responsive Web Design” design concept.

Media Query Generator

To simplify the usage of media queries with styled-components, a utility function to generate media templateshas been implemented. It uses the min-width parameter to fulfill the used mobile-first approach. The base size that is used has been implemented as theme property in #54.

Initial Media Queries

Always adjust media queries to the content individually and not vice-versa.
The design supports the content. Not the other way around.

Like documented in the #52, Nord Docs uses the mobile-first pattern and follows the great “Google Developer Responsive Web Design” guidelines. The recommended way is to create media queries not based on any device sizes but individually based on the content which is unique for each project. This is the best practice and, contrary to most popular CSS framework like Bootstrap, the correct way since each site is different and there are thousands of devices and in the future new sizes will appear.
The following media query template functions have been implemented:

• phonePortrait — max-width: 479px
• phoneLandscape — max-width: 480px
• tabletPortrait — max-width: 600px
• tabletLandscape — max-width: 900px
• desktop — max-width: 1200px
• desktopPlus — max-width: 1800px

Core Layout Component: BaseLayout — #66 ⇄ #68 (⊶ 208c9ac)
↠ Implemented the BaseLayout core layout component, the default layout of Nord Docs. It consists of the Root core container as root element and the core components representing the header, the main page container and in the future the footer.

Core Container Component: Page — #65 ⇄ #67 (⊶ 701ec43)
↠ Implemented the core container component Page, the base wrapper for page content of Nord Docs. It renders the HTML <main> element to wrap page content and is used in layout components like BaseLayout.

Core Atom HTML Element: P — #79 ⇄ #80 (⊶ ad995b0)
↠ Implemented the core atom P that represents the text content HTML element <p>. It uses adjusted styles instead of browser defaults to match Nord Docs brand style.

Core Atom HTML Element: Heading — #81 ⇄ #82 (⊶ c4e1aa8)
↠ Implemented the core atoms H1-H6 that represent the content sectioning HTML elements <h1>-<h6>. They use custom styles instead of browser defaults and allow to disable the bottom margin via the noMargin prop. The font style like size, modular scale and family adhere to the “Typography” design concept.

Core Atom HTML Element: A — #70 ⇄ #71 (⊶ 75d0e49)
↠ Implemented the core atom A that represents the inline text semantic HTML element <a>. This is a special dynamic and failsafe component because it internally uses the Gatsby Link component to route within the site (internal links) while also being able to link to external data.

URL Routing Utilities

To handle the logic of conditionally rendering a Gatsby Link or a basic <a>, based on the passed target URL (internal & external), utility functions has been implemented to evaluate the passed target.

Core Organism Component: Header — #64 ⇄ #75 (⊶ d6f0fef)
↠ Implemented the essential core organism component Header that provides the main site navigation and a user action component to toggle between the global theme modes.

Layout

The header uses the CSS flexbox layout consisting of two container components with the maximum of flexible space between both. The containers contain the branding and the navigation components like described in the sections below.

Navigation

To allow users to simply navigate around the site, the component provides the quickly accessible navigation. It is placed in the right-sided container and currently contains the following items:

• “Ports” — links to /ports, the landing page for all Nord port projects.
• “Docs” — links to /docs, the landing page for Nord's documentation.
• “Blog” — links to /blog, the landing page for Nord's blog.
• “Community” — links to /community, the landing page of the Nord community channels.

Branding

To represent Nord's branding, the left-sided container contains the Nord logo with the caption. It links the landing page to allow quick access to the root (/) page.

Theme Mode Switcher

The user action component mentioned in the introduction paragraph above allows to toggle between the available global theme modes. Both modes are represented through icons where a sun is used for the “bright snow flurry” and a moon for the “dark night frost” mode. They are implemented using the awesome React Pose project to animate the switching. The icons “fly out and in” within the bounds of the component that takes the form of a button.

Like documented in the “Iconography” design concept, the awesome Eva Icons project is for icons.

Responsive Design

For reduced width views (responsive design) the header adjusts several styles and composed components.

Slide Menu

The main navigation link list will be hidden and replaced by a user action element (button) that toggles an animated slide down menu containing the navigation links. The drop down starts right below the header and takes up the available height and width to cover the full screen. As soon as the animation starts all scroll events will be removed from the underlying content (body) using the body-scroll-lock project. This prevents users from scrolling the content below the menu when the menu itself overflows the Y-axis and shows a scroll bar.

Behavior

To allow quick access while also being inconspicuous, the component is sticky at the top of the site, but collapses as soon as the user scrolls down and only switches back into expanded mode when at top of the site.
In expanded mode, the height of the header is larger and the caption of the logo is visible. As soon as switching into collapsed mode the height decreases and the logo caption fades out with a smooth transition animation.

To achieve the resizing animation based on the scroll position the subscribe-ui-event project is used to listen to scroll events. It provides throttling by default, only calls document.body.scrollTop and window.innerWidth once and uses requestAnimationFrame for a better performance.

Empty State Component — #78 ⇄ #83 (⊶ 2079c05)
↠ Implemented the EmptyState molecule component to represent an empty state. It consists an vector illustration, a headline and the corresponding subline.

There are initially 3 different illustrations available that can be selected through the illustrationVariant prop. The headline informs the user about the purpose of the illustration and the reason why it is currently shown while the subline can include additional information and helpful instructions.

The empty state component has been placed within a base HTML component that represents a <section> with multiple base style variants and is now initially used by the new base page components for the header navigation links.

404 Page Components — #84 ⇄ #85 (⊶ a39649f)
↠ Implemented the 404 page and illustration components to handle requested but non-existing routes and resources.

It aligns with Nord Docs brand and can use a humorous image and tagline that conveys the purpose of the screen, without appearing actionable.
Also see the great Gatsby documentation about 404 pages for more details.

SVGR Integration — #72 ⇄ #73 (⊶ 39c1304)
↠ Integrated SVGR, a transformer for SVG into ready to use React components. It is part of create-react-app and makes SVG integration into React projects easy.

All configurations are placed in the svgr.config.js file instead of passing them to the corresponding Gatsby plugin for the Webpack loader that is described in the section below.

Webpack Loader

To directly import SVG's as React component the @svgr/webpack package is used to simply integrate SVGR as Webpack plugin. It has been added through gatsby-plugin-svgr which adjusts the required Webpack configurations by adding the loader and removing the default .svg file loader/handler.

Jest utilities for Styled Components — #76 ⇄ #77 (⊶ 47010b8)
↠ Integrated jest-styled-components, a set of utilities for testing Styled Components with Jest that improves the snapshot testing experience and provides a brand new matcher to make expectations on the style rules.
Instead of storing the generated class names in snapshots it allows to track the actual CSS rules and attributes for better comparison what changed and if the change is even really related to the affected component.

This is the officially recommended library to use Jest with styled-components.

const Button = styled.button`
  color: red;
`;

exports[`snapshot`] = `
<button
  className="sc-bdVaJa rOCEJ"
/>
`;

Before

- Snapshot
+ Received

 <button
-  className="sc-bdVaJa rOCEJ"
+  className="sc-bdVaJa hUzqNt"
 />

After

- Snapshot
+ Received

+.c0 {
+  color: green;
+}
+
 <button
-  className="sc-bdVaJa rOCEJ"
+  className="c0"
 />

The package has been added in the setup file defined in Jest's setupTestFrameworkScriptFile field (#39) to enable all included features.

Custom Style Matcher

The custom toHaveStyleRule matcher is useful to test if a given rule is applied to a component. It is added to the extended global except object when the main package file is being imported.

---

The full changelog is available here