@tailor-platform/erp-kit 0.2.0 → 0.2.2

package/skills/erp-kit-app-4-design/SKILL.md

@@ -1,256 +0,0 @@
----
-name: erp-kit-app-4-design
-description: Create design mockups from screen specifications using .pen files. Use after completing documentation review with erp-kit-app-3-doc-review. Generates visual UI mockups with shadcn components.
----
-
-# Design Mockup Workflow
-
-Create visual UI mockups from Tier 3 screen documentation using .pen design files and shadcn components.
-
-## Prerequisites
-
-Tier 3 documentation must exist:
-
-- `docs/screen/*.md` (screen specifications)
-- Design system source file (contains reusable shadcn components)
-
-## Workflow Phases
-
-```
-SETUP → ANALYZE → DESIGN → VALIDATE
-```
-
-### Phase 1: Setup
-
-Ensure the design system file exists at the application's `docs/design.pen`.
-
-This provides access to 87+ shadcn reusable components including:
-
-- **Layout**: Sidebar, Card, Table, Data Table
-- **Form**: Input, Textarea, Select, Checkbox, Radio
-- **Navigation**: Breadcrumb, Pagination, Tabs
-- **Feedback**: Badge, Alert, Dialog
-- **Actions**: Button (Default, Secondary, Outline, Ghost, Destructive)
-
-### Phase 2: Analyze
-
-1. **Read** all screen documentation in `docs/screen/*.md`
-2. **Identify** screen types: ListView, DetailView, Form
-3. **Map** UI requirements to available components
-4. **Plan** layout hierarchy based on sidebar navigation
-
-### Phase 3: Design
-
-Create mockups using Pencil MCP tools.
-
-#### 3.1 Get Editor State
-
-```
-mcp__pencil__get_editor_state(include_schema: true)
-mcp__pencil__open_document(filePathOrTemplate: "docs/design.pen")
-```
-
-#### 3.2 Discover Components
-
-Search for reusable components:
-
-```
-mcp__pencil__batch_get(
-  filePath: "docs/design.pen",
-  patterns: [{ "reusable": true }],
-  searchDepth: 3
-)
-```
-
-Key component patterns to search:
-
-| Component Type | Search Pattern          |
-| -------------- | ----------------------- |
-| Sidebar        | `{ "name": "Sidebar" }` |
-| Card           | `{ "name": "Card" }`    |
-| Table          | `{ "name": "Table" }`   |
-| Input          | `{ "name": "Input" }`   |
-| Button         | `{ "name": "Button" }`  |
-| Badge          | `{ "name": "Badge" }`   |
-
-#### 3.3 Create Screen Frames
-
-Use `batch_design` to create screens. Standard pattern:
-
-```javascript
-// Create screen frame
-screen = I("document", {
-  type: "frame",
-  name: "{screen-name}",
-  x: { x },
-  y: { y },
-  width: 1280,
-  height: 800,
-  fill: "$--background",
-  layout: "horizontal",
-});
-
-// Add sidebar
-sidebar = I(screen, {
-  type: "ref",
-  ref: "{sidebar-component-id}",
-  height: "fill_container",
-});
-U(sidebar + "/{title-id}", { content: "{app-name}" });
-
-// Add main content area
-mainContent = I(screen, {
-  type: "frame",
-  layout: "vertical",
-  gap: 24,
-  padding: 32,
-  width: "fill_container",
-  height: "fill_container",
-});
-```
-
-#### 3.4 Layout Organization
-
-Arrange screens by navigation hierarchy:
-
-| Row | Y Position | Screens                   |
-| --- | ---------- | ------------------------- |
-| 0   | 0          | Dashboard (Home)          |
-| 1   | 1000       | Primary feature screens   |
-| 2   | 2000       | Secondary feature screens |
-| 3   | 3000       | Tertiary feature screens  |
-| N   | N\*1000    | Settings/Admin screens    |
-
-Flow within rows: List → Detail → Create/Edit Form
-
-#### 3.5 Component Patterns by Screen Type
-
-**ListView Pattern:**
-
-```javascript
-// Header with title and action button
-header = I(mainContent, {
-  type: "frame",
-  justifyContent: "space_between",
-  alignItems: "center",
-  width: "fill_container",
-});
-title = I(header, {
-  type: "text",
-  content: "{page-title}",
-  fontSize: 24,
-  fontWeight: "600",
-  fill: "$--foreground",
-});
-actionBtn = I(header, { type: "ref", ref: "{button-component-id}" });
-
-// Filter row
-filterRow = I(mainContent, { type: "frame", gap: 12, alignItems: "center" });
-
-// Data table in card
-tableCard = I(mainContent, {
-  type: "ref",
-  ref: "{card-component-id}",
-  width: "fill_container",
-});
-```
-
-**Form Pattern:**
-
-```javascript
-// Card with header
-formCard = I(mainContent, {
-  type: "ref",
-  ref: "{card-component-id}",
-  width: "fill_container",
-});
-cardTitle = I(formCard + "/{header-slot-id}", {
-  type: "text",
-  content: "{form-title}",
-  fontSize: 18,
-  fontWeight: "600",
-});
-
-// Form fields in content slot
-formContent = I(formCard + "/{content-slot-id}", {
-  type: "frame",
-  layout: "vertical",
-  gap: 16,
-  width: "fill_container",
-});
-inputField = I(formContent, {
-  type: "ref",
-  ref: "{input-component-id}",
-  width: "fill_container",
-});
-U(inputField + "/{label-id}", { content: "{field-label}" });
-
-// Action buttons in footer slot
-btnRow = I(formCard + "/{footer-slot-id}", {
-  type: "frame",
-  gap: 12,
-  justifyContent: "flex_end",
-});
-```
-
-**DetailView Pattern:**
-
-```javascript
-// Breadcrumb navigation
-bcRow = I(mainContent, { type: "frame", gap: 4, alignItems: "center" });
-
-// Info cards
-infoCard = I(mainContent, {
-  type: "ref",
-  ref: "{card-component-id}",
-  width: "fill_container",
-});
-
-// Action section
-actionRow = I(mainContent, { type: "frame", gap: 12 });
-```
-
-### Phase 4: Validate
-
-Take screenshots to verify each screen:
-
-```
-mcp__pencil__get_screenshot(filePath: "docs/design.pen", nodeId: "{frame-id}")
-```
-
-Check for:
-
-- Consistent sidebar navigation across screens
-- Proper alignment and spacing
-- Correct component usage
-- Readable text and labels
-
-## Tips
-
-- Always check component structure with `batch_get` before using `U()` updates
-- Use `find_empty_space_on_canvas` for positioning new screens
-- Sidebar navigation should highlight the current screen's menu item
-- Keep operations under 25 per `batch_design` call
-- Use consistent user profile in sidebar footer across all screens
-
-## Validation Commands
-
-```
-# Check layout structure
-mcp__pencil__snapshot_layout(filePath: "docs/design.pen", maxDepth: 0)
-
-# Verify screen screenshot
-mcp__pencil__get_screenshot(filePath: "docs/design.pen", nodeId: "{frame-id}")
-```
-
-## Next Step
-
-After completing design mockups, use `/erp-kit-app-5-design-review` to review and validate the mockups against screen specifications.
-
-## References
-
-- [Application structure](references/structure.md)
-- [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/erp-kit-app-4-design/references/component.md

@@ -1,50 +0,0 @@
-# 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/erp-kit-app-4-design/references/screen-detailview.md

@@ -1,106 +0,0 @@
-# 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/erp-kit-app-4-design/references/screen-form.md

@@ -1,139 +0,0 @@
-# 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`

package/skills/erp-kit-app-4-design/references/screen-listview.md

@@ -1,153 +0,0 @@
-# ListView Screen Implementation
-
-Implementation pattern for screens with `Screen Type: ListView`.
-Assumes `page.md` and `component.md` rules.
-
-## File Structure
-
-```
-{screen-path}/
-├── components/
-│   └── {screen-name}-table.tsx     # Table component with fragments
-└── page.tsx
-```
-
-## Page Component (page.tsx)
-
-Data fetching and `Layout` must be co-located in the same page component.
-Do NOT split into an inner Content component — `Layout` requires `Layout.Column` as direct children.
-
-```tsx
-const ResourcesQuery = graphql(
-  `
-    query Resources {
-      resources {
-        ...ResourceTable
-      }
-    }
-  `,
-  [ResourceTableFragment],
-);
-
-const ResourcesPage = () => {
-  const [{ data, error, fetching }, reexecuteQuery] = useQuery({
-    query: ResourcesQuery,
-  });
-
-  if (fetching) return <Loading />;
-
-  if (error || !data) {
-    return (
-      <ErrorFallback
-        title="Failed to load resources"
-        message="An error occurred while fetching the list."
-        onReset={() => reexecuteQuery({ requestPolicy: "network-only" })}
-      />
-    );
-  }
-
-  return (
-    <Layout
-      columns={1}
-      title="Resources"
-      actions={[
-        <Button key="create" asChild>
-          <Link to="create">Create</Link>
-        </Button>,
-      ]}
-    >
-      <Layout.Column>
-        <ResourceTable data={data.resources} />
-      </Layout.Column>
-    </Layout>
-  );
-};
-```
-
-## Table Component (components/{screen-name}-table.tsx)
-
-### Fragment Collocation
-
-Define a row fragment and a table fragment wrapping the Connection type.
-
-```tsx
-const ResourceRowFragment = graphql(`
-  fragment ResourceRow on Resource {
-    id
-    title
-    status
-    createdAt
-  }
-`);
-
-export const ResourceTableFragment = graphql(
-  `
-    fragment ResourceTable on ResourceConnection {
-      edges {
-        node {
-          ...ResourceRow
-        }
-      }
-    }
-  `,
-  [ResourceRowFragment],
-);
-```
-
-### Row Component
-
-```tsx
-const ResourceRow = ({ resource: resourceFragment }: ResourceRowProps) => {
-  const resource = readFragment(ResourceRowFragment, resourceFragment);
-  return (
-    <TableRow>
-      <TableCell>{resource.title}</TableCell>
-      <TableCell>
-        <Badge variant={resource.status === "ACTIVE" ? "default" : "secondary"}>
-          {resource.status}
-        </Badge>
-      </TableCell>
-      <TableCell>
-        <Button variant="ghost" size="sm" asChild>
-          <Link to={resource.id}>View</Link>
-        </Button>
-      </TableCell>
-    </TableRow>
-  );
-};
-```
-
-### Empty State
-
-```tsx
-if (connection.edges.length === 0) {
-  return (
-    <EmptyState
-      title="No resources"
-      message="Get started by creating a new resource."
-      action={
-        <Button asChild>
-          <Link to="create">Create</Link>
-        </Button>
-      }
-    />
-  );
-}
-```
-
-## Column Property Mapping
-
-| Property        | Implementation                                              |
-| --------------- | ----------------------------------------------------------- |
-| Hideable: Yes   | Column visibility state to toggle show/hide                 |
-| Sortable: Yes   | Sort icon on `<TableHead>` + onClick to toggle query vars   |
-| Filterable: Yes | Filter UI above table (`<Select />`)                        |
-| Searchable: Yes | Search input above table (`<Input placeholder="Search" />`) |
-
-## Key Points
-
-- Use `<Badge />` for status columns
-- Format dates with `toLocaleDateString()`
-- Use `<EmptyState />` with Create action for empty lists
-- Add a View button per row to navigate to the detail page
-- Iterate data using Connection type `edges.node` pattern