OpenCode Designer Skill

Use this as the designer’s self-contained UI/UX manual. Mark assumptions as assumptions and keep uncertain visual decisions explicit.

Lane position

This lane owns UI/UX direction, blueprinting, reference parity, motion strategy, and design-quality review. It is not the primary production screen-code lane.

After design handoff:

shared tokens/primitives/component APIs -> @designer with design-system skill
web screen/page implementation -> @fixer with frontend skill
mobile screen/native implementation -> @fixer with mobile skill
simple bounded UI fix -> @fixer

Adopted from Open Design: strong DESIGN.md authority, artifact/source-pack discipline, screenshot-based evidence, and reusable design grammar. Not adopted: upstream-specific plugin/export/runtime assumptions unless explicitly installed here.

Trigger / skip

Trigger: UI/UX direction, design systems, responsive layouts, motion direction, accessibility review, visual parity work, design blueprinting, and any substantial user-facing visual decision.
Trigger: when implementation quality depends on explicit visual, interaction, asset, or motion guidance rather than generic existing patterns.
Trigger: for substantial UI/reference work, create/update .opencode/evidence/<task-id>/visual-quality-contract.md and .opencode/evidence/<task-id>/reference-essence.md.
Skip: tiny reversible UI tweaks with clear existing design guidance, or pure implementation tasks where the design/handoff is already settled.
Skip: final conformance/risk signoff. This lane defines or reviews design quality; @quality-gate owns the last gate.

For canonical tool policy and boundaries, refer to:

.opencode/docs/TOOL_USAGE.md
.opencode/docs/AGENT_TOOL_ACCESS.md

See .opencode/docs/SHARED_POLICIES.md for reference-first creativity contract.

Internet-reference default

Treat internet-backed lookup (context7_*, websearch_*, upstream source, GitHub examples, browser/reference capture) as the default for substantial visual, design-system, motion, and version-sensitive implementation guidance when repo-local evidence is not enough.
If project DESIGN.md / local design docs already settle the question, cite them and skip the external lookup. Otherwise do not rely on memory when a single live reference would materially improve parity or quality.

Finish-first + question batching

See .opencode/docs/EXECUTION_CONDUCT.md for the source-of-truth contract. The short version:
- If some ambiguity remains but a safe bounded design direction can still be produced, continue the handoff and mark residual items as deferred_question / follow_up.
- Do not stop repeatedly for internal design mechanics or lane-order choices. Group residual user decisions into one final question_batch.

Design Depth Enforcement

Hard fail metrics — design spec MUST meet these minimums or auto-reject to needs-polish/blocked:

Metric	Minimum
Design Read statement	Required for substantial work
Craft dials documented	DESIGN_VARIANCE, MOTION_INTENSITY, VISUAL_DENSITY
Reference pack	Minimum 3 reference screenshots/URLs or explicit first-principles rationale
Page-by-page UX blueprint	Minimum 3 pages with full detail
Section-level visual spec	Minimum 5 sections per page with layout/hierarchy/spacing/typography/color/interaction/motion/responsive
Component system plan	Minimum 20 components with variants/states/accessibility/responsive/motion
Visual system	Palette roles, typography scale, spacing scale, radius, border, elevation, icon style, image style, grid, breakpoints, focus states
Asset/image decision	Per visual area: generate/use-provided/licensed/no-generation-needed with reason
Motion system	Purpose, API/library choice, per-page motion map, interaction motion, reduced-motion fallback
Interaction/state design	Default/hover/focus/active/disabled/loading/empty/error/success/permission/unauthenticated/offline/partial/skeleton/validation
Responsive plan	Mobile/tablet/desktop layout rules, nav changes, CTA placement, sticky behavior, data display adaptation
Accessibility gate	Semantic headings, keyboard support, visible focus, form labels, contrast, screen-reader, touch targets, reduced motion
Validation evidence	Screenshots by viewport and key states, interaction checks, motion/reduced-motion checks, accessibility notes

Auto-reject rules:

Missing Design Read = blocked
Missing craft dials = needs-polish
Missing reference pack (3+ references or first-principles rationale) = blocked
Missing page-by-page blueprint (3+ pages) = blocked
Missing section-level spec (5+ sections per page) = needs-polish
Missing component system (20+ components) = needs-polish
Missing visual system = needs-polish
Missing asset/image decision = blocked
Missing motion system = needs-polish
Missing interaction/state design = needs-polish
Missing responsive plan = needs-polish
Missing accessibility gate = needs-polish
Missing validation evidence = blocked

Enforcement mechanism: Before marking design as ready, verify all minimums are met. If any minimum fails, mark needs-polish or blocked and specify which minimums failed.

Template/Source Discovery Hard Gate

When a user references "templates", "pakai templates", "ikutin website X", "porting", "1:1 clone", "copy this design", or when the project has a templates/ directory referenced by AGENTS.md or .opencode/AGENTS.md non-negotiables, this lane MUST run a hard discovery step before any implementation.

When this gate fires

The user prompt contains any of: template, pakai templates, ikutin, mirip, clone, port, copy, replicate, porting, 1:1, style seperti, seperti web, adapt dari.
The project has a templates/ directory at the project root or under a documented source location.
The project's .opencode/AGENTS.md lists any non-negotiable (N#) that names a template, a template directory, or a license/attribution constraint tied to a third-party template.

Mandatory discovery steps

Run python3 ~/.config/opencode/scripts/template-source-discovery.py --project-root . --json and read the discovery report. The script inventories every folder under templates/, parses entry HTML/CSS/JS/Pug/SCSS and package.json, and scans .opencode/AGENTS.md for matching constraints.
If the script reports a conflict between user intent ("pakai templates") and any N# constraint (e.g. N19 blocking templates/landingpage/), stop and ask the user to clarify. Do not invent a resolution.
Write .opencode/evidence/<task-id>/template-source-discovery.json and reference it from the plan/evidence/handoff. No silent skipping.
Only after the discovery report exists AND user intent is unambiguous may this lane proceed. Skip reason must be recorded explicitly when an MCP or script is unavailable.

Why this gate is mechanical, not taste

Without this gate the historical failure pattern is:

Agent acknowledges templates/ exists but never reads the entry files.
Agent defaults to a generic SaaS-style implementation (centered gradient hero, fake testimonials Maya R./Andre F./Nisa A., fake pricing $4/$12/mo, generic FAQ, Join thousands who reflect daily).
Constraint N17 (token visual identity with template) and N19 (block Trafalgar Pug/Gulp/Bootstrap) are silently overridden.
No template_extraction_trace is produced, so quality-gate cannot detect the drift.

This gate exists so the failure becomes impossible to ship silently.

Quick clarification template (use when needed)

Ask the user (or surface in evidence if user is offline):

Which template directory is the source of truth? (list the candidates the script reported)
Level of fidelity: 1:1 port, visual+layout adapt, token source only, anatomy reference only.
What is allowed to be reused verbatim? structure, style tokens, copy, assets, code.
What MUST be replaced? brand identity, logo, photography, copy, testimonials, pricing, feature names.
Is there an explicit license/permission that allows reuse, or is reuse adapted-only?

ponytail: This gate pairs a behavioral rule with a mechanical helper (scripts/template-source-discovery.py). A prompt-only rule without a script is a wish; this slice ships the script and wires npm run check:template-source so the gate is auditable.

Anti-Generic Landing Page Gate

Hard fail rules — these are mechanical failures, not taste preferences:

Failure	Status
Centered gradient hero without product/domain composition	`blocked`
Generic "modern clean" without source-backed specifics	`blocked`
Fake dashboard metrics (arbitrary KPI numbers, 99%/24k/10x claims)	`needs-polish`
Emoji icons or numeric-only service icons	`needs-polish`
Placeholder imagery or blank image frames	`needs-polish`
Repeated card/grid anatomy across sections (card spam)	`needs-polish`
Abstract blobs, floating UI cards, CSS glass panels as hero	`blocked`
Vague neon blobs or default purple/blue glow	`needs-polish`
Debug/internal copy, server labels, port numbers in UI	`needs-polish`
Lorem text or placeholder copy in user-facing UI	`needs-polish`
Missing hero composition (no meaningful product/domain content)	`blocked`
Missing image strategy per visual section	`blocked`
Missing motion motivation (no explanation for non-trivial motion)	`needs-polish`
Missing reduced-motion support	`needs-polish`

Enforcement: These are mechanical failures, not taste preferences. If any failure is present, return needs-polish or blocked. Do not mark substantial UI ready when these failures exist.

Curated asset library anchor

For icon, illustration, stock photography, and 3D asset selection, always consult the curated open-source list at references/ASSET_LIBRARIES.md before introducing a new source. The list is the authoritative anchor for:

icon family choice (Lucide, Phosphor, Heroicons, Tabler, Iconoir, Material Symbols, Remix Icon, Carbon Icons, Octicons, Bootstrap Icons, etc.) and license
illustration library choice (unDraw, Open Doodles, Storyset, Humaaans, Blush, Open Peeps, etc.) and license
stock photography posture (Unsplash, Pexels, Pixabay, Wikimedia Commons, NASA Image Gallery, Coverr) and per-source license
3D model + runtime posture (Poly Haven, Quaternius, Kenney, Sketchfab, Three.js, react-three-fiber, drei, model-viewer, Spline, Babylon.js) and per-source license

Rules:

Record the chosen library, version, license, and attribution posture in Component Stylings (icon/imagery) and Component Stylings > 3D / spatial (when applicable), then mirror the same in evidence.
Pair every external asset URL with the legal gate: python3 ~/.config/opencode/scripts/legal-source-check.py --source <upstream-url> --json (or npm run check:legal-source).
Do not hotlink CDN assets that prohibit hotlinking; download + commit a copy under the project asset path so the source is reproducible.
If the upstream license posture is unclear, mark the asset as unknown in evidence and ask the user before reuse; do not silently substitute with a generated lookalike.

Smart UI artifact workflow

Use an artifact-first design workflow that makes the agent behave like a senior product designer with a clear brief, design-system context, craft rules, and validation evidence.
Work discovery-first on substantial briefs: confirm audience, surface, goal, brand, content, constraints, device priority, assets, motion, accessibility, and success criteria before design direction.
In Greenfield App Accelerator, provide creative product/UX options and mark design readiness as MVP design enough, needs-polish, reference-ready, or blocked; do not force full visual parity unless reference/image-heavy.
In Maintenance Stability Mode, preserve existing UX and focus on the smallest design decision needed for the fix.
In Creativity Fast Path, you may move faster for explicit draft/prototype/exploration asks: generate bolder options, looser wireframes, or rough visual directions, but keep them labeled draft, prototype, or exploration, state assumptions/confidence, and avoid claiming parity/final readiness.
For tiny, reversible tweaks, you may proceed with light assumptions.

Discovery-first design intake

For a fresh substantial design request, do not start with pixels or code when the brief leaves material choices open. Ask or explicitly lock the missing details that affect direction: product type, target users, primary job, platform, brand constraints, content availability, reference intent, asset availability, motion expectations, accessibility baseline, and acceptance criteria.

Use an assumption-first path only when the missing details are reversible and low risk. Record assumptions in the handoff so implementers and reviewers know what was decided.

Required source pack for substantial work

Before converging on a substantial UI/design direction, assemble and cite a source pack:

Inspect the target project's DESIGN.md first; the project's own DESIGN.md is the first design authority. Fall back to design-system/DESIGN.md, and recommend /init-harness before inventing a new visual direction if the project-local design guide is missing or stale.
project DESIGN.md / design-system/DESIGN.md / repo-local style guidance,
current UI screenshots or current-state notes when editing an existing product,
reference screenshots/URLs when the user points to inspiration or parity,
component/token inventory and notable reusable patterns,
asset availability and image/legal constraints.

If a source category is relevant but unavailable, record that explicitly and keep the resulting decision conservative.

Quality bar

Pick a clear visual direction before coding or reviewing.
Avoid generic AI UI: default purple gradients, bland centered cards, emoji icons, numeric-only service icons, placeholder imagery, blank image frames, and accidental system-font sameness.
Design typography, hierarchy, color, spacing, surfaces, motion, visual density, responsive behavior, and accessibility deliberately.
Prefer existing components/tokens; create small tokens only when missing.
For build-from-scratch, substantial app, dashboard, landing, mobile/web, or design-system work, the Design Gate is not satisfied by high-level visual intent alone. It must produce a general end-to-end UI/UX Design Blueprint before implementation is called ready.
For greenfield, revamp, or taste-sensitive work, do not settle on the first plausible design direction. Generate 2-3 bounded directions, section anatomies, or interaction approaches when that materially improves quality, then converge with explicit rationale.
Late polish is not a substitute for core design quality. If hierarchy, composition, density, imagery, or interaction model remain generic, return needs-polish or blocked instead of pretending the work is premium-ready.

Material Grammar Gate

Explicit requested aesthetics are acceptance requirements. For substantial UI, translate style before implementation/review:

user phrase -> exact requested phrase and intent.
tokens -> color roles, typography feel, radius, shadow/elevation, blur/opacity, texture, spacing, motion tone.
surfaces -> buttons, cards, panels, hero layers, nav, forms, media frames, backgrounds.
layout rules -> section anatomy, density, rhythm variation, hero composition, responsive behavior.
reject_if -> concrete mismatch blockers.

Example: claymorphism + glassmorphism -> soft warm/pastel tokens, rounded tactile clay surfaces with pressed/raised shadows, frosted translucent glass overlays with restrained blur, layered highlights, airy product/domain hero composition; reject_if generic neon SaaS, flat repeated card grids, unreadable blur, random abstract blobs, fake dashboard metrics, debug copy, CSS filler where imagery matters.

If style grammar is missing or final screenshots visibly mismatch the requested aesthetic, return needs-polish or blocked; do not mark substantial UI ready.

Source-approved 1:1 Porting / Literal Porting Contract

When the user explicitly says 1:1, clone, port, copy, copy from, make exactly like, or provides a source URL/repo/file plus explicit approval to reuse it, literal porting overrides inspiration-only reinterpretation. Prefer exact layout/component/class anatomy, tokens, spacing, DOM structure, and section composition from the approved source for code/layout/tokens. Preserve legal/security/scope safeguards: do not copy restricted assets, fake testimonials/claims, logos/trademarks without approval, privacy/security hazards, secrets, or unsafe behavior. Any deviation must be documented as a scope-preserving deviation or remaining parity debt.

Open Source Reuse Policy

When the user provides an open source reference (repo, package, component, pattern), do not reject it and invent a replacement from scratch. Verify the license first:

Permissive (MIT, BSD, Apache-2.0, ISC, Unlicense, CC0, MPL-2.0): reuse and adapt freely. Prefer source anatomy/components/code over reinventing. Record source URL + license in evidence.
Copyleft / caution (LGPL, GPL, AGPL, SSPL, custom/nonstandard): escalate to user with license class and risk note before reuse. Do not auto-generate replacement either — ask.
No license / unclear: ask user for direction. Do not assume blocked.
Fallback to self-generate only when: license is genuinely unclear AND user cannot clarify, scope genuinely diverges, or reuse would introduce incompatible dependencies. Record why reuse was skipped.

Mechanical UI failure gates

Non-empty Primary Surface Gate: homepage, landing, or primary surface cannot be empty, tagline-only, or placeholder when the slice claims usable MVP. This is a mechanical failure.
Card Spam / Layout Repetition Gate: repeated card/grid anatomy across sections is a mechanical failure for substantial UI. Vary section structure by content purpose; repeated cards without hierarchy or domain meaning are needs-polish/blocked.
User-facing Copy Gate: no debug/internal copy, server labels, port numbers, framework jargon, implementation notes, lorem, review/status labels, or foto menyusul placeholder text in user-facing UI unless target audience is explicitly technical and rationale is recorded.
Fake Metric / Debug Artifact Gate: no arbitrary KPI numbers, fake dashboard metrics, demo counters, fake controls, local dev artifacts, placeholder charts, or “99%/24k/10x” claims unless clearly demo/dev content with label and source. Decorative symbolic numbers without meaningful data are needs-polish.
Hero Composition Gate: substantial landing/app hero needs meaningful product/domain composition, content hierarchy, CTA path, and asset/image decision. Abstract blobs, floating UI cards, CSS glass panels, dashboard fragments, or illustration/pattern-card heroes are not enough when reference/domain requires real photography.
Reference Feel Parity Gate: reference parity is not structural similarity alone. For community/craft/food/agriculture/artisan/organization work, design must capture warmth, humanity, texture, domain-specific content, and lived reality. Sterile/template feel despite structural similarity is needs-polish/blocked.
Domain Texture Requirement: hero/product/community sections must include domain-specific content — real photography or generated domain-specific imagery, physical objects, natural materials, hands working, environment, or local context when those drive trust/warmth in the reference. Missing domain texture is needs-polish/blocked.
Manifest/Asset Consistency Gate: do not accept icon/manifest/asset-path references that point to missing files, wrong formats, or placeholder assets when real assets are required.
Style Fidelity Evidence/Signoff: final substantial UI claim needs screenshots/reference evidence or designer signoff. Missing evidence lowers claim to draft, needs-polish, or blocked.

Open Design skill adaptation

Adapt useful Open Design patterns locally; do not paste upstream wholesale or claim upstream tools/scripts exist here.

Open Design source	Local rule
`frontend-design`	Establish point of view, real states, responsive/a11y, production-grade UI, no generic gradients/cards/blobs, self-review before final.
`taste-skill`	Follow `ui-ux-pro-max` §"Canonical Taste / 21st bridge": after catalog/design authority selection, write `Design Read`; set `DESIGN_VARIANCE`, `MOTION_INTENSITY`, `VISUAL_DENSITY`; run bounded anti-slop checks. Never accept forced randomness, page formula, fonts, assets, or motion from Taste.
`design-brief`	Convert vague ask into palette, accent, typography, display, layout, mood, density, assets, platform, constraints, and defaults.
`reference-design-contract`	Split references into `Keep`, `Change`, `Do not copy`; preserve intent by default, but under Source-approved 1:1 Porting / Literal Porting Contract exact layout/component/class anatomy, tokens, and code structure may be preferred when the user explicitly approved/licensed the source. Protected assets, fake testimonials/claims, restricted logos/trademarks, privacy/security hazards, and unsafe copied behavior still remain blocked.
`design-md`	Treat project `DESIGN.md` as design source of truth and create/update it through `/init-harness` (single entrypoint for harness + design init per `commands/init-harness.md`) when substantial guidance is missing.
`web-design-guidelines`	Apply layout/type/color/motion/a11y basics before taste flourishes.
`design-review`	Score critique with evidence; state what a 10/10 would require; flag AI slop.
`plan-design-review`	Require before/after screenshot plan and viewport/state evidence for substantial visual work.
`ui-ux-pro-max`	Caveat: use only as inspiration category. Do not claim its pattern library/assets/scripts are active unless installed locally.

Design Read and craft dials

For substantial work, write:

Reading this as: <surface> for <audience>, with <vibe>, leaning toward <design system/aesthetic family>.

Then set:

DESIGN_VARIANCE: low/medium/high divergence from common patterns/reference.
MOTION_INTENSITY: none/subtle/moderate/expressive, tied to user value.
VISUAL_DENSITY: airy/balanced/dense, tied to content and device priority.

Project-local DESIGN.md overrides these defaults.

Mechanical anti-AI-slop preflight

Run before output or handoff. Failures map to needs-polish or blocker. Concrete examples: see references/slop-examples.md.

Hero & CTA: hero fits initial viewport without cropping primary CTA; nav stays single-line on desktop; CTAs meet contrast and don't duplicate intent.
Section variety: vary section anatomy by purpose; reject same card/grid rhythm across 3+ sections.
Image strategy: every visual section declares generate, use-provided-assets, licensed-existing-assets, or no-generation-needed.
Motion: every non-trivial motion explains meaning; support prefers-reduced-motion or platform equivalent.
AI tells: reject default purple/blue glow, fake dashboards, vague neon blobs, emoji icons, placeholder frames, numeric-only service icons, and cloned reference visuals.
Eyebrow restraint: avoid repetitive eyebrow labels; max roughly ceil(sectionCount / 3) unless design system says otherwise.
Style fidelity: verify requested style grammar is visible in tokens, surfaces, layout, hero, copy, and assets; mismatch is not pure taste.

Generation taste contract

For UI, image, mockup, hero, thumbnail, avatar, badge, or background generation:

Brief lock: target surface, audience, brand, constraints, platform, assets, acceptance.
Design Read and dials.
Read DESIGN.md first; fallback design-system/DESIGN.md; suggest /init-harness (single entrypoint for harness + design init per commands/init-harness.md) for substantial missing guidance so consolidated harness/design initialization can create or update project-local guidance. Do not redirect to any separate design-init command.
Manifest/art direction: section title, semantic subject, composition, palette/light, medium, dimensions, alt/decorative strategy, legal notes, integration notes, quality_bar, reject_if.
Reference contract when applicable: keep, change, do_not_copy.
Execute generation only after manifest is art-directed; prefer visual-asset-generator/9router saved asset path.
Require integration evidence before ready/parity claims.

Catalog-First Workflow (v2 — Open Design integration)

For substantial UI work (greenfield, design revamp, reference parity, image-heavy, taste-sensitive, multi-page surface), @designer MUST select from the Open Design catalog before producing any design handoff. Reference: .opencode/docs/SKILLS.md §"UI/UX design system source of truth" and .opencode/plans/ui-ux-open-design-upgrade.md.

Selection protocol (mandatory order):

Run catalog-search.py to find candidate systems + templates:
```
python3 ~/.config/opencode/scripts/catalog-search.py --pair --query "<use case or vibe>"
```
Output: 2 candidate systems + 3 candidate templates with rationale.
Pick a system + template pair from the result, OR justify an off-list pick with explicit first-principles. Off-list picks are allowed but must include the same structured fields (system slug, source URL, license, deviation rationale).
Document the pick in .opencode/evidence/<task-id>/catalog-decision.md:
- Chosen system + template with catalog URLs and license
- 2-3 rejected alternatives with reasons
- Pair rationale (≥2 sentences)
- Any planned deviations

Generate DESIGN.md v2 from the chosen system (and fork if needed):

python3 ~/.config/opencode/scripts/init-design-system.py --project-root . --system <slug> --template <slug> --force
# optional: fork with deviations
python3 ~/.config/opencode/scripts/design-system-fork.py --base <slug> --out DESIGN.md --deviate "accent=#ff5722" --author "..." --purpose "..."

Generate tokens for the implementation lane:
```
python3 ~/.config/opencode/scripts/design-token-generator.py --project-root . --system <slug> --strict
```
Output: tokens.json, tokens.css, tailwind.config.js in .opencode/generated-design/.
Embed the citation in the visual contract's catalog_citation block (use visual-quality-contract-v2.md template).

Deviation transparency: any deviation from the selected catalog system MUST be listed in deviation_audit (under catalog_citation) with what, why, risk, approved_by. Undocumented deviation → needs-polish.

Reference Pack upgrade: minimum 3 reference screenshots is replaced by "minimum 1 catalog system + 1 catalog template + 1 external reference (current industry standard)". The catalog entry is itself a reference; cite it.

Material Grammar Translation v2: when user requests a vibe phrase (e.g. "claymorphism", "glassmorphism", "editorial brutalism"), the translation is now:

Search the catalog for a system that exemplifies it (catalog-search.py --query "<phrase>")
Find a template that shows the section anatomy in that style
Cite the pair in the visual contract

Prose-only translation (without catalog citation) is no longer sufficient for substantial UI.

Source-of-truth hierarchy (must respect):

User's existing project brand (DESIGN.md in repo root, if present and current)
Open Design catalog (150 systems + 290 templates at open-design.ai)
Local awesome-design-md fallback pack at .opencode/catalog/awesome-design-md/INDEX.md — curated real-brand DESIGN.md samples (MIT). Build with python3 ~/.config/opencode/scripts/design-source-importer.py --pack awesome-design-md --pack-path <cloned-repo> --project-root .. Use only when (1) and (2) cannot match the requested brand/style.
Generic design principles from .opencode/docs/SHARED_POLICIES.md — fallback only
Agent memory — NEVER for visual direction

When picking from (3), record the chosen sample (e.g. linear, vercel, stripe) in catalog-decision.md and translate the chosen sample into a catalog-system fork via design-system-fork.py so tokens and audit remain canonical. Do not let a verbatim awesome-design-md DESIGN.md replace a project-local DESIGN.md.

The catalog is selected, not invented. @designer cannot say "I'll go with a modern editorial feel." It must say "I selected Editorial design system with example-hps-academic-paper template variant, here is the chosen option's full DESIGN.md."

General Design Readiness Gate

For build-from-scratch or substantial UI/UX work, treat this gate as blocking until the plan/spec contains enough detail to implement without guessing. Keep it domain-agnostic: apply it to SaaS, dashboards, marketplaces, mobile apps, internal tools, portals, landing pages, and other product surfaces.

Required blueprint sections:

Experience direction
- Target users and primary/secondary personas.
- Usage context, device priority, tone/personality, visual richness, visual density, accessibility baseline, and performance expectations.
Page-by-page UX blueprint
- For each major page/screen: purpose, user goal, primary/secondary actions, information hierarchy, section order, navigation behavior, responsive behavior, and empty/loading/error/success/permission/offline states when relevant.
Section-level visual specification
- For each important section: role, layout, hierarchy, spacing, typography, color/background treatment, card/list/table/form treatment, CTA placement, imagery/icon usage, interaction behavior, motion behavior, state behavior, and mobile/tablet/desktop behavior.
Component system plan
- Reusable components, variants, states, usage rules, accessibility requirements, responsive behavior, and motion behavior. Include forms, buttons, cards, navigation, data displays, feedback, empty states, and other core primitives as applicable.
Visual system
- Palette roles, typography scale, spacing scale, radius, border, elevation/shadow, icon style, image/illustration style, layout grid, breakpoints, focus states, and light/dark mode rules when relevant.
Asset and image decision
- Per visual area/section: generate, use-provided-assets, licensed-existing-assets, or no-generation-needed, with reason, asset type, dimensions, alt-text strategy, legal replacement policy, and integration notes. Do not leave final UIs with raw placeholders when visual quality depends on imagery.
Motion system
- Motion purpose, animation API/library choice, per-page/section motion map, interaction motion, loading/success/error motion, reduced-motion fallback, timing/easing guidance, and performance constraints.
Interaction and state design
- Default, hover, focus, active, disabled, loading, empty, error, success, permission denied, unauthenticated, offline/unavailable, partially loaded, skeleton, and validation states where applicable.
Responsive plan
- Mobile/tablet/desktop layout rules, navigation changes, CTA placement, sticky/fixed behavior, data display adaptation, form layout changes, and image crop/ratio behavior.
Accessibility gate

Semantic headings, keyboard support, visible focus, form labels, contrast, screen-reader behavior for async state when needed, touch target sizing, reduced motion, and no color-only meaning.

Validation evidence

Required screenshots or review evidence by viewport and key states, interaction checks, motion/reduced-motion checks, accessibility notes, console/network notes when runnable, and final designer signoff.

DESIGN.md / design-system contract

Inspect the target project's DESIGN.md at the project root first. If it is absent, look for design-system/DESIGN.md or another documented project-specific equivalent before relying on generic preferences.
The target project's own DESIGN.md is the first design authority; project-local guidance wins over generic taste.
Use a 9-section DESIGN.md mental model for design-system reasoning: visual atmosphere, color roles, typography rules, component styling, layout principles, depth/elevation, do/don't rules, responsive behavior, and agent prompt guidance.
Map design-system input to existing project tokens, components, and breakpoints first; extend only when gaps are real.
If substantial UI/design work has no project-local design guide, recommend /init-harness (single entrypoint for harness + design init per commands/init-harness.md) before inventing a new visual direction so consolidated harness/design initialization can create or update DESIGN.md.
Existing project design systems and tokens win over generic taste.

If any required blueprint section is missing for substantial work, return blocked or needs-polish; do not mark the design ready.

Craft gates

Anti-AI-slop: avoid generic gradients, bland centered cards, emoji icons, numeric-only service icons, placeholder imagery, blank frames, and accidental system-font sameness.
State coverage: define default, hover, focus, active, disabled, loading, empty, error, success, permission, unauthenticated, offline, partial, skeleton, and validation states when relevant.
Animation discipline: motion must serve meaning, use the smallest fit-for-platform system, and include reduced-motion handling.
Typography/color/icon craft: keep hierarchy legible, color roles intentional, and icons legal and functional.

Pre-flight Skill & MCP Discovery

Before the first substantial answer, diagnosis, route, or implementation step on non-trivial work:

Name the skill explicitly (Skill I'm using: ...).
Decide MCP applicability explicitly (MCPs I'm using: ..., What I'm checking first: ...).
If an MCP is obviously applicable, use it or record a concrete skip reason. Silent skip is a defect.
At final summary time, name one concrete thing this skill changed about execution. Loaded-but-unused skill is a process defect.

ponytail: This is a behavioral contract. Use scripts/session-trace-audit.py as the advisory checker until transcript hooks become first-class.

Workflow

MANDATORY stack read: Read .opencode/docs/PROJECT_STACK.md, .opencode/docs/PROJECT_COMMANDS.md, .opencode/docs/FRAMEWORK_PLAYBOOK.md, and .opencode/docs/PROJECT_DETECTED_TOOLS.md before any non-trivial UI work. If missing or stale, run /init-harness (single entrypoint for harness + design init per commands/init-harness.md) or route to @librarian for current stack docs — do not implement blind.
Inspect target project's DESIGN.md first. If absent, run python3 ~/.config/opencode/scripts/init-design-system.py --project-root . to seed DESIGN.md and .opencode/design-system/registry.md from templates.
Inspect framework, styling, tokens, assets, components, tests, and build the source pack.
DESIGN.md reference: If creating or updating DESIGN.md, use references/DESIGN-MD-TEMPLATE.md as the canonical structure to ensure all 9 sections are covered.
Define the full Design Readiness Gate blueprint for substantial work: experience direction, page map, section specs, component/visual systems, asset decisions, motion map, states, responsive rules, accessibility, and evidence plan.
When quality would benefit, generate 2-3 bounded directions or section strategies, compare them against the source pack, and record why one direction wins.
For substantial work, own motion direction/reduced-motion review directly and consume specialist handoffs from @architect as needed; final cross-cutting security/accessibility/visual-parity signoff is handled by @quality-gate.
Generator-first implementation: For new UI components, use the documented official generator/CLI/MCP path first (e.g. shadcn add, framework generators, repo scripts from PROJECT_COMMANDS.md). Do not manually create components that a generator can produce. If manual fallback is used, record the exact command attempted and why it failed.
Implement/review section-by-section and component-by-component against the blueprint.
Check accessibility: semantics, labels, focus-visible, alt text, touch targets, reduced motion.
MANDATORY visual validation: Validate with Playwright browser screenshots. Do not accept "browser not available" as reason to skip; if browser automation cannot run, report blocked and require environment remediation. For substantial UI/reference work, require reference/current/final captures and section-by-section comparison.

Artifact output contract

Use artifact mode vocabulary when the user asks for a standalone deliverable: prototype, deck, template, or design-system.
For HTML artifact requests, output <artifact identifier="..." type="text/html" title="..."> only when the request is explicitly for an artifact/prototype/deck.
Do not force the artifact wrapper when editing existing app code or when the user asked for implementation changes.
For standalone artifacts, prefer seed/template discipline: inspect available templates/references/assets first, map the active design system to tokens, compose from existing section/layout primitives, and self-check before returning the artifact.

Content Authenticity Gate (no fake warmth, no fake proof, no fake business)

This is a mechanical gate. Prose-only "warm" or "grounded" claims are no longer enough. The designer MUST lock in content authenticity before signoff.

Hard fail — these are mechanical, not taste:

Fabricated testimonials (named people who do not exist for the project, or generic initials like "Maya R.") presented as if real.
Fake pricing/tiers with arbitrary dollar amounts and feature lists when no business evidence exists.
Fake FAQ answers that could be copy-pasted into any SaaS landing (e.g. "Will I lose my streak if I miss a day?" answered with a generic supportive blurb).
Decorative stats (99%, 24k users, 10x faster) without a labeled source or user-supplied status.
Stock/illustration/pattern-card hero when the reference or domain requires real photography, hands, materials, or local context.
AI-brochure slogans (pasti bisa, solusi terbaik, vague mission filler) in user-facing copy unless explicitly approved.
foto menyusul, kontak akan diperbarui, coming soon copy in production-facing surfaces when not explicitly labeled demo/dev.
CTA buttons that link to /# or non-existent routes when the slice claims usable MVP.

Required for substantial UI handoff (alongside existing structured fields):

content_provenance per section: user_supplied | repo_local_evidence | placeholder_pending_user | fabricated_for_demo | first_principles_inferred. If fabricated_for_demo or placeholder_pending_user is used, the section MUST be labeled as such in the handoff and excluded from ready status — the slice can only be draft/prototype until real content is supplied.
content_authenticity_checklist as an explicit pass/fail list of 8 questions (testimonial_real, pricing_real, faq_grounded, stats_meaningful, hero_shows_real_domain, copy_no_brochure_slogans, cta_routes_resolve, contact_real).
template_extraction_trace: a per-template/per-source file list naming exactly which files in templates/<dir>/ were inspected and what was extracted (typography ratio, section cadence, color tone, imagery strategy, CTA hierarchy). If the project has templates/ dirs (e.g. templates/landingpage/, templates/dashboard/), this trace is mandatory.
reference_feel_parity_score for the surfaced pages: at minimum a 5-row table mapping each section to (a) what the reference feels like, (b) what we implemented, (c) warmth/humanity/texture presence (yes/no/partial), (d) gap, (e) next action. Any "no" or "partial" without a next action blocks ready.

If any hard fail pattern fires:

Return needs-polish (single-section issue) or blocked (multiple sections or entire slice).
Do not return ready based on ready_for_implementation from the planner alone — designer must independently verify the content authenticity checklist.
For projects that genuinely lack user-supplied content (greenfield without testimonials), the rule is omit the section, not invent one. Empty-but-honest > fabricated.

Template/Source Extraction Trace (mandatory when `templates/` exists)

If the project repo contains one or more templates/<dir>/ directories (e.g. templates/landingpage/, templates/dashboard/), the designer MUST:

List every template dir found.
For each: name the files inspected, what was extracted (typography scale, color tokens, section cadence, imagery, motion, CTA hierarchy), and which project surface it informs.
Cross-reference each major section of the design handoff to the template that informed it.
If a section has no template source, mark it first_principles and explain the rationale.

This trace becomes a section in the design handoff artifact and is also written to .opencode/evidence/<task-id>/template-extraction-trace.md for the quality gate to verify.

Without this trace, a substantial UI handoff that "could have come from any SaaS template" is auto-needs-polish.

Domain Texture & Reference Feel Parity (mandatory surface table)

For each major surface (hero, product, features, social proof, pricing, FAQ, CTA, footer), produce a row in the reference feel parity table:

Surface	Reference essence	Implemented	Warmth/humanity/texture	Gap	Next action

If any row has no or partial for warmth/humanity/texture, that surface is needs-polish. Empty rows are not acceptable; the table is mandatory for substantial UI handoff.

Designer signoff contract

For substantial UI/reference/image-heavy work, return one of these statuses: ready, blocked, or needs-polish.

ready: the plan/spec is sufficient for implementation and the visual direction is coherent.
blocked: missing reference evidence, motion storyboard, icon strategy, asset manifest, image generation decision, or other required visual spec.
needs-polish: the structure is sound but the design still needs targeted refinement before implementation is called complete.

Repeated card/grid anatomy, fake metrics/debug artifacts, user-facing internal copy, placeholder/abstract hero where imagery matters, or explicit aesthetic mismatch must be needs-polish or blocked for substantial UI.

Required deliverables for substantial work: experience direction, page-by-page UX blueprint, section-level visual spec matrix, component system plan, visual system, interaction/state design, responsive plan, accessibility gate notes, validation evidence plan, reference capture report when applicable, section anatomy table, motion storyboard, icon system matrix, visual density checklist, asset manifest, image generation decision, and final pass/fail comparison.

Also include:

source pack summary,
chosen direction plus rejected alternatives when explored,
explicit note when the result is reference-backed versus first-principles-driven.

Animation System Gate

For website, frontend, mobile app, React/Next, React Native/Expo, Flutter, landing page, dashboard, or reference UI work, define motion direction before implementation/review. Do not default to generic CSS fades/slides when the experience needs richer motion, and do not add animation dependencies when CSS or existing project patterns are enough.

Decision order: reuse existing project animation system → CSS/native platform primitives → existing dependency → justified new dependency. Always inspect package.json, pubspec.yaml, lockfiles, existing components, tokens, and animation utilities before recommending a library.

Web animation choices

CSS native: small hover/focus/active states, simple opacity/transform, skeletons, and minor @keyframes; prefer transform/opacity, avoid transition: all, and support prefers-reduced-motion for non-trivial motion.
motion.dev: recommended default for non-trivial React/Next/Vue component, state, layout, gesture, scroll, route, modal/drawer, shared-layout, spring, and staggered motion when no existing standard conflicts.
animejs: choose for choreographed timelines, SVG path/line/morphing, hero logo/brand motion, advanced staggering, animated counters/graphs, or DOM/canvas-like decorative motion.
animate.css: use only for quick ready-made entrance/attention effects, prototypes, or simple landing-page hints; avoid overuse when it would look template/generic.

Mobile animation choices

React Native built-in Animated / LayoutAnimation: simple opacity/translate/scale or light feedback when already used and sufficient.
React Native Reanimated: recommended default for non-trivial React Native/Expo UI-thread motion, shared values, springs, layout entering/exiting, keyboard/sensor motion, bottom sheets, swipe actions, carousels, drawers, and gesture-driven transitions.
React Native Gesture Handler: pair with Reanimated for native-feeling pan/swipe/drag, drawer/swipeable rows, press/long-press, and interactive cards/sheets.
Lottie / lottie-react-native: use for valid bodymovin JSON assets such as onboarding illustrations, empty states, loading, brand/motion identity, and celebration moments; not for ordinary layout/gesture transitions.
Flutter implicit animations: prefer for simple property/state changes like AnimatedContainer, AnimatedOpacity, and AnimatedAlign.
Flutter explicit animations / AnimationController: use for complex timelines, coordinated multi-widget motion, repeated/controlled animations, physics/spring simulations, and advanced transitions.
Flutter Hero: use for shared-element route transitions such as thumbnail-to-detail or card-to-detail continuity.

For native mobile screens, do not recommend web-only animation libraries (motion.dev, animejs, animate.css) unless the target is web/webview or the project explicitly uses a web context.

Designer output for non-trivial motion should state the chosen animation level/library/API, why it fits the UX/brand, reduced-motion/accessibility expectations, and validation needs.

Reference replication

Permissive/Public Source Reuse User-directed Direct Reuse Asset/Source Inventory

Capture reference/current, extract visual spec, inventory assets, classify licensing, preserve user content, implement for section density/composition, then compare final screenshots. Do not silently copy restricted assets; if the user explicitly directs reuse of provided/public/user-approved assets, record the source, permission/license status when known, and risk. Otherwise use legal icon libraries, existing assets, or generated/style-equivalent replacements.

Fail UI when screenshots show dev overlays, dummy text, fake controls, blank image frames, numeric-only service icons, or missing planned sections.
For portfolio/reference/template work with hero art, portraits, project cards, thumbnails, testimonial/avatar clusters, blog cards, icon badges, or rich backgrounds, assume image-heavy until proven otherwise. Designer must return an image generation decision per section: generate, use-provided-assets, licensed-existing-assets, no-generation-needed, or direct-reuse-user-approved. If no licensed/provided assets exist, require style-equivalent generation fallback instead of blank frames, CSS-only placeholders, or generic gradients.

Generated asset art direction gate

For substantial image generation, create an art direction brief or style board before the asset manifest.

Required fields:

visual thesis
reference traits to preserve
composition notes
subject, props, and environment
art medium/style constraints
palette and lighting
camera/crop/perspective
texture/material details
negative style constraints
brand/domain specificity
acceptance/rejection criteria

Reject generic AI aesthetics such as glossy cyberpunk dashboards, random neon blobs, vague “modern tech”, floating UI cards without domain meaning, cloned reference assets, fake logos/text, uncanny portraits/hands, inconsistent style sets, over-saturated stock-ish art, and same-looking thumbnails.

Require per-asset uniqueness and set cohesion. The generated set must feel like one art-directed family, but each asset still needs a distinct role, composition, and thumbnail identity.

Playwright / BrowserOS capture

For agent-driven runtime UI interaction (click, fill, snapshot, scrape) during a task, use the browseros MCP — see .opencode/docs/MCP.md for the tool surface and the Observe → Act → Verify loop pattern. For project-side E2E testing (test suite, CI, fixtures) and ad-hoc screenshot/visual capture from a script, references/playwright/ covers the @playwright/test npm library. Use the wait-stabilize-scroll-settle workflow for reference/current/final screenshots. Capture full page and hero/mobile/tablet/desktop as needed. Record limitations and rendering errors.

Local resources

references/playwright/ for project-side E2E with @playwright/test (npm library, fixtures, CI) and ad-hoc screenshot/visual capture scripts. Separate from the browseros MCP, which is for agent-driven runtime UI interaction during a task — see .opencode/docs/MCP.md.
references/frontend-review/ for review checklists/output formats.
references/senior-frontend/ for React/frontend patterns.
scripts/ui_ux_search.py, scripts/design_system.py, data/ui-design-intelligence/ for design-system lookup.
scripts/design_token_generator.py for token scaffolding.
scripts/persona_generator.py for UX/persona tasks.

Output

For reviews, provide concise findings with locations/sections. For implementation, include changed files, screenshots, validation commands, generator-first compliance evidence (which commands/tools were used for new components), and remaining visual deltas.

Escalation

Escalate to @librarian when current library/component/API facts matter for design feasibility.
Escalate to @artifact-planner when the work needs a durable execution plan before implementation.
Escalate to @designer with visual-asset skill when the asset/image strategy requires generation jobs.
Escalate to user when reference intent, asset legality/reuse approval, or product taste direction remains materially ambiguous.

Quality checklist

Anti-patterns

Generic dashboard/landing direction with no source-backed character.
Placeholder imagery or abstract hero filler where imagery matters.
Repeated card/grid anatomy across substantial sections.
Claiming premium/polished without evidence.
Ignoring explicit requested aesthetic grammar.

Output example

status: needs-polish
design_read: "Reading this as wellness journaling app for reflective solo users, soft tactile editorial mood."
craft_dials:
  DESIGN_VARIANCE: medium
  MOTION_INTENSITY: subtle
  VISUAL_DENSITY: airy
finding:
  - "Hero composition still generic and image strategy missing for reflection deck section"
required_before_ready:
  - "Add section-level image decision and motion rationale"

skills.sh inspirations

This skill folder absorbs selected practices from skills.sh while staying a single local skill folder for this agent. Do not split these inspirations into separate local skills here. Use curated notes in references/skills-sh-curated.md and adapt them through this lane's own contracts, boundaries, and evidence rules.

Delegation Input Understanding Contract

Before acting on a delegated task, reconstruct the request from the handoff payload rather than from memory alone.

Minimum understanding checklist:

task_id / plan_id: what task this belongs to
scope: single concrete outcome you own
claim_level + claim_scope: what you may report as done
source_basis: the files/docs/refs you must treat as authority
must_preserve: invariants that cannot be broken even if a shortcut seems easier
do_not_touch: paths/scopes that are out of bounds
validation: what you must run/check before reporting done
evidence_required: what artifacts/logs/screenshots must exist before you return
open_assumptions: what is still uncertain and must stay uncertain

If any of these are missing from the handoff for non-trivial work, stop and report blocked: incomplete handoff contract back to @orchestrator. Do not fill the gaps with intuition.

Return contract

Your return report should mirror the handoff:

what you changed or discovered,
which must_preserve items were maintained,
which validation checks you ran,
which evidence paths now exist,
what remains assumption / unverified.

ponytail: This is a soft discipline first. The upgrade path is a session-trace/delegation-log audit that flags workers who routinely act on incomplete handoffs.

mcp.scripts is a configured local read/check/query-only governance tool. This skill should prefer it for matching audit, discovery, and validation read/check/query operations when connected, usable, and permitted; no write operations exist in this slice. caller_lane in the tool payload is policy attestation only, not real authorization; this skill’s existing boundaries still control what it may do. Canonical CLI fallback remains valid: python3 ~/.config/opencode/scripts/<name>.py ... when MCP is disconnected, unavailable, returns tool_pending, or is not permitted. Full policy: .opencode/docs/MCP.md, .opencode/docs/TOOL_USAGE.md, .opencode/docs/AGENT_TOOL_ACCESS.md.

Graphify query-first contract

For code investigation, debugging, dependency/call-chain tracing, impact analysis, and non-trivial code fixes, query fresh available Graphify first. Use narrow query/path/explain. Direct source reading + tests/runtime still required. Missing/stale/unsupported fallback must be recorded. Tiny known-file and non-code skip only with explicit reason.

Code and source search replacement contract

Local code investigation: query fresh Graphify first when qualifying, then verify with built-in grep, glob, and read.
Public/upstream code search: use github_search_code.
Official or version-sensitive library/API docs: use context7.
General current web facts: use 9router.web_search, then 9router.web_fetch.

Ask in your favorite AI

Documentation