@pen.dev/cli 0.3.2 → 0.3.4

package/dist/out/skills/pen-dev/guide/code.md

@@ -0,0 +1,198 @@
+# Instructions when generating code from .pen files
+
+- IMPORTANT: Make sure to use the frontend frameworks that are already used in the project. For example, if the project is using React, always generate compliant React code.
+- IMPORTANT: After generating code, DO NOT output Markdown files of the changes. Just stick to generating code and nothing else.
+- IMPORTANT: Make sure to use and leverage the CSS libraries, design systems and other UI coding utilities that are already used in the project. For example, if the project is using Tailwind, make sure to style your code using Tailwind.
+- IMPORTANT: Make sure when using CSS libraries and frameworks that you identify the installed version and always use the correct APIs that are supported by the installed versions.
+- IMPORTANT: When generating code from .pen designs, always make sure to use the same text labels, icons ans spacing as what is in the design.
+- DO NOT create documentations for the changes when generating code from design.
+- Explore the workspace to find if the design elements you are translating to code are already exist in the code base.
+- Make sure to awlays use the correct font, icons, and UI details like border radius when generating the code from a design.
+- If you are not sure what frontend frameworks and UI libraries are used in the project, explore it in the workspace.
+- If the UI design element you are turning code into already exist in the codebase, update it, not generate a new one.
+- When changing existing components and UI elements in the code, make sure to not break the functionality.
+
+## Initial Setup
+
+### Project Initialization
+
+- Identify the frontend framework and language used in the project (e.g., React, Vue, Angular, Svelte, etc.)
+- Use the same framework, language, and conventions as the existing project
+- Identify the styling approach (e.g., Tailwind, CSS Modules, styled-components, etc.)
+- If using Tailwind, refer to 'tailwind' topic for implementation details
+
+### Pre-Implementation Verification
+
+- Ensure CSS/styles compile without errors
+- Verify all CSS variables are accessible (if using CSS custom properties)
+- Confirm styling system is properly configured and loaded
+
+## Component Implementation Workflow
+
+### Step 1: Component Analysis and Extraction
+
+#### 1A. Identify Required Components
+
+- Read the target frame/design
+- Identify which reusable components (refs) are used in this specific frame
+- **IMPORTANT**: Only process components that appear in the current frame
+- Count instances of each component (helps catch missing instances later)
+- Document: "Component X used N times"
+
+#### 1B. Extract Component Definitions
+
+- Use `Print(Get(componentId, {depth: 5}))` in `execute` to get component structure
+- Extract full component tree with all nested children
+- Process components ONE AT A TIME:
+  1. Extract component with full depth
+  2. Recreate in React (Step 2)
+  3. Validate (Step 3)
+  4. Move to next component only after validation passes
+
+#### 1C. Map Component Instances
+
+- Read the target frame structure
+- For each component, identify ALL instances
+- Document for each instance:
+  * Instance ID and location
+  * Nested component overrides (`descendants` map)
+  * Props/values being passed
+- **Nested Component Analysis**:
+  * Check base component definition: Does it always include nested components?
+  * Check all instances: Do any override/hide nested components?
+  * **Decision Rule**:
+    - If NO instances override away → Nested component is REQUIRED (always render)
+    - If ANY instances override away → Nested component is OPTIONAL (conditional render)
+  * Verify each nested component ref in base definition against all instances
+- **Visual Verification**:
+  * Use `TakeScreenshot` on instances in context (not just base definition)
+  * Verify visible elements (borders, backgrounds, shadows)
+  * Check if styling should be on outer container or nested elements
+  * Match visual appearance in frame context
+
+### Step 2: React Component Creation
+
+#### Component Structure
+
+- Create `.tsx` file in `src/components/` with component name
+- Use named exports
+- Define TypeScript interfaces for all props
+
+#### Props Interface Design
+
+- Review ALL instances from Step 1C mapping
+- Support all properties used by any instance (including optional ones)
+- **Nested Component Rendering**:
+  * Apply decision rule from Step 1C:
+    - NO instances override away → Always render (required)
+    - ANY instances override away → Conditional render (optional)
+  * Verify against instance mapping before making props optional
+- Document required vs optional props based on actual usage
+- Cross-reference with instance mapping to ensure completeness
+
+#### Style Implementation
+
+- Use Tailwind classes exclusively (NO inline styles)
+- Refer to tailwind.md sections: "Layout Conversion", "Style Implementation", "CSS Custom Properties and Font Stacks"
+- Match design values exactly (use arbitrary values when needed)
+- Use CSS variables for colors (no hardcoded values)
+
+#### SVG Path Implementation
+
+When implementing SVG elements from the design:
+
+**1. Extract Exact Geometry**
+- Use `Print(Get(nodeId, {includePathGeometry: true}))` in `execute`
+- NEVER approximate paths - extract exact `geometry` property from design
+
+**2. Properties to Extract**
+- `geometry` - use as `d` attribute in `<path>`
+- `fill` - convert design variables to CSS variables (e.g., `$primary` → `var(--primary)`)
+- `stroke` properties if present (`strokeColor`, `strokeThickness`)
+- `width` and `height` for viewBox calculation
+
+**3. Implementation**
+- Use exact geometry string in `d` attribute
+- Set `viewBox="0 0 {width} {height}"`
+- Preserve all stroke properties
+- For styling, see tailwind.md "SVG Styling" section for Tailwind-specific syntax
+
+**4. Logos and Complex Icons**
+- Extract complete geometry even if very long
+- Don't simplify or approximate
+- Maintain precision for brand assets
+
+### Step 3: Component Validation
+
+1. **Visual Verification**:
+   - Use `TakeScreenshot` on design component
+   - Compare with rendered React component
+   - Verify pixel-perfect match
+
+2. **Style Verification**:
+   - Inspect computed CSS properties
+   - Verify dimensions, spacing, colors, typography match design
+   - Ensure CSS variables resolve correctly
+
+3. **Behavior Verification**:
+   - Test fill_container elements expand properly
+   - Test fit_content elements size to content
+   - Verify no overflow issues
+
+4. **Iterative Fixing**:
+   - Fix discrepancies immediately
+   - Re-validate after each fix
+   - Only proceed to next component when current is perfect
+
+### Step 4: Frame Integration
+
+#### Pre-Integration Analysis
+
+- Read complete target frame with `maxDepth: 10`
+- Map component tree structure
+- Identify all component instances
+
+#### Instance Configuration
+
+- Document all property overrides for each instance
+- Verify nested component overrides
+- Create instance mapping with exact props
+- **Layout Context**:
+  * Check parent container layout mode
+  * If flex container with multiple `fill_container` children → each needs `flex-1`
+  * Document which components need `flex-1` based on parent layout
+
+#### Completeness Verification
+
+- Count component instances in design vs implementation
+- Verify all props match design overrides
+- Confirm nested components follow required/optional decision from Step 1C
+- Use checklist:
+  * [ ] All instances accounted for
+  * [ ] All props match overrides
+  * [ ] Nested components render correctly (always vs conditional)
+  * [ ] Layout classes applied correctly (`flex-1`, etc.)
+
+### Step 5: Final Validation
+
+- Verify component positions and spacing match design
+- Verify colors resolve correctly
+- Verify typography matches
+- Verify responsive behavior:
+  * Layout adapts to different viewport sizes
+  * Scrollable areas work when content exceeds space
+  * No horizontal overflow
+  * `fill_container` elements expand properly
+  * `fit_content` elements size to content
+- Verify no console errors
+- Verify all interactive elements function correctly
+
+## Key Principles
+
+- Use the project's styling system consistently (avoid inline styles when possible)
+- If using Tailwind, see tailwind.md for Tailwind-specific implementation details
+- Match design values exactly
+- Use the project's color system (CSS variables, design tokens, theme files, etc.) - avoid hardcoded values
+- Process components one at a time with validation
+- Verify nested component rendering requirements
+- Ensure proper styling and layout based on parent context

package/dist/out/skills/pen-dev/guide/components.md

@@ -0,0 +1,45 @@
+# Components and Instances
+
+- Object that has `reusable` property `true` can be also called a "component" or a "symbol"
+- Components will always have a random generated ID. It's not possible to set the ID of a component.
+- Components can be used to replicate the same object tree in multiple places, to avoid repetition. This is ideal for common widgets in a design, like buttons, form fields, toggles, cards, etc.
+- To reuse a component, use the `ref` object type that points to a reusable component. `ref` objects are also called "instances".
+- Instances have a `ref` property, which identifies the mother component.
+- The `ref` property of the instance must be set to the reused component's `id`.
+- Instances can be customized by overriding objects' properties in their subtree:
+  - To override properties of the component's root object, just put the overridden properties in the `ref` object.
+  - To override properties of an object inside the component's subtree, use the `descendants` property of the `ref`. Put the overridden properties under the customized object's `id`, path, or unique name inside the `descendants` map. If a name is not unique, use the node ID/path instead. When accessing multi-level descendant nodes in the component, use paths in the `descendants` object keys to access it, DO NOT create multiple levels of `descendants` objects.
+  - To override properties of an object inside a nested instance, the object's `id` must be prefixed by the instance's `id` followed by a slash (/). This works for arbitrarily nested component instances, e.g. consider an icon component; and a button component that contains an instance of this icon; and a menu component that contains multiple instances of the button component; and a sidebar component that contains an instance of the menu component!
+  - Parts of an instance's object tree can also be replaced with completely new objects: if the `type` property is present for a particular descendant, it means that the whole subtree will be swapped out with the override. In this case, the override must be a complete object tree, not just properties! This mechanism is useful for reusable container-type objects, such as windows, tables, grids, cards, etc.
+- An instance can emulate the deletion of a nested object from its subtree by overriding its `enabled` property with `false`.
+- You cannot reference components across files. If you want to use a component from a different file you must copy it over.
+- Try to use existing components in the document instead of always making new ones.
+- Instead of duplicating the same component multiple times with small tweaks. Try to find a way to make them more generic so the instances can use them in more places.
+- Overrides will be only applied to the object it's overriding. The changes will not be inherited to all children.
+- When parsing designs, treat "component" word broadly - some components are formally defined symbols that can be references, others are ad-hoc groupings that visually or functionally behave like components, sometimes their node name is prefixed "component/"
+- When copying nodes and modifying descendants, use the `descendants` property in the Copy operation. Never use separate Update operations for descendants of copied nodes, as this will fail due to ID mismatches.
+- An instance (`ref` node) has no `children` of its own - its subtree comes from the component. Do NOT `Get` an instance to discover its children: use the component's child ids you already have (from creating it or from the response mapping) in `instanceId + "/" + componentChildId` paths, or `Get(instanceId, {resolveInstances: true})` if you truly need to read the expanded subtree.
+- When modifying component instance descendants:
+  - Use `Update(instanceId+"/childId", {...})` to change properties
+  - Use `newNodeId=Replace(instanceId+"/childId", {...})` to replace with a new node
+  - Use `newNodeId=Insert()` when the parent is a regular frame
+- IMPORTANT: DO NOT try to Update a node's descendant that you just copied (Copy), since copying will recreate the descendant nodes and it will assign new IDs to those children nodes.
+- Prefer using `fit_content` or `fill_container` size instance override to resize the component instance into the new location.
+- When an instance is not inside an object using `layout`, it must be positioned by overriding its `x` and `y` properties. Do this even if the position is (0, 0). Never override just a single position axis. Always override both if you need to specify the position.
+- An object must have a specified position, or be a child of an object using horizontal or vertical layout.
+
+**Pattern: Insert instance, then Update descendants**
+
+```js
+cardId=Insert("Casf3fX",{type:"ref",ref:"abc",name:"Account Card"})
+Update(cardId+"/childTitleId",{content:"Account Details"})
+Update(cardId+"/childDescriptionId",{content:"Manage your settings"})
+```
+
+**Pattern: Insert instance, then Replace a slot**
+
+```js
+cardId=Insert("Casf3fX",{type:"ref",ref:"abc",name:"Account Card"})
+customContentId=Replace(cardId+"/contentSlotId",{type:"frame",name:"Content",layout:"vertical"})
+item1Id=Insert(customContentId,{type:"text",name:"Item 1",fontFamily:"Inter",content:"Item 1",fill:"#000000"})
+```