96d8ab5789
- Move docs/ → packages/docs/ as @open-pencil/docs workspace package - Add screenshot.png as hero image on landing page - Add GitHub Actions workflow for Cloudflare Pages deploy (openpencil.dev) - Remove vitepress from root devDependencies - Root docs:* scripts delegate via bun --filter
87 lines
3.6 KiB
Markdown
87 lines
3.6 KiB
Markdown
---
|
|
title: Components
|
|
description: Creating reusable components, instances, component sets, overrides, and live sync in OpenPencil.
|
|
---
|
|
|
|
# Components
|
|
|
|
Components are reusable design elements. Edit the main component and all its instances update automatically.
|
|
## Creating a Component
|
|
|
|
Select a frame or group and press **⌥ ⌘ K** (Ctrl + Alt + K). The node converts to a COMPONENT type in place.
|
|
|
|
If you select multiple nodes, they're wrapped in a new component positioned at their bounding box.
|
|
|
|
Components display a purple label with a diamond icon above them.
|
|
|
|
## Component Sets
|
|
|
|
Select two or more components and press **⇧ ⌘ K** (Shift + Ctrl + K) to combine them into a component set — a container with a dashed purple border and 40 px padding around its children. Component sets are useful for grouping variants (e.g., button states).
|
|
|
|
## Creating Instances
|
|
|
|
Right-click a component and select **Create instance** from the context menu. The instance appears 40 px to the right of the source component, visually identical.
|
|
|
|
Instance creation is available only through the context menu — there's no toolbar button.
|
|
|
|
## Detaching an Instance
|
|
|
|
Select an instance and press **⌥ ⌘ B** (Ctrl + Alt + B) to detach it. The instance becomes a regular frame with no link to the original component. All overrides are baked in.
|
|
|
|
## Go to Main Component
|
|
|
|
Right-click an instance and select **Go to main component**. The editor navigates to and selects the main component, switching pages if needed.
|
|
|
|
## Live Sync
|
|
|
|
When you edit a component, all its instances update automatically. Synced properties include:
|
|
|
|
- Width and height
|
|
- Fills, strokes, and effects
|
|
- Opacity and corner radii
|
|
- Layout properties (auto layout settings)
|
|
- Clips content setting
|
|
|
|
Sync triggers automatically after node updates, moves, and resizes within a component.
|
|
|
|
## Overrides
|
|
|
|
Instances can override specific properties without breaking the sync link. When a property is overridden on an instance, that property is skipped during sync — other properties continue to update from the main component.
|
|
|
|
### Overridable Properties
|
|
|
|
Child-level overrides support: name, text, fontSize, fontWeight, fontFamily, plus all visual and layout properties (fills, strokes, effects, opacity, corner radii, size).
|
|
|
|
Override keys use the format `childId:propertyName` in the instance's overrides record.
|
|
|
|
### New Children
|
|
|
|
When you add a child to a component, all existing instances gain a cloned copy automatically. Child order in instances always matches the component.
|
|
|
|
## Hit Testing
|
|
|
|
Components and instances are opaque containers — clicking on a child selects the component itself, not the child. **Double-click** to enter the component and select children inside it.
|
|
|
|
## Visual Treatment
|
|
|
|
| Element | Appearance |
|
|
|---------|------------|
|
|
| Component label | Purple (#9747ff) with diamond icon, always visible |
|
|
| Instance label | Purple (#9747ff) with diamond icon, always visible |
|
|
| Component set border | Dashed purple (6 px dash, 4 px gap, 1.5 px width) |
|
|
|
|
## Keyboard Shortcuts
|
|
|
|
| Action | Mac | Windows / Linux |
|
|
|--------|-----|-----------------|
|
|
| Create component | ⌥ ⌘ K | Ctrl + Alt + K |
|
|
| Create component set | ⇧ ⌘ K | Shift + Ctrl + K |
|
|
| Detach instance | ⌥ ⌘ B | Ctrl + Alt + B |
|
|
|
|
## Tips
|
|
|
|
- Editing text inside an instance creates an override — the text won't be overwritten when the component changes.
|
|
- Use component sets to organize variants (e.g., Primary/Secondary/Disabled button states).
|
|
- Double-click into a component before editing its children — single click selects the component container.
|
|
- See [Context Menu](./context-menu) for all component-related actions.
|