@ztothez/design-engineering 2.0.0

package/knowledge-base/design-intelligence/licensing-and-provenance.md

@@ -0,0 +1,59 @@
+# Licensing And Provenance
+
+Maintain a per-asset evidence trail so design output can be reviewed, replaced, and distributed deliberately. This workflow organizes evidence; it is not legal advice.
+
+## Required Asset Record
+
+For every logo, icon, image, illustration, texture, chart, screenshot, font, audio file, or video, record:
+
+- Stable asset identifier and local path.
+- Origin and creator.
+- Source URL when applicable.
+- Rights status: `approved`, `pending`, `rejected`, or `unknown`.
+- Rights basis: ownership, contract, provider terms, SPDX license, public domain, or permission.
+- Evidence path or source URL.
+- Attribution and restrictions.
+- Reviewer and review date when approval requires human authority.
+- Alternative-content classification.
+
+Only `approved` assets may ship. Pending, rejected, or unknown assets are blockers, not warnings.
+
+## Source-Specific Evidence
+
+### Original And Commissioned
+
+Record creator, agreement or employment basis, assignment terms when relevant, delivery date, and source files. Do not assume payment alone transfers every right.
+
+### Open Source And Open Content
+
+Use an SPDX identifier or expression when the applicable license is represented by SPDX. Preserve copyright notices, attribution, modification notices, source links, and license text as required. Record channel restrictions that cannot be expressed by the identifier alone.
+
+### Licensed Libraries And Stock
+
+Record the exact asset, account or purchase evidence, license version, download date, allowed channels, seat or audience limits, modification terms, and attribution requirements. A generic link to the provider home page is insufficient.
+
+### Public Domain
+
+Record the source and the basis for the public-domain claim. Review trademarks, privacy, publicity, cultural-property, and jurisdiction-specific constraints separately.
+
+### User-Provided Assets
+
+Record the user's representation or permission and any distribution boundary. Do not interpret possession as permission to publish.
+
+### Generated Assets
+
+Record provider, model, provider-terms evidence, prompt artifact, reference assets, human contributions, and post-processing. Review confusing similarity, embedded marks, recognizable people, sensitive contexts, and jurisdiction or channel requirements. Do not promise copyright protection or non-infringement based only on generation metadata.
+
+## Operational Rules
+
+1. Keep evidence outside generated public assets when it contains private account or contractual data.
+2. Make asset replacement possible through stable IDs and semantic references.
+3. Re-review assets when channels, territory, audience size, monetization, or provider terms change.
+4. Keep rejected assets for audit only when policy permits; never leave them in production asset directories.
+5. Treat missing evidence as unresolved even when an asset looks generic.
+
+## Machine-Readable Identifiers
+
+SPDX identifiers make standard licenses easier to record consistently, but they do not replace required notices or a review of whether the license fits the intended use. See [SPDX guidance for license information](https://spdx.dev/learn/handling-license-info/) and the [SPDX License List](https://spdx.org/licenses/).
+
+For current United States guidance on copyrightability and generative AI, consult the [U.S. Copyright Office AI initiative](https://www.copyright.gov/ai/). Obtain qualified advice for consequential releases or jurisdiction-specific questions.

package/knowledge-base/design-intelligence/presentation-design.md

@@ -0,0 +1,56 @@
+# Presentation Design
+
+Design a presentation as a sequence of audience decisions supported by reusable masters, not as disconnected decorated slides.
+
+## Step 1: Define The Communication Contract
+
+Record the audience, decision or outcome, delivery context, duration, aspect ratio, and distribution format. Separate what must be understood during delivery from what belongs in speaker notes or a companion document.
+
+Write a one-sentence purpose for every slide. Remove slides that do not advance the narrative, support a decision, explain evidence, or enable action.
+
+## Step 2: Build The Narrative
+
+Use a structure appropriate to the task, such as:
+
+1. Context and stakes.
+2. User or system problem.
+3. Evidence and constraints.
+4. Proposed direction.
+5. Trade-offs and alternatives.
+6. Implementation or operating model.
+7. Decision, owner, and next action.
+
+Do not force this sequence onto reports, training, or status reviews when a different task model is clearer.
+
+## Step 3: Create Masters
+
+Define a small set of master layouts for recurring communication roles, such as title, section, statement, comparison, process, evidence, and closing. Each master controls margins, grid, title location, footer, page number, safe area, and reading order.
+
+Use tokens for background, text, accent, status, spacing, and typography. Keep the brand present but subordinate to legibility and evidence.
+
+## Step 4: Compose Slides
+
+- Give each slide one primary message.
+- Use a literal title that states the point, not a vague topic label.
+- Prefer real product views, diagrams, and data over decorative stock imagery.
+- Label charts directly and provide source, scope, units, and time range.
+- Avoid screenshots with unreadable UI or unexplained highlights.
+- Keep body text and diagrams readable at the expected viewing distance.
+- Use builds and motion only when sequence is necessary to comprehension.
+
+## Step 5: Make The Deck Accessible
+
+Declare reading order for every slide. Use unique slide titles, sufficient text and non-text contrast, non-color cues, meaningful link text, and alternatives for informative visuals. Mark decorative media appropriately. Provide captions or transcripts for time-based media.
+
+Do not place essential content only in speaker notes when the distributed deck must stand alone. Check the exported PDF or presentation file because reading order and alternatives can change during export.
+
+## Step 6: Verify Delivery And Export
+
+- Rehearse at the real display resolution and viewing distance.
+- Check projection and low-quality screen conditions.
+- Inspect all fonts, media, links, notes, page numbers, and transitions.
+- Open exported formats independently.
+- Confirm assets retain approved attribution and restrictions.
+- Test keyboard progression and reading order in the delivery format.
+
+The manifest validator checks master references, slide IDs, reading-order declarations, and asset references. It cannot inspect the actual deck file.

package/knowledge-base/design-intelligence/product-design-brief.md

@@ -0,0 +1,67 @@
+# Product Design Brief Contract
+
+Use this module before generating a new product interface, redesigning a consequential workflow, or
+compiling downstream architecture and visual contracts. It turns product intent into a reviewable
+input boundary and prevents an agent from filling missing users, data behavior, recovery, or success
+criteria with generic UI conventions.
+
+## Required Sequence
+
+1. Record sources before conclusions. Classify user statements, research, analytics, existing
+   product behavior, technical evidence, standards, and agent assumptions separately.
+2. State the current problem and desired outcome using source references. An agent assumption alone
+   cannot establish the product problem or primary audience.
+3. Define included and excluded scope. Resolve contradictory scope before planning.
+4. Identify at least one primary audience with concrete goals, operating context, constraints,
+   accessibility needs, expertise, and non-agent evidence.
+5. Define measurable user, operational, business, or risk-reduction outcomes. Unknown baselines are
+   valid when their reason is explicit.
+6. Model primary tasks with trigger, goal, frequency, criticality, inputs, data, success signal,
+   failure impact, and recovery. Consequential tasks must declare their data boundary.
+7. Classify each data source as live, demo, hybrid, imported, cached, user input, or local static.
+   Declare latency, sensitivity, freshness, limitations, fallback, disclosure, and origin
+   preservation. Configuration is not proof that a live service is connected.
+8. Declare every applicable state. Async and operational products generally need loading, empty,
+   success, error, partial, stale, and disconnected behavior. Sensitive products need unauthorized
+   behavior. State requirements are derived from the declared data rather than added decoratively.
+9. Declare platforms, viewports, input methods, constraints, and prioritized requirements. A
+   responsive web product covers 375, 768, 1024, and 1440 CSS pixels plus keyboard, pointer, touch,
+   and assistive-technology operation.
+10. Keep assumptions visible. Unresolved high-risk assumptions block generation; unresolved
+    medium-risk assumptions remain warnings.
+11. Bind every must-have requirement and every task to an observable acceptance criterion. Naming a
+    human verification method does not create human evidence.
+12. Decide whether product-task, interface-trust, information-design, and design-deliverable
+    contracts are planned, already exist, or are genuinely not applicable.
+
+## Generation Boundary
+
+A brief is generation-ready only when it passes semantic validation and has `status: validated`.
+That status authorizes design planning, not production release. Continue through architecture,
+interface trust, information design, visual design, implementation, browser verification, and the
+quality gate.
+
+Do not convert uncertainty into invented personas, fake metrics, unsupported live labels, generic
+dashboard cards, or placeholder acceptance criteria. Record the uncertainty as an assumption,
+assign risk, and define how it will be validated.
+
+## Commands
+
+Start from `product-design-brief.template.yaml`, then run:
+
+```bash
+npm run validate-brief -- --brief path/to/product-design-brief.yaml
+```
+
+MCP clients can call `validate_product_design_brief`. External brief roots must be explicitly
+listed in `ZTOTHEZ_DESIGN_BRIEF_ROOTS`. The tool is read-only and returns the same structured report
+as the CLI.
+
+## Evidence Limits
+
+- Structural and semantic validation does not prove that a proposed product is desirable.
+- A source reference proves traceability, not source quality.
+- Agent assumptions remain agent evidence even when a contract is validated.
+- Human-expert and representative-user acceptance methods require separately attributable evidence.
+- Interactive success, accessibility, responsive composition, and truthful runtime behavior require
+  downstream implementation and browser evidence.

package/knowledge-base/design-intelligence/product-design-brief.schema.yaml

@@ -0,0 +1,279 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://ztothez.github.io/schemas/product-design-brief.schema.yaml
+title: ZtotheZ Product Design Brief
+type: object
+additionalProperties: false
+required: [version, id, product, status, preparedAt, preparedBy, evidenceSources, problem, scope, audiences, outcomes, dataSources, tasks, states, platforms, constraints, requirements, assumptions, acceptanceCriteria, downstreamContracts]
+properties:
+  version: { const: "1.0" }
+  id: { $ref: "#/$defs/id" }
+  product: { $ref: "#/$defs/text" }
+  status: { enum: [draft, validated] }
+  preparedAt: { type: string, format: date-time }
+  preparedBy:
+    type: object
+    additionalProperties: false
+    required: [type, name]
+    properties:
+      type: { enum: [agent, human, mixed] }
+      name: { $ref: "#/$defs/text" }
+  evidenceSources:
+    type: array
+    minItems: 1
+    maxItems: 500
+    items: { $ref: "#/$defs/evidenceSource" }
+  problem:
+    type: object
+    additionalProperties: false
+    required: [statement, currentOutcome, desiredOutcome, evidenceRefs]
+    properties:
+      statement: { $ref: "#/$defs/longText" }
+      currentOutcome: { $ref: "#/$defs/longText" }
+      desiredOutcome: { $ref: "#/$defs/longText" }
+      evidenceRefs: { $ref: "#/$defs/nonEmptyRefs" }
+  scope:
+    type: object
+    additionalProperties: false
+    required: [included, excluded]
+    properties:
+      included: { $ref: "#/$defs/nonEmptyTextList" }
+      excluded: { $ref: "#/$defs/nonEmptyTextList" }
+  audiences:
+    type: array
+    minItems: 1
+    maxItems: 100
+    items: { $ref: "#/$defs/audience" }
+  outcomes:
+    type: array
+    minItems: 1
+    maxItems: 200
+    items: { $ref: "#/$defs/outcome" }
+  dataSources:
+    type: array
+    minItems: 1
+    maxItems: 500
+    items: { $ref: "#/$defs/dataSource" }
+  tasks:
+    type: array
+    minItems: 1
+    maxItems: 500
+    items: { $ref: "#/$defs/task" }
+  states:
+    type: array
+    minItems: 1
+    maxItems: 20
+    items: { $ref: "#/$defs/state" }
+  platforms:
+    type: array
+    minItems: 1
+    maxItems: 20
+    items: { $ref: "#/$defs/platform" }
+  constraints: { $ref: "#/$defs/textList" }
+  requirements:
+    type: array
+    minItems: 1
+    maxItems: 1000
+    items: { $ref: "#/$defs/requirement" }
+  assumptions:
+    type: array
+    maxItems: 500
+    items: { $ref: "#/$defs/assumption" }
+  acceptanceCriteria:
+    type: array
+    minItems: 1
+    maxItems: 2000
+    items: { $ref: "#/$defs/acceptanceCriterion" }
+  downstreamContracts:
+    type: array
+    minItems: 4
+    maxItems: 4
+    items: { $ref: "#/$defs/downstreamContract" }
+$defs:
+  id: { type: string, pattern: "^[a-z0-9][a-z0-9-]{0,63}$" }
+  text: { type: string, minLength: 1, maxLength: 512 }
+  longText: { type: string, minLength: 1, maxLength: 1024 }
+  refs:
+    type: array
+    maxItems: 100
+    items: { $ref: "#/$defs/id" }
+  nonEmptyRefs:
+    type: array
+    minItems: 1
+    maxItems: 100
+    items: { $ref: "#/$defs/id" }
+  textList:
+    type: array
+    maxItems: 100
+    items: { $ref: "#/$defs/longText" }
+  nonEmptyTextList:
+    type: array
+    minItems: 1
+    maxItems: 100
+    items: { $ref: "#/$defs/longText" }
+  evidenceSource:
+    type: object
+    additionalProperties: false
+    required: [id, kind, description, owner]
+    properties:
+      id: { $ref: "#/$defs/id" }
+      kind: { enum: [user-provided, stakeholder, user-research, product-analytics, support-record, existing-product, technical-source, public-standard, agent-assumption] }
+      description: { $ref: "#/$defs/longText" }
+      location: { $ref: "#/$defs/longText" }
+      owner: { $ref: "#/$defs/text" }
+  audience:
+    type: object
+    additionalProperties: false
+    required: [id, role, priority, goals, contexts, constraints, accessibilityNeeds, expertise, evidenceRefs]
+    properties:
+      id: { $ref: "#/$defs/id" }
+      role: { $ref: "#/$defs/text" }
+      priority: { enum: [primary, secondary, affected] }
+      goals: { $ref: "#/$defs/textList" }
+      contexts: { $ref: "#/$defs/textList" }
+      constraints: { $ref: "#/$defs/textList" }
+      accessibilityNeeds: { $ref: "#/$defs/textList" }
+      expertise: { enum: [novice, intermediate, expert, mixed, unknown] }
+      evidenceRefs: { $ref: "#/$defs/nonEmptyRefs" }
+  outcome:
+    type: object
+    additionalProperties: false
+    required: [id, kind, statement, measure, evidenceRefs]
+    properties:
+      id: { $ref: "#/$defs/id" }
+      kind: { enum: [user, business, operational, risk-reduction] }
+      statement: { $ref: "#/$defs/longText" }
+      measure:
+        type: object
+        additionalProperties: false
+        required: [signal, baseline, target]
+        properties:
+          signal: { $ref: "#/$defs/longText" }
+          target: { $ref: "#/$defs/longText" }
+          baseline:
+            oneOf:
+              - type: object
+                additionalProperties: false
+                required: [status, value]
+                properties:
+                  status: { const: known }
+                  value: { $ref: "#/$defs/text" }
+              - type: object
+                additionalProperties: false
+                required: [status, reason]
+                properties:
+                  status: { enum: [unknown, not-applicable] }
+                  reason: { $ref: "#/$defs/longText" }
+      evidenceRefs: { $ref: "#/$defs/nonEmptyRefs" }
+  dataSource:
+    type: object
+    additionalProperties: false
+    required: [id, name, mode, latency, classification, sourceEvidenceRef, freshness, limitations, fallback]
+    properties:
+      id: { $ref: "#/$defs/id" }
+      name: { $ref: "#/$defs/text" }
+      mode: { enum: [live, demo, hybrid, imported, cached, user-input, local-static] }
+      latency: { enum: [immediate, async, streaming, unknown] }
+      classification: { enum: [public, internal, confidential, restricted] }
+      sourceEvidenceRef: { $ref: "#/$defs/id" }
+      freshness: { $ref: "#/$defs/longText" }
+      limitations: { $ref: "#/$defs/textList" }
+      fallback:
+        type: object
+        additionalProperties: false
+        required: [kind, disclosure, preservesOrigin]
+        properties:
+          kind: { enum: [none, demo, cache, import, manual] }
+          disclosure: { $ref: "#/$defs/longText" }
+          preservesOrigin: { type: boolean }
+  task:
+    type: object
+    additionalProperties: false
+    required: [id, title, audienceRefs, outcomeRefs, dataRefs, trigger, goal, frequency, criticality, consequential, inputs, successSignal, failureImpact, recovery, evidenceRefs]
+    properties:
+      id: { $ref: "#/$defs/id" }
+      title: { $ref: "#/$defs/text" }
+      audienceRefs: { $ref: "#/$defs/nonEmptyRefs" }
+      outcomeRefs: { $ref: "#/$defs/nonEmptyRefs" }
+      dataRefs: { $ref: "#/$defs/refs" }
+      trigger: { $ref: "#/$defs/longText" }
+      goal: { $ref: "#/$defs/longText" }
+      frequency: { enum: [continuous, daily, weekly, monthly, occasional, one-time] }
+      criticality: { enum: [critical, high, medium, low] }
+      consequential: { type: boolean }
+      inputs: { $ref: "#/$defs/textList" }
+      successSignal: { $ref: "#/$defs/longText" }
+      failureImpact: { $ref: "#/$defs/longText" }
+      recovery: { $ref: "#/$defs/longText" }
+      evidenceRefs: { $ref: "#/$defs/nonEmptyRefs" }
+  state:
+    type: object
+    additionalProperties: false
+    required: [state, taskRefs, behavior, recovery, disclosure]
+    properties:
+      state: { enum: [loading, empty, success, error, partial, stale, disconnected, unauthorized, blocked, offline] }
+      taskRefs: { $ref: "#/$defs/nonEmptyRefs" }
+      behavior: { $ref: "#/$defs/longText" }
+      recovery: { $ref: "#/$defs/longText" }
+      disclosure: { $ref: "#/$defs/longText" }
+  platform:
+    type: object
+    additionalProperties: false
+    required: [id, kind, priority, viewports, inputModes, constraints]
+    properties:
+      id: { $ref: "#/$defs/id" }
+      kind: { enum: [responsive-web, desktop-web, mobile-web, native-mobile, desktop-app] }
+      priority: { enum: [primary, secondary] }
+      viewports: { type: array, items: { type: integer, minimum: 240, maximum: 10000 } }
+      inputModes: { type: array, minItems: 1, items: { enum: [keyboard, pointer, touch, assistive-technology] } }
+      constraints: { $ref: "#/$defs/textList" }
+  requirement:
+    type: object
+    additionalProperties: false
+    required: [id, category, priority, statement, rationale, taskRefs, evidenceRefs]
+    properties:
+      id: { $ref: "#/$defs/id" }
+      category: { enum: [functional, usability, accessibility, security, privacy, performance, reliability, maintainability, content, brand] }
+      priority: { enum: [must, should, could, wont] }
+      statement: { $ref: "#/$defs/longText" }
+      rationale: { $ref: "#/$defs/longText" }
+      taskRefs: { $ref: "#/$defs/refs" }
+      evidenceRefs: { $ref: "#/$defs/nonEmptyRefs" }
+  assumption:
+    type: object
+    additionalProperties: false
+    required: [id, statement, risk, status, evidenceRefs, validationMethod]
+    properties:
+      id: { $ref: "#/$defs/id" }
+      statement: { $ref: "#/$defs/longText" }
+      risk: { enum: [high, medium, low] }
+      status: { enum: [unresolved, validated, rejected] }
+      evidenceRefs: { $ref: "#/$defs/refs" }
+      validationMethod: { $ref: "#/$defs/longText" }
+  acceptanceCriterion:
+    type: object
+    additionalProperties: false
+    required: [id, statement, requirementRefs, taskRefs, method, expectedEvidence, blocking]
+    properties:
+      id: { $ref: "#/$defs/id" }
+      statement: { $ref: "#/$defs/longText" }
+      requirementRefs: { $ref: "#/$defs/nonEmptyRefs" }
+      taskRefs: { $ref: "#/$defs/nonEmptyRefs" }
+      method: { enum: [static-analysis, unit-test, integration-test, browser-test, manual-human, human-expert, representative-user] }
+      expectedEvidence: { $ref: "#/$defs/longText" }
+      blocking: { type: boolean }
+  downstreamContract:
+    type: object
+    additionalProperties: false
+    required: [kind, status]
+    properties:
+      kind: { enum: [product-task, interface-trust, information-design, design-deliverable] }
+      status: { enum: [planned, exists, not-applicable] }
+      path: { $ref: "#/$defs/longText" }
+      reason: { $ref: "#/$defs/longText" }
+    allOf:
+      - if:
+          properties: { status: { const: exists } }
+        then: { required: [path] }
+      - if:
+          properties: { status: { const: not-applicable } }
+        then: { required: [reason] }