Blog / Framer & site building /
Documenting reusable Framer components for client teams
A client editor opens the Framer project, sees a component called “Card 2” and changes one thing. Suddenly twelve pages look different.
Reusable components save time, but they confuse a client team when nobody knows what’s safe to edit or what depends on what. A good handover explains each component’s purpose, safe inputs and expected output, and which changes need a designer or developer.
Document the component’s job
For each reusable component, record where it appears, what problem it solves and which pages use it. List the editable fields, required and optional values and design constraints. A name like “Card 2” means nothing to someone who didn’t build it, so use words that describe the content or behaviour.
Explain what should stay consistent: spacing, image ratio, button destination, heading level or responsive behaviour. If a component has variants, say when to use each and what changes between them. I don’t just list every property. I tell editors how to choose.
Show safe editing and common mistakes
Give one good example and, where it helps, one common mistake. Explain how to replace the image, update the link and preview the result. If a field expects a URL or a short label, say so. Make clear whether editors can add or remove instances and who approves structural changes.
Check how the component behaves with long text, missing images and mobile layouts. The Framer canvas may show one polished example while real CMS content overflows. Document character limits only when they’re meaningful and tested, not as arbitrary rules.
Keep project decisions discoverable
Store notes where the client team can find them and link to the relevant component or collection. Name a project owner responsible for updates. When the design or content model changes, revise the notes and delete screenshots that no longer match. Give editors a way to ask questions or report a broken component.
Test the handover
Ask a client editor to update a safe instance using the notes. Watch whether they can change content without breaking layout or links. Their questions show you the missing context. Check the published page afterwards and explain any approval step before changes go live.
Explain the safe edit
A reusable component can look simple and still hide decisions an editor can’t see. A card may use a shared link, a fixed image ratio and a text limit that keeps mobile readable. Your notes should make those boundaries visible in ordinary language.
Start with the edits the client will really make: replacing the card’s title, choosing an image, updating the destination. Then explain which parts are shared and which belong to that instance, because an editor expecting a local change can accidentally affect every use of the component.
I use a screenshot from the actual project with a short note beside the relevant control. A generic components guide asks the client to translate platform knowledge into project decisions. The handover should do that translation for them.
Document behaviour, not only appearance
List the component’s states and what triggers them. For a menu, describe open and closed behaviour, the mobile presentation and keyboard interaction. For a form control, include its label, error and loading states where they exist.
Explain what happens when content is missing. If an optional image is removed, does the text expand, does the space stay or should the block hide? Give editors a supported route so they don’t improvise with blank text or invisible elements.
For linked cards, show where the destination comes from. It may be set manually, supplied by a CMS field or inherited through a shared structure. Knowing the source helps the editor fix the right place when a link is wrong.
Include examples that reveal the limits
A short title and a perfect landscape image make most components look fine. Document a longer title, an image with a different focal point and a case with optional content missing. They show what the component can handle without turning the guide into a design textbook.
If a limit is a project convention rather than a technical restriction, say so. A concise title may protect readability even if the field accepts more text. Editors choose better when they understand the reason.
Don’t use technical names as the only labels. An internal name helps a designer find the component, but the client also needs to know where it appears and what it does. Give both.
Ask the client to use the guide
Give an editor a small task and let them follow the instructions without coaching. Notice where they hesitate or look in the wrong place. Those are gaps to fix before the handover is finished.
Keep the guide next to the project’s other working documents and say who updates it when a component changes. Notes for an old version can confuse more than no notes at all. Ask the team to flag any instruction that no longer matches the project, so the guide stays trustworthy.
Related reading
- How to test Framer forms before a client handover
- Documenting a framer plugin without confusing users
- A review process for Framer redirects after a rebuild
Reusable components work best when the next person can use them confidently. Which component in your Framer project would benefit most from a one-page handover note?