# Li Generate Web

> Use to render a static HTML mockup, a profile-aware single-file page or a Next.js scaffold from a brief or the existing design/content contracts.

- Skill: `jokerman89/li-generate-web` (Agent Skill)
- Install (CLI): `npx get-skill add jokerman89/li-generate-web`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jokerman89/li-generate-web/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: jokerman89 (https://skillmd.com/u/jokerman89)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/jokerman89/li-generate-web

---


> **Lintel on GitHub Copilot.** Generated from `skills/generate-web/SKILL.md`; edit the canonical file, then run
> `li-copilot init`.
> - **Resource root:** `../../..` from this skill's base directory (the Lintel source with `bin/`,
>   `lib/`, `skills/`). Write plans, state and evidence into the working repository's `.claude/`
>   tree, never into the resource root.
> - **Skill-relative paths:** this skill's own `scripts/`, `references/` and `data/` folders (and a
>   `<base>` that the workflow defines as its own directory) mean
>   `../../../skills/generate-web/` in the Lintel source, not this generated folder.
>   `${LINTEL_SKILLS_DIR:-skills}` means the skills root, `../../../skills`. A `bin/li-run` step
>   runs in the working repository, so use `$LINTEL_SKILLS_DIR/generate-web/` there.
> - **Shell steps:** run Bash snippets with Bash (Git for Windows' `bash.exe` on Windows, never
>   `System32\bash.exe`). Save a snippet to a temporary `.sh` file and run
>   `bash "<resource root>/bin/li-run" <file>`; it prepares `LINTEL_SOURCE_ROOT`, `LINTEL_REPO_ROOT`
>   and the profile context.
> - **Tools:** Read=`view`, Write=`create`, Edit=`edit`, Bash=`bash`/`powershell`, Grep=`grep`,
>   Glob=`glob`, AskUserQuestion=`ask_user`, TodoWrite=the plan checklist, Task or a named role=`task`
>   with that custom agent, WebFetch=`web_fetch`.
> - **Other Lintel workflows** are native skills: invoke `/li-<name>` rather than reading their
>   files. Named roles such as `CodeReviewer` are custom agents.

# /generate-web

Web artifact generation with `--mode artifact|mockup`; default `artifact`
preserves the existing brief/pipeline/frontend-design routes below.

- **Mockup mode:** follow the [mockup procedure](../../../skills/generate-web/references/mockup.md) for
  `--brief`, `--reference`, `--tokens`, `--inherit-project`, `--copy-tier`,
  `--out` and optional `--preview`. It implies `single-file`: actual static HTML,
  inline CSS/minimal JS, no framework or build step.
- **Artifact variants:** `single-file` is self-contained HTML; `nextjs-scaffold`
  is a multi-file project with routes and components, not a deployment.

Use only explicitly selected or verified-profile templates and available project
resources. A named template is not proof a bundled skeleton exists.

The [shared design contract](../../../skills/design-dna/references/design-contract.md) is the
only input/argument/profile boundary. Template paths must be explicitly authorized;
their historic home convention does not permit personal-directory discovery.

## When to use

- Customer-demo landing page (single-file for quick iteration; Next.js for deployable demo)
- Engagement-internal microsite (technical wiki, runbook viewer)
- Pitch artifact that needs to look modern + carry the active pack's brand

## When NOT to use

- Static markdown — direct edit is faster
- Complex web app — Next.js scaffold is starter, not full product
- Slide artifact — use `/generate-ppt`

## Inputs

- Required `--brief <path|inline>` — content brief **OR** `--from-pipeline <dir>` (Phase 2: shared pipeline mode) **OR** `--from-frontend-design <dir>` (v3.7 Phase B: frontend-design family integration)
- Required `--variant <single-file|nextjs-scaffold>` in artifact mode; mockup implies single-file
- Optional `--audience <text>` — primary audience
- Optional `--use-defaults` — force in-repo default templates
- Optional `--preview` — after generation, use `/web-session --mode open` on an owned admitted preview
- Optional `--theme <name>` — apply a pack-provided theme palette (default: neutral)
- Required explicit `--out <path>` for owned output; optional `--customer-share`
  is propagated from the director. Reject conflicting input modes, unknown or
  duplicate options; direct `--brief` remains an entry point into the same contract.

## From-pipeline mode (v3.5 Phase 2 — generate-pipeline integration)

If invoked with `--from-pipeline <run-dir>` instead of `--brief`:

1. **Read shared pipeline-output:**
   - `<run-dir>/content.md` — hero + sections + body with HTML-comment annotations
   - `<run-dir>/design-spec.json` — read `per_format.web.sections` for layout-mappings
   - Validate its existing envelope plus resolved `web_design`/`binding` through
     `design_contract.load_design`. Preserve legacy readability, not fabricated
     render readiness. Keep P12's document mappings intact.

2. **Replace brief-parsing logic** with direct-read of content.md sections + design-spec web-block-types (hero / sections / features / FAQ).

3. **Apply format-specific design-pass via design_pass_hook:**
   - Reads `per_format.web.sections[N].design_pass_hook` (canonical: WebExperienceCritic)
   - Applies the web-specific fidelity method to the selected sections; the hook
     name does not require another default post-generation reviewer
   - Per Reviewer Concern #7: WebExperienceCritic stays web-specific, not lifted

4. **CLI stays backward-compat:** existing `--brief`-flag invocations work unchanged. `--from-pipeline` is additive.

5. **4-gate pipeline runs as usual** after generation.

## From-frontend-design mode (v3.7 Phase B — frontend-* family integration, M-1 resolution)

If invoked with `--from-frontend-design <run-dir>` instead of `--brief` or `--from-pipeline`:

1. **Read frontend-design output:**
   - `<run-dir>/frontend-design-spec.json` — **distinct filename** from pipeline's `design-spec.json`, avoiding a schema collision. Verify `"source": "frontend-design"` + `"schema_version": 1` before consuming.
   - Embedded blocks: `typography`, `motion`, nullable `shader`, `component_libraries`, `layout_grammar`, `interaction_signature` and `visual_thesis`.

2. **Shared handshake:** use `design_contract.load_design` with the external
   prepared P05 context and explicit P07 configuration, then `renderer_args`.
   Checking two JSON strings alone does not validate bindings, choices or policy.

3. **Replace brief-parsing logic** with direct-read of spec:
   - Copy: preserve the bound brief/content; a visual thesis is design direction,
     not a replacement for substantive source text, tables or limitations
   - Typography: honor `typography.font_stacks[].loading_strategy` through the
     existing target's CSS/config; fetch or link external assets only when authorized
   - Motion: `none` emits no animation dependency; `css` emits only selected CSS;
     `library` imports only the selected, sourced library and justified configuration.
   - Shader: emit a selected GPU component only when
     `shader != null && shader.visual_thesis != "none" && shader.library != null`.
     Both null and the accepted non-null `visual_thesis: none, library: null`
     representation emit no GPU canvas, import or dependency. Apply the same
     predicate to pipeline `web_design.shader`; do not substitute an artificial score.
   - Component libraries: preserve existing primitives; emit no setup/import when
     the selected list is empty. New library advice requires source/version/license evidence.
   - Layout: apply `layout_grammar.max_width` + grid-config to root layout
   - Interaction: apply selected smoothing only through its explicitly chosen
     library/stack; native scrolling emits no smoothing dependency

4. **Design-pass hook integration:**
   - Follow [review ownership and reuse](../../../skills/frontend-design-review/references/built-review.md#review-ownership-and-reuse):
     return actual produced output, input identity and observations to one
     post-generation owner; do not run both critic aliases by default
   - `frontend-design-review` consumes that handoff and the original required
     observations. An optional request cannot waive mandatory independent review,
     and reuse requires the existing current-context reader/QA checks

5. **CLI stays backward-compat:** existing `--brief` + `--from-pipeline`-flag invocations work unchanged. `--from-frontend-design` is an additive third mode.

6. **prefers-reduced-motion handling** — always emit fallback per `motion.perf_budget.fallback_for_prefers_reduced_motion` field. Non-negotiable.

7. **Mobile-strategy emission** — apply the selected strategy through the actual
   CSS/library mechanism; do not introduce GSAP solely to handle a media query.

8. **4-gate pipeline runs as usual** after generation.

**Boundary with frontend-* family (L-002):** generate-web is the **rendering-engine** — file-output. frontend-design is the **design-director** — decisions. generate-web does NOT make design-decisions; it READS them from frontend-design-spec.json + renders accordingly.

## Workflow

1. **Preflight gates** — brand templates check, staleness, the active pack's compliance gates if customer-bound

2. **Read brief + parse structure:**
   - Hero (title + subtitle + CTA)
   - All substantive sections, preserving source detail rather than a fixed section cap
   - Optional: features grid, FAQ, footer
   Resolve direct brief input into the same frontend contract, pinning the existing
   project/profile and retrieval evidence before rendering. With no handed-over lock, follow
   the direct-entry steps in [Reusable patterns](#reusable-patterns) before the first design
   choice. No parallel private schema for this entry point.

3. **Apply the `WebExperienceCritic` method** for layout review BEFORE generation:
   - Information hierarchy
   - Accessibility (WCAG AA via existing AccessibilityChecker)
   - Motion-language considerations
   - Brand alignment

   Use actual native delegation when available and authorized; otherwise label
   the builder's pass as self-review. No actor or model is implied by this recipe.

3b. **Stack-guidance pass (ADR-0015 — retrieval before rendering):**
   ```bash
   python3 "${LINTEL_SKILLS_DIR:-skills}/design-dna/scripts/search.py" "<layout/feature keywords>" --stack html-tailwind   # or nextjs per variant
   ```
   Apply the returned Do/Don't/Severity rules during generation. python3 absent → Read
   `design-dna/data/stacks/<stack>.csv` (same root) directly.

4. **Generate per variant:**
   - **single-file:** render the selected design as one HTML file with inline
     CSS and only necessary authorized interactions
   - **nextjs-scaffold:** use a selected compatible skeleton or the established
     project structure; write routes/components and only justified manifest changes

5. **Gate 0 + 4-gate quality pipeline** (per /generate-ppt):
   - Gate 0 (mechanical, ADR-0015): use the
     [design validator](../../../skills/design-dna/scripts/validate_design.py),
     `validate_design.check(content, path,
     profile_hexes)` on actual HTML with the loaded design's resolved palette.
     Hard errors such as zoom-disable, killed focus and emoji icons block;
     off-palette/token findings retain their warning severity. Do not reconstruct
     a bundled profile path that ignores a selected pack asset or brief override.
   - Gate 1: voice (if customer-bound)
   - Gate 2: brand-conformance
   - Gate 3: honest-limitations (only if generating an AI-feature page with disclosure)
   - Gate 4: provenance

6. **Publish within scope:** atomically write/read back the selected `--out`,
   preserving an authorized replacement's preimage. Report actual checks and
   blocked/unverified obligations; no draft move confers release clearance.

7. **Optional preview** through the shared browser operations on an authorized owned
   local server. Verify health and actual session ownership first; provider availability
   and URL admission are not established by this instruction.

## Reusable patterns

Follow the [reusable pattern consumer contract](../../../skills/pattern/references/consumer-contract.md).
generate-web still makes no design decisions of its own; it renders the projected values.

**Handed-over lock** (from-frontend-design mode, or a direct run that is given a lock): run
`li-pattern verify-lock` on it against the current context before rendering. Only `ok`
continues. Then check the spec's `pattern_context` with `validate_visual` against that verified
lock, never against a stored report. A stale context, a mismatched setting or an unusable
selection blocks the render; it is not corrected here.

**Direct entry without a handed-over lock** (`--mode mockup --brief`, and the plain artifact
`--brief` route) resolves itself through the same contract. Do this **before the first design
choice**:

1. Write the evidenced context, and turn explicit brief decisions about bound settings into
   `--overrides`. Omit unknown facts, and never infer a target.
2. Run `li-pattern resolve --context <ctx> [--overrides <file>]` from the trusted source root.
   - `empty`: continue exactly as without patterns. Write no lock and no `pattern_context`.
   - `ready`: rerun the same command with `--lock
     .claude/runtime/patterns/<run-id>/patterns.lock.json`. The lock goes inside this repository
     even when `--out` is elsewhere. Confirm the same `selection_digest`, then run
     `li-pattern verify-lock` on the new lock against the same context; only `ok` continues.
     Carry the full requirements and setting winners into the design choices.
   - Any other status blocks the dependent design decision and the render: `needs-context`,
     `conflict`, `unavailable` (including a pack context in `fallback` or `error`) and
     `invalid`. So does a run that prints no JSON report. Report the status; never
     hand-write a lock, and never fall back to another source or renderer.
3. Apply `$LINTEL_SOURCE_ROOT/lib/pattern_visual.py` `project_visual` with the verified lock to
   the synthesized design spec. This writes the **final** `frontend-design-spec.json`, with its
   `pattern_context`, before that spec's P05 binding is prepared.
   - Never project after binding: that would change bytes the bound context already selected.
4. Load the bound spec with `design_contract.load_design` and the current P07 configuration.
   With a `ready` selection, pass `pattern_lock` and `pattern_context`, and select both files
   plus `.claude/patterns` in the P05 context; this is what lets a verified pattern palette winner
   outrank the pinned profile.
   Run `validate_visual` against the verified lock **before rendering**; only `passed`
   continues, and unknown settings stay open review items.

The mockup procedure's step 2 decision method and step 3 load follow these steps; see
[mockup mode](../../../skills/generate-web/references/mockup.md). Direct entry and cycle entry call the same command with the
same inputs, so they produce the same `selection_digest`. When the runtime reports no patterns,
rendering is unchanged.

## Report format

Report mode/variant, exact source/design/output paths, selected profile/template,
retained content, actual rendering operations and mechanical/voice/brand/
limitations/provenance outcomes. State whether preview, keyboard, responsive,
reduced-motion and other required observations ran, with their actual evidence.
Missing browser or renderer coverage remains unverified, not a fabricated pass.

## Compliance integration

- 4-gate pipeline is the customer-bound enforcement path; the specific gates are pack-configurable (`resolve_pack_field compliance.hooks`; none by default)
- HTML/JS output sanitized — no inline scripts that fetch external resources without disclosure
- nextjs-scaffold retains applicable deployment requirements but triggers no deployment

## Failure modes

- **nextjs-scaffold template incomplete** — block that requested target with the
  concrete missing resource; do not silently change the requested artifact.
- **Voice gate fails on customer-facing content** — surface flagged paragraphs, allow regen
- **Accessibility audit fails** (contrast issue, missing alt text) — surface findings; require fixes before gate-2 passes
- **Customer-data in brief** — BLOCK

## Examples

**Single-file customer demo:**
```
> /generate-web --brief demo-brief.md --variant single-file --out demo.html --preview
[Render; preview only through a verified owned server and authorized provider.]
```

**Next.js scaffold:**
```
> /generate-web --brief microsite-brief.md --variant nextjs-scaffold --use-defaults --out microsite
[Render a compatible scaffold; use existing tooling and authorized dependency restoration only.]
```

## See also

- `BRAND-INTEGRATION.md`
- `WebExperienceCritic` agent
- `AccessibilityChecker` (Layer 4) for WCAG audit
- `/web-session --mode open` — preview the generated file through owned loopback
- `/frontend-design --mode variants` — compare directions around a mockup
- `/generate-docs` — produce source-grounded Markdown before a format handoff
- The active pack's deploy gate — wire Next.js deployment (pack-configurable)

