Create your own design for your widgets

#What is a design in Widgetry?

A design is a custom theme for your MCP Apps widgets: a set of --wg-* design tokens (colors, type, shape, effects) plus optional CSS. In Widgetry, design and widget type are separate. The type (board, table, bar chart, 3D globe) sets the structure, and the design sets the skin. Widget styles read only the tokens, so any type can wear any design and a brand design applies to all your widgets in one step. You can make one in the designer at Designs, or let an AI agent do it through Widgetry's MCP tools.

This guide covers the Widgetry side. For how hosts such as Claude and ChatGPT pass their theme and CSS variables to a widget, read theming MCP Apps.

#Which tokens can a design set?

A design can set 30 tokens, in the same seven groups as the designer, with the designer's labels in parentheses.

Any token a design leaves unset falls back to the host: text to the chat's text color, cards to its background, fonts to its font.

#The twenty built-in designs

Widgetry ships twenty designs you can use as they are or as a base:

• The house design, Widgetry: black outline, butter yellow, a marker swipe under the title.
• Five classics: Nordic, Aurora, Brutalist, Editorial and Neon.
• Fourteen inspired by well-known brands: Claude, Google, Microsoft, Apple, GitHub, Vercel, Supabase, Stripe, Linear, Notion, Figma, Spotify, Airbnb and Shopify. They take colors, radii, weights and type character, never logos.

Thirteen follow the chat's light or dark theme: Widgetry, Nordic, Editorial, Apple, Claude, Figma, GitHub, Google, Microsoft, Notion, Stripe, Supabase and Vercel. Nordic goes furthest and takes its text and surface colors straight from the host. The other seven commit to one scheme: Aurora, Neon, Linear and Spotify are always dark, and Brutalist, Airbnb and Shopify are always light.

#How to create your own design in the designer

Owners and editors of an organization can create, edit and delete designs. Viewers can only look.

1. Open Designs in the top bar. Your designs are under Yours, the twenty under Built-in. The Show the designs on bar switches the sample widget every card is drawn on.
2. Pick a base and duplicate it. Click Duplicate on a built-in card, or open one and click Duplicate to edit. The copy is called "My Stripe" (or whatever the base was) and the designer opens.
3. Name it in the field at the top. The design's key, which widgets store, is set from the first name and stays the same when you rename.
4. Change tokens. The panel says what the design is based on: anything you don't change comes from the base, and your own values show in bold. Inherited values show greyed out in each control, and the reset arrow next to a value of your own drops it back to the inherited one. Colors take a picker or any CSS color you type; lengths are sliders; fonts, shadow and heading case are menus.
5. Switch between Light chat and Dark chat above the controls (see the next section).
6. Add Advanced CSS if tokens are not enough.
7. Check the preview. The right side draws your design on six types at once (Metrics, Board, Area chart, Weather, Progress rings and Aurora card), in the theme you selected.

There is no save button. The designer saves about half a second after each change, and the header says Saved, Unsaved, Saving or Not saved.

#What you inherit from the base

A copy keeps everything about its base that you don't override: its token values, its canvas CSS (Aurora's drifting glow, Neon's scan lines, the house design's marker swipe) and its per-type touches. The five classics have small refinements in each widget type's own styles, written for that design; your copy keeps them because each widget still identifies the base design to its own styles. The house design and the brand-inspired ones work through tokens only. Duplicating one of your own designs copies its overrides, its CSS and its base.

#Light chat and dark chat values

Light chat values are the general ones: they also apply when the chat is dark, unless you change them under Dark chat, which holds values used only in a dark chat. One catch: if the base has its own night value for a token, that night value still wins in a dark chat. Stripe, for example, sets a lighter accent for dark, so a light-only accent change shows up in light chats only. With a base that has a night version, set your brand colors under Dark chat too, and check the preview in that mode.

#Advanced CSS

The Advanced CSS box is added after the tokens, for animated backgrounds, textures or anything tokens cannot express. It is part of the design, so it reaches only the widgets that wear it, and you can fine-tune one type through its classes. Two rules: it can be up to 50,000 characters, and the widget's own styles load after it, so a widget rule of the same specificity wins. A token value itself cannot contain ;, {, } or <.

/* A paper grain on the canvas, behind every widget that wears the design. */
html { background-image: radial-gradient(rgb(0 0 0 / .04) 1px, transparent 1px); background-size: 4px 4px; }

#Apply a design to a widget

Every widget has one design. In the widget editor, the Widget design row above the preview lists every built-in design and yours; click one to switch, and use Light and Dark to see it in both chat themes. The link next to it opens the current design (Edit this design for yours, View or duplicate this design for a built-in one). New widgets start in Nordic unless you or your agent choose another.

#What happens when you edit or delete a design

Widgets store a reference to their design, not a copy. When you edit a design, every widget that wears it changes: the tools on Widgetry's /mcp serve the new version on the next request, and an MCP server that links a published widget picks it up the next time it reads it (the linking code keeps a copy for a minute). Downloaded files are a snapshot: download them again to take the change.

You can delete a design of your own with Delete in the designer, but only when no widget wears it, drafts included. Otherwise Widgetry refuses and says how many widgets use it; switch their design first. Built-in designs cannot be deleted.

#How to make a brand design that works

• Check contrast in both themes. Text on cards, secondary text on insets, and --wg-on-accent on --wg-accent. A brand color that works as an accent on white often fails on a dark card. Claude asks for WCAG AA contrast at minimum.
• Keep the five series apart. Bar, area and donut charts and progress rings color their series with --wg-c1 to --wg-c5. Use your brand color for Series 1, then vary lightness as well as hue so the series stay distinguishable for color-blind readers, and keep --wg-positive and --wg-negative distinct from them.
• Use system fonts. The font menus offer ten system stacks (System sans, Helvetica, Geometric, Heavy, Book serif, Didone, Georgia, Rounded, Monospace, Typewriter), and each renders with what the viewer's device has. Hosts block any origin a widget's resource doesn't declare in its CSP, and a design has no way to declare a font origin, so a web font loaded from Advanced CSS will not reach the chat. See the MCP Apps CSP guide. Leaving Body inherited on a base that doesn't set it, like Nordic, uses the chat's own font.
• Keep shape consistent. One radius for cards and a smaller one for chips and bars, one line width, one shadow.
• Test on demanding types. The designer previews six. Open a widget of the other types in the editor, pick your design and switch Light and Dark: a table and a bar chart for dense data, lines and series, a 3D globe and a 3D carousel for canvas and surface colors drawn by script.

#Create a design through your agent

With an editor or owner credential, an agent connected to Widgetry's MCP has the same design tools you have on the web. Set it up with connect Widgetry to your agent.

• widgetry_list_designs lists the built-in designs and yours.
• widgetry_get_design reads one design's light and dark tokens and CSS, and lists every token a design can set.
• widgetry_create_design creates a design from any other (from), optionally with tokens, darkTokens, css and a summary.
• widgetry_update_design changes a design of yours. tokens and darkTokens each replace the whole set of overrides, so send every override you want to keep.
• widgetry_delete_design deletes one that no widget wears.

A widget wears a design through its design field, which widgetry_update_widget sets. Try a prompt like this, with an invented brand:

Create a design for Larkspur Tea from our brand colors: deep green #1f4d3a, amber #e8b04b and cream #f7f3ea. It has to work in light and dark chats. Then apply it to the sales board.

The agent reads a base with widgetry_get_design, then calls widgetry_create_design with arguments like these:

{
  "name": "Larkspur",
  "from": "nordic",
  "summary": "Larkspur Tea: cream canvas, deep green ink and amber highlights.",
  "tokens": {
    "--wg-bg": "#f7f3ea",
    "--wg-surface": "#fffdf8",
    "--wg-ink": "#1d2b24",
    "--wg-accent": "#1f4d3a",
    "--wg-on-accent": "#ffffff",
    "--wg-c1": "#1f4d3a", "--wg-c2": "#e8b04b", "--wg-c3": "#7a9e8a", "--wg-c4": "#b5523b", "--wg-c5": "#4a6b8a",
    "--wg-radius": "10px"
  },
  "darkTokens": {
    "--wg-bg": "#121a16",
    "--wg-surface": "#1a2620",
    "--wg-ink": "#f1ede4",
    "--wg-accent": "#e8b04b",
    "--wg-on-accent": "#1d2b24",
    "--wg-c1": "#6fbf98", "--wg-c2": "#e8b04b", "--wg-c3": "#a9c7b6", "--wg-c4": "#e08a70", "--wg-c5": "#8fb0d0"
  }
}

The series are set again under darkTokens because Nordic has its own night palette, which would otherwise win in a dark chat. Then the agent finds the sales board with widgetry_list_widgets and calls widgetry_update_widget with its slug and "design": "larkspur". If the widget is published, the change is live on the next request. Open the design in Designs to check it on the preview and adjust any token by hand. To let an agent build the whole widget too, see let your AI agent build MCP Apps widgets.