Skip to content

Commit

Permalink
docs: tidy up existing recipe and page documentation
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
- also link to documentation defining what a canonical recipe is
  • Loading branch information
booc0mtaco committed Aug 4, 2023
1 parent d8a4f6a commit 6ac0cb4
Show file tree
Hide file tree
Showing 5 changed files with 7 additions and 119 deletions.
2 changes: 0 additions & 2 deletions .storybook/components/Docs/GettingStarted.stories.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,6 @@ 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).

### 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
102 changes: 2 additions & 100 deletions .storybook/components/Docs/Guidelines/Components.stories.mdx
Original file line number Diff line number Diff line change
@@ -1,16 +1,14 @@
<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.
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.

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

- Design tokens
- Documentation
- Components
- Pages
- Recipes

## Working with components

Expand Down Expand Up @@ -63,96 +61,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 +69,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
18 changes: 3 additions & 15 deletions .storybook/components/Docs/Recipes.stories.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,8 @@

# Recipes

Recipes are code examples that show EDS components in context of a larger feature.
From [Brad Frost](https://bradfrost.com/blog/post/design-system-components-recipes-and-snowflakes/):

## How does a feature become a recipe?
> Recipe components are specific compositions of design system components (for the most part) that are to be consistently used across a product, but aren’t agnostic enough to live in the design system.
Recipes come from pilots where the EDS team designs a feature or page that will use one or more EDS components. Those pilots are undertaken specifically for the purpose of creating new EDS components and patterns. The EDS team does not implement the resulting design in the product surface area; instead, the EDS team creates the components and also creates recipes showing the components in action. The product team can then use the recipes as a examples for how to implement the feature themselves.

## Does every feature that uses EDS in a product become a recipe?

No, not every feature that uses an EDS component becomes a recipe. If a product team is developing a feature or page on their own and uses an EDS component, the EDS team does not add that feature as a recipe in EDS. Recipes only come from features that the EDS team designs (or codesigns with another team).

## Are recipes imported and used in other products like components?

No, recipes are not used directly in other products. They can be used as examples of how to implement a component on the code side or as general examples of how components can be used in a user interface, but that's all.

## What functions do recipes perform?

Aside from serving as examples for how components can be used (in a user interface or in a code context), they also serve as tests to verify that the components continue to work in the context of a larger feature or page.
Your team may have some recipes already! To learn more about those, refer to your team's tab in [ZeroHeight](https://eds.czi.design/). The page will contain themed recipes specific to your product. If curious, you can find a similar page for other teams' recipes as well.
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 6ac0cb4

Please sign in to comment.