Getting started

Read our principles

Before designing and developing the components of your dreams, please read over our principles. Reading our principles will help frame the entire process before any design or development occurs.

After reading our principles please submit your component idea to using our support channels.

Design

All components follow a design process and approval process before any development starts. We have generated a Figma template file that you can reference as a designer to ensure all areas are covered when designing a new component or making refinements. It has a required checklist for each phase. The high-level process is as follows:

Phase 1: Audit

1. Audit our current website: Look at our site for similar patterns related to your present component. If you find a pattern on the site that matches this component document with screenshots, annotate behaviors and variants. It may be the case we do not have this component, and if that is the case, note it in your designs.

2. Audit the web: Visit popular sites and document patterns, behaviors, and variants. The chances are that these popular sites will help inform expected visual and interaction patterns users come to expect from a component.

3. Audit other design systems: It is always best practice to audit other design systems as patterns at a component level is shared between systems. It is best to understand why that pattern, style, or behavior fits that specific product.

4. Audit our design system: Last but not least, audit our own system. Often, we tend to think about visual patterns in isolation, but a design system is a series of interconnected patterns shared across many components. Document the similar patterns, behaviors, or variants of our existing components.

Phase 2: Concept

1. Distill the audit findings: Distill the audit findings into actionable insights. These insights should result in a clear direction on conceptual exploration.

2. Think in WPDS: When designing the component, please think holistically and not for one specific use case. It may require getting in touch base with other designers, product managers, and engineers to understand what this component is trying to resolve.

3. Design in context and out of context: One of the pitfalls when designing a component is that we tend to design in isolation, resulting in a poorly tested component. However, designing for a single context also results in a hyper-specialized component, resulting in a very unflexible component.

4. Use our system: When starting your concepts start with our system. All of our components must utilize our tokens. That means to avoid creating new tokens to fit the concept. Exhaust our system before making new tokens within a new component.

Phase 3: Decide

1. Options: When thinking about component options, consider future use cases and current ones. Don’t feel a need to have multiple options. Some components have only one option, and that is okay.

2. Behaviors: Documenting behaviors include defining states, overflow behavior, responsive behavior, and conditional behavior. You want to make sure your component is flexible and ready to be tested.

3. Guidance: Create clear guidance on the component for others to reference when using it. The direction will help avoid component misuse.

4. Accessibility: All of our components must meet the minimum accessibility requirements for the site laid out by WCAG for AA standards. Please review your component based on those standards. They differ from component to component.

5. Specs: Define the specs using our tokens. Be clear in a fixed size, positioning of elements when scaled, and any other requirements.

Phase 4: Deliver

1. Submit: At the end of the design process comes the submission. At this stage, you have already completed what has outlined above, completed the required checklist in the Figma template, and have received approval from all the parties necessary (Design leadership, WPDS, and other Stakeholders). Next, submissions move to our backlog awaiting development for an engineer to contribute or to be contributed by WPDS team.

Code

All components must follow a predefined design spec. Without a design spec, development cannot occur. If you are interested in a component not in our backlog, please reach out.

Core Tenets

When developing a component, use these core tenets for component design:

1. They should be controlled by their API or left uncontrolled.
2. If a component has multiple DOM nodes such as an Accordion's trigger and its display it should be split into multiple components, such as AccordionTrigger and AccordionDisplay, and use a provider component to manage the state across the two (e.g. AccordionRoot).
3. We should avoid using any DOM APIs that are not supported by evergreen browsers.
4. We should allow modification of styles via the css prop using our tokens (locally and globally scoped components and theme).
5. We should use our theme tokens to style our components.

Ready to Code

1. Check our Jira backlog to make sure that your component is not currently being worked on and check the component section on the docs site double check that it does not already exists. Reach out to the WPDS team on slack if you have any questions.

2. Components live in the wpds-ui-kit. Make sure you can spin up the local dev environment. If you are running into any issues, double check that the node version matches that on the .nvmrc file and that you're using npm v8.3. See WPDS-ui contribution doc for more information.

3. We use conventional commits for every commit. We don't squash our commits from our PR into one before merging to main. We like to keep our git history clean. For example, feat: add new component and stories or fix: update props.

4. On the command line run the new-component scaffolding script npm run new-component <component-name> to get things started. This command will create a component directory for you that includes an index.ts file, a play.stories.jsx, and a <component-name>.tsx file.

5. Add all of your component's logic in the .tsx file. Remember, you should split up complex components into multiple files. We have a list of props we use to make sure we stay consistent. If you need a prop that doesn't fit into one of these, feel free to add your own. Don't forget to document it!

6. Add a storybook example with interactive props so that it's easy for others to see how your component works. If there are multiple variants of your compoment, please add some headers to distinguish them. This should also make it easy to see the different states your component has (what happens on hover, on click, etc.).

7. Add your component to the server side testing page app/pages/index.tsx. This page helps us catch possible server side render issues with all of our compoments.

8. Make a PR and include @WPDS for review. Feel free to add your teammates as well so they can see how easy it is to contribute to WPDS! Once your PR is approved, it's documentation time.

9. All component documentation lives in wpds-ui-kit/build.washingtonpost.com. As the main contributor, you are responsible for documenting your new component. Together with your designer, come up with and document some content, assets, best practices, and any other helpful things someone consuming your component needs. Don't forget to document implementation details and code specific things in the component's README.

10. All components have a Zeplin code snippet available to all who use Zeplin. As the main contributor, you are responsible for connecting your component to Zeplin and creating a code snippet. Follow the steps in Connecting to Zeplin to get your component synced up to Zeplin. Note: in order for this to work, design needs to have added your component to the styleguide.

11. Congratulations, your component is now ready to ship 🎉. Review the release documentation and latest releases to see how we release components. New components are released on a monthly basis.

12. Now that your work is live, others can start to use it! Please note that you are expected to commit to two weeks of support and triage. Please review the support process.