design2spec

name	design2spec
description	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.
metadata	{"author":"kundeng","version":"1.0.0"}

Design-to-Spec Handoff

Convert a reference UI design into an implementation-ready specification package that a downstream coding agent or developer can implement with minimal ambiguity.

Why this skill exists

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.

Core workflow

1. 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.

2. 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.

3. Discover platform constraints — this is the step generic tools skip. Identify what the target platform forbids, requires, or changes:

   • Chrome extensions: manifest v3 schema, CSP restrictions (no inline scripts, no eval), background service worker limitations, popup size constraints, message passing patterns
   • Splunk dashboards: SplunkUI component library requirements, dashboard framework SDK, search job patterns, token-based data binding
   • Tauri apps: webview restrictions, Rust↔JS IPC bridge (invoke/listen), allowed filesystem APIs, window management, no Node.js runtime
   • Electron: main/renderer process split, preload script requirements, context isolation, IPC channels
   • VS Code extensions: webview API (postMessage only), no direct DOM access from extension host, contribution points schema
   • React Native: no DOM, native module bridge, platform-specific components (iOS/Android), no CSS grid
   • Standard web apps: still valuable — surfaces SSR/CSR decisions, hydration boundaries, API route patterns

   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.

4. Decide starter-pack strategy — derive from the project, not from a fixed default:

   • Existing codebase → extend current conventions
   • Codebase has design system/tokens/primitives → build spec around those
   • Codebase missing usable foundation → recommend minimum additions
   • Clean-slate → recommend starter pack appropriate to platform/goals, emitted as spec (not code)

5. Emit the handoff spec — produce the structured JSONC package (see schema below).

6. 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.

Operating modes

Mode A: Existing project / retrofit

Use when the user has an existing repo and wants to add or restyle a screen, flow, or module.

• Inspect existing conventions first
• Emit spec aligned to current architecture
• Recommend only incremental changes
• Do not propose a new stack unless the existing one is clearly unsuitable

Mode B: Clean-slate / greenfield

Use when no codebase exists and the user wants a new project scaffold recommendation.

• Recommend an appropriate starter pack based on product/platform
• Emit the recommendation as structured spec, not code
• Do not overfit to a single framework unless the project context supports it

Output format

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.

Output priority

Optimize in this order:

1. Downstream implementability — a coding agent can build from this spec without major ambiguity
2. Compatibility with existing codebase conventions
3. Platform constraint compliance — the spec must not produce code that violates platform rules
4. Design fidelity
5. Maintainability
6. Themeability
7. Verification readiness

Default JSONC schema

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": []
    }
  ]
}

What NOT to do

• Do not generate implementation code — this skill's job is the spec, not the build. The spec is a checkpoint that prevents committing to code before constraints are understood.
• Do not force a new stack when adapting an existing codebase is more appropriate.
• Do not hide inferred decisions — mark them with JSONC comments so downstream consumers can validate or override.
• Do not skip platform constraint discovery for specialized targets. A spec that ignores Chrome CSP rules or Splunk SDK requirements will produce code that looks right but fails at runtime.
• Do not overfit to a single framework unless the project context supports it.