feat(Tooltip): Engineering guideline #429

ddouglasz · 2025-09-10T13:42:16Z

This PR provides a sample template or what we can call an initial draft to building a workflow for our Nimbus component developer docs / Engineering guideline. It should serve as a base where as much feedback as possible is provided until we arrive at a satisfactory template that other components can build upon.

changeset-bot · 2025-09-10T13:42:20Z

⚠️ No Changeset found

Latest commit: 27715fe

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

vercel · 2025-09-10T13:42:21Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
nimbus-documentation	Ready	Preview	Comment	Sep 19, 2025 1:00pm
nimbus-storybook	Ready	Preview	Comment	Sep 19, 2025 1:00pm

…ace.yaml, and package.json

…mbus Tooltip component.

…nality

ddouglasz · 2025-09-18T12:40:46Z

apps/docs/src/components/document-renderer/components/live-code-editor/live-code-editor.tsx

 export const LiveCodeEditor = (props: LiveCodeEditorProps) => {
  const [code, setCode] = useState(props.children);
-  const [activeTab, setActiveTab] = useState<"preview" | "editor">("preview");
+  const [activeTab, setActiveTab] = useState<"preview" | "editor">(


I had to introduce this change since we agreed that for the engineering guideline, the code editor should be the default view.

ddouglasz · 2025-09-18T13:09:09Z

packages/nimbus/src/components/tooltip/tooltip-dev.mdx

+
+Component Anatomy here - image with parts and description as can be seen on [combobox](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=5311-13804&p=f&m=dev) for example
+
+![](/images/tooltip/tooltip.png)


This is likely not relevant to this component but since this is almost like a Poc, I added it. The idea is the component anatomy image might not be necessary for simple components so it is optional.

This is very valuable conceptually, especially for consumers who prefer to learn visually. I think it'd be worth including in every guideline

ddouglasz · 2025-09-18T13:11:24Z

packages/nimbus/src/components/tooltip/tooltip-dev.mdx

+)
+```
+
+```....Add example snippets for each relevant component prop```


In react aria, the docs showcases a good number of the relevant props use cases with code snippets. Should we consider doing the same thing?

ddouglasz · 2025-09-18T13:12:50Z

packages/nimbus/src/components/tooltip/tooltip-dev.mdx

+
+### API Reference
+
+<PropsTable id="Tooltip" />


We still need a different topic to discuss how we would manually add props. The exposed props listing on the props table does not capture a lot of the important props.

tylermorrisford · 2025-09-18T15:48:02Z

packages/nimbus/src/components/tooltip/tooltip-migration-guide.mdx

+| UI Kit Component | Nimbus Component | Notes |
+|------------------|------------------|-------|
+| `<Tooltip>` | `<Tooltip.Root>` + `<Tooltip.Content>` | Now uses compound component pattern |
+| `title` prop | `<Tooltip.Content>` children | Text content now goes as children |
+| `isOpen` prop | `isOpen` prop | ✅ Same API |
+| `onClose` | `onOpenChange` | ⚠️ Renamed, now receives boolean parameter |
+| `horizontalConstraint` | Not supported | ❌ Removed - use CSS or container sizing |


Beautiful. I cried. 10/10

tylermorrisford · 2025-09-18T15:50:30Z

packages/nimbus/src/components/tooltip/tooltip-migration-guide.mdx

+- **Testing**: Include both providers in test wrapper
+- **Accessibility**: Built-in ARIA support, keyboard navigation included
+
+### Migration Checklist


This should calm some nerves - it may not ever be totally complete for every instance but that's a lovely idea.

tylermorrisford · 2025-09-18T15:58:14Z

packages/nimbus/src/components/tooltip/tooltip-dev.mdx

+
+Use the [Nimbus storybook Tooltip component story](https://nimbus-storybook-6l4m4g78g-commercetools.vercel.app/?path=/docs/components-tooltip-tooltip--docs) as a playground for visual testing of the component. 
+
+#### 3. Regression tests


Anything in here?

Its kind of a placeholder for now since we have not fully come up with a regression test strategy yet.

tylermorrisford · 2025-09-18T15:59:41Z

packages/nimbus/src/components/tooltip/tooltip-dev.mdx

+- `delay` and `closeDelay`: More granular control over timing
+- `horizontalConstraint`: Use CSS width constraints on content instead
+- `tone`: Styling is now handled through design tokens
+


For discussion: should there be a pitfalls/don'ts section for devs?

Do you have any examples? Do the design guidelines suffice?

Yes the design guideline does that already, but good point, I think we can have a note somewhere that states something like "for design guidelines, see [link]".

tylermorrisford

This is absolutely what I would want. I know it will be a big lift to provide this for every component but this should make life so much easier 🙏

stephsprinkle

I think this is a great place to start. Are we going to look into tabs (one for design, dev, and migration) for the final product?

stephsprinkle · 2025-09-18T18:19:09Z

packages/nimbus/src/components/tooltip/tooltip-dev.mdx

+
+```....Add example snippets for each relevant component prop```
+
+### API Changes


This section feels like it belongs in the migration guide

Oh yes, I added it there too. I can take it out from here.

Are we going to look into tabs (one for design, dev, and migration) for the final product?

Yes, I thinks we discussed exploring that possibility.

I agree, this belongs in the migration guide

stephsprinkle · 2025-09-18T18:19:55Z

packages/nimbus/src/components/tooltip/tooltip-dev.mdx

+- `delay` and `closeDelay`: More granular control over timing
+- `horizontalConstraint`: Use CSS width constraints on content instead
+- `tone`: Styling is now handled through design tokens
+


Do you have any examples? Do the design guidelines suffice?

stephsprinkle · 2025-09-18T18:20:40Z

packages/nimbus/src/components/tooltip/tooltip-dev.mdx

+// Test wrapper with required providers
+const TestWrapper = ({ children }: { children: React.ReactNode }) => (
+  <IntlProvider locale="en" messages={{}} defaultLocale="en">
+    <NimbusProvider>
+      {children}
+    </NimbusProvider>
+  </IntlProvider>
+);


Aren't we going to put NimbusProvider into App Kit? One of Tobi's biggest complaints was this here pattern in tests.

If we are doing that, then that would be great!

Do you have any examples? Do the design guidelines suffice?

Yes, I think we can point to the guidelines here

stephsprinkle · 2025-09-18T18:23:24Z

packages/nimbus/src/components/tooltip/tooltip-migration-guide.mdx

+```tsx
+<Tooltip.Root>
+  <Button>Button</Button>
+  <Tooltip.Content style={{ maxWidth: '200px' }}>


Forgive my ignorance, isn't one of the main benefits of Nimbus that we can put styles directly on our components like maxWidth="200px"?

No, forgive my ignorance actually 😅
You are correct!

I made some updates here to handle most of the feedback 27715fe
Thank you.

…mentation - Adjusted JSX formatting in tooltip examples for consistency. - Updated migration guide to clarify usage of `maxWidth` property in Tooltip.Content. - Added caution note regarding provider availability in testing setups.

feat(Tooltip): Migration guideline

7c3e0db

chore(deps): add react-intl dependency to pnpm-lock.yaml, pnpm-worksp…

d2901df

…ace.yaml, and package.json

vercel bot deployed to Preview – nimbus-documentation September 10, 2025 13:56 View deployment

vercel bot deployed to Preview – nimbus-storybook September 10, 2025 13:57 View deployment

refactor(tooltip): update dev guideline template documentation for Ni…

2195689

…mbus Tooltip component.

vercel bot deployed to Preview – nimbus-documentation September 10, 2025 16:18 View deployment

vercel bot deployed to Preview – nimbus-storybook September 10, 2025 16:19 View deployment

ddouglasz requested a review from a team September 11, 2025 11:11

feat(tooltip): add tooltip image and enhance live code editor functio…

46e896e

…nality

ddouglasz changed the title ~~feat(Tooltip): Migration guideline~~ feat(Tooltip): Engineering guideline Sep 18, 2025

vercel bot deployed to Preview – nimbus-documentation September 18, 2025 12:21 View deployment

vercel bot deployed to Preview – nimbus-storybook September 18, 2025 12:22 View deployment

ddouglasz commented Sep 18, 2025

View reviewed changes

tylermorrisford reviewed Sep 18, 2025

View reviewed changes

tylermorrisford approved these changes Sep 18, 2025

View reviewed changes

stephsprinkle reviewed Sep 18, 2025

View reviewed changes

vercel bot deployed to Preview – nimbus-documentation September 19, 2025 12:58 View deployment

vercel bot deployed to Preview – nimbus-storybook September 19, 2025 13:00 View deployment


		Component Anatomy here - image with parts and description as can be seen on [combobox](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=5311-13804&p=f&m=dev) for example

		![](/images/tooltip/tooltip.png)


		Use the [Nimbus storybook Tooltip component story](https://nimbus-storybook-6l4m4g78g-commercetools.vercel.app/?path=/docs/components-tooltip-tooltip--docs) as a playground for visual testing of the component.

		#### 3. Regression tests


		```....Add example snippets for each relevant component prop```

		### API Changes

feat(Tooltip): Engineering guideline #429

Are you sure you want to change the base?

feat(Tooltip): Engineering guideline #429

Uh oh!

Conversation

ddouglasz commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

vercel bot commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ddouglasz Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tylermorrisford left a comment

Choose a reason for hiding this comment

Uh oh!

stephsprinkle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ddouglasz commented Sep 10, 2025 •

edited

Loading

changeset-bot bot commented Sep 10, 2025 •

edited

Loading

vercel bot commented Sep 10, 2025 •

edited

Loading

ddouglasz Sep 19, 2025 •

edited

Loading