@polymorphism-tech/morph-spec 4.3.6 → 4.5.0

package/framework/templates/docs/spec.md

@@ -1,149 +1,149 @@
-# Feature Specification: {{titleCase FEATURE_NAME}}
-
-| Field | Value |
-|-------|-------|
-| **ID** | {{FEATURE_NAME}} |
-| **Status** | Draft / In Review / Approved / In Progress / Done |
-| **Created** | {{DATE}} |
-| **Stack** | {{STACK}} |
-| **Complexity** | Low / Medium / High |
-| **Estimated Cost** | $X/month |
-| **Agents** | Core: All / Specialists: {list} |
-
----
-
-## Overview
-
-**Problem:** {What problem this feature solves}
-
-**Solution:** {High-level solution}
-
-**Success Criteria:**
-- [ ] {Criterion 1}
-- [ ] {Criterion 2}
-
----
-
-## Requirements
-
-**Functional:** FR1: {desc} | FR2: {desc} | FR3: {desc}
-
-**Non-Functional:** NFR1: Performance - {target} | NFR2: Reliability - {target}
-
----
-
-## User Stories
-
-### US001: {Title}
-**As** {user type} **I want** {feature} **so that** {benefit}
-
-**Acceptance Criteria:** 1. {criterion} 2. {criterion}
-
-**Edge Cases:** {edge case}: {handling}
-
----
-
-## Technical Design
-
-### Stack
-| Component | Technology |
-|-----------|------------|
-| Frontend | {Blazor Server / Next.js} |
-| Backend | .NET 10 / C# 14 |
-| Database | {Azure SQL / Cosmos DB} |
-
-### Data Model
-
-#### {EntityName}
-| Column | Type | Constraints |
-|--------|------|-------------|
-| Id | Guid | PK |
-| {Property} | {Type} | {Constraints} |
-| CreatedAt | datetime2 | Default: GETUTCDATE() |
-
-### Contracts
-
-> **Ref:** `framework/standards/blazor-efcore.md` for background operations
-
-```csharp
-public interface I{{pascalCase FEATURE_NAME}}Service
-{
-    Task<{{pascalCase FEATURE_NAME}}Dto> GetByIdAsync(int id);
-    Task<{{pascalCase FEATURE_NAME}}Dto> CreateAsync(Create{{pascalCase FEATURE_NAME}}Request request);
-}
-```
-
-**Contracts Workflow:** Generate `contracts.cs` FIRST → validate names → reference in spec → approve with user.
-
-**Validation Checklist:**
-- [ ] Property names are descriptive (not generic "Data", "Value")
-- [ ] Records use correct types (Stream vs byte[], Guid vs string)
-- [ ] Response DTOs have all properties needed for UI
-- [ ] Request DTOs have implicit validations (required, nullable)
-
----
-
-## UI/UX Design (if front-end)
-
-### Wireframes
-```
-{ASCII wireframe per screen - include states: loading, error, empty}
-```
-
-### User Flow
-1. {Step} → {System response}
-
----
-
-## Flows
-
-### {Flow Name}
-**Trigger:** {what starts this flow}
-1. {Actor} {action} → {system response}
-2. If {condition}: Path A / Else: Path B
-**End State:** {final state}
-
----
-
-## Cost Estimate
-
-| Resource | SKU | Monthly Cost | Justification |
-|----------|-----|--------------|---------------|
-| {Resource} | {SKU} | ${X} | {Why} |
-| **Total** | | **${X}/month** | |
-
----
-
-## ADRs (Architectural Decision Records)
-
-### ADR-001: {Decision Title}
-**Status:** Proposed / Accepted
-**Context:** {Why decide now}
-**Decision:** {What we chose}
-**Alternatives:** 1. {Alt} (pros/cons) 2. {Alt} (pros/cons)
-**Trade-offs:** {key trade-offs}
-
----
-
-## Security
-
-| Action | Required Policy |
-|--------|-----------------|
-| View | CanView{Feature} |
-| Create | CanManage{Feature} |
-
-## Risks
-
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| {Risk} | {H/M/L} | {Mitigation} |
-
-## Out of Scope
-- {Item}
-
-## Definition of Done
-- [ ] Code implemented
-- [ ] Tests >80% coverage
-- [ ] Code review approved
-- [ ] Deploy to staging
-- [ ] Recap.md generated
+# Feature Specification: {{titleCase FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **ID** | {{FEATURE_NAME}} |
+| **Status** | Draft / In Review / Approved / In Progress / Done |
+| **Created** | {{DATE}} |
+| **Stack** | {{STACK}} |
+| **Complexity** | Low / Medium / High |
+| **Estimated Cost** | $X/month |
+| **Agents** | Core: All / Specialists: {list} |
+
+---
+
+## Overview
+
+**Problem:** {What problem this feature solves}
+
+**Solution:** {High-level solution}
+
+**Success Criteria:**
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+
+---
+
+## Requirements
+
+**Functional:** FR1: {desc} | FR2: {desc} | FR3: {desc}
+
+**Non-Functional:** NFR1: Performance - {target} | NFR2: Reliability - {target}
+
+---
+
+## User Stories
+
+### US001: {Title}
+**As** {user type} **I want** {feature} **so that** {benefit}
+
+**Acceptance Criteria:** 1. {criterion} 2. {criterion}
+
+**Edge Cases:** {edge case}: {handling}
+
+---
+
+## Technical Design
+
+### Stack
+| Component | Technology |
+|-----------|------------|
+| Frontend | {Blazor Server / Next.js} |
+| Backend | .NET 10 / C# 14 |
+| Database | {Azure SQL / Cosmos DB} |
+
+### Data Model
+
+#### {EntityName}
+| Column | Type | Constraints |
+|--------|------|-------------|
+| Id | Guid | PK |
+| {Property} | {Type} | {Constraints} |
+| CreatedAt | datetime2 | Default: GETUTCDATE() |
+
+### Contracts
+
+> **Ref:** `framework/standards/backend/database/ef-core.md` for background operations
+
+```csharp
+public interface I{{pascalCase FEATURE_NAME}}Service
+{
+    Task<{{pascalCase FEATURE_NAME}}Dto> GetByIdAsync(int id);
+    Task<{{pascalCase FEATURE_NAME}}Dto> CreateAsync(Create{{pascalCase FEATURE_NAME}}Request request);
+}
+```
+
+**Contracts Workflow:** Generate `contracts.cs` FIRST → validate names → reference in spec → approve with user.
+
+**Validation Checklist:**
+- [ ] Property names are descriptive (not generic "Data", "Value")
+- [ ] Records use correct types (Stream vs byte[], Guid vs string)
+- [ ] Response DTOs have all properties needed for UI
+- [ ] Request DTOs have implicit validations (required, nullable)
+
+---
+
+## UI/UX Design (if front-end)
+
+### Wireframes
+```
+{ASCII wireframe per screen - include states: loading, error, empty}
+```
+
+### User Flow
+1. {Step} → {System response}
+
+---
+
+## Flows
+
+### {Flow Name}
+**Trigger:** {what starts this flow}
+1. {Actor} {action} → {system response}
+2. If {condition}: Path A / Else: Path B
+**End State:** {final state}
+
+---
+
+## Cost Estimate
+
+| Resource | SKU | Monthly Cost | Justification |
+|----------|-----|--------------|---------------|
+| {Resource} | {SKU} | ${X} | {Why} |
+| **Total** | | **${X}/month** | |
+
+---
+
+## ADRs (Architectural Decision Records)
+
+### ADR-001: {Decision Title}
+**Status:** Proposed / Accepted
+**Context:** {Why decide now}
+**Decision:** {What we chose}
+**Alternatives:** 1. {Alt} (pros/cons) 2. {Alt} (pros/cons)
+**Trade-offs:** {key trade-offs}
+
+---
+
+## Security
+
+| Action | Required Policy |
+|--------|-----------------|
+| View | CanView{Feature} |
+| Create | CanManage{Feature} |
+
+## Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| {Risk} | {H/M/L} | {Mitigation} |
+
+## Out of Scope
+- {Item}
+
+## Definition of Done
+- [ ] Code implemented
+- [ ] Tests >80% coverage
+- [ ] Code review approved
+- [ ] Deploy to staging
+- [ ] Recap.md generated

package/framework/templates/docs/ui-components.md

@@ -0,0 +1,124 @@
+# UI Components: {{titleCase FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Feature** | {{FEATURE_NAME}} |
+| **Created** | {{DATE}} |
+| **Stack** | {{STACK}} |
+
+---
+
+{{#if (eq STACK "blazor-azure")}}
+## Component Library: FluentUI Blazor / MudBlazor
+
+**NuGet Package:**
+```xml
+<PackageReference Include="Microsoft.FluentUI.AspNetCore.Components" Version="4.x.x" />
+```
+
+---
+
+### C001: Header Navigation
+
+**Component:** `<FluentHeader>`
+
+```razor
+<FluentHeader>
+    <FluentLabel>{{FEATURE_NAME}}</FluentLabel>
+    <FluentSpacer />
+    <FluentPersona Name="@userName" OnClick="@ShowUserMenu" />
+</FluentHeader>
+```
+
+---
+
+### C002: Primary Button
+
+**Component:** `<FluentButton>`
+
+```razor
+<FluentButton Appearance="Appearance.Accent"
+              OnClick="@HandleSave"
+              Disabled="@(!isValid)">
+    Save
+</FluentButton>
+```
+
+---
+
+### C003: Data Table
+
+**Component:** `<FluentDataGrid>`
+
+```razor
+<FluentDataGrid Items="@items" Pagination="@pagination">
+    <PropertyColumn Property="@(i => i.Name)" Sortable="true" />
+    <PropertyColumn Property="@(i => i.Status)" Sortable="true" />
+    <TemplateColumn Title="Actions">
+        <FluentMenu>
+            <FluentMenuItem OnClick="@(() => EditItem(context))">Edit</FluentMenuItem>
+            <FluentMenuItem OnClick="@(() => DeleteItem(context))">Delete</FluentMenuItem>
+        </FluentMenu>
+    </TemplateColumn>
+</FluentDataGrid>
+```
+
+---
+
+### C004: Form Input
+
+**Component:** `<FluentTextField>`
+
+```razor
+<FluentTextField @bind-Value="model.Name"
+                 Label="Name"
+                 Required="true"
+                 MaxLength="100"
+                 ErrorMessage="@GetValidationError(nameof(model.Name))">
+</FluentTextField>
+```
+
+{{/if}}
+
+{{#if (eq STACK "nextjs-supabase")}}
+## Component Library: shadcn/ui
+
+### C001: Button
+
+```tsx
+import { Button } from '@/components/ui/button';
+
+<Button onClick={handleSave} disabled={!isValid}>
+  Save
+</Button>
+```
+
+### C002: Data Table
+
+```tsx
+import { DataTable } from '@/components/ui/data-table';
+
+<DataTable columns={columns} data={items} />
+```
+
+{{/if}}
+
+---
+
+## Form Validation
+
+| Field | Rule | Error Message |
+|-------|------|---------------|
+| **Name** | Required, max 100 | "Name is required" |
+| **Email** | Valid email | "Invalid email" |
+
+---
+
+## Accessibility
+- [ ] All inputs have labels
+- [ ] Error messages announced
+- [ ] Keyboard navigation works
+
+---
+
+*Generated with MORPH Framework*

package/framework/templates/docs/ui-design-system.md

@@ -0,0 +1,76 @@
+# UI Design System: {{titleCase FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Feature** | {{FEATURE_NAME}} |
+| **Created** | {{DATE}} |
+| **Project** | {{PROJECT_NAME}} |
+
+---
+
+## Color Palette
+
+### Primary Colors
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--color-primary` | #0078D4 | Primary actions, links |
+| `--color-primary-hover` | #106EBE | Hover states |
+
+### Semantic Colors
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--color-success` | #107C10 | Success states |
+| `--color-warning` | #F7630C | Warnings |
+| `--color-error` | #D13438 | Errors |
+
+---
+
+## Typography
+
+| Token | Size | Weight | Usage |
+|-------|------|--------|-------|
+| `--text-h1` | 24px | 600 | Section headers |
+| `--text-body` | 14px | 400 | Body text |
+| `--text-caption` | 12px | 400 | Labels |
+
+---
+
+## Spacing
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--space-sm` | 8px | Compact spacing |
+| `--space-md` | 16px | Standard spacing |
+| `--space-lg` | 24px | Wide spacing |
+
+---
+
+## Components
+
+### Buttons
+- **Primary**: `--color-primary` background, white text
+- **Secondary**: Transparent, `--color-primary` border
+- **Sizes**: Small (24px), Medium (32px), Large (40px)
+
+### Forms
+- **Input height**: 32px
+- **Focus**: 2px solid `--color-primary`
+- **Error**: 1px solid `--color-error`
+
+---
+
+## Accessibility
+- [ ] 4.5:1 contrast ratio (WCAG AA)
+- [ ] Touch targets minimum 44x44px
+- [ ] Keyboard navigation supported
+
+---
+
+## Responsive Breakpoints
+- **Mobile**: < 768px
+- **Tablet**: 768px - 1199px
+- **Desktop**: ≥ 1200px
+
+---
+
+*Generated with MORPH Framework*

package/framework/templates/docs/ui-flows.md

@@ -0,0 +1,167 @@
+# UI Flows: {{titleCase FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Feature** | {{FEATURE_NAME}} |
+| **Created** | {{DATE}} |
+
+---
+
+## User Stories
+
+### US001: {Primary User Story}
+
+**As** a {user type}
+**I want** to {capability}
+**So that** {benefit}
+
+**Acceptance Criteria:**
+1. {Criterion 1}
+2. {Criterion 2}
+
+---
+
+## Flow Inventory
+
+| Flow ID | Name | Priority |
+|---------|------|----------|
+| **F001** | Create New Item | High |
+| **F002** | Edit Existing Item | High |
+| **F003** | Delete Item | Medium |
+
+---
+
+## F001: Create New Item
+
+### Happy Path
+
+```
+START
+  ↓
+[User clicks "Add New"]
+  ↓
+[Modal opens with form]
+  ↓
+[User fills required fields]
+  ↓
+[User clicks "Submit"]
+  ↓
+[Validation passes] ✓
+  ↓
+[API call: POST /api/items]
+  ↓
+[Success response]
+  ↓
+[Modal closes]
+  ↓
+[Success toast: "Item created"]
+  ↓
+[Table refreshes]
+  ↓
+END
+```
+
+**Duration:** 15-30 seconds
+**Success Rate Target:** 95%
+
+---
+
+### Alternative Path: Validation Error
+
+```
+[User clicks "Submit"]
+  ↓
+[Validation fails] ✕
+  ↓
+[Error messages shown inline]
+  ↓
+[User corrects errors]
+  ↓
+[Real-time validation clears errors]
+  ↓
+→ Returns to Happy Path
+```
+
+---
+
+### Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| **Duplicate Name** | Show warning, allow submit |
+| **Network Error** | Show error toast, preserve data |
+| **Session Expired** | Redirect to login |
+
+---
+
+## F002: Edit Existing Item
+
+```
+[User clicks "Edit"]
+  ↓
+[Modal opens with pre-filled form]
+  ↓
+[User modifies fields]
+  ↓
+[User clicks "Save"]
+  ↓
+[API call: PUT /api/items/{id}]
+  ↓
+[Success toast]
+  ↓
+[Table refreshes]
+END
+```
+
+---
+
+## F003: Delete Item
+
+```
+[User clicks "Delete"]
+  ↓
+[Confirmation dialog: "Delete item?"]
+  ↓
+[User confirms]
+  ↓
+[API call: DELETE /api/items/{id}]
+  ↓
+[Success toast]
+  ↓
+[Table refreshes]
+END
+```
+
+---
+
+## Toast Notifications
+
+| Event | Type | Message | Duration |
+|-------|------|---------|----------|
+| **Item Created** | Success | "Item created successfully" | 3s |
+| **Item Updated** | Success | "Item updated successfully" | 3s |
+| **Item Deleted** | Success | "Item deleted successfully" | 3s |
+| **Error** | Error | "Something went wrong" | 5s |
+
+---
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| **Ctrl+N** | New Item |
+| **Escape** | Close modal |
+| **Enter** | Submit form |
+
+---
+
+## Performance Targets
+
+| Flow | Target |
+|------|--------|
+| **Create Item** | < 2s (API response) |
+| **Search** | < 500ms |
+
+---
+
+*Generated with MORPH Framework*