ToshqulovLaziz/naqsh

¿Qué hace naqsh?

v0.6. <skill> abajo significa el directorio base de esta habilidad. Los scripts requieren Node ≥ 22 y un Chrome/Edge local; nada que instalar.

1. Ruta

Indica la superficie y el modo en una línea antes de cualquier otra cosa.

Superficie	Señales	Leer
page	landing, portafolio, marketing, producto, one-pager	references/page.md
app	ERP, admin, panel, tabla, formulario, configuración, CRUD	references/app.md

Modo	¿Toca código?	Salida
build	sí, nueva UI	UI + DESIGN.md
redesign	sí; mantener comportamiento, datos y texto	UI + DESIGN.md
audit	no	hallazgos clasificados con archivo:línea y solución

Siempre leer references/rules.md antes de ejecutar verificaciones. Si nadie puede responder preguntas, decide y registra por qué.

2. Contexto

• Stack, estilos, tokens existentes, fuentes y cómo se cargan, cambio de tema (+ su clave localStorage), i18n (+ clave locale), rutas, comando de construcción.
• Qué puede cambiar y qué no debe (otras páginas, componentes compartidos, lógica de negocio).
• Locales: si alguno usa cirílico, cada tipografía elegida debe cubrirlo.

3. Línea base

Ejecuta ambas verificaciones sobre el estado actual y guarda la salida: es el "antes" del informe y a menudo revela errores reales (fuentes que nunca cargan, contraste, desbordamiento).

node <skill>/scripts/lint.mjs <projectRoot>
node <skill>/scripts/inspect.mjs http://localhost:PORT --surface <surface> --routes ... --locales ... --themes ...

Modo audit: sigue references/audit.md desde aquí y detente. No edites archivos del proyecto.

4. Inventario

• Tema: 8–12 cosas que solo este producto o persona tiene (nombres, lugares, números reales, trabajo real).
• Material: para cada espacio visual marca real, picture (honestamente obtenible) o absent. Nunca inventes evidencia: sin logotipos falsos, testimonios, métricas o capturas de pantalla.
• Audiencia y trabajo: quién mira, qué deben hacer o aprender primero.

5. Dirección (tratada, impulsada por gusto)

node <skill>/scripts/deal.mjs --surface <page|app> --options 3 --project <projectRoot>

El script puntúa la biblioteca contra el perfil de gusto del usuario (~/.naqsh/taste.json, se puede sobrescribir por proyecto en <project>/.naqsh/taste.json) y selecciones recientes, y reparte 3 direcciones de diferentes familias.

• Si el usuario está presente, muestra las tres (idea, tipo, paleta, héroe) y déjalo elegir. De lo contrario, elige la mejor opción para el contenido y explica por qué.
• deal.mjs --pick <id> imprime la hoja completa (secciones, movimiento, importación de fuente, tokens claro/oscuro) y registra la elección. Construye desde la hoja: su tipo, paleta y héroe son el contrato. Adapta tamaños y secciones al contenido real; desvía solo con una razón escrita (p. ej., material faltante).
• page: también lee references/page.md. app: también lee references/app.md; el bloque system de la hoja decide shell, densidad, KPI, tabla, estado y estilo de gráfico.

Breve vs gusto. Los adjetivos en un breve ("tranquilo", "minimalista", "profesional") describen el trabajo, no la apariencia. Cúmplelos mediante claridad, densidad y moderación en movimiento, no seleccionando una dirección que el perfil de gusto evite. Nunca descartes una dirección solo porque sea más audaz que el adjetivo del breve; si el breve y el gusto realmente chocan, elige por gusto y anótalo en DESIGN.md.

Retroalimentación de gusto. Cuando el usuario diga qué le gusta o no de un resultado, actualiza ~/.naqsh/taste.json (boldness 1–5, temperature warm|cool|neutral|any, typeStyles, likes, avoid, notes) e infórmaselo. Las preferencias que aplican solo a una superficie van en su bloque page o app, que sobrescribe las claves generales.

6. Suelo (nunca eximido; los scripts verifican la mayor parte)

• Texto visible de i18n en cada locale; sin texto inventado.
• Las fuentes cargan y cubren cada escritura locale; el locale más largo cabe a 375 px.
• @import de fuentes arriba de @import "tailwindcss"; estilos de elementos dentro de @layer base.
• Sin desplazamiento horizontal en la página; overflow-x: clip, nunca hidden/100vw.
• Contraste ≥ 4.5:1 (3:1 grande) en cada tema; foco visible; objetivos ≥ 24 px (44 recomendado).
• prefers-reduced-motion respetado; sin transition: all; animar transform/opacity.
• Nuevos tokens con alcance para que las páginas no modificadas no cambien.

7. Señales de UI generada (reflejo: eximir solo cuando la hoja tratada lo permita)

Índigo/violeta por defecto de Tailwind; brillo, vidrio, blobs aurora, iconos orbitantes, botones brillantes, texto degradado; cejas en mayúsculas espaciadas sobre cada encabezado; cuadrículas de tarjetas idénticas con sombra redondeada; una banda héroe de métricas redondas; el mismo nombre o título repetido en una pantalla. Escala audaz, color fuerte y contraste serif/sans no son señales — la timidez también es un fracaso: si el resultado podría pasar por una plantilla, empuja la idea de la hoja con más fuerza.

8. Bucle de construcción

1. Tokens (con alcance) → pantalla principal / héroe → el resto.
2. Después de cada paso: lint. Después de la pantalla principal: construir, previsualizar, inspect en esa ruta solo (ancho más amplio + más estrecho, primer locale, ambos temas). Al final: la matriz completa. Abre las capturas de pantalla y míralas cada vez. Corrige, repite — como máximo 3 rondas después del primer pase completo. Lee solo los archivos que cambias; mantén los turnos cortos.
3. Pase de detalle: lee references/components.md; cada control está construido según esto (ningún native-control sin eximir), el momento emblemático existe. Ejecuta inspect ... --details y abre cada recorte en <out>/details/; corrige hasta que cada uno se vea intencional a 2x.
4. Cuando el pase de detalle esté completo y la construcción tenga 0 fallos de suelo, escribe DESIGN.md (borrador) y genera el revisor en un contexto nuevo — Herramienta de agente, subagent_type: "naqsh:naqsh-reviewer" — con: raíz del proyecto, superficie, modo, id de dirección, ruta <skill>, carpeta de capturas (con details/), URL de vista previa y las banderas de inspect. Aplica sus correcciones de floor, idea y fidelity (las demás a tu criterio), vuelve a ejecutar las verificaciones. Una ronda de revisión; una segunda solo si el veredicto fue rework. Si no hay herramienta de agente disponible, haz la revisión tú mismo desde agents/naqsh-reviewer.md después de releer las capturas.
5. Termina con 0 fallos de suelo, cada señal reflejo corregida o eximida, y la construcción del proyecto pasando. Detén el servidor de vista previa.

9. Informe

Escribe DESIGN.md en la raíz del proyecto (o donde el usuario diga): opciones tratadas y la elegida, frase de la idea, tokens, tipo, decisiones clave, el momento emblemático, conteos de antes → después de verificaciones, exenciones con razones, verificaciones juzgadas, elementos abiertos. Termina preguntando al usuario qué le gusta y qué no, para que el perfil de gusto mejore.