diff --git a/packages/chakra-components/README.md b/packages/chakra-components/README.md
index 6784000..d3a7623 100644
--- a/packages/chakra-components/README.md
+++ b/packages/chakra-components/README.md
@@ -53,6 +53,8 @@ The best place to learn about using this package is the [developer portal](https
### Table of Contents
- [Getting Started](#getting-started)
+- [Component System](#component-system)
+- [Customizing Components](#customizing-components)
- [Reference](#reference)
- [Examples](#examples)
- [Preview](#preview)
@@ -72,6 +74,98 @@ After that, you can add the required vocdoni components dependencies:
yarn add @vocdoni/sdk @vocdoni/chakra-components react-markdown remark-gfm
~~~
+## Component System
+
+This package provides Chakra UI implementations of the Vocdoni component system. The components are initialized automatically when you use the `ClientProvider`:
+
+```tsx
+import { ClientProvider } from '@vocdoni/chakra-components'
+
+function App() {
+ return (
+
,
+ category: Category,
+ key: Component
+) => {
+ const RegistryAwareComponent = (props: P) => {
+ const { components } = useComponents()
+
+ // Ensure components and category exist
+ if (!components || !components[category]) {
+ console.warn(`Registry: Missing components or category "${String(category)}"`)
+ return
| undefined
+
+ // Log component resolution for debugging
+ if (process.env.NODE_ENV !== 'production') {
+ console.debug(
+ `Registry: Resolving ${String(category)}.${String(key)}`,
+ OverrideComponent ? '(using override)' : '(using base)'
+ )
+ }
+
+ // If we have an override component, use it
+ if (OverrideComponent && OverrideComponent !== BaseComponent) {
+ return