@ztothez/design-engineering 2.0.0

package/knowledge-base/design-intelligence/figma-production.md

@@ -0,0 +1,63 @@
+# Figma Production Workflow
+
+Use Figma as a structured implementation contract. A visually complete canvas with detached layers, raw values, and undocumented states is not a design system.
+
+## Step 1: Establish File Architecture
+
+Give each page one role and stated purpose. A maintained library requires at least foundations and components. Add patterns, templates, sandbox, archive, or cover pages only when they have an owner and lifecycle.
+
+Keep exploration separate from published assets. Move obsolete work to archive rather than leaving near-duplicate components in active pages.
+
+## Step 2: Map Tokens To Variables
+
+Create primitive values first, semantic aliases second, and component aliases only where local state or variation warrants them. Group variables by responsibility rather than by arbitrary color name.
+
+Use modes for genuine contexts such as light and dark themes, density, device class, language, or brand. Avoid duplicating frames merely to express a mode. Verify every mode independently, including contrast and missing aliases.
+
+Figma supports variables, aliases, collections, modes, and design-token import using the Design Tokens Community Group format. Keep one canonical token source and define the direction of synchronization between code and Figma. Do not allow independent edits on both sides without conflict policy.
+
+## Step 3: Engineer Components
+
+For every component:
+
+1. State its purpose and ownership.
+2. Use auto layout for content-driven dimensions and stable spacing.
+3. Expose only useful text, boolean, instance-swap, variant, or slot properties.
+4. Use variants for meaningful states or configurations, not every stylistic permutation.
+5. Declare default and focus states for interactive components. Add hover, active, disabled, loading, selected, error, success, or empty states where behavior requires them.
+6. Define resizing, truncation, wrapping, minimum size, and maximum-content behavior.
+7. Add usage, content, accessibility, and prohibited-use documentation.
+
+Prefer composition and slots over deeply nested overrides. Name properties by user-visible meaning, not internal layer names.
+
+## Step 4: Build Patterns And Templates
+
+Patterns combine components around a task, state model, and responsive behavior. Templates provide a starting structure without hiding required product decisions.
+
+For every pattern or template, include:
+
+- Primary task and success condition.
+- Data and state assumptions.
+- Empty, loading, partial, error, and permission states.
+- Mobile and long-content examples.
+- Keyboard and focus expectations.
+- Implementation notes that identify semantic tokens and component contracts.
+
+## Step 5: Handoff With Evidence
+
+Before publishing:
+
+- Inspect detached instances and raw values.
+- Verify component property names and defaults.
+- Exercise all modes and representative variants.
+- Check long strings, localization, and text resizing.
+- Compare Figma token names with the canonical token source.
+- Export a small implementation sample and confirm assets, dimensions, and states survive handoff.
+- Record library version, owner, breaking changes, and migration notes.
+
+The manifest validator checks declared structure and references. It does not connect to Figma or verify the actual file. Inspect the source file or use an approved Figma integration for final evidence.
+
+## Official Platform References
+
+- [Figma variables, collections, aliases, and modes](https://help.figma.com/hc/en-us/articles/14506821864087-Overview-of-variables-collections-and-modes)
+- [Figma component properties](https://help.figma.com/hc/en-us/articles/5579474826519-Explore-component-properties)

package/knowledge-base/design-intelligence/generation-adapter.md

@@ -0,0 +1,72 @@
+# React And TypeScript Generation Adapter
+
+Current adapter version: `1.2.1`.
+
+Use this adapter only after a product design brief compiles to a design plan with `status: ready`
+and `implementationReady: true`. It creates a new independent React, TypeScript, and Vite fixture.
+It does not merge into an existing application, repair an original product, prove visual quality,
+or authorize release. A separate bounded workflow in `closed-loop-repair.md` can repair an exact
+finding in a manifest-owned generated fixture only.
+
+## Input Gate
+
+1. Validate the source brief and all four downstream contract declarations.
+2. Compile the brief and preserve the complete design-plan artifact.
+3. Stop when the plan is blocked or provisional. Never edit compiled readiness fields manually.
+4. Provide an existing real generation root, one absent child output path, and a passing portfolio
+   registry. The adapter refuses existing output, symlinked parents, traversal, and any target that
+   overlaps a portfolio root.
+5. Keep the portfolio registry local. Its absolute paths authorize denial checks and must not enter
+   generated files or reports.
+
+## Generated Architecture
+
+The initial `react-typescript-vite` adapter generates:
+
+- A complete local demonstration task and a disconnected-source recovery path.
+- Reducer-owned task state separate from rendering and source-boundary declarations.
+- Separate demo, imported, cached, and live modes with origin, freshness, connection, and
+  limitation text. Missing live, import, or cache evidence remains unavailable rather than
+  borrowing demonstration values.
+- Primitive and semantic CSS tokens, responsive composition, visible focus, minimum target
+  geometry, non-color status labels, and reduced-motion behavior.
+- Opt-in composition markers for context, primary outcome, next action, density limits, status
+  purpose, state cues, and evidence-backed visual claims. The primary action precedes supporting
+  telemetry in semantic order.
+- Unit tests, build and typecheck scripts, a traceable plan summary, and a checksummed deterministic
+  generation manifest.
+- A development and preview response header that identifies the generation plan to bounded repair.
+
+The adapter interpolates only validated plan data into a generated constant. It never treats plan
+text as executable source and never imports implementation from an external design product.
+
+## Command
+
+```bash
+zz-design generate-react \
+  --plan path/to/ready-design-plan.json \
+  --generation-root .ztothez-design-generated \
+  --output .ztothez-design-generated/example-app \
+  --portfolio-registry .ztothez-design-local/portfolio-registry.yaml \
+  --json
+```
+
+Create the generation root before running the command. The output directory must not exist. Use
+`generation-adapter.schema.yaml` to validate the generated `ztothez-design-generation.json` file.
+
+## Evidence Boundary
+
+- Deterministic files and checksums prove repeatable transformation for the same plan and adapter
+  version. They do not prove the chosen design is desirable.
+- Static audit and generated unit tests prove only the implemented source rules and reducer paths.
+- Live connectivity remains unimplemented until a real target adapter receives authenticated
+  runtime evidence. Imported and cached modes remain unavailable until valid records exist.
+- The adapter emits composition semantics but does not claim they passed. Run browser verification
+  at 375, 768, 1024, and 1440 CSS pixels in every implemented color scheme. Security, integration,
+  usability, and attributable human review remain later gates.
+- Existing-repository adaptation is outside version 1.0. Use the independent fixture path until a
+  separate convention-aware merge adapter has its own containment and regression evidence.
+- Finding-bound remediation of this generated output must use `zz-design repair-react`. Never use
+  that command as an existing-repository merge or product migration mechanism.
+- Bounded repair must reject runtime evidence when `X-ZtotheZ-Design-Plan` is missing or does not
+  equal the plan ID in the generated manifest.

package/knowledge-base/design-intelligence/generation-adapter.schema.yaml

@@ -0,0 +1,47 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://ztothez.dev/schemas/generation-adapter-1.0.schema.json
+title: ZtotheZ React And TypeScript Generation Manifest
+type: object
+additionalProperties: false
+required: [version, adapter, adapterVersion, plan, outputMode, files, guarantees, limitations]
+properties:
+  version:
+    const: "1.0"
+  adapter:
+    const: react-typescript-vite
+  adapterVersion:
+    type: string
+    pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+  plan:
+    type: object
+    additionalProperties: false
+    required: [id, sourceDigest, compilerVersion]
+    properties:
+      id: { type: string, minLength: 1, maxLength: 256 }
+      sourceDigest: { type: string, pattern: "^[a-f0-9]{64}$" }
+      compilerVersion: { type: string, pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$" }
+  outputMode:
+    const: new-independent-fixture
+  files:
+    type: array
+    minItems: 1
+    items:
+      type: object
+      additionalProperties: false
+      required: [path, digest, bytes]
+      properties:
+        path:
+          type: string
+          minLength: 1
+          maxLength: 1024
+          pattern: "^(?!/)(?!.*(?:^|/)[.][.](?:/|$)).+$"
+        digest: { type: string, pattern: "^[a-f0-9]{64}$" }
+        bytes: { type: integer, minimum: 0 }
+  guarantees:
+    type: array
+    minItems: 1
+    items: { type: string, minLength: 1, maxLength: 1024 }
+  limitations:
+    type: array
+    minItems: 1
+    items: { type: string, minLength: 1, maxLength: 1024 }

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

@@ -0,0 +1,46 @@
+# Iconography
+
+An icon system is a semantic vocabulary with controlled geometry. It is not a folder of unrelated glyphs.
+
+## Step 1: Inventory Meanings
+
+List the actions, objects, statuses, navigation destinations, and domain concepts that need icons. Remove duplicate meanings and distinguish actions from states. Prefer familiar platform or product conventions when they are clear in context.
+
+Use text instead of inventing a glyph for an abstract concept users will not recognize. Pair unfamiliar icons with visible labels. Do not use Unicode symbols as inconsistent icon fallbacks.
+
+## Step 2: Choose The Source Strategy
+
+Reuse the product's approved icon library when one exists. Add custom icons only for domain meanings the library cannot express. Keep all source assets and licenses in the manifest.
+
+Do not combine outline, filled, duotone, and hand-drawn systems without an explicit semantic reason. If filled icons indicate selected state, document and test that rule consistently.
+
+## Step 3: Define Geometry
+
+Declare:
+
+- Base grid and key sizes.
+- Stroke style, weight, caps, and joins.
+- Corner behavior and optical overshoot.
+- Bounding box, padding, baseline, and alignment.
+- Filled-area and detail limits at the smallest size.
+- Mirroring and localization rules.
+
+Review icons at native size. Mathematically aligned shapes can still need optical correction.
+
+## Step 4: Define Semantics And Accessibility
+
+Every icon needs one documented meaning. A semantic icon requires an accessible name unless equivalent visible text labels the same control. Decorative icons must be hidden from assistive technology and must not receive redundant names.
+
+Never rely on icon color alone for status. Combine it with text, shape, placement, value, or another cue. Ensure active, disabled, destructive, and focus treatments use semantic tokens and pass non-text contrast where required.
+
+## Step 5: Package And Verify
+
+- Use stable lowercase identifiers.
+- Optimize SVG paths without flattening meaningful structure needed by the implementation.
+- Remove editor metadata and unexpected embedded raster content.
+- Preserve `viewBox` and test scaling.
+- Expose icons through the existing icon component or library adapter.
+- Add automated snapshots or rendering checks for the supported sizes.
+- Test bidirectional layouts and high-contrast modes where applicable.
+
+The design manifest checks identifier uniqueness, asset references, and semantic naming. It does not inspect SVG geometry or the accessible implementation.

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

@@ -0,0 +1,104 @@
+# Operational Information Design
+
+Use this module for dashboards, workspaces, reports, monitoring surfaces, findings queues, and any interface that presents metrics or charts to support a decision. Create an `information-design.yaml` from `information-design.template.yaml` before treating an operational surface as implementation-ready.
+
+This contract defines decision structure. It does not award visual quality, prove runtime calculations, or substitute task declarations for attributable human evidence.
+
+## Required Answer Flow
+
+Make the surface answer these questions in order:
+
+1. What environment, scope, data, source, and freshness am I viewing?
+2. What changed or requires attention now?
+3. What is the operational, financial, security, user, compliance, or reliability impact?
+4. What evidence supports the conclusion?
+5. What action should happen next, and who or what receives it?
+6. How will success be verified?
+
+Do not begin with a wall of equal-weight cards. Establish context and the primary outcome first, then exceptions, impact, findings, telemetry, evidence, and records.
+
+## Step 1: Establish Context And Provenance
+
+Declare the environment, scope, data description, source references, freshness, and limitations. Use explicit current, stale, unknown, or not-applicable freshness states. Current and stale data require an offset timestamp and IANA timezone.
+
+Treat source, freshness, and comparison baseline as separate facts. A current API response does not prove that a derived metric uses the same scope. A comparison is unavailable until its baseline source and period are declared.
+
+## Step 2: Define Decision Metrics
+
+For every metric, declare:
+
+- Label and plain-language definition.
+- Formula, including exclusions and aggregation behavior.
+- Source references, context, scope, and time period.
+- Freshness and comparison baseline, or a reason the baseline is unknown or not applicable.
+- Drill-down destination and limitations.
+- The question it answers and the action it supports.
+- Label and value-state policies.
+
+Reject decorative metrics. A large number, trend arrow, status ring, or chart without a supported decision and drill-down consumes attention without helping the task.
+
+Use explicit value behavior for `loading`, `available`, `missing`, `partial`, `stale`, and `error`. Never render missing as zero, partial as complete, or stale as current.
+
+## Step 3: Structure Findings
+
+Every finding must include severity, affected entity, observation, evidence, impact, confidence and basis, remediation, destination, and validation method. Preserve the path from finding to evidence to action to verification.
+
+Do not use color as the only severity or state cue. Pair color with readable text, an icon, value, shape, pattern, or stable position. Do not infer confidence from severity; record them independently.
+
+## Step 4: Justify Charts
+
+Each chart must declare its source metrics, supported decision, drill-down, value-state policy, and accessible table or text alternative. Show a title and readable values. Show a legend or explain the direct-labeling strategy.
+
+Remove a chart when a sentence, value, or table answers the task more directly. Never use charts as decorative proof that a dashboard is sophisticated.
+
+## Step 5: Handle Labels And Collections
+
+Wrap long labels by default. If truncation is necessary, provide keyboard and assistive-technology-accessible full text. Do not depend on pointer hover.
+
+For collections over 100 items, use pagination or virtualization, provide search, and provide filtering or sorting. Declare empty, partial, and stale states. Test realistic long entity names, absent values, partial responses, stale records, and maximum expected collection size.
+
+## Step 6: Apply The Eight-Level Hierarchy
+
+Use this exact order for operational surfaces:
+
+1. `context-provenance`
+2. `primary-outcome-action`
+3. `critical-exceptions`
+4. `health-impact-metrics`
+5. `prioritized-findings`
+6. `operational-telemetry`
+7. `evidence-audit-trail`
+8. `history-exports`
+
+Levels may share records, but each level needs declared content. Responsive layouts may change geometry, not the semantic order.
+
+## Step 7: Declare Review Tasks
+
+Add one or more structured tasks for all six answer questions: context, priority, impact, evidence, next action, and success verification. Reference the exact contract records needed for the expected answer and require non-color cues.
+
+These task declarations prepare expert and representative-user review. They are not evidence that a person understood or completed the task. Record attributable review evidence separately under the V2 evidence workflow.
+
+## Step 8: Validate And Verify
+
+Validate the declaration:
+
+```bash
+npm run validate-information -- --contract PATH
+```
+
+Or use the MCP tool `validate_information_design`.
+
+Resolve every error before implementation is information-design complete. Then verify rendered hierarchy, responsive reflow, value states, keyboard access, chart alternatives, and task comprehension separately.
+
+## Rejection Patterns
+
+- KPI cards with no definition, formula, source, period, or decision.
+- Green and red states with no text or icon semantics.
+- Charts that repeat a headline number without adding a comparison or diagnostic path.
+- Findings without affected entities, evidence, remediation, ownership, or validation.
+- Missing values displayed as zero or hidden.
+- Stale values without timestamps, timezone, scope, and limitation.
+- Ellipsized labels that cannot be revealed without a pointer.
+- Unbounded tables that render thousands of rows without retrieval controls.
+- Equal visual priority for context, exceptions, telemetry, history, and exports.
+- Agent-authored task declarations presented as representative-user validation.