design-arsenal

Design Arsenal — الأداة الموحدة لتصميم الواجهات

Una herramienta. Un punto de entrada. Once módulos. Esto es una sola habilidad — todo funciona a través de este archivo. Siete herramientas de nivel mundial aguas arriba y cuatro módulos originales ya no son habilidades separadas; son módulos internos, cada uno documentado en un MANUAL.md que se lee desde el disco cuando la tarea lo requiere.

EXTRACT  →  TASTE  →  BUILD  →  MOTION  →  POLISH  →  VERIFY
 extract     taste     code      gsap /     impeccable   playwright-cli
 + design-tokens       react-bits  transitions
rtl-arabic (capa de contexto — cualquier contenido árabe)
a11y (filtra cada etapa)        web-vitals (presupuestos en cada etapa)

نظام أداة واحدة: تُنصَّب هذه المهارة مرة واحدة كأداة واحدة باسم design-arsenal، وكل ما تفعله يمر عبر هذا الملف. الأدوات السبع السابقة أصبحت وحدات داخلية (مع 4 وحدات أصلية: rtl-arabic وa11y وdesign-tokens وweb-vitals) — لا تُنصَّب منفردة ولا تظهر كأدوات مستقلة، بل تُقرأ أدلة استخدامها (MANUAL.md) من القرص عند الحاجة فقط.

---

🧭 Despacho de módulos — lea esta tabla primero

Identifique UN módulo de la tarea, lea su MANUAL.md desde el disco (rutas relativas al directorio de este archivo), luego sígalo. Nunca cargue más de dos módulos para una sola tarea.

#	Señal de tarea (lo que pide el usuario)	Módulo	Leer desde el disco
1	Copiar el diseño de un sitio web: "extraer diseño de stripe.com", "qué tokens/colores/fuentes usa este sitio", "convertir esta URL en un tema Tailwind"	extract (designlang)	skills/extract-design/MANUAL.md
2	Dirección artística y anti-sludge antes de construir: "crear una página de aterrizaje", "diseño que no parezca plantilla", "elegir una paleta/dirección tipográfica"	taste (taste-skill v2)	skills/taste/MANUAL.md
3	Refinar, revisar o endurecer una UI existente: "pulir", "auditar", "criticar", "más audaz", "más sutil", "tipografiar", "colorear", "endurecer", "destilar"	polish (impeccable, 24 comandos)	skills/impeccable/MANUAL.md
4	Animación programática avanzada: "GSAP", "animación scroll", "línea de tiempo", "ScrollTrigger", "stagger", "pinning"	motion/gsap (8 módulos)	skills/gsap/gsap-<module>/MANUAL.md
5	Componentes React animados listos para usar: "hero animado", "efecto de texto", "fondo animado", "hover con brillo", "pantalla dividida"	components (react-bits, 218)	skills/react-bits/CATALOG.md
6	Micro-interacciones y movimiento UI en CSS: "transición de modal", "toast", "badge de notificación", "skeleton loader", "check de éxito", "estado de pensamiento de IA"	motion/transitions (43+ fragmentos)	skills/transitions/transitions-dev/MANUAL.md
7	Verificar o automatizar: "probar en navegador", "captura de pantalla", "verificar que el flujo funciona", "grabar un video", "hacer clic a través del flujo"	verify (playwright-cli)	skills/playwright-cli/MANUAL.md
8	Interfaz Árabe/RTL: "interfaz árabe", "RTL", "عربي", "derecha a izquierda", "bidi", cualquier contenido que contenga árabe	rtl-arabic (original)	skills/rtl-arabic/MANUAL.md
9	Accesibilidad: "a11y", "accesible", "WCAG", "contraste", "aria", "lector de pantalla", "teclado"	a11y (original)	skills/a11y/MANUAL.md
10	Tokens de diseño: "tokens de diseño", "DTCG", "tokens de tema", "variables CSS de tema", "convertir paleta a Tailwind", "arquitectura de tokens"	tokens (original)	skills/design-tokens/MANUAL.md
11	Rendimiento: "página lenta", "lighthouse", "core web vitals", "LCP", "INP", "CLS", "presupuesto de rendimiento", "render-blocking", "أداء", "بطيء", "سرعة"	web-vitals (original)	skills/web-vitals/MANUAL.md

Superposiciones → desempates:

• Construir algo nuevo → taste primero (dirección), luego react-bits o gsap mientras se implementa.
• Rediseñar algo existente → polish auditoría/crítica primero, luego taste si se necesita una nueva dirección.
• Micro-interacción pura (un elemento, estado abierto/cerrado) → transitions (CSS, barato). Coreografía de escena completa, scroll o física → gsap.
• Tokens legibles por máquina (archivos JSON/DTCG) → tokens. Resumen de diseño en prosa desde un sitio en vivo → extract. Captura de pantalla → tokens → tokens directamente.
• Cualquier contenido árabe → leer rtl-arabic antes de estilizar, independientemente de qué módulo lidere.
• Movimiento + pregunta de accesibilidad → las reglas de a11y sobre movimiento reducido siempre ganan sobre la riqueza del movimiento.
• Movimiento + pregunta de rendimiento → el presupuesto del hilo principal de web-vitals gana; las animaciones se envían solo en transform/opacity.
• "La página es lenta" → web-vitals lint estático primero (causas estructurales), luego medir (§8 de su manual) — nunca adivinar una métrica.
• Después de CUALQUIER cambio de UI → ofrecer verificar con verify (captura de pantalla del resultado).

---

🌳 Árbol de decisión — enrute en cuatro preguntas

Pregunte, en orden, y deténgase en la primera coincidencia:

1. ¿El contenido contiene árabe (u otro script RTL)? → añadir rtl-arabic como capa de contexto, luego continuar abajo.
2. ¿La entrada es un diseño existente para consumir? URL → extract; captura de pantalla/maqueta → tokens; archivo de paleta → tokens.
3. ¿La tarea crea algo nuevo o cambia algo que existe? Nuevo → taste → construir (tomar de react-bits/gsap/transitions según sea necesario). Existente → polish auditoría primero (/impeccable audit), luego taste solo si se necesita una nueva dirección.
4. ¿Con qué termina la tarea? Envío de UI → ejecutar puertas a11y + lint web-vitals + capturas de pantalla verify. Producción de un archivo de tema/token → exportaciones tokens + auditoría a11y de los pares.

Lea como máximo dos archivos MANUAL.md por tarea; los cuatro módulos originales pueden apilarse con un módulo ascendente (por ejemplo, rtl-arabic + taste).

---

🚫 Registro de anti-patrones — nunca enviar estos

Prohibiciones entre módulos recopiladas de los manuales. Si su salida contiene uno, la tarea no está completa:

• Un <div onClick> que sustituye a un botón (a11y §3) — muerto para teclado, invisible para lector de pantalla.
• Texto gris sobre color, o cualquier par fg/bg por debajo de 4.5:1 (a11y §2, prohibición de impeccable) — ejecutar el script de contraste en lugar de adivinar.
• outline: none sin un anillo de enfoque de reemplazo (a11y §5).
• Animación sin un guardia prefers-reduced-motion (a11y §7, regla de transitions) — la regla más estricta gana.
• letter-spacing en texto árabe (rtl-arabic §3) — rompe la escritura conectada.
• Propiedades CSS físicas left/right en una página RTL (rtl-arabic §1) — usar propiedades lógicas.
• Hex/px codificados en componentes cuando existe un archivo de tokens (tokens §7) — solo los archivos de tokens contienen valores brutos.
• GSAP para un hover de un solo elemento (usar transitions) o transiciones CSS para una escena coreografiada con scroll (usar gsap).
• Un nombre de componente react-bits que no esté en catalog.json — nunca inventar uno.
• Tarjetas anidadas dentro de tarjetas, easing de rebote en UI, y otras señales de slop de impeccable — /impeccable audit las detecta.
• loading="lazy" en la imagen hero/LCP (web-vitals §2) — el navegador descubre la solicitud solo después del layout.
• Un <img> o <iframe> sin width/height explícito (web-vitals §3) — cambio de layout garantizado.
• Un clásico <script src> en <head> sin defer/async, o cualquier document.write (web-vitals §7).
• Un @font-face sin font-display, o una hoja de estilo de Google Fonts sin preconnect a fonts.gstatic.com (web-vitals §6).

---

📦 Contenido interno

design-arsenal/                  ← UNA habilidad, instalada una vez
├── SKILL.md                     ← el punto de entrada único (este archivo)
├── index.json                   ← índice de módulos legible por máquina
├── install.sh                   ← instalador de un comando (todas las plataformas)
├── ATTRIBUTION.md               ← fuentes y licencias
├── README.md                    ← الدليل الكامل بالعربية
├── demo/index.html              ← demo funcional del stack motion
├── examples/gsap/               ← ejemplos iniciales GSAP (react/vue/nuxt/vanilla)
└── skills/                      ← módulos internos (solo manuales de referencia)
    ├── extract-design/          ← designlang: URL → sistema de diseño completo (17+ archivos)
    ├── taste/                   ← taste-skill v2: 13 reglas anti-sludge + librería + inspector
    ├── impeccable/              ← impeccable: 24 comandos + 60+ reglas detectoras + scripts
    ├── gsap/                    ← 8 módulos GSAP: core/timeline/scrolltrigger/react/plugins/…
    ├── react-bits/              ← 218 componentes React animados (TS-CSS + TS-Tailwind) + catálogo
    ├── transitions/             ← transitions.dev: 18 referencias de transición + tokens
    ├── playwright-cli/          ← módulo de automatización de navegador + 10 referencias
    ├── rtl-arabic/              ← original: interfaces Árabe/RTL (propiedades lógicas, tipografía, auditoría de 10 puntos)
    ├── a11y/                    ← original: puertas WCAG 2.2 AA + script de contraste sin dependencias
    ├── design-tokens/           ← original: arquitectura DTCG + convertidor multi-destino
    └── web-vitals/              ← original: manual de Core Web Vitals + linter estático HTML

Cada directorio de módulo contiene un MANUAL.md (anteriormente su propio SKILL.md). Debido a que solo existe este SKILL.md raíz, su agente registra y carga exactamente una herramienta — sin proliferación de habilidades, sin disparadores duplicados, sin hinchazón de contexto de siete habilidades instaladas.

---

🚀 Inicios rápidos

De cero a página de aterrizaje (la tubería completa):

1. (Reconocimiento opcional) extract en 1–2 URLs de competidores → tokens + patrones.
2. taste → leer el resumen, inferir dirección (tipo/paleta/familia de layout), aplicar prohibiciones.
3. Construir. Tomar movimiento de transitions, componentes listos de react-bits, trabajo de escena de gsap.
4. polish → /impeccable polish + /impeccable audit antes de enviar.
5. verify → captura de pantalla de escritorio + widths móviles, confirmar que nada se rompió.

¿Solo arreglar una UI fea? → polish solo (empezar: /impeccable audit <target>). ¿Solo animar? → transitions para micro, gsap para escenas, nunca ambos en el mismo elemento. ¿Página lenta / Vitals fallando? → web-vitals: lint del marcado, aplicar el manual LCP/CLS/INP, luego medir (§8).

---

⚙️ Notas de entorno únicas

• extract necesita Node 20+ y Playwright (npx designlang <url> maneja la instalación en el primer inicio).
• polish scripts son binarios autocontenidos en skills/impeccable/scripts/; en Windows sin sh usar impeccable.cmd.
• taste scripts son Node sin dependencias (node skills/taste/scripts/lint.mjs src/).
• web-vitals linter es Node 18+ sin dependencias (node skills/web-vitals/scripts/webvitals.mjs page.html).
• verify necesita npm install -g @playwright/cli + playwright-cli install-browser chromium.
• components fuentes locales son archivos planos — copiar de ts-tailwind/ (proyectos Tailwind) o ts-default/ (proyectos CSS), o usar el registro en vivo: {"registries":{"@react-bits":"https://reactbits.dev/r/{name}.json"}} en components.json.
• Los ejemplos de GSAP viven en examples/gsap/{vanilla,react,vue,nuxt}.

🧠 Reglas para el agente

1. Una herramienta, un punto de entrada. Todas las solicitudes pasan por este archivo. Si una tarea coincide con la tubería, trabajar módulo por módulo en el orden de la tubería — no buscar los módulos como habilidades separadas instaladas; son internos a esta.
2. Leer desde el disco. Las rutas de los módulos son relativas al directorio de este archivo. Leer completamente el MANUAL.md del módulo antes de actuar.
3. Coincidir, no mezclar. Una tarea → un módulo principal. Apilar módulos solo en el orden de la tubería anterior.
4. Respetar las prohibiciones de cada módulo. taste prohíbe apariencias de plantilla; impeccable prohíbe gris sobre color, tarjetas anidadas, easing de rebote; transitions y a11y requieren guardias prefers-reduced-motion; rtl-arabic prohíbe espaciado de letras en árabe y left/right físicos en páginas RTL; web-vitals prohíbe heroes lazy, medios sin dimensiones y scripts en head que bloquean renderizado. Cuando las reglas entren en conflicto, la regla más estricta gana — y las reglas de seguridad de a11y superan cualquier preferencia estética.
5. Nunca inventar nombres de componentes. Para react-bits, usar solo nombres presentes en skills/react-bits/catalog.json; de lo contrario construir desde cero bajo las reglas de taste.
6. Medir, no estimar visualmente. Las afirmaciones de contraste provienen de node skills/a11y/scripts/contrast.mjs; las exportaciones de tokens provienen de node skills/design-tokens/scripts/convert.mjs; las afirmaciones de rendimiento estructural provienen de node skills/web-vitals/scripts/webvitals.mjs. Si los scripts discrepan con lo que ves, los scripts ganan.
7. El contenido árabe se enruta a través de rtl-arabic. En el momento en que una tarea contiene contenido árabe o RTL, leer skills/rtl-arabic/MANUAL.md antes de escribir cualquier CSS — incluso si otro módulo lidera.
8. Atribución. Los siete módulos ascendentes provienen de proyectos open-source independientes — mantener sus licencias intactas (ver ATTRIBUTION.md). Los cuatro módulos originales (rtl-arabic, a11y, design-tokens, web-vitals) son parte de este paquete.