Save your first project
When your design is worth keeping, sign in and choose Save in the editor header. The project needs at least one layer or folder; an empty canvas cannot be saved.
After a successful save, the editor shows Gradient saved! and updates the URL
to /editor/ followed by the project's ID. Update replaces Save for your
saved project. Keep that URL or open Details View for a presentation link.
Editing automatically backs up a local draft, but does not save online. Choose Save or Update to publish your changes. An amber dot on Save, Update, or Fork means the current artwork has unsaved changes.
Recover unsaved work
The editor keeps a draft in this browser's local storage, including layers,
folders, clones, variables, project settings, and valid in-progress path edits.
This works without signing in. Reopen /editor to resume a new project, or
reopen an existing project's editor URL to resume its draft. Drafts are kept
separately so opening a different project does not replace another's work.
Undoing back to the last saved version clears the unsaved indicator. Saving successfully also clears it, unless you made more edits while the request was running. A failed save leaves both your changes and their indicator in place. Construction guide layers are restored with the draft. Undo history, selection, and zoom are not restored.
Local drafts stay in this browser, not your account, and are not a substitute for Save, Update, or Export as JSON. Clearing site data removes them; private browsing or full/blocked storage can prevent recovery. If a backup fails, the editor shows a warning: keep the tab open and save or export before leaving.
Discard unsaved changes
Open Project actions beside Save or Update. When you have unsaved changes, choose Discard changes for a new project, or Revert to saved for an existing project. Confirm to remove that project's local draft and clear its undo history. Cancel leaves your work untouched.
Discard changes leaves a blank new project. Revert to saved restores the last saved version without changing its URL or writing anything online. Discarded changes cannot be recovered with Undo.
Update your project
Open a project you own while signed in to see Update. Make your changes, then choose Update to save them to the same project URL. This includes layer edits, variables, and project metadata. Clone links and each reference's independent placement are saved too. Reopening the project restores the links rather than turning the references into unrelated copies.
Wait for success feedback. If the editor reports an error, keep the page open, resolve the problem, and retry rather than assuming the save completed. Command+S on Mac or Ctrl+S elsewhere runs Save or Update when available.
Fork a project
Fork creates a separate project you own, leaving the source unchanged. Use it to build on someone else's design or preserve an alternate version of your own. You need to be signed in.
In the editor, Fork saves the current layers, document settings, and variables to a new project and changes the URL to that copy. The new version retains a connection to its original project. Future Update actions affect your copy. Clones remain linked within the fork, but no live clone source is shared between projects. Editing a clone in your fork doesn't update the source project.
Unlike Update, Fork is available for existing projects you don't own. You can experiment with their layers in the editor, then Fork when you want to keep your version.
Preview values and forks
The Customize controls in Details View are a temporary preview. Its Fork action uses the saved source data, not the values you just tried there.
To preserve a customized variation, choose Open in Editor, set the desired values in Variables, and Fork from the editor. If you already forked in Details View, open your copy, make those changes, and Update it. See Customize a preview for resetting and validating exposed values.
Export images and HTML
Open Project actions (the arrow beside Save, Update, or Fork) and choose Export. Pick PNG, JPG, WebP, SVG, HTML with CSS, or an editable JSON project. No sign-in is required. On a project's details page, the Export button opens the same dialog. Exports include the current customized preview values without changing the saved project.
Set the document width and height in pixels. Image and HTML exports scale the complete artwork to that size without changing the open project. Turn on Lock aspect ratio to keep the current width-to-height ratio when editing either dimension; linked dimensions are rounded to whole pixels. To restore the document's original aspect ratio at your current export size, choose Restore aspect ratio. The width stays unchanged, the height adjusts, and the original ratio is locked for further edits. The limit is 8192 pixels per side and 32 megapixels. PNG and WebP retain transparency; JPG uses a white background. HTML includes its CSS and fonts in one downloadable file. For HTML, CSS units selects Pixels (px) for the chosen fixed export size or Percentages (%) for a responsive layout that fills its container. Percentage HTML does not use the document-size or aspect-ratio controls.
For PNG, set PNG compression from 0 (uncompressed) to 9 (highest compression). PNG stays lossless at every level; stronger compression trades export time for smaller files without changing pixels or dimensions. For JPG and WebP, set JPG quality or WebP quality from 1% to 100%; higher values preserve more detail and produce larger files. WebP requires browser encoding support; if it is unavailable, the dialog reports an error instead of downloading a different format.
SVG preserves shapes, text, linear and radial gradients, repeating linear and radial gradients, clipping masks, background blends, rounded corners, and solid or double borders as native SVG. Blur, color adjustments, and outer and inset shadows use SVG filters and vector geometry rather than embedded screenshots. These remain scalable and editable, although SVG viewers can render blur and antialiased edges slightly differently from CSS.
SVG files contain one root <svg> element, with no nested SVG elements.
Nested artwork viewports become transformed groups with explicit clipping,
preserving their placement, aspect ratios, and mask geometry.
Non-repeating shapes and text paint directly rather than through pattern-filled
rectangles. Layer tiling uses <pattern> only when horizontal or vertical
repetition is enabled; procedural pattern layers also use it for their repeating
motifs. Export removes unused definitions and redundant groups and attributes,
while keeping groups required for clipping, masks, filters, opacity, and blending.
Opaque, unstroked parts of a custom shape are combined into one compound path
so SVG editors can import them as a single shape. Opaque path-based clipping
masks, including those applied to folders, export as flattened <clipPath>
geometry for compatibility with editors such as Photopea. Masks with transparency,
strokes, or effects retain their native SVG mask representation.
Repeating radial gradients use <radialGradient spreadMethod="repeat"> rather
than embedded images. Some SVG viewers, including WebKit-based viewers, do not
render radial repeats correctly; the export keeps the native SVG representation.
Effects without a supported native SVG conversion, including conic gradients, still use embedded images for the affected paint only; surrounding shapes and supported effects remain vector. Unsupported border styles or masks may require an image of the affected layer. Backdrop filters still require an image of the complete composition because they sample the layers behind them.
Turn on Vectorize text to convert native text to paths instead of embedding its font. Paths do not require installed fonts, but their text is no longer editable. Rasterized effects remain images.
Export an editable JSON file
Open Project actions (the arrow beside Save, Update, or Fork) and choose
Export, then select JSON project and click Export.
This downloads your current design, including unsaved edits,
as a .gradient-art.json file. You do not need to sign in.
Unlike generated CSS, HTML, or an image, this file keeps editable layers, folders, clone links and placement, variables and formulas, and project settings. It does not include ownership, comments, statistics, or editor controls such as zoom, selection, and undo history. Construction guide layers are included. Export finishes an active path draft first; if that draft cannot be finished, correct it before retrying.
The project must contain at least one layer or folder. Files are limited to 4 MiB, including their JSON formatting. Keep the download somewhere safe: exporting does not save or update the project online. Changing dimensions in this dialog changes only the exported copy's document size, not its layer geometry. A resized dimension no longer uses its variable binding; unchanged dimensions keep their bindings.
Import an editable JSON file
Choose Import JSON in Project actions, then select a GradientArt JSON file. The editor validates it before changing your work. If you already have content, it asks for confirmation; Cancel keeps your current project. Save or export any unsaved changes before confirming.
Import opens the file as a new unsaved project at /editor, even when you
started from a saved project. It never overwrites the original online project.
Selection, undo history, and zoom reset; construction guide layers are restored.
Choose Save afterward to create
a new online copy (sign-in required), or Export as JSON to keep a local copy.
Invalid JSON, unsupported versions, oversized files, and invalid design data show an error without replacing your project. Correct the file and select it again. Empty projects cannot be imported; a project containing an empty folder is allowed.
Generate designs with an AI agent
Give your agent the authoring guide, the modular version-1 schema, and an example: a simple gradient or clones with variables. Agents with HTTP tools can submit the generated file to the design preparation API and return an Open in editor link. Every design uses a temporary token, regardless of size. Open that link to load the design as a new unsaved project; confirm replacement if you already have work in the editor. No sign-in is required and the original saved project is not overwritten.
Links expire after one hour. Before expiry, anyone with the link can open the original generated design more than once. If it expires, ask the agent for a new link. Receiving the design clears the token from the address bar, so save or export your work for a durable copy. The editor can restore its local draft after reloading. Expiry does not erase a design already open in your editor, but it does not save that design online either.
The API temporarily stores the design; it does not create a permanent project. Save remains an explicit user action. Treat the link as private and do not include sensitive information in generated designs.
Agents without HTTP tools can provide a JSON file for Import JSON instead. The self-contained schema is also available for offline validation. The format reference explains units, bindings, clone relationships, validation, and versioning.
The schema covers structure; the API and import also check relationships, formulas, and design limits. Discover the API through llms.txt and its OpenAPI definition. No AI plugin is required; your agent generates the artwork, while GradientArt validates and opens it.
Export cloned artwork
The editor's Code panel and the Code tab in Details View generate code for the artwork. Clones reuse shared CSS artwork values and SVG source definitions rather than embedding the same artwork separately for every reference. Each reference still gets its own placement. In the editor, Code shows the active layer or folder; clear the selection for the entire project. The Code tab in Details View always shows the entire project.
The export doesn't need JavaScript to preserve that reuse. Folder wrappers and placement or clipping styles can repeat because each occurrence needs its own place in the composition. Keep the generated HTML, CSS, and SVG definitions together; a reference without its shared definition cannot draw the artwork. Live variable and formula bindings remain in the exported code.
Generated CSS classes use layer and folder names: Gradient Layer becomes
.gradient-layer. Collisions receive numeric suffixes such as
.gradient-layer-2, including repeated clone occurrences, without renaming
anything in the editor. Names are normalized into CSS-safe identifiers; empty
or punctuation-only names use layer. Gradients combined into one background
keep a single element named after their folder, or after the first visible
layer in an internal paint group. The top-level artwork uses #root directly,
without an extra artwork wrapper. It owns the dimensions, variables, clipping,
blend isolation, and any shared root background.
Details View
Choose Details View from a saved project's header. This opens /view/ plus
its ID: the page for looking at the finished artwork, sharing its URL, and
understanding how it was made.
The page includes a preview, a Code tab, author and project information, description, tags, colors, layers, and comments. Templates also show Customize controls. Open in Editor takes you back to the editing workspace.
Details View loads the saved version. Unsaved editor changes will not appear there just because you opened it in another tab.
Full Screen View
Full Screen View opens /embed/ plus the saved project ID. It shows the
artwork alone by default, without editor controls. Use the embedding options
below to include the project title, creator credit, or GradientArt symbol.
It is a separate presentation route, not a command that resizes your canvas
or necessarily enters the browser's full-screen mode.
Use Details View when sharing context and customization controls. Use Full Screen View when the artwork itself should have the stage. Both reflect the saved project, so Update first if you want them to show your latest changes.
Organize projects into collections
Open your profile and choose Collections, then Create collection. Give it a name (up to 100 characters) and an optional description (up to 300). Collections are public, and can include any artist's public projects.
On a project's Details View, choose Add to collection. Sign in if needed, then check one or more of your collections and choose Save. Existing memberships are already checked; uncheck one to remove the project from that collection. Cancel leaves membership unchanged. If saving fails, keep the dialog open and retry; some changes may already have reached the server.
Your profile's Collections tab shows a preview of up to four projects per collection. Open a collection to browse its projects and share its URL. Collections appear newest first; their projects appear most recently updated first, using the creation date if no update date is available. Both profile tabs show skeleton previews while loading and load 24 items at a time as you scroll, just like Explore. You can also use Load more projects or Load more collections. Inside a collection, use Load more to browse additional projects.
Explore keeps Featured, Latest, and Templates as its built-in views. Its other tabs are the site's curated collections, shared with everyone, rather than automatic tag categories or each visitor's personal collections. These views show the projects saved in each collection, including forks, in most recently updated order. The curator manages their names and contents from their profile; changes appear when Explore is opened or refreshed. Collection links use stable IDs, so renaming a collection does not break its link.
Use the Filters bar on a collection page or either profile tab to search and filter by tags, templates, color, and layer count, just like Explore. On the Collections tab, project filters show collections with at least one project matching all selected criteria. Text search also matches collection names and descriptions, including empty collections. Tiles still preview the collection as a whole. Filters stay in the URL and carry over when switching between a profile's Projects and Collections tabs; Clear filters resets them without leaving the current tab.
On a collection you own, Edit collection changes its name and description. Delete collection asks for confirmation and removes only the collection, not its projects. Deleting a project removes it from collections too.
Embed on another website
Open a saved project's Details View, choose Embed project in the actions below its details, choose what to show, then choose Copy. Paste the HTML into your website's HTML editor or custom HTML block. Your site must allow iframes. If copying is blocked by your browser, select the code and copy it manually.
For example, this embeds the Carbon Fiber project:
<iframe
src="https://gra.dient.art/embed/lhk0fierr8"
title="Carbon Fiber | GradientArt"
width="500"
height="500"
style="border: 0; max-width: 100%; aspect-ratio: 500 / 500; height: auto;"
loading="lazy"
></iframe>
The generated dimensions use your saved canvas size, including its default
variable bindings. The snippet shrinks to fit narrow containers while keeping
that aspect ratio. You can change its width and height; if you change its shape,
adjust aspect-ratio too. The artwork fills the frame, so a different aspect
ratio can crop its edges.
The title links to Details View, the creator's avatar and name link to their profile, and the logo links to GradientArt. These links open in a new tab so visitors don't lose their place on your website.
Choose what appears
In Embed project, use the Project name, User name, Avatar, and Logo toggles to show or hide each element independently. All four are off by default. The HTML updates immediately; copy it again after changing an option. These settings belong to that embed URL, not the saved project or other embeds.
The tool opens in Preview, showing the saved artwork with your selected visibility options and the same aspect ratio as the generated embed. Switch to Code to inspect or manually copy the HTML, and back to Preview to see your changes. Preview, Code, and Copy share a row below the content. Copy is available in either view.
You can also set the options directly in the iframe's src URL:
projectName=true: Show the project title at the top left.userName=true: Show the creator's name at the bottom left.avatar=true: Show the creator's avatar at the bottom left.logo=true: Show the GradientArt symbol at the bottom right.
Omit a parameter to hide its element. Only a single value of true shows it;
unrecognized or repeated values leave it hidden.
For example, /embed/lhk0fierr8?userName=true&logo=true shows the user name and
logo while keeping the title and avatar hidden. In HTML attributes, write & as &,
as the generated snippet does.
Hiding both the name and avatar removes the profile link. Hiding the name, avatar, and logo also removes the bottom overlay. Turn all four off for artwork alone. An avatar shown without a name still links to the creator's profile. These are display options, not privacy settings: the project and creator remain public.
Embeds are public and don't require visitors to sign in. They show the saved project, not unsaved editor changes or temporary Customize preview values. Choose Update in the editor to publish changes; they appear the next time the embedded page is loaded or refreshed. Deleting the project makes its embed unavailable. Unlike downloading HTML, an embed needs a connection to GradientArt.
The iframe first shows a lightweight loading screen, then fetches the saved
project. Its GradientArt logo with a subtle animated glow is included in the initial HTML and works
before JavaScript loads. It can appear as soon as the HTML, styles, and logo
image arrive, but cannot
cover the initial network connection or server response time. With
loading="lazy", the browser may also wait until the iframe is near the viewport
before loading it. The artwork itself requires JavaScript.
If loading fails, the embed shows an error and a Try again button instead of spinning indefinitely. Missing or deleted projects show an unavailable message.
Project settings
Open Project actions (the arrow beside Save, Update, or Fork) in the editor header and choose Settings. It is available for a new project or a saved project you own. If you're working from someone else's design, Fork it before editing its project settings.
Changes apply immediately in the editor. Done closes the dialog; it does not save to the server. Use Save or Update afterward.
Project name, description, and tags
Edit the project name in the header, not in Settings. Keep it descriptive enough to recognize later; names can be up to 100 characters.
Settings contains Description (up to 300 characters) and Tags (up to five, 25 characters each). A short description can explain the visual idea or what a template's controls are good for. Tags help describe the design's subject or style.
These belong to the project. Your profile and sign-in preferences live in account settings instead.
Canvas size
Set Width and Height in pixels, each at least 1. These are the actual
artwork dimensions, not the size of your browser window.
Changing canvas size changes the area available to the composition; it doesn't automatically scale every layer proportionally. Check layer sizes, offsets, and repeat after resizing. A variable or formula can connect the dimensions to related layer properties when you want them to respond together.
Use the link button beside either dimension to bind a compatible Number, Function, or input formula. To make the canvas merely look larger while working, use zoom instead.
Start a new project
Choose New project in the header to start from a blank design. When the current project contains work, the editor asks for confirmation. For a new, never-saved project, confirming discards its work and local draft. Cancel preserves both.
For an existing project, New project keeps its unsaved changes in local storage. Reopen that project's editor URL to continue where you left off. Use Revert to saved to explicitly discard those changes instead. Starting fresh replaces any separate new-project draft with a blank canvas, but never deletes a project saved online.
