flyee 0.1.0

package/core/workflows/ds-components.md

@@ -0,0 +1,296 @@
+---
+description: Create, extend, and document Design System components using **shadcn/ui as the canonical base**, strictly governed by Design Tokens and Design System validation rules.
+---
+
+This workflow guarantees:
+
+* Visual consistency
+* Token-only styling
+* Proper documentation
+* Safe scalability of UI components
+
+---
+
+## HARD PRECONDITIONS (NON-NEGOTIABLE)
+
+Before execution, **ALL** conditions below MUST be true:
+
+* `design_system.validated === true`
+* `design_system.tokens === "ready"`
+* `design_system.token_origin !== "scaffold_only"`
+* `shadcn/ui` is initialized
+* `src/app/globals.css` exists
+* No pending blocking issues from `/next-step`
+* `/next-step` status === "ALLOW_COMPONENTS"
+
+
+❌ If any condition fails → **BLOCK execution**
+✅ Output reason + required corrective command
+
+---
+
+## INPUT
+
+* Component name (required)
+* Optional customization requirements (variants, states, behaviors)
+
+Example:
+
+```
+/ds-components Button
+```
+
+---
+
+## WORKFLOW STEPS
+
+---
+
+### 1. Component Discovery (shadcn Registry)
+
+Use shadcn MCP to determine if the component exists.
+
+#### Actions
+
+* `search_items_in_registries` → query: `[component-name]`
+
+#### Decision
+
+* If found → go to **Step 2**
+* If NOT found → go to **Step 4**
+
+---
+
+### 2. Install Base Component (shadcn)
+
+Retrieve install command:
+
+* `get_add_command_for_items`
+
+Execute:
+
+```bash
+npx shadcn@latest add [component-name]
+```
+
+#### Post-install Verification
+
+* Component created in `/components/ui/`
+* Uses Tailwind classes mapped to CSS variables
+* No hardcoded colors, spacing, or fonts
+
+---
+
+### 3. Optional Customization (Extension Layer)
+
+If the base component requires project-specific behavior or variants:
+
+#### Rules
+
+* ❌ Never modify files in `/components/ui/`
+* ✅ Create wrapper in `/components/[ComponentName].tsx`
+* ✅ Use CSS variables only (`bg-primary`, `text-muted-foreground`, etc.)
+
+#### Example Pattern
+
+```tsx
+import { Button } from "@/components/ui/button"
+import { cn } from "@/lib/utils"
+
+interface CustomButtonProps extends React.ComponentProps<typeof Button> {
+  intent?: "default" | "success" | "warning" | "info"
+}
+
+export function CustomButton({
+  intent = "default",
+  className,
+  ...props
+}: CustomButtonProps) {
+  return (
+    <Button
+      className={cn(
+        intent === "success" && "bg-success text-success-foreground",
+        intent === "warning" && "bg-warning text-warning-foreground",
+        intent === "info" && "bg-info text-info-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+```
+
+---
+
+### 4. Build Custom Component (If Not in shadcn)
+
+If the component does not exist in shadcn:
+
+#### Rules
+
+* Use shadcn primitives and patterns
+* Use Tailwind + CSS variables exclusively
+* Follow accessibility best practices (ARIA, keyboard support)
+
+#### Example
+
+```tsx
+import { cn } from "@/lib/utils"
+
+interface CustomWidgetProps {
+  variant?: "default" | "primary" | "muted"
+  className?: string
+  children: React.ReactNode
+}
+
+export function CustomWidget({
+  variant = "default",
+  className,
+  children,
+}: CustomWidgetProps) {
+  return (
+    <div
+      className={cn(
+        "rounded-lg border p-4",
+        variant === "default" && "bg-card text-card-foreground border-border",
+        variant === "primary" && "bg-primary text-primary-foreground border-primary",
+        variant === "muted" && "bg-muted text-muted-foreground border-border",
+        className
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+```
+
+---
+
+### 5. Generate Component Showcase (MANDATORY)
+
+Create:
+
+```
+src/app/styleguide/components/[component-name]/page.tsx
+```
+
+#### Must Include
+
+* All variants
+* All states (default, hover, focus, disabled, loading)
+* Light & Dark mode (using Theme Toggle)
+* Interactive examples
+* Code snippets
+
+❌ If showcase is missing → component is considered **incomplete**
+
+❌ If the component exists in `/components/` but has no showcase page
+→ Treat as INVALID
+→ Must not be referenced by any UI or page
+
+
+---
+
+### 6. Document Usage
+
+Inside the showcase page, document:
+
+* Import path
+* Basic usage
+* Props table (types + defaults)
+* Variant examples
+* Accessibility notes
+
+---
+
+### 7. Update Styleguide Navigation
+
+Update:
+
+```
+src/app/styleguide/navigation.ts
+```
+
+Add entry:
+
+```ts
+{
+  name: "[Component Name]",
+  href: "/styleguide/components/[component-name]"
+}
+```
+
+---
+
+### 8. Validation Check (Component-Level)
+
+Before completion, validate:
+
+* No hardcoded styles
+* Uses only tokens from `globals.css`
+* Renders correctly in light and dark mode
+* Matches shadcn patterns
+* Passes accessibility baseline
+
+❌ If any check fails → BLOCK completion
+
+---
+
+### Project State Update (Mandatory)
+
+{
+  "design_system": {
+    "components": "in_progress",
+    "last_component_added": "[component-name]",
+    "last_updated": "ISO_TIMESTAMP"
+  }
+}
+
+
+---
+
+## OUTPUT
+
+* Component installed or created
+* Optional custom wrapper added
+* Showcase page generated
+* Styleguide navigation updated
+* Component visible and interactive in `/styleguide`
+
+---
+
+## POST-CONDITIONS
+
+On success:
+
+* Component is approved for reuse
+* Component becomes part of the official Design System
+* No further UI generation is blocked by this component
+
+---
+
+## AUTHORITY & RESTRICTIONS
+
+* This workflow is the **ONLY allowed way** to create components
+* Manual UI component creation outside this workflow is forbidden
+* Tokens are immutable during this workflow
+* Design decisions are LOCKED
+
+---
+
+## RELATED WORKFLOWS
+
+* `/ds-init`
+* `/ds-tokens`
+* `/ds-validate`
+* `/ds-styleguide`
+* `/next-step`
+
+---
+
+## FINAL NOTE
+
+> **shadcn defines structure.
+> Tokens define identity.
+> The styleguide proves correctness.**
+

package/core/workflows/ds-init.md

@@ -0,0 +1,58 @@
+---
+description: Initialize a production-ready Design System using shadcn/ui.
+---
+
+## STEPS
+
+1. Verify if the project uses Next.js App Router.
+   - If not, abort and request explicit user confirmation.
+
+2. Initialize shadcn/ui as the **UI infrastructure layer**:
+   - Run `npx shadcn@latest init`
+   - Use default style
+   - Enable CSS variables
+   - Select neutral base color
+
+   ⚠️ Important:
+   - shadcn/ui DOES NOT define the Design System
+   - It only provides the structural and technical foundation
+   - All visual identity will be overridden by Design Tokens
+
+3. Verify that `/app/globals.css` exists.
+   - If missing, create it.
+
+4. Inject a **minimal and provisional** CSS variable scaffold into `globals.css`:
+   - Background
+   - Foreground
+   - Primary
+   - Secondary
+   - Muted
+   - Accent
+   - Destructive
+   - Border
+   - Radius
+   - Light and Dark mode blocks
+
+   ⚠️ Rules:
+   - Values are placeholders only
+   - No brand decisions are allowed here
+   - These variables MUST be replaced by `/ds-tokens`
+
+5. Ensure Tailwind is configured to consume CSS variables:
+   - colors
+   - borderRadius
+   - shadows
+   - typography (if applicable)
+
+6. Scan the project for existing UI components:
+   - If hardcoded styles are found:
+     - Emit warnings
+     - Do NOT fail initialization
+     - Block UI generation in `/next-step` until resolved
+
+## OUTPUT
+- shadcn/ui initialized as infrastructure
+- globals.css prepared with provisional tokens
+- Tailwind configured for token consumption
+- Design System marked as `initialized`
+- Project ready for `/ds-tokens`

package/core/workflows/ds-refactor.md

@@ -0,0 +1,245 @@
+---
+description: This workflow provides a controlled, auditable, and user-authorized mechanism to refactor existing UI code so it fully complies with the Design System, without redoing the design. It exists **only** to remediate violations detected by `/ds-validate` 
+---
+
+## PURPOSE
+
+Safely convert **non-compliant UI code** (hardcoded values, inline styles, token bypasses) into **token-only, governance-compliant code**, while:
+
+* Preserving visual output
+* Preserving component structure
+* Preserving locked design decisions
+* Maintaining full auditability
+
+---
+
+## HARD PRECONDITIONS (NON-NEGOTIABLE)
+
+The workflow **MUST NOT RUN** unless **ALL** conditions are met:
+
+1. `design_system.validated === false`
+2. A `/ds-validate` run exists with status **FAIL**
+3. Validation report exists at:
+
+   ```
+   src/design-system/validation/ds-validation-report.json
+   ```
+4. Violations include **auto-fixable types only** (see classification below)
+5. User has explicitly invoked `/ds-refactor`
+
+❌ If any condition fails → **ABORT**
+
+---
+
+## AUTO-FIXABLE VIOLATION TYPES
+
+Only the following violations are eligible:
+
+| Type              | Description                                         |
+| ----------------- | --------------------------------------------------- |
+| `hardcoded_color` | Hex/RGB values replaceable by existing color tokens |
+| `inline_style`    | Inline styles convertible to Tailwind token classes |
+| `raw_spacing`     | Numeric spacing matching existing spacing tokens    |
+| `raw_radius`      | Border-radius values matching radius tokens         |
+
+❌ NOT ELIGIBLE:
+
+* Missing tokens
+* New variants
+* Layout changes
+* Visual hierarchy changes
+* Behavioral logic changes
+
+---
+
+## INPUT
+
+```text
+/ds-refactor
+```
+
+Optional:
+
+```text
+/ds-refactor --apply
+```
+
+---
+
+## WORKFLOW STEPS
+
+---
+
+### 1️⃣ Load Validation Artifacts
+
+Read:
+
+* `ds-validation-report.json`
+* Affected source files
+* `globals.css`
+* Design token definitions
+
+---
+
+### 2️⃣ Violation Classification
+
+For each violation, produce a structured record:
+
+```json
+{
+  "file": "goal-card.tsx",
+  "violation_type": "hardcoded_color",
+  "original": "#0F172A",
+  "mapped_token": "bg-card",
+  "confidence": "high"
+}
+```
+
+If **any** violation cannot be deterministically mapped → **BLOCK** workflow.
+
+---
+
+### 3️⃣ Patch Generation (Dry Run)
+
+Generate **diff-only patches**.
+
+Example:
+
+```diff
+- backgroundColor: "#0F172A"
++ className="bg-card"
+```
+
+Rules:
+
+* ❌ No file writes
+* ❌ No formatting changes
+* ❌ No refactors beyond token replacement
+
+---
+
+### 4️⃣ Review Summary (MANDATORY STOP)
+
+Output a summary:
+
+```text
+Auto-refactor candidates detected
+Files: 6
+Total changes: 19
+
+Affected files:
+- goal-card.tsx
+- meeting-card.tsx
+- feature-card.tsx
+- documents-card.tsx
+- lead-card.tsx
+- summary-card.tsx
+
+Authorize application?
+/ds-refactor --apply
+```
+
+❌ Without explicit authorization → **STOP**
+
+---
+
+### 5️⃣ Apply Patches (Authorized Only)
+
+When invoked with `--apply`:
+
+* Apply generated diffs
+* Preserve original formatting
+* Do NOT introduce new tokens
+* Do NOT alter component APIs
+
+---
+
+### 6️⃣ Build & Sanity Check
+
+* Run build
+* Verify no runtime errors
+* Ensure visual output unchanged (best-effort)
+
+❌ On failure → rollback changes
+
+---
+
+### 7️⃣ Re-run Validation
+
+Automatically invoke:
+
+```
+/ds-validate
+```
+
+---
+
+### 8️⃣ Audit Log Generation
+
+Create:
+
+```
+src/design-system/audit/ds-refactor-log.md
+```
+
+Include:
+
+* Timestamp
+* Files changed
+* Tokens used
+* Validation result (PASS/FAIL)
+* User authorization confirmation
+
+---
+
+## OUTPUT
+
+### On Success
+
+```text
+Design System Refactor: COMPLETE
+Validation: PASS
+UI Generation: UNBLOCKED
+```
+
+### On Failure
+
+```text
+Design System Refactor: PARTIAL / FAILED
+Remaining Violations: X
+Next Action: Manual remediation required
+UI Generation: BLOCKED
+```
+
+---
+
+## GOVERNANCE RULES (HARD LAW)
+
+* No silent fixes
+* No automatic application
+* No token mutation
+* No visual redesign
+* Full auditability required
+
+---
+
+## `/next-step` INTEGRATION
+
+`/next-step` MUST interpret:
+
+```text
+ds-validate FAIL + auto-fixable violations
+```
+
+As:
+
+```text
+NEXT ACTION: /ds-refactor
+```
+
+---
+
+## FINAL PRINCIPLE
+
+> **Refactoring is correction, not redesign.**
+> **Governance is preserved, velocity is restored.**