Design System Documentation

We get asked a lot: “How do you handle design system documentation?” So I recorded a full walkthrough of our actual workflow. Here’s the short version: 1. We use Figma Console MCP to generate component documentation. 2. It analyzes the selected Figma component. 3. If a developed version exists, it compares design + code and checks for parity. 4. It generates structured markdown docs (great for nearly any documentation software as is). 5. We ingest those docs into our Company Docs MCP. 6. They’re published to a vector database and instantly retrievable via Claude, Slack, or any MCP client. The important part: This is not “press a button and hope for magic.” The purpose, intent, governance, and usage guidelines still start with humans. AI handles the structured synthesis. It inspects variants, props, tokens, detects drift, and formats it consistently. We stay involved where judgment matters. From there, documentation becomes queryable infrastructure. Ask Claude: → “What variants does Button Group support?” → “Which tokens are applied?” → “Is there drift between design and code?” Or ask the Slack bot the same thing. Same source. Same context. Live retrieval. The demo walks through the entire flow, including generating docs from Figma-only components and publishing them through our MCP server. If you’re deep in documentation work, this one’s for you. 🔗 Company Docs Repo: https://lnkd.in/gZpZ4p7W 📖 Resource Article: https://lnkd.in/gnHDXXA7 Documentation doesn’t have to sit in a static site hoping someone reads it. It can participate!

Every time you start a documentation project, how much time do you spend re-litigating the same decisions? Which words are on the avoid list? How are procedures structured? What is the callout hierarchy? When do you use 'log in' or 'login'? What colors, fonts, or structures do you use? A technical writing design system solves this. One reference that captures your voice and tone rules, content patterns, formatting standards, and word decisions. And it is structured enough that another writer or an AI tool could produce work that fits in with you and your existing documents. Design system is a UX term — Figma, tokens, component libraries. But the concept transfers directly to documentation. And it matters more now: when AI helps you draft or review, it defaults to general conventions. Your design system is how you govern that output. I built one recently using Claude, starting from my own website. The post below walks through exactly what to include, how to prompt for it, and how to use it immediately. It took resources and documents that already existed and created the design system and style guide elements. https://lnkd.in/emsA_2gz

Don't overcomplicate design-to-dev handoffs. Listen up designers, dropping Figma files into the void and praying for the best: Your developers are SILENTLY SCREAMING. And no, it's not because they hate designers. Here's the truth about your current process: • You're designing in isolation • You're skipping documentation • You're ignoring technical constraints • You're using inconsistent naming conventions Instead, here's what actually works: 1. Component Audit First - Map existing components before new designs - Document reusable patterns - Align with dev team's component library 2. Design System Integration - Use real data, not Lorem Ipsum - Define clear states (loading, error, success) - Document responsive breakpoints 3. Collaborative Reviews - Weekly design-dev syncs - Live prototype reviews - Technical feasibility checks early 4. Handoff Documentation - Clear component specs - Interaction flows - Edge cases defined - Accessibility requirements Stop treating handoff like throwing designs over a wall. Start treating it like a bridge you're building together. --- PS: The best designs aren't just beautiful. They're buildable. When's the last time you asked your dev team what would make their life easier? Follow me, John Balboa. I swear I'm friendly and I won't detach your components.

What if documentation wasn't a chore but something teams actually enjoyed using? That's what eBay’s design team achieved with their new design system, Evo. Rather than settling for scattered files and siloed information, they reimagined what documentation could be. We recently spent time with Tyler Moore, Ryan Tinsley, and Cordelia McGee-Tubb to understand how they rethought their approach. Instead of maintaining separate resources for designers, developers, and accessibility, they built a unified Playbook that brings everything together. The magic lies in their custom Figma plugin. Updates that once took days now happen in minutes. Components track their implementation status across platforms automatically. Accessibility requirements are woven directly into the documentation process. "Our previous setup buried critical information in different places," explains Cordelia. By connecting these dots, they've created something more valuable than just visual guidelines. The results are tangible. Office hours have evolved from basic troubleshooting to deeper discussions about patterns and principles. Teams reference the documentation without prompting. The system has become a living part of how eBay works. There's a lesson here for any organization building tools for internal use: When you make documentation a delight rather than a burden, consistency naturally follows. https://lnkd.in/eCfjQuN6

AI agents just got a design memory layer. Coding agents are strong at logic, synthesis, and implementation, but they routinely fail at preserving design systems with precision. They drift on color tokens, violate spacing scales, override border-radius rules, and flatten intentional decisions into arbitrary UI output. They can generate components, but they often cannot reliably preserve the reasoning encoded in a product’s visual system. That is exactly where design.md comes in. design.md is used as a repo-level design contract that an agent can read before it writes or edits UI code. Instead of inferring styles from scattered components, screenshots, or inconsistent historical patterns, the agent reads design.md as the explicit source of truth for the system it is expected to follow. In practice, the file is used to define the design system in two layers. The YAML front matter captures the hard constraints: tokenized colors, typography definitions, spacing scales, radii, and other enforceable primitives. The markdown body explains how those primitives should be interpreted, why they exist, and where they should or should not be applied. That combination matters because agents do not only need raw values. They also need decision context. Once present in the repository, design.md becomes part of the agent’s working context. The agent reads it the same way it reads a README, contribution guide, or architecture note. That means when it generates a component, refactors a layout, or updates an existing screen, it can map its output against the rules and rationale already defined in the file rather than guessing. It is also used as an operational interface for validation and tooling. Teams can lint design.md to catch invalid token references, contradictory definitions, or WCAG contrast failures. They can diff one version against another to identify design-system regressions. And they can export it into implementation targets such as Tailwind config or DTCG-compatible token formats so that the specification does not remain passive documentation, but becomes part of the actual delivery pipeline. The important shift is not just documentation quality. It is execution quality. design.md gives agents a stable, machine-readable, human-explained design layer they can consult before making UI decisions, during code generation, and during subsequent edits. That makes design behavior less probabilistic, more auditable, and far more consistent across the lifecycle of the codebase.

🍱 How To Organize Your Design System At Scale (https://lnkd.in/e9343uqv), a fantastic case study on how to set up a design system with 900 shared components and 25 designers — with product-specific domain components and shared ownership between the design system guild and product designers. Written by Jérôme Benoit ↓ Key takeaways: ✅ 1 design system, 8 design libraries, 1 library serves 1 goal. ✅ Each library has owners, editors (edit/publish), users (view-only). ✅ All designers have access to all resources from all files. ✅ Product team has domains, each domain has feature teams. ✅ Foundations + Core components are owned by design system team. ✅ Domain components are product-specific, owned by product designers. ✅ Each feature team has its own frame (not a page!) on a Domain page. ✅ Domain components are structured [Instance name] 💠 [Core name]. ✅ The work by product teams can move up to the Core level, too. In many products, different feature teams often have very different needs, and that’s why secondary design systems emerge. With this set-up, all teams are still working within 1 single design system, pulling and pushing components between levels and having search across all design work in all domains at once — without an organizational overhead! 👏🏼👏🏽👏🏾 Useful resources: How To Organize 1250+ Design Screens in Figma (+ File examples), by Lorenzo Palacios Venin https://lnkd.in/e7X4fKcj Booking.com: Multi-Platform Design System (+ Figma), by Nicole Saidy https://lnkd.in/edueYQPG Frog: Building A Global Design System, by Anthony Nguyen https://lnkd.in/etkiTxfB Doctolib Figma Files Organization Tips, by Jérôme Benoit https://lnkd.in/eK7bhQeS Multi-Brand Design System, by Pavel Kiselev https://lnkd.in/eShgnPnW Design System Structure for Teams, Projects and Files, by Luis Ouriach https://lnkd.in/eFZUjUCU How to Organize Your Figma Files For Design System, by Jules Mahé https://lnkd.in/eeHG2VzU Organizing Design System For Scalability, by Allie Paschal https://lnkd.in/eeAtakGs Design That Scales (Book), by Dan Mall https://lnkd.in/eeFrqFfP And kudos to the wonderful design team at Doctolib and all the wonderful designers above for sharing their insights for everyone to learn from!👏🏼👏🏽👏🏾 #ux #design #designsystems

MCP changed how design systems work. 👇 Usual DS workflow: → Screenshots from Figma to get documentation in ChatGPT → Paste the text back to Figma or the documentation platform → Manually creating readme files and instructions   → Manually reviewing design token names → Chasing context MCP (Model Context Protocol) changes everything. Think of it as USB-C for AI integrations. One standard. Infinite connections. Here's what just became possible: With MCP: "Audit our entire component library against Figma specs, update the docs, and create issues for any inconsistencies." You get: *Figma file access *Codebase awareness *Terminal execution *PRs & README files generation *Auto-updated docs *Full toolchain context Example flow 👇 ✨ Design token sync: *Figma MCP reads Figma variables/tokens/styles *Generates design tokens (with Cursor, Claude Code, Gemini CLI) *Creates PR with changes *Updates Storybook docs *Notifies team in Slack Start with these 5 MCP connections: 1️⃣ Terminal: run builds, updates, installs, tests 2️⃣ Figma: read files, tokens, variants (Figma MCP) 3️⃣ Codebase: understand implementation, auto-generate docs (Cursor, Claude Code) 4️⃣ Git: branch, review, track changes (GitHub, GitLab, Bitbucket) 5️⃣ Docs: generate and sync automatically (Storybook, Notion, Mintlify) ✅ 𝗛𝗼𝘄 𝘁𝗼 𝘀𝘁𝗮𝗿𝘁: ↪️ Install Cursor ↪️ Add one MCP server ↪️ Copy link from Figma ↪️ Ask: "Generate a complete specs file with all component variants and design tokens." The best part? MCP is an open standard and works with any AI that supports it. #designsystem #MCP #productdesign #AI #designtokens

In the past 10 years, I’ve reviewed 100s of design docs. Here’s how to write review-ready design docs in 3 simple steps. 1/ Start with a skeleton, write these: • Metadata (Title, authors, status, date, reviewers, approvers) • Context and background • Problem statement • Summary or tl;dr (Optional) • Proposed solution details with tradeoffs and selection rationale  • Other alternatives considered • Failure modes of the proposed solution • Open Questions • References (Optional) 2/ After the skeleton, fill in the content under these headings. -If there are sub-sections, add sub-headings.  -Provide examples and sample calculations. -Use bullet points and lists wherever applicable -Include architectural diagrams, graphs and tables. 3/ If the document is large, put a summary after the problem statement. Start with the skeleton, take it one step at a time, and before you know it, you are done! Remember, a good design doc: -helps understand design decisions and implementation details -helps in identifying potential issues and challenges early  -gives a clear understanding of the architecture -serves as a reference doc during the project While you write and review, make sure your work follows these guidelines. I know writing detailed docs doesn’t come naturally when you’re focused on problem solving. But it’s an essential skill you have to learn to level up. just follow a simple procedure, practice and you’ll get the hang of it. – P.S: Check out additional writing tips in the comments below ↓

Good morning! Today, I want to share some design documentation for my level design project, The Cosmic Vale. In these documents, I cover the top/down concept map, original prototype, refined map, quest design, Factions & NPCs, and the player hub. Each document contains a brief description, image references, and expected gameplay elements. Why is design documentation important? Well, design documentation serves as a blueprint and creates a shared vision, allowing the rest of your team - from artists to programmers - to align with the original concept and its execution. It ensures that the team visualizes the same version of the game world. Having a shared understanding is essential for collaboration and for creating a more unified gameplay experience for players! Furthermore, design documentation lays a foundation for the rest of the project. Acting as a guide for each phase of development, such as: asset creation, system & technical design, environmental story telling, and much more. By establishing a clear and organized framework, design documentation helps streamline communication and decision-making, contributing to smoother project management. Moreover, the value of design documentation extends beyond level design. It informs system design by establishing gameplay mechanics, narrative design by mapping out key story beats and storytelling through the game environment, and 3D modeling by providing visual cues for in-game assets. Even programming is influenced by the documentation process, as it defines technical requirements and player interactions that need to be implemented. In summary, design documentation is a comprehensive guide that unifies the vision of a project, ensuring every department works towards the same creative and technical goals. #leveldesign #designdocumentation

Design Decisions Without Documentation? Think Again! Documenting your design decisions is like leaving breadcrumbs for your future self and team. Not only does it foster better products, but it also cultivates a growth mindset, making you a more thoughtful, strategic designer. It is key to the success of any product because it provides clarity to the entire team. As far as I’ve seen, design processes are rarely linear. Multiple stakeholders are involved, each with their own perspective. Keeping track of these decisions helps avoid confusion, ensures consistency, and minimises the risk of reworking designs later. It also serves as a bridge between the present and future iterations, allowing future designers to understand the rationale behind each decision, which can be a huge time-saver. [Tips for Documenting Design Decisions] 1] Start Early and Keep It Simple: Begin documenting from the very first discussions and keep it lightweight. You don’t need to write essays, bullet points or a short paragraph explaining each major decision will suffice. 2] Use Visuals: Where possible, supplement text with visuals. Screenshots, wireframes, and prototypes make it easier to communicate your thoughts. 3] Centralise Documentation: Make sure everyone has access to this documentation by using tools like Notion, Confluence, or even Figma’s comment features. 4] Keep It Organised: Organise documentation chronologically or by feature. It’s easier to reference when things are categorised properly. 5] Review and Update Regularly: Don’t treat documentation as a “set it and forget it” task. Revisit it periodically, especially during major project milestones or product updates. I’ve found that the more transparent you are about your design choices, the stronger your credibility becomes not only as a designer but as a problem-solver. At the end of the day, a well-documented process is your safety net, it ensures you’re making deliberate, informed choices rather than just gut decisions. #uxdesign #uxdocumentation #productdesign #ux