| name | metodologia-brand-html |
| description | Create and replicate brand-ready MetodologIA HTML for webpages, web apps, and playbooks, respecting UX/UI guidelines and brand rules. Use when generating, scaffolding, replicating, extending, or reviewing MetodologIA-branded HTML/CSS documents or pages. Enforces the brand: no prices (Cotizacion tras Discovery), no 'gratis'/'sin compromiso', brand pun 'EstrategIA' with IA in gold, Poppins headings + Montserrat body, light-default web palette (neoswiss-v5) and dark-first rich palette for playbooks, trilingual ES/EN/PT, SVG icons (no emoji, no Tailwind), and WCAG AA. Includes a scaffolder (scaffold.py), a contract-driven brand+UX validator (brand_check.py) with stable rule IDs, a knowledge graph (contracts.json), a regression harness, and auditor agents. Triggers: build/replicate a MetodologIA page, landing, web app, dashboard, playbook, runbook, proposal, or branded document; check/audit brand compliance. |
| metadata | {"version":"2.0.0","owner":"javier.montano.guz@gmail.com","reviewed":"2026-05-31","review-cadence":"quarterly, or whenever neoswiss-v5 tokens change"} |
MetodologIA Brand HTML
Generate brand-ready MetodologIA HTML that respects UX/UI guidelines, fast and consistently —
across three use cases: webpage, web app, playbook. Two palettes (owner decision):
web (neoswiss-v5, light-default, site-canonical) for webpage/webapp, playbook (richer,
dark-first) for documents. The brand contract is a single source of truth (references/contracts.json),
enforced by an IDed validator, drift-guarded, and regression-tested.
Workflow
- Pick the use case (table) → determines template + palette.
- Scaffold:
python3 scripts/scaffold.py <webpage|webapp|playbook> "<name>" --title "…" --desc "…" --out DIR
→ writes a self-contained, brand-ready .html with the right palette inlined.
- Fill content from
references/components.md. Obey references/brand-rules.md + references/ux-floor.md.
- Validate:
python3 scripts/brand_check.py --strict <file-or-dir> → fix every finding (each prints
its rule id; exit 1 until clean). Add --json for machine output.
- Audit + verify: run the brand-auditor agent (tone/contrast/i18n judgment), then serve + Playwright
@ 390px and desktop (0 console errors) + Lighthouse mobile (≥97 PERF / 100 A11Y / CLS <0.1); playbook → print preview.
| Use case | Palette | Template | Adds |
|---|
| webpage | web (light) | assets/templates/webpage.html | header + hero + sections + footer |
| webapp | web (light) | assets/templates/webapp.html | sidebar nav + theme/lang toggle + modal + scroll-reveal |
| playbook | playbook (dark) | assets/templates/playbook.html | sticky TOC + numbered sections + glossary modal + print |
For a real metodologia.info page, prefer the repo design-system/templates/page.template.html
(links the live neoswiss trio + shell-v5 + i18n JSON). The bundled webpage.html is for off-repo
standalone brand-ready pages. Details: references/use-cases.md.
Example
$ python3 scripts/scaffold.py webpage "Aceleradora" --title "Aceleradora" --desc "Método + IA + Coach." --out /tmp/x
OK webpage (web palette) -> /tmp/x/aceleradora.html
$ python3 scripts/brand_check.py --strict /tmp/x/aceleradora.html
/tmp/x/aceleradora.html [PASS] use-case=webpage 0 fail · 0 warn
Summary: 1 file(s) · effective_fail=0 (strict)
# a violation is traceable to its rule id:
/tmp/x/bad.html:6: FAIL BR-001: price figure. remove price; use 'Cotización tras Discovery'. (brand-rules.md#1)
Brand quick-checklist (always)
- No prices → "Cotización tras Discovery". No "gratis"/"sin compromiso" → "sin costo"/"Recursos Abiertos".
- Pun intact: "Aceleremos su EstrategIA" (IA gold); EN "StrategIA". Never "yIA".
- Poppins headings / Montserrat body. SVG icons (no emoji). No Tailwind utility classes.
- Gold:
--brand-gold for fills/borders; --brand-gold-text for gold text on light. Navy on gold, never white.
- Light-default for web / dark-first for playbook. Trilingual ES/EN/PT (web). Disclaimers on results.
- WCAG AA: 4.5:1 text, visible focus,
aria-label on icon buttons, sequential headings, reduced-motion.
Scripts (stdlib only; no network/hooks)
scaffold.py — emit a ready file. --palette web|playbook overrides the default mapping.brand_check.py — contract-driven validator; every finding carries a rule id (BR-/UX-/A11Y-) from
contracts.json. Flags --json, --strict (WARN→FAIL), --use-case web|playbook|auto.graph_check.py — integrity: rule ids == detectors, refs resolve. Run after editing contracts/checks.tokens_lint.py — drift guard: CSS palettes == design-tokens.json.contract_test.py — regression: tests/fixtures/good clean, tests/fixtures/bad trip exactly their ids.
Limitations (what brand_check does NOT do)
It is a heuristic text scan, not a browser. It does not verify: numeric contrast ratios (only literal
white-on-gold), real translation quality (only data-es/data-en parity), keyboard/focus order, line
length, touch-target size, JS runtime errors, or visual layout. A PASS is necessary, not sufficient —
always finish with the brand-auditor agent + Lighthouse mobile + Playwright (references/ux-floor.md
pre-delivery gate).
Agents (markdown prompts; invoke via the Agent tool — not auto-running)
| Agent | File | When |
|---|
| Brand Auditor | agents/brand-auditor.md | audit a deliverable (validator + tone/contrast/i18n judgment) |
| Contract Keeper | agents/contract-keeper.md | change a rule/token/component coherently across JSON, code, prose, tests |
Knowledge graph
references/contracts.json links tokens ↔ components ↔ templates ↔ use-cases ↔ IDed rules; it is the
single source of truth. references/knowledge-graph.md explains it and how to query/extend. The reliability
guarantee: graph_check (parity) + tokens_lint (no drift) + contract_test (validator proven) must all
be green, and they are enforced by the contract-keeper agent on every change.
References
brand-rules.md (non-negotiables + a11y floor, rule-IDed) · tokens.md (both palettes) ·
components.md (snippets) · ux-floor.md (UX/a11y checklist + gate) · use-cases.md (per-use-case DoD) ·
knowledge-graph.md · contracts.json (rule registry) · design-tokens.json (DTCG + drift contract).
Assets
tokens-web.css, tokens-playbook.css (palettes, inlined by scaffold) · templates/{webpage,webapp,playbook}.html.
Canonical upstream for the web palette = the metodologia.info repo design-system/ (estilos/neoswiss-v5.css).
Keep aligned; tokens_lint.py guards drift.
