flyee 0.1.0

package/core/workflows/ds-tokens.md

@@ -0,0 +1,317 @@
+---
+description: Extract and normalize design tokens from visual references.
+---
+
+Extract, normalize, and version **official Design Tokens** from visual reference materials, ensuring that **no UI code can exist without valid, up-to-date tokens**.
+
+This workflow is the **only authorized source** of design tokens in the system.
+
+---
+
+## Hard Preconditions (Abort if any fail)
+
+The workflow **MUST NOT RUN** unless all conditions below are true:
+
+1. `.agent/state/project.json` exists
+2. `project.stage === "development"`
+3. `design_system.status === "initialized"`
+4. Reference directory exists:
+
+   ```
+   src/design-system/references/
+   ```
+5. At least **one valid reference file** is present
+
+If any condition fails, abort with:
+
+```text
+/ds-tokens aborted: Design System not initialized or references missing.
+```
+---
+
+## Reference Intake Gate (Mandatory)
+
+Design Tokens MUST be derived from explicit visual references.
+
+If NO visual references are found in:
+
+src/design-system/references/
+
+Then:
+
+- DO NOT generate brand, semantic, or expressive tokens
+- Generate ONLY neutral scaffold tokens:
+  - grayscale palette
+  - base typography scale
+  - spacing, radius, shadows (neutral)
+- Set token classification as: scaffold_only
+- Mark design tokens as NOT eligible for validation
+
+This mode exists only to:
+- bootstrap the system
+- enable early infrastructure setup
+
+Scaffold tokens MUST be replaced once references are provided.
+
+---
+
+## Accepted Inputs
+
+From `src/design-system/references/`:
+
+* Images: `.png`, `.jpg`, `.jpeg`, `.webp`
+* Documents: `.pdf`
+* Markdown files with links (Figma, Dribbble, Behance)
+
+---
+
+## Execution Steps (Mandatory)
+
+---
+
+### 0️⃣ Reference Presence Check (Hard Gate)
+
+Scan directory:
+
+src/design-system/references/
+
+If directory is empty:
+
+- Enter SCAFFOLD MODE
+- Skip brand and semantic inference
+- Set internal token_state = scaffold_only
+- Continue ONLY with neutral system tokens
+
+---
+
+### 1️⃣ Load Current Project State
+
+Read from `.agent/state/project.json`:
+
+* `design_system.tokens`
+* `design_system.last_validation`
+* Previously processed references (if tracked)
+
+---
+
+### 2️⃣ Exhaustive Reference Analysis (Critical Rule)
+
+* **ALL** files in `/references` must be analyzed
+* No reference may be skipped
+* If new references are detected:
+
+  * Existing tokens are marked **OUTDATED**
+
+> ⚠️ Large reference sets must be processed iteratively while preserving state.
+
+---
+
+### 3️⃣ Token Extraction Engine (Multimodal)
+
+This step is responsible **only for inference**, not governance.
+
+---
+
+#### 🎨 Colors
+
+* Primary / Brand color
+* Neutral palette (50–900)
+* Semantic colors:
+
+  * Success
+  * Warning
+  * Error
+  * Info
+* Background / Surface / Border
+* Focus / Ring
+* Chart colors (minimum 5)
+
+✔ Generate **harmonic scales**, not raw samples
+
+---
+
+#### 🔤 Typography
+
+* Primary font family
+* Hierarchy:
+
+  * Display
+  * Heading
+  * Body
+  * Caption
+* Font sizes, weights, line heights
+* Safe fallbacks
+
+---
+
+#### 📐 Spacing & Layout
+
+* Base scale (4px or 8px)
+* Semantic spacing tokens
+* Inferred rhythm / grid
+
+---
+
+#### 🟦 Border Radius
+
+* Sharp / Rounded / Pill styles
+* Scaled tokens (`xs → xl`)
+
+---
+
+#### 🌫️ Shadows
+
+* Levels: none / sm / md / lg
+* Consistent elevation logic
+
+---
+
+### 4️⃣ Semantic Normalization (Non-Negotiable)
+
+🚫 Forbidden:
+
+* Raw numeric names (`blue-500`)
+* Hardcoded values (`#123456`)
+* Context-less tokens
+
+✅ Required naming examples:
+
+```text
+color-button-primary-bg
+color-text-muted
+radius-card
+space-section
+shadow-overlay
+```
+
+Tokens must be **semantic, contextual, and reusable**.
+
+---
+
+### 5️⃣ Official Token Artifacts Generation
+
+The following structure **MUST be generated**:
+
+```
+src/design-system/
+├── tokens/
+│   ├── colors.json
+│   ├── typography.json
+│   ├── spacing.json
+│   ├── radius.json
+│   ├── shadows.json
+│   └── index.json
+├── tokens.css        # CSS Variables
+└── tokens.ts         # Typed tokens (TS)
+```
+
+⚠️ **Tokens must NEVER be defined inside components.**
+
+---
+
+### 6️⃣ UI Integration Layer (If Applicable)
+
+If using Tailwind / shadcn:
+
+* Map tokens into `globals.css`
+* Support **light and dark modes**
+* Zero hardcoded UI values allowed
+
+`globals.css` is a **consumer**, never the source of truth.
+
+---
+
+### 7️⃣ Project State Update (Mandatory)
+
+If token_state === "scaffold_only":
+
+```json
+"design_system": {
+  "status": "initialized",
+  "tokens": "scaffold_only",
+  "token_origin": "scaffold",
+  "components": "missing",
+  "styleguide": "missing",
+  "validated": false
+}
+````
+
+If token_state === "reference_based":
+
+```json
+"design_system": {
+  "status": "initialized",
+  "tokens": "ready",
+  "token_origin": "visual_reference",
+  "components": "missing",
+  "styleguide": "missing",
+  "validated": false
+}
+
+```
+
+---
+
+### 8️⃣ Artifact Registration
+
+Append to project artifacts:
+
+```json
+"artifacts": {
+  "documents": ["Design tokens generated from visual references"],
+  "code": ["src/design-system/tokens/*"],
+  "prompts": ["/ds-tokens"]
+}
+```
+
+---
+
+## Postconditions (Guaranteed)
+
+After successful execution:
+
+* Tokens exist and are versioned
+* Tokens reflect **all references**
+* Tokens are semantic and accessible
+* UI generation remains **BLOCKED**
+* Next mandatory step is `/ds-validate`
+
+---
+
+## Standard Output Format
+
+```text
+Design System Tokens: READY
+References Processed: 8
+New References Detected: true
+Token Status: NORMALIZED
+Next Required Action: /ds-validate
+UI Generation: BLOCKED
+```
+
+---
+
+## Golden Rules (Non-Negotiable)
+
+* Tokens are evidence, not opinion
+* New references invalidate existing tokens
+* Tokens ≠ UI
+* Without `/ds-validate`, nothing passes
+
+---
+
+## `/next-step` Integration
+
+`/next-step` MUST interpret:
+
+```text
+design_system.tokens === "ready"
+design_system.validated === false
+```
+
+As:
+
+```text
+BLOCK UI
+NEXT ACTION: /ds-validate
+```

package/core/workflows/ds-validate.md

@@ -0,0 +1,309 @@
+---
+description: Validate the entire Design System for correctness, consistency, accessibility, and documentation completeness.
+---
+
+Validate that the Design System is **complete, consistent, accessible, and enforceable** before **any UI, feature, or page** is allowed to be generated.
+
+This workflow acts as a **hard stop** in the system.
+Failure blocks **all downstream execution**.
+
+---
+
+## Hard Preconditions (Abort if any fail)
+
+The workflow **MUST NOT RUN** unless **all** conditions below are met:
+
+1. `.agent/state/project.json` exists
+2. `project.stage === "development"`
+3. `design_system.status === "initialized"`
+4. `design_system.tokens === "ready"`
+5. Token artifacts exist:
+
+   ```
+   src/design-system/tokens/
+   ```
+6. At least one token consumer exists:
+
+   * `tokens.css` **OR**
+   * `globals.css`
+
+If any condition fails, abort with:
+
+```text
+/ds-validate aborted: Design System not ready for validation.
+```
+---
+
+## Reference Origin Gate (Critical)
+
+The validation workflow MUST HARD FAIL if design tokens
+were not generated from visual references.
+
+Required condition:
+
+```text
+design_system.token_origin === "visual_reference"
+```
+
+If the condition is not met, abort with:
+
+```text
+/ds-validate aborted: Tokens are scaffold-only. Visual references required.
+```
+
+This rule is ABSOLUTE.
+No override, no partial validation, no warnings.
+
+---
+
+## Validation Scope (Non-Negotiable)
+
+Validation applies to **all layers**:
+
+* Design Tokens
+* Component Specifications (if any)
+* Styling Integration
+* Accessibility
+* Governance Compliance
+
+---
+
+## Execution Phases
+
+---
+
+### 1️⃣ Load Project State & Artifacts
+
+Read from:
+
+* `.agent/state/project.json`
+* `src/design-system/tokens/*`
+* `tokens.css` / `globals.css`
+* Existing component specs (if present)
+
+---
+
+### 2️⃣ Design Token Integrity Validation
+
+#### Required Checks
+
+* Tokens are **semantic**, not numeric
+* No duplicated meanings
+* No missing mandatory categories:
+
+  * Colors
+  * Typography
+  * Spacing
+  * Radius
+  * Shadows
+
+🚫 FAIL if:
+
+* Hardcoded values detected
+* Token names reference raw values
+* Tokens are defined inside components
+
+---
+
+### 3️⃣ Structural Consistency Validation
+
+* JSON schema integrity
+* Cross-file references resolve correctly
+* Token index completeness
+* No orphan or unused core tokens
+
+🚫 FAIL if:
+
+* Broken references exist
+* Schema mismatch detected
+
+---
+
+### 4️⃣ UI Integration Validation
+
+* CSS variables are generated correctly
+* Light and Dark themes exist (if required)
+* All UI styles reference tokens
+* No inline styles or magic numbers
+
+🚫 FAIL if:
+
+* Components bypass token usage
+* globals.css contains raw values
+
+---
+
+### 5️⃣ Component Readiness Validation (If Components Exist)
+
+If `design_system.components !== "missing"`:
+
+* Each component must declare:
+
+  * Token dependencies
+  * Variants
+  * States
+* No visual values defined locally
+
+🚫 FAIL if:
+
+* Components define colors, spacing, or fonts directly
+
+---
+
+### 6️⃣ Accessibility & Contrast Validation (WCAG 2.1 AA)
+
+* Text contrast ≥ AA
+* Interactive elements distinguishable
+* Focus and hover states visible
+* Semantic color usage respected
+
+🚫 FAIL if:
+
+* Any AA contrast violation exists
+
+---
+
+### 7️⃣ Governance & Rule Enforcement
+
+Verify compliance with:
+
+* `project.rules.md`
+* Locked decisions
+* Design System rules
+
+🚫 FAIL if:
+
+* Locked decisions violated
+* UI generated before validation
+* Unauthorized workflow execution detected
+
+Verify token origin integrity:
+
+- Tokens MUST be derived from visual references
+- Scaffold tokens are NOT eligible for validation
+- Token origin must be traceable in project state
+
+🚫 FAIL if:
+
+- design_system.token_origin !== "visual_reference"
+
+---
+
+### 8️⃣ Validation Report Generation
+
+Generate a **machine-readable** and **human-readable** report:
+
+```
+src/design-system/validation/
+├── ds-validation-report.json
+└── ds-validation-report.md
+```
+
+Report MUST include:
+
+* PASS / FAIL status
+* Failed checks (if any)
+* Blocking issues
+* Required remediation steps
+
+---
+
+### 9️⃣ Project State Update (Conditional)
+
+#### On PASS:
+
+```json
+"design_system": {
+  "status": "validated",
+  "tokens": "ready",
+  "token_origin": "visual_reference",
+  "components": "ready",
+  "styleguide": "missing",
+  "validated": true,
+  "locked": true,
+  "last_validation": "ISO_TIMESTAMP"
+}
+
+```
+
+#### On FAIL:
+
+* `validated` remains `false`
+* State is NOT advanced
+
+---
+
+## Standard Output Format (Mandatory)
+
+```text
+Design System Validation: PASS
+Token Integrity: PASS
+Structural Consistency: PASS
+Accessibility: PASS
+Governance Compliance: PASS
+
+Next Allowed Action: UI / Feature generation
+```
+
+OR
+
+```text
+Design System Validation: FAIL
+Blocking Issues: 3
+Critical Violations Detected
+Next Required Action: Fix tokens or components
+UI Generation: BLOCKED
+```
+
+---
+
+## Postconditions
+
+### On PASS
+
+* Design System is LOCKED
+* Tokens and component decisions become immutable
+* UI generation is officially allowed
+
+### On FAIL
+
+* System remains blocked
+* No downstream workflow may proceed
+
+---
+
+## Golden Rules (Hard Law)
+
+* Validation is final authority
+* No partial passes
+* No silent bypass
+* Governance > Speed
+
+---
+
+## `/next-step` Integration (Mandatory)
+
+`/next-step` MUST interpret:
+
+```text
+design_system.validated === true
+```
+
+As:
+
+```text
+ALLOW UI / FEATURE GENERATION
+```
+
+And:
+
+```text
+design_system.validated === false
+```
+
+As:
+
+```text
+BLOCK ALL UI
+NEXT ACTION: /ds-validate
+```