@valcis/brand

Componentes React de marca valcis: Logo SVG, Footer, Spinner, Watermark y tema con soporte SSR.

Instalación

npm install @valcis/brand

Logo

Componente SVG puro, sin hooks ni estado. Compatible con React Server Components.

import { Logo } from '@valcis/brand';

// Icono: <V>
<Logo variant="icon" size="md" />

// Completo: >valcis|
<Logo variant="full" size={40} />

// Mini: solo la V caligráfica
<Logo variant="mini" size="lg" />

// El logo full viene animado por defecto (cursor blink)
// Para desactivarlo:
<Logo variant="full" size={32} animated={false} />

Props

| Prop | Tipo | Default | Descripción | |------|------|---------|-------------| | variant | 'icon' \| 'full' \| 'mini' | 'icon' | Variante del logo | | size | number \| 'sm' \| 'md' \| 'lg' \| 'xl' | 24 | Tamaño en px o preset | | animated | boolean | true (full) / false (icon) | Animación CSS-only (respeta prefers-reduced-motion) | | accentColor | string | — | Color de brackets/chevron/cursor | | textColor | string | — | Color de letras | | className | string | — | Clase CSS adicional | | style | CSSProperties | — | Estilos inline | | ariaLabel | string | — | Label de accesibilidad (si se omite, es decorativo) |

Presets de tamaño

| Preset | Pixels | |--------|--------| | sm | 16 | | md | 24 | | lg | 32 | | xl | 48 |

Spinner

Indicador de carga con el logo animado.

import { Spinner } from '@valcis/brand';

// Básico
<Spinner />

// Con opciones
<Spinner size="lg" animation="spin" label="Cargando datos..." />

Props

| Prop | Tipo | Default | Descripción | |------|------|---------|-------------| | size | number \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Tamaño | | animation | 'pulse' \| 'spin' \| 'bounce' | 'pulse' | Tipo de animación | | accentColor | string | — | Color de acento | | textColor | string | — | Color de texto | | label | string | 'Cargando...' | Texto para screen readers | | className | string | — | Clase CSS adicional |

Watermark

Marca de agua posicionable para imágenes o secciones.

import { Watermark } from '@valcis/brand';

// El contenedor padre debe tener position: relative
<div style={{ position: 'relative' }}>
  <img src="foto.jpg" alt="Foto" />
  <Watermark position="bottom-right" opacity={0.3} />
</div>

Props

| Prop | Tipo | Default | Descripción | |------|------|---------|-------------| | position | 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' \| 'center' | 'bottom-right' | Posición | | opacity | number | 0.3 | Opacidad (0-1) | | size | number | 48 | Tamaño del logo | | rotation | number | 0 | Rotación en grados | | showOnHover | boolean | false | Solo visible en hover | | className | string | — | Clase CSS adicional |

Footer

Footer de atribución con logo, contacto y modos de copyright.

import { Footer } from '@valcis/brand';

// Uso básico
<Footer />

// Con datos SSR
<Footer initialDevInfo={devInfo} theme="dark" />

// Modo owner
<Footer mode="owner" />

Props

| Prop | Tipo | Default | Descripción | |------|------|---------|-------------| | theme | 'light' \| 'dark' | 'light' | Tema visual | | mode | 'owner' \| 'designer' \| 'partner' | 'designer' | Modo de copyright | | showYear | boolean | true | Mostrar año | | showContact | boolean | true | Mostrar email de contacto | | animatedLogo | boolean | true | Animar el logo (cursor blink) | | variant | 'inline' \| 'stacked' | 'inline' | Layout horizontal o vertical | | align | 'left' \| 'center' \| 'right' | 'center' | Alineación | | position | 'static' \| 'sticky' \| 'fixed' | 'sticky' | Posicionamiento CSS | | padding | 'compact' \| 'normal' \| 'spacious' \| { x?, y? } | 'normal' | Densidad | | border | boolean \| 'top' \| 'bottom' \| 'both' \| 'none' | 'top' | Borde separador | | accentColor | string | — | Color de acento (texto, links) | | backgroundColor | string | 'transparent' | Fondo | | textColor | string | — | Color de texto override | | as | 'footer' \| 'div' \| 'section' | 'div' | Tag HTML | | className | string | — | Clase CSS adicional | | initialDevInfo | DevInfo | — | Datos pre-cargados (SSR) | | devInfoUrl | string | — | URL alternativa del JSON |

Modos de copyright

| Modo | Resultado | |------|-----------| | owner | © 2026 >valcis| | | designer | © 2026 · Diseñado por >valcis| | | partner | Powered by >valcis| |

useTheme

Hook para detectar y controlar dark/light mode.

import { useTheme } from '@valcis/brand';

function App() {
  const { theme, isDark, toggleTheme, setTheme } = useTheme();

  return (
    <div className={isDark ? 'dark' : 'light'}>
      <button onClick={toggleTheme}>
        {isDark ? '☀️' : '🌙'}
      </button>

      {/* Volver a preferencia del sistema */}
      <button onClick={() => setTheme(null)}>Auto</button>
    </div>
  );
}

Retorno

| Propiedad | Tipo | Descripción | |-----------|------|-------------| | theme | 'light' \| 'dark' | Tema actual | | isDark | boolean | true si es dark mode | | isLight | boolean | true si es light mode | | setTheme | (theme: 'light' \| 'dark' \| null) => void | Forzar tema (null = auto) | | toggleTheme | () => void | Alternar entre light/dark |

Paleta de colores

Colores de marca exportados como constantes.

import { colors, primary, text, cssVariables } from '@valcis/brand';

// Usar en estilos
const style = { color: primary.DEFAULT }; // '#3B82F6'

// Paleta completa
console.log(colors.primary[500]); // '#3B82F6'
console.log(colors.text.DEFAULT); // '#1E293B'
console.log(colors.semantic.success); // '#22C55E'

// Inyectar CSS custom properties
const GlobalStyles = () => <style>{cssVariables}</style>;

Colores disponibles

colors.primary    // Azules de marca (50-900, DEFAULT, light, dark)
colors.text       // Colores de texto (DEFAULT, dark, muted, mutedDark)
colors.background // Fondos (light, dark, muted, mutedDark)
colors.border     // Bordes (light, dark)
colors.semantic   // Semánticos (success, warning, error, info)

CSS Custom Properties

/* Disponibles tras inyectar cssVariables */
--valcis-primary
--valcis-primary-light
--valcis-primary-dark
--valcis-text
--valcis-text-muted
--valcis-bg
--valcis-bg-muted
--valcis-border
--valcis-logo-accent
--valcis-logo-text

Tailwind CSS Preset

Preset con la paleta de marca para proyectos que usan Tailwind CSS.

// tailwind.config.ts
import { valcisPreset } from '@valcis/brand';

export default {
  presets: [valcisPreset],
  content: ['./src/**/*.{ts,tsx}'],
};

Clases disponibles:

<!-- Colores primarios -->
<div class="bg-valcis text-valcis-dark border-valcis-light">

<!-- Texto -->
<p class="text-valcis-text dark:text-valcis-text-dark">

<!-- Fondos -->
<div class="bg-valcis-bg-light dark:bg-valcis-bg-dark">

<!-- Semánticos -->
<span class="text-valcis-success">OK</span>
<span class="text-valcis-error">Error</span>

Datos del desarrollador

El Footer y el hook useDevInfo obtienen los datos de marca desde https://valcis.net/api/dev-info.json. Si el servidor no está disponible o el fetch falla (timeout de 2s, error de red, JSON inválido), se usa automáticamente un fallback local:

{
  version: 1,
  brand: 'valcis',
  contact: '[email protected]',
  website: 'https://valcis.net',
  year: new Date().getFullYear(),
}

En cliente, las respuestas se cachean en localStorage durante 1 hora para minimizar peticiones.

SSR

Para evitar el fetch en cliente, puedes pre-cargar los datos en el servidor con getDevInfo():

import { getDevInfo, Footer } from '@valcis/brand';

// Next.js
export async function getStaticProps() {
  const devInfo = await getDevInfo();
  return { props: { devInfo }, revalidate: 3600 };
}

export default function Page({ devInfo }) {
  return <Footer initialDevInfo={devInfo} />;
}

Si se pasa initialDevInfo, el componente no hace fetch.

Assets estáticos

El paquete incluye SVGs en assets/ para uso fuera de React:

@valcis/brand/assets/favicon.svg
@valcis/brand/assets/logo-icon.svg
@valcis/brand/assets/logo-icon-light.svg
@valcis/brand/assets/logo-icon-dark.svg
@valcis/brand/assets/logo-full.svg
@valcis/brand/assets/logo-full-light.svg
@valcis/brand/assets/logo-full-dark.svg

Las variantes sin sufijo son adaptativas (usan prefers-color-scheme).

SVG paths

Para uso sin React, se exportan los paths SVG crudos:

import { V_CALLIGRAPHIC_PATH, BRACKET_LEFT_PATH, VIEWBOXES } from '@valcis/brand';

Accesibilidad

El componente cumple con WCAG 2.2:

• Contraste: Colores con ratio AA (4.5:1)
• Focus visible: :focus-visible con outline
• Target size: Links con área mínima 44x44px
• Semántica: Uso de <nav>, <footer>, aria-label
• Logo decorativo: aria-hidden="true" (excepto si se proporciona ariaLabel)
• Reduced motion: Animaciones respetan prefers-reduced-motion

Desarrollo

npm run build        # Build de producción
npm run dev          # Build en modo watch
npm run lint         # Ejecutar ESLint
npm run lint:fix     # Arreglar errores de lint
npm run format       # Formatear con Prettier
npm test             # Ejecutar tests (81 tests)
npm run test:watch   # Tests en modo watch

Licencia

El código es MIT. La marca no.

La licencia MIT cubre únicamente el código fuente de este paquete. Los logotipos de Valcis (y sus trazados SVG), el nombre «Valcis», el wordmark valcis| y el contenido de assets/ quedan expresamente excluidos de la licencia y son propiedad exclusiva de Valcis, con todos los derechos reservados.

Usar esos elementos para identificar un producto, servicio u organización distintos de Valcis, o de forma que sugiera respaldo o vinculación con Valcis, requiere autorización previa y por escrito. Ver la sección TRADEMARK / MARCA del fichero LICENSE.

Este paquete es infraestructura interna publicada, no un producto: está en npm por comodidad de consumo dentro del ecosistema Valcis. Sin soporte a terceros, sin contribuciones externas y sin roadmap público.