#Design System (Ark UI + Panda CSS)

Un Design System construido con Ark UI y Panda CSS. Este paquete proporciona componentes de UI accesibles, personalizables y con excelente rendimiento.

Características

• Zero-Runtime CSS: Estilos generados en tiempo de compilación para máximo rendimiento
• Componentes Headless: Lógica y accesibilidad de Ark UI con estilos personalizables
• Tipado Completo: TypeScript en todos los componentes y APIs
• Personalizable: Sistema de tokens y variantes para adaptarse a cualquier marca
• Modular: Importa solo lo que necesites
• Accesible: Componentes que siguen las mejores prácticas de accesibilidad

💻 Uso

// Importar componentes individuales
import { Button, Card, Modal } from "@iobricks/ark-ui-ds";

// Usar en tu aplicación
const MyComponent = () => {
  return (
    <Card variant="outline">
      <h2>Hello World</h2>
      <Button colorScheme="primary">Click me</Button>
    </Card>
  );
};

Estilos

Para que los componentes se muestren correctamente, necesitas importar los estilos CSS:

// En tu archivo principal (por ejemplo, App.tsx o _app.tsx)
import "@iobricks/ark-ui-ds/styled-system/styles.css";

🔄 Flujo de Trabajo

1. Desarrollo de componentes

Sigue este patrón para crear nuevos componentes:

1. Crea la recipe en theme/recipes/:

   // theme/recipes/nuevoComponente.ts
   import { defineRecipe } from "@pandacss/dev";
   
   export const nuevoComponente = defineRecipe({
     className: "ds-nuevoComponente",
     base: {
       /* estilos base */
     },
     variants: {
       /* variantes */
     },
     defaultVariants: {
       /* valores por defecto */
     },
   });

2. Exporta la recipe en theme/recipes/index.ts:

   // Añade la nueva recipe al objeto de recipes
   export const recipes = {
     button,
     nuevoComponente, // <-- Añade aquí tu nueva recipe
   };

3. Crea el componente base en src/ui/styled/:

   // src/ui/styled/nuevoComponente.tsx
   import { ark } from "@ark-ui/react";
   import { styled } from "styled-system/jsx";
   import { nuevoComponente } from "styled-system/recipes";
   
   export const StyledNuevoComponente = styled(ark.div, nuevoComponente);

4. Implementa la lógica en src/ui/:

   // src/ui/nuevoComponente.tsx
   import { StyledNuevoComponente } from "./styled/nuevoComponente";
   
   export const NuevoComponente = (props) => {
     return <StyledNuevoComponente {...props} />;
   };

5. Documenta con stories en src/ui/*.stories.tsx

6. Actualiza el force-css.tsx:

   • Ejecuta yarn panda:force para regenerar el archivo force-css.tsx (Aunque usando yarn ds:watch deberia verse con el hotreload)

2. Comandos principales

• yarn ds:watch - Desarrollo con hot reload completo (recomendado)

  • Genera los helpers de Panda
  • Genera el CSS inicial
  • Observa cambios en recipes y regenera el CSS
  • Lanza Storybook

• yarn ds:dev - Desarrollo sin hot reload

  • Útil para sesiones cortas o cuando no necesitas hot reload

• yarn panda:force - Regenera el archivo force-css.tsx

  • Necesario después de añadir nuevas recipes o variantes

• yarn panda:cssgen - Genera el CSS estático

  • Útil para regenerar el CSS manualmente

• yarn panda:all - Ejecuta todo lo anterior en secuencia

3. Publicación

• yarn build-storybook - Genera la documentación
• yarn panda:cssgen - Asegura que el CSS esté actualizado

📝 Notas Importantes

El archivo force-css.tsx

El archivo src/ui/force-css.tsx es fundamental para el funcionamiento del Design System durante el desarrollo:

• Propósito: Fuerza a Panda CSS a generar todas las variantes posibles de los componentes.
• Funcionamiento: Contiene llamadas a todas las recipes con diferentes combinaciones de variantes.
• Importancia: Sin este archivo, Panda solo generaría CSS para las variantes que se usan explícitamente en el código.
• Actualización: Debe actualizarse cuando se añaden nuevas recipes o variantes (automáticamente con yarn panda:force).
• Distribución: Este archivo es solo para desarrollo y no afecta al paquete final cuando se publica el Design System.

Otras notas

• Modificación de estilos: Edita las recipes en theme/recipes/ para cambiar los estilos base.
• Nuevos componentes: Sigue el patrón de separación entre componentes styled y UI.
• Hot Reload: Usa yarn ds:watch para desarrollo con actualización automática.
• Generación de CSS: Ejecuta yarn panda:cssgen después de cambios en recipes o tokens.