Main Concepts
Usage States
The Knapsack UI displays certain editing controls under certain circumstances.
- Public: When viewing the design system documentation on the web without being logged in.
- Logged In: When viewing the design system documentation on the web while logged in.
- Local: When running the design system documentation code on a local machine with access to the code.
| State | Create Pattern Examples | Propose Changes | Connect Code |
| Public | X | ||
| Logged In | X | X | |
| Local | X | X | X |
Creating Documentation
Content documentation is created using Knapsack's system of Blocks. Blocks allow you to add various types of content on a page. This includes rich text of course, but also external embeds from various popular online tools, and automatically generated docs from your design system code.
Writing content in the same environment that patterns are coded in provides you some unique superpowers! For example, want to display every size variation of buttons but not have to worry about keeping it up to date when new sizes are introduced? Use the Pattern Variation block!
Coding Patterns
When developing a pattern, Knapsack provides a live updating stage and hooks into the schema of the pattern to automatically document mutable properties and surface controls for editing them when creating examples.
Managing Patterns
Keeping track of the current state of a particular pattern in a system can be challenging. Knapsack provides a flexible system of statuses to help your team track when a component is ready, needs updating, needs review, etc.
Organizing Content
The main utilities available for organizing your documentation and patterns in Knapsack include...
- Main Navigation: Flexible and searchable. Here you can use Pages (purely documentation), Pattern Pages (comes with tabs for displaying docs and coded components), and Groups (used to group nav items together) to organize top-level content. The navigation structure is decoupled from your design systems folder structure.
- Pattern Page Tabs: A pattern page can have one or more templates or content tabs. You could group multiple button templates under one "Buttons" pattern page, along with an overview tab, etc.
Entering Changes into the System
Knapsack runs along-side your coded design system and stores all documentation in a JSON based database that's generated and stored in your design system's code repository.
If you're not a developer, this means changes you make to the system are happening in your browser only. To save your changes into the system, you need to Propose a Change. Along with providing the opportunity for others to review your submission before it's made available to everyone, it also enters the changes into robust Git powered version control.
If you are a developer, you'll see all content saved as JSON or YAML data in a designated folder of your design system repository. This gives you the ability to edit the content directly in the data file, interact with it via the API, and of course securely store it with your versioned, coded patterns.