# Component Catalog: One Searchable Home for Every Design System Part

> Learn what each catalog entry should show, how to organize the catalog so people find parts fast, and how to keep it accurate enough to trust.

**In short:** A component catalog is one searchable home for every design system part, with entries organized so people find parts fast and kept accurate enough to trust.

From "Design systems", a free course by Venkat R. Murty: https://designervenkat.online/learn/design-systems/component-catalog

## What you will learn

A design system is the shared set of parts and rules a team uses to build its products. Each reusable part is a component, such as a button, a text field, or a menu. When a team has dozens or hundreds of components, nobody can keep them all in mind. People rebuild parts that already exist, and the product slowly becomes inconsistent. A component catalog is the fix. It is one searchable, browsable home for every component. Each component has its own page with live demos, options, usage rules, and code, so designers and developers can find and reuse what is already there.

In this lesson you will learn what a catalog entry should contain, how to organize the catalog so people find the right part quickly, and how to keep it accurate enough that the team trusts it. A worked example walks through a Shopify Polaris component page. Two short quizzes check your understanding.

- **Component:** One reusable piece of a product screen, such as a button, a text field, or a card.
- **Design system:** The shared parts, rules, and guidance a team uses to build its screens and products.
- **Component catalog:** A searchable, browsable home for every component, with its demos, options, rules, and code.
- **Live preview:** A working demo of a component that a reader can click and change. It is more useful than a still picture.
- **Variant:** A version of a component with a different look or purpose, such as a main button or a quiet button.
- **State:** A condition a component can be in, such as default, disabled, or loading.
- **Props or options:** The settings a builder can change on a component, such as its label or whether it is turned off.
- **Status:** A label that shows how ready a component is to use.
- **Tag:** A short extra keyword attached to an entry so that search can find it, even when the official name is different.
- **Single source of truth:** One official place for an answer, so that no copy of it can disagree with the official version.

## What does a catalog entry contain?

Every component gets its own entry, which is a page in the catalog. A good entry answers the questions a busy designer asks in the first minute. What is this part? What does it look like? When should I use it? Where is the code? One well-known guide to design system documentation splits these answers into four areas: a description, examples of variants and states, a design reference, and a code reference. A practical entry usually covers six parts.

- **Live preview:** A working demo that people can click and try. A screenshot shows how the part looks, but not how it reacts. Readers prefer interactive demos to static pictures.
- **Variants and states:** Every version of the component and every condition it can be in, such as default, hover, disabled, or loading. Show them together on one page so nobody has to guess what exists.
- **Props or options:** The settings a builder can change, such as a label, a size, or whether the part is turned off. Mark which settings are required and which value is the default.
- **Do and don't guidance:** Short rules for right and wrong use, each with a plain reason. A good entry says when to use the part and when to choose something else instead.
- **Design and code references:** Links to the design file the part came from and to the code that builds it. The designer and the developer then look at the same thing.
- **Status:** A clear label that tells the reader whether the part is stable, in beta, or deprecated. It should appear at the top of the page.

A name and a screenshot are not enough. Entries need depth, or people will use the part in the wrong way. Writing the usage rules and the options takes time, but it prevents costly mistakes later. Accessibility notes also belong in the entry. They tell readers how the part works for people using a keyboard, a screen reader, or other assistive tools.

Status is the entry field that readers check first, so it needs careful wording. A design system team should also decide who owns each entry and how deprecation works, because those rules belong to the system too.

> **Tip:** On a deprecated entry, write the name of the replacement near the top of the page. A reader who lands there should leave knowing what to use instead.

## How do you organize the catalog for findability?

A catalog is only useful if people find the right entry within seconds. Findability is the word for how easily someone can locate something. Four tools make a catalog findable, and a shared entry template keeps every page in the same shape.

- **Categories:** Group parts into a few clear families, such as inputs, navigation, feedback messages, and layout. A reader who knows the family can browse straight to the right area.
- **Search:** A search box that matches names, tags, and plain words. Someone who types a everyday phrase should still reach the right entry, even if the team uses a different official word.
- **Naming:** One agreed name for each part, used everywhere. If the team calls a part a dialog, the catalog, the design file, and the code should all say dialog. Naming conventions keep the whole system easier to follow.
- **Tags:** Extra keywords on an entry, such as synonyms or the problem the part solves. Tags catch the words that people actually type when they are in a hurry.

Use the same entry template for every component. Each entry should follow the same outline, in the same order. When a reader knows where the usage rules sit on one page, they know where to look on every page. A template usually lists the name, a short description of what the part does and when to use it, a live preview, the anatomy, which means the labeled parts of the component, the variants and states, the options, the do and don't guidance, accessibility notes, design and code references, and the status. Designers can also review a new entry quickly, because the template shows what is missing.

> **Tip:** Turn the template into a checklist. If any field is empty, the entry is not ready to publish. This one habit prevents most half-finished pages.

## How do you keep the catalog accurate and trusted?

An out-of-date catalog can do more harm than having no catalog. People try the wrong option, copy a retired part, or give up and build a new one. Trust comes from two things: keeping the catalog tied to the real components, and getting the team to check it before they build.

The strongest way to stay accurate is to build the catalog from the components themselves. Some teams generate their pages from the code, so the option tables, examples, and source references update when the component changes. Others sync the catalog with a shared component library or a design file. In both cases, nobody copies a change by hand into a separate page, so the page cannot drift away from the part. Storybook, a tool that builds components in isolation, can auto-generate such a page from the examples a team already writes.

1. **Tie every entry to the real component:** Link the entry to the live component or its source, not to a copied picture. The demo should show what the product really ships.
2. **Require documentation before a part counts as finished:** Make the entry a required step before a new component or pattern is marked done. Then the catalog grows with the system.
3. **Name an owner for each entry:** If nobody owns the updates, the entry will age. The owner checks the page when the component changes.
4. **Update the status on every change:** When a part moves from beta to stable, or from stable to deprecated, change the label the same day. Add the reason and the replacement name.
5. **Retire parts; do not quietly delete them:** Keep the deprecated entry visible with its replacement, so older screens and questions still have an answer.
6. **Check the catalog against the product on a regular schedule:** Compare a sample of entries with what the product actually shows. Fix any gap you find before it spreads.

Show the status and the version at the top of each entry, not at the bottom. A reader should see at a glance whether the part is safe to use today. A small note with the date of the last update also helps, because it tells the reader how fresh the guidance is.

The catalog should work as the single source of truth. That means it is the one official place for the answer, so no copy can disagree with it. An old wiki page can break this rule. Either point the old page to the catalog or retire it. Then build the habit of checking the catalog. Put the link in the design file, in the code project, and in the onboarding notes for new team members. Ask reviewers to check the catalog before they approve a new part. A catalog that people consult every day is a trusted catalog. One that nobody opens is not, however complete it looks.

## Worked example: one Polaris component page

Shopify's Polaris design system is a useful model. The steps below show how a reader moves through the catalog to one part. The details come from Shopify's developer guide and from published summaries of Polaris. Websites change layout over time, so treat the steps as a pattern to copy, not a fixed map.

1. **Search by the job, not the official name:** A designer who needs a way to choose one answer from a list types a plain phrase into the catalog search. Tags and synonyms let the search match words like choose or pick, even when the official name is different.
2. **Check the status before anything else:** Polaris has two versions of its components. A third-party guide notes that the older React version is deprecated, while the web components are the current choice.
3. **Try the live demo:** Click the demo and change its settings. Watch how the part responds, instead of trusting a picture. This is the fastest way to learn whether the part fits the job.
4. **Compare variants and states:** Look for each version of the part and each condition it can be in. A good entry shows them together, so the reader can pick the right one without building a test screen.
5. **Read the usage guidance:** Read when to use the part, when to avoid it, and what content to put inside it. Polaris entries include content recommendations and notes on mobile behavior, which help a reader make the right choice.
6. **Check the accessibility notes:** Shopify states that its web components have accessibility built in. They use standard page elements, support keyboard use, manage focus, and provide contrast that is suitable for reading. They also log warnings when a required accessibility property is missing. The guide still asks builders to set a label on every form field and to keep headings in order.
7. **Copy the code and follow the design reference:** Use the code example as a starting point, then follow the design reference so the screen matches the design file. Use the site's links to move between the usage page, the options list, and the code without starting a new search.

> **Tip:** Built-in accessibility does not remove the builder's duty. A good catalog says plainly which checks are still the builder's job, such as labels, heading order, and keyboard testing.

## Check your understanding

**Quick check:** A team's designers keep building a new custom dropdown because they cannot tell whether the design system already has one. The wiki page about dropdowns is out of date. Which change to the component catalog would most help, and why?

A. Add a longer wiki page with a full history of every dropdown the team has ever made.
B. Give the dropdown entry tags and plain search words, show its status and last update, and build its live demo and options from the real component.
C. Post a reminder in the team chat asking designers to check with a lead before they start any new part.
D. Hide the dropdown entry until a final version is approved, so nobody sees an old one.

**Answer:** B. Designers build new parts when they cannot find or trust the existing one. Tags and plain search words make the entry easy to reach, and a status plus a demo built from the real component show what is current. A longer wiki page would go out of date again, and hiding the entry leaves designers with no answer at all.

**Quick check:** A new designer types 'pop-up box' into the catalog search and gets no results. The team's entry is named Dialog and has no other keywords. Which fix is best?

A. Rename every dialog in the design files to pop-up box, so the words match.
B. Add pop-up box and similar words as tags on the Dialog entry, and keep the one agreed name.
C. Create a second entry called Pop-up Box that copies the Dialog page.
D. Remove the search box and let people browse by category only.

**Answer:** B. One agreed name should stay, because a shared name keeps the design files and the code in step. Tags carry the words people actually type, so the search finds the right entry. A copied entry creates two versions that can disagree, and removing search makes the problem worse.

## Common mistakes and a quick recap

- **Screenshots only:** A picture cannot show how a part reacts. Use a working demo, and add the options and the do and don't rules.
- **Two names for one part:** When the design file, the catalog, and the code use different names, people cannot match them. Pick one name and use it everywhere.
- **Entries that never change:** A page that was correct last year can mislead people today. Name an owner and tie the entry to the real component.
- **Deprecated parts with no replacement:** A warning with no next step leaves readers stuck. Always name the part to use instead.

A component catalog is a searchable, browsable home for every component in a design system. Each entry should hold a live preview, variants and states, options, do and don't guidance, design and code references, and a clear status. The catalog stays findable through categories, search, consistent naming, tags, and one shared template. It stays trusted when it is generated or synced from the real components, when it shows its status and version, and when the whole team uses it as the single source of truth. Before you build something new, check the catalog first.

## Sources

- [Storybook blog: 4 ways to document your design system with Storybook](https://storybook.js.org/blog/4-ways-to-document-your-design-system-with-storybook/)
- [Storybook blog: How to document your design system, best practices and tools](https://storybook.js.org/blog/how-to-document-your-design-system-best-practices-tools/)
- [Shopify developer docs: Using Polaris web components](https://shopify.dev/docs/api/polaris/using-polaris-web-components)
- [Brainvire: Shopify Polaris guide for developers](https://www.brainvire.com/blog/shopify-polaris-guide-for-developers/)
- [Folio3: What is Shopify Polaris, features and benefits](https://ecommerce.folio3.com/blog/what-is-shopify-polaris/)
- [UX Pilot: 7 Design System Best Practices for UI](https://uxpilot.ai/blogs/design-system-best-practices)
- [Magic Patterns: Documenting Your Design System, Best Practices](https://www.magicpatterns.com/blog/design-system-documentation)
- [Figma blog: Design system 103, documentation that drives adoption](https://www.figma.com/blog/design-systems-103-documentation-that-drives-adoption/)
- [Backlight: Design System documentation best practices](https://backlight.dev/blog/design-system-documentation-best-practices)
- [StackBlitz: How to document design system components](https://blog.stackblitz.com/posts/design-system-component-documentation/)
- [DesignRush: Design System Documentation, a practical guide for teams](https://www.designrush.com/best-designs/print/trends/design-system-documentation)
- [Eleken: Design System With Storybook, setup, testing and tips](https://www.eleken.co/blog-posts/design-system-with-storybook)
- [OneThing Design: 10 Component Library Best Practices for Design Systems](https://www.onething.design/post/component-library-best-practices)
- [getdom.studio: Design System Components Explained with Real Examples](https://getdom.studio/blog/design-system-components)
