arrow-left

All pages
gitbookPowered by GitBook
1 of 8

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

@atomico/storybook

Mejora la experiencia de desarrollo y documentación en Storybook de los webcomponents creados con Atomico

@atomico/storybook posee como objetivo:

  1. Entregar un decorador para renderizar el JSX/HTML y serializar el codigo de las historias.

  2. Entregar un generador de argTypes/args segun el componente dado.

hashtag
Decorador para renderizar el JSX/HTML

decorator permite renderizar el JSX/HTML usando el render de Atomico, este también permite serializar el JSX y HTML declarado en su historia, ejemplo:

hashtag
Ejemplo de renderización y serialización del JSX

circle-exclamation

La serialización del JSX ocurre solo si se defineparameters.docs.source = 'jsx' por historia o global en .storybook/preview.js.

Esta funcionalidad solo es compatible con versiones >= atomico@1.70.0 gracias a la

hashtag
Ejemplo de renderización y serialización del HTML

hashtag
Generador de argTypes/args según el componente dado

hashtag
Ejemplo

característica de nombres automáticos según definición del componentearrow-up-right
import { decorador } from "@atomico/storybook";
import { define } from "@atomico/storybook";
import { Button } from "./button";

export default {
    title: "Component/Button"
    ...define(Button) 
}

Storybook

Atomico hoy ofrece un set de utilidades para mejorar la creacion de sistemas de diseño usando Storybook.

  1. @atomico/storybook

  2. @atomico/vite

  3. @atomico/postcss-tokens

Monorepositorio versionado a nivel de sistema de diseño

Trata de un repositorio que posee un componentes versionados a nivel de sistema de diseño.

Trata de un repositorio que posee un componentes versionados a nivel de sistema de diseño esto quiere decir que cualquier cambio a nivel de componente se publicara como una nueva versión del sistema de diseño.

hashtag
Ventajas

  1. Mayor agilidad al crear nuevos componentes, ya que no deberemos crear un nuevo package para un nuevo componente.

  2. Facil centralización de todo el sistema de diseño, bastara con un fichero components para definir que se exporta a nivel de sistema de diseño.

hashtag
Desventajas

  1. No podremos individualizar las dependencias por componente, ya que estas estarán atadas al package de todo el sistema de diseño.

hashtag
Ejemplo de estructura:

hashtag
Ejemplo de importación por componente

hashtag
Ejemplo de importación por sistema de componentes

packages
├─ components
│  ├─ src 
│  │  ├─ my-button
│  │  ├─ my-input
│  │  ├─ my-card
│  │  └─ components.{ts,js,tsx,jsx}
│  └─ package.json
└─ storybook
   └─ package.json
import { Button } from "@ds/components/button";
import { Button } from "@ds/components";

Estrategias de estructuración de repositorio con Atomico al crear sistemas de diseño.

Le invito a conocer 2 estrategias de estructuración de tu repositorio para tu proyecto como sistemas de diseño.

Puede ser confuso abordar a el desarrollo de un sistema de diseño sin saber como estructurar nuestro proyecto, la estructura de nuestro repositorio definirá en gran medida el formato de publicación de su sistema de diseño sea:

  1. Monorepositorio versionado a nivel de componente

  2. Monorepositorio versionado a nivel de sistema de diseño

hashtag
¿Por qué monorepositorio para su sistemas de diseño?

Es la forma más eficiente de asilar las herramientas que gira entorno a nuestro sistema de diseño.

hashtag
Recomendaciones para su monorepositorio

hashtag
1. Aislé su Storybook como package.

Esto mantendrá limpio el workspaces, ejemplo:

hashtag
2. Adjunte las historias para Storybook en a nivel de componente.

Storybook puede consumir las historias fuera de su repositorio

packages
├─ components
└─ storybook 
packages
├─ components
│  └─ my-button
│     └─ src
│        └─ define.stories.tsx
└─ storybook 

Slots

El uso de slots mejora la composición permitiéndote reflejar el contenido expuesto en el lightDOM del componente en el shadowDOM de este, ejemplo:

hashtag
::slotted(<selector>)

El selector slotted permite la manipulación del contenido expuesto como slot del lightDOM desde el shadowDOM, ejemplo:

hashtag
Auto slot

Con Atomico puedes definir un slot por defecto para tus componentes, esto es útil si buscas mantener cierta consistencia de composición sin la necesidad de declarar el uso de slot, ejemplo:

Para definir un slot por defecto solo debes declarar en las props la prop slot, ejemplo:

Considere esto practico solo si la composición esta apalancada al contenedor, esto no evita que ud modifique la propiedad slot desde la instancia del componente

hashtag
Slot condicional.

Atomico ofrece un hook dentro del package ** **que anexa el evento a una referencia, este le permitirá ocultar slots si estos no declaran contenido, ejemplo:

@atomico/hooks/use-slotarrow-up-right
slotchangearrow-up-right
<my-component>
    <my-component-header></my-component-header>
    <my-component-footer></my-component-footer>
</my-component>
myComponentHeader.props = {
    slot: { type:String, value: "header"}
}

myComponentFooter.props = {
    slot: { type:String, value: "footer"}
}
import { useRef } from "atomico";
import { useSlot } from "@atomico/hooks/use-slot";

function component(){
    const ref = useRef();
    const childNodes = useSlot(ref);
    return <host shadowDom>
        <header style={{
            display: childNodes.length? "block": "none"
        }}>
            <slot name="header" ref={ref}/>
        </header>
    </host>
}

Sistemas de diseño con Atomico

Es grato saber que hoy te enfrentas al desafío de implementar un sistema de diseño con Atomico, espero que esta guía te ayude a abordar:

triangle-exclamation

La siguiente guía está en desarrollo

  1. Estrategias de estructuración de repositorio con Atomico al crear sistemas de diseño.

  2. Abstracción de componentes.

  3. Composición. (Slots)

  4. Distribución.

  5. Documentación.

hashtag

Storybook
Tokens (CSS custom properties)

Tokens (CSS custom properties)

Los tokens son valores configurables de nuestro sistema de diseño representados usando css custom properties, en esta guía encontraras recomendaciones de uso para que tu proyecto sea más escale y configurable sin complicaciones

hashtag
CSS custom properties

hashtag
Contexto a nivel de :root

El seudo selector :root nos permite definir tokens que podrán ser accedidos a nivel de todo el documento incluso shadowDOM, para aprovechar esta ventaja lo ideal es mantener el siguiente patrón.

un documento theme sea CSS o JS que defina todos los tokens como custom property a nivel de :root, ejemplo:

Te invito a notar que para este caso hemos asociado el como prefijo de nombre la cadena--my-design-system, la idea de esto es minimizar conflicto y definir un namespace que identifique las css custom properties que nos pertenecen a nivel de sistema de diseño.

hashtag
Contexto a nivel de :host

El seudo selector :host nos permite encapsular estilos que apuntan a la instancia de nuestro webcomponent, gracias a :host podemos facilitar el acceso a las css custom properties provenientes de :root, esto es práctico ya que facilita el mantenimiento y es automatizable, ejemplo:

:root{
    --my-design-system--color-primary: red;
}
:host{
    --color-primary: var(--my-design-system--color-primary);
}

Monorepositorio versionado a nivel de componente

Trata de un repositorio que posee un sistema de diseño versionados por componentes

Es la estrategia más habitual al momento de crear sistemas de diseño, ya que permite individualizar los cambios a nivel de componente:

hashtag
Ventajas

Gracias a que cada componente posee su package.json se lograra:

  • Versionamiento: Cada package estará versionado, ejemplo @ds/button@1.0.0, esto permite que podamos agregar mejoras o corregir problemas apuntando solo a la versión del componente afectado.

  • Mantenimiento: Al ser un package, podemos individualizar sus dependencias y pruebas, lo que facilita el mantenimiento.

  • Abstracción: Trata de que cada componente aislara en su package los slots de composición(Subcomponentes que únicamente dependen del componente principal, ejemplo el tag option depende del tag select) y alguna otra utilidad especifica del componente.

hashtag
Desventajas

Las siguientes desventajas son prácticas:

  1. Mayor lentitud al crear nuevos componentes, ya que cada componente requerirá ser un nuevo package.

  2. Mayor dificultad de centralización de componentes en un solo package, ya que cada cambio requerirá actualizar el package principal y adjuntar la nueva exportación.

circle-info

Las desventajas prácticas pueden ser reparadas mediante herramientas de CLI que automatizan la generación de archivos y centralización de packages

hashtag
Ejemplo de estructura

hashtag
Ejemplo de importación por componente

hashtag
Ejemplo de importación por sistema de componentes

packages
├─ components
│  ├─ my-button
│  │  └─ package.json
│  ├─ my-input
│  │  └─ package.json
│  └─ my-card
│     └─ package.json
└─ storybook
   └─ package.json
import { Button } from "@ds/my-button";
import { Button } from "@ds/components";