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

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

@@ -0,0 +1,194 @@
+import { Canvas, Meta } from "@storybook/addon-docs";
+
+import Button from "../Button/Button";
+import ButtonGroup from "../ButtonGroup/ButtonGroup";
+import Icon from "../Icons/Icon";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta title={getCategory("Buttons")} />
+
+# Buttons
+
+| Table of Contents                              |
+| ---------------------------------------------- |
+| 1. [General Information](#general-information) |
+| 2. [Guidelines](#guidelines)                   |
+| 3. [Button Groups](#button-groups)             |
+| 4. [Button Types](#button-types)               |
+| 5. [Patterns](#patterns)                       |
+| 6. [Figma Reference](#figma-reference)         |
+
+## General Information
+
+Use the [Button](https://nypl.github.io/nypl-design-system/reservoir/v1/?path=/docs/components-form-elements-button--button-with-controls)
+component to render form buttons.
+
+```jsx
+import { Button } from "@nypl/design-system-react-components";
+
+<Button id="btn">Button Text</Button>;
+```
+
+## Guidelines
+
+- Button text is optional.
+- Button text should be title case.
+- Button icon is optional.
+- Buttons may have an icon on either the left or the right.
+- Buttons by default are blue. However, Donation callout buttons are red.
+- Buttons used for Back to Top actions have a Secondary button style with an
+  arrow icon pointing up.
+- When buttons are used in a group, they should be wrapped in a `ButtonGroup`.
+- When buttons are used in a group where the user can move forward or backward,
+  the `Primary` button is on the right and the `Secondary` button on the left
+  (i.e. cancel = secondary, submit = primary).
+
+## Button Groups
+
+When `Button` components are displayed in a group, use the `ButtonGroup`
+component to handle the spacing and layout. The `ButtonGroup` component will use
+`--nypl-space-xs` (0.5rem) for spacing in horizontal group layouts.
+
+Standalone `Button` components and the `ButtonGroup` component should use
+`--nypl-space-l` (2rem) for spacing between all other UI elements. This spacing
+can be achieved by using the `Form` component to wrap the `Button`s.
+
+<Canvas>
+  <DSProvider>
+    <ButtonGroup>
+      <Button id="basic">Button Text</Button>
+      <Button id="btn-search">
+        <Icon name="search" size="small" align="left" />
+        Button Text
+      </Button>
+      <Button id="only-icon">
+        <Icon name="close" size="medium" />
+      </Button>
+      <Button buttonType="callout" id="donate">
+        Donate
+      </Button>
+      <Button buttonType="secondary" id="btn-back-to-top">
+        Back to Top
+        <Icon
+          name="arrow"
+          size="small"
+          align="right"
+          iconRotation="rotate180"
+        />
+      </Button>
+    </ButtonGroup>
+  </DSProvider>
+</Canvas>
+
+## Button Types
+
+The `buttonType` prop should be used to render various forms of the button
+component.
+
+<Canvas>
+  <DSProvider>
+    <ButtonGroup>
+      <Button buttonType="primary" id="primary">
+        Primary Button
+      </Button>
+      <Button buttonType="secondary" id="secondary">
+        Secondary Button
+      </Button>
+      <Button buttonType="callout" id="callout">
+        Callout Button
+      </Button>
+      <Button buttonType="pill" id="pill">
+        Pill Button
+      </Button>
+      <Button buttonType="link" id="link">
+        Link Button
+      </Button>
+      <Button buttonType="noBrand" id="noBrand">
+        NoBrand Button
+      </Button>
+    </ButtonGroup>
+  </DSProvider>
+</Canvas>
+
+### Primary
+
+- used for actions that move the user forward
+- Visual Treatment: rectangular, filled
+
+### Secondary
+
+- used for actions that move the user back, such as a form cancel button
+- often paired with a Primary button
+- Visual Treatment: rectangular, outlined
+
+### Callout
+
+- used for call to actions such as donation buttons
+- Visual Treatment: rectangular, NYPL red background
+
+### Pill
+
+- used for equally weighted actions
+- should only be used for buttons that are displayed in a set (i.e. never use for a singleton button)
+- Visual Treatment: rounded, outlined
+
+### Link
+
+- used for equally weighted actions
+- Visual Treatment: text link with underline
+
+### NoBrand
+
+- used in cases where there is no brand color
+- Visual Treatment: rectangular, filled with a black background
+
+## Patterns
+
+- Buttons are blue by default.
+- Buttons that are intended as a call out (i.e. Donation buttons) should be set
+  as `"callout"`.
+- The "Back to Top" button must be set as `"secondary"` and must include an up
+  arrow icon.
+- Previous and Next buttons should be set as `"secondary"` and be wrapped in a
+  `ButtonGroup`.
+- Only use the `"noBrand"` style where there is no brand color. _This should be
+  rarely used._
+
+<Canvas>
+  <DSProvider>
+    <ButtonGroup>
+      <Button buttonType="callout" id="callout2">
+        Donate to this library
+      </Button>
+      <Button buttonType="secondary" id="secondary2">
+        Back to Top
+        <Icon
+          align="right"
+          iconRotation="rotate180"
+          name="arrow"
+          size="small"
+        />
+      </Button>
+      <Button buttonType="secondary" id="previous">
+        <Icon align="left" iconRotation="rotate90" name="arrow" size="small" />
+        Previous
+      </Button>
+      <Button buttonType="secondary" id="next">
+        Next
+        <Icon
+          align="right"
+          iconRotation="rotate270"
+          name="arrow"
+          size="small"
+        />
+      </Button>
+    </ButtonGroup>
+  </DSProvider>
+</Canvas>
+
+## Figma Reference
+
+For more styling information, please refer to the Figma Main file.
+
+- https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11477%3A2298

package/src/components/StyleGuide/ColorCard.tsx

@@ -0,0 +1,43 @@
+import * as React from "react";
+
+import Card from "../Card/Card";
+import Heading from "../Heading/Heading";
+
+export interface ColorCardProps {
+  /** backgroundColor of the color card */
+  backgroundColor: string;
+  /** name of the CSS var */
+  colorName: string;
+}
+
+/**
+ * ColorCard
+ * Component only used for Storybook.
+ */
+export default function ColorCard(
+  props: React.PropsWithChildren<ColorCardProps>
+) {
+  const { backgroundColor, colorName = "" } = props;
+
+  return (
+    <div style={{ display: "flex", alignItems: "center" }}>
+      <Card
+        backgroundColor={backgroundColor}
+        isBordered
+        isCentered
+        layout="column"
+      />
+      <div style={{ marginLeft: "1rem" }}>
+        <Heading level="four">{colorName}</Heading>
+        {/* 
+        TODO:
+        This code is returning the CSS variable name.  This is not what we 
+        want.  Rather, we want to see the variable's hex value.  This is 
+        somethign we will need to come back to.
+
+        <Text noSpace>{backgroundColor}</Text> 
+        */}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,201 @@
+import { Canvas, Meta } from "@storybook/addon-docs";
+
+import ColorCard from "./ColorCard";
+import Heading from "../Heading/Heading";
+import SimpleGrid from "../Grid/SimpleGrid";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+export const cssVars = {
+  brand: ["--nypl-colors-brand-primary", "--nypl-colors-brand-secondary"],
+  blogs: [
+    "--nypl-colors-section-blogs-primary",
+    "--nypl-colors-section-blogs-secondary",
+  ],
+  booksAndMore: [
+    "--nypl-colors-section-books-and-more-primary",
+    "--nypl-colors-section-books-and-more-secondary",
+  ],
+  education: [
+    "--nypl-colors-section-education-primary",
+    "--nypl-colors-section-education-secondary",
+  ],
+  locations: [
+    "--nypl-colors-section-locations-primary",
+    "--nypl-colors-section-locations-secondary",
+  ],
+  research: [
+    "--nypl-colors-section-research-primary",
+    "--nypl-colors-section-research-secondary",
+  ],
+  researchLibraries: [
+    "--nypl-colors-section-research-library-lpa",
+    "--nypl-colors-section-research-library-schomburg",
+    "--nypl-colors-section-research-library-schwartzman",
+  ],
+  whatsOn: [
+    "--nypl-colors-section-whats-on-primary",
+    "--nypl-colors-section-whats-on-secondary",
+  ],
+  ui: [
+    "--nypl-colors-ui-black",
+    "--nypl-colors-ui-white",
+    "--nypl-colors-ui-disabled-primary",
+    "--nypl-colors-ui-disabled-secondary",
+    "--nypl-colors-ui-error-primary",
+    "--nypl-colors-ui-error-secondary",
+    "--nypl-colors-ui-focus",
+    "--nypl-colors-ui-link-primary",
+    "--nypl-colors-ui-link-secondary",
+    "--nypl-colors-ui-status-primary",
+    "--nypl-colors-ui-status-secondary",
+    "--nypl-colors-ui-success-primary",
+    "--nypl-colors-ui-success-secondary",
+    "--nypl-colors-ui-test",
+    "--nypl-colors-ui-warning-primary",
+    "--nypl-colors-ui-warning-secondary",
+  ],
+  grayscale: [
+    "--nypl-colors-ui-gray-xdark",
+    "--nypl-colors-ui-gray-dark",
+    "--nypl-colors-ui-gray-medium",
+    "--nypl-colors-ui-gray-light-cool",
+    "--nypl-colors-ui-gray-light-warm",
+    "--nypl-colors-ui-gray-x-light-cool",
+    "--nypl-colors-ui-gray-x-light-warm",
+    "--nypl-colors-ui-gray-xx-light-cool",
+  ],
+};
+
+export const makeColorCard = function (key) {
+  const cssValue = `var(${key})`;
+  const card = (
+    <ColorCard backgroundColor={cssValue} colorName={key} key={key} />
+  );
+  return card;
+};
+
+export const getColorCards = (cat) => {
+  const cards = [];
+  const catArr = cssVars[cat];
+  for (let i = 0; i < catArr.length; i++) {
+    const varName = catArr[i];
+    const card = makeColorCard(varName);
+    cards.push(card);
+  }
+  return cards;
+};
+
+<Meta title={getCategory("Colors")} />
+
+# NYPL Colors
+
+| Table of Contents                        |
+| ---------------------------------------- |
+| 1. [Brand Colors](#brand-colors)         |
+| 2. [Section Colors](#section-colors)     |
+| 3. [Utility Colors](#utility-colors)     |
+| 3. [Grayscale Colors](#grayscale-colors) |
+| 4. [Figma Reference](#figma-reference)   |
+
+## Brand Colors
+
+Brand fills are the NYPL primary and secondary colors.
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns={1}>{getColorCards("brand")}</SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+## Section Colors
+
+Section colors are branding colors only in use at NYPL.
+
+<Canvas>
+  <DSProvider>
+    <Heading>Blogs</Heading>
+    <p>Blogs is used for the Blogs section.</p>
+    <SimpleGrid columns={1}>{getColorCards("blogs")}</SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading>Books and More</Heading>
+    <p>
+      Books and More is used for the Catalog, Staff Picks, Recommendations, New
+      Arrivals, and E-Book Central.
+    </p>
+    <SimpleGrid columns={1}>{getColorCards("booksAndMore")}</SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading>Education</Heading>
+    <p>
+      Education is used for the Education section front and all associated
+      sub-sections.
+    </p>
+    <SimpleGrid columns={1}>{getColorCards("education")}</SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading>Locations</Heading>
+    <p>
+      Locations is used for Location Finder and all branch pages with the
+      exceptions of some research libraries.
+    </p>
+    <SimpleGrid columns={1}>{getColorCards("locations")}</SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading>Research</Heading>
+    <p>Research is used for the Research Catalog and SCC.</p>
+    <SimpleGrid columns={1}>{getColorCards("research")}</SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading>Research Libraries</Heading>
+    <p>Research libraries with specific brand colors to adhere to.</p>
+    <SimpleGrid columns={1}>{getColorCards("researchLibraries")}</SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+<Canvas>
+  <DSProvider>
+    <Heading>What's On</Heading>
+    <p>What's On is used for Events, Exhibitions &amp; Audio Guides.</p>
+    <SimpleGrid columns={1}>{getColorCards("whatsOn")}</SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+## Utility Colors
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns={1}>{getColorCards("ui")}</SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+## Grayscale Colors
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns={1}>{getColorCards("grayscale")}</SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+## Figma Reference
+
+For additional spacing information, please refer to the Figma Main file.
+
+- [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=47083%3A27674)

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

@@ -0,0 +1,193 @@
+import { Meta } from "@storybook/addon-docs";
+
+import { getCategory } from "../../utils/componentCategories";
+
+<Meta title={getCategory("Design Tokens")} />
+
+# Design Tokens
+
+| Table of Contents                                                                              |
+| ---------------------------------------------------------------------------------------------- |
+| 1. [What are Design Tokens?](#what-are-design-tokens)                                          |
+| 2. [Why Use Design Tokens?](#why-use-design-tokens)                                            |
+| 3. [How to Use the Reservoir Design Tokens](#figma-reference)                                  |
+| 4. [Using Reservoir Design Tokens in CSS](#using-reservoir-design-tokens-in-css)               |
+| 5. [Using Reservoir Design Tokens in Javascript](#using-reservoir-design-tokens-in-javascript) |
+| 6. [Reservoir Design Token Categories](#reservoir-design-token-categories)                     |
+
+## What are Design Tokens?
+
+Design tokens are the style values that define a design system. These values
+can include, but may not be limited to, spacing, color, typography, breakpoints
+and object styles. Ultimately, these values are used to construct and maintain
+the components that make up our system.
+
+## Why Use Design Tokens?
+
+_"With design tokens, you can capture low-level values and then use them to
+create the styles for your product or app. You can maintain a scalable and
+consistent visual system for UI development."_ - Jina Bolton, Lead Designer
+for the Salesforce Design System
+
+Design tokens are a single source of truth when it comes to styles. They allow
+an organization to more easily build multiple applications - web and/or native -
+that feel and look the same without slowing down the development team.
+
+## How to Use the Reservoir Design Tokens
+
+The NYPL design tokens are built into the Reservoir Design System (DS) and are
+offered in two formats for consumption: CSS variables and javascript data
+objects. To access either of these formats, the DS `v0.25.9` or higher needs
+to be properly installed in a consuming React application.
+
+## Using Reservoir Design Tokens in CSS
+
+If your app uses CSS or SCSS to handle styles, the DS creates standard CSS
+custom properties (e.g. variables) for consumption in your stylesheets. If the
+DS is properly installed, the CSS custom properties will be available for you
+to use. Nothing more needs to be done to your app.
+
+To assist with CSS scope isolation, all of the CSS custom properties created
+by the DS are prefixed with "nypl." Please see the examples below.
+
+```css
+--nypl-colors-brand-primary
+--nypl-colors-brand-secondary
+--nypl-fontSizes-sm
+--nypl-fontSizes-md
+--nypl-fontSizes-lg
+--nypl-fontSizes-xl
+--nypl-space-xxs
+--nypl-space-xs
+--nypl-space-s
+--nypl-space-m
+--nypl-space-l
+```
+
+The CSS custom properties are defined on the :root pseudo-class and should be
+implemented using standard CSS custom properties conventions.
+
+```css
+/* Property Declaration in the DS */
+:root {
+  --nypl-colors-brand-primary: #c60917;
+}
+
+/* Property Usage in Your Application */
+.custom-button {
+  background: var(--nypl-colors-brand-primary);
+}
+```
+
+## Using Reservoir Design Tokens in Javascript
+
+If you would like to use CSS-in-JS styles in your React components, the
+`useNYPLTheme` hook will provide you with Reservoir design token values. The hook
+depends on the `DSProvider` component and will not work properly outside of
+the `DSProvider` wrapper component.
+
+After importing and implementing the `DSProvider` wrapper component, as
+explained in the `DSProvider` section of the [DS Chakra UI](?path=/story/chakra-ui--page#dsprovider)
+document, your children components can use this hook function.
+
+```tsx
+import { useNYPLTheme } from "@nypl/design-system-react-components";
+const theme = useNYPLTheme();
+```
+
+The theme variable will be a javascript object containing the NYPL design
+token style values. This will allow you to use design token values in your
+components through CSS-in-JS.
+
+```tsx
+// theme
+{
+  breakpoints: { ... },
+  colors: {
+    brand: { ... },
+    section: { ... },
+    transparent: { ... },
+    ui: { ... },
+  },
+  fontSizes: { ... },
+  fontWeights: { ... },
+  fonts: { ... },
+  radii: { ... },
+  space: { ... },
+}
+```
+
+#### Using in DS Components
+
+The general rule of thumb is that DS components and the available variants
+should be used with the styles and variants as they are shown in Storybook,
+but there may be rare times when a component does require a modification.
+That said, if a DS component does need an updated style, first contact the
+Design System and UX teams about this update.
+
+If you receive approval to make a change in a consuming app, then you can add
+styles directly as style props. For example, if the `Heading` component needs to
+render text in Reservoir's "success primary" green color and add a bold font
+weight, then you can do the following:
+
+```tsx
+const theme = useNYPLTheme();
+
+// ...
+return (
+  <div>
+    <Heading
+      level={2}
+      color={theme.colors.ui.success.primary}
+      fontWeight={theme.fontWeights.bold}
+    >
+      Get a Digital Library Card Today in a Few Easy Steps
+    </Heading>
+  </div>
+);
+```
+
+IMPORTANT: At the moment, not all DS components have this prop or feature.
+
+#### Using in HTML Components
+
+For styling standard HTML elements, use the `style` attribute to add inline styles.
+
+```html
+<p style={{ color: theme.colors.ui.success.primary }}>
+  If you are 13 or older and live, work, attend school, or pay property
+  taxes in New York State, you can get a free digital library card right
+  now using this online form. Visitors to New York State can also use this
+  form to apply for a temporary card.
+</p>
+```
+
+#### Using in Styled Components
+
+For adding theme styles to styled-objects, use the theme object as a standard javascript variable.
+
+```tsx
+const CustomButton = styled.button`
+  background: ${theme.colors.brand.primary};
+`;
+```
+
+## Reservoir Design Token Categories
+
+The DS design tokens are broken into the following categories:
+
+- [breakpoints](?path=/story/documentation-style-guide-breakpoints--page)
+- [colors](?path=/story/documentation-style-guide-colors--page)
+  - brand
+  - section
+  - transparent
+  - ui
+- radii
+- [spacing](?path=/story/documentation-style-guide-spacing--page)
+- [typography](?path=/story/documentation-style-guide-typography--page)
+  - font families
+  - font sizes
+  - font weights
+
+For details related to a specific category, please refer to the corresponding
+section in the Style Guide available in the DS Storybook.