@tailor-platform/erp-kit 0.0.1 → 0.1.1

package/skills/app-compose-4-design-mock/references/structure.md

@@ -0,0 +1,27 @@
+# Application Directory Structure
+
+```
+{app_name}/
+├── backend/
+│   ├── src/
+│   │   ├── modules.ts              # Declaring module usage
+│   │   ├── modules/
+│   │   │   └── {module-name}/      # Module-specific directory
+│   │   │       ├── resolvers/      # API Definition to expose graphql apis
+│   │   │       └── executors/      # PubSub Automation (one file per declaration)
+│   │   └── generated/              # Auto-generated code (do not edit)
+│   └── tailor.config.ts            # tailor application config
+│
+└── frontend/
+    └── src/
+        ├── pages/                  # File-based routing (auto-discovered by Vite plugin)
+        │   └── {page-path}/
+        │       ├── page.tsx
+        │       └── {page-path}/
+        │           ├── components/
+        │           └── page.tsx
+        ├── components/
+        │   └── ui/                 # Generic UI components
+        ├── graphql/                # gql.tada settings
+        └── providers/              # react providers
+```

package/skills/app-compose-5-design-mock-review/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: app-compose-5-design-mock-review
+description: Review design mockups (.pen files) against screen specifications. Use after completing design mockups with app-compose-4-design-mock. Validates visual consistency, detects regressions, and fixes layout issues.
+---
+
+# Design Mockup Review Workflow
+
+Review visual design mockups against Tier 3 screen documentation. Detect and fix regressions, layout issues, and specification mismatches.
+
+## Prerequisites
+
+- `docs/screen/*.md` (screen specifications)
+- `docs/design.pen` (design mockups from app-compose-4-design-mock)
+
+## Workflow Phases
+
+```
+INVENTORY → PARITY CHECK → VISUAL REVIEW → REGRESSION FIX → VALIDATE
+```
+
+### Phase 1: Inventory
+
+#### 1.1 Open Design File
+
+```
+mcp__pencil__get_editor_state(include_schema: false)
+mcp__pencil__open_document(filePathOrTemplate: "docs/design.pen")
+```
+
+#### 1.2 List Design Screens
+
+Extract top-level frames (screens) from design.pen:
+
+```
+mcp__pencil__batch_get(
+  filePath: "docs/design.pen",
+  readDepth: 1
+)
+```
+
+Filter for screen frames (exclude design system components frame).
+
+#### 1.3 List Screen Specifications
+
+```bash
+ls docs/screen/*.md
+```
+
+### Phase 2: Parity Check
+
+#### Screen Count Validation
+
+| Check           | Question                                                     |
+| --------------- | ------------------------------------------------------------ |
+| Count match     | Does design.pen have same number of screens as screen/\*.md? |
+| Name match      | Does each screen in design.pen correspond to a spec file?    |
+| Missing screens | Any spec files without corresponding design frames?          |
+
+Create mapping table:
+
+```markdown
+| Screen Spec      | Design Frame               | Status     |
+| ---------------- | -------------------------- | ---------- |
+| {screen-name}.md | {Screen Name} ({frame-id}) | ✅         |
+| {screen-name}.md | -                          | ❌ Missing |
+```
+
+### Phase 3: Visual Review
+
+For each screen, perform detailed review:
+
+#### 3.1 Screenshot Capture
+
+```
+mcp__pencil__get_screenshot(filePath: "docs/design.pen", nodeId: "{frame-id}")
+```
+
+#### 3.2 Specification Comparison
+
+**For ListView screens:**
+
+| Check                  | How to Verify                                        |
+| ---------------------- | ---------------------------------------------------- |
+| Required columns exist | Compare spec table columns with design table headers |
+| Column properties      | Sortable/Filterable indicators if applicable         |
+| Action buttons         | Create/Edit/Delete buttons per spec                  |
+| Pagination             | Present if list can be long                          |
+
+**For Form screens:**
+
+| Check                  | How to Verify                                    |
+| ---------------------- | ------------------------------------------------ |
+| All input fields exist | Match spec field list with form fields           |
+| Field types correct    | Text/Dropdown/Radio/Checkbox/FileUpload per spec |
+| Required indicators    | Required fields marked appropriately             |
+| Action buttons         | Submit/Cancel buttons present                    |
+
+**For DetailView screens:**
+
+| Check             | How to Verify                |
+| ----------------- | ---------------------------- |
+| Displayed fields  | All spec fields visible      |
+| Action buttons    | Available actions per spec   |
+| Status indicators | Badges/Timeline if specified |
+
+#### 3.3 Layout Problem Detection
+
+```
+mcp__pencil__snapshot_layout(
+  filePath: "docs/design.pen",
+  parentId: "{frame-id}",
+  problemsOnly: true,
+  maxDepth: 10
+)
+```
+
+Common problems:
+
+- `partially clipped` - Content overflows container
+- `fully clipped` - Element completely hidden
+- Negative coordinates - Mispositioned elements
+
+### Phase 4: Regression Fix
+
+#### 4.1 Layout Issues
+
+**Fixed height causing overflow:**
+
+```javascript
+// Change fixed height to fit_content
+U("{container-id}", { height: "fit_content", justifyContent: "start" });
+```
+
+**Element positioning:**
+
+```javascript
+// Reset position
+U("{element-id}", { x: 0, y: 0 });
+```
+
+#### 4.2 Style Inconsistencies
+
+**Background color mismatch:**
+
+```javascript
+// Use design token instead of hardcoded color
+U("{frame-id}", { fill: "$--background" });
+```
+
+**Missing icon:**
+
+```javascript
+// Add icon to sidebar item
+U("{frame-id}/{sidebar-id}/{menu-item-id}/{icon-id}", { iconFontName: "{icon-name}" });
+```
+
+**Text not visible (missing fill):**
+
+```javascript
+// Add fill color to text
+U("{text-id}", { fill: "$--foreground" });
+```
+
+#### 4.3 Missing Fields
+
+**Add missing form field:**
+
+```javascript
+newField = I("{form-container-id}", {
+  type: "ref",
+  ref: "{input-component-id}",
+  width: "fill_container",
+  descendants: {
+    "{label-id}": { content: "{field-label}" },
+    "{input-id}": { content: "{placeholder}" },
+  },
+});
+```
+
+#### 4.4 Common Component Fixes
+
+| Issue                   | Fix Pattern                                      |
+| ----------------------- | ------------------------------------------------ |
+| Card content overflow   | Set `height: "fit_content"` on Card Content slot |
+| Sidebar icons missing   | Update `iconFontName` on menu item icon element  |
+| Text invisible          | Add `fill: "$--foreground"` to text element      |
+| Inconsistent background | Use `$--background` instead of hex colors        |
+
+### Phase 5: Validate
+
+After fixes, re-verify each screen:
+
+```
+mcp__pencil__get_screenshot(filePath: "docs/design.pen", nodeId: "{frame-id}")
+```
+
+Check:
+
+- Layout renders correctly
+- All text visible
+- Consistent styling
+- No clipped elements
+
+## Review Report Template
+
+```markdown
+## Design Mockup Review Report
+
+**Application:** {app-name}
+**Design File:** docs/design.pen
+
+### Screen Inventory
+
+| Screen        | Spec File        | Design Frame | Status |
+| ------------- | ---------------- | ------------ | ------ |
+| {screen-name} | {screen-name}.md | {frame-id}   | ✅     |
+
+### Issues Found & Fixed
+
+#### 1. [{screen-name}] - {issue-description}
+
+- **Problem:** {description}
+- **Root Cause:** {cause}
+- **Fix Applied:** {fix}
+
+### Remaining Issues
+
+- [ ] {issue-description}
+
+### Summary
+
+| Category         | Count   |
+| ---------------- | ------- |
+| Screens Reviewed | {count} |
+| Issues Found     | {count} |
+| Issues Fixed     | {count} |
+| Remaining        | {count} |
+```
+
+## Design Token Reference
+
+Retrieve available design tokens dynamically:
+
+```
+mcp__pencil__get_variables(filePath: "docs/design.pen")
+```
+
+Common token patterns:
+
+- `$--background` / `$--foreground` - Base colors
+- `$--card` / `$--border` - Card styling
+- `$--primary` / `$--secondary` - Action colors
+- `$--sidebar-*` - Sidebar-specific tokens
+- `$--muted-*` - Subdued variants
+
+## Sidebar Component Reference
+
+Retrieve sidebar component structure to find icon element paths:
+
+```
+mcp__pencil__batch_get(
+  filePath: "docs/design.pen",
+  patterns: [{"reusable": true, "name": "Sidebar"}],
+  readDepth: 4
+)
+```
+
+To find icon names used in an existing screen's sidebar:
+
+```
+mcp__pencil__batch_get(
+  filePath: "docs/design.pen",
+  nodeIds: ["{frame-id}/{sidebar-id}"],
+  readDepth: 5,
+  resolveInstances: true
+)
+```
+
+Look for `iconFontName` property in sidebar menu items. Icons use Lucide icon font family.
+
+## Next Step
+
+After completing design review, use `/app-compose-6-implementation-spec` to create Tier 4 documentation (resolvers).
+
+## References
+
+- [ListView screen](references/screen-listview.md)
+- [Form screen](references/screen-form.md)
+- [DetailView screen](references/screen-detailview.md)
+- [Page components](references/component.md)

package/skills/app-compose-5-design-mock-review/references/component.md

@@ -0,0 +1,50 @@
+# Page Components
+
+Page-specific components are placed in a `components/` directory, separated from page.tsx.
+
+```
+{page-name}/
+├── components/
+│   └── *.tsx
+└── page.tsx
+```
+
+## Fragment Collocation
+
+Components define and export their own GraphQL Fragment for the data they display. The parent page imports the Fragment and includes it in the query.
+
+Use `graphql`, `FragmentOf`, and `readFragment` from `@/graphql`.
+
+```tsx
+// components/user-card.tsx
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+
+export const UserCardFragment = graphql(`
+  fragment UserCard on User {
+    id
+    name
+    email
+  }
+`);
+
+export const UserCard = ({ user }: { user: FragmentOf<typeof UserCardFragment> }) => {
+  const data = readFragment(UserCardFragment, user);
+  return <div>{data.name}</div>;
+};
+```
+
+```tsx
+// page.tsx
+import { UserCard, UserCardFragment } from "./components/user-card";
+
+const UserQuery = graphql(
+  `
+    query User($id: ID!) {
+      user(id: $id) {
+        ...UserCard
+      }
+    }
+  `,
+  [UserCardFragment],
+);
+```

package/skills/app-compose-5-design-mock-review/references/screen-detailview.md

@@ -0,0 +1,106 @@
+# DetailView Screen Implementation
+
+Implementation pattern for screens with `Screen Type: DetailView`.
+Assumes `page.md` and `component.md` rules.
+
+## File Structure
+
+```
+{screen-path}/[id]/
+├── components/
+│   ├── {screen-name}-detail.tsx     # Main content (left column)
+│   └── {screen-name}-actions.tsx    # Action sidebar (right column)
+├── edit/
+│   ├── components/
+│   │   └── edit-{screen-name}-form.tsx
+│   └── page.tsx
+└── page.tsx
+```
+
+## Layout
+
+- Two-column layout: main content on the left, actions on the right.
+
+```tsx
+const ResourcePage = () => {
+  const { id } = useParams();
+  const [{ data, error, fetching }, reexecuteQuery] = useQuery({
+    query: ResourceQuery,
+    variables: { id: id! },
+  });
+
+  if (fetching) return <Loading />;
+  if (error || !data?.resource) return <ErrorFallback ... />;
+
+  return (
+    <Layout columns={2} title="Resource Detail">
+      <Layout.Column>
+        <ResourceDetail resource={data.resource} />
+      </Layout.Column>
+      <Layout.Column>
+        <ResourceActions resource={data.resource} />
+      </Layout.Column>
+    </Layout>
+  );
+};
+```
+
+## Left Column: Detail Component
+
+Stack `DescriptionCard` and related tables vertically with `space-y-6`.
+
+- `DescriptionCard` (`@tailor-platform/app-shell`): renders key-value fields declaratively.
+- Complex content (tables, timelines): wrap in `<div className="rounded-lg border bg-card p-6">`.
+
+### DescriptionCard
+
+```tsx
+<DescriptionCard
+  data={resource}
+  title="Overview"
+  columns={3}
+  fields={[
+    { key: "name", label: "Name", meta: { copyable: true } },
+    {
+      key: "status",
+      label: "Status",
+      type: "badge",
+      meta: { badgeVariantMap: { ACTIVE: "success", PENDING: "warning" } },
+    },
+    { type: "divider" },
+    {
+      key: "createdAt",
+      label: "Created At",
+      type: "date",
+      meta: { dateFormat: "medium" },
+    },
+  ]}
+/>
+```
+
+Field types: `"text"` (default), `"badge"`, `"money"`, `"date"`, `"link"`, `"address"`, `"reference"`, `"divider"`
+
+## Right Column: Actions Component
+
+Wrap in a `Card` component. Use `Button variant="ghost"` for each action item.
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Actions</CardTitle>
+  </CardHeader>
+  <CardContent className="space-y-2">
+    <Button variant="ghost" className="w-full justify-start gap-2" asChild>
+      <Link to="edit">✎ Edit</Link>
+    </Button>
+    <Button variant="ghost" className="w-full justify-start gap-2" onClick={handler}>
+      ✓ Approve
+    </Button>
+  </CardContent>
+</Card>
+```
+
+- Navigation: `<Button variant="ghost" asChild><Link to="...">`
+- Mutation: `<Button variant="ghost" onClick={handler}>` with custom resolvers (see `backend/resolvers.md`)
+- Conditional: show/hide based on status
+- Multiple cards: stack with `<div className="space-y-6">`

package/skills/app-compose-5-design-mock-review/references/screen-form.md

@@ -0,0 +1,139 @@
+# Form Screen Implementation
+
+Implementation pattern for screens with `Screen Type: Form`.
+Assumes `page.md` and `component.md` rules.
+
+## File Structure
+
+```
+{screen-path}/
+├── components/
+│   └── {screen-name}-form.tsx    # Form component with validation
+└── page.tsx
+```
+
+## Page Component (page.tsx)
+
+Form pages delegate mutation logic to the form component.
+
+```tsx
+const ScreenNamePage = () => (
+  <Layout columns={1} title="Screen Title">
+    <Layout.Column>
+      <ScreenNameForm />
+    </Layout.Column>
+  </Layout>
+);
+```
+
+For edit forms that need existing data, co-locate data fetching in the page component:
+
+```tsx
+const EditPage = () => {
+  const { id } = useParams();
+  const [{ data, error, fetching }] = useQuery({
+    query: ResourceQuery,
+    variables: { id: id! },
+  });
+
+  if (fetching) return <Loading />;
+  if (error || !data?.resource) return <ErrorFallback ... />;
+
+  return (
+    <Layout columns={1} title="Edit Resource">
+      <Layout.Column>
+        <EditResourceForm resource={data.resource} />
+      </Layout.Column>
+    </Layout>
+  );
+};
+```
+
+## Form Component (components/{screen-name}-form.tsx)
+
+### Technology Stack
+
+- `react-hook-form` — form state management
+- `zod` + `@hookform/resolvers/zod` — validation
+- `useMutation` (urql) — GraphQL mutation
+- `useNavigate` (@tailor-platform/app-shell) — post-submit navigation
+
+### Pattern
+
+```tsx
+const formSchema = z.object({
+  title: z.string().min(1, "Title is required"),
+  description: z.string().optional(),
+});
+
+type FormValues = z.infer<typeof formSchema>;
+
+export const ScreenNameForm = () => {
+  const navigate = useNavigate();
+  const [, createResource] = useMutation(CreateMutation);
+
+  const form = useForm<FormValues>({
+    resolver: zodResolver(formSchema),
+    defaultValues: { title: "", description: "" },
+  });
+
+  const onSubmit = (values: FormValues) => {
+    void createResource({ input: values }).then((result) => {
+      if (!result.error) {
+        void navigate("..");
+      }
+    });
+  };
+
+  return (
+    <Form {...form}>
+      <form onSubmit={(e) => void form.handleSubmit(onSubmit)(e)} className="max-w-md space-y-4">
+        <FormField
+          control={form.control}
+          name="title"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Title</FormLabel>
+              <FormControl>
+                <Input placeholder="Enter title" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <div className="flex gap-2">
+          <Button type="submit">Create</Button>
+          <Button type="button" variant="outline" onClick={() => void navigate("..")}>
+            Cancel
+          </Button>
+        </div>
+      </form>
+    </Form>
+  );
+};
+```
+
+## Field Type Mapping
+
+| Field Type | Component                      | Zod Schema                      |
+| ---------- | ------------------------------ | ------------------------------- |
+| Text       | `<Input />`                    | `z.string()`                    |
+| Textarea   | `<textarea className="..." />` | `z.string()`                    |
+| Dropdown   | `<Select />`                   | `z.string()` or `z.enum([...])` |
+| Date       | `<Input type="date" />`        | `z.string()` (ISO format)       |
+| Number     | `<Input type="number" />`      | `z.coerce.number()`             |
+| Email      | `<Input type="email" />`       | `z.string().email()`            |
+| Checkbox   | `<Checkbox />`                 | `z.boolean()`                   |
+| Radio      | `<RadioGroup />`               | `z.enum([...])`                 |
+
+## Validation Mapping
+
+- **Required: Yes** → `.min(1, "Field is required")` (string) / `.positive()` (number)
+- **Required: No** → `.optional()`
+
+## Key Points
+
+- Set `defaultValues` for all fields (empty string, false, etc.)
+- Navigate to `".."` after successful mutation
+- Cancel button must use `type="button"` to prevent form submit
+- For edit forms, accept fragment data as props and pre-fill `defaultValues`