@equinor/echo-components

EchoComponents

This publishable library was generated with Nx.

Building blocks for Echo, built on top of EDS (Equinor Design System).

Online storybook

Publishing static storybook page

• a github action builds and deploys the static storybook page to the following branch: echo-components-storybook - we shouldn't delete this one!
• another github action will pick it up from here, and publish it to a github page

Online storybook can be found here

How to develop and release EchoComponents

Check the readme in the NX libraries folder.

Available NPM scripts

• lint-components
• build-components
• test-components

Old repository of echoComponents

Keeping it for historical reasons. https://github.com/equinor/EchoComponents

Guidelines for developing

Composition

When deciding how to write your new component consider the composition. Using smaller interchangeable components that each represent a specific function or feature in the context of a larger component. Using wrapper components in conjunction with the children property, allows for a greater separation of concerns, smaller blocks of code and a greater level of customization in the final product.

Example: Card Component

<Card.Container> {/* REQUIRED */}
    <Card.Image src="hello_world.jpg"> {/* INTERCHANGEABLE */}
        <Card.Caption>Descriptive text</Card.Caption> {/* INTERCHANGEABLE */}
        <Card.Heading>Heading</Card.Heading> {/* INTERCHANGEABLE */}
        <Card.Ingress>Subtitle/Ingress</Card.Ingress> {/* INTERCHANGEABLE */}
        <Card.Article>Main content</Card.Article> {/* INTERCHANGEABLE */}
    </Card.Image>
</Card.Container>

The makeup of each component may vary depending on the feature and the problem being solved. Some components may not be interchangeable, and some components may need additional props.

Abstracting the individual composition should be possible, by creating a new component in the project that can act as a bootstrapping mechanism for the EchoComponent composition.

Example: Bootstrapping Card Components

import React from 'react';

type Props = {
    heading: string;
    mainContent: string;
    imageSrc?: string;
    imageCaption?: string;
    ingress?: string;
};

export const ExampleCard: React.FC<Props> = ({ heading, mainContent, imageSrc, imageCaption, ingress }) => {
    return (
        <Card.Container>
            <Card.Image src={imageSrc}>
                {imageCaption && <Card.Caption>{imageCaption}</Card.Caption>}
                <Card.Heading>{heading}</Card.Heading>
                {ingress && <Card.Ingress>{ingress}</Card.Ingress>}
                <Card.Article>{mainContent}</Card.Article>
            </Card.Image>
        </Card.Container>
    );
};

export default ExampleCard;

Developer Checklist

1. Keep components small, focused with a single responsibility where possible.
2. When possible, use wrapper components with properties for children and className.
3. className should always be included, to allow for custom styling when needed. (see point 6. for more information on custom styling)
4. Styling of components should always be done with CSS Modules.
5. Make sure the component(s) accurately reflect the provided UX sketches, but do not be afraid to challenge the UX sketches if they have not accounted for specific uses case, and/or present a unusually difficult challenge.
6. Allowing custom styling of individual components does not mean developers have free rein to do as they please. Custom styling should always be approved by UX and only when it makes sense for the user experience.
7. When naming components always check if the UX sketches already have a name, if not make the name as intuitive and descriptive as possible.
8. Add each component to Storybook with default props, examples, and explanations (when needed).