orbital-ds 0.6.0 → 0.7.0

package/AGENTS.md

@@ -58,3 +58,23 @@ Si `pnpm check:ds` falla, **corrige la causa**; no lo desactives ni lo rodees.
 
 Copia `themes/qratia.css` (o `zyro.css`), cambia valores, no quites ninguno, añade
 `<tema>.fonts.css` con el `@import url()` de sus fuentes y ejecuta `pnpm check:ds`.
+
+## Estándar de integración (cómo debe ajustarse una app)
+
+Para que una app (o un agente que la edite) use orbital-ds sin romper nada:
+
+1. **La marca vive solo en `brand.css`.** Ninguna regla de color propia fuera de ese fichero; jamás se edita el paquete.
+2. **Solo variables públicas.** Nada de variables privadas de un tema (por ejemplo `--zw-*`): se renombran sin aviso de versión mayor. Usa `--ds-*` y los tokens del contrato.
+3. **Sin `!important` ni selectores propios** para vencer a la librería (lateral, raíl, botones). Si algo no se puede ajustar con un token, es un hueco de la librería: abre un issue.
+4. **El tema se elige con un solo `@import`** (o `pnpm theme`). Los temas con ámbito (`*.scoped.css`) son solo para un banco de pruebas; la marca (`brand.css`) gana siempre, también sobre ellos.
+5. **Patrón de página.** La cabecera lleva solo botón de menú, título y, siempre visibles, idioma y tema (y avisos si la app los tiene). El subtítulo y las acciones de la vista van al inicio del contenido, centrado en un ancho máximo; solo un lienzo (mapa, kanban, editor) ocupa todo el ancho.
+6. **Cada tema se documenta y se elige informado.** Lee `orbital-ds/themes/<tema>.guide.md` y su ficha `<tema>.meta.json` (esencia, gesto firma, paleta, accesibilidad, qué valores son aproximados) antes de usar o ajustar un tema.
+7. **Comprueba antes de dar algo por bueno:** `pnpm exec orbital-ds-doctor --css src/brand.css` y el `verify` de la app.
+
+### Accesibilidad (WCAG 2.2)
+
+- **Mínimo exigible: AA.** Texto 4,5:1; texto grande y controles 3:1. `pnpm check:ds` falla si un par principal de texto sobre su superficie (texto/fondo, tarjeta, popover, primario, secundario, lateral, destructivo) o un texto de estado (info, danger, warning, success, neutral) baja de 4,5:1.
+- **Objetivo: AAA en el texto del cuerpo** (7:1 para texto/fondo y texto/tarjeta). Se mide con `pnpm check:ds -- --aaa` y avisa, no falla: WCAG no aconseja exigir AAA a todo el sitio. Hoy todos los temas lo cumplen.
+- **Excepciones declaradas, nunca silenciosas.** Si un tema no puede cumplir un par (el azul de marca de Twitter con texto blanco da 3:1), lo declara en su ficha, en `a11y.exceptions`, con su porqué; el doctor lo muestra como aviso.
+- **Foco siempre visible** (anillo de 3:1 como mínimo) y sin que otro elemento lo tape.
+- **Una marca nueva debe volver a pasar el doctor.** Cambiar `--primary` obliga a revisar `--primary-foreground`, `--link` y `--ring`.

package/components.manifest.json

@@ -1,6 +1,6 @@
 {
   "package": "orbital-ds",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "engine": "@base-ui/react",
   "docs": [
     "README.md",
@@ -1256,6 +1256,7 @@
       ],
       "slots": [
         "tooltip",
+        "tooltip-arrow",
         "tooltip-content",
         "tooltip-provider",
         "tooltip-trigger"

package/contract.json

@@ -1,162 +1,168 @@
-{
-  "version": 3,
-  "descripcion": "Contrato de tema de orbital-ds: todo tema (themes/*.css) debe definir estos tokens en :root. Nombres en inglés estándar; los de shadcn sin prefijo; los propios con --ds-. baseTheme es el tema aplicado siempre (los demás se aplican encima, con ámbito).",
-  "root": [
-    "radius",
-    "background",
-    "foreground",
-    "card",
-    "card-foreground",
-    "popover",
-    "popover-foreground",
-    "primary",
-    "primary-foreground",
-    "secondary",
-    "secondary-foreground",
-    "muted",
-    "muted-foreground",
-    "accent",
-    "accent-foreground",
-    "destructive",
-    "destructive-foreground",
-    "border",
-    "input",
-    "ring",
-    "chart-1",
-    "chart-2",
-    "chart-3",
-    "chart-4",
-    "chart-5",
-    "sidebar",
-    "sidebar-foreground",
-    "sidebar-primary",
-    "sidebar-primary-foreground",
-    "sidebar-accent",
-    "sidebar-accent-foreground",
-    "sidebar-border",
-    "sidebar-ring",
-    "danger",
-    "danger-soft",
-    "warning",
-    "warning-soft",
-    "success",
-    "success-soft",
-    "info",
-    "info-soft",
-    "neutral",
-    "neutral-soft",
-    "link",
-    "link-hover",
-    "inset",
-    "inset-foreground",
-    "brand",
-    "brand-bright"
-  ],
-  "fonts": [
-    "ds-font-sans"
-  ],
-  "dark": {
-    "descripcion": "Recomendados en .dark (si faltan, el tema hereda el valor claro y doctor avisa).",
-    "avisar_si_falta": [
-      "background",
-      "foreground",
-      "card",
-      "card-foreground",
-      "popover",
-      "popover-foreground",
-      "primary",
-      "primary-foreground",
-      "muted",
-      "muted-foreground",
-      "border",
-      "input",
-      "ring",
-      "danger",
-      "warning",
-      "success",
-      "info",
-      "link"
-    ]
-  },
-  "baseTheme": "qratia",
-  "brand": {
-    "descripcion": "Grupo ESTABLE de variables que una app suele personalizar en su fichero de marca (brand.css). Renombrar o quitar una es versión MAYOR. Todas están también en `root` salvo las --ds-*.",
-    "tokens": [
-      {
-        "name": "primary",
-        "example": "oklch(0.55 0.2 260)",
-        "about": "color de acción principal (botones, foco)"
-      },
-      {
-        "name": "primary-foreground",
-        "example": "#ffffff",
-        "about": "texto sobre el color principal (comprueba el contraste)"
-      },
-      {
-        "name": "ring",
-        "example": "oklch(0.55 0.2 260)",
-        "about": "anillo de foco; suele ir igual que primary"
-      },
-      {
-        "name": "link",
-        "example": "oklch(0.5 0.15 260)",
-        "about": "texto de enlace: más oscuro que primary para tener contraste"
-      },
-      {
-        "name": "link-hover",
-        "example": "oklch(0.42 0.13 260)",
-        "about": "enlace al pasar el ratón"
-      },
-      {
-        "name": "brand",
-        "example": "oklch(0.7 0.13 220)",
-        "about": "acento de marca (detalles, selección)"
-      },
-      {
-        "name": "brand-bright",
-        "example": "oklch(0.8 0.13 220)",
-        "about": "acento de marca sobre fondos oscuros"
-      },
-      {
-        "name": "sidebar-primary",
-        "example": "oklch(0.8 0.13 220)",
-        "about": "acento dentro del sidebar"
-      },
-      {
-        "name": "sidebar-primary-foreground",
-        "example": "#04121c",
-        "about": "texto sobre el acento del sidebar"
-      },
-      {
-        "name": "sidebar-accent-foreground",
-        "example": "oklch(0.85 0.1 220)",
-        "about": "texto del destino activo del sidebar"
-      },
-      {
-        "name": "accent-foreground",
-        "example": "oklch(0.5 0.15 260)",
-        "about": "texto sobre superficies de acento suave"
-      },
-      {
-        "name": "chart-1",
-        "example": "oklch(0.55 0.2 260)",
-        "about": "primera serie de las gráficas: la marca"
-      },
-      {
-        "name": "radius",
-        "example": "12px",
-        "about": "redondez base (en temas cuya rampa deriva de ella)"
-      },
-      {
-        "name": "ds-font-sans",
-        "example": "'Inter', system-ui, sans-serif",
-        "about": "fuente del cuerpo (carga la fuente en tu app)"
-      },
-      {
-        "name": "ds-font-display",
-        "example": "'Sora', system-ui, sans-serif",
-        "about": "fuente de los titulares"
-      }
-    ]
-  }
-}
+{
+  "version": 4,
+  "descripcion": "Contrato de tema de orbital-ds: todo tema (themes/*.css) debe definir estos tokens en :root. Nombres en inglés estándar; los de shadcn sin prefijo; los propios con --ds-. baseTheme es el tema aplicado siempre (los demás se aplican encima, con ámbito).",
+  "root": [
+    "radius",
+    "background",
+    "foreground",
+    "card",
+    "card-foreground",
+    "popover",
+    "popover-foreground",
+    "primary",
+    "primary-foreground",
+    "secondary",
+    "secondary-foreground",
+    "muted",
+    "muted-foreground",
+    "accent",
+    "accent-foreground",
+    "destructive",
+    "destructive-foreground",
+    "border",
+    "input",
+    "ring",
+    "chart-1",
+    "chart-2",
+    "chart-3",
+    "chart-4",
+    "chart-5",
+    "sidebar",
+    "sidebar-foreground",
+    "sidebar-primary",
+    "sidebar-primary-foreground",
+    "sidebar-accent",
+    "sidebar-accent-foreground",
+    "sidebar-border",
+    "sidebar-ring",
+    "danger",
+    "danger-soft",
+    "warning",
+    "warning-soft",
+    "success",
+    "success-soft",
+    "info",
+    "info-soft",
+    "neutral",
+    "neutral-soft",
+    "link",
+    "link-hover",
+    "inset",
+    "inset-foreground",
+    "brand",
+    "brand-bright",
+    "ds-sidebar-icon",
+    "ds-sidebar-icon-stroke",
+    "ds-sidebar-rail-w",
+    "ds-sidebar-rail-item",
+    "ds-sidebar-logo",
+    "ds-sidebar-sep-inset"
+  ],
+  "fonts": [
+    "ds-font-sans"
+  ],
+  "dark": {
+    "descripcion": "Recomendados en .dark (si faltan, el tema hereda el valor claro y doctor avisa).",
+    "avisar_si_falta": [
+      "background",
+      "foreground",
+      "card",
+      "card-foreground",
+      "popover",
+      "popover-foreground",
+      "primary",
+      "primary-foreground",
+      "muted",
+      "muted-foreground",
+      "border",
+      "input",
+      "ring",
+      "danger",
+      "warning",
+      "success",
+      "info",
+      "link"
+    ]
+  },
+  "baseTheme": "qratia",
+  "brand": {
+    "descripcion": "Grupo ESTABLE de variables que una app suele personalizar en su fichero de marca (brand.css). Renombrar o quitar una es versión MAYOR. Todas están también en `root` salvo las --ds-*.",
+    "tokens": [
+      {
+        "name": "primary",
+        "example": "oklch(0.55 0.2 260)",
+        "about": "color de acción principal (botones, foco)"
+      },
+      {
+        "name": "primary-foreground",
+        "example": "#ffffff",
+        "about": "texto sobre el color principal (comprueba el contraste)"
+      },
+      {
+        "name": "ring",
+        "example": "oklch(0.55 0.2 260)",
+        "about": "anillo de foco; suele ir igual que primary"
+      },
+      {
+        "name": "link",
+        "example": "oklch(0.5 0.15 260)",
+        "about": "texto de enlace: más oscuro que primary para tener contraste"
+      },
+      {
+        "name": "link-hover",
+        "example": "oklch(0.42 0.13 260)",
+        "about": "enlace al pasar el ratón"
+      },
+      {
+        "name": "brand",
+        "example": "oklch(0.7 0.13 220)",
+        "about": "acento de marca (detalles, selección)"
+      },
+      {
+        "name": "brand-bright",
+        "example": "oklch(0.8 0.13 220)",
+        "about": "acento de marca sobre fondos oscuros"
+      },
+      {
+        "name": "sidebar-primary",
+        "example": "oklch(0.8 0.13 220)",
+        "about": "acento dentro del sidebar"
+      },
+      {
+        "name": "sidebar-primary-foreground",
+        "example": "#04121c",
+        "about": "texto sobre el acento del sidebar"
+      },
+      {
+        "name": "sidebar-accent-foreground",
+        "example": "oklch(0.85 0.1 220)",
+        "about": "texto del destino activo del sidebar"
+      },
+      {
+        "name": "accent-foreground",
+        "example": "oklch(0.5 0.15 260)",
+        "about": "texto sobre superficies de acento suave"
+      },
+      {
+        "name": "chart-1",
+        "example": "oklch(0.55 0.2 260)",
+        "about": "primera serie de las gráficas: la marca"
+      },
+      {
+        "name": "radius",
+        "example": "12px",
+        "about": "redondez base (en temas cuya rampa deriva de ella)"
+      },
+      {
+        "name": "ds-font-sans",
+        "example": "'Inter', system-ui, sans-serif",
+        "about": "fuente del cuerpo (carga la fuente en tu app)"
+      },
+      {
+        "name": "ds-font-display",
+        "example": "'Sora', system-ui, sans-serif",
+        "about": "fuente de los titulares"
+      }
+    ]
+  }
+}

package/dist/styles.css

@@ -134,6 +134,7 @@
    */
   --ds-z-raised: 10;
   --ds-z-sticky: 20;
+  --ds-z-sidebar: 21; /* por encima de la cabecera sticky: su filete no debe quedar tapado */
   --ds-z-overlay: 50;
 
   --ds-motion-fast: 100ms;
@@ -192,6 +193,12 @@
   --ds-sidebar-shadow: var(--ds-shadow-raised);
   --ds-sidebar-ring: 1px;
   --ds-sidebar-edge: 0 solid transparent;
+  --ds-sidebar-rail-w: 4rem; /* ancho del lateral contraído (raíl de iconos) */
+  --ds-sidebar-rail-item: 2.5rem; /* lado del botón de cada destino en el raíl */
+  --ds-sidebar-icon: 1.125rem; /* tamaño de los iconos del lateral */
+  --ds-sidebar-icon-stroke: 2; /* grosor del trazo de esos iconos */
+  --ds-sidebar-logo: 2rem; /* ficha del logo y del avatar del lateral */
+  --ds-sidebar-sep-inset: 0rem; /* margen lateral de los separadores (negativo = de borde a borde) */
   --ds-sidebar-item-radius: var(--ds-radius-md);
   --ds-sidebar-item-h: 2.5rem;
 
@@ -433,15 +440,27 @@
    * TAMAÑO Y ALINEACIÓN DE LA NAVEGACIÓN (los `!important` baten a las
    * utilidades que el primitivo trae escritas).
    * EXPANDIDO: filas de altura `--ds-sidebar-item-h` con icono de 18px.
-   * COLAPSADO: botón de 40px y padding lateral de 12px → icono centrado en el
-   * raíl de 64px.
+   * COLAPSADO: botón cuadrado de `--ds-sidebar-rail-item` con el icono centrado,
+   * sin etiqueta, y el botón centrado en el raíl (`--ds-sidebar-rail-w`).
    */
   [data-sidebar='menu-button'] {
     min-height: var(--ds-sidebar-item-h);
   }
   [data-sidebar='menu-button'] svg {
-    width: 1.125rem !important;
-    height: 1.125rem !important;
+    width: var(--ds-sidebar-icon) !important;
+    height: var(--ds-sidebar-icon) !important;
+    stroke-width: var(--ds-sidebar-icon-stroke);
+  }
+  /* Logo / avatar del lateral (botones lg: marca y cuenta) */
+  [data-sidebar='menu-button'][data-size='lg'] > :first-child {
+    width: var(--ds-sidebar-logo);
+    height: var(--ds-sidebar-logo);
+    flex: 0 0 var(--ds-sidebar-logo);
+  }
+  /* Separadores: alineados con las filas (0) o de borde a borde (negativo) */
+  [data-slot='sidebar-separator'] {
+    margin-inline: var(--ds-sidebar-sep-inset);
+    width: auto;
   }
 
   [data-collapsible='icon'] [data-slot='sidebar-header'],
@@ -449,14 +468,19 @@
   [data-collapsible='icon'] [data-slot='sidebar-group'] {
     padding-inline: 0.75rem;
   }
+  /* Raíl: tecla cuadrada, centrada, con el icono centrado dentro y sin etiqueta */
   [data-collapsible='icon'] [data-sidebar='menu-button'] {
-    width: 2.5rem !important;
-    height: 2.5rem !important;
-    padding: 0.6875rem !important; /* (40−18)/2: icono centrado */
+    width: var(--ds-sidebar-rail-item) !important;
+    height: var(--ds-sidebar-rail-item) !important;
+    min-height: var(--ds-sidebar-rail-item);
+    padding: 0 !important;
+    gap: 0;
+    justify-content: center;
+    margin-inline: auto;
   }
-  /* Botones lg (marca, cuenta): dentro va una ficha de 32px → 4px de aire. */
-  [data-collapsible='icon'] [data-sidebar='menu-button'][data-size='lg'] {
-    padding: 0.25rem !important;
+  [data-collapsible='icon'] [data-sidebar='menu-button'] > span:last-child:not(:first-child),
+  [data-collapsible='icon'] [data-sidebar='menu-button'][data-size='lg'] > :not(:first-child) {
+    display: none;
   }
 
   /*

package/dist/themes/friendly.css

@@ -24,6 +24,14 @@
   --ds-font-sans: 'Rubik', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
   --ds-font-display: var(--ds-font-sans);
   --ds-font-mono: ui-monospace, 'SF Mono', Menlo, monospace;
+
+  /* Lateral: iconos, raíl, logo y separadores (cada tema fija su forma y tamaño) */
+  --ds-sidebar-icon: 1.25rem;
+  --ds-sidebar-icon-stroke: 2;
+  --ds-sidebar-rail-w: 4.5rem;
+  --ds-sidebar-rail-item: 2.75rem;
+  --ds-sidebar-logo: 2.25rem;
+  --ds-sidebar-sep-inset: 0rem;
   --ds-heading-tracking: normal;
 
   /* Color: lienzo azulado, tinta índigo, acento periwinkle + naranja cálido */
@@ -43,7 +51,7 @@
   --muted-foreground: #6b6d96;
   --accent: rgba(55, 132, 247, 0.14);
   --accent-foreground: #2a64c4;
-  --destructive: #e5484d;
+  --destructive: #d04246;
   --destructive-foreground: #ffffff;
 
   --border: rgba(35, 36, 80, 0.08);
@@ -65,15 +73,15 @@
   --sidebar-border: rgba(35, 36, 80, 0.07);
   --sidebar-ring: #5f6ec9;
 
-  --danger: #c7343a;
+  --danger: #bb3137;
   --danger-soft: rgba(229, 72, 77, 0.12);
-  --warning: #9a5b00;
+  --warning: #955800;
   --warning-soft: rgba(251, 178, 50, 0.24);
-  --success: #0a7d55;
+  --success: #097650;
   --success-soft: rgba(29, 184, 122, 0.14);
-  --info: #2a64c4;
+  --info: #2962c0;
   --info-soft: rgba(55, 132, 247, 0.14);
-  --neutral: #6b6d96;
+  --neutral: #616389;
   --neutral-soft: rgba(35, 36, 80, 0.07);
 
   --link: #2a64c4;

package/dist/themes/friendly.scoped.css

@@ -18,12 +18,20 @@
  */
 
 /* ── VARIABLES · PIEL CLARA ──────────────────────────────────────────────── */
-:root[data-theme='friendly'] {
+:root:where([data-theme='friendly']) {
   --radius: 8px;
 
   --ds-font-sans: 'Rubik', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
   --ds-font-display: var(--ds-font-sans);
   --ds-font-mono: ui-monospace, 'SF Mono', Menlo, monospace;
+
+  /* Lateral: iconos, raíl, logo y separadores (cada tema fija su forma y tamaño) */
+  --ds-sidebar-icon: 1.25rem;
+  --ds-sidebar-icon-stroke: 2;
+  --ds-sidebar-rail-w: 4.5rem;
+  --ds-sidebar-rail-item: 2.75rem;
+  --ds-sidebar-logo: 2.25rem;
+  --ds-sidebar-sep-inset: 0rem;
   --ds-heading-tracking: normal;
 
   /* Color: lienzo azulado, tinta índigo, acento periwinkle + naranja cálido */
@@ -43,7 +51,7 @@
   --muted-foreground: #6b6d96;
   --accent: rgba(55, 132, 247, 0.14);
   --accent-foreground: #2a64c4;
-  --destructive: #e5484d;
+  --destructive: #d04246;
   --destructive-foreground: #ffffff;
 
   --border: rgba(35, 36, 80, 0.08);
@@ -65,15 +73,15 @@
   --sidebar-border: rgba(35, 36, 80, 0.07);
   --sidebar-ring: #5f6ec9;
 
-  --danger: #c7343a;
+  --danger: #bb3137;
   --danger-soft: rgba(229, 72, 77, 0.12);
-  --warning: #9a5b00;
+  --warning: #955800;
   --warning-soft: rgba(251, 178, 50, 0.24);
-  --success: #0a7d55;
+  --success: #097650;
   --success-soft: rgba(29, 184, 122, 0.14);
-  --info: #2a64c4;
+  --info: #2962c0;
   --info-soft: rgba(55, 132, 247, 0.14);
-  --neutral: #6b6d96;
+  --neutral: #616389;
   --neutral-soft: rgba(35, 36, 80, 0.07);
 
   --link: #2a64c4;
@@ -137,7 +145,7 @@
 }
 
 /* ── VARIABLES · PIEL OSCURA («noche índigo») ────────────────────────────── */
-:root[data-theme='friendly'].dark {
+:where(:root[data-theme='friendly']).dark {
   --background: #16173b;
   --foreground: #ecedfa;
 
@@ -210,7 +218,7 @@
 /* ── PERSONALIDAD ────────────────────────────────────────────────────────────
  * Sin capa: gana a las utilidades de los componentes. Solo variables.
  */
-:root[data-theme='friendly'] {
+:root:where([data-theme='friendly']) {
   /* Botones: píldora en mayúsculas con espaciado, y brillo de color debajo */
   [data-slot='button'] {
     border-radius: 9999px;

package/dist/themes/qratia.css

@@ -14,6 +14,14 @@
 	/* Tipografía: Instrument Sans (fuentes en qratia.fonts.css) */
 	--ds-font-sans: 'Instrument Sans', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
 	--ds-font-mono: ui-monospace, 'SF Mono', Menlo, monospace;
+
+	/* Lateral: iconos, raíl, logo y separadores (cada tema fija su forma y tamaño) */
+	--ds-sidebar-icon: 1.125rem;
+	--ds-sidebar-icon-stroke: 2;
+	--ds-sidebar-rail-w: 4rem;
+	--ds-sidebar-rail-item: 2.5rem;
+	--ds-sidebar-logo: 2rem;
+	--ds-sidebar-sep-inset: 0rem;
 
 	/*
 	 * Dos sombras de tarjeta: reposo y realce al señalar, EN CAPAS y TINTADAS con

package/dist/themes/qratia.scoped.css

@@ -8,12 +8,20 @@
  * DESIGN.md. Las utilidades de Tailwind se derivan en styles.css (@theme).
  */
 
-:root[data-theme='qratia'] {
+:root:where([data-theme='qratia']) {
 	--radius: 0.625rem;
 
 	/* Tipografía: Instrument Sans (fuentes en qratia.fonts.css) */
 	--ds-font-sans: 'Instrument Sans', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
 	--ds-font-mono: ui-monospace, 'SF Mono', Menlo, monospace;
+
+	/* Lateral: iconos, raíl, logo y separadores (cada tema fija su forma y tamaño) */
+	--ds-sidebar-icon: 1.125rem;
+	--ds-sidebar-icon-stroke: 2;
+	--ds-sidebar-rail-w: 4rem;
+	--ds-sidebar-rail-item: 2.5rem;
+	--ds-sidebar-logo: 2rem;
+	--ds-sidebar-sep-inset: 0rem;
 
 	/*
 	 * Dos sombras de tarjeta: reposo y realce al señalar, EN CAPAS y TINTADAS con
@@ -161,7 +169,7 @@
 	--sidebar-ring: oklch(0.711 0.129 219);
 }
 
-:root[data-theme='qratia'].dark {
+:where(:root[data-theme='qratia']).dark {
 	/*
    * Gris elevado, no negro. Un fondo casi negro con texto claro produce halación
    * y en jornadas de revisión eso cansa. Conserva los tres niveles de superficie.