Restyle Sites restyling
Use the Experience Modernization Agent to apply a design during migration or change the appearance of an existing Edge Delivery Services project. Faithfully copying a source site’s appearance and deliberately replacing it with a new design are different requests. State which you want.
Appearance lives in the project’s code: global CSS sets the look of default content, and each block has its own CSS and JavaScript. Together they can give the same semantic content any design without restructuring it, because the JavaScript can rebuild the markup in the browser; see How Your Site Is Built and Updated. A purely visual restyle therefore changes code in Git and leaves authored content alone.
This guide is for the person who leads a restyle. If you are a designer making individual visual changes that a developer reviews, start with Make Visual Changes.
Agree What Changes and What Stays prepare
Connect the project and confirm permission to modify it. Save a baseline code revision and preserve affected content before changes.
Provide:
- Content source: Existing pages whose text, images, links, metadata, and meaning must be preserved, or approved new content.
- Design reference: A specific Figma component or frame, an authorized reference website, a screenshot, or a design specification. Name its version and the desktop and mobile states that matter.
- Scope: Global tokens (CSS custom properties for colors, typography, and spacing) and default content, selected blocks, a page, or the whole site.
- What must not change: Content, URLs, authoring models, accessibility behavior, and integrations.
- Output: Content that authors can edit, in the storage option that your project uses, or a static design prototype if that is all you need.
Screenshots and reference sites can leave interactions and responsive rules unspecified. Settle those on one sample page before you apply them to the whole site.
References, Prototypes, and Delivery design-output
The agent supports design work from source sites, Figma, and supplied references. Figma import and guided redesign are optional capabilities that it offers to turn on for your project when a request needs them. They have different inputs and outputs; do not assume that they work the same way.
- For one Figma block, provide its component or node link. For a new page, provide a specific frame rather than an entire file.
- Figma import needs a Figma access token and permission to read the file. See Work from a Figma Design.
- A static HTML design preview shows the new design on copies of your pages, which helps you choose a direction. Authors can’t edit those copies; they aren’t the site’s documents or Experience Manager pages.
- If authors must edit the result, ask for site content and block models in the storage option that your project uses, then check them as described for document-based content or Experience Manager authoring.
Guided Redesign guided-redesign
Guided redesign takes a site, or a set of its pages, to a new design in stages. It is provided by the Stardust add-on, stardust@excat-extended. The agent captures the current design, records the direction you want, builds before-and-after prototypes for review, and then turns the approved design into blocks and content. Use it for a redesign across several pages rather than for restyling one page or block. The agent keeps the working files and progress of a redesign in the repository, so you can continue it in a later conversation.
You don’t need to know the stages by name. Describe the result you want, for example “Redesign the home page and the product pages in a lighter, more editorial style”, and the agent proposes the steps. You can also ask for one step directly:
Turning on guided redesign also turns on the design craft add-on, which applies frontend design-quality guidance to each page. Review every stage before you continue, and validate the deployed result as described below.
Restyle During Migration during-migration
Use this path when content comes from an existing website but the target design differs.
- Complete project and migration scoping, including where content is stored.
- Define the target design system: typography, colors, spacing, default content, and reusable blocks. Reuse existing project conventions where they fit.
- For Figma, set up access, then create the blocks or variants that you need from specific component nodes. See Redesign with Blocks from Figma and Create a Block from Figma.
- Migrate a sample page for each template into that block collection. Keep the live site as the content source and Figma or the approved reference as the design source.
- Compare content with the source website and appearance with the target design. Don’t judge the redesigned page against the old site’s appearance.
- Check that authors can edit the result and that it works at each screen width. Correct content mappings or models where needed, then continue in batches.
For example:
Apply the approved design at
https://www.figma.com/design/AbC123/Brand-Refresh?node-id=12-345while migratinghttps://www.example.com/products/tents. The live pages are the content source; the reference defines the new appearance. Preserve text, links, metadata, and meaningful images. Check one sample page first. Create content that authors can edit in Experience Workspace. Do not upload, push, or publish.
Replace the example URLs with your own, and for Experience Manager authoring, say that the content is stored in the JCR.
If a new page has no source website, see Create a New Page from Figma: a specific frame supplies the text and assets as well as the design. This is different from mapping existing website content into a new design.
Restyle an Existing Site existing-site
A new migration is not required.
-
Connect the existing project and intended branch. Ask the agent to read the project’s design conventions, blocks, and authoring models.
-
Identify baseline pages covering the affected templates and variants. Record their current appearance and important interactions.
-
State the scope of the change and what must stay. For example:
Restyle this existing project using the approved design at
https://www.figma.com/design/AbC123/Brand-Refresh. Change global colors and typography and the cards presentation on/and/products. Preserve content, URLs, models, analytics, keyboard behavior, and integrations. Reuse our tokens and blocks. Show the proposed scope first; do not reimport content or upload, push, or publish.Replace the example URL and paths with your own.
-
Update shared tokens and global styles first where the change is global. Apply block-specific styling only where needed.
-
Preview all affected sample pages, not only the page used to derive the design. Include mobile widths, long headings, missing optional content, and different variants. A global token change can affect pages outside the original example, so include those too.
-
If the design requires structural or model changes, make that a separate, explicit decision. Plan how existing content moves to the new structure rather than silently rewriting author content.
-
Review the code diff and project checks, then push and deliver through the existing project’s workflow. Style changes are code: they reach the live site as soon as the branch is merged into
main, so check the affected pages on the branch’s preview URL first. See How Changes Go Live.
Validate and Recover validate
The restyle is done when content remains correct, the approved design works at each screen width, interactions remain usable, and authors can still edit, save, and reopen the sample pages. Check contrast, focus, reading order, image meaning, and the project’s performance requirements. A similarity score doesn’t decide this for you.
If a result is wrong, identify the affected page or block and whether the problem is a token, shared style, block style, structure, or content mapping. Fix that layer and recheck all affected variants. For Figma access errors, check the node link, file permissions, token, and that Figma import is on for the project before you try again.
Revert unwanted code through the project’s Git workflow. Restore any changed remote content separately; a code revert does not undo uploads. Keep the baseline until the restyle is signed off.
Hand over the approved reference and its version, changed files, affected pages, model and content changes, check results, known gaps, and how to recover code and content, using the project handover.