docs(uikit): add comprehensive UIKit documentation section#145
Merged
MCarlomagno merged 57 commits intoOpenZeppelin:mainfrom Apr 27, 2026
Merged
Conversation
…pelin Ecosystem Adapters - Add 5 documentation pages: overview, architecture, getting started, supported ecosystems, building an adapter - Include Mermaid diagrams for package topology, capability tiers, profiles, runtime lifecycle, and execution strategies - Add navigation config (ecosystem-adapters.json) and wire into sidebar - Add Ecosystem Adapters section to ethereum-evm.json navigation under Open Source Tools - Register ecosystemAdaptersTree in navigation index and use-navigation-tree hook Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
…x with flowchart subgraphs The block-beta diagram type causes a circular JSON serialization error in the Mermaid component. Replace with flowchart subgraphs which render correctly with colored tier groupings. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
…rint - Overview: replace expanded 13-node tier tree with compact 3-node summary - Architecture: replace oversized Mermaid tier diagram with a single clean table - Removes redundant duplicate tier table Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
…capability matrix The Mermaid flowchart with cross-links between profiles and capabilities created a cluttered spider-web visual. Replaced with a single clear checkmark matrix table that shows exactly which capabilities each profile includes at a glance. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
…mary table The Mermaid subgraph cards took excessive vertical space for minimal info. Replaced with a single 5-row table showing adapter, networks, capability count, and status. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
- Add 'Using with React' section covering wallet context providers, configureUiKit, connectWallet/disconnectWallet, and hook facade pattern (useAccount, useSwitchChain, etc.) - Add 'Multi-Ecosystem Apps' section showing how to instantiate runtimes from EVM + Stellar adapters in the same application - Add prominent link to the adapters GitHub repo on the overview page - All API details referenced from adapter source code Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
…ation-27d3 feat(ecosystem-adapters): add React integration and multi-ecosystem documentation
Add the Ecosystem Adapters folder to Stellar, Polkadot, Midnight, and Arbitrum Stylus navigation trees so the section is discoverable from every supported ecosystem, not just EVM. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
…ation-27d3 feat(navigation): add Ecosystem Adapters to all ecosystem sidebars
Add 6 new documentation pages for OpenZeppelin UIKit: - Overview: package map, architecture diagram, design principles - Getting Started: installation, Tailwind setup, first form - Architecture: package layers, capability tiers, runtime lifecycle - Components: UI primitives, form fields, renderer widgets - React Integration: providers, hooks, wallet state, multi-ecosystem - Theming & Styling: Tailwind v4 tokens, dark mode, customization All pages include Mermaid diagrams and cross-link to Ecosystem Adapters docs. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Register UIKit docs under Open Source Tools in the sidebar navigation with links to all 6 documentation pages. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Place the GitHub repository link in an info Callout at the top of the overview page, matching the pattern used in the Ecosystem Adapters docs. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Replace nested subgraph diagrams with flat color-coded flowcharts. Eliminates overlapping labels and tangled arrows by using: - Individual styled nodes instead of subgraph containers - Minimal dependency arrows (table covers full details) - Stadium-shaped nodes with color legend - Init config for tighter spacing Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Consolidate 13 individual capability nodes into 3 tier blocks that list their capabilities inline. Avoids the squished side-by-side subgraph layout and renders at full readable size. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
- Remove 'replaces the legacy pattern' sentence - Merge three per-tier tables into a single reference table - Add cross-link to Ecosystem Adapters for full capability deep-dive - Keep diagram, tier summary, and Capability Bundles section (UIKit-specific) Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Multisig is not yet implemented — only EOA and Relayer are available. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Capture and embed screenshots from https://openzeppelin-ui.vercel.app/: - Overview: contract interaction UI as hero image - Components: Form Renderer and ContractStateWidget - React Integration: wallet connection UI with network selector Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Remove contract-interactions and contract-state-widget screenshots that showed RPC errors. Replace overview hero with clean form-renderer screenshot. Re-capture wallet-connect screenshot. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
The deployed example app at openzeppelin-ui.vercel.app has a missing app.config.json which prevents runtime initialization. This blocks Contract State Widget and Wallet pages from loading. Keep only the screenshots that render without a runtime: - example-app-overview.png (landing page with ecosystem switcher) - form-renderer.png (schema-driven TransactionForm) Remove broken screenshots: wallet-connect, architecture-example, form-renderer-scroll. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Add animated GIF showing the ContractStateWidget querying live view functions on Sepolia. Displayed in a flex layout with the GIF on the left and description + code example on the right. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
…rflow in layout Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
…nd nav entry Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
The previous commit reduced the information shown to users (e.g. 'EcosystemRuntir' truncated to fit narrow LR nodes). Restored full descriptive text using bold provider names with descriptions on separate lines, increased node spacing, and set useMaxWidth:false to prevent truncation. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
LR layout with subgraph truncates descriptive text. TD layout without subgraph wrapper allows full-width nodes that display all information. Matches the clean node style used by other UIKit diagrams. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Add wrappingWidth:400 and classDef width:350px to prevent Mermaid from truncating descriptive text in Provider Tree nodes. Use classDef for cleaner style definitions matching other UIKit diagram patterns. Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
…untimeForNetwork return Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
… examples Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
…ateCrudHook, createLiveQueryHook, createJsonFileIO) Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
…ents page Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
… for provider tree diagram Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
docs(uikit): add "Why Use the Storage Plugin?" section with real-world examples
…gram-05ec docs(uikit): fix Provider Tree diagram text truncation in React Integration
👷 Deploy request for openzeppelin-docs-v2 pending review.Visit the deploys page to approve it
|
pasevin
changed the title
Replace invalid ecosystem adapter routes with links that exist in this docs site so link validation passes in CI.
Co-authored-by: Aleksandr Pasevin <aleksandr.pasevin@openzeppelin.com>
Place UIKit nav item directly below Role Manager
10 tasks
Merged
5 tasks
stevep0z
approved these changes
Apr 27, 2026
Collaborator
There was a problem hiding this comment.
Overall great job! Page hierarchy, scaffolding (Cards, Callouts, mermaid, tables) and everything looks good. A few thoughts to consider, none required:
- Em dashes and dashes. Same ask as on the Adapters PR. Could we remove em dashes (
—) and regular hyphens in prose throughout? Prefer ending the sentence where appropriate, or using a comma; semicolons sparingly. Purely stylistic preference. - Cross PR link target. Every page links to "Building New Adapters" at
/ui-builder/building-adapters. That same content now also exists in the Ecosystem Adapters PR at/ecosystem-adapters/building-an-adapter. Once both merge, suggest pointing UIKit's links at the new ecosystem adapters page so we have one canonical home for adapter docs rather than two. Links to update appear inindex.mdx(lines 78, 88, 110, 122),architecture.mdx(89, 137, 220),getting-started.mdx(51, 222), andreact-integration.mdx(272). - Repeated "Building New Adapters" callouts. That same link is referenced 3 times in
index.mdxand 3 times inarchitecture.mdx. The reinforcement starts to read as filler. Consider keeping it once at the bottom of each page's Next Steps and removing the inline mid-section repeats. - Sidebar coverage. UIKit nav is only added to
ethereum-evm.json. The Ecosystem Adapters PR adds its entry to all five chain sidebars (ethereum-evm, stellar, polkadot, midnight, arbitrum-stylus). Intentional? UIKit is chain agnostic, so it probably belongs in every chain's sidebar too; otherwise a Stellar developer browsing docs never sees it. - Sidebar grouping. Same suggestion as on the Adapters PR. UIKit currently lives under "Open Source Tools" alongside Relayer, Monitor, UI Builder, Role Manager, Defender, which read as off the shelf apps. UIKit (and Adapters) are libraries devs pull into their own builds, which feels like a different category.
AddressBookWidgetimage placement. Incomponents.mdx(line 230), the screenshot appears before the section heading, which leaves it visually orphaned. The earlierContractStateWidgetsection uses a side by side layout for image and prose. Consider matching that pattern forAddressBookWidgetso the two widget sections present consistently.
Use lastEcosystem for /ecosystem-adapters like relayer/monitor; drop standalone ecosystemAdaptersTree. Add tab url rules and midnight context. Polish MDX prose; document viem isAddress for EVM addressing.
- useNavigationTree: keep useState lastEcosystem + effect (hydration); set zama from /confidential-contracts and midnight from /contracts-compact; add zama and ecosystem-adapters to shared-path switch. - docs-layout: same state pattern; merge zamaUrls with ecosystem-adapters tab attribution and Ethereum/Midnight conditional urls.
- Refine UIKit MDX copy across architecture, components, and guides. - Treat /tools as ecosystem-aware shared paths; merge Ecosystem Adapters + UIKit from shared/developer-libraries.json to avoid nav duplication.
…section - Link to /ecosystem-adapters/building-an-adapter; keep single Next Steps callouts per page. - AddressBookWidget: lead with intro, full-width image below; drop cramped side layout.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation Pull Request
Summary
This PR adds a new
UIKitdocumentation section to the OpenZeppelin docs site, including overview, getting started, architecture, components, React integration, theming, and storage pages. It also adds supporting screenshots/diagrams, documents key hooks and storage patterns, and wires the new section into the Ethereum & EVM sidebar navigation.Type of Change
Related Issues
Fixes #
Relates to #
Checklist
pnpm run buildpnpm run checkAdditional Notes
This PR is primarily focused on introducing first-pass UIKit product documentation and improving readability with visuals, package-layer diagrams, capability overviews, and practical integration examples. It also includes a few follow-up fixes to examples and diagram/layout readability that were made while building out the new docs set.