@ztothez/design-engineering 2.0.0

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

@@ -0,0 +1,225 @@
+version: "1.0"
+id: example-operations-brief
+product: Example Operations Workspace
+status: validated
+preparedAt: 2026-08-28T20:00:00+03:00
+preparedBy:
+  type: mixed
+  name: ZtotheZ and design agent
+evidenceSources:
+  - id: operator-request
+    kind: user-provided
+    description: Operators need to identify the highest-impact issue and start a bounded remediation without losing scope context.
+    owner: Product owner
+  - id: service-contract
+    kind: technical-source
+    description: The service contract exposes scoped findings and can fall back to disclosed demonstration data when disconnected.
+    location: docs/service-contract.yaml
+    owner: Engineering
+problem:
+  statement: Operators cannot reliably distinguish the highest-impact issue from supporting telemetry before taking action.
+  currentOutcome: Reviewers scan several disconnected panels and may act without confirming scope or result origin.
+  desiredOutcome: An operator identifies scope, priority, evidence, and the next safe action from one coherent task path.
+  evidenceRefs: [operator-request, service-contract]
+scope:
+  included:
+    - Scoped findings overview
+    - Finding evidence drill-down
+    - Bounded remediation start and recovery
+  excluded:
+    - Automatic remediation without confirmation
+    - Production credential management
+audiences:
+  - id: operations-engineer
+    role: Operations engineer
+    priority: primary
+    goals:
+      - Identify the most consequential finding.
+      - Verify evidence before starting remediation.
+    contexts:
+      - Desktop operations review during normal and degraded service states.
+      - Narrow viewport incident triage away from the primary workstation.
+    constraints:
+      - Must preserve environment and scope during failures.
+      - Must not confuse demonstration results with live results.
+    accessibilityNeeds:
+      - Keyboard-complete operation and visible focus.
+      - High-contrast text and non-color severity cues.
+    expertise: mixed
+    evidenceRefs: [operator-request]
+outcomes:
+  - id: identify-next-action
+    kind: user
+    statement: The operator can identify the highest-impact finding and its next action without inspecting unrelated telemetry.
+    measure:
+      signal: Primary journey reaches the evidence-backed action from the overview.
+      baseline:
+        status: unknown
+        reason: No retained interaction baseline exists for the example product.
+      target: Browser journey exposes scope, priority, evidence, and action at every maintained viewport.
+    evidenceRefs: [operator-request]
+  - id: preserve-result-trust
+    kind: risk-reduction
+    statement: The interface preserves live or demonstration origin throughout findings and actions.
+    measure:
+      signal: Result-origin assertions remain visible before action and in resulting records.
+      baseline:
+        status: not-applicable
+        reason: This is a new example workflow.
+      target: All live, fallback, stale, and disconnected fixtures pass the trust contract.
+    evidenceRefs: [service-contract]
+dataSources:
+  - id: findings-service
+    name: Findings service
+    mode: hybrid
+    latency: async
+    classification: internal
+    sourceEvidenceRef: service-contract
+    freshness: Runtime response timestamp with timezone; unknown until a response arrives.
+    limitations:
+      - Demonstration fallback cannot establish production service availability.
+    fallback:
+      kind: demo
+      disclosure: Show Demonstration data next to scope, findings, actions, history, and exports.
+      preservesOrigin: true
+tasks:
+  - id: review-and-start-remediation
+    title: Review the highest-impact finding and start remediation
+    audienceRefs: [operations-engineer]
+    outcomeRefs: [identify-next-action, preserve-result-trust]
+    dataRefs: [findings-service]
+    trigger: A scheduled or manual analysis has findings available for the selected environment.
+    goal: Confirm scope and evidence, then start the bounded remediation for the highest-impact finding.
+    frequency: daily
+    criticality: high
+    consequential: true
+    inputs:
+      - Selected environment
+      - Finding identifier
+    successSignal: The selected finding enters a started state with scope, origin, evidence, and verification instructions preserved.
+    failureImpact: The operator may act on the wrong environment or mistake demonstration evidence for live service output.
+    recovery: Preserve the selected scope and finding, explain the failure, and offer a bounded retry or return to review.
+    evidenceRefs: [operator-request, service-contract]
+states:
+  - state: loading
+    taskRefs: [review-and-start-remediation]
+    behavior: Preserve layout and selected scope while announcing bounded progress.
+    recovery: Allow cancellation and retain the current finding selection.
+    disclosure: Connection and result origin remain checking until runtime evidence resolves them.
+  - state: empty
+    taskRefs: [review-and-start-remediation]
+    behavior: State that no findings exist for the selected scope and period.
+    recovery: Let the operator change scope or rerun analysis.
+    disclosure: Preserve data mode, scope, freshness, and limitations.
+  - state: success
+    taskRefs: [review-and-start-remediation]
+    behavior: Show the started remediation, affected scope, evidence, and verification step.
+    recovery: Provide a return path to the finding and history.
+    disclosure: Preserve result origin and service state in the resulting record.
+  - state: error
+    taskRefs: [review-and-start-remediation]
+    behavior: Explain the failed operation without discarding the selected finding.
+    recovery: Offer a bounded retry and a safe return to review.
+    disclosure: Distinguish interface availability from service failure.
+  - state: partial
+    taskRefs: [review-and-start-remediation]
+    behavior: Label unavailable evidence and prevent unsupported certainty.
+    recovery: Allow review of available evidence or retry missing portions.
+    disclosure: State which findings or evidence are incomplete.
+  - state: stale
+    taskRefs: [review-and-start-remediation]
+    behavior: Keep stale findings visible with timestamp and block unsafe assumptions of currency.
+    recovery: Refresh while preserving scope and selection.
+    disclosure: Show stale status, observed time, timezone, and source.
+  - state: disconnected
+    taskRefs: [review-and-start-remediation]
+    behavior: Keep the interface usable and disable actions that require a verified connection.
+    recovery: Retry connection or enter explicitly disclosed demonstration mode.
+    disclosure: Show disconnected state separately from demonstration result origin.
+platforms:
+  - id: responsive-browser
+    kind: responsive-web
+    priority: primary
+    viewports: [375, 768, 1024, 1440]
+    inputModes: [keyboard, pointer, touch, assistive-technology]
+    constraints:
+      - Avoid competing scroll regions on narrow viewports.
+      - Keep the next action visible before telemetry detail.
+constraints:
+  - TypeScript and semantic token architecture.
+  - Local fixture states must not contact production services.
+  - Evidence output must not contain credentials or absolute private paths.
+requirements:
+  - id: requirement-decision-path
+    category: functional
+    priority: must
+    statement: The overview exposes scope, highest-impact finding, evidence, and the bounded next action in decision order.
+    rationale: The primary task depends on identifying and verifying the right action.
+    taskRefs: [review-and-start-remediation]
+    evidenceRefs: [operator-request]
+  - id: requirement-truth
+    category: reliability
+    priority: must
+    statement: Live, demonstration, stale, partial, and disconnected results remain visibly distinguishable before action and in resulting records.
+    rationale: Unsupported operational certainty can cause incorrect remediation.
+    taskRefs: [review-and-start-remediation]
+    evidenceRefs: [service-contract]
+  - id: requirement-accessibility
+    category: accessibility
+    priority: must
+    statement: The primary task supports keyboard, visible focus, non-color status cues, text resize, reflow, and maintained contrast.
+    rationale: The task must remain operable across declared access needs and viewports.
+    taskRefs: [review-and-start-remediation]
+    evidenceRefs: [operator-request]
+  - id: requirement-boundaries
+    category: maintainability
+    priority: should
+    statement: Domain state, service access, and rendering remain independently testable.
+    rationale: Trust and recovery behavior must not depend on one monolithic component.
+    taskRefs: [review-and-start-remediation]
+    evidenceRefs: [service-contract]
+assumptions:
+  - id: assumption-service-shape
+    statement: The declared service contract represents the initial fixture response shape.
+    risk: low
+    status: validated
+    evidenceRefs: [service-contract]
+    validationMethod: Validate fixtures against the service contract before browser verification.
+acceptanceCriteria:
+  - id: acceptance-decision-path
+    statement: At 375, 768, 1024, and 1440 CSS pixels, the operator can inspect scope, priority, evidence, and next action without telemetry preceding the action.
+    requirementRefs: [requirement-decision-path]
+    taskRefs: [review-and-start-remediation]
+    method: browser-test
+    expectedEvidence: Checksummed captures and journey assertions for all four viewports.
+    blocking: true
+  - id: acceptance-trust-states
+    statement: Live, demonstration fallback, partial, stale, and disconnected fixtures preserve origin and limitations before and after the action.
+    requirementRefs: [requirement-truth]
+    taskRefs: [review-and-start-remediation]
+    method: integration-test
+    expectedEvidence: State-specific contract and runtime assertions with no unsupported live claim.
+    blocking: true
+  - id: acceptance-accessibility
+    statement: The primary journey passes keyboard, focus, contrast, target, text-resize, reflow, and reduced-motion checks.
+    requirementRefs: [requirement-accessibility]
+    taskRefs: [review-and-start-remediation]
+    method: browser-test
+    expectedEvidence: Browser report with applicable accessibility checks passing.
+    blocking: true
+  - id: acceptance-boundaries
+    statement: Static audit reports no domain-state ownership leak or shared component threshold violation in the primary task path.
+    requirementRefs: [requirement-boundaries]
+    taskRefs: [review-and-start-remediation]
+    method: static-analysis
+    expectedEvidence: Architecture audit report bound to the source revision.
+    blocking: false
+downstreamContracts:
+  - kind: product-task
+    status: planned
+  - kind: interface-trust
+    status: planned
+  - kind: information-design
+    status: planned
+  - kind: design-deliverable
+    status: planned

package/knowledge-base/design-intelligence/repair-request.schema.yaml

@@ -0,0 +1,95 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://ztothez.dev/schemas/repair-request-1.0.schema.json
+title: ZtotheZ Bounded Repair Request
+type: object
+additionalProperties: false
+required: [version, id, target, findings, attempts, stopping]
+properties:
+  version: { const: "1.0" }
+  id: { $ref: "#/$defs/id" }
+  target:
+    type: object
+    additionalProperties: false
+    required: [adapter, manifest]
+    properties:
+      adapter: { const: react-typescript-vite }
+      manifest: { $ref: "#/$defs/relativePath" }
+  findings:
+    type: array
+    minItems: 1
+    maxItems: 20
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, source, checkId, acceptanceCriterion, expectedEvidence]
+      properties:
+        id: { $ref: "#/$defs/id" }
+        source: { enum: [architecture, runtime] }
+        checkId: { type: string, minLength: 1, maxLength: 128 }
+        file: { $ref: "#/$defs/relativePath" }
+        messageIncludes: { type: string, minLength: 1, maxLength: 512 }
+        viewport: { type: string, minLength: 1, maxLength: 128 }
+        journey: { type: string, minLength: 1, maxLength: 128 }
+        selector: { type: string, minLength: 1, maxLength: 1024 }
+        acceptanceCriterion: { $ref: "#/$defs/id" }
+        expectedEvidence:
+          type: array
+          minItems: 1
+          maxItems: 4
+          uniqueItems: true
+          items:
+            enum: [contract-validation, static-audit, browser-runtime, responsive-screenshots]
+      allOf:
+        - if:
+            properties: { source: { const: architecture } }
+          then:
+            required: [file]
+  attempts:
+    type: array
+    minItems: 1
+    maxItems: 3
+    items:
+      type: object
+      additionalProperties: false
+      required: [id, operations]
+      properties:
+        id: { $ref: "#/$defs/id" }
+        operations:
+          type: array
+          minItems: 1
+          maxItems: 20
+          items:
+            type: object
+            additionalProperties: false
+            required: [id, findingRef, kind, file, expectedFileDigest, before, after, expectedOccurrences]
+            properties:
+              id: { $ref: "#/$defs/id" }
+              findingRef: { $ref: "#/$defs/id" }
+              kind: { const: replace-exact }
+              file: { $ref: "#/$defs/relativePath" }
+              expectedFileDigest: { $ref: "#/$defs/digest" }
+              before: { type: string, minLength: 1, maxLength: 100000 }
+              after: { type: string, maxLength: 100000 }
+              expectedOccurrences: { type: integer, minimum: 1, maximum: 20 }
+  stopping:
+    type: object
+    additionalProperties: false
+    required: [maxAttempts, resolved, repeatedFinding, preconditionFailure, verificationFailure]
+    properties:
+      maxAttempts: { type: integer, minimum: 1, maximum: 3 }
+      resolved: { const: all-referenced-findings-absent-and-quality-gate-passed }
+      repeatedFinding: { const: stop-unresolved-and-restore }
+      preconditionFailure: { const: stop-without-write }
+      verificationFailure: { const: stop-unresolved-and-restore }
+$defs:
+  id:
+    type: string
+    pattern: "^[a-z0-9][a-z0-9-]{0,63}$"
+  digest:
+    type: string
+    pattern: "^[a-f0-9]{64}$"
+  relativePath:
+    type: string
+    minLength: 1
+    maxLength: 1024
+    pattern: "^(?!/)(?!.*(?:^|/)[.][.](?:/|$)).+$"

package/knowledge-base/design-intelligence/repair-request.template.yaml

@@ -0,0 +1,39 @@
+version: "1.0"
+id: responsive-token-repair
+target:
+  adapter: react-typescript-vite
+  manifest: ztothez-design-generation.json
+findings:
+  - id: raw-responsive-values
+    source: architecture
+    checkId: ZTDE-DESIGN-001
+    file: src/styles/app.css
+    messageIncludes: raw visual values
+    acceptanceCriterion: responsive-integrity
+    expectedEvidence:
+      - contract-validation
+      - static-audit
+      - browser-runtime
+      - responsive-screenshots
+attempts:
+  - id: replace-with-semantic-tokens
+    operations:
+      - id: remove-raw-responsive-values
+        findingRef: raw-responsive-values
+        kind: replace-exact
+        file: src/styles/app.css
+        expectedFileDigest: "0000000000000000000000000000000000000000000000000000000000000000"
+        before: |-
+          .example-unsafe-rule {
+            color: #111111;
+            background: #eeeeee;
+            border-color: #777777;
+          }
+        after: ""
+        expectedOccurrences: 1
+stopping:
+  maxAttempts: 1
+  resolved: all-referenced-findings-absent-and-quality-gate-passed
+  repeatedFinding: stop-unresolved-and-restore
+  preconditionFailure: stop-without-write
+  verificationFailure: stop-unresolved-and-restore

package/knowledge-base/design-intelligence/visual-accessibility.md

@@ -0,0 +1,56 @@
+# Visual Accessibility Verification
+
+Use this module for normal-text contrast ratios, non-color status cues, semantic token pairs, focus
+contrast, visual alternatives, and rendered accessibility verification. Validate visual
+accessibility at token, design-source, exported-artifact, and rendered-implementation levels. A
+passing token pair does not prove the pixels users receive.
+
+## Step 1: Declare Semantic Pairs
+
+Record foreground and background token pairs for normal text, qualifying large text, controls, focus indicators, graphical objects, status treatments, and data visualization. Test every supported mode and state.
+
+The deterministic manifest validator applies these WCAG 2.2 thresholds:
+
+- Normal text: at least 4.5:1.
+- Large text: at least 3:1, with large text declared as at least 24 CSS pixels regular or 18.66 CSS pixels at weight 700 or greater.
+- User-interface components and meaningful graphical objects: at least 3:1 where non-text contrast applies.
+
+The validator supports opaque `#RRGGBB` primitives. Use a rendered check for alpha, images, video, gradients, blending, filters, and changing backgrounds.
+
+## Step 2: Prevent Color-Only Meaning
+
+For every status, validation result, selection, chart series, required field, and changed value, combine color with at least one independent cue such as text, icon, shape, pattern, position, value, or underline. Assistive-technology text alone does not replace the visual cue needed by sighted users who do not distinguish the colors.
+
+## Step 3: Provide Visual Alternatives
+
+Classify every asset:
+
+- Decorative: empty alternative and hidden semantics.
+- Short informative image: concise alternative text describing purpose in context.
+- Complex image or diagram: short alternative plus adjacent long description.
+- Chart: summary plus accessible data table when users need exact values.
+- Audio or video: captions, transcript, and audio description as applicable.
+- Screenshot: describe the relevant state or annotation, not every visible pixel.
+
+Do not repeat nearby visible text. Do not embed essential copy only in images.
+
+## Step 4: Check Scale And Perception
+
+- Inspect at 200 percent text resizing and zoom.
+- Verify focus remains visible and unobscured.
+- Test high-contrast and forced-color behavior when the platform supports them.
+- Respect reduced-motion preference and remove nonessential movement.
+- Check target size and spacing for touch input.
+- Verify charts, maps, and diagrams under color-vision simulations without treating simulation as user testing.
+- Inspect light, dark, print, projected, and disabled states independently.
+
+## Step 5: Verify Final Output
+
+Run the manifest validator for declarations and token math. Run browser verification for implemented UI. Inspect image exports at native size. Inspect document and presentation reading order after export. Use human review for hierarchy, legibility, comprehension, and cultural interpretation.
+
+Record limitations when a check cannot model the actual background or output format. Never suppress a failure merely because the intended aesthetic uses low contrast.
+
+## Standards References
+
+- [WCAG 2.2 use of color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color)
+- [WCAG 2.2 distinguishable guidance](https://www.w3.org/WAI/WCAG22/Understanding/distinguishable.html)

package/knowledge-base/design-intelligence/visual-polish.md

@@ -0,0 +1,172 @@
+# Visual Polish System
+
+Use this module when an implemented interface must feel intentional, balanced, legible, domain-appropriate, and ready for rendered review. Declare `interface-system` in a version `2.1` design-deliverable manifest and complete the visual-polish sections before implementation is called visually complete. Existing version `2.0` manifests remain valid but do not enforce the review-derived decision-order and theme-coverage additions below.
+
+Visual polish is not decoration. It is the consistent control of hierarchy, typography, density, alignment, state language, chart communication, motion, and responsive composition around the product task.
+
+## Evidence Boundary
+
+Keep these outcomes separate:
+
+1. `passed`: the manifest is structurally valid and its declared references are consistent.
+2. `renderedEvidenceReady`: verified screenshots and runtime reports exist at every required viewport.
+3. `humanReviewReady`: attributable reviewer-supplied evidence covers hierarchy, balance, scanability, density, and domain fit.
+4. `releaseReady`: all three conditions are satisfied.
+
+`planned` and `captured` evidence is not verified evidence. An agent must not mark a human review complete or create reviewer identities, observations, or approval records.
+
+## Step 1: Choose A Domain Direction
+
+Define the domain, visual intent, three to eight principles, prohibited treatments, and semantic token references. The direction must make the primary task easier to scan and trust.
+
+For operational products, favor calm surfaces, explicit state labels, compact evidence, stable geometry, and high information contrast. For creative products, expression may be stronger, but interaction state and content hierarchy must remain readable.
+
+Reject these default generator patterns unless a real product requirement establishes meaning:
+
+- Decorative agent or node diagrams.
+- Excessive glow around controls, cards, or status indicators.
+- Gradients that do not encode a value, brand transition, or spatial function.
+- Pulsing dots, shields, rings, or ornaments presented as operational proof.
+- Repeated floating cards used as page sections.
+- Oversized headings inside compact tools or dashboards.
+- A one-hue palette that erases hierarchy between surfaces, actions, evidence, and states.
+
+## Step 2: Bind Visual Usage To Semantic Tokens
+
+Keep three token responsibilities:
+
+- `primitive`: raw values such as colors, dimensions, font families, weights, durations, numbers, and shadows.
+- `semantic`: product meaning such as primary text, raised surface, selected border, compact row height, or feedback duration.
+- `component`: a stable component decision that references a semantic or primitive token where the design-system architecture requires it.
+
+Visual-direction, typography, composition, density, states, motion, and chart contracts must reference semantic or component tokens. Never bind component usage directly to primitives. Repository audits must also reject repeated raw colors and visual values outside identifiable token-definition files.
+
+## Step 3: Define Typography Roles
+
+Declare all eight roles with family, size, weight, line-height, color, and usage:
+
+1. `body`
+2. `label`
+3. `heading`
+4. `metadata`
+5. `metric`
+6. `evidence`
+7. `log`
+8. `code`
+
+Use at least 16 CSS pixels for body text unless a tested platform convention requires otherwise. Keep ordinary reading lines between 45 and 90 characters. Use tabular numerals for changing operational metrics and aligned comparisons.
+
+Do not create hierarchy by font size alone. Combine role, weight, surface, spacing, and position. Keep metadata quieter than evidence and evidence quieter than the primary task outcome without reducing essential text below readable contrast or size.
+
+## Step 4: Build Composition And Rhythm
+
+Declare grids at 375, 768, 1024, and 1440 CSS pixels. For each viewport, specify columns, gutter, margin, and composition behavior. Responsive changes may alter geometry but must preserve semantic order and task continuity.
+
+Define:
+
+- Fluid, bounded, or hybrid content width with a maximum.
+- A base spacing token and four or more allowed spacing steps.
+- Alignment rules for headings, labels, values, controls, tables, and evidence.
+- Stable dimensions for boards, rows, toolbars, media, charts, and controls whose content or state changes could shift layout.
+- Canvas, subtle, raised, overlay, and inverse surfaces as needed.
+- Default, strong, focus, and selected borders.
+- Base, raised, and overlay elevation roles.
+- Primary, secondary, tertiary, and muted emphasis.
+- A selected state with background, border, visible indicator, and a non-color cue.
+
+Use elevation to explain stacking or interaction, not to make every region float. Use borders to establish grouping and selected state, not to outline every element equally.
+
+## Step 5: Choose Density Deliberately
+
+Select `comfortable`, `compact`, `dense`, or `adaptive` from task frequency, data volume, pointer precision, and reading burden. Declare control height, row heights, spacing tokens, and no more than three simultaneous primary actions.
+
+For each required viewport, state the density mode and visible priorities, then map each priority to
+a canonical `priorityRole`. Keep `context`, `primary-outcome`, and `next-action` visible at every
+viewport. Place telemetry, detailed evidence, and history after the next action. At 375 CSS pixels,
+use comfortable density and expose at most four decision-critical priorities before expandable
+detail. At 768 CSS pixels, do not use dense mode. Do not solve crowding only by shrinking text.
+
+Use progressive disclosure for supporting metrics, telemetry, history, logs, and detailed evidence,
+but never hide the primary outcome, critical exception, or next action behind unrelated navigation.
+Expansion must preserve task context, focus order, and state continuity.
+
+## Step 6: Unify Interaction States
+
+Define one visual language for:
+
+```text
+loading empty success warning error partial disabled selected focus
+```
+
+Each state needs behavior and semantic token bindings. Warning, error, partial, and selected states require text or a semantic icon in addition to color. Loading must preserve stable geometry. Empty states must explain scope and recovery. Partial and stale content must remain distinguishable from success. Disabled controls must remain legible and explain unavailable actions where necessary. Focus must remain visible against adjacent surfaces.
+
+## Step 7: Constrain Motion
+
+Use motion only to explain state change, continuity, feedback, progress, or spatial relationship. Define semantic duration categories:
+
+- `instant`: 0 to 100 milliseconds.
+- `feedback`: 100 to 220 milliseconds.
+- `transition`: 150 to 350 milliseconds.
+- `emphasis`: 200 to 500 milliseconds.
+
+Declare the trigger, animated property, duration category, purpose, and whether each motion is interruptible. Every motion requires a reduced-motion equivalent that removes, replaces, or shortens movement while preserving state meaning. Avoid continuous ornamental movement and motion that delays task completion.
+
+## Step 8: Design Charts As Decision Surfaces
+
+For every chart, declare purpose, source metric identifiers, title and value visibility, label strategy, legend behavior, comparison context, accessible table or text alternative, loading, empty, partial, and error states, semantic tokens, and non-color cues.
+
+Remove decorative charts. Prefer direct labels when they reduce lookup cost. Use tables when exact comparison is the task. Do not rely on hover for values, on color alone for series, or on a trend without baseline and period context.
+
+## Step 9: Capture Required Viewports
+
+Create one stable fixture or product journey and capture 375, 768, 1024, and 1440 CSS pixel evidence. A verified capture records:
+
+- Screenshot path.
+- Runtime report path.
+- SHA-256 checksum of the screenshot.
+- Exact viewport.
+
+Use `planned` before capture, `captured` when files exist but have not been reviewed against the report, and `verified` only after evidence integrity and expected composition are checked. Browser verification must still inspect clipping, overlap, text and non-text contrast, focus, target size, keyboard behavior, reflow, text resize, reduced motion, decision order, visual claims, and rendered asset metadata.
+
+For version `2.1`, declare normal-text contrast pairs for every typography foreground against the
+canvas in the default mode and every declared token mode. Declare focus non-text contrast in the
+same modes. Declare every state foreground against its adjacent surface and every chart series
+against its chart background in those modes. A passing light mode does not establish dark-mode readability, and a passing dark mode
+does not establish that a bright light canvas is comfortable in the intended viewing context.
+
+Instrument interfaces that claim automated composition verification with
+`data-ztothez-design-composition="1.0"`. Mark exactly one visible `context`, `primary-outcome`, and
+`next-action` priority in semantic DOM order. Declare primary-action and visible-region limits,
+status purpose, visual-claim basis and evidence, state non-color cues, chart series visuals, and
+asset purpose, source, approved rights, alternative class, and failure strategy. These markers make
+declared decisions measurable; they do not prescribe a visual style or establish human preference.
+
+Run both maintained color schemes when both are implemented:
+
+```bash
+npm run verify-ui -- --url URL --color-schemes light,dark
+```
+
+## Step 10: Require Attributable Human Review
+
+Rendered human review must evaluate:
+
+- Hierarchy.
+- Balance.
+- Scanability.
+- Density.
+- Domain fit.
+
+Record reviewer-supplied name, role, offset timestamp, and an evidence reference whose kind is `review`. Preserve dissent and unresolved findings. Automated checks and AI-assisted critique may prepare the packet but cannot satisfy this gate.
+
+## Validation
+
+Validate the manifest:
+
+```bash
+npm run validate-design -- --manifest PATH
+```
+
+Or use MCP tool `validate_design_deliverable`.
+
+Read `visualPolish.releaseReady` separately from `passed`. A structurally passing manifest with planned screenshots or required human review remains not ready for visual release.

package/knowledge-base/maintained/architecture/MASTER.md

@@ -0,0 +1,22 @@
+# Maintained Design Architecture
+
+Use this module set when a design task changes system boundaries, shared components, runtime ownership, product-family reuse, or consequential quality attributes. These files are independently authored for ZtotheZ Design Engineering and are the only architecture references in the distributable knowledge index.
+
+## Routing
+
+| Need | Module |
+|---|---|
+| Quality attributes, scenarios, trade-offs, or architecture review | `quality-attributes-and-evaluation.md` |
+| Components, state ownership, coupling, cohesion, or package boundaries | `component-boundaries.md` |
+| Shared product families, variation points, plugins, or platform evolution | `product-platforms.md` |
+
+## Operating Contract
+
+1. Start with actors, critical tasks, sources of truth, failure states, and measurable quality scenarios.
+2. Draw dependency and runtime boundaries before choosing patterns or packages.
+3. Keep domain policy independent from rendering and infrastructure details.
+4. Use explicit contracts for state, events, errors, cancellation, retries, and ownership.
+5. Record consequential decisions with alternatives, trade-offs, and reversal cost.
+6. Validate important scenarios through source inspection, tests, runtime evidence, and attributable review as appropriate.
+
+Architecture vocabulary is not evidence. A named pattern is acceptable only when the implemented dependency direction and runtime behavior support the required tasks and quality attributes.

package/knowledge-base/maintained/architecture/component-boundaries.md

@@ -0,0 +1,30 @@
+# Component And Package Boundaries
+
+## Ownership Rules
+
+- One feature owns each mutable source of truth.
+- Rendering consumes state and emits user intent; domain policy decides outcomes.
+- Infrastructure adapters own transport, storage, and vendor details.
+- Shared components own interaction behavior and accessibility contracts, not product-specific workflow policy.
+- Cross-feature communication uses explicit events, commands, or query contracts.
+
+## Coupling Review
+
+Reject or refactor boundaries that create:
+
+- Cyclic package dependencies.
+- Feature code importing another feature's internal modules.
+- Presentation components directly coordinating network, persistence, export, and domain validation.
+- Shared utilities that encode unrelated business policy.
+- Prop contracts that mirror an entire store instead of the component's actual needs.
+- Global state used only to avoid defining ownership.
+
+Depend on stable abstractions only where multiple implementations, test isolation, or a consequential change requires them. A wrapper that merely renames one dependency adds indirection without reducing coupling.
+
+## Cohesion Review
+
+Group code by shared reason to change. Split a module when separate owners, policies, lifecycles, or verification methods are entangled. Keep code together when splitting would scatter one invariant across files or force coordination through a vague utility layer.
+
+## Contract Checklist
+
+Define inputs, outputs, state transitions, loading and error behavior, cancellation, retries, idempotency, accessibility semantics, telemetry, and test seams. Verify package dependency direction with tooling and verify runtime ownership through journeys and failure cases.

package/knowledge-base/maintained/architecture/product-platforms.md

@@ -0,0 +1,25 @@
+# Product Platforms And Variation
+
+## Step 1: Establish Shared Scope
+
+Identify products, users, workflows, entities, quality requirements, and deployment constraints that are genuinely shared. Do not create a platform from visual similarity alone.
+
+## Step 2: Classify Variation
+
+For each difference, record whether it is required, optional, mutually exclusive, environment-specific, customer-specific, or experimental. Assign one owner and one binding time: build, deployment, startup, workspace configuration, or runtime user choice.
+
+## Step 3: Select A Mechanism
+
+- Configuration for bounded values with stable behavior.
+- Composition for replaceable behavior assembled from explicit contracts.
+- Plugins for independently delivered capabilities with lifecycle and compatibility boundaries.
+- Feature flags for controlled rollout, not permanent product modeling.
+- Separate products when shared abstractions would weaken ownership or create conditional logic everywhere.
+
+## Step 4: Protect The Platform
+
+Version extension contracts, validate configuration, isolate tenant data, define failure behavior for optional capabilities, and keep product-specific policy outside the shared core. Track compatibility, migration, deprecation, and removal.
+
+## Step 5: Evaluate Economics
+
+Measure whether reuse reduces total change cost after accounting for coordination, testing combinations, release coupling, and migration. Reopen the platform decision when variation grows faster than shared value.