### Pencil CLI Quick Start Examples

Source: https://docs.pencil.dev/for-developers/pencil-cli

A collection of common Pencil CLI operations including login, creating new designs, modifying existing ones, exporting to PNG, and starting an interactive shell.

```bash
# Log in first
pencil login
 
# Create a new design from scratch
pencil --out design.pen --prompt "Create a login page with email and password fields"
 
# Modify an existing design
pencil --in existing.pen --out modified.pen --prompt "Add a blue submit button"
 
# Export a design to PNG
pencil --in design.pen --export design.png
 
# Start an interactive shell
pencil interactive -o design.pen
 
# List available models
pencil --list-models
```

--------------------------------

### Example AI Integration Session

Source: https://docs.pencil.dev/getting-started/ai-integration

This example session demonstrates a typical workflow involving Pencil AI, from starting the tools to committing changes to Git. It covers design creation, refinement, code generation, and version control.

```bash
# 1. Start Pencil and Claude Code
claude

# 2. Open design.pen in IDE

# 3. Press Cmd + K and start designing
User: "Create a modern landing page hero section"
AI: [Creates hero with heading, subheading, CTA buttons]

User: "Add a features section with 3 columns"
AI: [Adds features section below hero]

User: "Use our primary color variable for the CTA buttons"
AI: [Updates buttons to use color variable]

User: "Generate React code for this entire page"
AI: [Exports to React component with Tailwind CSS]

# 4. Review and refine
# 5. Commit to Git
git add design.pen src/pages/landing.tsx
git commit -m "Add landing page design and implementation"
```

--------------------------------

### Example Pencil Interactive Session

Source: https://docs.pencil.dev/for-developers/pencil-cli

Demonstrates a sequence of commands within the Pencil interactive shell, including getting editor state, guidelines, performing design operations, and saving.

```bash
pencil > get_editor_state({ include_schema: true })
pencil > get_guidelines()
pencil > get_guidelines({ category: "guide", name: "Landing Page" })
pencil > batch_design({ operations: 'hero=I(document,{type:"frame",name:"Hero",x:0,y:0,width:1440,height:900,fill:"#0A0A0A"})' })
pencil > get_screenshot({ nodeId: "hero" })
pencil > save()
pencil > exit()
```

--------------------------------

### Verify Pencil CLI Installation

Source: https://docs.pencil.dev/for-developers/pencil-cli

Check if the Pencil CLI is installed correctly by running the version command.

```bash
pencil version
```

--------------------------------

### Project File Organization Example

Source: https://docs.pencil.dev/design-and-code/design-to-code

Illustrates recommended file organization for a project using Pencil, keeping `.pen` files within the repository for version control and AI access.

```text
my-project/
├── src/
│   ├── components/
│   └── styles/
├── design.pen           ← Design file
└── package.json
```

--------------------------------

### Install Pencil CLI

Source: https://docs.pencil.dev/for-developers/pencil-cli

Install the Pencil CLI globally using npm. Requires Node.js 18 or later.

```bash
npm install -g @pencil.dev/cli
```

--------------------------------

### CI/CD Setup for Pencil

Source: https://docs.pencil.dev/for-developers/pencil-cli

Sets environment variables for API keys required to run Pencil in automated pipelines. The CLI key takes precedence over stored sessions.

```bash
export PENCIL_CLI_KEY=pencil_cli_...
export ANTHROPIC_API_KEY=sk-ant-...

pencil --out onboarding.pen --prompt "Create a 3-step onboarding flow"
```

--------------------------------

### Install Pencil Desktop App on Linux

Source: https://docs.pencil.dev/getting-started/installation

Use these commands to install the Pencil desktop application on Linux, depending on your package type. Ensure you have the correct package file.

```bash
sudo dpkg -i pencil-*.deb
```

```bash
chmod +x pencil-*.AppImage
./pencil-*.AppImage
```

--------------------------------

### Run Pencil in Headless Mode (New Canvas)

Source: https://docs.pencil.dev/for-developers/pencil-cli

Starts a local Pencil editor instance without a GUI for creating a new design. Output is saved to the specified file.

```bash
# New empty canvas
pencil interactive -o output.pen
```

--------------------------------

### Start Pencil Interactive Mode

Source: https://docs.pencil.dev/for-developers/pencil-cli

Launches the interactive shell for direct MCP tool calls. Use options to specify input/output files or connect to a running app.

```bash
pencil interactive [options]
```

--------------------------------

### Install Claude Code CLI

Source: https://docs.pencil.dev/getting-started/installation

Install the Claude Code CLI using npm or the official installer script. This is required for Pencil's AI features.

```bash
npm install -g @anthropic-ai/claude-code-cli
```

```bash
curl https://claude.ai/cli/install.sh | sh
```

--------------------------------

### Run Pencil in Headless Mode (Edit Existing)

Source: https://docs.pencil.dev/for-developers/pencil-cli

Starts a local Pencil editor instance without a GUI for editing an existing design. Input and output files must be specified.

```bash
# Edit an existing file
pencil interactive -i input.pen -o output.pen
```

--------------------------------

### Example Batch Tasks JSON File

Source: https://docs.pencil.dev/for-developers/pencil-cli

A sample JSON file defining tasks for batch processing designs. Each task includes output path, prompt, and optional input file and model override.

```json
{
  "tasks": [
    {
      "out": "landing-page.pen",
      "prompt": "Create a SaaS landing page with hero, features, and pricing sections"
    },
    {
      "in": "existing-app.pen",
      "out": "existing-app-v2.pen",
      "prompt": "Add a dark mode toggle to the header"
    },
    {
      "out": "mobile-menu.pen",
      "model": "claude-haiku-4-5",
      "prompt": "Create a mobile hamburger menu component"
    }
  ]
}
```

--------------------------------

### Use a Specific Model with Pencil CLI

Source: https://docs.pencil.dev/for-developers/pencil-cli

Specify a particular AI model to use for design generation or modification. This example uses Claude Haiku for faster, simpler tasks.

```bash
# Use Claude Haiku for simple, fast tasks
pencil --out simple.pen \
  --model claude-haiku-4-5 \
  --prompt "Create a simple 404 error page"
```

--------------------------------

### Example Prompts for Claude Code

Source: https://docs.pencil.dev/getting-started/ai-integration

Use these prompts in the AI prompt panel to guide AI in creating, modifying, or managing designs within Pencil.

```plaintext
"Create a login form with email and password"
```

```plaintext
"Add a navigation bar to this page"
```

```plaintext
"Design a card component for my design system"
```

```plaintext
"Design a dashboard with sidebar and main content area"
```

```plaintext
"Create a pricing table with 3 tiers"
```

```plaintext
"Add a hero section with heading and CTA button"
```

```plaintext
"Change all primary buttons to blue"
```

```plaintext
"Make the sidebar narrower"
```

```plaintext
"Add spacing between these elements"
```

```plaintext
"Create a button component with variants"
```

```plaintext
"Generate a color palette based on #3b82f6"
```

```plaintext
"Build a typography scale"
```

```plaintext
"Generate React code for this component"
```

```plaintext
"Import the Header from my codebase"
```

```plaintext
"Create Tailwind config from these variables"
```

--------------------------------

### Pencil Script File Header

Source: https://docs.pencil.dev/core-concepts/code-on-canvas

Every script must start with a header comment declaring its schema version and inputs. Use '2.11' for the current schema version. Inputs become controls in the properties panel.

```javascript
/**
 * @schema <version>
 * @input <name>: <type>[(<args>)] [= <default>]
 */
```

--------------------------------

### Pencil Script Example: Grid Layout

Source: https://docs.pencil.dev/core-concepts/code-on-canvas

This script generates a grid of rectangles based on input parameters like rows, gap, fill color, and rounded corners. Ensure input values are within specified ranges.

```javascript
/**
 * @schema 2.11
 *
 * @input rows: number(min=1, max=20) = 5
 * @input gap: number(min=0) = 6
 * @input fill: color = #10B981
 * @input rounded: boolean = true
 */
const rows = Math.floor(pencil.input.rows);
const gap = pencil.input.gap;
const rowH = (pencil.height - gap * (rows - 1)) / rows;
 
const nodes = [];
for (let r = 0; r < rows; r++) {
  nodes.push({
    type: "rectangle",
    x: 0,
    y: r * (rowH + gap),
    width: pencil.width,
    height: rowH,
    cornerRadius: pencil.input.rounded ? 8 : 0,
    fill: pencil.input.fill,
  });
}
return nodes;
```

--------------------------------

### Theme Interface Definition

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines a theme where each key must be an existing theme axis and each value must be one of the possible values for that axis. Example: { 'device': 'phone' }.

```typescript
export interface Theme {
  [key: string]: string;
}
```

--------------------------------

### Recreate Component from File Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Use this prompt to import an existing component from your codebase into Pencil. Ensure the `.pen` file is in the same workspace.

```text
Recreate the Button component from src/components/Button.tsx
```

--------------------------------

### Create an Instance of a Component in .pen Format

Source: https://docs.pencil.dev/for-developers/the-pen-format

Use the `ref` type and specify the `ref` property to create an instance of a reusable component. This creates an instance named 'bar' of the component 'foo'.

```json
{
  "id": "bar",
  "type": "ref",
  "ref": "foo", // <- this object is an instance of the component "foo"
  "x": 120, "y": 0
}
```

--------------------------------

### Connect to Pencil Desktop App

Source: https://docs.pencil.dev/for-developers/pencil-cli

Connects to a running Pencil desktop app in interactive mode, applying changes live. Requires specifying the app and an input file.

```bash
pencil interactive -a desktop -i my-design.pen
```

--------------------------------

### List Available Models in Pencil CLI

Source: https://docs.pencil.dev/for-developers/pencil-cli

Display a list of all available AI models that can be used with the Pencil CLI. This command helps in choosing the appropriate model for a task.

```bash
pencil --list-models
```

--------------------------------

### Use Shadcn/ui Components Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to utilize shadcn/ui components for a layout. This leverages a popular library for building accessible and customizable UIs.

```text
Use shadcn/ui components for this layout
```

--------------------------------

### Import LoginForm Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to import a specific component, like LoginForm, from your codebase into Pencil. This facilitates visual editing of existing components.

```text
Import the LoginForm from my codebase into this design
```

--------------------------------

### Create a New Design with Pencil CLI

Source: https://docs.pencil.dev/for-developers/pencil-cli

Use the Pencil CLI to generate a new design file based on a detailed prompt. Specify the output file and the AI prompt.

```bash
pencil --out login.pen --prompt "Create a modern login page with:
- Email input field
- Password input field
- Sign In button
- Forgot password link
- Social login options (Google, GitHub)"
```

--------------------------------

### Convert to Component

Source: https://docs.pencil.dev/troubleshooting

Use this keyboard shortcut to convert a selected element into a reusable component. After conversion, deselect and reselect the element to see the purple highlight indicating it's a component.

```bash
Cmd/Ctrl + Option/Alt + K
```

--------------------------------

### Generate React Component Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Use this prompt to generate a React component from a Pencil design. Ensure your design is ready on the canvas.

```text
Create a React component for this button
```

--------------------------------

### Process Multiple Designs with Tasks File

Source: https://docs.pencil.dev/for-developers/pencil-cli

Executes a series of design tasks defined in a JSON file. Each task can specify input, output, and an AI prompt.

```bash
pencil --tasks batch.json
```

--------------------------------

### Interactive Login for Pencil CLI

Source: https://docs.pencil.dev/for-developers/pencil-cli

Initiate an interactive login session for the Pencil CLI. This stores a session token in ~/.pencil/session-cli.json.

```bash
pencil login
```

--------------------------------

### Check Pencil CLI Status

Source: https://docs.pencil.dev/for-developers/pencil-cli

Display the current authentication method, verify the session with the backend, and show account details.

```bash
pencil status
```

--------------------------------

### Design System Management Prompts

Source: https://docs.pencil.dev/getting-started/ai-integration

These prompts help enforce consistency and manage component libraries within your design system. Use them to apply global styles or generate specific components.

```plaintext
"Ensure all buttons use the primary color variable"
```

```plaintext
"Update all headings to use the typography scale"
```

```plaintext
"Apply 8px spacing grid to all elements"
```

```plaintext
"Create a complete button component with all variants"
```

```plaintext
"Generate form input components (text, select, checkbox, radio)"
```

```plaintext
"Build a card component with image, title, description, and actions"
```

--------------------------------

### Implement Theming with Dynamic Variables

Source: https://docs.pencil.dev/for-developers/the-pen-format

Define multiple values for a variable, each associated with a specific theme. The last satisfied theme's value is used. The default theme is determined by the first value in each theme axis.

```json
{
  "variables": {
    "color.background": {
      "type": "color",
      "value": [
        { "value": "#FFFFFF", "theme": { "mode": "light" } },
        { "value": "#000000", "theme": { "mode": "dark" } }
      ]
    },
    "color.text": {
      "type": "color",
      "value": [
        { "value": "#333333", "theme": { "mode": "light" } },
        { "value": "#AAAAAA", "theme": { "mode": "dark" } }
      ]
    },
    "text.title": {
      "type": "number",
      "value": [
        { "value": 72, "theme": { "spacing": "regular" } },
        { "value": 36, "theme": { "spacing": "condensed" } }
      ]
    }
  },
  "themes": {
    "mode": ["light", "dark"],
    "spacing": ["regular", "condensed"]
  },
  "children": [
    {
      "id": "landing-page-light",
      "type": "frame",
      "fill": "$color.background",
      "children": [
        {
          "id": "welcome-label",
          "type": "text",
          "fill": "$color.text",
          "fontSize": "$text.title",
          "content": "Welcome!"
        }
      ]
    },
    {
      "id": "landing-page-dark",
      "type": "frame",
      "theme": { "mode": "dark" },
      "fill": "$color.background",
      "children": [
        {
          "id": "welcome-label",
          "type": "text",
          "fill": "$color.text",
          "fontSize": "$text.title",
          "content": "Welcome!"
        }
      ]
    },
    {
      "id": "landing-page-dark-condensed",
      "type": "frame",
      "fill": "$color.background",
      "theme": { "mode": "dark", "spacing": "condensed" },
      "children": [
        {
          "id": "welcome-label",
          "type": "text",
          "fill": "$color.text",
          "fontSize": "$text.title",
          "content": "Welcome!"
        }
      ]
    }
  ]
}
```

--------------------------------

### Authenticate Pencil CLI with a Key

Source: https://docs.pencil.dev/for-developers/pencil-cli

Use the PENCIL_CLI_KEY environment variable for authentication, which takes precedence over session tokens. Useful for CI/CD pipelines.

```bash
PENCIL_CLI_KEY=pencil_cli_... pencil --out design.pen --prompt "Create a form"
```

--------------------------------

### Sync Design Tokens to CSS Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to sync design tokens from Pencil to a CSS file. This maintains consistency between design and implementation.

```text
Sync these design tokens to my CSS
```

--------------------------------

### Generate Design with Lucide Icons Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to generate a design using Lucide icons. This specifies a preferred icon library for the output.

```text
Generate this design using Lucide icons
```

--------------------------------

### Export with Lucide Icons Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to export a design using Lucide icons instead of default Material Icons. This allows for customization of icon sets.

```text
Export using Lucide icons instead of Material Icons
```

--------------------------------

### Verify MCP Connection with Codex CLI

Source: https://docs.pencil.dev/getting-started/ai-integration

Run this command in the Codex CLI to verify that the MCP connection to Pencil is established. Pencil should appear in the MCP server list if the connection is successful.

```bash
/mcp
```

--------------------------------

### Define a Reusable Component in .pen Format

Source: https://docs.pencil.dev/for-developers/the-pen-format

Mark an object with `reusable: true` to make it a reusable component. This object defines a 100x100 red rectangle.

```json
{
  "id": "foo",
  "type": "rectangle",
  "reusable": true, // <- this object is now a reusable component
  "x": 0, "y": 0, "width": 100, "height": 100,
  "fill": "#FF0000"
}
```

--------------------------------

### Code-Design Workflow Prompts

Source: https://docs.pencil.dev/getting-started/ai-integration

Utilize these prompts for importing existing application code into Pencil or synchronizing design changes between Pencil and your codebase. These facilitate seamless integration between design and development.

```plaintext
"Recreate all components from src/components in Pencil"
```

```plaintext
"Import the design system from our Tailwind config"
```

```plaintext
"Analyze the codebase and create matching designs"
```

```plaintext
"Update all React components to match the Pencil designs"
```

```plaintext
"Apply the new color scheme to both design and code"
```

```plaintext
"Sync typography variables between CSS and Pencil"
```

--------------------------------

### Create Vue Component with TypeScript Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to create a Vue component using TypeScript. This is useful for projects that benefit from static typing in a Vue environment.

```text
Create a Vue component using TypeScript
```

--------------------------------

### Export Design to Image with Pencil CLI

Source: https://docs.pencil.dev/for-developers/pencil-cli

Export a design file to an image format (e.g., PNG) with a specified scale factor. The `--export` flag is used for this purpose.

```bash
pencil --in design.pen --export hero.png --export-scale 2
```

--------------------------------

### Replace Material Icons with Heroicons Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to replace Material Icons with Heroicons in the generated code. This allows for switching icon sets based on project requirements.

```text
Replace Material Icons with Heroicons in the code
```

--------------------------------

### Sizing Behavior

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines how an element's size behaves dynamically within a layout.

```APIDOC
## Sizing Behavior

### Description
Controls the dynamic layout size.
- fit_content: Use the combined size of all children for the container size. Fallback is used when there are no children.
- fill_container: Use the parent size for the container size. Fallback is used when the parent has no layout.
Optional number in parentheses (e.g., 'fit_content(100)') specifies the fallback size.

### Type Definition
```typescript
export type SizingBehavior = string;
```
```

--------------------------------

### Export Dashboard as React Component Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to export a dashboard design as a React component. This is useful for creating complex data visualization interfaces.

```text
Export this dashboard as a React component
```

--------------------------------

### Generate Code with Shadcn UI Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to generate code using Shadcn UI components. This ensures consistency with a popular, accessible component library.

```text
Generate code using Shadcn UI components
```

--------------------------------

### Prompt Object

Source: https://docs.pencil.dev/for-developers/the-pen-format

Represents a prompt element with text content and a model.

```APIDOC
## Prompt Object

### Description
Represents a prompt element.

### Properties
- **type** (string) - Must be "prompt".
- **content** (TextContent) - The text content of the prompt.
- **model** (StringOrVariable) - The model associated with the prompt.
```

--------------------------------

### Import Design Tokens from CSS Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to import design tokens from a specific CSS file into Pencil. This is useful for establishing a shared design system.

```text
Import design tokens from src/styles/tokens.css
```

--------------------------------

### Export Component as Reusable Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to export a design element as a reusable component. This helps in creating modular and maintainable codebases.

```text
Export this card as a reusable component
```

--------------------------------

### Automated Design Generation Prompts

Source: https://docs.pencil.dev/getting-started/ai-integration

Use these prompts to instruct AI in generating designs based on specific styles, principles, or batch requirements. Ensure prompts are clear and specific for desired outcomes.

```plaintext
"Create a dashboard using Material Design principles"
```

```plaintext
"Design a landing page with modern, minimal aesthetics"
```

```plaintext
"Build components following our design system in design-system.pen"
```

```plaintext
"Create 5 variations of this button component"
```

```plaintext
"Generate a complete form with all input types"
```

```plaintext
"Design an entire landing page with hero, features, pricing, and footer"
```

--------------------------------

### Add Header Component Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to add a Header component from your codebase into the current Pencil design. This integrates existing layout elements.

```text
Add the Header component from src/layouts/Header.tsx
```

--------------------------------

### Create Landing Page with Tailwind CSS Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to create a landing page component using Tailwind CSS. This leverages utility-first CSS for rapid UI development.

```text
Create a landing page component with Tailwind CSS
```

--------------------------------

### Authenticate Claude Code CLI

Source: https://docs.pencil.dev/getting-started/installation

Log in to Claude Code using the `claude` CLI command. This will initiate a browser-based authentication flow.

```bash
claude
```

--------------------------------

### Context Object

Source: https://docs.pencil.dev/for-developers/the-pen-format

Represents a context element with text content.

```APIDOC
## Context Object

### Description
Represents a context element.

### Properties
- **type** (string) - Must be "context".
- **content** (TextContent) - The text content of the context.
```

--------------------------------

### Pencil Interactive Shell Commands

Source: https://docs.pencil.dev/for-developers/pencil-cli

Basic commands available within the Pencil interactive shell for manipulating designs and managing the session.

```bash
tool_name({ key: value })   Call an MCP tool with arguments
```

```bash
tool_name()                 Call an MCP tool with no arguments
```

```bash
save()                      Save the document to disk
```

```bash
exit()                      Exit the shell
```

--------------------------------

### SizingBehavior Type Alias

Source: https://docs.pencil.dev/for-developers/the-pen-format

Controls dynamic layout sizing. 'fit_content' uses children's size (with fallback), 'fill_container' uses parent's size (with fallback). Fallback size can be specified in parentheses, e.g., 'fit_content(100)'.

```typescript
export type SizingBehavior = string;
```

--------------------------------

### Create Pencil Variables from CSS Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to create Pencil variables from an existing CSS file containing CSS variables. This synchronizes design tokens.

```text
Create Pencil variables from my globals.css
```

--------------------------------

### Verify Claude Code CLI Authentication

Source: https://docs.pencil.dev/getting-started/installation

Check your Claude Code CLI login status by running the `claude --version` command. This confirms successful authentication.

```bash
claude --version
```

--------------------------------

### Define Document-Wide Variables

Source: https://docs.pencil.dev/for-developers/the-pen-format

Use variables to store and reuse common values like colors and sizes. Reference them using the '$' prefix.

```json
{
  "variables": {
    "color.background": {
      "type": "color",
      "value": "#FFFFFF"
    },
    "color.text": {
      "type": "color",
      "value": "#333333"
    },
    "text.title": {
      "type": "number",
      "value": 72
    }
  },
  "children": [
    {
      "id": "landing-page",
      "type": "frame",
      "fill": "$color.background",
      "children": [
        {
          "id": "welcome-label",
          "type": "text",
          "fill": "$color.text",
          "fontSize": "$text.title",
          "content": "Welcome!"
        }
      ]
    }
  ]
}
```

--------------------------------

### Layout Schema

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines the layout properties for elements, including flexbox options, gap, padding, and alignment.

```APIDOC
## Layout Schema

### Description
Defines the layout properties for elements, including flexbox options, gap, padding, and alignment.

### Type Definition
```typescript
export interface Layout {
  /** Enable flex layout. None means all children are absolutely positioned and will not be affected by layout properties. Frames default to horizontal, groups default to none. */
  layout?: "none" | "vertical" | "horizontal";
  /** The gap between children in the main axis direction. Defaults to 0. */
  gap?: NumberOrVariable;
  layoutIncludeStroke?: boolean;
  /** The Inside padding along the edge of the container */
  padding?:
    | /** The inside padding to all sides */ NumberOrVariable
    | /** The inside horizontal and vertical padding */ [NumberOrVariable, NumberOrVariable]
    | /** Top, Right, Bottom, Left padding */ [
        NumberOrVariable,
        NumberOrVariable,
        NumberOrVariable,
        NumberOrVariable,
      ];
  /** Control the justify alignment of the children along the main axis. Defaults to 'start'. */
  justifyContent?: "start" | "center" | "end" | "space_between" | "space_around";
  /** Control the alignment of children along the cross axis. Defaults to 'start'. */
  alignItems?: "start" | "center" | "end";
}
```
```

--------------------------------

### Modify an Existing Design with Pencil CLI

Source: https://docs.pencil.dev/for-developers/pencil-cli

Modify an existing design file by providing the input file, output file, and a prompt for the AI agent. This allows for iterative design improvements.

```bash
pencil --in dashboard.pen --out dashboard-v2.pen --prompt "Add a sidebar navigation with:
- Dashboard link (active)
- Users link
- Settings link
- Logout button at bottom"
```

--------------------------------

### Ref Object

Source: https://docs.pencil.dev/for-developers/the-pen-format

Allows reusing other objects in different places.

```APIDOC
## Ref Object

### Description
References allow reusing other objects in different places.

### Properties
- **type** (string) - Must be "ref".
- **ref** (string) - The `ref` property must be another object's ID.
- **descendants** ({ [key: string]: {} }) - Customizes properties of descendant objects except `children`. Keys are ID paths to descendant objects. Values can be property overrides or complete object replacements.
```

--------------------------------

### Generate Next.js Page Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Use this prompt to generate a full Next.js page from your Pencil design. This is ideal for creating landing pages or application views.

```text
Generate a Next.js page from this design
```

--------------------------------

### Create Form with React Hook Form Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to create a form using React Hook Form. This is beneficial for managing form state and validation efficiently.

```text
Create this form using React Hook Form
```

--------------------------------

### Select Parent Element

Source: https://docs.pencil.dev/troubleshooting

Use these keyboard shortcuts to navigate up the element hierarchy and select the parent of the currently selected item. Useful for understanding and modifying structure.

```bash
Shift + Enter
```

```bash
Cmd/Ctrl + Enter
```

--------------------------------

### Basic Component Nesting

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines a reusable frame component and a reference to it, inheriting its properties.

```json
{
  "id": "round-button",
  "type": "frame",
  "reusable": true,
  "cornerRadius": 9999,
  "children": [
    {
      "id": "label",
      "type": "text",
      "content": "Submit",
      "fill": "#000000"
      ...
    }
  ]
}

{
  "id": "red-round-button",
  "type": "ref",
  "ref": "round-button",
  "fill": "#FF0000"
}
```

--------------------------------

### Size Schema

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines the width and height properties of an element, which can be a number, variable, or sizing behavior.

```APIDOC
## Size Schema

### Description
Defines the width and height properties of an element, which can be a number, variable, or sizing behavior.

### Type Definition
```typescript
export interface Size {
  width?: NumberOrVariable | SizingBehavior;
  height?: NumberOrVariable | SizingBehavior;
}
```
```

--------------------------------

### Component Built from Other Components

Source: https://docs.pencil.dev/for-developers/the-pen-format

An 'alert' component is defined using a frame, including text and instances of another component ('round-button') with customized descendants.

```json
{
  "id": "alert",
  "type": "frame",
  "reusable": true,
  "children": [
    {
      "id": "message",
      "type": "text",
      "content": "This is an alert!",
      "fill": "#000000"
      ...
    },
    {
      "id": "ok-button",
      "type": "ref",
      "ref": "round-button",
      "descendants": {
        "label": {
          "text": "OK"
        }
      }
    },
    {
      "id": "cancel-button",
      "type": "ref",
      "ref": "round-button",
      "descendants": {
        "label": {
          "text": "Cancel"
        }
      }
    }
  ]
}
```

--------------------------------

### Update CSS with Pencil Variables Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to update a CSS file with variables defined in Pencil. This ensures code reflects the latest design token changes.

```text
Update globals.css with these Pencil variables
```

--------------------------------

### Design Prompts in Codex CLI

Source: https://docs.pencil.dev/getting-started/ai-integration

Execute these commands in the Codex CLI to generate or modify designs within your `.pen` file. This enables a command-line workflow for design automation.

```bash
# In Codex CLI
> Create a button component in design.pen
```

```bash
> Add a hero section to the landing page
```

```bash
> Generate a color scheme based on blue
```

--------------------------------

### Text Growth Behavior

Source: https://docs.pencil.dev/for-developers/the-pen-format

Controls how text box dimensions behave. Must be set before width or height can be used.

```APIDOC
## Text Growth Behavior

### Description
Controls how text box dimensions behave. It must be set before width or height can be used. Without `textGrowth`, the `width` and `height` properties are ignored.

### Options
- **auto**: The text box automatically grows to fit the text content. Text does not wrap. Width and height adjust dynamically.
- **fixed-width**: The width is fixed and text wraps within it. The height grows automatically to fit the wrapped content.
- **fixed-width-height**: Both width and height are fixed. Text wraps and may be overflow if it exceeds the bounds.

### Important Note
Never set `width` or `height` without also setting `textGrowth`. If you want to control the size of a text box, you must set `textGrowth` first.
```

--------------------------------

### Theme Schema

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines the structure for theme properties, where each key is a theme axis and each value is a possible value for that axis.

```APIDOC
## Theme Schema

### Description
Each key must be an existing theme axis, and each value must be one of the possible values for that axis. E.g. { 'device': 'phone' }

### Type Definition
```typescript
export interface Theme {
  [key: string]: string;
}
```
```

--------------------------------

### IconFont Object

Source: https://docs.pencil.dev/for-developers/the-pen-format

Represents an icon from a font.

```APIDOC
## IconFont Object

### Description
Represents an icon from a font.

### Properties
- **type** (string) - Must be "icon_font".
- **iconFontName** (StringOrVariable) - Name of the icon in the icon font.
- **iconFontFamily** (StringOrVariable) - Icon font to use. Valid fonts are 'lucide', 'feather', 'Material Symbols Outlined', 'Material Symbols Rounded', 'Material Symbols Sharp', 'phosphor'.
- **weight** (NumberOrVariable) - Variable font weight, only valid for icon fonts with variable weight. Values from 100 to 700.
- **fill** (Fills) - The fill color of the icon.
```

--------------------------------

### Generate Next.js 14 with Tailwind CSS Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Prompt to generate code specifically for Next.js 14 using Tailwind CSS. This ensures compatibility with modern web development stacks.

```text
Generate Next.js 14 code with Tailwind CSS
```

--------------------------------

### Generate TypeScript Types Prompt

Source: https://docs.pencil.dev/design-and-code/design-to-code

Use this prompt to generate TypeScript types for a form based on your Pencil design. This is useful for ensuring type safety in your application.

```text
Generate TypeScript types for this form
```

--------------------------------

### Fill Schema

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines the various types of fills available for elements, including solid colors, gradients, images, and mesh gradients.

```APIDOC
## Fill Schema

### Description
Defines the various types of fills available for elements, including solid colors, gradients, images, and mesh gradients.

### Type Definition
```typescript
export type Fill =
  | ColorOrVariable
  | {
      type: "color";
      enabled?: BooleanOrVariable;
      blendMode?: BlendMode;
      color: ColorOrVariable;
    }
  | {
      type: "gradient";
      enabled?: BooleanOrVariable;
      blendMode?: BlendMode;
      gradientType?: "linear" | "radial" | "angular";
      opacity?: NumberOrVariable;
      /** Normalized to bounding box (default: 0.5,0.5). */
      center?: Position;
      /** Normalized to bounding box (default: 1,1). Linear: height sets gradient length, width is ignored. Radial/Angular: sets ellipse diameters. */
      size?: { width?: NumberOrVariable; height?: NumberOrVariable };
      /** Rotation in degrees, counterclockwise (0° up, 90° left, 180° down). */
      rotation?: NumberOrVariable;
      colors?: { color: ColorOrVariable; position: NumberOrVariable }[];
    }
  /** Image fill. Url needs to be a relative from the pen file, for example `../../file.png` or `./image.jpg` */
  | {
      type: "image";
      enabled?: BooleanOrVariable;
      blendMode?: BlendMode;
      opacity?: NumberOrVariable;
      url: string;
      mode?: "stretch" | "fill" | "fit";
    }
  /** Grid of colors with bezier-interpolated edges. Row-major order. Adjust the points and handles to create complex gradients. Keep the points on the edges at their default position. */
  | {
      type: "mesh_gradient";
      enabled?: BooleanOrVariable;
      blendMode?: BlendMode;
      opacity?: NumberOrVariable;
      columns?: number;
      rows?: number;
      /** Color per vertex. */
      colors?: ColorOrVariable[];
      /** columns * rows points in [0,1] normalized coordinates. */
      points?: (
        | /** Position with auto-generated handles. */ [number, number]
        | /** Position with optional bezier handles (relative offsets). Omitted handles are auto-generated. */ {
            position: [number, number];
```
```

--------------------------------

### Note Object

Source: https://docs.pencil.dev/for-developers/the-pen-format

Represents a note element with text content.

```APIDOC
## Note Object

### Description
Represents a note element.

### Properties
- **type** (string) - Must be "note".
- **content** (TextContent) - The text content of the note.
```

--------------------------------

### Create a Horizontal Bar Chart Script

Source: https://docs.pencil.dev/core-concepts/code-on-canvas

This script generates a horizontal bar chart. It accepts inputs for the number of columns, bar color, and an array of values. The output is an array of rectangle nodes.

```javascript
/**
 * @schema 2.11
 *
 * @input columns: number(min=1) = 3
 * @input color: color = #3B82F6
 */
const cols = Math.floor(pencil.input.columns);
const cellW = pencil.width / cols;
 
const nodes = [];
for (let c = 0; c < cols; c++) {
  nodes.push({
    type: "rectangle",
    x: c * cellW,
    y: 0,
    width: cellW - 4,
    height: pencil.height,
    fill: pencil.input.color,
  });
}
return nodes;
```

--------------------------------

### Entity with Graphics and Effects

Source: https://docs.pencil.dev/for-developers/the-pen-format

Base interface for entities that can have graphics (stroke, fill) and effects.

```APIDOC
## Entity with Graphics and Effects

### Description
An interface representing entities that can possess graphical properties like strokes and fills, as well as visual effects.

### Type
Interface

### Properties
- **stroke** (Stroke) - Optional - Defines the stroke properties.
- **fill** (Fills) - Optional - Defines the fill properties.
- **effect** (Effects) - Optional - Defines the visual effects applied.
```

--------------------------------

### Size Interface Definition

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines the width and height properties for an element. Values can be numbers, variables, or sizing behaviors.

```typescript
export interface Size {
  width?: NumberOrVariable | SizingBehavior;
  height?: NumberOrVariable | SizingBehavior;
}
```

--------------------------------

### Line Definition

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines a line entity with position, size, and graphics.

```APIDOC
## Line Definition

### Description
Represents a line segment defined by its bounding rectangle, position, and size.

### Type
Interface

### Extends
- Entity
- Size
- CanHaveGraphics

### Properties
- **type**: "line" - Required - The type of the shape.
```

--------------------------------

### Layout Interface Definition

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines layout properties for arranging child elements. Supports flex layout ('none', 'vertical', 'horizontal'), gap between children, padding, and alignment controls.

```typescript
export interface Layout {
  /** Enable flex layout. None means all children are absolutely positioned and will not be affected by layout properties. Frames default to horizontal, groups default to none. */
  layout?: "none" | "vertical" | "horizontal";
  /** The gap between children in the main axis direction. Defaults to 0. */
  gap?: NumberOrVariable;
  layoutIncludeStroke?: boolean;
  /** The Inside padding along the edge of the container */
  padding?:
    | /** The inside padding to all sides */ NumberOrVariable
    | /** The inside horizontal and vertical padding */ [
        NumberOrVariable,
        NumberOrVariable,
      ]
    | /** Top, Right, Bottom, Left padding */ [
        NumberOrVariable,
        NumberOrVariable,
        NumberOrVariable,
        NumberOrVariable,
      ];
  /** Control the justify alignment of the children along the main axis. Defaults to 'start'. */
  justifyContent?:
    | "start"
    | "center"
    | "end"
    | "space_between"
    | "space_around";
  /** Control the alignment of children along the cross axis. Defaults to 'start'. */
  alignItems?: "start" | "center" | "end";
}
```

--------------------------------

### Path Definition

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines a path entity using SVG path data, with graphics and fill rules.

```APIDOC
## Path Definition

### Description
Represents a path defined by SVG path data, allowing for complex shapes with custom fills and strokes.

### Type
Interface

### Extends
- Entity
- Size
- CanHaveGraphics

### Properties
- **type**: "path" - Required - The type of the shape.
- **fillRule** (enum: "nonzero" | "evenodd") - Optional - Determines how the path's interior is calculated for filling. Default: 'nonzero'.
- **geometry** (string) - Required - The SVG path data string.
```

--------------------------------

### Blend Mode Enum

Source: https://docs.pencil.dev/for-developers/the-pen-format

Enumerates the available blend modes for fills and effects.

```APIDOC
## Blend Mode Enum

### Description
Enumerates the available blend modes for fills and effects.

### Enum Values
- normal
- darken
- multiply
- linearBurn
- colorBurn
- light
- screen
- linearDodge
- colorDodge
- overlay
- softLight
- hardLight
- difference
- exclusion
- hue
- saturation
- color
- luminosity

### Type Definition
```typescript
export type BlendMode =
  | "normal"
  | "darken"
  | "multiply"
  | "linearBurn"
  | "colorBurn"
  | "light"
  | "screen"
  | "linearDodge"
  | "colorDodge"
  | "overlay"
  | "softLight"
  | "hardLight"
  | "difference"
  | "exclusion"
  | "hue"
  | "saturation"
  | "color"
  | "luminosity";
```
```

--------------------------------

### Text Definition

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines a text entity with content, styling, and graphical properties.

```APIDOC
## Text Definition

### Description
Represents a text element with its content, styling, and graphical properties.

### Type
Interface

### Extends
- Entity
- Size
- CanHaveGraphics
- TextStyle

### Properties
- **type**: "text" - Required - The type of the element.
- **content** (StringOrVariable | array of TextStyle) - Optional - The text content or an array of text styles for rich text.
```

--------------------------------

### Variable and Typed Values

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines types for variables, numbers, colors, booleans, and strings that can be used directly or as variables.

```APIDOC
## Variable and Typed Values

### Description
Types for variables, numbers, colors, booleans, and strings that can be used directly or as variables.

### Type Definitions

**Variable**: To bind a variable to a property, set the property to the dollar-prefixed name of the variable!
```typescript
export type Variable = string;
```

**NumberOrVariable**: Represents a number or a variable.
```typescript
export type NumberOrVariable = number | Variable;
```

**Color**: Colors can be 8-digit RGBA hex strings (e.g. #AABBCCDD), 6-digit RGB hex strings (e.g. #AABBCC) or 3-digit RGB hex strings (e.g. #ABC which means #AABBCC).
```typescript
export type Color = string;
```

**ColorOrVariable**: Represents a color or a variable.
```typescript
export type ColorOrVariable = Color | Variable;
```

**BooleanOrVariable**: Represents a boolean or a variable.
```typescript
export type BooleanOrVariable = boolean | Variable;
```

**StringOrVariable**: Represents a string or a variable.
```typescript
export type StringOrVariable = string | Variable;
```
```

--------------------------------

### Fill Type Definitions

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines the structure for various fill types including solid color, gradients, images, and mesh gradients. Each type can have properties like enabled state, blend mode, opacity, and specific parameters.

```typescript
export type Fill =
  | ColorOrVariable
  | {
      type: "color";
      enabled?: BooleanOrVariable;
      blendMode?: BlendMode;
      color: ColorOrVariable;
    }
  | {
      type: "gradient";
      enabled?: BooleanOrVariable;
      blendMode?: BlendMode;
      gradientType?: "linear" | "radial" | "angular";
      opacity?: NumberOrVariable;
      /** Normalized to bounding box (default: 0.5,0.5). */
      center?: Position;
      /** Normalized to bounding box (default: 1,1). Linear: height sets gradient length, width is ignored. Radial/Angular: sets ellipse diameters. */
      size?: { width?: NumberOrVariable; height?: NumberOrVariable };
      /** Rotation in degrees, counterclockwise (0° up, 90° left, 180° down). */
      rotation?: NumberOrVariable;
      colors?: { color: ColorOrVariable; position: NumberOrVariable }[];
    }
  /** Image fill. Url needs to be a relative from the pen file, for example `../../file.png` or `./image.jpg` */
  | {
      type: "image";
      enabled?: BooleanOrVariable;
      blendMode?: BlendMode;
      opacity?: NumberOrVariable;
      url: string;
      mode?: "stretch" | "fill" | "fit";
    }
  /** Grid of colors with bezier-interpolated edges. Row-major order. Adjust the points and handles to create complex gradients. Keep the points on the edges at their default position. */
  | {
      type: "mesh_gradient";
      enabled?: BooleanOrVariable;
      blendMode?: BlendMode;
      opacity?: NumberOrVariable;
      columns?: number;
      rows?: number;
      /** Color per vertex. */
      colors?: ColorOrVariable[];
      /** columns * rows points in [0,1] normalized coordinates. */
      points?: (
        | /** Position with auto-generated handles. */ [number, number]
        | /** Position with optional bezier handles (relative offsets). Omitted handles are auto-generated. */ {
            position: [number, number];
```

--------------------------------

### Document Structure

Source: https://docs.pencil.dev/for-developers/the-pen-format

Defines the overall structure of a Pencil document, including themes, imports, variables, and children.

```APIDOC
## Document Structure

### Properties
- **version** (string) - The version of the document format, e.g., "2.10".
- **themes** ({ [key: string]: string[] }) - Defines themes for styling.
- **imports** ({ [key: string]: string }) - Specifies imported files and their aliases.
- **variables** ({ [key: string]: ... }) - Defines variables with types (boolean, color, number, string) and values, potentially theme-specific.
- **children** (Array<Frame | Group | Rectangle | Ellipse | Line | Polygon | Path | Text | Note | Context | Prompt | IconFont | Ref>) - An array of top-level elements within the document.
```