@nypl/design-system-react-components 1.0.1 → 1.0.2

package/src/components/StyleGuide/Forms.stories.mdx

@@ -0,0 +1,94 @@
+import { Meta } from "@storybook/addon-docs";
+
+import Card from "../Card/Card";
+import List from "../List/List";
+import { getCategory } from "../../utils/componentCategories";
+
+<Meta title={getCategory("Forms")} />
+
+# Forms
+
+| Table of Contents                                  |
+| -------------------------------------------------- |
+| 1. [General Information](#general-information)     |
+| 2. [Form Input Components](#form-input-components) |
+| 3. [Input Labelling](#input-labelling)             |
+| 4. [Input States](#input-states)                   |
+| 5. [Figma Reference](#figma-reference)             |
+
+## General Information
+
+Use the [Form](https://nypl.github.io/nypl-design-system/reservoir/v1/?path=/docs/components-form-elements-form--form-with-controls)
+component to control the placement and spacing for standard HTML forms.
+
+## Form Layout
+
+The `Form` component offers two child-components to assist with layout:
+`FormRow` and `FormField`.
+
+The `FormField` component is used as a parent for all input components from
+the Reservoir Design System (DS) (`Button`, `Select`, `TextInput`, etc.). When using the
+`Form` is it is necessary to wrap each individual form input component within
+a `FormField` component to ensure proper spacing and responsiveness.
+
+The `FormRow` component is used as a parent of multiple `FormField` components
+when you need to render more than one input component in a horizontal row.
+
+The recommended layout and spacing within individual form input components is
+built into the components. Consuming apps should rely on the components to
+handle NYPL best practices for layout and responsiveness.
+
+## Form Input Components
+
+The list of form input fields available in the Reservoir Design System (DS)
+includes, but is not limited to, the following:
+
+- Button
+- Checkbox
+- CheckboxGroup
+- DatePicker
+- Dropdown \*\*\*
+- Fieldset
+- FileUploader \*\*\*
+- Form
+- Label
+- Radio
+- RadioGroup
+- SearchBar
+- Select
+- Slider
+- TextInput (text, tel, url, number, password, textarea)
+- Toggle
+
+\*\*\* currently under development
+
+## Input Labelling
+
+Most form components in the DS will have the option to show a
+label, basic helper text and error text.
+
+For accessibility compliance, a text value for the label is always required. If
+necessary, the label can be hidden from the screen. In cases where the label is
+hidden, appropriate ARIA tags will be added to the form input component.
+
+When the label is visible, `CheckboxGroup`, `DatePicker`, `FileUploader`,
+`RadioGroup`, `Select`, `Slider` and `TextInput` will show the label at the top
+of the rendered component. While `Checkbox`, `Radio` and `Toggle` will show the
+label to the right of the input field.
+
+The helper and error text will always be rendered below the input field.
+
+## Input States
+
+All form input fields offer styling for the following states:
+
+- static
+- focused
+- errored
+- disabled
+
+## Figma Reference
+
+For additional spacing information, please refer to the Figma Main file.
+
+- [General Forms Page](https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/?node-id=10734%3A2768)

package/src/components/StyleGuide/Iconography.stories.mdx

@@ -0,0 +1,142 @@
+import { Stack } from "@chakra-ui/react";
+import { Canvas, Meta } from "@storybook/addon-docs";
+
+import Icon from "../Icons/Icon";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta title={getCategory("Iconography")} />
+
+# Iconography
+
+| Table of Contents                              |
+| ---------------------------------------------- |
+| 1. [General Information](#general-information) |
+| 2. [Icon Examples](#icon-examples)             |
+| 3. [Icon Sizes](#icon-sizes)                   |
+| 4. [Icon Colors](#icon-colors)                 |
+| 5. [Development Notes](#development-notes)     |
+| 6. [Figma Reference](#figma-reference)         |
+
+## General Information
+
+Use the Reservoir Design System (DS) [Icon](https://nypl.github.io/nypl-design-system/reservoir/v1/?path=/docs/components-media-icons-icon--icon-with-controls)
+component to render and control icons as `<svg>` elements within consuming apps.
+
+The DS utilizes the `Filled` icons available in the [Material UI Design System](https://material-ui.com/components/material-icons/).
+
+## Icon Examples
+
+The graphic of the `Icon` component is handled through the `name` prop. To see
+all graphic options for `Icon`, please refer to the [Icon](https://nypl.github.io/nypl-design-system/reservoir/v1/?path=/docs/components-media-icons-icon--icon-with-controls)
+Storybook page.
+
+<Canvas>
+  <DSProvider>
+    <Stack spacing="s" direction="row">
+      <Icon decorative size="xxxlarge" name="check" />
+      <Icon decorative size="xxxlarge" name="close" />
+      <Icon decorative size="xxxlarge" name="errorOutline" />
+      <Icon decorative size="xxxlarge" name="speakerNotes" />
+    </Stack>
+  </DSProvider>
+</Canvas>
+
+| Values for Examples Above |
+| ------------------------- |
+| `check`                   |
+| `close`                   |
+| `errorOutline`            |
+| `speakerNotes`            |
+
+## Icon Sizes
+
+The size of the `Icon` component is handled through the `size` prop.
+
+<Canvas>
+  <DSProvider>
+    <Stack spacing="s" direction="row" alignItems="center">
+      <Icon size="small" name="check" />
+      <Icon size="medium" name="check" />
+      <Icon size="large" name="check" />
+      <Icon size="xlarge" name="check" />
+      <Icon size="xxlarge" name="check" />
+      <Icon size="xxxlarge" name="check" />
+    </Stack>
+  </DSProvider>
+</Canvas>
+
+| Value      | CSS Value         | CSS Variable       |
+| ---------- | ----------------- | ------------------ |
+| `small`    | `0.875rem` (14px) | n/a                |
+| `medium`   | `1.125rem` (18px) | n/a                |
+| `large`    | `1.5rem` (24px)   | `--nypl-space-m`   |
+| `xlarge`   | `2rem` (32px)     | `--nypl-space-l`   |
+| `xxlarge`  | `3rem` (48px)     | `--nypl-space-xl`  |
+| `xxxlarge` | `4rem` (64px)     | `--nypl-space-xxl` |
+
+## Icon Colors
+
+The color of the `Icon` component is handled through the `color` prop. Icons in
+NYPL projects should always be rendered with one color.
+
+<Canvas>
+  <DSProvider>
+    <Stack spacing="s" direction="row">
+      <Icon size="xxxlarge" name="check" />
+      <Icon name="check" size="xxxlarge" color="brand.primary" />
+      <Icon name="check" size="xxxlarge" color="section.research.primary" />
+      <Icon
+        name="check"
+        size="xxxlarge"
+        color="section.research-library.schwartzman"
+      />
+      <Icon
+        name="check"
+        size="xxxlarge"
+        color="section.research-library.schomburg"
+      />
+    </Stack>
+  </DSProvider>
+</Canvas>
+
+| Value                                  | CSS Variable                                         |
+| -------------------------------------- | ---------------------------------------------------- |
+| `ui.black`                             | `--nypl-colors-ui-black`                             |
+| `ui.white`                             | `--nypl-colors-ui-white`                             |
+| `brand.primary`                        | `--nypl-colors-brand-primary`                        |
+| `brand.secondary`                      | `--nypl-colors-brand-secondary`                      |
+| `section.blogs.primary`                | `--nypl-colors-section-blogs-primary`                |
+| `section.blogs.secondary`              | `--nypl-colors-section-blogs-secondary`              |
+| `section.books-and-more.primary`       | `--nypl-colors-section-books-and-more-primary`       |
+| `section.books-and-more.secondary`     | `--nypl-colors-section-books-and-more-secondary`     |
+| `section.education.primary`            | `--nypl-colors-section-education-primary`            |
+| `section.education.secondary`          | `--nypl-colors-section-education-secondary`          |
+| `section.locations.primary`            | `--nypl-colors-section-locations-primary`            |
+| `section.locations.secondary`          | `--nypl-colors-section-locations-secondary`          |
+| `section.research.primary`             | `--nypl-colors-section-research-primary`             |
+| `section.research.secondary`           | `--nypl-colors-section-research-secondary`           |
+| `section.research-library.lpa`         | `--nypl-colors-section-research-library-lpa`         |
+| `section.research.library.schomburg`   | `--nypl-colors-section-research-library-schomburg`   |
+| `section.research.library.schwartzman` | `--nypl-colors-section-research-library-schwartzman` |
+| `section.whats-on.primary`             | `--nypl-colors-section-whats-on-primary`             |
+| `section.whats-on.secondary`           | `--nypl-colors-section-whats-on-secondary`           |
+
+## Development Notes
+
+Icons have been added to the Icon component as they have been needed within NYPL
+development project, so not all of the [NYPL icons](https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/?node-id=10734%3A3945)
+and [NYPL Brand](https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=15454%3A47007)
+and [NYPL UI](https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=14989%3A37)
+colors are currently available through the DS Icon component. If your project
+requires an icon or color that is not currently available in the Icon component,
+please inform your project manager or reach out directly to the NYPL Design
+System team.
+
+## Figma Reference
+
+For additional spacing information, please refer to the Figma Main file.
+
+- [NYPL Icons](https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/?node-id=10734%3A3945)
+- [NYPL Brand Colors](https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=15454%3A47007)
+- [NYPL UI Colors](https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=14989%3A37)

package/src/components/StyleGuide/Spacing.stories.mdx

@@ -0,0 +1,116 @@
+import { Meta } from "@storybook/addon-docs";
+
+import Card from "../Card/Card";
+import List from "../List/List";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta title={getCategory("Spacing")} />
+
+# Spacing
+
+| Table of Contents                                    |
+| ---------------------------------------------------- |
+| 1. [General Information](#general-information)       |
+| 2. [Default Spacing Values](#default-spacing-values) |
+| 3. [Page Section Spacing](#page-section-spacing)     |
+| 4. [Grid Spacing](#grid-spacing)                     |
+| 5. [Form Spacing](#form-spacing)                     |
+| 6. [Tabular Data Spacing](#tabular-data-spacing)     |
+| 7. [Figma Reference](#figma-reference)               |
+
+## General Information
+
+The Reservoir Design System (DS) spacing values are based on a root unit
+of `16px` (`1rem` = `16px`).
+
+## Default Spacing Values
+
+<DSProvider>
+The following default spacing values are available through the DS.
+
+| JS Theme Object | CSS Variable        | REM Equivalent | Pixel Equivalent | Visual Reference                                                                                              |
+| --------------- | ------------------- | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
+| `xxxs`          | `--nypl-space-xxxs` | `0.125rem`     | `2px`            | <div style={{ width: "var(--nypl-space-xxxs)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div> |
+| `xxs`           | `--nypl-space-xxs`  | `0.25rem`      | `4px`            | <div style={{ width: "var(--nypl-space-xxs)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>  |
+| `xs`            | `--nypl-space-xs`   | `0.5rem`       | `8px`            | <div style={{ width: "var(--nypl-space-xs)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>   |
+| `s`             | `--nypl-space-s`    | `1rem`         | `16px`           | <div style={{ width: "var(--nypl-space-s)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>    |
+| `m`             | `--nypl-space-m`    | `1.5rem`       | `24px`           | <div style={{ width: "var(--nypl-space-m)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>    |
+| `l`             | `--nypl-space-l`    | `2rem`         | `32px`           | <div style={{ width: "var(--nypl-space-l)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>    |
+| `xl`            | `--nypl-space-xl`   | `3rem`         | `48px`           | <div style={{ width: "var(--nypl-space-xl)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>   |
+| `xxl`           | `--nypl-space-xxl`  | `4rem`         | `64px`           | <div style={{ width: "var(--nypl-space-xxl)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>  |
+| `xxxl`          | `--nypl-space-xxxl` | `6rem`         | `96px`           | <div style={{ width: "var(--nypl-space-xxxl)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div> |
+
+</DSProvider>
+
+## Page Section Spacing
+
+In consuming apps, the major page sections should be separated vertically by
+`2rem`. This includes the space after the page global `header` and the space
+before the global `footer`. Similarly, the major page sections should be
+separated horizontally by `2rem`.
+
+|                        | Value  | JS Theme Object | CSS Variable                 |
+| ---------------------- | ------ | --------------- | ---------------------------- |
+| **Vertical Spacing**   | `2rem` | `page.vstack`   | `--nypl-spacing-page-vstack` |
+| **Horizontal Spacing** | `2rem` | `page.hstack`   | `--nypl-spacing-page-hstack` |
+
+## Grid Spacing
+
+When elements are displayed in a grid (i.e. Cards, Images, etc.), the space
+between elements, both horizontal and vertical, should be `2rem`.
+
+|                 | Value  | JS Theme Object | CSS Variable                  |
+| --------------- | ------ | --------------- | ----------------------------- |
+| **Default Gap** | `2rem` | `grid.default`  | `--nypl-spacing-grid-default` |
+
+## Form Spacing
+
+Form input components should have a `2rem` space between each form input
+component. This includes both vertical (column) and horizontal (row) stacking.
+The DS [Form](https://nypl.github.io/nypl-design-system/reservoir/v1/?path=/docs/components-form-elements-form--form-with-controls)
+component has correct spacing incorporated into its UI structure and should
+always be used when building forms. Please note that the spacing in the `Form`
+component is identical to the spacing in the `Grid` component.
+
+When `Checkbox` and `Radio` components are grouped together, the components
+should have a `1rem` space between components for vertical (column) stacking
+and a `2rem` space between components for horizontal (row) stacking. The DS
+`CheckboxGroup` and `RadioGroup` components have the correct spacing built
+
+in and should be used respectively when multiple `Checkbox` or `radio`
+components are being used together.
+
+When `Button` components are grouped together, the `Button` components should
+have a `0.5rem` space between component. This includes both vertical (column)
+and horizontal (row) stacking. The DS `ButtonGroup` component has the correct
+spacing built in and should be used when multiple `Button` components are being
+used together.
+
+|                                        | Value    | JS Theme Object              | CSS Variable                                |
+| -------------------------------------- | -------- | ---------------------------- | ------------------------------------------- |
+| **Default Form Gap**                   | `2rem`   | `grid.default`               | `--nypl-spacing-grid-default`               |
+| **Input Group Default Row Spacing**    | `2rem`   | `input.group.default.hstack` | `--nypl-spacing-input-group-default-hstack` |
+| **Input Group Default Column Spacing** | `1rem`   | `input.group.default.vstack` | `--nypl-spacing-input-group-default-vstack` |
+| **Button Group Row Spacing**           | `0.5rem` | `input.group.button.hstack`  | `--nypl-spacing-input-group-button-hstack`  |
+| **Button Group Column Spacing**        | `0.5rem` | `input.group.button.vstack`  | `--nypl-spacing-input-group-button-vstack`  |
+
+## Tabular Data Spacing
+
+When data is displayed in a tabular layout (i.e. rows and columns in a table,
+a description list, etc.), the space between data cells in a row should be
+`1.5rem` and the space between rows should be `2rem`.
+
+|                | Value    | JS Theme Object | CSS Variable                  |
+| -------------- | -------- | --------------- | ----------------------------- |
+| **Column Gap** | `1.5rem` | `table.column`  | `--nypl-spacing-table-column` |
+| **Row Gap**    | `2rem`   | `table.row`     | `--nypl-spacing-table-row`    |
+
+## Figma Reference
+
+For additional spacing information, please refer to the Figma Main file.
+
+- [General Spacing](https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=17249%3A13)
+- [Section Spacing](https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=17185%3A249)
+- [Grid Spacing](https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=17185%3A204)
+- [Tabular Data Spacing](https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/?node-id=10734%3A5146)