Skip to content

Commit

Permalink
docs: tidy up existing recipe and page documentation (#1718)
Browse files Browse the repository at this point in the history
- clean up any remaining references to recipes and pages in our documentation
- add link to refer back to zeroheight if someone comes looking here for information
  • Loading branch information
booc0mtaco authored Aug 7, 2023
1 parent 3288ba4 commit 41cf335
Show file tree
Hide file tree
Showing 5 changed files with 6 additions and 132 deletions.
5 changes: 2 additions & 3 deletions .storybook/components/Docs/GettingStarted.stories.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,8 @@ The navigation consists of:

- **Documentation** are a collection of guidelines and explanations for all the written content on this site.
- **Design Tokens** are the reusable CSS variables that can be themed in your application. They are grouped into tiers which describe the specificity of the tokens (with tier one values corresponding to basic definitions, and tier two corresponing to use cases referencing the tier one values, etc.)
- **Components** are all the exported offerings of EDS, combined in one list. They consist of various atoms, molecules, and organisms that can be used in a product, along with relevant documentation, controls, and <kbd>tags</kbd> (describing the component type and status)
- **Pages** are UI prototypes that use the components and recipes to structure the majority of real product pages that will use these. While these are not shipped with the system, the layout using components and recipes can be copied over into the product to represent the majority of the UI.
- **Recipes** are product-specific compositions that use the design system components to structure, but are not shipped with the system. This is to allow for teams to meet their business needs without polluting or complicating the reusable component structure and styling. Read [Brad Frost's post on recipes](https://bradfrost.com/blog/post/design-system-components-recipes-and-snowflakes/) and [our internal documentation on how we use recipes in EDS](/?path=/docs/documentation-recipes--recipes).
- **Components** are all the exported offerings of EDS, combined in one list. They consist of various atoms, molecules, and organisms that can be used in a product, along with relevant documentation, implementation examples controls, and <kbd>tags</kbd> (describing the component type and status)
- **Pages** are a place to demonstrate layouts with other themes and presets applied. Right now, it houses a layout example using our nascent wireframe theme (used when prototyping).

### Storybook Features

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -295,7 +295,7 @@ Use:
}
```

You can continue to use the `Icon` components' `color` prop with JavaScript variables in storybook (including recipes and pages) because those will not be imported and themed in other prodcuts.
You can continue to use the `Icon` components' `color` prop with JavaScript variables in storybook because those will not be imported and themed in other prodcuts.

## Tailwind utility classes <a name="tailwind-utility-classes"></a>

Expand Down
108 changes: 2 additions & 106 deletions .storybook/components/Docs/Guidelines/Components.stories.mdx
Original file line number Diff line number Diff line change
@@ -1,16 +1,8 @@
<Meta title="Documentation/Guidelines/Components" />

# Working with EDS Components, Pages, and Recipes
# Working with EDS Components

This codebase contains all the components, [recipes](https://bradfrost.com/blog/post/design-system-components-recipes-and-snowflakes/), and pages to successfully build the presentation view of product screens.

The top-level organization you can find in storybook is as follows:

- Design tokens
- Documentation
- Components
- Pages
- Recipes
This codebase contains all the components to successfully build the presentation view of product screens. These components are built to exactly match those seen in design mockups.

## Working with components

Expand Down Expand Up @@ -63,96 +55,6 @@ Exceptions can be made for components that are still fluctuating and experiencin

---

## Working with pages

Pages are compositions of components and recipes that operate as a working prototype or "interactive comp" of a product screen ([read more here](https://bradfrost.com/blog/post/atomic-design-and-storybook/)). They are not wired up to any back-end services or application logic, but serve an important purpose of validating that EDS components and recipes all come together to build successful products.

### Using pages

Pages aren't meant to be consumed directly, but rather referenced by application developers. The intention is for pages represented in Storybook to faithfully represent the UI code layer of an application screen.

Application developers can copy and paste page-level code into the application and then begin replacing static data and content with dynamic application code.

### Creating a page

1. Run `yarn plop:page` in the command line.
2. Provide a name when asked "What is your page name?"
3. Plop will generate a page and accompanying stories file at `./storybook/pages/[YourPageName]/[YourPageName].tsx`
4. Begin editing the page, importing any components and recipes required to successfully build the page.
5. Create relevant stories for all page variants

**Note**: pages live in the `.storybook` directory of the project. These do not live in `src` since they are not shipped with the EDS library.

These take on the same structure as the components above:

```
.storybook
--pages
----PageName
------PageName.tsx
------PageName.stories.tsx
```

- `PageName.tsx` contains the HTML and components with mock data applied to render the page
- `PageName.stories.tsx` contains all the [stories](https://storybook.js.org/basics/writing-stories/) for the page.

**Pages** follow this organizational structure in Storybook:

```
Pages
--Page Name
----Default
----Additional States (as needed)
```

---

## Working with recipes

**[Recipes](https://bradfrost.com/blog/post/design-system-components-recipes-and-snowflakes/)** are mainly compositions of design system components that are to be consistently used across products, but aren’t agnostic enough to live in core component library. Like pages, recipes live in the `.storybook` directory of the project since they are not packaged up with the design system. Recipes should follow EDS [code conventions][code-guidelines] as closely as possible in order to make future use across projects as easy as possible.

### Using recipes

Recipes aren't meant to be consumed directly, but rather referenced by application developers. The intention is for recipes represented in Storybook to faithfully represent how to compose core components in EDS to achieve common, useful user interface conventions.

If you have any new ideas for recipes, feel free to reach out via slack to discuss! Or, contribute a new one using the steps below.

### Creating a recipe

1. Run `plop recipe` in the command line.
2. Provide a name when asked "What is your recipe name?"
3. Plop will generate a recipe and accompanying stories file at `./storybook/recipes/[YourRecipeName]/[YourRecipeName].tsx`
4. Begin editing the recipe, importing any necessary components and other recipes.
5. Create relevant stories for all recipe variants

**Note**: Recipes live in `.storybook` directory of the project. These do not live in `src` since they are not shipped with the EDS library.

These take on the same structure as the components above:

```
.storybook
--recipes
----RecipeName
------RecipeName.tsx
------RecipeName.stories.ts
------RecipeName.module.css
```

- `RecipeName.tsx` contains the HTML and components, and may define state and behaviors to demonstrate how the composed components work
- `RecipeName.stories.tsx` contains all the [stories](https://storybook.js.org/basics/writing-stories/) for the recipe.
- `RecipeName.module.css` may contain some light styling to control the composition (e.g., how to use TailwindCSS with the components)

**Recipes** follow this organizational structure in Storybook:

```
Recipe
--Recipe Name
----Default
----Additional States (as needed)
```

---

## Directory structure <a name="directory"></a>

The component stucture is as follows:
Expand All @@ -161,12 +63,6 @@ The component stucture is as follows:
Components
--Component Name
----Component Stories
Pages
--Page Category
----Page Template Name
Recipes
--Recipe Name
----Recipe Stories
```

[code-guidelines]: ./?path=/story/documentation-guidelines-code-guidelines--page
21 changes: 0 additions & 21 deletions .storybook/components/Docs/Recipes.stories.mdx

This file was deleted.

2 changes: 1 addition & 1 deletion src/components/Card/CardWithNotification.module.css
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
\*------------------------------------*/

/**
* Card recipe with a bottom notification.
* Card with a bottom notification.
*/
.card-with-notification {
/**
Expand Down

0 comments on commit 41cf335

Please sign in to comment.