Agent skills for iOS, iPadOS, Swift, SwiftUI, and modern Apple framework development.
80
100%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
View guide
Advisory
Suggest reviewing before use
Beta-sensitive. PaperKit is new in iOS/iPadOS 26, macOS 26, and visionOS 26. API surface may change. Verify details against current Apple documentation before shipping.
PaperKit combines PencilKit drawing with structured markup elements such as shapes, text, images, and lines in a canvas managed by PaperMarkupViewController.
FeatureSet, and persistence version before constructing UI.PaperMarkup, embed PaperMarkupViewController, and keep the controller, tool picker, and insertion controller alive for the view lifetime.Load references/paperkit-patterns.md for full platform setup, tool picker wiring, persistence, thumbnails, custom feature sets, programmatic construction, and migration.
PaperKit requires no entitlements or special Info.plist entries.
import PaperKitPlatform availability: iOS 26.0+, iPadOS 26.0+, Mac Catalyst 26.0+, macOS 26.0+, visionOS 26.0+.
Three core components:
| Component | Role |
|---|---|
PaperMarkupViewController | Interactive canvas for creating and displaying markup and drawing |
PaperMarkup | Data model for serializing all markup elements and PencilKit drawing |
MarkupEditViewController / MarkupToolbarViewController | Insertion UI for adding markup elements |
The primary view controller for interactive markup. Provides a scrollable canvas for freeform PencilKit drawing and structured markup elements. Conforms to Observable and PKToolPickerObserver.
import PaperKit
import PencilKit
import UIKit
class MarkupViewController: UIViewController, PaperMarkupViewController.Delegate {
var paperVC: PaperMarkupViewController!
var toolPicker: PKToolPicker!
override func viewDidLoad() {
super.viewDidLoad()
let pageBounds = CGRect(origin: .zero, size: CGSize(width: 612, height: 792))
let markup = PaperMarkup(bounds: pageBounds)
let features = FeatureSet.latest
paperVC = PaperMarkupViewController(
markup: markup,
supportedFeatureSet: features
)
paperVC.delegate = self
addChild(paperVC)
paperVC.view.frame = view.bounds
paperVC.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
view.addSubview(paperVC.view)
paperVC.didMove(toParent: self)
toolPicker = PKToolPicker()
toolPicker.addObserver(paperVC)
paperVC.pencilKitResponderState.activeToolPicker = toolPicker
paperVC.pencilKitResponderState.toolPickerVisibility = .visible
}
func paperMarkupViewControllerDidChangeMarkup(
_ controller: PaperMarkupViewController
) {
guard let markup = controller.markup else { return }
Task { try await save(markup) }
}
}| Property | Type | Description |
|---|---|---|
markup | PaperMarkup? | The current data model |
selectedMarkup | PaperMarkup | Currently selected content |
isEditable | Bool | Whether the canvas accepts input |
isRulerActive | Bool | Whether the ruler overlay is shown |
drawingTool | any PKTool | Active PencilKit drawing tool |
contentView | UIView? / NSView? | Background view rendered beneath markup |
zoomRange | ClosedRange<CGFloat> | Min/max zoom scale |
supportedFeatureSet | FeatureSet | Enabled PaperKit features |
PaperMarkupViewController.TouchMode has two cases: .drawing and .selection.
paperVC.directTouchMode = .drawing // Finger draws
paperVC.directTouchMode = .selection // Finger selects elements
paperVC.directTouchAutomaticallyDraws = true // System decides based on Pencil stateSet any view beneath the markup layer for templates, document pages, or images being annotated. Keep the PaperMarkup(bounds:) coordinate space aligned to the background content, such as a PDF page or rendered image size, so saved annotations restore in the right place:
let pageBounds = CGRect(origin: .zero, size: pageImage.size)
let imageView = UIImageView(image: pageImage)
imageView.frame = pageBounds
let markup = PaperMarkup(bounds: pageBounds)
paperVC = PaperMarkupViewController(markup: markup, supportedFeatureSet: features)
paperVC.contentView = imageView| Method | Called when |
|---|---|
paperMarkupViewControllerDidChangeMarkup(_:) | Markup content changes |
paperMarkupViewControllerDidBeginDrawing(_:) | User starts drawing |
paperMarkupViewControllerDidChangeSelection(_:) | Selection changes |
paperMarkupViewControllerDidChangeContentVisibleFrame(_:) | Visible frame changes |
PaperMarkup is a Sendable struct that stores all markup elements and PencilKit drawing data.
// New empty model. Bounds define the saved document coordinate space.
let markup = PaperMarkup(bounds: CGRect(x: 0, y: 0, width: 612, height: 792))
// Load from saved data
let markup = try PaperMarkup(dataRepresentation: savedData)
// Save — dataRepresentation() is async throws
func save(_ markup: PaperMarkup) async throws {
let data = try await markup.dataRepresentation()
try data.write(to: fileURL)
}// Text box
markup.insertNewTextbox(
attributedText: AttributedString("Annotation"),
frame: CGRect(x: 50, y: 100, width: 200, height: 40),
rotation: 0
)
// Image
markup.insertNewImage(cgImage, frame: CGRect(x: 50, y: 200, width: 300, height: 200), rotation: 0)
// Shape
let shapeConfig = ShapeConfiguration(
type: .rectangle,
fillColor: UIColor.systemBlue.withAlphaComponent(0.2).cgColor,
strokeColor: UIColor.systemBlue.cgColor,
lineWidth: 2
)
markup.insertNewShape(configuration: shapeConfig, frame: CGRect(x: 50, y: 420, width: 200, height: 100), rotation: 0)
// Line with arrow end marker
let lineConfig = ShapeConfiguration(type: .line, fillColor: nil, strokeColor: UIColor.red.cgColor, lineWidth: 3)
markup.insertNewLine(
configuration: lineConfig,
from: CGPoint(x: 50, y: 550), to: CGPoint(x: 250, y: 550),
startMarker: false, endMarker: true
)Shape types: .rectangle, .roundedRectangle, .ellipse, .line, .arrowShape, .star, .chatBubble, .regularPolygon.
markup.append(contentsOf: otherMarkup) // Merge another PaperMarkup
markup.append(contentsOf: pkDrawing) // Merge a PKDrawing
markup.transformContent(CGAffineTransform(...)) // Apply affine transform
markup.removeContentUnsupported(by: featureSet) // Strip unsupported elements| Property | Description |
|---|---|
bounds | Coordinate space of the markup |
contentsRenderFrame | Tight bounding box of all content |
featureSet | Features used by this data model's content |
indexableContent | Extractable text for search indexing |
Use suggestedFrameForInserting(contentInFrame:) on the view controller to get a frame that avoids overlapping existing content.
Presents a popover menu for inserting shapes, text boxes, lines, and other elements.
func showInsertionMenu(from barButtonItem: UIBarButtonItem) {
let editVC = MarkupEditViewController(
supportedFeatureSet: paperVC.supportedFeatureSet,
additionalActions: []
)
editVC.delegate = paperVC // PaperMarkupViewController conforms to the delegate
editVC.modalPresentationStyle = .popover
editVC.popoverPresentationController?.barButtonItem = barButtonItem
present(editVC, animated: true)
}Provides a toolbar with drawing tools and insertion buttons. Use it for native macOS and for Mac Catalyst toolbar-style UI; Catalyst apps that want a UIKit popover can use MarkupEditViewController.
let toolbar = MarkupToolbarViewController(supportedFeatureSet: paperVC.supportedFeatureSet)
toolbar.delegate = paperVC
addChild(toolbar)
toolbar.view.frame = toolbarContainerView.bounds
toolbarContainerView.addSubview(toolbar.view)
toolbar.didMove(toParent: self)Both controllers must use the same FeatureSet as the PaperMarkupViewController.
FeatureSet controls which markup capabilities are available.
| Preset | Description |
|---|---|
.latest | All current features — recommended starting point |
.version1 | Features from version 1 |
.empty | No features enabled |
var features = FeatureSet.latest
features.remove(.stickers)
features.remove(.images)
// Or build up from empty
var features = FeatureSet.empty
features.insert(.drawing)
features.insert(.text)
features.insert(.shapeStrokes)| Feature | Description |
|---|---|
.drawing | Freeform PencilKit drawing |
.text | Text box insertion |
.images | Image insertion |
.stickers | Sticker insertion |
.links | Link annotations |
.loupes | Loupe/magnifier elements |
.shapeStrokes | Shape outlines |
.shapeFills | Shape fills |
.shapeOpacity | Shape opacity control |
Set colorMaximumLinearExposure above 1.0 on both the FeatureSet and PKToolPicker:
var features = FeatureSet.latest
features.colorMaximumLinearExposure = 4.0
toolPicker.colorMaximumLinearExposure = features.colorMaximumLinearExposureUse view.window?.windowScene?.screen.potentialEDRHeadroom to match the device screen's capability. Use 1.0 for SDR-only.
features.shapes = [.rectangle, .ellipse, .arrowShape, .line]
features.inks = [.pen, .pencil, .marker]
features.lineMarkerPositions = .all // .single, .double, .plain, or .allPaperKit accepts PKTool for drawing and can append PKDrawing content.
PaperKit is not a drop-in replacement for a low-level PKCanvasView when the app depends on custom brush behavior, raw PKDrawing / PKStroke analytics, or custom lasso-centric editing. Keep those workflows owned by PencilKit, and add PaperKit beside them for structured review markup such as callouts, arrows, text boxes, labels, image stamps, and system-standard insertion UI. Migrate or duplicate existing drawings into a PaperKit annotation layer with PaperMarkup.append(contentsOf: PKDrawing) only when the low-level editing path no longer needs to own that content.
import PencilKit
// Set drawing tool
paperVC.drawingTool = PKInkingTool(.pen, color: .black, width: 3)
// Merge existing PKDrawing into markup
markup.append(contentsOf: existingPKDrawing)let toolPicker = PKToolPicker()
toolPicker.addObserver(paperVC)
paperVC.pencilKitResponderState.activeToolPicker = toolPicker
paperVC.pencilKitResponderState.toolPickerVisibility = .visibleSetting toolPickerVisibility to .hidden keeps the picker functional (responds to Pencil gestures) but not visible, enabling the mini tool picker experience.
FeatureSet.ContentVersion maps to PKContentVersion:
let pkVersion = features.contentVersion.pencilKitContentVersionWrap PaperMarkupViewController in UIViewControllerRepresentable:
struct MarkupView: UIViewControllerRepresentable {
@Binding var markup: PaperMarkup
let features: FeatureSet
func makeUIViewController(context: Context) -> PaperMarkupViewController {
let vc = PaperMarkupViewController(markup: markup, supportedFeatureSet: features)
vc.delegate = context.coordinator
let toolPicker = PKToolPicker()
toolPicker.addObserver(vc)
vc.pencilKitResponderState.activeToolPicker = toolPicker
vc.pencilKitResponderState.toolPickerVisibility = .visible
context.coordinator.toolPicker = toolPicker
return vc
}
func updateUIViewController(_ vc: PaperMarkupViewController, context: Context) {
if vc.markup != markup { vc.markup = markup }
}
func makeCoordinator() -> Coordinator { Coordinator(parent: self) }
class Coordinator: NSObject, PaperMarkupViewController.Delegate {
let parent: MarkupView
var toolPicker: PKToolPicker?
init(parent: MarkupView) { self.parent = parent }
func paperMarkupViewControllerDidChangeMarkup(
_ controller: PaperMarkupViewController
) {
if let markup = controller.markup { parent.markup = markup }
}
}
}Initialize the bound PaperMarkup from the document or page size before creating the SwiftUI bridge:
struct DocumentMarkupScreen: View {
let pageSize: CGSize
@State private var markup: PaperMarkup
private let features = FeatureSet.latest
init(pageSize: CGSize) {
self.pageSize = pageSize
_markup = State(
initialValue: PaperMarkup(
bounds: CGRect(origin: .zero, size: pageSize)
)
)
}
var body: some View {
MarkupView(markup: $markup, features: features)
}
}| Mistake | Fix |
|---|---|
| View, insertion UI, and saved document use mismatched feature sets | Choose one supported FeatureSet and use it across the editing session. |
| Loaded content is assigned without a version check | Verify markup.featureSet.isSubset(of: supportedFeatureSet) or show the saved thumbnail/fallback. |
| Serialization blocks UI or overlaps unsafely | Await dataRepresentation() off the interaction path and debounce autosaves. |
| Tool picker is a local variable | Retain it for the controller/view lifetime. |
| Wrong insertion surface for the platform | Use MarkupToolbarViewController on macOS; use MarkupEditViewController on UIKit, with Catalyst supporting either presentation. |
import PaperKit present; deployment target is iOS 26+ / macOS 26+ / visionOS 26+PaperMarkup initialized with bounds matching content sizeFeatureSet used for PaperMarkupViewController and insertion controllerdataRepresentation() called in async contextPKToolPicker retained as a stored propertyPaperMarkupViewController for change callbacksMarkupToolbarViewController for macOS/Catalyst toolbar UI; MarkupEditViewController for UIKit/Catalyst popovers)MarkupError cases handled on deserializationcolorMaximumLinearExposure set on FeatureSet and PKToolPicker.colorMaximumLinearExposurepencilkit skill covers PencilKit drawing, tool pickers, and PKDrawing serialization.tessl-plugin
skills
accessorysetupkit
references
activitykit
references
adattributionkit
references
alarmkit
references
app-clips
app-intents
app-store-optimization
app-store-review
apple-on-device-ai
appmigrationkit
references
audioaccessorykit
references
authentication
references
avkit
references
background-processing
references
browserenginekit
references
callkit
references
carplay
references
cloudkit
references
contacts-framework
references
core-bluetooth
references
core-data
core-motion
references
core-nfc
references
coreml
references
cryptokit
references
cryptotokenkit
references
debugging-instruments
device-integrity
references
dockkit
references
energykit
references
eventkit
references
financekit
references
focus-engine
gamekit
references
healthkit
references
homekit
references
ios-accessibility
ios-ettrace-performance
ios-localization
ios-memgraph-analysis
ios-networking
ios-simulator
references
mapkit
metrickit
references
musickit
references
natural-language
references
paperkit
references
passkit
references
pdfkit
references
pencilkit
references
permissionkit
references
photokit
push-notifications
realitykit
references
relevancekit
references
scenekit
references
sensorkit
references
speech-recognition
references
spritekit
references
storekit
swift-api-design-guidelines
swift-architecture
references
swift-charts
references
swift-codable
references
swift-concurrency
swift-formatstyle
references
swift-language
swift-security
references
swift-testing
swiftdata
swiftlint
swiftui-animation
swiftui-gestures
references
swiftui-layout-components
swiftui-liquid-glass
references
swiftui-patterns
swiftui-performance
swiftui-uikit-interop
swiftui-webkit
tabletopkit
references
tipkit
references
vision-framework
weatherkit
references
widgetkit
references