Recommended structure

src/
	# Import, export and declare all our components
	components.js 
  # Group all the tokens in our system
	tokens.js
	# Structure example for our component
	/button
		button.{js,jsx,ts,tsx}
		button.md
		button.test.js

We will analyze the above.

src/components.js

File that imports, exports and declares all the components of our design system, example:

import { Button } from "./button/button";
export { Button } from "./button/button";

customElements.define("my-button", Button);

the utilities of this are to centralize everything in components.js are:

1. Clarity of the definition of customElements in a single file for our entire design system

2. Export of all customElements to be extended or redefined.

src/tokens.js

File that centralizes the custom-properties of our design system, example:

import { css } from "atomico";

export const tokensInput = css`
  :host {
    --background: var(--my-ds-input--background, #fff);
    --border-width: var(--my-ds-input--border-width, 1px);
    --border-color: var(--my-ds-input--border-color, black);
    --radius: var(--my-ds-input--radius, 0.5rem);
    --min-height: var(--my-ds-input--min-height, 40px);
  }
`;

export const tokenColors = css`
  :host {
    --primary: var(--my-ds--primary);
    --secondary: var(--my-ds--secondary);
    --success: var(--my-ds--warning);
    --warning: var(--my-ds--warning);
    --danger: var(--my-ds--warning);
    --info: var(--my-ds--warning);
  }
`;

From the example above I highlight the custom property declaration pattern

:host {
    --background: var(--my-ds-input--background, #fff);
}

--background will be a token that can be modified at the instance level and this inherits a global token from our system called --my-ds-input--background, I want you to notice that the global name of our custom property has a pattern, example:

---my-ds-input--background
---<prefix>-<namespace>--<property>

Where:

1. prefix: Prefix of our global design system

2. namespace: group independent of our design system

3. property: property associated with the system, such as color, size, or other value.

Why use the recommended pattern? To individualize the configuration at the group level and separate the property definition from it thanks to the use of double hyphens (--), internally everything is simplified since the tokens only capture the global configuration global to reflect it to a simpler variable accessible only from the component instance level.

Instance level

It is the instance of the component either in HTML or JS, example:

<my-component style="--background: red;"></my-component>;

const component = document.createElement("my-component");

component.style = "--background: red";

src/button.js

import { c, html, css } from "atomico";
import { tokensColor, tokensInput } from "../tokens";

function button(props) {

  return html`<host shadowDom>
    <button ...${props} class="input-box">
      <slot name="icon"></slot>
      <slot></slot>
    </button>
  </host>`;
}

button.props = {
  name: String,
  value: String,
  disabled: Boolean,
};

button.styles = [
  tokensColor,
  tokensInput,
  css`
    .input-box {
      display: flex;
      gap: 1rem;
    }
  `,
];

import { c, css } from "atomico";
import { tokensColor, tokensInput } from "../tokens";

function button(props) {
  return (
    <host shadowDom>
      <button {...props} class="input-box input-box--use-border">
        <slot name="icon"></slot>
        <slot></slot>
      </button>
    </host>
  );
}

button.props = {
  name: String,
  value: String,
  disabled: Boolean,
};

button.styles = [
  tokensColor,
  tokensInput,
  css`
    .input-box {
      display: flex;
      gap: 1rem;
    }
  `,
];

export const Button = c(button);

From the previous code I highlight:

1. import of "../tokens" and the destructuring of the module that declares the use of tokensColor and tokensInput.

2. button.styles: Atomico allows to associate multiple styles through the use of an array.

3. Button export.

Classes external to Atomico

component: function that declares the webcomponent for Atomico.

VanillaElement: class that will be extended by Atomico to create Component, Atomico will not break the life cycle of the component, allowing them to interact freely.

Classes internal to Atomico

classes produced by the Atomico function c, these can be extended between components, example:

Consider the following effects when using this inheritance model:

1. The render will be rewritten.

2. The props are inherited, Atomico will reuse the previously declared props.

3. Styles are inherited. Atomico will merge the stylesheets.

Inheritance outside of Atomico

The c function creates an optimized standard custom element, which can be extended to modify its behavior, be:

1. Adding methods.

2. Creating or replacing style sheets.

3. Creando nuevas propiedades.

Suppose we have a MyButton product of the function c, we can extend this component to modify its appearance without the need to completely rewrite it, example:

The benefit of this inheritance is to simplify the modification of the appearance of a component created with Atomico, since it avoids its rewriting.

Distribution and consumption

When creating design systems or component systems, we recommend that you maintain a centralized distribution structure in a single export package with multiple import paths, example:

What are the benefits of this type of distribution?

Aesthetic coherence, the entire design system leverages itself and thanks to this we gain aesthetic coherence.

While a monorepo might seem like an ideal path, it actually increases the complexity of maintenance, whether it be component versioning and dependency maintenance.

We move faster and reduce implementation errors if you don't rely on individual versioning at the component level and leave this only defined at the design system level.

This has its pros and cons:

Pros:

1. It speeds up the creation of components, since it avoids the individual publication process and centralizes all this at the design system level.

Cons

1. you will not be able to update a component individually, since it is leveraged at the design system level.

Recommended file structure for webcomponents

you always prefer to keep each component isolated in a directory with names associative to the same component, example:

The following format is friendly when sharing a webcomponent to NPM using @atomico/exports

From the previous structure we highlight:

1. src/define: import the components from src/elements and declare them as customElements

2. src/elements: groups and export components as CustomElements

Why separate the export of the element from the declaration?

since it improves the customElements definition experience, example:

Thanks to @atomico/exports this is really easy, example:

You can see a use case of this structure in @atomico/components

It is normal that we use the technique of dispatching events from the component to communicate states and more, but when using forms this changes since the events inside the shadowDOM do not interact with the form outside of it, example:

To solve this we will have to nest an input tag in the lightDOM of our component, in order to reflect the logic of this to the form. Atomico facilitates this hybrid interaction between lightDOM and shadowDOM with the hook that allows executing a second render that works from the lightDOM, example:

With this you have gained full control over the existing input tag in the lightDOM, allowing you to apply styles using the ::slotted selector, example:

We have created an input tag that allows you to interact directly with the form, this technique is applicable with all the tags that interact with the form, such as button, input, textarea and others.

Component name as function

Write the functional component using the first lowercase character, since the functional declaration is not instantiable as a constructor in JSX.

This prevents confusion when identifying the constructor of the component instance.

useProp

preferably use useProp in the following cases:

• By modifying the prop from inside the component.

• By isolating the logic of the prop in a customHook.

In most cases downloading the prop from the first argument of the function is simpler and more declarative, example:

Prefers the use of static styles

This does not rule out the use within the style tag, since it is sometimes the solution to the definition of conditional styles or variables to the logic and outside the scope of the custom properties.