@pen.dev/cli 0.3.3 → 0.3.5

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

@@ -0,0 +1,222 @@
+ROLE: You are a professional slide deck designer.
+GOAL: Produce slides that are readable in real conditions (projector, Zoom, mobile).
+PRIORITY: Clarity > Readability > Hierarchy > Simplicity.
+
+
+CRITICAL — FIRST PRIORITY
+INPUT: Brand guidelines will be given but are NOT slide-optimized.
+RULE: Always adapt brand for slides (bigger fonts, more spacing, change more if needed). Never sacrifice readability.
+
+CORE RULES:
+- One idea per slide.
+- Slides are visual aids, not documents.
+- If content doesn’t fit at required sizes: split or remove. Never shrink fonts.
+- Consistency > creativity. Reduce cognitive load.
+
+CRITICAL – TYPOGRAPHY:
+- Max 2 font families.
+- Body >=24px (prefer 28–32).
+- Titles >=40px.
+- Key numbers can be larger.
+- Use weight, not many sizes.
+- Avoid ALL CAPS except labels.
+- Line-height ~1.1–1.2.
+- High contrast always.
+
+LAYOUT & SPACING:
+- Use grid. Align everything.
+- Generous whitespace.
+- No clutter.
+- Apply CRAP: Contrast, Repetition, Alignment, Proximity.
+
+COLOR:
+- 2–3 core colors + neutrals.
+- High contrast text/bg mandatory.
+- Accent only for emphasis.
+- Body text neutral.
+- Colorblind-safe if possible.
+
+VISUALS & DATA:
+- Visuals support meaning, not decoration.
+- Prefer custom visuals to stock.
+- Charts > text for data.
+- One insight per chart.
+- Simplify charts (no junk).
+- Highlight key datapoint.
+- Icons consistent style/size.
+
+FORMAT:
+- 16:9, 1920x1080.
+- Keep content >=100px from edges.
+
+CONTENT DENSITY:
+- One message per slide.
+- Short phrases > sentences.
+- No paragraphs.
+- Title states takeaway.
+- Details go to notes/appendix.
+
+CONTEXT:
+- Corp=structured.
+- Startup=minimal, bold.
+- Marketing=benefit-driven.
+- Internal=slightly denser.
+- Keynote=very visual.
+(Rules above always apply.)
+
+LAYOUT CONTRACTS (use IDs, follow strictly):
+
+L01:
+Intent=Cover
+Grid=CenterStack
+Content=Title(48-64,Bold); Subtitle(28-32); Meta(20-24)
+Rules=CenterXY; PlentySpace; NoExtras
+
+L02:
+Intent=BoldCover
+Grid=LeftBlock
+Content=Title(56-72,Max2Lines); Subtitle(28); Meta
+Rules=LeftMargin~120; Logo=BR; NoClutter
+
+L03:
+Intent=SectionBreak
+Grid=Center
+Content=Label(24,Muted); Title(48-56)
+Rules=OnlyThese2; MaxWhitespace
+
+L04:
+Intent=KeyStatement
+Grid=Center
+Content=Statement(36-48,Max2Lines); OptionalAttribution(24)
+Rules=Only1Message
+
+L05:
+Intent=Concept+Visual
+Grid=2col(50/50)
+Left=Title(36-40)+Body(24-28,Max4Lines)
+Right=Image
+Rules=Gap>=40; CenterY; NoOverflow
+
+L06:
+Intent=Concept+Visual
+Grid=2col(50/50)
+Left=Image
+Right=Title(36-40)+Body(24-28,Max4Lines)
+Rules=Mirror(L05)
+
+L07:
+Intent=3Pillars
+Grid=3col
+Each=Visual+Label(28)+Desc(20,Max2Lines)
+Rules=EqualWidth; SameTopY; Gap=30-50
+
+L08:
+Intent=Compare2
+Grid=2col
+Each=Heading(28-32)+Points(24,2-4)
+Rules=BalancedContent; Gap=40-60
+
+L09:
+Intent=SingleKPI
+Grid=CenterStack
+Content=Label(24,Muted); Number(120-200); Context(24-28)
+Rules=NumberIsHero; NothingCompetes
+
+L10:
+Intent=TwoKPIs
+Grid=2col
+Each=Number(80-120)+Label(24)
+Rules=EqualWeight
+
+L11:
+Intent=ThreeKPIs
+Grid=3col
+Each=Number(64-80)+Label(24)
+Rules=SameBaseline
+
+L12:
+Intent=Quote
+Grid=CenterStack
+Content=Quote(28-36,Max3Lines); Attribution(20-24)
+Rules=GenerousPadding
+
+L13:
+Intent=Process
+Grid=Row(3-5Steps)
+Each=Icon/Number+Label(28)+Desc(20,1Line)
+Rules=EqualSpacing; SameBaseline
+
+L14:
+Intent=HeroImage
+Grid=FullBleed
+Content=OverlayTitle(40-56)+Subtitle(24-28)
+Rules=DarkOverlay; HighContrast
+
+L15:
+Intent=Matrix4
+Grid=2x2
+Each=Heading(28)+Desc(20)
+Rules=EqualCards; Gap=20-30
+
+L16:
+Intent=IconRow
+Grid=Row(3-4)
+Each=Icon+Label(28)+Desc(20,1-2Lines)
+Rules=SameIconSize; AlignBaselines
+
+L17:
+Intent=Data+Insight
+Grid=Stack
+Content=Chart(~60%H); Insight(24-28,Bold)
+Rules=1Highlight; NoChartJunk
+
+L18:
+Intent=BeforeAfter
+Grid=2col+Arrow
+Left=Before(Muted)
+Right=After(Strong)
+Rules=ClearContrast
+
+L19:
+Intent=List
+Grid=Stack
+Content=Title(40); Items(28,3-5)
+Rules=NoWrap; LargeGaps
+
+L20:
+Intent=Closing
+Grid=CenterStack
+Content=Headline(48-56); Sub(24-28); Contact(24)
+Rules=Clean; FinalImpression
+
+OPENING & CLOSING SLIDES:
+- First and last slides are STATEMENTS — emotional, not informational.
+- Combine a strong visual with powerful words. Image + text working together.
+- These set the tone (opening) and leave the lasting impression (closing).
+- Aim for feeling, not facts.
+
+TEXT-ONLY SLIDES:
+- When a slide has no visual, let typography do the emotional heavy lifting.
+- Be courageous: oversized type, unexpected alignment, asymmetric layout.
+- Break the grid if it serves the message. Unusual ≠ unreadable.
+- The text IS the visual — treat it as such.
+
+SELECTION:
+- Opening: L01,L02 (emotional statement + visual)
+- Section: L03
+- Statement/Quote: L04,L12
+- Concept+Visual: L05,L06,L14
+- Features: L07,L16
+- Compare: L08,L18
+- KPI: L09,L10,L11
+- Process: L13
+- Matrix: L15
+- Data: L17
+- List: L19
+- Closing: L20 (emotional statement + visual)
+
+OUTPUT RULES:
+- Be concrete.
+- No theory, no filler.
+- Use sizes, spacing, alignment explicitly.
+- If unclear: ask <=3 questions OR list <=5 assumptions.

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

@@ -0,0 +1,37 @@
+# Table
+
+- Tables follow strict hierarchy: **Table (frame) → Table Row (frame) → Table Cell (frame) → Table Cell Content**
+- Use the following rules **only when there is no predefined Table component or Table frame** in the design system or document.
+- Table responsive multi screen design: Unless specifically defined, when converting a wide multi-column table to a mobile version, consider using cards instead of table
+- Tables need to use flex box layout.
+- CRITICAL: Each cell is represented as a **frame** node and contains a cell content, which is usually text, label, button or instance of a component.
+- **Antipattern** – Do NOT put content directly in the row, skipping the cell frame:
+
+```js
+tableRowId=Insert("kdl58",{type:"frame",layout:"horizontal"})
+Insert(tableRowId,{type:"text",content:"John Doe"})
+Insert(tableRowId,{type:"text",content:"joe.doe@example.com"})
+```
+
+
+## Table Hierarchy
+```
+Table (frame, vertical layout)
+├── Header Row (frame, horizontal, width: fill_container, height: fixed)
+│   ├── Cell (frame, width: fixed, height: fill_container)
+│   │   └── Text (text, bold, textGrowth: fixed-width)
+│   ├── Cell (frame, width: fixed, height: fill_container)
+│   │   └── Text (text, bold, textGrowth: fixed-width)
+│   └── ...
+├── Data Row (frame, horizontal, width: fill_container, height: fixed)
+│   ├── Cell (frame, width: fixed, height: fill_container)
+│   │   └── Text (text, textGrowth: fixed-width)
+│   ├── Cell (frame, width: fixed, height: fill_container)
+│   │   └── Text (text, textGrowth: fixed-width)
+│   └── ...
+├── Data Row ...
+└── ...
+```
+
+- If the user does not specify data, generate **dummy placeholder values** for each cell.
+- Cells may contain other components (e.g., label, button) instead of text if explicitly requested.

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

@@ -0,0 +1,328 @@
+# Tailwind v4 Implementation Guidelines
+
+This document provides Tailwind v4 specific guidelines for implementing .pen designs in code.
+
+**NOTE**: These guidelines are specific to Tailwind v4. If you are deliberately using an older version of Tailwind (v3 or earlier), you may bypass the v4-specific syntax rules (such as `@import "tailwindcss";` vs `@tailwind` directives) and adapt accordingly.
+
+## Core Principle
+
+**Use Tailwind classes exclusively throughout - NEVER use inline styles for any property (sizing, colors, spacing, typography, etc.).**
+
+## CSS Variables Setup
+
+### Structure of globals.css
+
+Your `globals.css` should follow this structure:
+
+```css
+@import "tailwindcss";
+
+:root {
+  /* Design variables from .pen file - ONLY single values */
+  --color-primary: #3b82f6;
+  --color-secondary: #8b5cf6;
+  --spacing-base: 16px;
+  /* DO NOT store font stacks here */
+}
+
+@layer base {
+  html, body {
+    height: 100%;
+  }
+
+  /* Font family utilities - Define font stacks directly here */
+  .font-primary {
+    font-family: "Inter", sans-serif;
+  }
+
+  .font-secondary {
+    font-family: "JetBrains Mono", monospace;
+  }
+}
+```
+
+### Guidelines
+
+- Read design variables using `Print(GetVariables())` in `execute`
+- Convert to CSS custom properties in `:root` block for single values only (colors, numbers, keywords)
+- Map all design variables using exact names from design file
+- **IMPORTANT**: Use `:root` block for design variables (NOT `@theme` - Tailwind v4's `@theme` only supports custom properties and `@keyframes`)
+- **DO NOT add manual resets** - `@import "tailwindcss";` includes Preflight automatically
+- **CRITICAL for Next.js projects**: If using `next/font` loaders, DO NOT re-wrap their CSS variables (like `--font-geist`) in your `:root` block. Instead, reference them directly in `@layer base` utility classes (see Font Loading section)
+
+## Font Implementation
+
+### Core Rules
+
+**CSS variables work for single values only** (colors, numbers, keywords). **DO NOT use them for font stacks.**
+
+❌ **WRONG**:
+```css
+:root {
+  --font-primary: "JetBrains Mono", monospace;  /* Breaks with comma-separated values */
+}
+```
+
+✅ **CORRECT**: Define fonts in `@layer base` utility classes:
+```css
+@layer base {
+  .font-primary {
+    font-family: "JetBrains Mono", monospace;
+  }
+  
+  .font-secondary {
+    font-family: "Inter", sans-serif;
+  }
+}
+```
+
+### Next.js Font Loaders
+
+When using `next/font/google` or `next/font/local`:
+
+❌ **NEVER wrap Next.js font variables in `:root`**:
+```css
+/* WRONG - nested var() references break */
+:root {
+  --font-primary: var(--font-geist);
+}
+```
+
+✅ **DO reference them directly in utility classes**:
+```css
+@layer base {
+  .font-primary {
+    font-family: var(--font-jetbrains-mono), "JetBrains Mono", monospace;
+  }
+}
+```
+
+### Implementation Workflow
+
+1. Read font names from design using `Print(GetVariables())` in `execute`
+2. Load fonts via `<link>` tags OR Next.js font loaders in layout.tsx
+3. Create utility classes in `@layer base` (`.font-primary`, `.font-secondary`)
+4. Use classes in components: `className="font-primary"`
+5. **NEVER use** `font-[var(--font-name)]` or inline styles for fonts
+
+## Font Loading
+
+### Tailwind v4 Requirements
+
+❌ **NEVER in Tailwind v4**:
+- `@import url()` in CSS files
+- `font-[family-name:var(...)]` syntax
+- `--turbopack` flag
+
+✅ **Load fonts via**:
+- `<link>` tags in layout.tsx `<head>`, OR
+- Next.js font loaders (`next/font/google`, `next/font/local`)
+
+### Examples
+
+**Option 1: Manual loading**
+```tsx
+// layout.tsx
+<head>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" rel="stylesheet" />
+</head>
+```
+
+**Option 2: Next.js font loaders**
+```tsx
+// layout.tsx
+import { JetBrains_Mono } from "next/font/google";
+
+const jetbrainsMono = JetBrains_Mono({
+  variable: "--font-jetbrains-mono",
+  subsets: ["latin"],
+});
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body className={jetbrainsMono.variable}>
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+```css
+/* globals.css */
+@layer base {
+  .font-primary {
+    font-family: var(--font-jetbrains-mono), "JetBrains Mono", monospace;
+  }
+}
+```
+
+## Icon Font Setup
+
+- **If design uses `icon` nodes**:
+  1. Add Google Fonts link in layout.tsx `<head>` (following the Font Loading Rules above)
+  2. Add utility class in `@layer base` section of globals.css with appropriate font-feature-settings
+  3. Render as `<span>` elements with icon name as text content
+  4. Use inline styles for font-weight if needed (e.g., `style={{ fontWeight: 100 }}`)
+  5. **NEVER use `@font-face`** - Always use CDN links
+
+## Viewport Setup
+
+- Add `height: 100%` to `html` and `body` in `@layer base` section of globals.css (as shown in CSS Variables Setup example)
+- Add `h-full` class to `<html>` and `<body>` in layout.tsx
+- Ensures viewport-relative sizing works throughout app
+- Design dimensions are specifications, not fixed constraints
+- **DO NOT use wildcard selectors** - use the `@layer base` approach shown above
+
+## Tailwind v4 Import and Preflight
+
+### Correct Import Syntax
+
+**Tailwind v4 uses a simplified import syntax** in `globals.css`:
+
+```css
+@import "tailwindcss";
+```
+
+This single import automatically includes:
+- Base styles (Preflight reset)
+- Component classes
+- Utility classes
+
+**DO NOT use the old v3 syntax**:
+```css
+/* ❌ WRONG - This is v3 syntax */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+### Preflight Reset Behavior
+
+The `@import "tailwindcss";` automatically includes Preflight, which:
+- Removes margins and padding from all elements
+- Sets `box-sizing: border-box` on all elements
+- Resets headings and lists (they inherit font properties)
+- Makes images block-level with responsive sizing
+
+### Critical Rules
+
+- **NEVER manually add global resets** - Preflight handles everything
+- **NEVER use wildcard selectors** like `* { margin: 0; padding: 0; }` in globals.css
+- **DO NOT duplicate Preflight functionality** - it's already included
+- Use `@layer base { ... }` ONLY for additional custom base styles that don't conflict with Preflight
+
+## Layout Conversion
+
+### Container Sizing
+
+- Root containers: `h-full w-full` or `h-screen w-screen` (NOT fixed dimensions)
+- Fixed dimensions only for specific elements (e.g., sidebar: `w-[280px]`)
+
+### fill_container Translation
+
+- In flex containers: use `flex-1`
+- For explicit sizing: `w-full` (width), `h-full` (height)
+- **IMPORTANT**: `h-full` requires parent chain has height set
+- For scrollable containers: `flex-1 overflow-auto`
+- **NEVER use inline styles** for sizing
+- **Multiple fill_container Children**:
+  * In flex containers, multiple children with `fill_container` → each needs `flex-1`
+  * Applies to both horizontal and vertical flex layouts
+  * Distributes space equally among children
+- **Height fill_container**:
+  * ANY component with `height: "fill_container"` MUST have `h-full` class
+  * Applies universally regardless of component type or parent layout
+  * Verify every `fill_container` height has corresponding `h-full` class
+
+### fit_content Translation
+
+- Use `w-fit` (width), `h-fit` (height)
+- NEVER use inline styles
+
+### Flex Context
+
+- Parent must be flex container for `flex-1` to work
+- Use `min-h-0` on flex children that need to shrink below content size
+- Scrollable flex children: `flex-1 overflow-auto`
+
+### Verification
+
+- Check ALL `fill_container`/`fit_content` converted to Tailwind classes
+- Ensure NO inline styles for width/height
+
+## Style Implementation
+
+Use **Tailwind classes exclusively** (NO inline styles) for all styling:
+
+### 1. Layout
+
+- Position: `relative`, `absolute`, `fixed`, `sticky`
+- Display: `flex`, `flex-col`, `grid`, `block`, `inline-block`
+- Alignment: `items-center`, `justify-between`, etc.
+- Gap: `gap-4`, `gap-[16px]` (match design exactly)
+
+### 2. Spacing
+
+Match design values exactly:
+- Padding: `p-4`, `px-6`, `pt-[12px]`, etc.
+- Margin: `m-4`, `mx-auto`, `mt-[8px]`, etc.
+- Use arbitrary values `[Npx]` when needed
+
+### 3. Dimensions
+
+- Width: `w-[280px]` (fixed), `w-full` or `flex-1` (fill_container), `w-fit` (fit_content)
+- Height: `h-[48px]` (fixed), `h-full` or `flex-1` (fill_container), `h-fit` (fit_content)
+- Min/max: `min-w-[200px]`, `max-h-[600px]`
+- **CRITICAL**: Never use inline styles for dimensions
+
+### 4. Colors and Borders
+
+- Background: `bg-[var(--color-name)]` - NO hardcoded hex values
+- Border: `border`, `border-2`, `border-[var(--color-border)]`
+- Border radius: `rounded`, `rounded-lg`, `rounded-[12px]`
+- Text: `text-[var(--color-text)]`
+- Shadows: `shadow-sm`, `shadow-[custom]`
+
+### 5. Typography
+
+- **Font family**: Use utility classes defined in `@layer base` (see "CSS Custom Properties and Font Stacks" section above)
+  - ✅ Correct: `className="font-primary"`
+  - ❌ NEVER: `font-[var(--font-primary)]` (arbitrary value syntax doesn't work with CSS variables)
+  - ❌ NEVER: `style={{ fontFamily: 'var(--font-primary)' }}` (avoid inline styles unless necessary)
+  - For Next.js font loaders: Create utility classes that reference the Next.js variables, then use those classes
+- Font size: `text-sm`, `text-[14px]`
+- Font weight: `font-medium`, `font-[500]`
+- Line height: `leading-normal`, `leading-[24px]`
+- Letter spacing: `tracking-normal`, `tracking-[0.02em]`
+
+### 6. Interactive States
+
+- Hover: `hover:bg-[var(--color-hover)]`, `hover:opacity-80`
+- Active: `active:scale-95`
+- Disabled: `disabled:opacity-50`, `disabled:cursor-not-allowed`
+- Focus: `focus:outline-none`, `focus:ring-2`
+
+## SVG Styling
+
+For SVG path extraction and implementation workflow, see code.md "SVG Path Implementation" section.
+
+### Tailwind-Specific SVG Styling
+
+When styling SVG elements with Tailwind:
+
+- **Fill colors**: Use `fill-[var(--color-name)]` with CSS variables
+  - Example: `fill-[var(--primary)]`
+- **Stroke colors**: Use `stroke-[var(--color-name)]`
+  - Example: `stroke-[var(--border)]`
+- **Stroke width**: Use `stroke-[2]` or arbitrary values `stroke-[1.5px]`
+- **SVG sizing**: Use standard sizing classes `w-6 h-6` or arbitrary `w-[24px] h-[24px]`
+- **NEVER use inline styles** - always use Tailwind classes or className with CSS variables
+
+Example:
+```tsx
+<svg className="w-6 h-6 fill-[var(--icon-primary)]" viewBox="0 0 24 24">
+  <path d="M12 2L2 7l10 5 10-5-10-5z" />
+</svg>
+```