Welcome to Orchard

Orchard is Georgia's official design system. Orchard makes it easy to quickly build an accessible, mobile-friendly, and uniform digital experience. Use it to stay on brand and save valuable engineering and design time.

For more information, see https://orchard.georgia.gov.

Installation

To install with NPM, run the following command inside your project.

npm install @georgiagov/orchard

You may also directly link to Orchard resources hosted on Georgia's official servers. For that method, see How to use Orchard.

Installing older versions

When starting a new project, or if it's your first time integrating Orchard into your project, it's recommended to use the latest version (see above).

If you do need to install an older version, add the release number to the end of your install command, for example @2.9.0.

npm install @georgiagov/[email protected]

See the official NPM documentation for more information.

All the available Orchard versions are listed on the NPM website.

Getting started

The Orchard NPM package can load assets either directly from the node_modules folder or via a build tool (recommended).

The most important integration is including the CSS styles. We'll need both the base stylesheet, plus a palette. We'll use the Foundation palette for these examples. All the Orchard palettes are available inside the palettes folder.

Using a build tool (recommended)

Integration is simple when using a build tool like Webpack, or any other NPM-aware build tooling. Use the @georgiagov/orchard namespace, and import in a place in your application that's globally available, like a page file.

Here's an example in JavaScript.

import "@georgiagov/orchard/orchard.min.css";
import "@georgiagov/orchard/palettes/foundation.css";

Loading files directly

You may also load files directly, if you've installed the node_modules folder inside your application root. If node_modules is outside your application root, you'll need a build script or some other process to copy the files into a place where your application can read them.

Here's an example of loading files directly from node_modules in HTML.

<link rel="stylesheet" href="node_modules/@georgiagov/orchard/orchard.min.css" />
<link rel="stylesheet" href="node_modules/@georgiagov/orchard/palettes/foundation.css" />

Confirming Orchard is setup correctly

To test that everything is setup correctly, copy and paste the following HTML snippet into a your application.

<a class="orchard-link orchard-link--button" href="https://example.com">
  Link text
  <svg aria-hidden="true" role="img" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
    <circle fill="var(--orchard-palette-icon-bg, #e2eae4)" cx="12" cy="12" r="12"></circle>
    <path d="M17.946 11.541a.72.72 0 0 0-.151-.237l-5.092-5.092a.718.718 0 0 0-.788-.157.718.718 0 0 0-.392.391.732.732 0 0 0 0 .554c.037.088.09.167.157.235l3.868 3.86H6.72a.72.72 0 0 0 0 1.44h8.828l-3.868 3.861a.733.733 0 0 0-.158.234.732.732 0 0 0 0 .554.733.733 0 0 0 .393.39.71.71 0 0 0 .276.053.711.711 0 0 0 .512-.209l5.092-5.092a.72.72 0 0 0 .151-.237.722.722 0 0 0 0-.548Z" fill="var(--orchard-palette-icon-stroke, #2b5a61)"></path>
  </svg>
</a>

If the result looks like the Orchard link button demo, setup was a success!

Troubleshooting

Sometimes, things don't work right away. Here's some common problems and some potential solutions.

• My Orchard components are not styled
  Make sure the Orchard stylesheets are loaded before any of your site's CSS styles.
• My Orchard components do not have color
  Did you include a palette file?
• My Orchard components look incorrect
  Orchard styles will have lower specificity than your styles. Inspect the code around incorrectly displaying components, and check if your styles are overriding it. You may need to refactor your code to reduce your style's specificity.
  Alternatively, you can directly control specificity using Cascade Layers.
• My Webpack build errors out
  Do you have css-loader installed and configured?
• My React project errors out
  Did you convert the Orchard HTML to JSX?

If you're still having trouble, send us a detailed report via our contact form.

Usage

Once you've successfully completed the Getting started section, you can add Orchard Pages and Components to your project. These elements are provided in plain HTML on the Orchard website. See Copying component HTML.

If you're building a project with a dynamic templating system, we recommend converting Orchard's plain HTML snippets into your templating language, and saving them in their own file for reuse. We recommend giving the component parameters, to maximize it's re-usability.

For example, the plain HTML version of the Card component with Orchard's default, dummy data, looks like this:

<div class="orchard-card">
  <div class="orchard-card__content">
    <h2>Card title</h2>
    <p>
      Lorem ipsum dolor sit amet,
      <em>consectetur adipiscing elit</em>
      , sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
      <strong>Sed euismod</strong>
      nisi porta lorem mollis aliquam.
    </p>
    <p><a href="https://example.com">Card link</a></p>
  </div>
</div>

If you were going to make this a re-usable component with parameters in ASP.NET, you might re-write the component to something like this:

<div class="orchard-card">
  <div class="orchard-card__content">
    @if(cardTitle != "") {
      <h2>@cardTitle</h2>
    }
    <p>@cardDescription</p>
    @if(cardLink !== "") {
      <p><a href="@cardLink.url">@cardLink.text</a></p>
    }
  </div>
</div>

JavaScript components and NPM

Some components require JavaScript to function. For example, the Side Navigation. Components that use JavaScript have a <script> tag at the bottom of their HTML. See Copying component HTML.

These <script> tags src points to the Georgia hosted version, not a local NPM version. Using the <script> tags as-is will work fine using NPM, if you're okay with the scripts being loaded externally.

If you would rather load the file from your server, you'll have to modify the <script> tag's src to point to the NPM version of the script. All Orchard JavaScript files are located in the top level folder of the NPM package.

You may be able to use the NPM @georgiagov/orchard namespace in your path, or you may have to copy the scripts you need into your application root with a build job, depend on your build tooling.

Note that Orchard JavaScript files all use IIFE, and are not ESM Module compatible, meaning an import won't work. Orchard JavaScript must be loaded from a <script> tag.

Favicons

Favicons are provided in the Orchard NPM package at several common sizes and formats. They are recommended for all Georgia projects.

• @georgiagov/orchard/favicon.ico
• @georgiagov/orchard/apple-touch-icon.png
• @georgiagov/orchard/favicon-16x16.png
• @georgiagov/orchard/favicon-32x32.png

Copy the above icons from your node_modules library to your application root, or include them with a NPM-aware build tool (see above). Here's an example of how the final HTML for the favicons should look.

<link rel="icon" href="/favicon.ico" type="image/vnd.microsoft.icon" />
<link rel="apple-touch-icon" href="/apple-touch-icon.png"/>
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png"/>
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png"/>

Color tokens

You can access Orchard color values directly in your application with CSS Custom Properties. The color value of each custom property depends on which palette you've chosen.

The custom properties for all palettes are available in an interactive visual browser on the Orchard website, or you can inspect your chosen palette file.

To use a color custom property, simply use it as a CSS value for an applicable property. For example, if you wanted to set the background color of an element to Orchard's "Accent Background", you might write something like this.

.my-element {
  background-color: var(--orchard-palette-bg-accent);
}

All custom properties are set on :root, so they will be available everywhere throughout your CSS.

Icons

Orchard provides an accessible icon set in SVG format.

You do not have to add an icon for Orchard components that already include an icon; the components already handle the inclusion. If you need to include an icon separately, the icons folder in the Orchard NPM package allows you to do so.

Either copy and paste the SVG code from the node_modules/@georgiagov/orchard/icons folder into your application, or import the icon using your NPM-aware build tooling or framework.

A visual icon browser is available on the Orchard website.

The physical sizes of the icons are not set, so you will need to set the dimensions yourself in CSS.

Tip: You can make all icons take on the size of the surrounding text with this CSS snippet.

svg {
  inline-size: 1em;
  block-size: 1em;
}

This code has low specificity, so can be easily overridden if a different size is required in a specific context.

Colors are set inside the SVG icons using palette CSS custom properties (see above). You can change the color of the icon by resetting the custom property value on the icon element.

Font performance

Orchard uses web fonts, which are automatically loaded when you include orchard.min.css.

Optionally, you may want to preload these fonts to improve page performance. Either use your NPM-aware build tooling to add the font preloading, such as Webpack's html-webpack-plugin, or copy node_modules/@georgiagov/orchard/fonts to a folder your application can access.

Here's an example of the final preload HTML, where the fonts folder has been copied to the application root.

<link href="/fonts/montserrat/Montserrat-VF.woff2" rel="prefetch" as="font" type="font/woff2" crossorigin />
<link href="/fonts/montserrat/Montserrat-Italic-VF.woff2" rel="prefetch" as="font" type="font/woff2" crossorigin />
<link href="/fonts/source-serif-pro/SourceSerifVariable-Roman.woff2" rel="prefetch" as="font" type="font/woff2" crossorigin />
<link href="/fonts/source-serif-pro/SourceSerifVariable-Italic.woff2" rel="prefetch" as="font" type="font/woff2" crossorigin />

Contact

We are dedicated to making this design system something that empowers your ability to autonomously customize projects within the Georgia government’s official styles.

We encourage you to send our team both general suggestions and feedback on specific components using the form provided below. Although we may not respond to each message directly, we welcome your questions and will consider them as we continue to build out this site. If you have built a unique component that you’d like to share with other sites or apps using Orchard, we’d love to hear about that too.

Fill out the Orchard contact form.

Changelog

The changelog is updated to reflect the changes in each release.

License

The Orchard project is licensed under the terms of the MIT license.