sdcorejs-design

name	sdcorejs-design
description	Design-track executor for FE handoff artifacts. Use for UI/UX design, mobile app/mobile web design, wireframes, mockups, screen flows, PNG previews, design from product stories, or design review before frontend implementation. Writes design/ specs/flows/wireframes/exports and .sdcorejs/docs/design/ traceability; no production code. Runtime-localized.

Codex path resolution: Resolve ../_refs/... relative to this SKILL.md. Resolve another SDCoreJS skill by opening the sibling folder ../<skill-name>/SKILL.md.

Design Track

Shared Protocols

Before executing this skill:

1. Read and apply ../_refs/shared/tasklist.md for non-trivial execution tasks.
2. Read and apply ../_refs/shared/persona.md if a project persona exists.
3. Read and apply ../_refs/shared/project-context.md for project memory, resume checkpoints, summaries, specs/plans, tasks, and relevant memories.
4. Current user request, current files, diffs, logs, failing tests, and command output override stored context.
5. Before presenting user-facing choices, approval gates, yes/no questions, or mode selections, read and apply ../_refs/shared/user-choice-prompt.md so options are presented as sequential numbered choices.

Purpose

Create FE handoff artifacts from product intent. The output should let Angular/Next.js executors implement screens without guessing layout, states, copy, interactions, or responsive behavior.

PNG generation is feasible, but a PNG alone is not a reliable source of truth. For exact FE implementation, always pair PNG previews with editable design artifacts and a written handoff spec.

Before designing UI from PRDs, user stories, acceptance criteria, or rough feature briefs, read ../_refs/design/frontend-design.md. Use it to create a compact visual direction, token plan, signature element, copy voice, and self-critique before writing final design specs or wireframes.

When the target surface is a mobile app, PWA, responsive mobile web experience, or explicitly mobile-first screen/flow, also read ../_refs/design/mobile-design.md. Use it to add mobile context, platform fit, touch ergonomics, navigation, mobile state coverage, and implementation governance to the handoff.

Step 0 - Context preflight

Before mapping stories to screens, run sdcorejs-explore (summary-read) through ../_refs/shared/project-context.md.

• For an existing app/site, ensure <target>/.sdcorejs/summary.md exists or is refreshed with summary-refresh only in write-approved design execution context so the design uses the real route structure, modules, component conventions, permissions, and target stack.
• For greenfield design before any app scaffold exists, continue from product docs and approved specs/plans, but mark UI component choices as candidate until the frontend/backend summary exists.
• If the summary conflicts with product stories, acceptance criteria, or current user attachments, surface the conflict instead of silently choosing one source.

Existing Design First

Before inventing a visual direction, inspect the project's existing interface and treat it as the primary design source of truth for both new UI inside an existing project and redesign work. Reuse established components, design tokens, CSS variables, Tailwind/theme settings, typography scale, color palette, spacing/radius/shadow conventions, icon and illustration style, layout patterns, existing pages/screens, accessibility conventions, and interaction patterns wherever they exist.

Only fall back to inferred design direction when the codebase or brief does not provide enough design evidence. When inference is necessary, state the assumption, keep it compatible with the surrounding product context, and avoid introducing new fonts, external assets, icon packs, motion libraries, color systems, visual dependencies, or a parallel design system without explicit brief or project-owner approval.

Inputs

Load what exists, in this order:

1. product/prds/<feature>.md
2. product/user-stories/<feature>.md
3. product/acceptance-criteria/<feature>.md
4. product/uat-checklists/<feature>.md
5. Approved specs/plans from .sdcorejs/specs/ and .sdcorejs/plans/
6. Existing design docs under design/
7. Existing frontend conventions from frontend/ or ../_refs/angular/ / ../_refs/nextjs/ when the target stack is known
8. Frontend design guidance from ../_refs/design/frontend-design.md when the work includes UI layout, visual direction, copy, or frontend handoff
9. Mobile design guidance from ../_refs/design/mobile-design.md when the target surface includes a mobile app, PWA, responsive mobile web, or mobile-first flow

If product stories or acceptance criteria are missing, write only an exploratory design draft and mark requirements as inferred - needs confirmation.

Output Paths

For a feature:

<target-project>/design/
  flows/<kebab-feature>.md
  specs/<kebab-feature>.md
  wireframes/<kebab-feature>/<screen>.html
  wireframes/<kebab-feature>/<screen>.svg
  exports/png/<kebab-feature>/<screen>.png
  decisions/<kebab-feature>.md

<target-project>/.sdcorejs/docs/design/<YYYY-MM-DD-HH-mm>-<kebab-feature>.md

Use whichever editable wireframe source best fits the target:

• html for implementation-ready FE handoff and screenshot-to-PNG.
• svg for static wireframes that need no runtime.
• PNG export only after a renderer actually produces the file.

Workflow

0. Create the frontend design plan

When the request includes UI design, design review, wireframes, mockups, or a frontend handoff from product artifacts, read ../_refs/design/frontend-design.md before mapping screens.

Write a compact design plan and critique into design/decisions/<kebab-feature>.md, then summarize the confirmed parts in design/specs/<kebab-feature>.md. The plan must cover:

• subject, audience, and single job
• visual direction and product-specific rationale
• 4-6 token colors with roles
• type roles or available system stacks
• desktop/tablet/mobile layout concept
• one signature element and why it fits
• copy voice for actions, empty states, and errors
• self-critique and revision when the first idea is too generic

For Core UI portals, keep the direction compatible with the existing shell, utility classes, component library, and operational density. Distinctive portal design should improve recognition, scanning, and task flow; it must not replace the app shell with a marketing layout.

When the target is mobile, also read ../_refs/design/mobile-design.md and add a mobile design plan to design/decisions/<kebab-feature>.md. The mobile plan must cover target surface, mobile context of use, navigation model, primary action placement, touch/gesture/keyboard/safe-area notes, mobile state coverage, dynamic type or zoom behavior, reduced motion, and no-new-dependency fallbacks for candidate assets or interaction libraries.

1. Map stories to screens

Create a screen map:

User Story	Screen	State	Primary Action	Notes
US1	Class list	empty / loading / data / error	Create class

Cover at minimum:

• entry screen
• create/edit/detail states
• empty/loading/error/permission-denied states
• mobile-specific offline, poor-network, permission-denied, interrupted, backgrounded/resumed, dynamic-type/zoom, and small/large phone states when the target surface is mobile
• mobile and desktop behavior when the feature is user-facing
• UAT scenarios that need visual confirmation

2. Write the design spec

Write design/specs/<feature>.md:

# Design Spec - <Feature>

## Source
- PRD:
- User stories:
- Acceptance criteria:

## Screens
| Screen | Route | Purpose | User Stories | Acceptance Criteria |
|---|---|---|---|---|

## Layout
<screen-by-screen structure, hierarchy, key controls>

## Frontend Design Plan
<visual direction, token roles, type roles, signature element, copy voice, and critique summary from design/decisions>

## Mobile Design Plan
<target surface, mobile context, navigation, reachability, safe-area/keyboard, gesture alternatives, mobile states, and platform notes when relevant>

## Components
| Need | Preferred component | Notes |
|---|---|---|

## States
| Screen | State | Behavior |
|---|---|---|

## Copy
<labels, buttons, empty states, validation messages>

## Responsive Rules
<desktop/tablet/mobile notes; include safe-area, keyboard, touch target, reachability, small/large phone, dynamic type/zoom, and reduced-motion notes when mobile applies>

## Accessibility
<keyboard order, labels, contrast, focus, error messaging>

## Open Questions

For SDCoreJS Angular, prefer Core UI components and name expected components in the spec. If the Core UI fit is unknown, say candidate instead of inventing an API.

3. Produce editable wireframes

Write one HTML or SVG per important screen/state. Keep them plain and implementation-oriented:

• use realistic product labels from user stories
• show important tables/forms/actions
• reflect the confirmed frontend design plan, including token roles, type hierarchy, signature element, copy voice, and interaction states
• reflect the confirmed mobile design plan when relevant, including safe areas, keyboard space, reachable primary actions, gesture alternatives, and interruption/offline/permission states
• include stable dimensions for desktop and mobile frames
• avoid decorative marketing art for operational tools
• include data-story, data-ac, or comments that link the wireframe section back to product IDs

4. Export PNG when requested or useful

Preferred PNG pipeline:

1. Render the HTML/SVG wireframe locally.
2. Screenshot/export to design/exports/png/<feature>/<screen>.png.
3. Verify the file exists and is non-empty.
4. Link the PNG from the design spec and .sdcorejs/docs/design/ ledger.

Use project tooling if available. If Playwright or another browser renderer is already installed, use it. If no renderer is available, apply ../_refs/shared/user-choice-prompt.md before adding dependencies: 1. Add renderer dependency / 2. Leave PNG export pending.

If an image-generation tool is available and the user explicitly wants high-fidelity visual concepts, it can create concept PNGs. Treat those as mood/reference only. Do not rely on AI-raster text for exact labels, tables, or form fields; exact UI text belongs in the design spec and editable wireframe source.

5. Write the design ledger

Write .sdcorejs/docs/design/<timestamp>-<feature>.md:

---
feature: <kebab-feature>
status: draft | reviewed | approved | partial
sourceUserStories: <path>
sourceAcceptanceCriteria: <path>
updatedAt: <ISO-8601 timestamp>
---

# Design Ledger - <Feature>

## Outputs
- Spec:
- Wireframes:
- PNG exports:

## Traceability
| User Story | Acceptance Criteria | Design Artifact | Status |
|---|---|---|---|

## FE Handoff Notes
- <implementation notes for frontend track>
- Frontend design plan:
- Mobile design plan:
- Confirmed token/component/copy decisions:
- Inferred or open visual decisions:

## Open Questions
- <question or None>

Rules

Must Do

• Preserve the user's language for user-facing labels and copy.
• Keep identifiers, route paths, permission codes, and component names in English.
• Link every screen to user story and acceptance criterion IDs when available.
• Read and apply ../_refs/design/frontend-design.md before producing UI handoff artifacts from PRDs or user stories.
• Read and apply ../_refs/design/mobile-design.md before producing mobile app, PWA, responsive mobile web, or mobile-first handoff artifacts.
• Record the frontend design plan, token roles, signature element, and critique in design/decisions/<feature>.md.
• Record the mobile design plan, target surface, ergonomics, mobile state coverage, platform notes, and implementation-governance constraints in design/decisions/<feature>.md when mobile applies.
• Produce editable design source before PNG export.
• Verify PNG files exist before claiming they were generated.
• Mark inferred design decisions clearly when product inputs are incomplete.
• Keep design docs in the target project, never in sdcorejs-agent unless that repo is explicitly the target.

Must Not

• Generate production FE code; hand off to sdcorejs-angular or sdcorejs-nextjs for implementation.
• Treat a PNG as the only handoff artifact.
• Use AI-generated raster text as authoritative UI copy.
• Invent product requirements to make a design look complete.
• Add new rendering dependencies without user approval.
• Claim a design is approved without explicit user approval.

Cross-references

• sdcorejs-product - source of PRDs, user stories, acceptance criteria, and UAT.
• ../_refs/design/frontend-design.md - visual direction, token plan, copy voice, and self-critique guidance for UI handoff.
• ../_refs/design/mobile-design.md - mobile-first context, platform, ergonomics, state coverage, and implementation-governance guidance.
• sdcorejs-execute-plan - routes approved design plans here.
• sdcorejs-parallel-dispatch - can run Design as one role in full-stack role split.
• sdcorejs-angular / sdcorejs-nextjs - consume design specs and wireframes during FE implementation.
• sdcorejs-test - maps UAT/e2e coverage back to designed flows.