
reshaped
Guidelines for building UI with Reshaped, v3 to v4 migration and the Reshaped MCP server
- GitHub stars
- 2.3K
Install
/plugin install reshaped@reshapedRun it inside Claude Code after adding the marketplace with /plugin marketplace add reshaped-ui/reshaped.
Contents
Discovered from sourceSkills 2
Reshaped v3 to v4 Migration
Apply documented and safe migrations from Reshaped v3 to v4 with minimal edits and explicit reporting.
Scope and inputs
- Canonical migration recipes live in
changes/*.mdin this skill directory. - Each file in
changes/*.mdrepresents one breaking-change topic. - Follow documented migration paths from those files first; if there is no automated migration path available and you don't have a high confidence solution – don't edit the code and add this case to the migration report.
- Prefer deterministic, low-risk edits over broad refactors.
Operating rules
-
Confirm migration scope
- Identify which package(s), app(s), or folders should be migrated.
- If scope is unclear, ask a focused clarifying question before editing.
-
Build an ordered migration checklist
- List all available files in
changes/*.md. - Process them one by one in a stable order (for example: alphabetical by filename).
- For each change file, determine whether it applies to the target scope.
- List all available files in
-
Apply migrations conservatively
- Use exact symbol/prop matching when possible.
- Keep behavior unchanged unless the migration doc requires behavior changes.
- Avoid unrelated cleanup while migrating.
- Preserve user-authored custom logic and styling intent.
-
Validate after batches of edits
- Run local checks relevant to the repo (typecheck, lint, tests, build, or targeted checks).
- If a migration introduces uncertainty, stop and verify before continuing.
-
Report outcomes explicitly
- Produce a migration report after edits.
- Include per-migration status, component counts, confidence, and manual actions.
Per-change execution loop
For each migration file in changes/*.md:
- Read the migration file fully.
- Extract:
- Trigger pattern (what old API usage to find).
- Target pattern (what v4 usage should replace it).
- Constraints, caveats, and exceptions.
- Search the scoped codebase for matches.
- Classify each match:
- Safe automated migration.
- Requires contextual/manual decision.
- Not applicable/false positive.
- Apply changes for safe matches.
- Record report data for this migration, even when no matches were found.
Confidence model
Use these confidence levels in the report:
high: mechanical replacement with unambiguous mapping and local validation passes.medium: mapping is mostly clear but depends on component context, composition, or styling intent.low: migration path is incomplete, risky, or requires product/UX intent to resolve.
For every medium or low item, include exact code locations that need review.
Required migration report
Create a report file in the workspace root named:
reshaped-v3-v4-migration-report.md
Report format:
# Reshaped v3 -> v4 Migration Report
## Scope
- Target: <folders/packages migrated>
- Date: <YYYY-MM-DD>
## Migration Results
### <migration name from file>
- Status: `completed` | `partial` | `not-applicable` | `blocked`
- Components updated: <number>
- Confidence: `high` | `medium` | `low`
- Medium/low review locations:
- `<path>:<line>` - <why review is needed>
- Notes: <key decisions, caveats>
- Manual steps (if any):
- <required human follow-up>
<!-- Repeat for every changes/*.md file -->
## Summary
- Total migrations processed: <number>
- Completed: <number>
- Partial: <number>
- Not applicable: <number>
- Blocked: <number>
- Total components updated: <number>
Handling missing automated paths
If a change file has no safe automated migration path:
- Mark status as
blockedorpartial(depending on progress). - Explain why automation is unsafe or impossible.
- Provide concrete manual remediation steps.
- Include precise locations for manual edits.
Communication style
- Be explicit and audit-friendly.
- Prefer short, factual notes over long explanations.
- Distinguish clearly between applied changes and recommendations.
Building with Reshaped
Reshaped is a React design system built around composition: a small set of layout and typography utilities, semantic design tokens, and components that share the same conventions. Most mistakes come from treating it like a generic component library – writing custom CSS for layout, hardcoding colors and pixel values, or guessing prop names.
Look up the API before using a component
Don't write component props from memory. Before using a component for the first time in a task, read its type definitions:
node_modules/reshaped/dist/components/<Name>/<Name>.types.d.ts
Every prop has a comment describing what it does, its default value and how it interacts with other props. The list of exported components, hooks and types is in node_modules/reshaped/dist/index.d.ts. If the Reshaped MCP server is connected, use it for usage examples.
Upgrading from v3? Use the reshaped-v3-v4 skill instead of this one.
Application setup
-
Wrap the application in
<Reshaped>once, at the root, and import the theme CSS. It provides theming, color mode, RTL, keyboard focus handling and the toast provider. Components don't work correctly outside of it.import { Reshaped } from "reshaped"; import "reshaped/themes/slate/theme.css"; const App = ({ children }) => <Reshaped theme="slate">{children}</Reshaped>; -
slateis the built-in theme.theme/colorModeare controlled; usedefaultTheme/defaultColorModewhen the app switches them at runtime withuseTheme()(setTheme,setColorMode,invertColorMode). -
Styles require PostCSS with the Reshaped config. In
postcss.config.js:export { config as default } from "reshaped/config/postcss";. For a custom theme that changes the viewport breakpoints, usegetConfig({ themeMediaCSSPath })from the same module. -
With server-side rendering, set the defaults on the
<html>element to avoid a flash of unstyled content:<html data-rs-theme="slate" data-rs-color-mode="light">(plusdir="rtl"for RTL). -
Next.js: add
transpilePackages: ["reshaped"]andexperimental.optimizePackageImports: ["reshaped"]to the Next config, and render<Reshaped>from a"use client"component used in the root layout. Reshaped components can be rendered from server components. -
Color mode doesn't follow the operating system preference automatically; set it explicitly.
Layout: use View, not custom CSS
View is the layout primitive – a flexbox container with access to the design tokens. Use it instead of <div> with custom styles or utility classes.
<View direction="row" gap={3} align="center" justify="space-between">
<Text variant="featured-3" weight="bold">
Projects
</Text>
<Button color="primary">Create</Button>
</View>
- Flexbox turns on when
direction,gap,alignorjustifyis passed, and the defaultdirectionis"column". Passdirection="row"for horizontal layouts. - A row wraps its children and aligns them to the start by default. Pass
align="center"to center them vertically andwrap={false}to keep them on one line. - Space siblings with
gapon the parentView. Don't add margins or spacer elements. View.Itemcontrols how a single child behaves:grow,shrink,columns(1–12 or"auto", for row direction, items wrap to the next row automatically),orderandgapBefore(overrides the gap before this one item;gapBefore="auto"pushes the item to the end of the row).growandshrinkcan also be set on a childViewdirectly.- For a "fill the remaining space" layout, give one child
grow. The parent then stops wrapping and the other children keep their size. dividedrenders dividers between the children; don't insertDividermanually betweenViewchildren.- Surfaces:
backgroundColor,borderColor,borderRadius,shadow,padding. SettingbackgroundColoralso sets a readable text color for that background. PassingborderColorenables the border on all sides; useborderTop,borderBlocketc. to render only some of them. - Positioning:
position,inset*andzIndexcover overlays, sticky headers and badges without custom CSS.inset="center"centers an absolutely positioned child. bleedapplies a negative inline margin to make an element span the full width of a padded parent, e.g. on mobile.- Render semantic HTML with
as(<View as="ul">,<View.Item as="li">,<View as="main">). Containercenters the page content and limits its width (<Container width="964px">).Gridis for two-dimensional CSS grid layouts; preferViewfor everything one-dimensional.Hiddenshows or hides content per viewport (<Hidden hide={{ s: true, l: false }}>) and works with server-side rendering. It can be used as a direct child ofViewwithout breaking the gaps.
Units and responsive values
- Numbers are multipliers of the base unit (4px in the default theme):
gap={4}is 16px,padding={6}is 24px. Never convert pixels by hand intogap={16}. - Strings are literal CSS values for the size props that accept them (
width,height,maxWidth,minHeight, …):width="320px",height="100%",maxWidth="60ch". Spacing props (gap,padding*,bleed) only take numbers. - Responsive values are objects keyed by viewport and are mobile-first:
{ s: "column", l: "row" }means column onsandm, row onlandxl. Viewports ares,m(≥660px),l(≥900px) andxl(≥1280px) in the default theme. Always include theskey – an object without it isn't treated as a responsive value. - Only props that affect layout are responsive (
G.Responsive<…>in the types) – for exampleViewlayout props,ButtonsizeandfullWidth,Textvariant. Others, likecolor, are not. For those, resolve the value on the client withuseResponsiveClientValue({ s: …, l: … })or render different content withHidden. - Don't read
window.innerWidthor write media queries in JS for layout – use the responsive props.
Colors and tokens
- Use semantic values, never hex colors or raw pixels. In props:
color="primary",backgroundColor="neutral-faded",borderColor="neutral-faded",borderRadius="medium",shadow="raised". - Colors have roles:
neutral,primary,critical,positive,warning. Usecriticalfor destructive actions and errors,positivefor success,primaryfor the main action of a view (usually one per view). - Dark mode is automatic when tokens are used. Don't branch on the color mode to pick colors. To render an area in a different mode, wrap it in
<Theme colorMode="dark">or<Theme colorMode="inverted">. - In custom CSS, use the CSS variables:
var(--rs-color-background-neutral-faded),var(--rs-color-foreground-neutral),var(--rs-color-border-neutral-faded),var(--rs-unit-x4),var(--rs-radius-medium),var(--rs-shadow-raised),var(--rs-duration-fast),var(--rs-easing-standard),var(--rs-z-index-absolute).foreground-*colors are for text and icons on page, elevation and*-fadedbackgrounds. On solid backgrounds likebackground-primary, use the matchingon-background-*color.- Surfaces use
background-elevation-base(cards),-raisedand-overlay(popovers, modals); the page usesbackground-page.
- Media queries in CSS use custom media:
@media (--rs-viewport-m) { … }(also-l,-xl, and-sfor small screens only). - Use CSS logical properties (
margin-inline-start,inset-inline-end) in custom CSS so RTL keeps working. This is also why props are namedstart/end, notleft/right.
Text
- Render text with
Text. Variants, from largest to smallest:headline-1…3,featured-1…6,body-1,body-2,caption-1,caption-2.body-2is the default size of the application text. - Set the HTML tag with
asfor headings and paragraphs:<Text as="h2" variant="featured-3" weight="bold">,<Text as="p">. Withoutas,featured-1…featured-6render ash1…h6and every other variant renders adiv, so passaswhenever the heading level shouldn't follow the variant number. - Secondary text uses
color="neutral-faded"; don't lower the opacity. maxLinestruncates,wrap="balance"balances headings,numerickeeps digit widths stable for changing numbers.
Actions and icons
Button,LinkandMenuItemare based onActionable: passinghrefrenders an<a>, passingonClick(ortype) renders a<button>, and passing none of them renders a non-interactive<span>. Don't put click handlers on non-interactive elements – useActionablefor custom clickable areas, it handles keyboard support and focus rings.- For client-side routing, pass the router link through
renderand spread everything it receives:<Button href="/settings" render={(props) => <RouterLink {...props} />}>. Wrapping aButtonwithouthrefin a router link gives a<span>inside an anchor. - Buttons render with
type="button". Passtype="submit"to the button that submits a form. - Icons are passed as components, not rendered elements:
<Button icon={PlusIcon}>,<Icon svg={PlusIcon} />. Any SVG icon library works (e.g.lucide-react); the SVG should usecurrentColor. - An icon-only button needs an accessible name:
<Button icon={TrashIcon} attributes={{ "aria-label": "Delete" }} />. Iconsizes are unit multipliers (size={5}is 20px) and it inherits the text color by default.<Icon svg={null} />renders an empty box of the same size – use it to keep rows with and without icons aligned. Theiconprops of other components render nothing fornull; pass the emptyIconthrough theirstartSlotinstead.- One
color="primary"button per group of actions; secondary actions stay neutral or usevariant="outline"/variant="ghost".
Forms
-
Every input takes a
nameand callsonChangewith an object, not a DOM event:onChange={({ name, value, event }) => …}(checkedinstead ofvalueforCheckboxandSwitch). -
Inputs are uncontrolled with
defaultValue/defaultCheckedand controlled withvalue/checked+onChange. Don't pass both. -
Wrap fields in
FormControlfor the label, helper and error text – it wires ids and aria attributes, and applies itshasErroranddisabledto the field inside:<FormControl hasError={!!error}> <FormControl.Label>Email</FormControl.Label> <TextField name="email" inputAttributes={{ type: "email" }} /> <FormControl.Helper>We'll only use it for receipts</FormControl.Helper> <FormControl.Error>{error}</FormControl.Error> </FormControl>FormControl.Erroris rendered only whilehasErroris set.requiredshows the indicator and setsaria-required, it doesn't enable native validation.sizeonly changes the label and caption text – set the fieldsizeon the field itself. -
Use
<FormControl group>around aRadioGrouporCheckboxGroup. Inside a group, eachRadio/Checkboxneeds avalue, and the group ownsname, the checked state andonChange. Groups render no element, so lay their children out with aView. -
Native input attributes (
type,autoComplete,inputMode,ref) go toinputAttributes;attributesapplies to the root element of the field. -
Selectrenders a custom dropdown withSelect.Optionchildren and a native<select>with<option>children. Give a customSelectaplaceholderor an initial value, and label it withFormControl.Label–inputAttributesgo to its hidden input, not to the trigger. -
Autocompleteis a controlled text field with suggestions: keepvaluein state, update it inonChange(called for typing and for selecting an item) and render only theAutocomplete.Items matching it – items are not filtered for you. -
NumberFieldrequiresincreaseAriaLabelanddecreaseAriaLabel. -
With React Hook Form, use
Controllerand adapt the handler:onChange={({ event }) => field.onChange(event)}.
Overlays
-
Popover,DropdownMenuandTooltippass trigger attributes through a render function. Always spread them onto the trigger via itsattributesprop:<DropdownMenu> <DropdownMenu.Trigger> {(attributes) => <Button attributes={attributes}>Options</Button>} </DropdownMenu.Trigger> <DropdownMenu.Content> <DropdownMenu.Item onClick={handleEdit}>Edit</DropdownMenu.Item> </DropdownMenu.Content> </DropdownMenu> <Tooltip text="Copy link"> {(attributes) => <Button icon={LinkIcon} attributes={{ ...attributes, "aria-label": "Copy link" }} />} </Tooltip> -
Modalis controlled: passactiveandonClose. Keep it mounted and toggleactiveinstead of rendering it conditionally, otherwise its close animation doesn't run.useToggle()returns{ active, activate, deactivate, toggle }for this. UseModal.TitleandModal.Subtitleso the dialog is labelled for screen readers. -
Popover,DropdownMenuandTooltipmanage their own state. Passingactivemakes them controlled – they then only open and close when you update it inonOpen/onClose. To keep one from opening, passdisabledinstead ofactive={false}. -
Tooltipdescribes its trigger only while it's shown and doesn't open on touch, so it doesn't replace anaria-labeland shouldn't hold information that isn't available elsewhere. With an emptytextit renders just the trigger, so conditional tooltips don't need branching. -
Pressing a
DropdownMenu.Itemcloses the menu.ContextMenuhas no trigger: everything rendered inside it exceptContextMenu.Contentis the right-click area. -
Toasts are shown imperatively:
const toast = useToast(); const id = toast.show({ title, text, icon, color, actionsSlot }); toast.hide(id);. There's no<Toast>component to render. Toasts hide after a timeout; passtimeout: 0together with an action that callshidefor the ones that should stay. -
Overlays render in a portal and manage focus trapping, scroll locking and z-index themselves. Don't set
z-indexon them.
Choosing a component
| Need | Use |
|---|---|
| Pick one option from a list | Select; RadioGroup when all options should stay visible; ToggleButtonGroup or Tabs with variant="pills" for a compact switcher |
| Pick an option by typing | Autocomplete |
| Menu of actions on a button | DropdownMenu; ContextMenu for right click |
| Arbitrary floating content | Popover; Tooltip for a short text hint on hover or focus |
| Blocking dialog, drawer, bottom sheet | Modal with position |
| Feedback after an action | toast via useToast; Alert for a persistent message inside the page |
| Boolean setting | Switch when it applies immediately, Checkbox inside a submitted form |
| Navigation between views | Tabs (pass value or defaultValue, nothing is selected otherwise; items accept href; inactive panels are unmounted), Breadcrumbs, Pagination |
| List row or navigation item | MenuItem |
| Surface for grouped content | Card (padding of 4 units by default, padding={0} for edge-to-edge media or tables; onClick or href makes it clickable) |
| Show/hide a section | Accordion |
| Loading | Skeleton for content placeholders, Loader for spinners, Button loading for pending actions |
| Status label or counter | Badge (Badge.Container to attach it to another element) |
Customizing components
- Every component accepts
classNameandattributesfor its root element.attributestakes any HTML attribute,data-*andaria-*attribute,styleandref. Some components expose the same for inner elements (inputAttributes,contentAttributes, …). - Using
classNameorattributes(includingstyle) to override the existing styles of a component is not recommended. Component styles are internal: their class names are hashed and their markup can change between releases, so overrides break without warning. Change how a component looks through its props and by composing components instead – for example, build a custom card fromViewinstead of restylingCard, or put custom content into a slot instead of restyling what's already rendered there. classNameandattributesare meant for what the props don't cover and what doesn't conflict with the component styles: positioning the component in your own layout,data-*andaria-*attributes, ids, refs and event handlers.- A custom look for a group of components (e.g. a branded button) is done with a scoped theme:
<Theme name="…">. - Build custom components from
View,Text,Actionableand tokens so they pick up theming, dark mode and RTL for free.
Common mistakes
<div style={{ display: "flex", gap: 16 }}>→<View direction="row" gap={4}>.gap={16}meaning 16px →gap={4}.- Expecting
Viewto be a row by default → it's a column. - Hex colors,
rgb()or Tailwind color classes → color props and--rs-color-*tokens. <h2>/<p>with custom font styles →<Text as="h2" variant="featured-2">.onChange={(e) => setValue(e.target.value)}→onChange={({ value }) => setValue(value)}.{open && <Modal>}→<Modal active={open} onClose={…}>.- Forgetting to pass the trigger
attributesinPopover/DropdownMenu/Tooltip– the overlay never opens. <Button icon={<PlusIcon />}>works, buticon={PlusIcon}is the convention; an icon-only button withoutaria-labelis inaccessible.
MCP servers 1
Sponsors
Details
- Marketplace
- reshaped-ui/reshaped
- Source
- plugins/reshaped
- Category
- Community