helix

name

helix

description

HELIX — design intelligence + code generation engine for Claude Code. Open source. Serve pra projeto pessoal, side-project, open source, portfolio, comercial, agência — qualquer contexto onde se queira decodificar uma referência ou gerar uma landing. Decodes the design DNA of any reference (URL, landing page, carrossel, app screen, screenshots) into multiple artifacts: BLUEPRINT.md, Tailwind tokens, design-system.md, voice.md, audit.md, full onboarding package, OR generates a complete Next.js + React + Tailwind landing page via guided workflow. Also validates generated code against the synthesized contracts (`helix validate`) and measures visual fidelity vs reference (`helix mirror`). Routes between commands based on intent. Includes a conversational wizard (`helix wizard`) for guided end-to-end use. Triggers on phrases like "helix", "helix wizard", "helix start", "me guia", "começa do zero", "decode", "decodifica", "blueprint", "tokens", "tailwind config of", "design system from", "system.md de", "voice of", "voice de", "audit", "audita", "diagnóstico de", "package", "pacote do cliente", "onboarding pack", "library", "biblioteca", "landing", "cria a landing", "gera o site", "build landing", "validate", "valida", "helix validate", "valida contra design-system", "check contract", "compliance check", "mirror", "helix mirror", "fidelidade visual", "score perceptual", "quão parecido ficou", "mensura a similaridade", "compara com a referência", "I want something like <url>", "quero algo tipo <url>", "analise essa referência", "reverse engineer this site".

HELIX — Router

HELIX has multiple commands, all powered by the same extraction pipeline. When invoked, identify the user's intent and load the corresponding workflow from ~/.claude/skills/helix/commands/<command>.md.

Intent → Command map

When the user says...	Load workflow
bare helix (no arguments), "helix wizard", "helix start", "helix onboarding", "me guia", "começa do zero", "não sei por onde começar", "tour", "tutorial"	commands/wizard.md
"decode X", "blueprint of X", "decodifica X", "analise essa referência X"	commands/decode.md
"tokens of X", "tailwind de X", "css vars de X", "tokens para X"	commands/tokens.md
"design system from X", "system.md de X", "design-system de X"	commands/system.md
"voice of X", "padrões de copy de X", "voice de X"	commands/voice.md
"audit X", "audita X", "diagnóstico de X", "auditoria do "	commands/audit.md
"package X", "pacote do cliente Y a partir de X", "onboarding pack para X"	commands/package.md
"library list/add/search/similar-to/mix", "biblioteca", "adiciona à library"	commands/library.md
"landing", "cria a landing", "gera o site", "helix landing", "build landing"	commands/landing.md
"mirror", "helix mirror", "fidelidade visual", "score perceptual", "quão parecido ficou", "compara com a referência", "mensura a similaridade"	commands/mirror.md
"validate", "valida", "helix validate", "valida contra design-system", "check contract", "compliance check"	commands/validate.md
"update", "atualiza", "helix update", "atualiza o helix", "tem update?", "helix update --check"	commands/update.md

Default for bare helix: load commands/wizard.md. The wizard captures intent conversationally and delegates to the right specialist command — much more welcoming for first-time users than asking "qual artefato você quer?".

If the user is clearly a power-user invoking a specific command (e.g. helix decode stripe.com), skip the wizard and go straight to the target workflow.

Pre-command hook — daily update check 🔄

Before dispatching to ANY command above, run the update checker. It self-throttles (1× per 24h) so this is cheap.

node ~/.claude/skills/helix/scripts/update-check.mjs

Parse the single-line JSON output. Behavior per status:

Status returned	What to do
gated, current, not-a-repo, check-failed	Silent. Proceed directly to the target command. Don't mention the check happened.
behind	Show 1-line prompt before the target command (see below). After user response, proceed.
behind-dirty	Show 1-line warning (no prompt — won't update with dirty tree). Then proceed to target command.

Skip the hook entirely when the user's command is helix update itself (the workflow handles its own check with --force).

Prompt format for behind

Single line, before running the user's actual command:

⬆ HELIX update disponível ({commits_behind} commits, {current} → {latest}). Aplicar antes? (s/n)

Wait for response. Accept variants: s/sim/y/yes → load commands/update.md with --force, then resume the user's original command. n/não/no/anything else → proceed to original command (timestamp already updated, so won't ask again today).

Warning format for behind-dirty

Single line, no prompt:

ℹ HELIX tem update disponível, mas você tem mudanças locais em {dirty_files[0]} (+ N outros). Faça commit ou stash antes de rodar `helix update`.

Then continue with original command.

Why the hook is non-blocking on failure

check-failed covers offline, GitHub down, SSH key mismatch, DNS hiccup. None of those should prevent the user from running helix decode stripe.com. The check is opportunistic — silent fail keeps the tool usable everywhere.

Shared infrastructure

Extraction

Single extractor: ~/.claude/skills/helix/scripts/extract-web.mjs <url> <output-dir>. Produces meta.json, palette.json, fonts.json, text-content.json, computed.json, and 4 screenshots (mobile, tablet, desktop, full-page).

Cache

Extractions live in ~/.helix/cache/<sha256-of-url>/ with 7-day TTL. Commands MUST check cache before re-extracting.

Cache helper: ~/.claude/skills/helix/scripts/cache.mjs. CLI:

# resolve the cache path for a URL
node ~/.claude/skills/helix/scripts/cache.mjs path "<url>"

# check if there's a fresh extraction available
node ~/.claude/skills/helix/scripts/cache.mjs fresh "<url>"   # prints "fresh" or "stale"

# init cache + library roots (creates ~/.helix/ if missing)
node ~/.claude/skills/helix/scripts/cache.mjs init

# stamp the timestamp file after successful extraction
node ~/.claude/skills/helix/scripts/cache.mjs stamp "<url>"

# force re-extract
node ~/.claude/skills/helix/scripts/cache.mjs clear "<url>"

Library

Persistent blueprints in ~/.helix/library/ (created on demand). Managed by commands/library.md (coming in v1.1).

First-time setup

If ~/.claude/skills/helix/scripts/node_modules is missing, tell the user:

cd ~/.claude/skills/helix/scripts
npm install
npx playwright install chromium

Also run once to create cache dirs:

node ~/.claude/skills/helix/scripts/cache.mjs init

Quality bar — applies to every synthesized output

Every claim must be specific, falsifiable, replicable. Never write a sentence that could apply to 80% of websites.

❌ "Modern sans-serif typography" ✅ "Inter, weights 400/500/700. Headings tracked at -0.022em. Body line-height 1.55. No italics anywhere."

❌ "Strong CTAs" ✅ "Primary CTA: 44px height, 24px horizontal padding, 8px radius, accent fill, white label. Label pattern: <Verb> <noun> — 'Start free', 'Get template'. Never 'Learn more', never with arrow icon."

If you find yourself writing a sentence that could apply to 80% of websites, delete it and look closer.

Always cite real values from extracted JSON (HEX, font names, sizes) — never guess.