Contributing

We’re excited that you’d like to contribute to Pluma! Before getting started, please review the following resources:

1. General Guidelines

   • View the Pluma Contributing Notion doc for our standards, best practices, and overall project structure.

2. Running Locally

   • Refer to the Pluma README for instructions on how to set up and run the project on your machine.

3. Publishing

   • Please follow the publishing guidelines for using Changesets to manage package versioning and releases.

4. Creating New Components

   • If you’re adding or modifying a component, be sure to read the component creation guidelines for details on naming conventions, folder structure, and tests.

Thank you for helping us improve Pluma! If you have any questions or run into any issues, feel free to open a discussion in the #pluma channel on Slack.

Component API

We have some rules around how to design a good API for a component.

Property names

When adding a new property or changing an existing one, you should follow these rules:

1. use the prefix is or has when affecting state - e.g. isOpen, isHovered, hasError
2. use the prefix on for events or callbacks - e.g. onOpen, onClose, onHover
3. Use the prefix should when affecting behavior - e.g. shouldCloseOnOverlayClick, shouldCloseOnEscape
4. Use the prefix aria when affecting accessibility - e.g. ariaLabel, ariaDescribedBy
5. Use the prefix with when conditionally rendering something - e.g. withIcon, withArrow, withOverlay

Specific names:

1. Use isError when affecting the error state
2. Use isDanger when the style indicates a destructive action
3. Use isDisabled when the component is disabled

Color naming

To ensure consistency, use semantic names like critical, success, caution, and information instead of raw color names like red, yellow, or blue whenever possible. Colors that don't have a semantic name should use their presentational color name (i.e. plum).

Accessibility

Components should make it easy to get accessibility right. This means:

1. Use the aria-* attributes when necessary
2. Use the correct role attribute
3. Use the tabIndex attribute

Follow the ARIA Authoring Practices Guide (APG) when creating a new component.

Size property

When designing a component with multiple sizes you should probably use a size property. It should take shorthand values. For example, size="sm" or size="lg". Long hand values (i.e. size="small") are not extensible and should be avoided.

The one exception to this is font weights where we follow browser standards and use size="normal", size="bold", etc.

Variant property

When designing a component with multiple variants you should probably use a variant property. It should almost always just take the following:

• primary
• secondary
• tertiary
• subtle

Danger variants should be done through a isDanger property, so it can be combined with other variants.

By default, variant should be secondary.

Composite components

Whenever you are creating a component that can contain multiple parts (i.e. a tooltip has a trigger and content), you should use multiple components that compose together. This allows us to have the same API between React and Ember. If most of the use-cases are strings for one of the parts, add a property that takes a string and does the composition to make it easier for the developer to get right.