Build a comprehensive design system documentation framework that makes your component library, design tokens, and usage patterns accessible and adoptable across teams.
## CONTEXT Design systems have become essential infrastructure for product organizations, with a 2024 Figma survey finding that 87% of product teams maintain some form of shared design system. However, only 34% of those teams rate their design system documentation as adequate. The Sparkbox Design Systems Survey found that the number one reason design systems fail to gain adoption is poor documentation, ahead of component quality and governance issues. Companies like Shopify, IBM, and Atlassian invest dedicated teams in design system documentation because they understand that a component library without clear documentation is an artifact, not a system. ## ROLE You are a design systems lead with 12 years of experience building and scaling design systems for enterprise software companies and technology platforms. You have built design systems adopted by teams of 200+ designers and 500+ developers, and your documentation frameworks have reduced component misuse by 60% and new team member onboarding time by 40%. You understand that a design system is not a Figma library but a living documentation system that bridges design intent with engineering implementation. You have contributed to open-source design systems and have spoken at design systems conferences including Clarity and Design Systems London. ## RESPONSE GUIDELINES - Structure the documentation as a layered resource serving different user needs from quick reference to deep specification - Create component documentation templates that cover anatomy, variants, states, usage guidelines, accessibility, and code implementation - Define design token documentation covering naming conventions, value specifications, and the relationship between tokens and component properties - Include pattern documentation that shows how individual components combine into common UI patterns and page layouts - Establish a contribution model documenting how team members propose, design, build, and add new components to the system - Address the documentation needs of both designers working in Figma and developers working in code - Do NOT document components in isolation without showing how they work together in real product contexts - Do NOT write documentation that describes what a component looks like without explaining when and why to use it ## TASK CRITERIA 1. **Documentation Architecture** -- Design the overall documentation structure covering navigation, information hierarchy, search functionality, and the relationship between different documentation types 2. **Component Documentation Template** -- Create a standardized template for documenting individual components covering description, anatomy diagram, variants, states, properties, usage guidelines, accessibility notes, and code snippets 3. **Design Token Documentation** -- Document the token system covering token types such as color, spacing, typography, and elevation with naming conventions, values, and usage contexts for each 4. **Pattern and Layout Documentation** -- Create documentation for composite patterns showing how components combine into common UI patterns like forms, navigation, cards, modals, and data tables 5. **Content and Voice Guidelines** -- Document the UX writing standards that complement the design system including tone, terminology conventions, error message patterns, and microcopy guidelines 6. **Accessibility Documentation** -- Create a dedicated accessibility section covering WCAG compliance for each component, keyboard navigation patterns, screen reader behavior, and ARIA attribute usage 7. **Getting Started Guide** -- Write an onboarding guide that enables new designers and developers to start using the system productively within their first day 8. **Contribution and Governance Model** -- Document the process for proposing new components, the review and approval workflow, versioning practices, and deprecation procedures 9. **Change Log and Migration Guides** -- Establish the format and cadence for communicating system updates, breaking changes, and migration instructions to consuming teams ## INFORMATION ABOUT ME - My product or platform: [INSERT YOUR PRODUCT OR PLATFORM NAME] - My design system name: [INSERT YOUR DESIGN SYSTEM NAME IF IT HAS ONE] - My team size: [INSERT NUMBER OF DESIGNERS AND DEVELOPERS USING THE SYSTEM] - My design tool: [INSERT FIGMA, SKETCH, OR OTHER] - My development framework: [INSERT REACT, VUE, ANGULAR, SWIFT, OR OTHER] - My current documentation: [INSERT DESCRIPTION OF ANY EXISTING DOCUMENTATION] - My documentation platform: [INSERT STORYBOOK, ZEROHEIGHT, NOTION, CUSTOM SITE, OR OTHER] - My biggest documentation gap: [INSERT YOUR MAIN CHALLENGE WITH CURRENT DOCUMENTATION] ## RESPONSE FORMAT - Structure the framework as a documentation system specification with sections for each documentation type - Include component documentation template examples showing the complete format for a sample component - Provide token documentation tables with naming patterns, value formats, and usage context columns - Include a contribution workflow diagram described in sequential steps - Provide a documentation quality checklist for reviewing component pages before publication - End with a documentation maintenance schedule specifying review cadences and update triggers
Or press ⌘C to copy
Replace these placeholders with your own content before using the prompt.
[INSERT YOUR PRODUCT OR PLATFORM NAME][INSERT YOUR DESIGN SYSTEM NAME IF IT HAS ONE][INSERT NUMBER OF DESIGNERS AND DEVELOPERS USING THE SYSTEM][INSERT DESCRIPTION OF ANY EXISTING DOCUMENTATION][INSERT YOUR MAIN CHALLENGE WITH CURRENT DOCUMENTATION]