Sdcorejs design

<!-- claude-adapter: generated from required-actions; do not edit mirror by hand -->

Design Track

Shared Protocols

Read _refs/shared/runtime-protocols.md and _refs/shared/artifact-lifecycle.md; load _refs/shared/design-handoff.md for durable handoffs. Consume canonical track/profile and artifact values from _refs/shared/system-registry.json, canonical artifact roots from _refs/shared/artifact-paths.mjs, verify approved spec/plan parents with _refs/shared/approved-artifact.mjs, and resolve semantic ownership with _refs/shared/repository-contract.mjs. Emit artifact_context for every design artifact and ledger written. Never rebuild a Design path by hand.

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.

Design does not write production code, replace a spec/plan, mutate an approved artifact, invent behavior outside approved requirements, or create module code.

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.

For frontend handoff, also read _refs/shared/frontend-architecture.md. Use repository evidence to produce an implementation-oriented component/data/ interaction map. Design may propose candidate boundaries, but it must not claim exact code paths, providers, or public exports are confirmed when the target codebase has not been inspected.

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, assemble read-only project_context.

• For an existing app/site, use valid summary sections when present. Missing or stale summary does not block design; continue with targeted reads or a scoped code map. Do not refresh merely because design execution is write-approved.
• For greenfield design before any app scaffold exists, continue from product docs and approved specs/plans, but mark UI component choices as candidate until frontend/backend source evidence 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. .sdcorejs/product/prds/<feature>.md
2. .sdcorejs/product/user-stories/<feature>.md
3. .sdcorejs/product/acceptance-criteria/<feature>.md
4. .sdcorejs/product/uat-checklists/<feature>.md
5. Approved specs/plans from .sdcorejs/specs/ and .sdcorejs/plans/
6. Existing design docs under .sdcorejs/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
10. Legacy root-level product/ or design/ documents only as a read-only compatibility fallback when no canonical .sdcorejs equivalent exists. See Legacy Layout Compatibility.

Resolve every Design read through resolveDesignArtifactSources in _refs/shared/design-handoff.mjs so canonical locations always win and a legacy fallback is explicit.

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

Output Paths

Resolve experience_scope and the semantic owner before any output path:

• module design belongs in the module repository; an unavailable/unwritable owner blocks and portal fallback is forbidden.
• portal-shell and portal-composition belong in the portal repository.
• cross-module belongs to one explicit portal/integration owner and references module handoffs using immutable repository/artifact/path/revision/hash identities. Never duplicate an editable module handoff.

Obtain the complete path bundle from resolveDesignHandoffTarget in _refs/shared/design-handoff.mjs. For a feature in the resolved owner:

<semantic-owner-repository>/.sdcorejs/design/
  flows/<kebab-feature>.md
  specs/<kebab-feature>.md
  decisions/<kebab-feature>.md
  wireframes/<kebab-feature>/<screen>.html
  wireframes/<kebab-feature>/<screen>.svg
  exports/png/<kebab-feature>/<screen>.png
  references/<kebab-feature>/<screen>.png

<semantic-owner-repository>/.sdcorejs/docs/design/<kebab-feature>.md

Root-level design/** is never a write target. It is a read-only compatibility input only.

Path roles:

Artifact	Canonical location
Frontend design plan and critique	.sdcorejs/design/decisions/<feature>.md
Mobile design plan	.sdcorejs/design/decisions/<feature>.md
Screen flow	.sdcorejs/design/flows/<feature>.md
Handoff spec	.sdcorejs/design/specs/<feature>.md
Editable wireframe source	.sdcorejs/design/wireframes/<feature>/<screen>.html or .svg
Generated PNG export	.sdcorejs/design/exports/png/<feature>/<screen>.png
Real product screenshot reference	.sdcorejs/design/references/<feature>/<screen>.png
Design ledger	.sdcorejs/docs/design/<feature>.md
Generated diagnostic or failure capture	.sdcorejs/design/diagnostics/**, always local_only

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 .sdcorejs/design/decisions/<kebab-feature>.md, then summarize the confirmed parts in .sdcorejs/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
• implementation component map covering route/page, feature-local, existing shared/design-system, and interactive-island candidates
• data and interaction map covering inputs, events, data source, and loading/ error ownership

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 .sdcorejs/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 .sdcorejs/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 .sdcorejs/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 |
|---|---|---|

## Implementation Component Map
| UI region | Component | Classification | Existing path/candidate | State owner | Status |
|---|---|---|---|---|---|

Use `confirmed`, `candidate`, `unknown`, or `new`. Mark paths `candidate` or
`unknown` unless repository evidence supports them.

## Data and Interaction Map
| Component | Receives | Emits | Data source | Loading/error owner | Status |
|---|---|---|---|---|---|

## 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 into .sdcorejs/design/wireframes/<feature>/<screen>.html or .svg. 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 .sdcorejs/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.

Classify generated static images as generated-mockup or illustration and bind them to the editable-source artifact hash. A real application capture is real-product-screenshot, is stored under .sdcorejs/design/references/<feature>/<screen>.png, and must carry repository ID, source/app revisions, capture evidence ID/timestamp, and content hash. Never present a generated image as a real product screenshot.

Durable PNG files participate in artifact closure as opaque bytes. They are classified from their canonical path, runtime artifact_context, the Design ledger relationship for the same feature, their content hash, and their declared provenance. They are never parsed as Markdown, scanned as UTF-8 text, or printed. Failure captures, traces, videos, auth/storage state, caches, and temporary renderer output stay local_only; put them under .sdcorejs/design/diagnostics/**.

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.

If the target editable surface is unavailable, record the concrete limitation, leave the editable-source result blocked/limited, and do not claim editable source pass. A PNG alone never satisfies the handoff.

5. Write the design ledger

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

---
schema_version: 1
artifact_id: design-handoff:<feature>
artifact_kind: design-handoff
contract_id: <approved contract id>
requirement_id: <requirement id>
change_ref: <change id>
track: design
stack_profile: design
experience_scope: module | portal-shell | portal-composition | cross-module
owner_repository_id: <stable repository id>
owner_repository_role: module | portal
owner_module_id: <module id | null>
ownership_scope: module | portal-composition | cross-repository-aggregate
repository_relative_path: .sdcorejs/design/specs/<feature>.md
source_revision: <40-character Git revision>
parent_references: [<approved spec ref>, <approved plan ref>]
supersedes: <artifact id | null>
approval_hash: <sha256:v1 hash when applicable | null>
artifact_hash: <sha256:v1 hash from design-handoff.mjs>
source_spec: <repo-relative path | none>
source_plan: <repo-relative path | none>
commit_policy: with-change
owner: sdcorejs-design
feature: <kebab-feature>
status: draft | reviewed | approved | partial
sourceUserStories: .sdcorejs/product/user-stories/<feature>.md
sourceAcceptanceCriteria: .sdcorejs/product/acceptance-criteria/<feature>.md
updatedAt: <ISO-8601 timestamp>
editable_source_status: available | unavailable
---

# Design Ledger - <Feature>

## Outputs
- Flow: .sdcorejs/design/flows/<feature>.md
- Spec: .sdcorejs/design/specs/<feature>.md
- Decisions: .sdcorejs/design/decisions/<feature>.md
- Wireframes: .sdcorejs/design/wireframes/<feature>/<screen>.html
- PNG exports: .sdcorejs/design/exports/png/<feature>/<screen>.png
- Product screenshot references: .sdcorejs/design/references/<feature>/<screen>.png

## 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>

Emit this ledger plus every created or updated spec, flow, decision log, editable wireframe, durable export, and approved screenshot reference in artifact_context.required_with_change. Build that block with buildDesignArtifactContext:

Every .sdcorejs/design/** document, wireframe, export, and reference plus the .sdcorejs/docs/design/<feature>.md ledger belongs in required_with_change with kind: design-asset or kind: design-handoff. Generated diagnostics under .sdcorejs/design/diagnostics/** stay local_only. Emitting only the ledger is a contract violation.

Legacy Layout Compatibility

Older target projects keep Design artifacts in a root-level design/** directory. That layout is a read-only compatibility input; it is never a write target.

1. New writes always use .sdcorejs/design/**.
2. Canonical paths are preferred for reads; a legacy path is read only when no canonical equivalent exists, and never duplicated into a silent second copy.
3. Updating a legacy-only artifact migrates that feature bundle to .sdcorejs/design/** in the same approved change and updates every internal reference. Unrelated historical artifacts are never bulk-migrated.
4. Equivalent canonical/legacy copies retire the legacy copy; conflicting copies block, and competing Design sources are never silently merged.
5. Portal fallback stays forbidden, and ownership, artifact identity, source revisions, approval hashes, artifact hashes, image provenance, and supersedes semantics survive the move.
6. A legacy path is never valid in newly generated metadata; validateDesignHandoff rejects it with LEGACY_DESIGN_ARTIFACT_PATH.

The full matrix lives in _refs/shared/design-handoff.md.

Use planDesignArtifactMigration in _refs/shared/design-handoff.mjs. It returns not-required, migration-required, or blocked plus the exact migrations, retirements, conflicts, and blockers.

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/shared/frontend-architecture.md for frontend handoff; include the implementation component map and data/interaction map without overstating unsupported code-level details.
• 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 .sdcorejs/design/decisions/<feature>.md.
• Record the mobile design plan, target surface, ergonomics, mobile state coverage, platform notes, and implementation-governance constraints in .sdcorejs/design/decisions/<feature>.md when mobile applies.
• Produce editable design source before PNG export.
• Validate editable source, static visual classification, real screenshot provenance, responsive coverage, evidence-aware component mapping, existing design-system reuse, and cross-repository references through _refs/shared/design-handoff.mjs.
• Preserve approved spec/plan identities and hashes as parent references.
• 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.
• Write every Design artifact under .sdcorejs/design/** and every ledger under .sdcorejs/docs/design/**.
• Resolve paths through resolveDesignHandoffTarget; never hardcode a Design root in prose, metadata, or output.
• Report canonical paths in every handoff report, ledger link, and final response, including any legacy compatibility read that was used.

Must Not

• Generate production FE code; hand off to sdcorejs-angular or sdcorejs-nextjs for implementation.
• Create or update a root-level design/** path.
• Emit a root-level design/** path in new or updated metadata, reports, or links.
• Keep an editable legacy copy alongside an equivalent canonical copy.
• Silently merge conflicting canonical and legacy Design sources.
• Treat a generated diagnostic, failure capture, trace, or video as a durable handoff artifact.
• Bypass the approved spec/plan, mutate approved artifacts, or expand implementation authority.
• Write a module handoff into the portal or duplicate an editable cross-repo handoff.
• 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.
• Mark an exact implementation path, provider scope, or public export as confirmed when repository evidence is absent.
• 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 under .sdcorejs/product/**.
• _refs/shared/artifact-paths.mjs - single canonical source for Product and Design roots.
• _refs/design/frontend-design.md - visual direction, token plan, copy voice, and self-critique guidance for UI handoff.
• _refs/shared/frontend-architecture.md - framework-neutral component, responsibility, state, data, registration, and public API vocabulary for 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 .sdcorejs/design/specs/** and .sdcorejs/design/wireframes/** during FE implementation.
• sdcorejs-test - maps UAT/e2e coverage back to designed flows.