AI Lytics Styleguide SDK

SDK completo de styleguide para AI Lytics - Sistema de diseño modular basado en Atomic Design con TypeScript y Tailwind CSS.

Desarrollado por Tita Media

Características

• 🎨 Design Tokens: Sistema completo de tokens (colores, tipografía, espaciado, sombras)
• 🌙 Dark Mode: Soporte completo para modo oscuro con ThemeProvider
• 🧩 Componentes Atómicos: Button, Input, Textarea, Icon, UIcons, Avatar, Badge, Typography
• 🔗 Componentes Moleculares: SearchInput, ChatInput, FormField, ButtonGroup, Card parts
• 🏗️ Componentes Organismos: Card, Form, Modal, Navigation, DataTable
• 📐 Templates: DashboardLayout
• 🔄 Sistema de Versiones: Permite múltiples versiones de tokens
• 📦 TypeScript: Tipado completo y estricto
• 🎯 Tailwind CSS: Configuración personalizada con tokens
• 📚 Documentación Interactiva: Página de documentación completa con ejemplos
• 👀 Preview Interactivo: Aplicación de preview para probar componentes en tiempo real

📚 Documentación y Preview

• Documentación Completa - Página de documentación con todos los componentes y tokens
• Preview Interactivo - Aplicación de preview para probar componentes en tiempo real
• Guía de Uso - Guía completa de instalación y uso
• Documentación de Componentes - Detalles de cada componente
• Documentación de Tokens - Referencia completa de design tokens

Instalación

npm install ai-lytics-styleguide

Uso Básico

Importar estilos

import 'ai-lytics-styleguide/dist/styles.css';

Usar componentes

import { Button, Input, Card, Typography } from 'ai-lytics-styleguide';

function App() {
  return (
    <div>
      <Typography variant="h1">Bienvenido a AI Lytics</Typography>
      <Button variant="primary" size="md">
        Click me
      </Button>
      <Input placeholder="Escribe aquí..." />
    </div>
  );
}

Usar tokens

import { tokens, colors, typography, spacing } from 'ai-lytics-styleguide';

console.log(colors.semantic.brand.primary); // #14b8a6
console.log(typography.scale.h1.fontSize); // 2.25rem
console.log(spacing.scale.lg); // 1.5rem

Dark Mode

import { ThemeProvider, useTheme } from 'ai-lytics-styleguide';

function App() {
  return (
    <ThemeProvider defaultTheme="system" storageKey="my-app-theme">
      <MyComponent />
    </ThemeProvider>
  );
}

function MyComponent() {
  const { theme, resolvedTheme, setTheme, toggleTheme } = useTheme();
  
  return (
    <div>
      <p>Current theme: {resolvedTheme}</p>
      <button onClick={toggleTheme}>Toggle Theme</button>
      <button onClick={() => setTheme('light')}>Light</button>
      <button onClick={() => setTheme('dark')}>Dark</button>
      <button onClick={() => setTheme('system')}>System</button>
    </div>
  );
}

ThemeProvider Props:

• defaultTheme: 'light' | 'dark' | 'system' - Tema por defecto (default: 'system')
• storageKey: string - Clave para persistir preferencia (default: 'ai-lytics-theme')

useTheme Hook:

• theme: Tema actual ('light', 'dark', o 'system')
• resolvedTheme: Tema resuelto ('light' o 'dark')
• setTheme: Función para establecer tema
• toggleTheme: Función para alternar entre light/dark

Sistema de Versiones

import { versionManager, getCurrentTokens } from 'ai-lytics-styleguide';

// Obtener tokens de una versión específica
const v1Tokens = versionManager.getTokens('v1');

// Cambiar versión actual
versionManager.setCurrentVersion('v2');

// Obtener tokens de la versión actual
const currentTokens = getCurrentTokens();

Componentes

Atoms

Button

import { Button } from 'ai-lytics-styleguide';

<Button variant="primary" size="md" onClick={handleClick}>
  Enviar
</Button>

Props:

• variant: 'primary' | 'secondary' | 'outline' | 'ghost'
• size: 'sm' | 'md' | 'lg'
• disabled: boolean
• loading: boolean
• icon: React.ReactNode
• iconPosition: 'left' | 'right'

Input

import { Input } from 'ai-lytics-styleguide';

<Input
  type="text"
  placeholder="Escribe aquí..."
  state="default"
  onChange={handleChange}
/>

Props:

• type: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url'
• state: 'default' | 'error' | 'success'
• disabled: boolean
• required: boolean

Textarea

import { Textarea } from 'ai-lytics-styleguide';

<Textarea
  placeholder="Escribe aquí..."
  state="default"
  rows={4}
  autoResize
  onChange={handleChange}
/>

Props:

• state: 'default' | 'error' | 'success'
• rows: number (default: 4)
• autoResize: boolean - Auto-ajusta altura según contenido
• maxLength: number
• minLength: number
• disabled: boolean
• required: boolean

Icon

import { Icon } from 'ai-lytics-styleguide';

<Icon size="md" color="#14b8a6">
  <path d="M12 2L2 7l10 5 10-5-10-5z" />
</Icon>

Props:

• size: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
• color: string - Color CSS o clase Tailwind
• fill: 'currentColor' | 'none'
• strokeWidth: number

UIcons

Librería de iconos predefinidos basados en Flaticon UIcons.

import { 
  SearchIcon, 
  CloseIcon, 
  SendIcon, 
  CheckIcon,
  ChevronRightIcon,
  PlusIcon,
  EditIcon,
  TrashIcon,
  UserIcon,
  SettingsIcon,
  BellIcon,
  HomeIcon,
  InfoIcon,
  WarningIcon,
  ErrorIcon,
  SuccessIcon,
  ArrowRightIcon,
  DownloadIcon,
  UploadIcon,
  MenuIcon,
  FilterIcon,
  CalendarIcon,
  ClockIcon,
  StarIcon,
  HeartIcon,
  EyeIcon,
  EyeOffIcon
} from 'ai-lytics-styleguide';

<SendIcon size="md" />
<CloseIcon size="lg" color="#14b8a6" />

Iconos disponibles: 30+ iconos predefinidos para uso común.

Avatar

import { Avatar } from 'ai-lytics-styleguide';

<Avatar
  src="/avatar.jpg"
  size="md"
  variant="default"
/>

<Avatar
  variant="tita"
  size="lg"
  titaExpression="happy"
/>

Badge

import { Badge } from 'ai-lytics-styleguide';

<Badge variant="primary" size="md">
  Nuevo
</Badge>

Typography

import { H1, H2, Body, Typography } from 'ai-lytics-styleguide';

<H1>Título Principal</H1>
<H2>Subtítulo</H2>
<Body>Texto de cuerpo</Body>

<Typography variant="display">Display Text</Typography>

Molecules

SearchInput

import { SearchInput } from 'ai-lytics-styleguide';

<SearchInput
  placeholder="Buscar..."
  iconPosition="left"
  onChange={handleSearch}
/>

FormField

import { FormField } from 'ai-lytics-styleguide';

<FormField
  label="Email"
  name="email"
  type="email"
  required
  error="Email inválido"
  helpText="Ingresa tu email"
/>

ChatInput

import { ChatInput } from 'ai-lytics-styleguide';

<ChatInput
  onSend={(message) => console.log(message)}
  placeholder="Escribe un mensaje..."
  showCharCount
  maxLength={500}
  sendLoading={isSending}
/>

Props:

• onSend: (value: string) => void - Handler cuando se envía el mensaje
• sendDisabled: boolean - Deshabilita botón de envío
• sendLoading: boolean - Muestra estado de carga
• sendLabel: string - Texto del botón de envío
• sendIcon: React.ReactNode - Icono personalizado
• maxRows: number - Máximo de filas antes de scroll (default: 6)
• minRows: number - Mínimo de filas (default: 1)
• showCharCount: boolean - Muestra contador de caracteres
• maxLength: number - Límite de caracteres

Características:

• Auto-resize del textarea
• Envío con Enter (Shift+Enter para nueva línea)
• Contador de caracteres opcional
• Botón de envío integrado

ButtonGroup

import { ButtonGroup } from 'ai-lytics-styleguide';

<ButtonGroup
  buttons={[
    { children: 'Cancel', variant: 'ghost' },
    { children: 'Save', variant: 'primary' },
  ]}
  orientation="horizontal"
/>

Organisms

Card

import { Card } from 'ai-lytics-styleguide';

<Card variant="default" shadow>
  <Card.Image src="/image.jpg" alt="Card image" />
  <Card.Header>
    <Typography variant="h3">Título de la tarjeta</Typography>
  </Card.Header>
  <Card.Body>
    <Body>Contenido de la tarjeta</Body>
  </Card.Body>
  <Card.Footer>
    <Button variant="primary">Acción</Button>
  </Card.Footer>
</Card>

Form

import { Form } from 'ai-lytics-styleguide';

<Form
  fields={[
    {
      id: 'email',
      name: 'email',
      label: 'Email',
      type: 'email',
      required: true,
    },
    {
      id: 'password',
      name: 'password',
      label: 'Contraseña',
      type: 'password',
      required: true,
    },
  ]}
  submitButton={{ children: 'Enviar', variant: 'primary' }}
  onSubmit={(data) => console.log(data)}
/>

Navigation

import { Navigation } from 'ai-lytics-styleguide';

<Navigation
  items={[
    { label: 'Inicio', href: '/', active: true },
    { label: 'Dashboard', href: '/dashboard' },
    { label: 'Configuración', href: '/settings' },
  ]}
  orientation="horizontal"
/>

Modal

import { Modal } from 'ai-lytics-styleguide';

<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="Mi Modal"
  size="md"
  closeOnOverlayClick
  closeOnEscape
>
  <p>Contenido del modal</p>
</Modal>

Props:

• isOpen: boolean - Controla visibilidad del modal
• onClose: () => void - Handler para cerrar
• title: string - Título del modal (opcional)
• size: 'sm' | 'md' | 'lg' | 'xl' | 'full' (default: 'md')
• showCloseButton: boolean - Muestra botón de cierre (default: true)
• closeOnOverlayClick: boolean - Cierra al hacer click en overlay (default: true)
• closeOnEscape: boolean - Cierra con tecla ESC (default: true)

Características:

• Overlay con backdrop blur
• Scroll interno para contenido largo
• Accesibilidad (ARIA)
• Focus trap automático

DataTable

import { DataTable } from 'ai-lytics-styleguide';

<DataTable
  columns={[
    { key: 'name', label: 'Nombre' },
    { key: 'email', label: 'Email' },
    { key: 'role', label: 'Rol' },
  ]}
  data={[
    { name: 'Juan', email: '[email protected]', role: 'Admin' },
    { name: 'María', email: '[email protected]', role: 'User' },
  ]}
  striped
  hover
/>

Templates

DashboardLayout

import { DashboardLayout } from 'ai-lytics-styleguide';

<DashboardLayout
  sidebarItems={[
    { label: 'Dashboard', href: '/', active: true },
    { label: 'Analytics', href: '/analytics' },
  ]}
  topNavItems={[
    { label: 'Perfil', href: '/profile' },
    { label: 'Configuración', href: '/settings' },
  ]}
>
  <div>Contenido principal</div>
</DashboardLayout>

Configuración de Tailwind

El SDK incluye una configuración de Tailwind personalizada. Para usarla en tu proyecto:

// tailwind.config.js
const styleguideConfig = require('ai-lytics-styleguide/src/config/tailwind.config.ts');

module.exports = {
  ...styleguideConfig,
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/ai-lytics-styleguide/dist/**/*.js',
  ],
};

Design Tokens

Colores

import { colors } from 'ai-lytics-styleguide';

// Primitivos
colors.primitives.teal[500]; // #14b8a6
colors.primitives.blue[700]; // #1e40af

// Semánticos
colors.semantic.brand.primary; // #14b8a6
colors.semantic.text.primary; // #0f172a
colors.semantic.feedback.error; // #dc2626

// Gradientes
colors.gradients.hero; // linear-gradient(...)

Tipografía

import { typography } from 'ai-lytics-styleguide';

typography.fontFamily.primary; // 'Inter'
typography.fontSize.xl; // '1.25rem'
typography.fontWeight.bold; // 700
typography.scale.h1.fontSize; // '2.25rem'

Espaciado

import { spacing } from 'ai-lytics-styleguide';

spacing.scale.xs; // '0.25rem' (4px)
spacing.scale.lg; // '1.5rem' (24px)
spacing.scale['4xl']; // '6rem' (96px)

Desarrollo

# Instalar dependencias
npm install

# Compilar
npm run build

# Modo desarrollo (watch)
npm run dev

# Verificar tipos
npm run type-check

Estructura del Proyecto

ia-styleguide/
├── src/
│   ├── tokens/          # Design tokens
│   ├── config/          # Configuraciones (Tailwind, versiones)
│   ├── atoms/           # Componentes atómicos
│   ├── molecules/       # Componentes moleculares
│   ├── organisms/       # Componentes organismos
│   ├── templates/       # Layouts estructurales
│   ├── utils/           # Utilidades
│   └── index.ts         # Export principal
├── dist/                # Build output
└── package.json

Licencia

MIT

Autor

Tita Media

Desarrollado con ❤️ por Tita Media