By the end of this lesson you can
- Structure a design system file so components are easy to find.
- Separate foundations, components and patterns.
- Document usage alongside components.
The idea
A design system file is used by many people, so its organisation matters as much as its contents. A common structure has three layers:
- Foundations: colour, typography, spacing, radius, elevation, grids, icons. Usually variables and styles.
- Components: buttons, inputs, selects, checkboxes, cards, navigation, modals.
- Patterns: combinations solving common problems, such as a sign-in form, a filter bar or an empty state.
Page structure
Give each component or group its own page, or group related components on a page with clear sections. Order pages logically and use dividers. Hide internal building blocks by prefixing their names (for example with a dot or underscore) so they do not appear in the assets panel.
Documentation next to components
Each component page should show the component set, its properties, do and don't examples, accessibility notes and a link to the coded version. Many teams also keep a website for documentation, but notes in the file help designers at the moment of use.
Why it matters in real projects
If people cannot find the right component quickly, they draw their own, and the system fragments. A clear structure speeds up everyday work, reduces duplicates and makes onboarding new designers much easier. It also shows developers how the system maps to their code.
A realistic example
A growing company's library has 140 components in one long page. Designers search the assets panel and find three different "Card" components, two of them internal pieces never meant for use.
The system team splits the file into Foundations, Components (one page per group: Actions, Inputs, Navigation, Feedback, Data display) and Patterns. Internal pieces get a leading underscore and are hidden from publishing. Each page gets a header with usage guidance and a link to the code. Searches now return one card, and duplicate requests drop.
Step by step
Audit what exists
List all components, styles and variables.
Group them
Sort them into foundations, components and patterns.
Create pages
Create ordered pages with dividers for each group.
Hide internals
Prefix private building blocks so they are not published.
Add documentation
Add a header frame per component with usage, dos and don'ts.
Test findability
Ask a teammate to find five components and time them.
Common mistakes
Mistake Everything on one page.
Instead Group into foundations, components and patterns.
Mistake Publishing internal building blocks.
Instead Hide them with a prefix.
Mistake No guidance on when to use components.
Instead Add usage notes and examples beside each one.
Check your understanding
Choose an answer, then check it. There is an explanation either way.
Practice exercise
Exercise · about 1 h
Organise a mini system
Organise your Stage 5 components into a structured system file.
Steps
- Create foundation, component and pattern pages.
- Move items into place and hide internals.
- Add a documentation header to three components.
- Ask someone to find components and note any confusion.
Deliverable
An organised system file with documentation for three components.
Self-assessment
Tick each item when it is true of your exercise. Be honest; this is for you.
4 items
Summary
- Organise systems as foundations, components and patterns.
- Clear pages and hidden internals improve findability.
- Document usage next to components.
- Good organisation prevents fragmentation.
Further reading
Third-party sources, chosen for reliability. They open in a new tab.
- GOV.UK Design System (opens in a new tab)GOV.UK
A clear example of styles, components and patterns.
- Material Design 3 (opens in a new tab)Google
Your notes
Marking complete updates your course and roadmap progress.