Lintel on GitHub Copilot. Generated from
skills/generate-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/generate-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/generate-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 generate-design skill — the shared content pipeline's design-spec producer.
What this skill does
Reads content.md (with HTML-comment annotations for type + voice + key_message) → produces design-spec.json with per-target-format layout-mappings, palette references, font hints, logo placements, and per-format design-pass hooks for format-builders.
This is the "shared design baseline." Format-builders (generate-ppt, generate-web, generate-word) read design-spec.json + apply their own format-specific design-pass (e.g., PPTNarrativeArchitect for PPT slide-narrative, WebExperienceCritic for web hero/flow, WordTechnicalEditor for word headings/style). The shared baseline gives them consistency; the per-format pass gives them format-fidelity.
For web, use the one direct design contract. Keep document-format mappings intact; P12 owns their rendering methods.
Used by generate orchestrator as Step 5, or solo when operator wants to re-design existing content for different formats or different brand-palette.
When to use
- Third step of
/li-generateorchestrator chain (after write) - Operator wants to retarget existing content to different formats
- Brand-palette swap (re-design with
--palette nordic-minimalvsdefault) - A/B-test layout strategies for same content
When NOT to use
- Operator has no content.md — invoke
/li-generate-writefirst - Pure visual mockup without content — use HTML wireframe sketch instead
- Format-specific design tweaks — those happen in format-builder's design-pass hook, not here
Inputs
- Required
--content <path>— content.md from generate-write - Required
--target-formats <ppt,web,word,...>— per-format spec generated for each - Optional
--palette <name>— explicit brief-level palette selection with source evidence - Optional
--brand-templates-dir <path>— explicitly authorized template root; no personal-home scan - Optional
--logo <path>— explicit logo override - Required
--out <path>— owned repository-relative output; the orchestrator may explicitly supply its already authorized${run_dir}/design-spec.json - Optional
--use-defaults— explicitly choose a blank design only when the brief/profile permits it; not a missing-brand or missing-output fallback
Follow owned source and output selection. A missing or unwritable output fails visibly with no alternate destination.
Design-spec.json schema
{
"version": "1.0",
"schema_version": 1,
"source": "pipeline",
"generated_at": "<iso-8601>",
"source_content_hash": "<sha256 of content.md>",
"palette": {
"name": "default",
"primary": "#0078D4",
"secondary": "#50E6FF",
"accent": "#FFB900",
"text_dark": "#1B1B1B",
"text_light": "#FFFFFF",
"background": "#FFFFFF"
},
"fonts": {
"heading": "Segoe UI Semibold",
"body": "Segoe UI",
"code": "Cascadia Code",
"heading_size": 28,
"body_size": 14
},
"logo": {
"path": "<explicitly-selected-logo-path>",
"position": "top-right"
},
"per_format": {
"ppt": {
"template_path": "<explicitly-selected-ppt-template-path>",
"layouts": [
{
"section_ref": "§1",
"layout_name": "Title Slide",
"layout_index": 0,
"elements": [
{"placeholder": "title", "content_field": "Title", "font_override": null},
{"placeholder": "subtitle", "content_field": "Subtitle", "font_override": null}
],
"animation": "dissolve",
"design_pass_hook": "PPTNarrativeArchitect"
}
]
},
"web": {
"template_path": "<explicitly-selected-web-template-path>",
"sections": [
{
"section_ref": "§1",
"block_type": "hero",
"elements": [
{"slot": "h1", "content_field": "Title"},
{"slot": "tagline", "content_field": "Subtitle"}
],
"design_pass_hook": "WebExperienceCritic"
}
]
},
"word": {
"template_path": "<explicitly-selected-word-template-path>",
"sections": [
{
"section_ref": "§1",
"heading_level": 1,
"elements": [
{"slot": "heading", "content_field": "Title"},
{"slot": "body", "content_field": "Body"}
],
"design_pass_hook": "WordTechnicalEditor"
}
]
}
}
}
The historical palette/font example above illustrates document projections, not a
brand to impose. New web output also includes web_design and binding as defined
by the shared schema. web_design uses the same common fields as the frontend v1
envelope. Legacy pipeline files remain readable but unresolved for new rendering.
Key contract points:
palette+fontsare shared across all target formats (consistency)per_format.<format>is format-specific layout-mappingdesign_pass_hooknames the format-specific agent that applies fidelity-pass at format-builder level (not invoked by generate-design directly)section_refties back to content.md§Nsections for traceability
Workflow
Step 1 — Read content.md + parse annotations
Parse content.md frontmatter + per-section HTML-comment annotations (<!-- type: ... -->, <!-- voice: ... -->, <!-- key_message: ... -->). Build per-section lookup table.
Step 2 — Load palette + brand templates
Load the verified P07 reference and selected design-profile asset through the shared
helper. Retain actual retrieval and asset bytes. A supplied --palette must resolve
to explicitly selected source evidence; a missing custom palette blocks instead of
silently selecting default. Preserve brief > profile > corpus, subject to policy
and existing project technology.
For each format in --target-formats, resolve the selected template only inside
--brand-templates-dir or the actual verified configured template root. Retain
the source/configuration path and template identity; do not derive a directory
from a palette name. Apply the brand-source and brand-freshness
selected asset evidence procedures
to any required brand/version/refresh obligations. No mtime-only license/brand
verdict or unconditional age threshold is supplied. A missing selected template
blocks; a blank mapping needs explicit --use-defaults and compatible policy.
Step 3 — Per-section layout-mapping
For each content.md section (§N):
- Per requested format, choose appropriate layout/block-type based on section's
typeannotation - Map content fields (Title, Subtitle, Body, Bullets) to format placeholders/slots
- Assign
design_pass_hook(PPT → PPTNarrativeArchitect, web → WebExperienceCritic, word → WordTechnicalEditor) - Apply palette + fonts (no overrides unless content explicitly differs)
Step 4 — Validate
- Every §N section has a layout-mapping for every target format
- No layout used > 3 times consecutively (rotation rule)
- Font sizes within palette min/max
- Logo placement consistent across all sections
- For web, run
design_contract.validate_spec(..., "pipeline")and thenload_designagainst the external P05 context before handing off to the renderer. Contradictory palette/font projections, unsupported versions or unresolved bindings block. No scalarcontrast_verifiedflag replaces observed P05 controls.
Step 5 — Write design-spec.json + return path
Publish only to --out through the shared owned-output procedure, against the
captured original state, and read back the written bytes. Missing/unwritable
output or readback failure blocks without switching destination. Surface summary
(per-format layout count, palette used, font baseline) to the operator.
Reusable patterns
Follow the reusable pattern consumer contract.
When the run has a lock, add the optional pattern_context attachment to design-spec.json with
design_attachment; the outer version: "1.0" and existing fields are unchanged. Direct entry
without a verified attachment resolves itself. Do not copy clause text into palette, fonts or
per-format mappings as a second authoritative copy.
Status protocol
- DONE — design-spec.json written, all sections mapped, validation passed
- DONE_WITH_CONCERNS — written but some validation warnings (layout-rotation, palette-staleness)
- BLOCKED — content.md missing or malformed, palette resolution failed, no template + no
--use-defaults - NEEDS_CONTEXT —
--target-formatsempty or unparseable
Pause-points
- Palette missing for
--palette <custom>name: report the missing selection; obtain its authorized source rather than substituting another brand - Layout-mapping ambiguous for §N (multiple valid layouts): surface options + recommendation
Integration
Reads:
content.md(from generate-write)- Explicitly selected palette source or actual verified design-profile asset
- Selected templates and logo within explicit owned or verified configured roots
Writes:
design-spec.jsonto--out
Consumed by:
/li-generateorchestrator (Step 5)/li-generate-ppt,/li-generate-web,/li-generate-word(canonical format-builders read design-spec.json + apply per-format design-pass)generate-pdfandgenerate-xlsxretain their actual standalone production and input-admission routes, not invented document layout projections. PDF inspection remains unavailable without a separately authorized reader; XLSX still requires actual recalculation/cache/reopen evidence.generate-visioretains its explicit unavailable-writer boundary. A design spec cannot create a missing writer or establish editable-format acceptance.
Anti-patterns
- Apply per-format design fidelity in generate-design — that's the design_pass_hook's job (format-builder-owned). Generate-design produces the baseline only.
- Override palette per-section — palette is shared across all sections + formats. Per-section overrides only if explicitly requested.
- Hard-code template path — use only explicitly selected assets or actual verified configured paths; a folder convention is not read permission.
- Skip
design_pass_hookfield — format-builders depend on it to know which agent to invoke for format-fidelity pass.
Failure recovery
- Palette resolution fails on
--palette <name>: BLOCKED with the exact missing selection; do not substitute a different brand. - Template missing: BLOCKED with the exact selected path and required source;
explicit policy-compatible
--use-defaultsis a new choice, not a silent fallback - Output missing/unwritable: BLOCKED; retain input and any owned partial artifact, report the actual error, and request an explicit repaired destination
- Validation rotation-rule violation: regenerate affected sections with varied layouts, flag if repeats
Recommended next steps after invocation
- For full chain: orchestrator triggers format-builders next (Step 7)
- For solo-iteration: operator inspects design-spec.json, tweaks layout assignments manually, then invokes format-builder
- For palette A/B-test: re-invoke with different
--palette+ diff the two design-spec.json files