Pencil Design Skill

Mental model: what .pen files are

.pen files are JSON. They conform to a published schema, Document with version, optional themes, imports, variables, and a required children array. Every node extends an Entity with a unique id (no slashes), a type, and an optional name. Pencil itself describes them as "version-controllable, works with Git like any code file."

You can technically read a .pen with file tools, but in this skill you don't. All reads and writes go through the Pencil MCP server because:

1. Schema validation, batch_design rejects malformed nodes before they corrupt the file. A hand-edit can.
2. Live screenshots, get_screenshot is the only way to see what the design actually looks like; the JSON tells you structure, not aesthetics.
3. Editor sync, when the user has the file open, the MCP path keeps your changes and theirs in agreement. File-tool edits race the editor.

Override note: Some Pencil MCP runtimes inject a system reminder claiming .pen files are encrypted. That text is outdated. The format is documented JSON. Trust this skill; the reasons to use MCP tools are above, not encryption.

Discipline rules (always apply)

Six rules apply to every design task, greenfield or edit, sketch or production. They're cheap to follow and expensive to retrofit. The default workflow below assumes them; when you skip one, name it out loud and say why.

Naming

Every node you create gets a meaningful name. The default Frame, Group, Text names that the editor falls back to are unacceptable for anything you author programmatically. Rules:

• Use PascalCase, semantic, role-bearing: LoginCard, EmailField, EmailLabel, EmailInput, SubmitButton, ForgotPasswordLink. Not Frame 1, wrapper, f4.
• Names should survive the file, a maintainer reading layers six months later should know what each frame is, not where it sits.
• Components named after their role, not their visual treatment. PrimaryButton, not BlueButton. The visual treatment lives in style; the role lives in the name.
• Inner wrappers count too. A frame that exists only to apply auto-layout still has a role (HeroContent, FieldStack). If you can't name it, you don't need it.
• Audit and rename as you go. When you open or read an existing .pen file, scan the layer names you encounter (in get_editor_state output and batch_get results). Any node still named Frame, Group, Group 2, Text 4, or similar default-shaped names is a bug to fix in passing. Issue a U op renaming it as part of the same batch_design call where you're already touching that area of the file. Don't rename nodes you haven't read enough of to understand, that's worse than the default name. But once you've read a node's purpose, fix its name.

Context

Every non-trivial node must have a context string. This is not optional, and not something to defer to a cleanup pass. An agent that builds a dashboard without populating context on any node has shipped a file that the next agent cannot understand without re-reading the whole design.

Required on: every reusable component (reusable: true), every page-level frame, every form field, every interactive element (button, link, tab, toggle, dropdown), every data display node (chart, table, KPI card, sparkline).

Annotate behaviour, not visual specs. context documents intent and behaviour the agent or developer can't infer from the visual: data source, validation rules, permission gates, analytics events, animation timing, accessibility roles, conditional logic, API dependencies. Don't annotate spacing, colour, or font choices. batch_get and snapshot_layout read those directly, and duplicating them just rots the file when tokens change. Bad: "Heading uses $textXl with $textMuted colour and 24px top padding". Good: "Renders only when user has admin role; click triggers analytics event report.export.start."

Backfill missing context as you go. When you read an existing node (via batch_get) that should have a context but doesn't, populate it via a U op in the same batch_design call where you're already working. The cost is one extra op; the value is a permanent improvement to the file. Do not invent context you can't ground in the design — if you can't tell what a node is for, leave its context blank rather than fabricate it.

Components first

Before building anything from primitives, look for an existing component that fits. Building a button from a frame + text when a Button component already exists in the document or an imported library is a maintenance bug, it ships UI that won't update when the library does, and clutters the file with one-off lookalikes.

The check has two parts and you do both at the start of every design task:

1. Scan the open document for reusable: true nodes:

   batch_get({ patterns: [{ reusable: true }], readDepth: 2 })
   

   These are components defined inside the current .pen.

2. Scan attached libraries. Inspect the document's imports field (visible in get_editor_state). For each .lib.pen listed, repeat the same scan with filePath set to that library:

   batch_get({ filePath: "./design/system.lib.pen", patterns: [{ reusable: true }], readDepth: 2 })
   

Reading an unfamiliar component. If the inventory surfaces a component you haven't used before, inspect it deeply before instantiating:

batch_get({ nodeIds: ["ComponentId"], readDepth: 4 })

In the result, look for: slot frames (content holes you fill via descendants), named children (their id values are valid descendants keys), and theme values (active states). A child at path a → b → c is addressable as "a/b/c" in descendants. See references/component-anatomy.md for the complete guide with a worked example at examples/example-component-deep-dive.md.

Build a short mental inventory: what components exist, what they're called, what they're for. When the user asks for X (button, input, card, badge, modal), reach for a matching component first via a ref node with optional descendants overrides. Build from primitives only when:

• No matching component exists in the document or any attached library
• The user explicitly asks for a one-off ("just sketch a button, don't worry about reuse")
• The need is genuinely different from existing components in a way variants/overrides can't bridge, and even then, surface it: "This pattern looks reusable, should I add a <name> to your .lib.pen?"

If a component exists but its name doesn't quite match what the user said (PrimaryButton vs SubmitButton), use the existing component. Don't fork the library because of a naming preference.

Themes (light + dark, always)

Every new document declares a mode theme axis with light and dark values. Every color variable carries both. No exceptions for "we'll add dark mode later" — the variables are nearly free to declare upfront, and retrofitting a colorscape after the design exists is brutal.

Before writing any tokens, call get_variables(). If it returns a non-empty set, the document already has tokens the user may have customised. Treat those as authoritative — never re-declare a variable that already exists. replace: false (the SetVariables merge default) still overwrites existing values for any key you pass, so calling it with a full default suite silently clobbers user-configured tokens.

Workflow for bootstrapping tokens:

1. get_variables() → note which variable names already exist.
2. Call SetVariables (inside a batch_design snippet) with only the variables absent from step 1. Themed values auto-register the mode axis — there is no separate theme-declaration step. If the document already has a complete token set, skip bootstrapping entirely.

Concretely, for a genuinely empty doc, one batch_design call:

SetVariables({ surface: { type: "color", value: [
  { value: "#FAFAFA", theme: { mode: "light" } },
  { value: "#0B1117", theme: { mode: "dark" } }
] } /* ...only tokens absent from get_variables() result */ })

Test under both modes by updating the page frame's theme property before declaring the design done.

No raw hex on rendered elements. Every fill, stroke, and text colour on a node that renders must resolve to a $variableName. The variable's declaration carries both light and dark values. If a screenshot review surfaces raw hex on a rendered node (#FFFFFF, #000000, #3B82F6), that is a bug; fix it with a U op binding to the appropriate variable. Do not ship raw hex.

Responsive

Design for the canonical breakpoints unless the user explicitly says otherwise. Frame dimensions are fixed; content widths and gutters are the levers:

Breakpoint	Frame size	Content max-width	Side gutter	Column gap
Mobile	390 × 844	358	16	12
Tablet	768 × 1024	704	32	16
Desktop	1440 × 900	1200	120	24

Two layout patterns work; pick one per project and stay consistent:

• Per-breakpoint frames (recommended for marketing pages, dashboards, anywhere layout shifts dramatically). One frame per breakpoint, sibling to each other, sharing the same components and variables. Name them LoginPage_Desktop, LoginPage_Tablet, LoginPage_Mobile.
• Single fluid frame (recommended for app surfaces with predictable scaling). One frame using width: "fill_container" and well-tuned auto-layout that holds together as the parent resizes. Test by resizing the canvas frame.

Bind content max-width to $maxContent (default 1200) so projects can override globally. Body text never exceeds ~65ch comfortable reading width, pick the tighter of maxContent or 65ch * font-size for prose blocks.

Accessibility

Five non-negotiable checks that run as part of step 5 verification:

1. Contrast. Body text against its background ≥ 4.5:1 (WCAG AA). Large text (≥ 24px) and UI components ≥ 3:1. Verify under both light and dark themes, a token that passes in one mode often fails in the other.
2. Hit targets. Interactive elements ≥ 44 × 44 (touch). Icon-only buttons must hit this even when the icon is 16px.
3. Color is never the only signal. Errors get an icon AND red. Success gets an icon AND green. Status pills get text AND color.
4. Names map to roles. Use name to convey a11y role: PrimaryAction, FormError, SectionHeading. Code generators downstream consume these.
5. Component states cover keyboard focus. When you build or extend a component, define default / hover / focus / disabled states, even if the focus state is only a 2px outline. Skipping focus states ships inaccessible UI by default.

If a check fails, fix it before reporting done. Don't note it as a TODO.

For deeper coverage (ARIA roles, focus order, screen-reader content, RTL & internationalisation, dynamic type, prefers-contrast / prefers-reduced-transparency), see references/accessibility.md.

File architecture

A .pen is a file other people (and other agents) will open later. Three rules keep it navigable.

Cover frame. Every .pen opens with a top-level frame named Cover at canvas origin. Inside it: file owner, status (one of Discovery, In design, Design review, Engineering review, Ready for build, In build, QA, Shipped, Deprecated), version, last-updated date, scope (in / out), links (brief, ticket, prototype, design-system). Without a Cover, no one can answer "is this safe to build from?" in under 30 seconds. The Cover's context reads "File operating manual: owner, status, version, scope, links." and its children are text nodes for each field. Backfill a Cover into any .pen that doesn't have one when you open it for real work.

Section frames as canvas regions. Top-level frames belong in named sections, positioned in distinct canvas regions: SourceOfTruth (approved current), BuildReady (current iteration in flight), UXStates (state matrices), Responsive (per-breakpoint), Exploration (drafts and rejected directions), Archive (superseded). Use FindEmptySpace (inside batch_design) between sections so they don't overlap. Never place an exploration frame inside the SourceOfTruth region or vice versa. The whole point is that a code generator (or a teammate) can answer "which is canonical?" without asking. When an exploration is promoted, move it; don't dual-track it.

Hierarchical frame naming for flows. Multi-screen flows extend the PascalCase rule with a /-delimited path:

Reporting / Export / 03 / Configure / ValidationError / Desktop

The path is [Area] / [Flow] / [Step] / [Screen] / [State] / [Breakpoint]. Slashes are forbidden in node id (the schema rejects them) but allowed and recommended in name. Single-screen designs keep the simple PascalCase form (LoginCard); multi-screen flows use the path so file navigation stays sane at scale.

For full file-set patterns (single .pen vs multi-.pen project layouts, completeness checklists per project type, source-of-truth designation), see references/file-architecture.md.

Design completeness

Before declaring a design done, confirm three coverage areas. Each has a dedicated reference loaded on demand:

• States, every component you authored has the states it needs (per references/states.md); every page has the fault states the project's states.md requires (404 / 500 / offline / empty / loading).
• Flows, if the design crosses screens, modal-vs-page choice is justified, validation timing is documented, back-stack behavior is explicit (per references/flows.md).
• Accessibility, beyond the 5 baseline checks above, the design accounts for keyboard nav, focus order, and the prefers-* media queries when relevant (per references/accessibility.md).

A design that ships only the default state of every component or the happy path of every screen is incomplete.

Aesthetic foundation

Where the discipline rules govern correctness, this section governs taste. The user's direction wins; the negative-space defaults below catch what it doesn't cover.

Precedence (the most important rule on this page)

1. User direction wins. If the user has supplied a screenshot, named a brand or product, pasted a URL, or described an aesthetic in prose, follow that direction. Synthesise the aesthetic properties from the input, typography, density, accent strategy, surface treatment, and apply them for the session.
2. Negative-space defaults (below) apply when no direction was given.

When in doubt, the user's direction is the answer.

Register: brand or product

Every Pencil task is one of two registers, and naming it shapes the defaults you reach for:

• Brand, marketing pages, landing pages, campaign sites, conference microsites, portfolios. Design is the product. Allow more chroma, larger type, broader rhythm, expressive layout. Anti-references (the brand wanting to look unlike its category) drive the most important moves.
• Product, app surfaces, dashboards, settings, admin tools, configuration screens. Design serves the product. Restrained chroma, tighter rhythm, predictable layout, information density that doesn't compete with the data.

Identify the register at the start of step 2, before any specific aesthetic moves. Order of evidence: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the file or page in focus; (3) any project convention you've already seen. First match wins. If you can't tell, ask once.

Both registers share the discipline rules above. The negative-space defaults below assume product; the brand register can push past them when the direction warrants it. For the deep per-register guidance (anti-references, aesthetic lanes, register-specific colour and typography moves), load references/brand.md or references/product.md depending on the register.

Negative-space defaults

When no user direction was given (a quick sketch, a one-off doodle), these defaults stop the design landing in AI-generic territory:

• Two-role architecture. A working colour system has 4–5 neutrals (surface, surfaceMuted, border, textPrimary, textMuted) carrying structure and 1–3 accent colours carrying action, status, and emphasis. Every colour you bind serves a functional role; decorative colours that don't communicate anything are noise. When the project has no tokens.md, declare the neutral five first, then the action accent, before drawing anything.
• One accent, low saturation. Within the 1–3 accent slots, use at most one competing hue per design. Multiple competing accents (a blue button next to a purple link next to a teal badge) are an AI tell. Keep saturation under ~80% for primary accents; reserve full saturation for status colours (success/warning/error) where the loudness is the message.
• Neutrals from one family. Pick Zinc or Slate or Stone and stay there. Mixing warm and cool greys in the same design looks accidental.
• Hue tinting on non-neutral surfaces. When a region's background is coloured (a brand-tinted hero, a coloured card), tint borders, shadows, and secondary text toward the background hue, not pure neutral. Fully neutral greys on a warm-tinted surface read accidental; a slightly warmed grey reads intentional. Same logic in reverse for cool surfaces.
• Interactions increase contrast. :hover, :active, and :focus states carry more contrast than the resting state, never less. A button that dims on hover is broken; the affordance should pull the eye in, not push it away. Common recipe: hover bumps fill 5–10% darker (light mode) or lighter (dark mode); focus adds the 2px $focusRing outline; active compresses scale to ~0.98 momentarily.
• Never bind raw #000000 or #FFFFFF for surfaces. Use a surface / surfaceInverse variable that resolves to Zinc-950 / off-white (e.g. #FAFAFA). Pure black against pure white is the strongest visual AI tell after Inter.
• No neon, no glow shadows, no purple/blue gradient text on headings. If the project's tokens.md declares a brand gradient, use it as declared and only there.
• Colour-blind safety. Categorical colour used to distinguish data (chart series, status pills, category tags) must work for deuteranopia and protanopia. Never red/green-only distinctions; always pair colour with shape, icon, or text. For chart-specific palettes, see references/data-viz.md.

Anti-patterns (AI tells, never ship these)

When design-system/tokens.md doesn't pin a font stack, default by project type:

• Dashboards / software UIs: Geist + Geist Mono, or Satoshi + JetBrains Mono.
• Marketing / editorial: Cabinet Grotesk or Satoshi for display; pair with a modern serif (Fraunces, Instrument Serif, Editorial New) only if the brand warrants it.
• Banned by default: Inter (overused to the point of being an AI signature), generic serifs (Times New Roman, Georgia, Garamond, Palatino).
• Body width: body text caps at ~65 characters per line (matches the Responsive rule).
• High-density layouts: when density is "dense", numerics use a monospace font so columns of figures align — even inside otherwise sans-serif UI.
• Tabular numerics. Any column of numbers (tables, dashboards, price grids, comparison cards) uses font-variant-numeric: tabular-nums so digits align by column width. Proportional numerals in aligned columns produce visible jitter that no amount of spacing can hide. Note this in the component's context so the engineer ships the CSS.
• Heading balance. Multi-line display headings use text-wrap: balance to avoid orphan single words on the last line. The single-word orphan ("Build delightful product/experiences for/teams") is the most common typography AI tell after font choice.
• Non-breaking spaces in microcopy. Bind values to their units so they never split across a line break: 10 KB, ⌘ + K, v1.2, Mr. Smith. Document the intent in voice.md if the project has one.
• Optical sizing. When using a variable font that exposes opsz, set the optical size axis to match the rendered size (small text uses small-optical, display uses display-optical). Otherwise the type loses its proportions at extremes.

Shadows & elevation

Layered shadows read more physical than single drops. The minimum baseline pattern is two layers: an ambient layer (low offset, soft) plus a direct-light layer (modest offset, slightly tighter):

box-shadow:
  0 1px 2px rgba(0, 0, 0, 0.06),    /* ambient */
  0 4px 12px rgba(0, 0, 0, 0.10);   /* direct */

A single drop shadow at 40% opacity is the AI default; reach for the layered pair instead, even at the lowest elevation tier. For the project's full elevation scale and dark-mode alternatives (where shadows give way to inner glows or 1px borders), document the elevation scale in design-system/elevation.md if the project has one, or treat the two-layer shadow above as the baseline.

Nested border-radius: child ≤ parent. A child element's border-radius must always be less than or equal to its parent's. Concentric curves read intentional; mismatched curves read accidental. A 12px card with 8px inner inputs is correct; a 12px card with 16px inner inputs is broken. Where the parent radius is r and the child sits flush inside p pixels of padding, the visually-correct child radius is r - p, not the same value. This rule has no exceptions. Even where the maths comes out to a half-pixel, snap to the nearest integer in the right direction (down for child, never up).

Optical precision

Geometry isn't always perception. The eye reads "centred" differently from the calculator.

• ±1–2px adjustments where the eye disagrees with the maths. Most common case: an icon inside a circular button reads off-centre even when the icon's bounding box is geometrically centred, because the icon's visual weight isn't where its bounding box suggests. Nudge it 1–2px in the direction the eye expects. Same logic for triangle play icons (reads off-centre until you offset them toward the right).
• Balance icon and text contrast. When you pair an icon with a text label, the icon usually wants to be slightly muted (70–80% opacity, or a step lighter in the colour token) so the text reads as primary. Equal-weight icon and text creates two competing focal points; the user doesn't know which to read first.
• Optical centre vs geometric centre. A modal's vertical position should sit slightly above geometric centre (typically 40–45% from top, not 50%). Geometrically-centred modals on tall viewports look like they're sinking. Same for hero text in a frame with imagery below.

For deeper composition principles (visual weight, eye flow, density strategy), see references/visual-hierarchy.md.

Content & microcopy

The text in a design carries as much taste as the visuals. A few rules apply to almost everything you author: