handoff-spec
owl-listener/designer-skills
Write complete implementation handoffs with measurements, behaviors, assets, states, and edge cases for developers.
What is handoff-spec?
Creates detailed handoff specifications that give developers everything needed to implement a design accurately. Use when engineering picks up design work to ensure nothing is missed—measurements, interactions, content rules, assets, and edge cases all documented.
- Documents visual specifications: spacing, sizing, colors (via tokens), typography, shadows, and responsive behavior
- Defines interaction specifications: component states, transitions, animations, gestures, and keyboard interactions
- Specifies content rules: character limits, truncation, dynamic content, localization, and empty/loading/error states
- Delivers assets: icons, images, fonts, and custom graphics with naming conventions and responsive variants
- Identifies edge cases: minimum/maximum content, breakpoint behavior, browser considerations, and accessibility requirements
- Provides implementation notes: component reuse, data structures, API dependencies, and performance considerations
How to install handoff-spec
npx skills add https://github.com/owl-listener/designer-skills --skill handoff-specHow to use handoff-spec
- 1.Gather your finalized design files, design tokens, and any component documentation
- 2.Start with visual specifications: list exact spacing, sizing, color token names, typography styles, and responsive breakpoints
- 3.Document all interaction states and behaviors: define each state (default, hover, focus, active, disabled) and any transitions or animations
- 4.Specify content rules: character limits, truncation behavior, dynamic content ranges, and localization needs
- 5.List all assets needed: icons (with naming), images (with resolutions and formats), fonts, and custom graphics
- 6.Identify edge cases: minimum/maximum content scenarios, browser-specific behavior, and accessibility requirements (ARIA, keyboard navigation)
- 7.Include implementation notes: suggest component reuse, document data structure assumptions, note API dependencies, and flag performance considerations
- 8.Review the handoff with the developer to walk through requirements and answer questions
Use cases
- Hand off a completed design to engineering with all specifications documented before development begins
- Document responsive behavior across multiple breakpoints to prevent implementation surprises
- Specify all component states (default, hover, focus, active, disabled) to ensure complete coverage
- Define animation and transition details (duration, easing, properties) for consistent interactions
- Capture edge cases like very long text, empty states, and loading scenarios before coding starts
- Product designers handing off work to engineering teams
- Design leads ensuring handoffs are complete and unambiguous
- Frontend developers receiving specifications and needing clarity on requirements
- Design systems teams documenting component specifications
handoff-spec FAQ
Use handoff-spec for one-off design implementations being handed to engineering. Use component-spec for reusable library components in design systems.
Always use design token names, not raw hex codes or pixel values. This keeps implementations consistent with your design system.
Document what you know and flag unknowns explicitly. Work with the developer to identify and spec remaining edge cases before implementation starts.
Include all states the component can be in: default, hover, focus, active, disabled, and any loading or error states. Specify visual changes and any animations for each.
Yes—flag any performance concerns like large image counts, complex animations, or heavy data loads so the developer can plan accordingly.
Full instructions (SKILL.md)
Source of truth, from owl-listener/designer-skills.
name: handoff-spec
description: Write the implementation handoff — measurements, behaviours, assets, states, and edge cases. Use when engineering picks up the work. For verifying the result afterwards use design-qa-checklist; for reusable library components use component-spec (design-systems).
Handoff Spec
You are an expert in creating clear, complete developer handoff specifications.
What You Do
You create handoff documents that give developers everything needed to implement a design accurately.
Handoff Contents
Visual Specifications
- Spacing and sizing (exact pixel values or token references)
- Color values (token names, not hex codes)
- Typography (style name, size, weight, line-height)
- Border radius, shadows, opacity values
- Responsive breakpoint behavior
Interaction Specifications
- State definitions (default, hover, focus, active, disabled)
- Transitions and animations (duration, easing, properties)
- Gesture behaviors (swipe, drag, pinch)
- Keyboard interactions (tab order, shortcuts)
Content Specifications
- Character limits and truncation behavior
- Dynamic content rules (what changes, min/max)
- Localization considerations (text expansion, RTL)
- Empty, loading, and error state content
Asset Delivery
- Icons (SVG, named per convention)
- Images (resolution, format, responsive variants)
- Fonts (files or service links)
- Any custom illustrations or graphics
Edge Cases
- Minimum and maximum content scenarios
- Responsive behavior at each breakpoint
- Browser/device-specific considerations
- Accessibility requirements (ARIA, keyboard, screen reader)
Implementation Notes
- Component reuse suggestions
- Data structure assumptions
- API dependencies
- Performance considerations
Best Practices
- Use design tokens, not raw values
- Annotate behavior, not just appearance
- Include all states, not just the happy path
- Provide redlines for complex layouts
- Walk through the handoff with the developer
Related skills
More from owl-listener/designer-skills and the wider catalog.
heuristic-evaluation
Systematic expert review of interfaces against Nielsen's 10 usability heuristics with severity ratings.
hicks-law
Reduce decision time by controlling the number of simultaneous choices presented.
icon-system
Design and standardize icon systems with grid, sizing, naming, and implementation specs.
illustration-style
Define visual language, colour usage, and application rules for consistent illustrations across your product.
information-architecture
Design content structure, hierarchy, labeling, and navigation models to help users find information and understand their location.
interview-script
Generate structured interview scripts with warm-up, core exploration, and wrap-up sections for user research.