Skip to content

Latest commit

 

History

History
93 lines (61 loc) · 6.39 KB

component-creation-guide.md

File metadata and controls

93 lines (61 loc) · 6.39 KB
Raw
layout title section order
article
Component Creation Guide
contribute
2
  • TOC {:toc}

Getting Started

So you've got a great idea for a new component and want to bring it to life! What's the process look like for going from initial concept to Official Elemental Design Component? There are three key steps to the process of creating a new component:

  1. Announce
    Let everyone know your idea for a component and begin to gather feedback. This is important for reducing duplicative effort and ensuring you have all the info to make a broadly useful component.

  2. Define
    Describe and specify your component, from general features to usage guidelines to specific colors and dimensions.

  3. Implement
    Transform your design into code and produce the final package which can be consumed by other teams.

After steps 2 and 3 you'll need to submit your work for review against the Library Membership Specification.

Resources

There are a few key documents that will get you started down the right path when creating a new component. Take a minute to read through these and feel free to ask any questions you have on the mailing list.

Library Membership Specification
The Library Membership Specification details everything that makes a high quality component. Each component will need to fulfill the requirements listed in this document so it's a good idea to familiarize yourself with them. Approval happens in two steps, once for the component definition (where the design requirements are used) and again for the implementation (against the development requirements).

Component Versioning Guide
Your iterations should also follow the standard versioning scheme. This can be helpful for managing communication as you make improvements to your design as well as keeping track of any dependencies your component has.

1. Announce

Once you have a handle on the Elemental Design infrastructure the next step is to share your idea with the community and gather feedback. This helps maximize usefulness of the final component and can uncover speed bumps early in the process. Suggested topics include:

  • Proposed component name
  • Description of the specific problem your team is trying to solve
  • Example use cases from across the platform
  • If there are any existing components which might be similar, points on why a new one is needed
  • Illustrative wireframes
  • Any pitfalls or problems you can foresee
  • List of teams that will function as stakeholders, dependencies, etc.

Your goals for the discussion should include:

  • Identifying key stakeholders and partners
  • Finding other teams who might consume the new component
  • Learning more about any potential constraints you’ll need to design around
  • Identifying any dependencies you might have on other teams

Begin the discussion by posting a new thread in the Component Proposals category of the mailing list.

2. Define

In the case that you proceed with a new component the next step is to begin designing and defining it. Your output at this stage is a component definition which will detail the features, usage, design, and behavior of your idea. Review the existing component documentation for examples of good definitions.

Design documentation is currently hosted in this Github Pages repository. Follow the readme file to get started with your own component definition page. (We're planning to add a guide dedicated to this topic in the future.)

As you work on coalescing your idea you should publish your project to the mailing list and use version numbers (with the 'beta' modifier) to track progress. This allows interested parties to track your progress and provide feedback as you work.

Definition Approval

Once your definition reaches a final state you'll need to submit it to the review board to check compliance with the Design Requirements from the membership specification. If everything in the spec is satisfied you can proceed to implementing your design. If anything doesn't line up, the approvers will work with you to bring your component into alignment with the spec.

Submit a definition for review by sending an email to [email protected]. Make sure to include a link to your work and a copy of the approval checklist (choose File > Make a copy).

3. Implement

Once your definition is approved you can begin building out the implementation. If your component is large enough to warrant being a standalone component, start with the component archetype based on React, available at https://github.com/Pearson-Higher-Ed/component-archetype. Otherwise it should be implemented in the Elements SDK https://github.com/Pearson-Higher-Ed/elements-sdk. This will be the fastest route to Origami spec compliance.

Implementation Approval

Last step! Once you've built a functional version of your component you can submit it for final review by the board (simply email [email protected] again). At this point they will ensure the final product matches your definition and continues to fulfill the membership specification. If everything looks good the component will be added to the library! If there are any issues the approvers will work with you to bring things in line with the spec.

Component Maintenance

Your component is now complete and in the library, although you will probably want to add new features over time and find bugs you want to fix. Make sure to follow the component versioning guide as you make changes and continue to publish beta iterations to the mailing list.

Note that you'll need to resubmit any modifications to the review board if you add new features or make breaking changes (anything that increments the Major or Minor version numbers) but bug fixes can be pushed through without review.

See Modifying and Updating Components for more information.