theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/rules/typescript/coding-style.md

@@ -0,0 +1,199 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# Estilo de código TypeScript/JavaScript
+
+> Este archivo extiende [common/coding-style.md](../common/coding-style.md) con contenido específico de TypeScript/JavaScript.
+
+## Tipos e interfaces
+
+Usa tipos para que las APIs públicas, los modelos compartidos y las props de componentes sean explícitos, legibles y reutilizables.
+
+### APIs públicas
+
+- Añade tipos de parámetros y de retorno a las funciones exportadas, a las utilidades compartidas y a los métodos públicos de clases
+- Deja que TypeScript infiera los tipos obvios de variables locales
+- Extrae las formas de objeto inline repetidas a tipos o interfaces con nombre
+
+```typescript
+// INCORRECTO: función exportada sin tipos explícitos
+export function formatUser(user) {
+  return `${user.firstName} ${user.lastName}`
+}
+
+// CORRECTO: tipos explícitos en las APIs públicas
+interface User {
+  firstName: string
+  lastName: string
+}
+
+export function formatUser(user: User): string {
+  return `${user.firstName} ${user.lastName}`
+}
+```
+
+### Interfaces vs. alias de tipo
+
+- Usa `interface` para formas de objeto que puedan extenderse o implementarse
+- Usa `type` para uniones, intersecciones, tuplas, mapped types y utility types
+- Prefiere uniones de literales de string sobre `enum`, salvo que un `enum` sea necesario por interoperabilidad
+
+```typescript
+interface User {
+  id: string
+  email: string
+}
+
+type UserRole = 'admin' | 'member'
+type UserWithRole = User & {
+  role: UserRole
+}
+```
+
+### Evita `any`
+
+- Evita `any` en el código de la aplicación
+- Usa `unknown` para entradas externas o no confiables y luego acótalas de forma segura
+- Usa genéricos cuando el tipo de un valor dependa del llamador
+
+```typescript
+// INCORRECTO: any elimina la seguridad de tipos
+function getErrorMessage(error: any) {
+  return error.message
+}
+
+// CORRECTO: unknown obliga a un acotamiento seguro
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message
+  }
+
+  return 'Error inesperado'
+}
+```
+
+### Props de React
+
+- Define las props de los componentes con una `interface` o un `type` con nombre
+- Tipa explícitamente las props de callback
+- No uses `React.FC` salvo que exista una razón específica para hacerlo
+
+```typescript
+interface User {
+  id: string
+  email: string
+}
+
+interface UserCardProps {
+  user: User
+  onSelect: (id: string) => void
+}
+
+function UserCard({ user, onSelect }: UserCardProps) {
+  return <button onClick={() => onSelect(user.id)}>{user.email}</button>
+}
+```
+
+### Archivos JavaScript
+
+- En archivos `.js` y `.jsx`, usa JSDoc cuando los tipos mejoren la claridad y una migración a TypeScript no sea práctica
+- Mantén el JSDoc alineado con el comportamiento en tiempo de ejecución
+
+```javascript
+/**
+ * @param {{ firstName: string, lastName: string }} user
+ * @returns {string}
+ */
+export function formatUser(user) {
+  return `${user.firstName} ${user.lastName}`
+}
+```
+
+## Inmutabilidad
+
+Usa el operador spread para actualizaciones inmutables:
+
+```typescript
+interface User {
+  id: string
+  name: string
+}
+
+// INCORRECTO: mutación
+function updateUser(user: User, name: string): User {
+  user.name = name // ¡MUTACIÓN!
+  return user
+}
+
+// CORRECTO: inmutabilidad
+function updateUser(user: Readonly<User>, name: string): User {
+  return {
+    ...user,
+    name
+  }
+}
+```
+
+## Manejo de errores
+
+Usa async/await con try-catch y acota los errores `unknown` de forma segura:
+
+```typescript
+interface User {
+  id: string
+  email: string
+}
+
+declare function riskyOperation(userId: string): Promise<User>
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message
+  }
+
+  return 'Error inesperado'
+}
+
+const logger = {
+  error: (message: string, error: unknown) => {
+    // Reemplaza esto con tu logger de producción (por ejemplo, pino o winston).
+  }
+}
+
+async function loadUser(userId: string): Promise<User> {
+  try {
+    const result = await riskyOperation(userId)
+    return result
+  } catch (error: unknown) {
+    logger.error('La operación falló', error)
+    throw new Error(getErrorMessage(error))
+  }
+}
+```
+
+## Validación de entrada
+
+Usa Zod para validación basada en esquemas e infiere los tipos a partir del esquema:
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  email: z.string().email(),
+  age: z.number().int().min(0).max(150)
+})
+
+type UserInput = z.infer<typeof userSchema>
+
+const validated: UserInput = userSchema.parse(input)
+```
+
+## Console.log
+
+- Nada de sentencias `console.log` en código de producción
+- Usa librerías de logging apropiadas en su lugar
+- Consulta los hooks para la detección automática

package/vendor/theus-arsenal/rules/typescript/hooks.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# Hooks para TypeScript/JavaScript
+
+> Este archivo extiende [common/hooks.md](../common/hooks.md) con contenido específico de TypeScript/JavaScript.
+
+## Hooks PostToolUse
+
+Se configuran en `~/.theus/settings.json`:
+
+- **Prettier**: auto-formatea los archivos JS/TS después de editarlos
+- **Chequeo de TypeScript**: ejecuta `tsc` después de editar archivos `.ts`/`.tsx`
+- **Aviso de console.log**: advierte sobre `console.log` en los archivos editados
+
+## Hooks Stop
+
+- **Auditoría de console.log**: revisa todos los archivos modificados en busca de `console.log` antes de que termine la sesión

package/vendor/theus-arsenal/rules/typescript/patterns.md

@@ -0,0 +1,52 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# Patrones de TypeScript/JavaScript
+
+> Este archivo extiende [common/patterns.md](../common/patterns.md) con contenido específico de TypeScript/JavaScript.
+
+## Formato de respuesta de API
+
+```typescript
+interface ApiResponse<T> {
+  success: boolean
+  data?: T
+  error?: string
+  meta?: {
+    total: number
+    page: number
+    limit: number
+  }
+}
+```
+
+## Patrón de custom hooks
+
+```typescript
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value)
+
+  useEffect(() => {
+    const handler = setTimeout(() => setDebouncedValue(value), delay)
+    return () => clearTimeout(handler)
+  }, [value, delay])
+
+  return debouncedValue
+}
+```
+
+## Patrón Repository
+
+```typescript
+interface Repository<T> {
+  findAll(filters?: Filters): Promise<T[]>
+  findById(id: string): Promise<T | null>
+  create(data: CreateDto): Promise<T>
+  update(id: string, data: UpdateDto): Promise<T>
+  delete(id: string): Promise<void>
+}
+```

package/vendor/theus-arsenal/rules/typescript/security.md

@@ -0,0 +1,28 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# Seguridad en TypeScript/JavaScript
+
+> Este archivo extiende [common/security.md](../common/security.md) con contenido específico de TypeScript/JavaScript.
+
+## Gestión de secretos
+
+```typescript
+// NUNCA: secretos hardcodeados
+const apiKey = "sk-proj-xxxxx"
+
+// SIEMPRE: variables de entorno
+const apiKey = process.env.API_KEY
+
+if (!apiKey) {
+  throw new Error('API_KEY no configurada')
+}
+```
+
+## Soporte de agentes
+
+- Usa el agente **revisor-seguridad** para auditorías de seguridad exhaustivas

package/vendor/theus-arsenal/rules/typescript/testing.md

@@ -0,0 +1,18 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# Testing en TypeScript/JavaScript
+
+> Este archivo extiende [common/testing.md](../common/testing.md) con contenido específico de TypeScript/JavaScript.
+
+## Testing E2E
+
+Usa **Playwright** como framework de testing E2E para los flujos de usuario críticos.
+
+## Soporte de agentes
+
+- **ejecutor-e2e** — especialista en testing E2E con Playwright

package/vendor/theus-arsenal/rules/vue/coding-style.md

@@ -0,0 +1,54 @@
+---
+paths:
+  - "**/*.vue"
+---
+
+# Estilo de código Vue
+
+> Este archivo extiende [common/coding-style.md](../common/coding-style.md) con contenido específico de Vue.
+
+## Estructura de SFC
+
+- Siempre `<script setup lang="ts">` con la Composition API. Nada de Options API en código nuevo.
+- Orden de bloques dentro de un archivo `.vue`: `<script setup>`, luego `<template>`, luego `<style scoped>`. Un componente por archivo.
+- Nomenclatura: archivos de componentes en PascalCase (`AuctionCard.vue`), composables en camelCase con prefijo `useXxx` (`useAuctionTimer`).
+- Formatea con Prettier más ESLint con flat config usando `eslint-plugin-vue` (`vue/vue3-recommended`). Verifica tipos con `vue-tsc`.
+
+## Disciplina de reactividad
+
+- `ref` es la API de estado principal. Muta vía `.value` en el script; el auto-desempaquetado solo ocurre en el nivel superior del template.
+- Un `ref` anidado dentro de arrays, `Map` o `Set` sigue necesitando `.value` para leerse.
+- Recurre a `reactive` solo para estado de objeto agrupado. Nunca reasignes un objeto `reactive` completo.
+- Nunca desestructures un objeto `reactive` ni un store de Pinia sin `toRefs` / `storeToRefs`. La desestructuración simple pierde la reactividad de forma silenciosa.
+
+## Computed y watchers
+
+- Los getters de `computed` deben ser puros: sin efectos secundarios, sin async, sin acceso al DOM.
+- Desde 3.4+, `computed` solo dispara cuando el valor devuelto cambia. Devuelve el objeto anterior sin modificar cuando sea igual, para saltarte actualizaciones aguas abajo.
+- `watch` es perezoso (lazy). Pasa un getter para una propiedad reactiva (`watch(() => x.value, ...)`), no el objeto reactivo a secas.
+- `watchEffect` es ansioso (eager) y deja de rastrear dependencias después de su primer `await`.
+
+## Ciclo de vida y DOM
+
+- Registra los hooks de ciclo de vida de forma síncrona dentro de `setup` (`onMounted`, `onUnmounted`).
+- Limpia timers, listeners y suscripciones en `onUnmounted`.
+- Lee o mide el DOM solo después de `await nextTick()`.
+
+## Macros y templates
+
+- Macros: `defineProps` / `defineEmits` (forma de tupla `change: [id: number]`), `defineModel` (3.4+) para `v-model`, `withDefaults` o la desestructuración reactiva de props de 3.5+ para valores por defecto, `defineExpose` para la API pública por ref.
+- Pon un `:key` en cada `v-for`, un primitivo único y estable. Nunca el índice del array, nunca un objeto.
+- Nunca pongas `v-if` y `v-for` en el mismo elemento. Envuelve con `<template v-for>` más un `v-if` interno, o precalcula una lista filtrada.
+
+```vue
+<script setup lang="ts">
+const props = defineProps<{ id: number }>()
+const emit = defineEmits<{ change: [id: number] }>()
+const open = defineModel<boolean>('open', { default: false })
+</script>
+```
+
+## Referencia
+
+- Skills de Theus: `patrones-frontend`, `patrones-vite`.
+- Docs: <https://vuejs.org/api/sfc-script-setup.html> · <https://vuejs.org/guide/essentials/reactivity-fundamentals.html> · <https://eslint.vuejs.org/>

package/vendor/theus-arsenal/rules/vue/hooks.md

@@ -0,0 +1,45 @@
+---
+paths:
+  - "**/*.vue"
+  - "**/*.ts"
+  - "**/*.tsx"
+---
+
+# Hooks para Vue
+
+> Este archivo extiende [common/hooks.md](../common/hooks.md) con contenido específico de Vue.
+
+## Objetivos de PostToolUse
+
+Ejecuta sobre `*.vue`, `*.ts` y `*.tsx` después de las ediciones. Acota a los archivos modificados cuando sea posible.
+
+## Typecheck
+
+- Usa `vue-tsc --noEmit` para verificar SFC más TypeScript. `tsc` a secas no puede leer componentes de archivo único `.vue`, así que no debe ser el hook de typecheck de este proyecto.
+- El typecheck es a nivel de todo el proyecto. Aplica debounce o acótalo para que un bucle de guardado en cada pulsación no congele el editor.
+
+## Lint y formato
+
+- `eslint --fix` con `eslint-plugin-vue` (flat config `vue/vue3-recommended`) cubre el lint tanto del template como del script.
+- `prettier --write` para el formato. Prefiere Prettier-vía-ESLint en lugar de una pasada de Prettier separada, para evitar formateo doble y bucles de conflicto.
+
+## Límites de arquitectura
+
+- Opcional: haz cumplir los límites de slices de Feature-Sliced Design con `@feature-sliced/steiger` o `eslint-plugin-boundaries` para bloquear imports profundos entre slices.
+
+## Secuencia
+
+```bash
+# solo archivos modificados
+eslint --fix "$FILE"
+prettier --write "$FILE"
+# a nivel de proyecto, con debounce
+vue-tsc --noEmit
+```
+
+- Ejecuta primero lint y formato por archivo, y al final el typecheck de todo el proyecto, para que los errores de tipos reflejen el código ya formateado.
+
+## Referencia
+
+- Skills de Theus: `patrones-frontend`, `patrones-vite`.
+- Docs: <https://github.com/vuejs/language-tools> (vue-tsc) · <https://eslint.vuejs.org/> · <https://github.com/feature-sliced/steiger>

package/vendor/theus-arsenal/rules/vue/patterns.md

@@ -0,0 +1,56 @@
+---
+paths:
+  - "**/*.vue"
+---
+
+# Patrones Vue
+
+> Este archivo extiende [common/patterns.md](../common/patterns.md) con contenido específico de Vue.
+
+## Composables
+
+- El composable (`useXxx`) es la unidad de lógica reutilizable. En Feature-Sliced Design vive en el segmento `model` del slice.
+- Acepta entradas `MaybeRefOrGetter<T>` y normalízalas con `toValue`, de modo que quien llama pueda pasar un ref, un getter o un valor plano.
+- Devuelve `toRefs(reactive(...))` para que los consumidores puedan desestructurar sin perder reactividad.
+- Un composable que usa hooks de ciclo de vida o `provide` / `inject` debe llamarse dentro del `setup` de un componente, no de forma perezosa ni condicional.
+
+## Props, emits, v-model
+
+- `defineProps<Props>()` basado en tipos y `defineEmits<{ change: [id: number] }>()` en forma de tupla.
+- `defineModel<T>('name', { default })` para enlace bidireccional. Compila a una prop más un emit `update:*`.
+
+## Provide / Inject
+
+- Usa `provide` / `inject` para datos con alcance de árbol sin prop drilling.
+- Claves con tipos seguros y sin colisiones: `const key = Symbol() as InjectionKey<T>`.
+- El proveedor es dueño de las mutaciones. Expón un ref `readonly` más una función actualizadora explícita, nunca un ref mutable en crudo.
+
+## Pinia (segmento model de FSD)
+
+- Prefiere setup stores: `ref` es el estado, `computed` son los getters, `function` son las acciones.
+- Los setup stores no reciben `$reset` gratis. Define el tuyo propio.
+- Usa `storeToRefs` para estado y getters. Desestructura las acciones directamente desde el store.
+- Nunca persistas tokens de autenticación en crudo en `localStorage`.
+
+## vue-router
+
+- Carga los componentes de ruta de forma diferida (lazy) con `import()` dinámico.
+- Un guard `beforeEach` global de autenticación basado en `meta.requiresAuth`. Los guards devuelven `false` (cancelar), una ubicación de ruta (redirigir) o `undefined` / `true` (continuar).
+- Observa `() => route.params.id`, no el objeto `route` completo.
+
+## vue-query (caché de servidor)
+
+- `@tanstack/vue-query` es dueño del estado de caché de servidor. Pinia es dueño del estado de cliente.
+- Coloca las funciones de request más las fábricas de `queryOptions` en el segmento `api` de FSD.
+- Crítico: pon el ref o computed EN SÍ MISMO en la query key, nunca `.value`. Pasar `.value` congela la clave y mata el refetch reactivo.
+
+```ts
+useQuery({ queryKey: ['auction', id], queryFn: () => fetchAuction(toValue(id)) })
+// después de una mutación
+queryClient.invalidateQueries({ queryKey: ['auction', id] })
+```
+
+## Referencia
+
+- Skills de Theus: `patrones-frontend`, `patrones-vite`.
+- Docs: <https://pinia.vuejs.org/> · <https://router.vuejs.org/> · <https://tanstack.com/query/latest/docs/framework/vue/overview> · <https://vuejs.org/guide/reusability/composables.html>

package/vendor/theus-arsenal/rules/vue/security.md

@@ -0,0 +1,46 @@
+---
+paths:
+  - "**/*.vue"
+---
+
+# Seguridad en Vue
+
+> Este archivo extiende [common/security.md](../common/security.md) con contenido específico de Vue.
+
+## Qué escapa Vue automáticamente
+
+- La interpolación de texto `{{ }}` y los bindings dinámicos de atributos (`:title`) se escapan automáticamente. Los vectores de abajo NO están protegidos.
+
+## Regla n.º 1: templates solo de fuentes confiables
+
+- Nunca uses contenido no confiable como template de un componente. Nada de compilación de templates en tiempo de ejecución a partir de entrada del usuario.
+- Nada de `:is` controlado por el usuario que resuelva un componente desde una cadena arbitraria.
+
+## v-html y funciones de render
+
+- `v-html` omite el escapado y es un vector directo de XSS. Evítalo sobre contenido de usuario.
+- Si es inevitable, sanitiza con DOMPurify (configuración de lista de permitidos) antes del binding, o renderiza en un iframe con sandbox. El propio Vue recomienda sanitizar en el backend antes de persistir.
+- La salida de funciones de render y de scoped slots conlleva el mismo riesgo. Pasar HTML de usuario a través de `h()` con `innerHTML` es `v-html` con otro nombre. Sanitiza primero.
+
+## Inyección por URL, estilos y eventos
+
+- `:href` y `:src` no se escapan. Las URLs `javascript:` se ejecutan. Valida el esquema; permite solo `http` / `https` / `mailto`. La documentación de Vue menciona `@braintree/sanitize-url`, pero sanitiza en el backend antes de persistir.
+- `:style` con entrada del usuario es inseguro (exfiltración vía CSS). Usa sintaxis de objeto con propiedades en lista blanca, nunca una cadena en crudo del usuario.
+- Nunca enlaces entrada del usuario a `onclick`, `onfocus` ni a ningún atributo de evento.
+
+## Secretos en el bundle de cliente
+
+- Todo lo que esté en `import.meta.env.VITE_*` se envía al navegador. Mantén las claves de API y los tokens del lado del servidor.
+- Usa cookies httpOnly para los tokens de sesión. Nunca empaquetes credenciales en el cliente.
+
+```vue
+<!-- inseguro -->
+<div v-html="userBio" />
+<!-- seguro -->
+<div v-html="sanitize(userBio)" />
+```
+
+## Referencia
+
+- Skills de Theus: `patrones-frontend`, `patrones-vite`.
+- Docs: <https://vuejs.org/guide/best-practices/security.html> · <https://github.com/cure53/DOMPurify> · <https://github.com/braintree/sanitize-url>

package/vendor/theus-arsenal/rules/vue/testing.md

@@ -0,0 +1,53 @@
+---
+paths:
+  - "**/*.vue"
+---
+
+# Testing en Vue
+
+> Este archivo extiende [common/testing.md](../common/testing.md) con contenido específico de Vue.
+
+## Stack
+
+- Vitest (runner nativo de Vite) más `@vue/test-utils`. `create-vue` genera el andamiaje con `@vitejs/plugin-vue`.
+- Entorno DOM vía `happy-dom` o `jsdom`, configurado en `vite.config.ts` bajo `test.environment`.
+
+## Renderizado y asincronía
+
+- `mount` para un render completo. `shallowMount` para stubear todos los componentes hijos.
+- `trigger` y `setValue` devuelven promesas: espéralas con `await`.
+- `flushPromises` vacía los handlers de promesas resueltas. `nextTick` asienta el DOM tras un cambio de estado.
+
+## Qué testear
+
+- Testea solo la interfaz pública: props, eventos emitidos, slots, salida renderizada.
+- No hagas aserciones sobre estado privado ni métodos internos, y no dependas únicamente de snapshots.
+
+## Composables
+
+- Los composables que usan solo APIs de reactividad se testean unitariamente de forma directa: llama a la función y haz aserciones sobre los refs devueltos.
+- Los composables que usan hooks de ciclo de vida o `inject` deben testearse a través de un componente anfitrión.
+
+## Pinia
+
+- En componentes: `createTestingPinia()` de `@pinia/testing`, pasada vía `global.plugins`. Las acciones vienen stubeadas por defecto; usa `stubActions: false` para ejecutarlas. `createSpy: vi.fn` es obligatorio bajo Vitest (no hay globales de Jest).
+- En aislamiento: `beforeEach(() => setActivePinia(createPinia()))` da un store fresco por test y evita fugas de estado.
+
+## Configuración de mount
+
+- `global.plugins`, `global.stubs` (stubea `Transition` / `TransitionGroup` por defecto), `global.mocks` (p. ej. `$router`), `global.provide` (para `inject`, admite claves Symbol).
+- `RouterLinkStub` stubea `router-link` sin montar un router completo.
+
+```ts
+const wrapper = mount(AuctionCard, {
+  props: { id: 1 },
+  global: { plugins: [createTestingPinia({ createSpy: vi.fn })] },
+})
+await wrapper.find('button').trigger('click')
+expect(wrapper.emitted('bid')).toBeTruthy()
+```
+
+## Referencia
+
+- Skills de Theus: `patrones-frontend`, `patrones-vite`.
+- Docs: <https://test-utils.vuejs.org/api/> · <https://pinia.vuejs.org/cookbook/testing.html> · <https://vitest.dev/>

package/vendor/theus-arsenal/rules/web/coding-style.md

@@ -0,0 +1,108 @@
+---
+paths:
+  - "**/*.css"
+  - "**/*.scss"
+  - "**/*.sass"
+  - "**/*.less"
+  - "**/*.html"
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/*.vue"
+  - "**/*.svelte"
+---
+> Este archivo extiende [common/coding-style.md](../common/coding-style.md) con contenido de frontend específico de web.
+
+# Estilo de código web
+
+## Organización de archivos
+
+Organiza por funcionalidad o área de la interfaz, no por tipo de archivo:
+
+```text
+src/
+├── components/
+│   ├── hero/
+│   │   ├── Hero.tsx
+│   │   ├── HeroVisual.tsx
+│   │   └── hero.css
+│   ├── scrolly-section/
+│   │   ├── ScrollySection.tsx
+│   │   ├── StickyVisual.tsx
+│   │   └── scrolly.css
+│   └── ui/
+│       ├── Button.tsx
+│       ├── SurfaceCard.tsx
+│       └── AnimatedText.tsx
+├── hooks/
+│   ├── useReducedMotion.ts
+│   └── useScrollProgress.ts
+├── lib/
+│   ├── animation.ts
+│   └── color.ts
+└── styles/
+    ├── tokens.css
+    ├── typography.css
+    └── global.css
+```
+
+## Propiedades personalizadas de CSS
+
+Define los tokens de diseño como variables. No repitas valores fijos de paleta, tipografía o espaciado por todo el código:
+
+```css
+:root {
+  --color-surface: oklch(98% 0 0);
+  --color-text: oklch(18% 0 0);
+  --color-accent: oklch(68% 0.21 250);
+
+  --text-base: clamp(1rem, 0.92rem + 0.4vw, 1.125rem);
+  --text-hero: clamp(3rem, 1rem + 7vw, 8rem);
+
+  --space-section: clamp(4rem, 3rem + 5vw, 10rem);
+
+  --duration-fast: 150ms;
+  --duration-normal: 300ms;
+  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+}
+```
+
+## Propiedades aptas para animación
+
+Prefiere movimiento amigable con el compositor:
+- `transform`
+- `opacity`
+- `clip-path`
+- `filter` (con moderación)
+
+Evita animar propiedades que fuerzan recálculo de layout:
+- `width`
+- `height`
+- `top`
+- `left`
+- `margin`
+- `padding`
+- `border`
+- `font-size`
+
+## HTML semántico primero
+
+```html
+<header>
+  <nav aria-label="Navegación principal">...</nav>
+</header>
+<main>
+  <section aria-labelledby="hero-heading">
+    <h1 id="hero-heading">...</h1>
+  </section>
+</main>
+<footer>...</footer>
+```
+
+No recurras a pilas de `div` genéricos cuando existe un elemento semántico.
+
+## Nomenclatura
+
+- Componentes: PascalCase (`ScrollySection`, `SurfaceCard`)
+- Hooks: prefijo `use` (`useReducedMotion`)
+- Clases CSS: kebab-case o clases utilitarias
+- Timelines de animación: camelCase con intención (`heroRevealTl`)