Lintel on GitHub Copilot. Generated from
skills/frontend-design/SKILL.md; edit the canonical file, then runli-copilot init.
- Resource root:
../../..from this skill's base directory (the Lintel source withbin/,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/anddata/folders (and a<base>that the workflow defines as its own directory) mean../../../skills/frontend-design/in the Lintel source, not this generated folder.${LINTEL_SKILLS_DIR:-skills}means the skills root,../../../skills. Abin/li-runstep runs in the working repository, so use$LINTEL_SKILLS_DIR/frontend-design/there.- Shell steps: run Bash snippets with Bash (Git for Windows'
bash.exeon Windows, neverSystem32\bash.exe). Save a snippet to a temporary.shfile and runbash "<resource root>/bin/li-run" <file>; it preparesLINTEL_SOURCE_ROOT,LINTEL_REPO_ROOTand 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=taskwith that custom agent, WebFetch=web_fetch.- Other Lintel workflows are native skills: invoke
/li-<name>rather than reading their files. Named roles such asCodeReviewerare custom agents.
You are the frontend-design skill, the design-director layer over existing rendering tools.
Modes
Select --mode design|advice|variants; default design preserves the ordinary
brief-to-design-to-render workflow below. Reject conflicting mode inputs before
writing. These are skill inputs, not an installed command parser.
| Mode | Inputs and output |
|---|---|
design |
<brief>, selected pattern/target/stack, explicit --out; bound frontend-design-spec.json, rendered artifact and review |
advice |
<question>, --scope, --read-design-system, --cross-check; grounded alternatives and a recommendation, no code |
variants |
--seed, --axis, --count (2-8, default 4), optional --brief/--only, explicit --out; per-variant designs, rendered HTML and comparison index.html |
For advice follow the advice procedure. For variants
follow the variants procedure. Neither mode invents
independent actors, installs tools, replaces project technology or waives policy.
Advice stops before rendering. Variants reuse this decision contract and the
existing generate-web renderer for each actual output.
What this skill does
Orchestrates design-director-decisions (typography + motion + shader thesis + component-library-pick) → produces frontend-design-spec.json → calls rendering-engine (generate-web single-file/Next.js or generate-app full-vite/svelte/next-monorepo — Phase B) for file-output.
The skill OWNS design-decisions. It does NOT own HTML/Next.js-file-generation (that's the generate-* family per the v3.7 design-doc-boundary).
Reads operator brief → dispatches typography + motion sub-skills in parallel → synthesizes frontend-design-spec.json → calls rendering-engine.
The direct design contract and its single schema/helper govern all producers, renderer arguments and review. Use actual available delegation or serial execution; a role name is not an invocation.
When to use
- "A landing page for our legal-research assistant" — full end-to-end mode for production-ready design
- Customer demo that must look Awwwards-grade
- Internal microsite where visual quality affects adoption
- Multi-format engagement where /li-cycle BUILD-phase produces an app + design must match the pitch
When NOT to use
- Wireframe-only sketch →
/li-generate-web --mode mockup - Single design-decision-axis (just typography or just motion) → solo sub-skill
/li-frontend-typographyor/li-frontend-motion - Pure file-gen without design-direction →
/li-generate-webdirectly with--brief - Re-render existing run →
/li-generate-web --from-frontend-design <existing-run-dir>
Inputs
- Required
<brief>— design brief text or path to brief.md - Optional
--pattern <name>— select an explicitly configured project/pack pattern; no personal-vault discovery - Optional
--target-format <single-file|nextjs|app>— default:single-file.apptriggers generate-app (Phase B) - Optional
--customer-share— sets CUSTOMER_SHARE=1, triggers compliance-gate + voice-gate - Required
--out <path>for rendering — owned repository-relative run directory - Optional
--overwrite— permit replacement of the explicitly selecteddesign-dna.mdretrieval output using its captured preimage; this does not authorize replacing other outputs or choosing another destination - Optional
--skip-shader— explicit no-shader choice, not an unfinished GPU feature --stack <next-app|vite-react|svelte-kit>for--target-format app, selected explicitly or confirmed from the existing project manifest; never infer React for an unknown stack.
Design mode workflow
Apply the axis ownership contract throughout: one decision method and one publication per fragment. A separate role context is optional expertise, not an automatic second execution or independent review.
Step 1 — Parse invocation + warm context
brief="${1:-}"
pattern="${PATTERN:-}"
target_format="${TARGET_FORMAT:-single-file}"
customer_share="${CUSTOMER_SHARE:-}"
out_dir="${OUT:?select an owned repository-relative output directory}"
[ -z "$brief" ] && { echo "Usage: /li-frontend-design <brief> [--pattern <name>] [--target-format <single-file|nextjs|app>]"; exit 2; }
Reject missing, unknown, duplicate or conflicting options before creating output.
Preserve the brief as literal data. --skip-shader records a no-shader decision.
The application stack and output path must reach the renderer unchanged.
Voice-tier resolution: default internal. If --customer-share, resolve the active
pack's actual voice requirements (resolve_pack_field voice.gates_active; none by
default) and retain any unverified mandatory observation before sharing. A declared
gate is not evidence that a host mechanism executed.
Step 1.5 — Design DNA pass (REQUIRED — ADR-0015/0016)
Retrieval before generation. Resolve the active design profile and search the corpus BEFORE any design decision:
Bind nonempty DESIGN_QUERY and PROJECT_NAME from the actual brief/project.
OUT is the selected repository-relative directory; OVERWRITE=1 records
only the explicit retrieval replacement permission. Capture its state before
searching, retain failed output separately, and publish only successful UTF-8
retrieval through the existing rooted writer. A directory is not overwrite authority.
python3 -I -B - "${LINTEL_SOURCE_ROOT:?trusted source required}" \
"${LINTEL_REPO_ROOT:?selected repository required}" "${OUT:?selected output required}" \
"${DESIGN_QUERY:?derive the retrieval query}" "${PROJECT_NAME:?select the project name}" \
"${OVERWRITE:-0}" <<'PY'
from pathlib import Path
import subprocess
import sys
source, repo, out_dir, query, project, overwrite = sys.argv[1:]
sys.path.insert(0, str(Path(source) / "lib"))
import context_safety as safety
try:
if overwrite not in ("0", "1"):
raise ValueError("OVERWRITE must be 0 or 1.")
root = safety.checked_root(Path(repo))
relative = (Path(out_dir) / "design-dna.md").as_posix()
original_state = safety.file_state(root, relative)
if original_state is not None and overwrite != "1":
raise FileExistsError("Retrieval output exists; explicit replacement permission is required.")
result = subprocess.run(
[sys.executable, "-I", "-B", str(Path(source) / "skills/design-dna/scripts/search.py"),
query, "--design-system", "-f", "markdown", "-p", project],
capture_output=True,
)
if result.returncode:
sys.stderr.buffer.write(result.stderr)
print(f"ERROR [lintel/design-retrieval]: producer exited {result.returncode}", file=sys.stderr)
raise SystemExit(result.returncode)
if not result.stdout.decode("utf-8").strip():
raise ValueError("Retrieval returned no usable text.")
safety.atomic_write(
root, relative, result.stdout,
mode=original_state["mode"] if original_state is not None else 0o600,
expected=original_state, check_expected=True,
)
persisted, _ = safety.read_owned(root, relative)
if persisted != result.stdout:
raise ValueError("Retrieval output readback differs.")
print(root / relative)
except (ValueError, OSError, UnicodeError) as error:
print(f"ERROR [lintel/design-retrieval]: {error}", file=sys.stderr)
raise SystemExit(2)
PY
Use the already verified P07 profile_ref and design_contract.profile_asset to select
the pack-owned profile before the same named bundled asset. Retain its hash and
retrieval output in binding. Missing required policy or a selected asset blocks;
do not source a personal-home fallback or silently substitute a brand.
Precedence: brief > verified profile > corpus hit — the profile is the
selected baseline; the corpus recommendation fills what the
profile doesn't pin (style pattern, landing structure, product-specific palette when the brief
asks for one); the brief's own words always win. Both design-dna.md and the profile feed
Step 2-4 dispatch and Step 5 synthesis. No python3 → use the grep fallback documented in
skills/design-dna/SKILL.md (the corpus is plain CSV).
Step 2-4 — Parallel sub-skill dispatch (M-4 resolution)
Typography and motion are independent decision tasks. Run concurrently only when the actual host provides attributable disjoint output ownership; otherwise serialize.
Concurrent dispatch:
├─ /li-frontend-typography --brief "$brief" --out "$out_dir/typography.json"
└─ /li-frontend-motion --brief "$brief" --out "$out_dir/motion.json"
(Phase A2 adds parallel /li-frontend-shader → $out_dir/shader.json)
Both sub-skills receive $out_dir/design-dna.md + the active profile as context (Step 1.5
outputs): typography starts from the profile's font roles + the corpus pairing hits; motion
starts from the profile's duration/easing tokens. They deviate only where the brief demands it.
Wait for both actual results before synthesis. No timing or parallel-execution claim follows from this recipe. None/CSS motion is a complete result, not a stub.
Step 5 — Synthesize frontend-design-spec.json
Read typography.json + motion.json (+ shader.json if A2). Synthesizes into frontend-design-spec.json:
{
"schema_version": 1,
"generated_at": "<iso-8601>",
"brief_hash": "<sha256 of brief>",
"source": "frontend-design",
"target_format": "single-file | nextjs | app",
"typography": { /* embedded from typography.json */ },
"motion": { /* embedded from motion.json */ },
"shader": null,
"component_libraries": [],
"layout_grammar": {
"max_width": "1200px",
"section_spacing": "var(--space-section)",
"grid": "12-col"
},
"interaction_signature": {
"scroll_smoothing": false,
"hover_intent": "subtle",
"page_transitions": "none"
},
"palette": {
"source_profile": "<selected-profile>",
"tokens": { "<semantic-name>": "<hex>" }
},
"style": {
"name": "<chosen style from design-dna search>",
"anti_patterns": ["<from the corpus reasoning rule>"]
},
"design_dna": {
"profile": "<selected-profile>",
"search_query": "<the Step 1.5 query>",
"search_ref": "design-dna.md"
},
"visual_thesis": "<one-paragraph synthesis>",
"voice_tier": "internal | customer-share",
"binding": { /* exact profile, brief, project, retrieval and provenance per shared schema */ }
}
palette, style and design_dna are additive optional fields (ADR-0015) — schema_version
stays 1; readers tolerate their absence (minor-additive per the schema-evolution policy below).
Legacy input remains readable, not automatically renderable. New resolved output
needs palette tokens, explicit motion mode and the shared binding. Libraries are
chosen only when justified by the existing stack and brief, with exact sourced
versions/licenses; empty lists are valid.
Schema-version discipline (M-5 resolution): ALL Lintel frontend-* contract-JSON files include "schema_version": 1. generate-web/generate-app readers log+reject on unknown major version. Schema-evolution policy: minor changes additive (new fields tolerated), major changes require new version + migration-path.
source-discriminator: "source": "frontend-design" distinguishes from pipeline's design-spec.json "source": "pipeline" (M-1 resolution — different filenames + explicit discriminator field).
Step 6 — Call rendering-engine
Prepare the external P05 input context, then call the shared helper's
renderer-args operation with the explicit target/profile paths. With a ready pattern
selection, also pass --pattern-lock and --pattern-context, and select both files plus
.claude/patterns in the P05 context; only this verified selection admits a pattern palette
winner over the pinned profile. It validates current bytes and returns a literal argument array:
single-file->generate-web --from-frontend-design <run> --variant single-file --out <out>nextjs->generate-web --from-frontend-design <run> --variant nextjs-scaffold --out <out>app->generate-app --from-frontend-design <run> --stack <selected-stack> --out <out>
Propagate --customer-share when selected. Invoke through the actual host only
within authorization; mapping itself reports executed: false. Missing stack,
unresolved bindings or incompatible existing technology block before rendering.
Step 7 — Quality gate (MANDATORY — ADR-0015)
The gate is no longer optional. Two parts, in order:
- Run the existing mechanical validator on actual produced HTML/CSS. Use the
resolved palette, including explicit brief overrides, rather than rebuilding
a bundled
$dna/profiles/<name>path that ignores a pack-owned asset. The existingvalidate_design.check(content, path, profile_hexes)API accepts the lowercase values ofloaded_design["design"]["palette"]["tokens"]. Preserve its returned errors/warnings separately; errors block. The standalone validator CLI remains available when an explicit verified asset path is used. - Own the single post-generation handoff through
review ownership and reuse.
Reuse only an actually current, applicable independent result and complete QA.
Otherwise invoke
/li-frontend-design-reviewfor the actual output and missing required coverage. That consumer rechecks P07 and the original P05 obligations; a renderer's self-check or advisory report does not substitute for it.
Validator errors → BLOCKED (fix and re-render; never ship over a red gate). No rendered HTML yet (spec-only run) → validator runs in generate-web/generate-app when output exists; spec feedback does not count as built-UI review. python3 absent → run the review with the design-dna non-negotiables checklist explicitly in scope.
Step 8 — Output paths + recommendation
FRONTEND-DESIGN RUN COMPLETE
══════════════════════════════════════════════════════════════════
Run dir: $out_dir
Typography spec: $out_dir/typography.json
Motion spec: $out_dir/motion.json
Frontend design spec: $out_dir/frontend-design-spec.json
Voice tier: $voice_tier
Target format: $target_format
Next:
Render: /li-generate-web --from-frontend-design $out_dir (Phase B)
Review: /li-frontend-design-review $out_dir (Phase A2)
Extract as pattern: /li-frontend-style-extract $out_dir/* (Phase A2)
Voice tier behavior
voice: mixed. Default internal. --customer-share selects applicable compliance
and voice review (resolve_pack_field voice.gates_active for voice; none by default),
not an assertion that a gate executed.
Reusable patterns
Follow the reusable pattern consumer contract.
Resolve, or verify a supplied lock, before the first design decision. Turn explicit brief
decisions about bound settings into --overrides before resolving; the adapter never guesses.
After synthesizing frontend-design-spec.json, apply
$LINTEL_SOURCE_ROOT/lib/pattern_visual.py project_visual (with the resolved report and its
context, or the verified lock) to write the final setting winners and the optional
pattern_context; unknown settings stay open review items. Hand the verified lock, not the
report, to generate-web, generate-app and frontend-design-review. With selected patterns the
preference order is explicit brief overrides > repository > active-pack > explicitly selected
personal pattern defaults > Design DNA profile > corpus, with mandatory clauses bounding all of
it; with none, brief > profile > corpus is unchanged. Legacy --pattern/--baseline names keep
legacy lookup and map only to defaults; colliding names need a qualified reference.
Status protocol
- DONE — the requested mode produced its actual outputs and required observations; spec validation alone does not complete a requested render/review
- DONE_WITH_CONCERNS — sub-skill returned with warnings (e.g., font-license unclear)
- BLOCKED — sub-skill failed, OR brief unparsable, OR customer-share check failed
- NEEDS_CONTEXT — brief too vague (no audience, no purpose, no aesthetic-direction)
Integration
Reads:
<brief>argument (path or inline text)- Explicitly selected project/pack pattern (if
--patternis set) - Verified P07 reference, selected profile asset and actual voice requirements
Writes:
<out>/typography.jsonand<out>/motion.json(validated sub-skill output)<out>/frontend-design-spec.json(Step 5 synthesis)- Variants add separate bound runs, rendered files and comparison
index.html - Advice returns Markdown or the explicit owned
--out; no rendered artifact
Calls into:
/li-design-dnasystem search + profile resolution (Step 1.5, required) + validator (Step 7)/li-frontend-typography(sub-skill, parallel)/li-frontend-motion(sub-skill, parallel)/li-generate-web --from-frontend-design <run-dir>(Phase B)- the active pack's voice requirements (
resolve_pack_field voice.gates_active; none by default — if customer-share) /li-compliance-gate(existing, if customer-share)
Boundary with the generate- family:*
frontend-design is the design-director layer; generate-web/generate-app own file output. Direct brief/mockup rendering can use the director's decision method without recursively invoking its render step. No second design schema is created.
Selected brand assets: use the already verified profile asset or explicit
repository/pack pattern references. Personal assets require an explicitly selected
authorized source; no home-directory discovery, default path or lazy creation.
The bundled ultra-modern-lovable-style seed remains available through its
declared source location, not an assumed personal copy.
Customer-share control boundary
Use the existing /li-compliance-gate control contract for this exact artifact and
actual policy source/version/applicability. No generic --check switch or named
font/motion/shader licensing validator is supplied by that skill. Perform the
selected asset evidence procedures:
font-licensing, motion-licensing, shader-licensing, brand-source and
brand-freshness for the actual selected assets and requirements. These are
manual/source inspections recorded as P05 check controls, not active scanners.
Retain applicable voice/policy observations as well; a missing required check
remains unverified and blocks its affected sharing action.
No-applicable-controls is not licensing clearance.
Pattern coverage and a valid design fragment do not establish these observations.
Retain mandatory clauses, notices and the same work/profile identity. A
--customer-share request selects the review boundary; it does not publish, install
tools, acquire a license or authorize access to unselected personal assets.
Anti-patterns
- Generating HTML inside frontend-design — that's generate-web's job (boundary-violation per L-002). Use
--from-frontend-designchain. - Invented parallel dispatch — serial/manual operation is valid when the host cannot provide attributable parallel ownership.
- Pre-baking canonical patterns — Phase A1 ships slot-bootstrapping only. Canonical hand-curation deferred to A2 after schema validates against operator-real briefs.
- Bundling unlicensed fonts/libraries — preserve actual source/license evidence and authorized tooling scope; no installation follows from advice.
Failure recovery
- Sub-skill failure: retain partial artifacts and report the missing decision; do not turn a stub into a resolved renderable spec.
- Brief unparsable: BLOCKED, return to operator with prompt-improvement-suggestions
- Schema-validation failure on frontend-design-spec.json: BLOCKED, log diff between produced + expected schema
- Voice-gate fail (customer-share): BLOCKED, surface voice-check output verbatim
Recommended next steps after invocation
- Phase A1: hand off
$out_dir/frontend-design-spec.jsonto generate-web manually for now (Phase B automatic chain) - Phase A2: pair with
/li-frontend-design-reviewfor 6-dimension audit - Phase A2+: extract successful design via
/li-frontend-style-extract $out_dir/*→ adds to vault - Cycle-integration: defer to Phase D after operator dogfood validates real-engagement flow
L-001/L-002/L-003 application
- L-001 (scaffolding-not-content): skill body is contract. Agent at invocation produces actual typography choices, motion language, shader thesis. Canonical pattern deferred to A2. Operator-extracted patterns dominate vault long-term.
- L-002 (grep-first): the generate-* family is preserved. Frontend-* family = identity-anchor + design-director layer, NOT a replacement. Boundary-table-row added to the design-doc.
- L-003 (verify-claims): schema_version field on every contract JSON. generate-web reader verifies before consuming. Don't trust stale schemas.