From 755dca55c763d6702a2eec23a66a10aed4e8f8d3 Mon Sep 17 00:00:00 2001 From: Andrew Holloway Date: Fri, 4 Aug 2023 16:10:56 -0500 Subject: [PATCH] docs: tidy up existing recipe and page documentation - 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 --- .../Docs/GettingStarted.stories.mdx | 5 +- .../Guidelines/CodeGuidelines.stories.mdx | 2 +- .../Docs/Guidelines/Components.stories.mdx | 108 +----------------- .../components/Docs/Recipes.stories.mdx | 18 +-- .../Card/CardWithNotification.module.css | 2 +- 5 files changed, 9 insertions(+), 126 deletions(-) diff --git a/.storybook/components/Docs/GettingStarted.stories.mdx b/.storybook/components/Docs/GettingStarted.stories.mdx index 739578838..67b015605 100644 --- a/.storybook/components/Docs/GettingStarted.stories.mdx +++ b/.storybook/components/Docs/GettingStarted.stories.mdx @@ -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 tags (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 tags (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 diff --git a/.storybook/components/Docs/Guidelines/CodeGuidelines.stories.mdx b/.storybook/components/Docs/Guidelines/CodeGuidelines.stories.mdx index 9b5318b5f..6b4ed9d54 100644 --- a/.storybook/components/Docs/Guidelines/CodeGuidelines.stories.mdx +++ b/.storybook/components/Docs/Guidelines/CodeGuidelines.stories.mdx @@ -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 diff --git a/.storybook/components/Docs/Guidelines/Components.stories.mdx b/.storybook/components/Docs/Guidelines/Components.stories.mdx index bae1e6bc1..365e03a39 100644 --- a/.storybook/components/Docs/Guidelines/Components.stories.mdx +++ b/.storybook/components/Docs/Guidelines/Components.stories.mdx @@ -1,16 +1,8 @@ -# 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 @@ -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 The component stucture is as follows: @@ -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 diff --git a/.storybook/components/Docs/Recipes.stories.mdx b/.storybook/components/Docs/Recipes.stories.mdx index d6d9baf05..cd2e91e61 100644 --- a/.storybook/components/Docs/Recipes.stories.mdx +++ b/.storybook/components/Docs/Recipes.stories.mdx @@ -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. \ No newline at end of file diff --git a/src/components/Card/CardWithNotification.module.css b/src/components/Card/CardWithNotification.module.css index 55977448a..4b1eb4c2d 100644 --- a/src/components/Card/CardWithNotification.module.css +++ b/src/components/Card/CardWithNotification.module.css @@ -5,7 +5,7 @@ \*------------------------------------*/ /** - * Card recipe with a bottom notification. + * Card with a bottom notification. */ .card-with-notification { /**