Overhaul UI Customization docs: new structure, reference tree, and AI plugin integration - #306
Open
rakesh-snippyly wants to merge 37 commits into
Open
Overhaul UI Customization docs: new structure, reference tree, and AI plugin integration#306rakesh-snippyly wants to merge 37 commits into
rakesh-snippyly wants to merge 37 commits into
Conversation
…n-guide-refresh Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # async-collaboration/comments-sidebar/v2/customize-behavior.mdx # async-collaboration/comments-sidebar/v2/setup.mdx # docs.json # ui-customization/features/async/comments/comment-sidebar/comment-sidebar-v2-primitives.mdx
…omization guide Restores the per-feature wireframe/primitive pages (React + Other Frameworks tabs, screenshots, Storybook links) as Components sections alongside the new guide, removes their away-redirects, cross-links them from the reference lists, and documents unstyled mode (setUnstyledMode) in CSS/Headless pages. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
… audience callouts Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
…alog Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
…ops from main Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
… examples Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
…aches Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
…subpages Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
…ent, nudge AI plugin
Review of this branch against main found strong new content (behavior
reference, decision tree, per-layer approach guides) mixed with internal
agent-guide artifacts and regressions vs the old wireframes docs. This
commit restructures the UI Customization tab and fixes what the review
found:
Navigation
- New 'Recipes & Troubleshooting' group rescues the orphaned human pages
(patterns-and-tips, debugging, edge-cases-and-limitations, localisation
— the last was in main's nav and had been dropped).
- Agent-workflow pages (rules, build-methodology, extraction,
build-gotchas, verifying-a-customization, sdk-gaps-and-blockers,
manifest, source-of-truth-invariant) grouped under Reference >
'AI Agent Workflow' with plugin pointers instead of dangling orphaned.
- Feature Guides now open with an overview/index page (retitled
other-features) that also covers Huddle, Live Selection, Single Editor
Mode, View Analytics, and Rewriter.
- Context moved into the Wireframes subgroup (it depends on token syntax).
- UI Customization Plugin page added to the tab's Concepts group.
- Restored all 58 deleted redirects (their old URLs 404'd), dropped 4
redirect sources that leaked internal naming, removed a duplicate
Comment Pin nav group.
Restored from main's wireframes docs
- styling.mdx: Disable Global Styles (globalStyles: false), the
className/style-does-nothing warning, and React + Other Frameworks
tabs for shadow DOM, injectCustomCss, and dark mode.
- layout.mdx: Other Frameworks tabs for the quick example, token
directives, and the interactivity do/don't example.
- setup-wireframes.mdx: the 'empty wireframes keep default styling'
warning; template-variables.mdx: the worked setUiState markup example.
Junior-readability cleanup
- Stripped internal rule IDs (R0/R1/R4/R9b/R13/…), 'Decision tree QN'
shorthand, 'verified in-browser' lab voice, 'buildable spec' agent
framing, and source-of-truth boilerplate from all human-facing pages;
replaced with plain language and links.
- css-variables.mdx: replaced leaked SCSS #{rem(...)} interpolations with
real values + px comments.
- De-duplicated the two 'Overview' pages, deleted overview's Docs-map
table, humanized its checklist.
- Deleted internal QA 'Coverage' sections from behavior detail pages;
retitled 'The two you asked about'; reference API/props/hooks/events/
data-models pages now link the canonical api-reference as source.
Fixes
- 17 broken anchor links (github-slugger single/double-hyphen mismatches)
plus retargeted release-note and customize-behavior anchors.
- useUnreadCommentAnnotationCountOnCurrentDocument (doesn't exist) →
useUnreadCommentCountOnCurrentDocument in 5 files.
- bubbleOnPinHover default aligned to true across reference pages.
- Reverted backend-sdks/node.mdx to main: branch edits inside its MDX
comment block broke the whole Mintlify build (acorn parse error).
- agentic-overview.mdx skill/rule counts aligned with
installation-plugin.mdx.
AI plugin nudges
- One consistent 'Have this design in Figma?' Tip on overview,
how-it-works, decision-tree, setup, styling, wireframes, primitives,
headless, combining-approaches, context, comment-surfaces,
notifications, and the feature-guides overview.
- Plugin page: defined the Figma 'Loop' concept, added a no-Figma
fallback path, explained the Judge, linked --mode values to the
approach pages.
Validated with mint broken-links (passes) and a full jargon/link/anchor
sweep.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Conflict resolutions: - realtime-collaboration/crdt/overview.mdx: took main's side (17 CRDT integrations vs the branch's 4; strictly newer content). - release-notes/version-5/sdk-changelog.mdx: kept main's more specific per-component doc links (all four anchors verified to exist) with the branch's cleaner phrasing for the beta.15 notifications entry. - api-reference/sdk/models/data-models.mdx: combined both sides — main's per-component notifications-primitives links plus the branch's pointer to the primitives catalog. Follow-ups required by the merge: - Main now codifies the no-em-dash house rule in CLAUDE.md; rewrote the 63 em-dashes this branch had introduced (commas/colons/semicolons/ connectives), keeping the 15 in link text that mirror em-dash headings whose slugs other links depend on. - backend-sdks/node.mdx now carries main's version (main independently repaired the parse error this branch had reverted). Validated: no conflict markers remain; mint broken-links passes; docs.json valid; nav orphan check clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
…riables page names The restructure had renamed these to 'Wireframe tokens' and 'Wireframe variables', which broke familiarity with the long-standing page names. Restore the original titles and align all 17 files' link text; page URLs, headings, and anchors are unchanged. The Conditional Templates description now names VeltIf, VeltData, and velt-class directly. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
…eadless approach pages Both pages were React-only. Every code example now has the standard React / Next.js + Other Frameworks tab pair, matching the rest of the docs: custom-element forms with kebab-case attributes for primitives (velt-comments, velt-comment-dialog, the status dropdown family) and Velt.getCommentElement() API methods for the headless data/actions (getAllCommentAnnotations subscribe/unsubscribe, addComment, resolveCommentAnnotation). All names verified against the canonical customize-behavior and comment-dialog primitives pages. Also on the Feature Guides overview: surface the standard comment components directly in the guides table (Comment Dialog, Sidebar, Pin/Bubble/Tool rows) and lead the row for the Text/Inline/Multi-thread guide with 'Comment surfaces' so it matches the sidebar name. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
Remove the standalone 'Feature Guides' nav group: it ran parallel to the Components section and read as redundant. Each guide now opens its feature's Components group as that group's first page: - Comments -> Comment surfaces guide (first page of the group) - Autocomplete -> Mentions & autocomplete guide - In-app Notifications / Reactions / Recorder / Activity Logs -> their guides, sidebar-titled 'Overview' - Tags/Arrows/Areas guide placed before the Arrows group - Presence & cursors guide opens Components: Realtime Collaboration - The index page is retitled 'Customize by Feature' and opens Components: Async Collaboration Page URLs are unchanged, so no redirects are needed. Updated the overview reading order and the eight agent-page Info boxes that pointed at the old group. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
…docs' scannability The Concepts pages read as dense essays next to the old docs' short, code-first pages. Restore that structure and simplicity without losing content: - overview: reading order cut to six short steps; the agent-flavored 'Implementation checklist' removed (its content lives in the decision tree and Setup). - how-it-works: numbered spec-style headings replaced with plain ones; the densest paragraphs (wireframes-vs-primitives blockquote, cloned- markup bullet, primitives layout note) split or tightened. - decision-tree: golden principles cut from five to three; the S1-S8 sub-decision wall collapsed into an AccordionGroup with question-style titles; Q2/Q3 shortened and their broken nested bolding fixed. - setup: title shortened to 'Setup'; intro Note cut to two sentences; the cross-cutting section compressed to one-line bullets plus the deep-dive link; the closing 'How to think' essay removed (duplicated in Patterns & tips). Inbound anchors preserved (setup sections 2/3/4/6 keep their headings); mint broken-links passes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
Two conflicts, both the same shape as the previous merge: main repointed suggestion-related links to the specific comment-dialog primitives anchors (veltcommentdialogsuggestion / veltcommentdialogsuggestionbanner, both verified to exist) where this branch had generic reference-page links. Took main's side in data-models.mdx and the version-5 changelog; its '## [Usage Examples]' form matches the file's established pattern. Main's new comment-dialog overview page auto-merged into the nav cleanly. mint broken-links passes; docs.json valid; no orphans. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
…mplates on main's structure
Per review feedback, the Wireframes subgroup pages should read as main's
docs first, expanded with this branch's exhaustive material:
- template-variables.mdx: restored main's full page as the base
(Using Built-in Velt Data with Basic Usage + Available Data Objects
tables + context resolution + the custom user card example; Injecting
Your Own Data with Setting/Using subsections), then appended the
branch's per-component variable catalog as section 3. Main's one
error stays fixed: injected values read via the uiState. path, with
a note about the older bare-name form.
- conditional-templates.mdx: restored main's page as the base
(Velt If component / Velt If attribute / Syntax / Strict CSP /
Examples), enriched Syntax with the branch's nested-path forms and
full operator whitelist, and kept the branch's extras after
(velt-data/velt-class directives, mapped vs flat-config, nested-access
roots, frequently used variables, debugging). Fixed main's wrong
element name in the Velt If attribute example
(velt-comment-dialog-wireframe-header -> velt-comment-dialog-header-wireframe).
- layout-customization.mdx: restored main's intro ('what you can do'
bullets + the changes-apply-globally Note, now linking the scoping
exception).
Inbound anchors preserved (mapped-vs-flat-config unchanged; the
setUiState link in how-it-works repointed to main's restored
2-injecting-your-own-data anchor, which an existing inbound link
already expected). mint broken-links passes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
… 3 in Template Variables Demote the per-component catalog headings (Comment Dialog … Tags, Notes) from H2 to H3 so the page TOC shows them indented under '3. Complete Variable Catalog (Per Component)' instead of as siblings. Anchor slugs are text-based, so no links change. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
- Replace the detailed SDK setup walkthrough (auth provider code, setDocuments) with a short 'Install Velt' step linking to the Quickstart and Installation Plugin. - Remove the 'complete minimal example' section. - Convert the page to <Steps titleSize="h2"> with imperative titles (Install Velt / Choose your shadow DOM strategy / Set up the folder structure / Follow the structural rules), matching the docs' setup-page convention; shadow DOM options now have React + Other Frameworks tabs. - Cross-cutting concerns stays as a closing section. - Repointed the five inbound anchors (styling, css-variables, combining-approaches x2, localisation) to the new step headings. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
…ded Setup step Remove the 'UI Customization Plugin' entry from the Concepts sidebar group. Instead, Setup gains a second step, 'Recommended: use the UI Customization Plugin', after Install Velt: use the plugin if the design is in Figma, otherwise continue with the manual steps below. The now-redundant plugin Tip at the top of the page is removed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
Setup is now only actions: - Removed the 'Follow the structural rules' step: rules are reference, not a one-time action, and one of its two rules restated the shadow DOM step. The one-VeltWireframe rule became a Note inside the folder-structure step, which already houses the registry file. - The cross-cutting section (guidance for while you build, not setup) shrank to a one-line pointer Note; localisation.mdx dropped its circular backlink and combining-approaches its anchor into the removed step. - Steps are now: Install Velt / Recommended: use the plugin / Choose your shadow DOM strategy / Set up the folder structure. Overview stops re-teaching what How-it-works owns: the default- preference and mixing paragraphs after the layer table collapsed to one routing line. Decision tree leads with the tool: the numbered 'How to use this' list and both pre-Q1 blockquotes (which duplicated accordion checks 1-2 and the matrix's reference links) compressed to a two-sentence lead-in. mint broken-links passes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
…up step The closing line pointing at the approach pages was trailing prose after the Steps block; it is the next action, so it becomes step 5. The cross-cutting Note moves inside it, since that guidance applies while you build. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
The four-layer comparison existed in three tables and shadow DOM in three places. Each page now owns one thing: - overview (orient + route): its layer table drops the Design control and Effort columns, which the decision tree's comparison matrix owns. - how-it-works (mental model only): 'Mix layers per feature' loses its five worked examples and the one-registry rule (Combining approaches and Setup own those); the primitives-vs-wireframes section keeps the mechanism but hands the 'so which do I pick' decision to the decision tree's UI-component-library table, where it was already documented; Shadow DOM shrinks to the concept plus links to Setup (the action) and CSS (the detail). Section retitled 'Wireframes are copies; primitives are components' to name the mechanism it teaches. - decision-tree (the tool): dropped leftover 'Record layer = mixed' spec voice. Also replaced four inbound links that targeted <Step title> anchors on Setup with links to the page: Setup no longer has markdown headings, and the repo's only precedent for step-title anchors is itself broken. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
284 -> 209 lines, same coverage, less explaining: - Intro cut from five stacked blocks to a one-line definition plus the playground/plugin Info and the className warning; the separate 'The model' section folded into the theming section (one line about legacy tokens). - Headings are now plain and scannable (Make your CSS reach Velt / Theme with variables / Dark mode / Fonts / Override classes / Unstyled mode) instead of 'Steps' with six numbered 'Step N: long sentence' titles, which implied a required sequence. - The four-bullet 'Shadow DOM & wireframes (root vs nested)' subsection plus its Tip compressed into one Note. - Dropped restatement lines that repeated the code above them (the dark mode recap, the injectCustomCss recap, the unstyled-mode trailer), and trimmed the class-override workflow to three steps. - Repointed 13 inbound links across 13 files to the new anchors. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
…section The playground was only linked from the page-level Info callout. Add it as a Tip in 'Theme with variables', where you are actually writing the tokens it generates, and reword the top Info so the two mentions serve different purposes (page-level shortcuts vs point-of-use). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
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
3 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.
Summary
Full overhaul of the UI Customization tab, aimed at making a junior frontend engineer productive quickly and steering users toward the UI Customization Plugin. This PR contains the
codex/ui-customization-guide-refreshrestructure plus a branch-vs-main review pass that restored lost content from the old wireframes docs, removed internal agent-guide artifacts, and fixed navigation/link/build regressions.New structure (UI Customization tab)
Review pass on top of the restructure
Restored from the old wireframes docs
Disable Global Styles(globalStyles: false) and theclassName/style-does-nothing warning on the CSS pageinjectCustomCssexamplessetUiStatemarkup example, the "empty wireframes keep default styling" warning, and Theme Playground promotionlocalisationrestored to the navJunior-readability cleanup
#{rem(...)}values with real values + px comments in the CSS variables referenceCorrectness fixes
backend-sdks/node.mdx(edits inside its MDX comment block broke the Mintlify build)useUnreadCommentAnnotationCountOnCurrentDocument→useUnreadCommentCountOnCurrentDocument(5 files);bubbleOnPinHoverdefault aligned totrue; 17 broken anchor links fixedapi-referencepages as source of truthAI plugin integration
--modevalues to the approach pagesValidation
mint broken-linkspasses (it failed before thenode.mdxrevert)docs.jsonvalidatedRelated
codex/ui-customization-guide-refresh); once this merges to main, Reorganize UI customization docs and add AI agent workflow section #305 can be closed.🤖 Generated with Claude Code
https://claude.ai/code/session_019wS4bsnet283ve432kWrXK
Generated by Claude Code