Add picasso design patterns by denieler · Pull Request #4956 · toptal/picasso

denieler · 2026-05-13T19:36:22Z

Description

Introducing the AI Claude Review check to validate newly added or modified Picasso components against Picasso base design rules and patterns. This check supposed to be non-blocking for now. It should provide useful information to the component author.

Alpha packages

Manually trigger the publish.yml workflow to publish alpha packages. Specify pull request number as a parameter (only digits, e.g. 123).

PR Review Guidelines

When to approve? ✅

You are OK with merging this PR and

You have no extra requests.
You have optional requests.
1. Add nit: to your comment. (ex. nit: I'd rename this variable from makeCircle to getCircle)

When to request changes? ❌

You are not OK with merging this PR because

Something is broken after the changes.
Acceptance criteria is not reached.
Code is dirty.

When to comment (neither ✅ nor ❌)

You want your comments to be addressed before merging this PR in cases like:

There are leftovers like unnecessary logs, comments, etc.
You have an opinionated comment regarding the code that requires a discussion.
You have questions.

How to handle the comments?

An owner of a comment is the only one who can resolve it.
An owner of a comment must resolve it when it's addressed.
A PR owner must reply with ✅ when a comment is addressed.

changeset-bot · 2026-05-13T19:36:28Z

⚠️ No Changeset found

Latest commit: 5081c72

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

github-actions · 2026-05-13T19:54:22Z

📖 Storybook Preview

🚀 Your Storybook preview is ready: View Storybook

📍 Preview URL: https://toptal.github.io/picasso/prs/4956/

This preview is updated automatically when you push changes to this PR.

github-actions · 2026-05-13T20:21:45Z

📖 Storybook Preview

🚀 Your Storybook preview is ready: View Storybook

📍 Preview URL: https://toptal.github.io/picasso/prs/4956/

This preview is updated automatically when you push changes to this PR.

github-actions · 2026-05-14T10:40:31Z

📖 Storybook Preview

🚀 Your Storybook preview is ready: View Storybook

📍 Preview URL: https://toptal.github.io/picasso/prs/4956/

This preview is updated automatically when you push changes to this PR.

vedrani

Can you extend it with some exceptions for current state so that agent can keep interfaces stable. If I plan to use this I will add in migration prompt that goal is to keep backward compatibility during migration.

vedrani · 2026-05-15T11:51:05Z

+4. **Mirror native HTML prop names.** When a prop corresponds to a native HTML attribute, use the native name verbatim (e.g., `name`, `value`, `type`, `disabled`, `placeholder`, `checked`, `readOnly`, `autoFocus`, `href`, `target`, `rel`, `alt`, `src`). Do not rename, prefix, or alias native attributes (avoid `inputName`, `fieldValue`, `isDisabled`, `linkHref`). For event handlers, keep the native name (`onChange`, `onBlur`, `onFocus`, `onClick`, …), but the callback signature may diverge from the native one when a simpler shape is more ergonomic — e.g., `onChange?: (value: string) => void` is preferred over passing the raw event when only the value is needed.
+5. **Style overrides only via `className` or `style`.** Consumers may customize a component's appearance exclusively through the `className` and `style` props. Do not expose other styling hooks such as `classes`, `styles`, `sx`, `css`, theme overrides, slot-level class props, or styled-component wrappers as part of the public API.
+6. **Prefer `children` over content props.** For simple components, pass content through `children` rather than a dedicated prop. Use `<Button>Save</Button>`, not `<Button content="Save" />`. Reserve named content props for components with multiple, distinct content slots.
+7. **Use `rem` for all sizes.** Express dimensions, spacing, font sizes, and radii in `rem`. The only exception is `1px` (e.g., hairline borders), which may be used directly.


I think there are some other exceptions

I checked codebase of Picasso and couldn't find any that I'd say usage of px makes sense there

vedrani · 2026-05-15T11:52:21Z

+      }
+    }
+    ```
+14. **No `is` prefix on boolean props.** Boolean props are named with the adjective only — `open`, `disabled`, `loading`, `selected`, `collapsed` — not `isOpen`, `isDisabled`, `isLoading`. The same applies to `has`/`should` prefixes.


Ok, but at the same time we should add rule to keep backward compatibility of component interfaces as MUST and only human should approve breaking changes.

I think it's not a "design pattern", it's more like a development practice to prevent breaking changes and keep backward compatibility if the change is really justifiable 🤔 I understand from the orchestrator point of view this addition, but if talking about this particular check on isolation - I think it doesn't make sense to include it here 🤔

I agree with you that it should be kept pure. But in that case we need to add additional info based on 'migration', 'review' or some other phase what is real-world practice.

E.g.

new-feature - error

migration - backward-compatibility over patterns -> warning/ignore

review - warning

github-actions · 2026-05-19T20:51:56Z

📖 Storybook Preview

🚀 Your Storybook preview is ready: View Storybook

📍 Preview URL: https://toptal.github.io/picasso/prs/4956/

This preview is updated automatically when you push changes to this PR.

github-actions · 2026-05-20T10:29:07Z

📖 Storybook Preview

🚀 Your Storybook preview is ready: View Storybook

📍 Preview URL: https://toptal.github.io/picasso/prs/4956/

This preview is updated automatically when you push changes to this PR.

github-actions · 2026-05-20T11:00:08Z

🗑️ Storybook preview cleaned up

The preview deployment has been automatically removed since this PR was closed.

Add picasso design patterns

b8283d9

denieler self-assigned this May 13, 2026

denieler added the no-jira label May 13, 2026

Adjust rules

02c7b43

github-actions Bot added a commit that referenced this pull request May 13, 2026

Sync: PR #4956 Preview

b225927

Fix rules

f8b956a

github-actions Bot added a commit that referenced this pull request May 13, 2026

Sync: PR #4956 Preview

3ddafef

Add CI check

0e85a54

github-actions Bot added a commit that referenced this pull request May 14, 2026

Sync: PR #4956 Preview

2d3f9de

vedrani reviewed May 15, 2026

View reviewed changes

Fix api key name

5081c72

github-actions Bot added a commit that referenced this pull request May 19, 2026

Sync: PR #4956 Preview

5f28ae8

denieler marked this pull request as ready for review May 20, 2026 10:12

denieler requested a review from a team as a code owner May 20, 2026 10:12

denieler added the claude label May 20, 2026

github-actions Bot added a commit that referenced this pull request May 20, 2026

Sync: PR #4956 Preview

ce5b450

vedrani approved these changes May 20, 2026

View reviewed changes

denieler merged commit c628a2e into master May 20, 2026
23 of 28 checks passed

denieler deleted the design-patterns-doc branch May 20, 2026 10:59

github-actions Bot added a commit that referenced this pull request May 20, 2026

Sync: Cleanup PR #4956

9af76b9

Uh oh!

Conversation

denieler commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

When to approve? ✅

When to request changes? ❌

When to comment (neither ✅ nor ❌)

How to handle the comments?

Uh oh!

changeset-bot Bot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions Bot commented May 13, 2026

Uh oh!

github-actions Bot commented May 13, 2026

Uh oh!

github-actions Bot commented May 14, 2026

Uh oh!

vedrani left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vedrani May 15, 2026

Choose a reason for hiding this comment

Uh oh!

denieler May 15, 2026

Choose a reason for hiding this comment

Uh oh!

vedrani May 15, 2026

Choose a reason for hiding this comment

Uh oh!

denieler May 15, 2026

Choose a reason for hiding this comment

Uh oh!

vedrani May 18, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

github-actions Bot commented May 20, 2026

Uh oh!

Uh oh!

github-actions Bot commented May 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

denieler commented May 13, 2026 •

edited

Loading

changeset-bot Bot commented May 13, 2026 •

edited

Loading