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

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

[FX-NNNN]

Description

Describe the changes and motivations for the pull request.

How to test

Temploy
FIXME: Add the steps describing how to verify your changes

Screenshots

Before.	After.
Insert screenshots or screen recordings	Insert screenshots or screen recordings

Development checks

Breaking change

codemod is created and showcased in the changeset
test alpha package of Picasso in StaffPortal

All development checks should be done and set checked to pass the
GitHub Bot: TODOLess action

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: 0e85a54

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:47:04Z

+2. **Reuse prop names across components.** The same concept must use the same prop name everywhere. If `collapsed` denotes a collapsed state in one component, every other component expressing the same concept must also use `collapsed` — not `isCollapsed`, `folded`, or `minimized`. Reuse before inventing.
+3. **Keep prop names short and simple.** Prop names should be as short as possible while staying readable. Prefer `size` over `sizeText`, `color` over `colorValue`, `label` over `labelString`. Drop redundant suffixes that restate the type or context.
+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.


We should put here some exception for existing state until we migrate from it and decide how to replace some of them with e.g. slots

no exceptions, if it will fail - we will see that. We can add instructions to the orchestrator to ignore this error maybe 🤔

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 🤔

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add picasso design patterns#4956

Add picasso design patterns#4956
denieler wants to merge 4 commits into
masterfrom
design-patterns-doc

denieler commented May 13, 2026 •

edited by github-actions Bot

Loading

Uh oh!

changeset-bot Bot commented May 13, 2026 •

edited

Loading

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

Uh oh!

vedrani May 15, 2026

Uh oh!

denieler May 15, 2026

Uh oh!

vedrani May 15, 2026

Uh oh!

denieler May 15, 2026

Uh oh!

vedrani May 15, 2026

Uh oh!

denieler May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

Description

How to test

Screenshots

Development checks

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!

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 15, 2026

Choose a reason for hiding this comment

Uh oh!

denieler May 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

denieler commented May 13, 2026 •

edited by github-actions Bot

Loading

changeset-bot Bot commented May 13, 2026 •

edited

Loading