Pencil Design

# Pencil Design Skill

Design production-quality UIs in Pencil and generate clean, maintainable code from them. This skill enforces best practices for design system reuse, variable usage, layout correctness, visual verification, and design-to-code workflows.

## When to Use This Skill

- Designing screens, pages, or components in a `.pen` file
- Generating code (React, Next.js, Vue, Svelte, HTML/CSS) from Pencil designs
- Building or extending a design system in Pencil
- Syncing design tokens between Pencil and code (Tailwind v4 `@theme`, shadcn/ui tokens)
- Importing existing code into Pencil designs
- Working with any Pencil MCP tools (`pencil_batch_design`, `pencil_batch_get`, etc.)

## Critical Rules

These rules address the most common agent mistakes. Violating them produces designs that are inconsistent, hard to maintain, and generate poor code.

### Rule 1: Always Reuse Design System Components

**NEVER recreate a component from scratch when one already exists in the design file.**

Before inserting any element, you MUST:
1. Call `pencil_batch_get` with `patterns: [{ reusable: true }]` to list all available reusable components
2. Search the results for a component that matches what you need (button, card, input, nav, etc.)
3. If a match exists, insert it as a `ref` instance using `I(parent, { type: "ref", ref: "<componentId>" })`
4. Customize the instance by updating its descendants with `U(instanceId + "/childId", { ... })`
5. Only create a new component from scratch if no suitable reusable component exists

See [references/design-system-components.md](references/design-system-components.md) for detailed workflow.

### Rule 2: Always Use Variables Instead of Hardcoded Values

**NEVER hardcode colors, border radius, spacing, or typography values when variables exist.**

Before applying any style value, you MUST:
1. Call `pencil_get_variables` to read all defined design tokens
2. Map your intended values to existing variables (e.g., use `primary` not `#3b82f6`, use `radius-md` not `6`)
3. Apply values using variable references, not raw values
4. When generating code, use Tailwind v4 semantic utility classes (e.g., `bg-primary`, `text-foreground`, `rounded-md`). NEVER use arbitrary value syntax (`bg-[#3b82f6]`, `text-[var(--primary)]`, `rounded-[6px]`)

See [references/variables-and-tokens.md](references/variables-and-tokens.md) for detailed workflow.

### Rule 3: Prevent Text and Content Overflow

**NEVER allow text or child elements to overflow their parent or the artboard.**

For every text element and container:
1. Set appropriate text wrapping and truncation
2. Constrain widths to parent bounds, especially on mobile screens (typically 375px wide)
3. Use `"fill_container"` for width on text elements inside auto-layout frames
4. After inserting content, call `pencil_snapshot_layout` with `problemsOnly: true` to detect clipping/overflow
5. Fix any reported issues before proceeding

See [references/layout-and-text-overflow.md](references/layout-and-text-overflow.md) for detailed workflow.

### Rule 4: Visually Verify Every Section

**NEVER skip visual verification after building a section or screen.**

After completing each logical section (header, hero, sidebar, form, card grid, etc.):
1. Call `pencil_get_screenshot` on the section or full screen node
2. Analyze the screenshot for: alignment issues, spacing inconsistencies, text overflow, visual glitches, missing content
3. Call `pencil_snapshot_layout` with `problemsOnly: true` to catch clipping and overlap
4. Fix any issues found before moving to the next section
5. Take a fin