@pantheon-systems/pds-toolkit-react 1.0.0-dev.1 → 1.0.0-dev.100

package/README.md

@@ -1,68 +1,37 @@
 # pds-toolkit-react
 
-React Toolkit for the Pantheon Design System
+## React Toolkit for the Pantheon Design System
 
 This toolkit provides assets for use within a React project and a Storybook instance to preview the components.
 
 [Published Storybook](https://live-pds-toolkit-react.appa.pantheon.site/)
 
-## Local Development Setup
+## Toolkit philosophy and scope
 
-**Prerequisites:** Node 18 and npm
+The intent of this toolkit is to provide a React-based implementation of the Pantheon Design System (PDS) with a focus on semantics, accessibility, visual design, and user-interface design.
 
-1. `npm install` — Installs dependencies
-2. `npm run develop` — Compiles styles, watches for changes, and starts the Storybook development server.
+This toolkit should not contain processes or mechanisms used for data manipulation, business logic, or similar. Therefore, processes such as form handling, routing, and language translation should be handled within the application that is consuming the toolkit.
 
-## Project Structure
+Each component will contain a documentation page within Storybook that provides usage notes, implementation instructions, and expected data structure for that particular component.
 
-Notable directories and files unique to this project.
+### Content within components
 
-### /src/components
+Content should not live within components with a few exceptions — the Social Links component and the links in the legal section of the SiteFooter component. To maintain consistency between all of our digital properties, these links will originate from the design system.
 
-Each component will have its own named directory here. All files specific to the component, test files, and stories file should be included in the directory.
+## Implementation instructions
 
-To create a new component run `npm run generate:component` from the root of the project.
+The toolkit consists of a global stylesheet and React components. Both are required for the toolkit to function as intended.
 
-### /src/docs
+The global stylesheet — `pds-core.css` — provides the base styles for the toolkit including foundations, utilities, and color variables. This stylesheet should be applied at the root of the application.
 
-Any doc pages that do not belong to a specific component.
+The React components are imported and used within the application as needed. Component-specific styles are imported and applied automatically when the component is used.
 
-### /src/foundations
+Components should be imported using named imports. For example:
 
-Includes stylesheets for native HTML elements and other global styles. Styles from this section will be compiled into `pds-core.css`.
+```js
+import { Container, SidebarLayout } from '@pantheon-systems/pds-toolkit-react';
+```
 
-Any stories built in this section are for example purposes only and will not have shipped JavaScript components.
+### Avoid style conflicts
 
-To create a new foundation story run `npm run generate:foundation` from the root of the project.
-
-### /src/patterns
-
-Patterns are reusable configurations of components and other foundational elements.
-
-Any stories built in this section are for example purposes only and will not have shipped JavaScript components.
-
-To create a new pattern story run `npm run generate:pattern` from the root of the project.
-
-### /src/utilities
-
-Utilities include functionality that is used to build components, pages, or other digital experiences in accordance with design system guidelines such as utility classes and functions. Styles from this section will be compiled into `pds-core.css`.
-
-Any stories built in this section are for example purposes only and will not have shipped JavaScript components.
-
-To create a new utility run `npm run generate:utility` from the root of the project.
-
-## Contributing
-
-### Updating a Component
-
-When making changes to a component, be sure to also update any associated tests. (COMING SOON -- tests are not enabled at this time).
-
-### Adding a new Component
-
-Run `npm run generate:component` from the project root to scaffold files necessary for the component.
-
-### Update the Changelog
-
-Add any changes that will affect the consumer of the toolkit to the `Unreleased` section of `CHANGELOG.md`.
-
-When creating a new release, update `CHANGELOG.md` accordingly with the new version number and start a new `Unreleased` section at the top.
+This toolkit is not intended to be used in conjunction with other CSS frameworks. Doing so may result in unexpected behavior and/or visual conflicts.