What you can do
You already have a workspace from Getting Started. Picture Maya's homepage hero sitting in Production. A Default Widget is already there. This page is how she opens it — and how she creates the next piece of content.
Two everyday jobs:
- Open the Production Default Widget and start composing. After Get Started you land in Production. The Default Widget is an empty canvas. Open it, drop in the hero, and you are building.
- Create a new widget in Development for the next campaign. The spring-sale takeover should not overwrite the everyday hero. Switch to Development, create a widget, compose it there, then promote when it is ready.
A widget is the content. A ruleset later chooses which published widget a visitor sees. This page gets you the widgets.
An agent can create that Development draft, rename it, save its CSS settings, and publish it after you connect MCP. The steps are on Widgets from an agent.
How a widget thinks
One widget lives in one environment. The composer edits the draft in that environment. Nothing a visitor's site fetches changes until you publish.
Promote and publish are different buttons. Promote to Staging copies the draft into Staging. Promote to Production copies the draft into Production. Publishing creates an immutable snapshot with a published key — that is what a Staging or Production token fetches. See Publishing for the snapshot workflow.
Copy To is not the pipeline. It is only for extra environments you named yourself — a sandbox that is not Staging or Production. The Projects guide already draws that line.
Here is the case that surprises people. You switch to Development looking for the Default Widget and the list is empty. That is expected. Get Started — and every extra team — creates the Default Widget in Production, the environment you land in. Staging and Development start empty of widgets until you create one or promote a draft into them.
You need a Widget Access group — View, Manage, or Admin — for that environment, or a RuleCMS admin account. View can open the list. Manage is enough to create and compose. The dashboard has no way to delete a widget, so Admin adds nothing you can use beyond Manage. Staging and Production have their own Widget Access groups when you want to split who can edit there.
Promoting is a separate grant. Promote to Staging needs the Post Promote To Staging group. Promote to Production needs Post Promote To Production. Both sit under Utility Functions on the team's User Groups page. No Widget Access group includes them, not even Admin — without the group, the button does not show. You also need access to the environment you promote into: View Project Environment Staging or View Project Environment Production. Publishing has its own groups too — see Publishing.
Open or create your first widget
You do this on an environment page — the same place you open Collections and Widget Selection Rulesets. After Get Started you are already in Production. That is a good place to open the Default Widget. Switch to Development when you want a new campaign draft.
- Open the organization → team → project → environment you want to work in.
- Find the orange Widgets card. It offers View Widgets and Add.
- To open the Default Widget (Production): click View Widgets, then the Default Widget row. You land on the management page. Click Edit Widget to open the composer.
- To create a new widget: click Add on that card, or Add Widget on the list. You land on Create New Widget. Widget Name is optional — leave it blank and RuleCMS assigns one. Submit Create Widget. You land in the composer.
- For the spring-sale story, switch the environment to Development first — use the switcher under the project name — then Add. Development is empty after Get Started. That is the right place for a campaign you are not ready to ship.
That is a safe stop. You are composing. The new widget received a snapshot of the project CSS catalog — tokens, classes, fonts, and the rest. After that the widget owns the copy. Come back to the management page when you need a lever below.
When you reach for it
The first path above is open or create. These are the other levers on the widget management page, named as jobs.
| What you need | When you reach for it |
|---|---|
| Rename | The display name no longer matches the slot — “Homepage hero” instead of a generated name. Opens the rename form from the management header. |
| Promote to Staging / Promote to Production | The draft is ready for the next environment. Promote copies the draft. It does not publish. On Development you see Promote to Staging. On Staging you see Promote to Production. The button only shows if you are in the matching Post Promote group. |
| Copy To ▼ | You named an extra environment and want a fork there. Copy To lists those extras only — not Staging or Production. Use promote for the pipeline. Make a Copy duplicates inside the same environment. |
| CSS Settings | Tokens, classes, fonts, and the rest on this widget. The header button opens the hub: View All CSS is the read-only stack in a full-page dialog. Generate Tailwind CSS compiles the class names this widget already uses — see Generate Tailwind CSS. Sync from Project pulls later project updates onto this widget (one type or all nine); entries that exist only here are kept. Start with widget CSS Variables. The other catalogs sit under Widgets in the sidebar. |
| CSS Settings tab | A read-only view of every catalog on this widget — the same previews as the View pages. Generate, sync, and edit stay on the hub. The active published widget page and each historic published version have a CSS Settings tab too. |
| Compare versions | Diff the draft against a published snapshot, or two published versions side by side. Switch between Visual, JSON, and CSS Settings. |
| Edit JSON | Raw configuration. On the management page, or from the composer Go To menu. Invalid JSON shows a validation message when you save. |
| Publish | Staging and Production only. Creates the snapshot a token fetches. Development shows Integrate instead — preview the live draft with a dev. token. The full snapshot workflow is Publishing. |
| Collections | Drop a shared or embedded collection from the composer palette. Shared updates everywhere it is referenced; embedded is tied to this widget. See Collections. |
What to read next
This page is the story and the first walkthrough. The composer, the snapshot, and each CSS catalog live on the pages below.
- The Composer — Palette, layout, Widget Settings, and the Modify drawer. That is where you build after you land from Create Widget or Edit Widget.
- Overlay Layers — Content that has to sit on top of the widget — a badge on a photo, a caption on a hero.
- Ask AI — The same composer operations in ordinary language.
- widget CSS Variables — This widget's token catalog. The other widget catalogs — classes, fonts, themes, and the rest — are siblings in the sidebar.
- Generate Tailwind CSS — Compile the class names this widget already uses into CSS it owns.
- Collections — Shared versus embedded blocks you drop into a widget.
- Publishing — How a draft becomes the snapshot a Staging or Production token fetches.
- Widget Selection Rulesets — Choose which published widget a visitor sees.
- Projects, Environments & Tokens — The pipeline,
dev.tokens, and project CSS as the template for the next widget.
How this fits
A widget is the content. A ruleset chooses which one. Publishing is how the site gets a key. Tokens live on Projects, Environments & Tokens.
Open the Default Widget in Production. When the next campaign needs its own layout, create that widget in Development, promote the draft, then publish.