Component

Understand how to create a Shoreline component, whether it is a new component, propose an improvement, or fix a bug. Only components that follow these guidelines will be allowed to be added to the library.

Patterns

• When creating a component, understand its web standards. Use W3C (opens in a new tab) as a reference.
• Any color combination must pass the mid-range conformance level for accessibility requirements AA.
• If your component uses another existing one, reuse it. For example, a new component that has a button must use the Shoreline Button.

Structure

Tokens usage

• Always use Shoreline tokens (opens in a new tab) for all spacing, color, typography, and shadow values when building a component.
• We do not recommend using custom values. Always thoroughly test the use of tokens before proposing anything customized.

Autolayout and constraints

• Apply auto layout and constraints whenever possible, ensuring responsiveness, correct spacing, and scalability in the component's application.
• We do not recommend using Groups in components.

Height and width

Apply definitions of max/min-height or width whenever they exist. For example, form fields always use 320px, since the mobile width is 360px and has a 20px margin on each side.

Layers

• Optimize the use of layers as much as possible.
• Look at other components with similar elements to better understand the names already used.
• Name the layer in a way that precisely indicates what it contains, whether it's a single element or a group.
  • Assign a label as the name for icon instances and text layers. For example, a text layer "Search..." is renamed to Placeholder.
  • When a layer is a group of other layers, name it with the names of the internal layers using the "+" symbol between the names. For example, the layer containing the icon and the message of the Alert is named Icon + Message, for any variant of the Alert, and contains the layers [IconName], keeping the original name of the icon since each variant uses a specific icon, and Message.
  • When an Icon from a component can be replaced with other icons, its layer is named Icon.
  • Shapes and vector layers should also follow the same logic. For example, the layer of the arrow shape in the Tooltip is named Tip.

Variants and properties

Usage

• Look at other components to better understand the patterns of property names already used.
• Maximize the number of variants and leverage properties (boolean, instance swap, text) to create less complex, high-performance, and easy-to-apply components.
• Some components exist to serve many different scenarios, such as the Table (opens in a new tab), and it's impractical to create a component that covers 100% of them. Therefore, it's acceptable for some components to need to be detached when applying it. Always consider the acceptable limit of variants that meet the usage needs while keeping the component optimized.
• Include all applicable states. For example, default, hover, pressed, focus, disabled, loading, empty, no results, error loading, error searching, and dragging.
  • Reuse styles from the hover state for the focus state.
  • When there's a focus ring, apply clip content and background color to all variants.
• Expose properties of nested instances whenever possible. Sequentially name nested instances. For example, Row 1, Row 2, and Row 3 in a Table.

Naming

• Name a property in a way that directly indicates what is being configured. Do not include verbs. For example, a property for the states of a component will be called state, a property to change the error text will be called errorText, and a property to toggle the label of the Input will be called label.
• Use camelCase for the names of properties and variants.
• Properties that are used to edit a value, such as text or instance swap, should always have a period (.) at the end. Figma does not allow two properties with the same name, and usually, these value properties coexist with another visibility property of the same element.

Prototype

• Connect only the default state with the hover state.
• Avoid creating too many connections in the component, as this can make its application difficult.
• Use transition animation that will be implemented in code, or Instant when in doubt.

Library organization

Name and description

• Define the name according to how the component is best known in the market and use TitleCase, without spaces between words.
• Write the description using a maximum of two short sentences, including the component's function and, if necessary, any relevant behavior or property.
• Use W3C (opens in a new tab), The Component Gallery (opens in a new tab), Material Design (opens in a new tab), and other well-established design systems as references.

Component

• The documentation of a component in the library (opens in a new tab) should always follow the component section template (opens in a new tab). Follow the instructions included in the template.
• Follow the alphabetical order to organize the sections of the components, including the order of the layers.

• Follow the pattern in organizing the component variants.
  • Position the default variant in the top-left corner.
  • Spacing of at least 20px between variants.
• Component frame with padding of 200px whenever possible, or at least 100px, and without borders.
• Base components (parts of the component that are not used by themselves) should always have the emoji ⚙️ at the beginning of the name.
• Fill in the Component configuration.
  • Include a description of the component, keywords (other names by which the component may be known), and implementation status (for a new component, the status will be Not implemented yet).
  • Select the option "Simplify all instances".
  • The link will only be filled in after the component is published on the documentation website.

• Order the variants and the values of each variant to follow a logical order.
  • Properties that depend on another boolean property should be below it. For example, the value property of a label is below the boolean property of the label.
  • In the absence of a logical order, follow alphabetical order.

Documentation

All components must have documentation on the Shoreline website (opens in a new tab).

Related components

Define the related components that appear on the main page of a component by answering the question: which other components have an application that may generate doubt regarding the new component? For example, there may be confusion between the application of a Button and an IconButton, so the IconButton is included as a related component (opens in a new tab) of the Button.

Best practices

• Visual components should always have Best practices documentation.
• Look at other components to better understand the patterns.
• Depending on the content, write in bullet points or include it in tables,
• The documentation content should always be part of one of the sections: Properties, Position, and Behavior. Not all components will have all three.
  • In Properties, describe the usage and guidelines for each property of the component. For example, the application scenarios for each variant, how to write a Label, or which icon to use. Each property should be a subsection.
  • In Position, describe where the component should be positioned in a container or how parts of a component should be positioned within it.
  • In Behavior, describe the possible behaviors of the component. For example, when the component is disabled, when it's in a loading state, or when it has scrolling.