Convert UI designs into structured JSONC spec packages before code is written, especially for constrained platforms like extensions, dashboards, desktop shells, and mobile apps. Use for design handoff and design-to-spec workflows. Outputs specs, not implementation code.
Convert a reference UI design into an implementation-ready specification package that a downstream coding agent or developer can implement with minimal ambiguity.
Design-to-code is lossy, and the losses compound on specialized platforms. A coding agent looking at a mockup will reach for familiar patterns — but those patterns break when the target is a Chrome extension (CSP blocks inline scripts), a Splunk dashboard (must use SplunkUI components), or a Tauri app (UI runs in a webview with Rust IPC). This skill sits between "here's what it should look like" and "go build it." It forces a structured analysis that surfaces platform constraints, flags architectural decisions, and prevents committing to code before the constraints are understood.
The structured JSONC output works as a discipline gate: the coding agent gets a spec with explicit platform rules, component mappings, and acceptance criteria rather than improvising from a screenshot.
Analyze the design input — accept images, screenshots, URLs, mockups, or natural-language descriptions. Extract layout, components, color system, typography, spacing, interaction cues, responsive assumptions, and accessibility implications.
Inspect project context — if the user provides a codebase or project, infer: framework, component library, styling system, theme/token strategy, routing, build conventions, and existing design-system patterns. Classify as greenfield, retrofit, or extension.
Discover platform constraints — this is the step generic tools skip. Identify what the target platform forbids, requires, or changes:
If the platform has constraints, populate the platformConstraints section in the output. This section is what prevents the downstream coding agent from generating code that looks right but can't run.
Decide starter-pack strategy — derive from the project, not from a fixed default:
Emit the handoff spec — produce the structured JSONC package (see schema below).
Conform to downstream contracts — if another spec-driven dev skill exists in the system, detect its schema and conform output to it instead of inventing a new one.
Use when the user has an existing repo and wants to add or restyle a screen, flow, or module.
Use when no codebase exists and the user wants a new project scaffold recommendation.
Default to JSONC. The inline comments serve a specific purpose: they mark inferred decisions and rationale so the downstream agent (or human) can validate assumptions before committing to code. If a downstream skill contract exists, conform to that format instead.
Optimize in this order:
Return these sections in order:
{
// High-level context about the request and confidence
"specMetadata": {
"mode": "retrofit | greenfield",
"platform": "web | chrome-extension | splunk-dashboard | tauri | electron | vscode-extension | react-native | other",
"outputFormat": "jsonc",
"confidence": "high | medium | low",
"downstreamContract": "system-standard | custom | none",
"notes": []
},
// Starter-pack choice derived from project/codebase context
"starterPackDecision": {
"strategy": "reuse-existing | extend-existing | recommend-new-foundation",
"detectedStack": {
"framework": "",
"uiLibrary": "",
"styling": "",
"themeSystem": "",
"routing": "",
"buildSystem": ""
},
"recommendedFoundation": {
"runtime": "",
"framework": "",
"uiSystem": "",
"styling": "",
"reasoning": []
},
"adaptationNotes": []
},
// Platform-specific constraints that downstream code MUST respect.
// Omit this section entirely for standard web apps with no special constraints.
"platformConstraints": {
"platform": "chrome-extension | splunk-dashboard | tauri | electron | vscode-extension | react-native | other",
"hardRules": [
// Things that will cause build/runtime failure if violated.
// e.g., "No inline scripts — Chrome extension CSP blocks them"
// e.g., "Must use SplunkUI <Table> component, not custom HTML tables"
// e.g., "No Node.js APIs — Tauri webview has no require/process"
],
"sdkRequirements": [
// Required SDK components, APIs, or patterns.
// e.g., "Use chrome.runtime.sendMessage for background communication"
// e.g., "Use @splunk/react-ui for all UI components"
// e.g., "Use Tauri invoke() for all Rust backend calls"
],
"manifestOrConfig": {
// Platform-specific config the project needs.
// e.g., Chrome: { "manifest_version": 3, "permissions": [...] }
// e.g., Tauri: { "allowlist": { "fs": { "scope": [...] } } }
},
"forbiddenPatterns": [
// Common web patterns that break on this platform.
// e.g., "No localStorage in service workers (Chrome MV3)"
// e.g., "No window.fetch in Electron main process"
// e.g., "No CSS grid in React Native"
],
"notes": []
},
// Structured design description derived from image/mockup/app context
"designBrief": {
"productContext": {
"appType": "",
"screenName": "",
"primaryUserGoal": "",
"primaryActions": []
},
"layout": {
"shell": "",
"regions": [],
"hierarchy": [],
"responsiveReflow": []
},
"components": [
{
"name": "",
"role": "",
"variants": [],
"states": [],
"notes": []
}
],
"designSystem": {
"colorRoles": {
"primary": "",
"secondary": "",
"background": "",
"surface": "",
"text": "",
"muted": "",
"success": "",
"warning": "",
"danger": ""
},
"typography": {
"style": "",
"scale": {}
},
"spacing": {},
"radius": {},
"shadow": {},
"motion": []
},
"contentModel": {
"dataEntities": [],
"mockDataNeeded": true
},
"accessibility": {
"contrastNotes": [],
"keyboardNotes": [],
"semanticNotes": []
},
"inferred": []
},
// Implementation-oriented brief for downstream coding agent
"developerBrief": {
"goal": "",
"implementationConstraints": [],
"architectureNotes": [],
"themeNotes": [],
"riskNotes": []
},
// Maps design to implementation touchpoints
"adaptationOrFilePlan": {
"domains": [],
"filesOrModules": [
{
"pathOrArea": "",
"purpose": "",
"changeType": "create | update | verify"
}
]
},
// What downstream coding agent must satisfy
"acceptanceCriteria": [],
// Notes for downstream implementation
"handoffNotes": {
"preferredNextStep": "implement-spec",
"downstreamSkillHints": [],
"unknowns": [],
"assumptionsSafeToProceed": []
},
// Verification hooks for coding or QA skill
"verificationChecklist": [
{
"name": "design-fidelity",
"checks": []
},
{
"name": "responsiveness",
"checks": []
},
{
"name": "theme-integrity",
"checks": []
},
{
"name": "platform-compliance",
// Only when platformConstraints section is present.
// Verify that hardRules and forbiddenPatterns are not violated.
"checks": []
},
{
"name": "maintainability",
"checks": []
}
]
}