martinille/ille-webdesign-skill

Ille Webdesign Skill

Run a closed local design loop: understand the real repository, choose a coherent art direction, implement in the existing stack, inspect real local screenshots, obtain independent criticism, and correct the result. Never claim a visual audit passed without screenshots.

Non-negotiable boundaries

• Work offline. Do not use web search, Figma, remote fonts/assets, external APIs, uploads, telemetry, or another design skill. An already available Chrome DevTools MCP may be used only as an optional headless localhost/file renderer and DOM inspector; never make it a required plugin dependency or use it for remote browsing.
• Preserve the project's framework, architecture, naming, existing comments, assets, and design conventions unless the user explicitly approves a change.
• Never auto-install packages or browsers. Run node scripts/doctor.mjs --project <root> to inspect local binaries/modules, then separately check whether the current session already exposes Chrome DevTools MCP. Report a missing renderer honestly.
• Refuse exact copying of another site or proprietary design system; abstract principles and make an original result.
• Keep accessibility, trust-boundary validation, security, error handling, and required tests intact.
• Store temporary work in <project>/.codex-design/runs/<task-id>/; do not commit it by default.

Choose the mode

• Micro — one component or small visual change in a stable system. Use one internal direction, relevant state screenshots, one independent critic, and correct every severe finding.
• Standard — a page, major section, feature, or medium redesign. Produce a brief and three materially different directions; after the user selects a direction, implement, capture mobile/tablet/desktop, use two independent critics, and complete two goal-led render iterations unless the first has no findings.
• Studio — greenfield site, new brand, major redesign, or broad design system. Produce three to five hypotheses and three small working concepts; ask the user to select one before production work, then use three critics and two to four goal-led iterations.

If materially different directions are viable, stop at the art-direction gate and let the user choose. Do not collapse them into a compromise.

1. Reconnaissance and brief

1. Read the nearest AGENTS.md and the files that drive the current frontend.
2. Run node scripts/detect-project.mjs --project <root> and inspect its evidence. Read stack-adapters.md for the detected stack.
3. Map components, tokens, fonts, icons, imagery, breakpoints, routes, build/test/preview commands, and constraints. For independent reconnaissance, spawn a read-only subagent with the Repository Analyst prompt in agent-roles.md.
4. Fill design-brief.md. Mark non-critical gaps as assumptions; ask only when a choice changes behavior, UX, scope, risk, data, dependencies, or maintainability.
5. Read domain-playbooks.md and the matching record in references/domain-profiles.json.

2. Generate and select directions

1. Read design-space.md, style-families.md, and anti-patterns.md.
2. Run node scripts/recommend-directions.mjs --brief <brief.json> --count <n>; use its ranking as evidence, not authority.
3. Describe every candidate with coordinates, thesis, layout, type, color, material, imagery, geometry, motion, interaction, signature moment, risks, and complexity in visual-directions.md.
4. In Standard and Studio, ensure candidates differ on at least five axes and include refined, brand-led, and experimental-but-usable options. Validate with node scripts/validate-direction.mjs --input <directions.json>.
5. Use the Art Director prompt from agent-roles.md. Score candidates with evaluation-rubric.md, then obtain the user's choice when the directions are materially distinct.

Load style-catalog.json, pattern-catalog.json, and compatibility-matrix.json only while generating or validating directions. The structured domain data lives in domain-profiles.json. Read composition.md, typography.md, color-and-material.md, and imagery.md only for the selected direction.

3. Define and implement the system

1. Record only tokens that the implementation uses in design-system.md: semantic colors, type roles and fluid scale, spacing, containers/grid, borders/radii, elevation/surfaces, icons/images, focus, motion, and responsive behavior.
2. Read component-design.md for component/state work, responsive-design.md for every layout, accessibility.md for every implementation, and motion.md only when motion is relevant.
3. Implement semantic HTML and native behavior first. Include relevant loading, empty, error, disabled, hover, focus, and keyboard states. Respect prefers-reduced-motion; never fabricate metrics, testimonials, or content.
4. Give every larger design one content-serving signature moment. Use existing assets; if none fit, create original local CSS or SVG artwork.

4. Render, audit, criticize, iterate

1. Start or locate the local server using the detected project command. Never concatenate untrusted input into a shell command.
2. Prefer an already exposed native browser or Chrome DevTools MCP in headless mode for local full-page/state capture and DOM evidence. Otherwise run node scripts/capture.mjs --project <root> --url <local-url> --routes <routes> --output .codex-design/runs/<id>/screenshots --iteration 1. Capture relevant states and at least mobile and desktop; Standard and Studio also require tablet.
3. Open every real screenshot with the available image viewer. Use Chrome DevTools MCP evaluation/console/network tools when available; otherwise run node scripts/audit-dom.mjs with the same target. Run node scripts/create-contact-sheet.mjs --metadata <capture-metadata.json> for script captures.
4. Give raw screenshots and audit output—not the implementer's rationale—to independent read-only critics using agent-roles.md. Two critics must not see each other's first report.
5. Save reports with visual-review.md. Aggregate conservatively: blockers and objective DOM failures override scores; use the lower subjective category score.
6. Fix blockers and highest-severity findings. Re-render with one explicit iteration goal and compare with the previous screenshots. Follow mode iteration limits.

Pass only with screenshots, confidence, no blocker/overflow/unintended clipping, a purpose-built mobile layout, clear primary action, readable text, score at least 85/100, and fewer than four strong generic anti-patterns. Otherwise report the remaining failures.

5. Handoff

• Run the project's build and smallest relevant tests.
• Save the brief, directions, selection, screenshots, DOM audit, critic reports, iteration log, and final score under the run directory using design-run.json.
• Summarize changed files, verified commands, screenshots inspected, final score, unresolved risks, and the run path. Never describe an unavailable check as passed.

Reference routing

• Read output-contracts.md when producing JSON/Markdown artifacts or critic reports.
• Read agent-roles.md before spawning any design subagent.
• Read maintenance.md only when changing this skill, catalogs, or rubric.
• Use anti-patterns.md at direction selection and every final review.
• The detailed catalogs and all other references are direct children of this file; load only the files named by the active phase.