feat: major overhaul - monorepo migration, documentation system, and usage-meter components #3
Conversation
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
- Update color scheme from nature tones to neutral grayscale palette - Replace Montserrat font with Inter for cleaner typography - Change headings from font-bold to font-semibold throughout - Add text-balance and improved line-height for better readability - Update registry JSON files to reflect component changes
- Add UsageMeter (Radix) with full accessibility support - Add UsageMeterBase (lightweight) without Radix dependency - Update registry.json with both component entries - Update branding: rename logo from "Registry" to "usage-ui" - Add documentation strategy and redesign workflow - Remove MONOREPO-MIGRATION.md (migration complete)
Set up foundation for component documentation pages with MDX, Shiki syntax highlighting, and reusable documentation components including code previews, API tables, installation tabs, and component navigation.
…ion system - Add new /docs/[name] pages for component documentation - Remove old /registry/[name] route in favor of /docs - Update all sidebar and homepage links to use /docs route - Add component-preview and preview-error-boundary components - Update add-registry-component workflow with documentation step - Add changeset for documentation system changes
The lockfile was out of sync with apps/www/package.json after adding @mdx-js/loader, @mdx-js/react, and @next/mdx dependencies.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Replace implicit types with explicit React.ReactNode annotations for all MDX component overrides to improve type safety.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
9 issues found across 51 files
Prompt for AI agents (all issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx">
<violation number="1" location="packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx:49">
P2: Guard against max being 0 or negative before dividing, otherwise the meter can render invalid widths/aria text (Infinity/NaN) when max is 0.</violation>
</file>
<file name="apps/www/src/components/docs/client-code-wrapper.tsx">
<violation number="1" location="apps/www/src/components/docs/client-code-wrapper.tsx:21">
P2: Handle clipboard write failures so a denied permission doesn’t throw an unhandled rejection and falsely flip the copied state.</violation>
</file>
<file name="apps/www/src/lib/extract-props.ts">
<violation number="1" location="apps/www/src/lib/extract-props.ts:301">
P3: Dead/incomplete code: `match` is captured but never used, and the block just returns the original `type` unchanged. The comment suggests this was meant to resolve actual values but was never implemented. Either complete the implementation or remove the unnecessary code.</violation>
</file>
<file name=".agents/context/decisions/005-component-documentation-strategy.md">
<violation number="1" location=".agents/context/decisions/005-component-documentation-strategy.md:265">
P3: This ADR records two conflicting “Selected” decisions for API documentation (manual MDX tables vs. auto-generated react-docgen-typescript). The document should reflect a single selected approach or explicitly mark one as a future/alternative, otherwise the decision record is ambiguous.</violation>
</file>
<file name="apps/www/src/app/docs/[slug]/page.tsx">
<violation number="1" location="apps/www/src/app/docs/[slug]/page.tsx:25">
P2: `ComponentDocPage` will throw for unknown slugs because `getRegistryItem` throws before the `notFound()` guard can run. Catch the error and call `notFound()` so invalid routes return 404s.</violation>
</file>
<file name="apps/www/src/components/registry/registry-sidebar.tsx">
<violation number="1" location="apps/www/src/components/registry/registry-sidebar.tsx:192">
P2: Active state no longer matches the new `/docs/...` routes, so sidebar items won't highlight. Update the active check to compare against the `/docs/${item.name}` path.</violation>
</file>
<file name="packages/ui/src/components/registry/usage-meter/usage-meter.tsx">
<violation number="1" location="packages/ui/src/components/registry/usage-meter/usage-meter.tsx:57">
P2: Guard against `max <= 0` to avoid division by zero and invalid progress state. Normalize `max` (and optionally clamp `value`) before computing percentage and before passing props to the Progress root.</violation>
</file>
<file name="apps/www/src/components/docs/component-code-preview.tsx">
<violation number="1" location="apps/www/src/components/docs/component-code-preview.tsx:66">
P2: The underline indicator will never become visible because the `data-[state=active]` selector is applied to the indicator element, which doesn’t receive `data-state`. The attribute is on the parent trigger, so the opacity class never toggles.</violation>
</file>
<file name=".agents/workflows/implement-documentation-redesign.md">
<violation number="1" location=".agents/workflows/implement-documentation-redesign.md:313">
P1: Missing `cn` import in code example. The `cn()` function is used but not imported, which will cause a `ReferenceError` when developers copy this code. Add `import { cn } from "@/lib/utils"` after the shiki import.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx
Outdated
Show resolved
Hide resolved
packages/ui/src/components/registry/usage-meter/usage-meter.tsx
Outdated
Show resolved
Hide resolved
Owner
Author
There was a problem hiding this comment.
15 issues found across 51 files
Prompt for AI agents (all issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="apps/www/src/components/docs/client-code-wrapper.tsx">
<violation number="1" location="apps/www/src/components/docs/client-code-wrapper.tsx:22">
P2: Handle clipboard write failures to avoid unhandled promise rejections and inconsistent UI state when permissions are denied.</violation>
</file>
<file name="apps/www/src/components/docs/api-table.tsx">
<violation number="1" location="apps/www/src/components/docs/api-table.tsx:50">
P2: Use nullish coalescing so valid falsy defaults (e.g., empty string) are displayed instead of being replaced with "—".</violation>
</file>
<file name="apps/www/src/mdx-components.tsx">
<violation number="1" location="apps/www/src/mdx-components.tsx:55">
P2: Use horizontal overflow for table wrappers so wide tables can scroll instead of overflowing the layout.</violation>
</file>
<file name="packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx">
<violation number="1" location="packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx:49">
P2: Guard against max <= 0 to avoid NaN/Infinity percentages and invalid width styles when consumers pass max={0}.</violation>
</file>
<file name="apps/www/src/components/docs/component-nav.tsx">
<violation number="1" location="apps/www/src/components/docs/component-nav.tsx:16">
P2: Guard against currentName not found; otherwise next will incorrectly point to the first item when currentIndex is -1.</violation>
</file>
<file name="packages/ui/src/components/registry/usage-meter/usage-meter.tsx">
<violation number="1" location="packages/ui/src/components/registry/usage-meter/usage-meter.tsx:57">
P2: Guard against `max` being 0 (or negative) before dividing; otherwise the percentage becomes Infinity/NaN and the indicator transform breaks.</violation>
</file>
<file name="apps/www/src/lib/shiki.ts">
<violation number="1" location="apps/www/src/lib/shiki.ts:50">
P2: highlightCode allows any BundledLanguage even though the highlighter only loads a small subset. Passing an unloaded language will throw at runtime. Narrow the parameter to the supported language union or validate before calling codeToHtml.</violation>
<violation number="2" location="apps/www/src/lib/shiki.ts:71">
P2: highlightCodeToTokens allows any BundledLanguage even though the highlighter only loads a small subset. Passing an unloaded language will throw at runtime. Narrow the parameter to the supported language union or validate before calling codeToTokens.</violation>
</file>
<file name="apps/www/src/lib/extract-props.ts">
<violation number="1" location="apps/www/src/lib/extract-props.ts:139">
P3: Dead code: `propName.startsWith("...")` can never be true because the regex `[\w]+` capturing `propName` cannot match `.` characters.</violation>
<violation number="2" location="apps/www/src/lib/extract-props.ts:300">
P2: Unused variable: `match` is captured but never used. The comment suggests resolving values, but this just returns the original type. Either complete the implementation or remove the match extraction.</violation>
</file>
<file name="apps/www/src/components/docs/component-code-preview.tsx">
<violation number="1" location="apps/www/src/components/docs/component-code-preview.tsx:1">
P1: This component renders Radix UI tabs but isn’t marked as a client component. Without a "use client" directive, Next.js will treat this file as a server component and Radix UI will fail at build/runtime. Add the directive at the top of the file.</violation>
<violation number="2" location="apps/www/src/components/docs/component-code-preview.tsx:66">
P2: TabIndicator never becomes visible because the `data-[state=active]` variant is applied to the indicator itself, but `data-state` is set on `Tabs.Trigger`. Use a group or parent selector so the indicator reacts to the trigger’s active state.</violation>
</file>
<file name="apps/www/src/components/docs/code-renderer.tsx">
<violation number="1" location="apps/www/src/components/docs/code-renderer.tsx:7">
P2: `CodeRenderer` accepts any `BundledLanguage`, but the highlighter only loads a small subset of languages. Passing an un-loaded language will throw at runtime (“Language not loaded”), which will break docs rendering. Restrict the prop type to the supported list or add a fallback/validation before calling `highlightCode`.</violation>
</file>
<file name="apps/www/src/app/docs/[slug]/page.tsx">
<violation number="1" location="apps/www/src/app/docs/[slug]/page.tsx:25">
P2: Convert the registry lookup to call notFound() when the slug is missing. As written, getRegistryItem throws and the notFound branch never runs.</violation>
</file>
<file name="apps/www/src/app/(registry)/tokens/page.tsx">
<violation number="1" location="apps/www/src/app/(registry)/tokens/page.tsx:38">
P2: The arbitrary font class uses `family-name:` which isn’t valid Tailwind syntax for `font-family`, so this utility won’t apply the intended font. Use a standard arbitrary font-family value instead.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx
Outdated
Show resolved
Hide resolved
Greptile OverviewGreptile SummaryThis PR successfully transforms the project from a flat structure into a production-ready monorepo with a comprehensive documentation system. The migration adds MDX-powered component documentation under Key Changes:
Critical Issue:
Recommendations:
Confidence Score: 3/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant User
participant Browser
participant DocsPage as /docs/[slug]
participant Registry as registry.json
participant CodeExtractor as lib/code.ts
participant Shiki as lib/shiki.ts
participant Demo as /demo/[name]
User->>Browser: Navigate to /docs/usage-meter
Browser->>DocsPage: Request page (SSG)
DocsPage->>Registry: getRegistryItem(slug)
Registry-->>DocsPage: Component metadata
DocsPage->>CodeExtractor: getComponentSource(slug)
CodeExtractor->>Registry: Read registry.json
CodeExtractor-->>DocsPage: Source code string
DocsPage->>Shiki: highlightCode(source, "tsx")
Shiki-->>DocsPage: Syntax-highlighted HTML
DocsPage->>DocsPage: Render ComponentCodePreview
DocsPage->>DocsPage: Check demos[slug] exists
alt Demo exists
DocsPage->>Browser: Render iframe to /demo/slug
Browser->>Demo: Load demo preview
Demo-->>Browser: Render component variants
else No demo
DocsPage->>Browser: Show "Preview not available"
end
DocsPage-->>Browser: Complete page with tabs, API table, install instructions
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
- Fix sidebar active state to match /docs/:slug route pattern - Fix table overflow direction (use overflow-x-auto for horizontal scroll) - Fix API table default value check using nullish coalescing - Fix component-nav next button bounds check to handle missing items - Add division-by-zero guard in usage-meter components - Add error handling for clipboard API in code copy functionality - Add "use client" directive to ComponentCodePreview - Use SupportedLanguage type instead of BundledLanguage for consistency - Add dynamicParams=false and try-catch for proper 404 handling - Fix tab indicator styling with group-data-[state=active] - Update ADR to clarify Decision 6 supersedes Decision 4 - Fix font class name in tokens page (font-inter)
- Fix hydration issues in sidebar and mcp-tabs by deferring Radix component rendering until after mount - Add guards against division by zero in usage-meter components when max <= 0 - Fix code.ts path resolution using __dirname for reliable monorepo paths - Update registry.json to focus on usage-meter components - Add demo components for usage-meter and usage-meter-base - Pre-render code syntax highlighting on server to avoid client-side mismatch - Fix conditional iframe rendering to check if demo exists
Use a filled Circle icon for a cleaner, more abstract logo appearance.
Owner
Author
…riables - Replace custom meter CSS variables with standard shadcn tokens: - success: chart-2, warning: chart-4, danger: destructive, track: secondary - Remove custom --meter-* CSS variable definitions from globals.css - Update favicon from emoji to minimal circle SVG - Improve code.ts to support dual registry lookup (packages/ui + apps/www) - Add dynamic prop extraction for API documentation tables - Update registry.json entries for usage-meter components
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.
| } | ||
|
|
||
| const sourceCode = getComponentSource(slug); | ||
| const codeHtml = await highlightCode(sourceCode, "tsx"); |
There was a problem hiding this comment.
Legacy components display layout file instead of source code
Medium Severity
The new docs page calls getComponentSource(slug) for all registry items to populate the "Code" tab. For legacy shadcn components (accordion, button, alert, etc.) in apps/www/src/registry.json, the files[0].path points to src/layouts/minimal-layout.tsx rather than actual component source files (these components use registryDependencies to reference shadcn's registry). This causes the "Code" tab to display the layout file content instead of relevant component code for approximately 20+ UI primitives.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Summary
This PR represents a major overhaul of the Usage UI project, transforming it from a flat structure into a production-ready monorepo with a comprehensive documentation system.
Key Changes
apps/www(docs site) andpackages/ui(component library)/docsroute with MDX support, live component previews, syntax-highlighted code blocks, and API tablesusage-meterandusage-meter-basecomponents to the registry.agents/directory with skills, workflows, and context documentationCommits Included
Test plan
pnpm installand verify workspace resolutionpnpm buildand verify all packages build successfullypnpm devand verify the docs site loads at localhost:3000/docs/usage-meterand verify component documentation rendersnpx shadcn add https://usage-ui.vercel.app/r/usage-meter.jsonpnpm lintandpnpm typecheckpassNote
Medium Risk
Touches Next.js routing/build pipeline (MDX/SSG) and adds filesystem-based code/props extraction, which could cause build/runtime regressions if paths or parsing assumptions break; other changes are mostly docs and styling.
Overview
Replaces the legacy
/registry/[name]component pages with a new statically-generated/docs/[slug]documentation route that includes examples, installation instructions, and API reference sections.Adds an MDX/tooling-backed documentation stack: Next.js MDX support, Shiki syntax highlighting + copyable code blocks, build-time source extraction from the monorepo, and lightweight TypeScript/JSDoc-based props extraction feeding a new
ApiTable.Updates demos and registry outputs to include new
usage-meter/usage-meter-basecomponents, refreshes global theme/typography (fonts, colors, prose styles), and adds extensive ADR/workflow documentation while removing the obsoleteMONOREPO-MIGRATION.md.Written by Cursor Bugbot for commit 7f30734. This will update automatically on new commits. Configure here.
Summary by cubic
Overhauls the project with a new MDX-powered documentation site under /docs and adds two usage-meter components ready for shadcn installation. This improves the docs experience, streamlines distribution, and modernizes the UI theme.
New Features
Refactors
Written for commit 7f30734. Summary will update on new commits.