Ayuda
Cómo instalar un item, el contrato de labels que comparten todos los componentes, cómo cambiar el acento de marca y qué hay disponible hoy en el registry.
Instalar un item
Dos caminos: con el registry `@kilos` (recomendado en un proyecto nuevo) o copiando los archivos a mano (sin red, útil mientras desarrollas el sistema mismo).
Configura el registry @kilos una vez en tu components.json:
{
"registries": {
"@kilos": {
"url": "https://ui.kilos.ai/r/{name}.json",
"headers": { "Authorization": "Bearer ${KILOS_REGISTRY_TOKEN}" }
}
}
}Con KILOS_REGISTRY_TOKEN en tu entorno, instala cualquier item con el CLI de shadcn:
bunx shadcn@latest add @kilos/shell
bunx shadcn@latest add @kilos/data-tableEl CLI resuelve registryDependencies solo (otros items de @kilos y los primitivos de shadcn que necesite) y agrega las dependencies de npm que declare el item a tu package.json.
El contrato de labels
Todo texto visible del sistema sale de un objeto `labels`, con defaults en es-MX (tú, nunca vos). Ningún componente importa una librería de i18n.
Sin pasar nada, el componente usa su default es-MX tal cual:
import { SearchInput } from "@/registry/kilos/page/search-input";
<SearchInput value={q} onChange={setQ} />
// placeholder: "Buscar…" (default es-MX)Sobreescribe solo la clave que necesites — el resto conserva su default:
<SearchInput
value={q}
onChange={setQ}
labels={{ placeholder: "Buscar prospecto…" }}
/>Si tu proyecto tiene su propio sistema de diccionarios (o usa next-intl), conecta TODO un namespace de una sola vez con useKilosLabels — el contrato completo, con next-intl incluido, está en registry/kilos/i18n/README.md:
import { useKilosLabels } from "@/registry/kilos/i18n/use-kilos-labels";
const dict = useMiDiccionario(); // el sistema de i18n de tu proyecto
const pageLabels = useKilosLabels("page", dict.kilos?.page);
<SearchInput value={q} onChange={setQ} labels={pageLabels.searchInput} />Cambiar el acento de marca
Un solo acento (`--brand`), sobreescribible en runtime con `BrandProvider` — sin recompilar ni tocar `kilos.css`.
import { BrandProvider } from "@/registry/kilos/style/brand-provider";
export default function RootLayout({ children }) {
// Cualquier color CSS válido — hex, oklch, lo que ya tengas guardado
// para el usuario o el workspace actual.
const acento = await getAcentoDelWorkspace();
return (
<html lang="es-MX">
<body>
<BrandProvider color={acento} global>
{children}
</BrandProvider>
</body>
</html>
);
}color acepta cualquier color CSS válido (hex, oklch, lo que uses). De --brand se derivan --brand-soft, --brand-line, --brand-deep y --brand-bright automáticamente vía color-mix() en kilos.css — nunca definas esos tokens a mano. Pruébalo en vivo en /tokens.
Items disponibles
Todo lo que hoy está publicado en el registry — la lista sale directo de `registry.json`, se actualiza sola con cada item nuevo.
Tokens OKLCH dark/light, Geist, acento dinámico --brand, motion presets.
Layout de aplicacion completo (sidebar colapsable, header, busqueda ⌘K, notificaciones, usuario, temas) configurado 100% por props con ShellConfig.
Patrones de pagina: encabezado, metricas con sparkline, rejilla de stats, estados vacio y de carga, badges de estado, barra de filtros y filas de ajustes.
Tabla de datos con busqueda, filtros facetados, columnas configurables, seleccion de filas, paginacion y exportacion a PDF/Excel/CSV con carga diferida.
Seis graficas (area, barras, linea, pastel, dona, radial) con API homogenea, colores solo de --chart-1..5 y formato es-MX.
Calendario mes/semana/dia con dialogo de evento, mini calendario de sidebar y selector de rango de fechas, en es-MX.
Campos de formulario accesibles integrados con react-hook-form + zod (mensajes en es-MX), dropzone sin libreria y wizard generico con validacion por paso.
Formularios de acceso, alta, recuperacion, restablecimiento, verificacion y dos pasos. Sin logica de autenticacion: reciben onSubmit por props.
Alta de espacio de trabajo en tres pasos sobre el wizard de @kilos/forms: nombre y slug, tamano de equipo y logo.
Precios con conmutador mensual/anual, tabla comparativa, medidores de consumo, insignia de plan, metodo de pago y tabla de facturas.
Paginas de error, 404 y carga como componentes, mas la configuracion de avisos (sonner) con los tokens del sistema.
Mapa mundial en SVG con d3-geo y topojson, coropletas por valor, marcadores, seleccion por teclado y lista de barras por pais. Sin librerias de mapas.
Contrato de textos del sistema: adaptador para tu propio diccionario y los defaults es-MX de todos los items. Sin dependencias.
Adaptador opcional para proyectos que usan next-intl. Solo instalalo si es tu caso.
Esta lista sale en vivo de registry.json — cuando se publique un item nuevo, aparece aquí solo, sin tocar esta página.
Reglas duras al agregar un item nuevo
Dos convenciones del registry que no son opcionales — romperlas ya causó bugs reales en producción.
Nombre de archivo único en TODO el registry
Los nombres de archivo se comparten en un único espacio de nombres al instalarse, sin importar de qué item vengan. Si dos items traen, por ejemplo, un labels.ts, uno pisa al otro en el proyecto del consumidor y el que perdió desaparece en silencio. Prefija o describe el archivo con el nombre del item (billing-labels.ts, no labels.ts).
Nada de imports relativos dentro de `registry/`
El CLI de shadcn solo sabe reescribir imports con alias (@/registry/kilos/...) al instalar un item en otro proyecto. Un import relativo como ./labels o ../style/tokens se copia tal cual y llega roto al consumidor, porque la ruta relativa ya no apunta a nada en su proyecto.
Más
El contrato completo de i18n (con next-intl, con diccionario propio, y por qué el registry es agnóstico) vive en registry/kilos/i18n/README.md. El template listo para arrancar un proyecto nuevo (Next 16 + next-intl + kilos-ui) está en templates/app-starter/ — su SETUP.md explica dónde enchufar autenticación y base de datos reales.