npm package: @georgiagov/orchard
Description: DSGa Design System
Latest version: 2.12.3

# 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.

```bash
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](https://orchard.georgia.gov/?path=/docs/welcome-how-to-use-orchard--docs).

### 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`.

```bash
npm install @georgiagov/orchard@2.9.0
```

See [the official NPM documentation](https://docs.npmjs.com/cli/v11/commands/npm-install)
for more information.

All the available Orchard versions are [listed on the NPM website](https://www.npmjs.com/package/@georgiagov/orchard/v/latest?activeTab=versions).

## 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](https://webpack.js.org/), 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.

```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.

```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.

```html
<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](https://orchard.georgia.gov/?path=/story/components-link--button),
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](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/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](https://www.lullabot.com/articles/introduction-css-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](https://react.dev/learn/writing-markup-with-jsx)?

If you're still having trouble, send us a detailed report via our
[contact form](https://digital.georgia.gov/orchard-design-system-feedback).

## Usage

Once you've successfully completed the **Getting started** section, you can add
Orchard [Pages](https://orchard.georgia.gov/?path=/docs/layouts-page--docs) and
Components to your project. These elements are provided in plain HTML on the
Orchard website.
See [Copying component HTML](https://orchard.georgia.gov/?path=/docs/welcome-how-to-use-orchard--docs#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](https://orchard.georgia.gov/?path=/docs/components-card--docs) component
with Orchard's default, dummy data, looks like this:

```html
<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:

```ASP.NET
<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](https://orchard.georgia.gov/?path=/docs/components-side-navigation--docs).
Components that use JavaScript have a `<script>` tag at the bottom of their HTML.
See [Copying component HTML](https://orchard.georgia.gov/?path=/docs/welcome-how-to-use-orchard--docs#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](https://developer.mozilla.org/en-US/docs/Glossary/Favicon) 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.

```html
<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](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties).
The color value of each custom property depends on which [palette](./palettes)
you've chosen.

The custom properties for all palettes are available in an
[interactive visual browser](https://orchard.georgia.gov/?path=/docs/styles-colors--docs)
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.

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

All custom properties are set on
[:root](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:root),
so they will be available everywhere throughout your CSS.

### Icons

Orchard provides an accessible icon set in
[SVG](https://developer.mozilla.org/en-US/docs/Web/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](https://orchard.georgia.gov/?path=/docs/styles-icons--docs)
is available on the Orchard website.

The [physical sizes of the icons are not set](https://architecture.lullabot.com/adr/20251008-use-svg-viewbox/),
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.

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

This code has low
[specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascade/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](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Text_styling/Web_fonts),
which are automatically loaded when you include `orchard.min.css`.

Optionally, you may want to
[preload these fonts](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/preload)
to improve page performance. Either use your NPM-aware build tooling to add the
font preloading, such as Webpack's
[html-webpack-plugin](https://www.npmjs.com/package/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.

```html
<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](https://digital.georgia.gov/orchard-design-system-feedback).

## Changelog

The [changelog](https://orchard.georgia.gov/?path=/docs/welcome-changelog--docs) is updated to reflect the changes in each
release.

## License

The Orchard project is licensed under the terms of the [MIT license](https://orchard.georgia.gov/?path=/docs/welcome-introduction--docs).