@nypl/design-system-react-components 1.0.0 → 1.0.3-beta

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

@@ -1,194 +0,0 @@
-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

@@ -1,43 +0,0 @@
-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

@@ -1,201 +0,0 @@
-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

@@ -1,193 +0,0 @@
-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.