⚠️ Standardizing how WeWeb coded components handle styles

Release date:

August 18, 2026

On August 18, we're releasing a CSS update that standardizes how our components handle styling. This is the groundwork for upcoming updates that improve the SEO and AEO performance of your apps.

Two things to know up front:

Most coded components are not affected.
Your published app keeps working exactly as it does today until you republish it.

Do I need to do anything?

You can check in about 30 seconds. In your WeWeb workspace, open a project, go to the Interface tab, open the Add element menu, and select the Coded components panel.

‍

The panel is empty: You're not affected. Nothing to do.
The panel only shows components generated by WeWeb AI or the WeWeb MCP: You may be affected if the AI forked one of the components we are updating as the basis to create a custom component.
The panel includes components you forked inside the editor: You may be affected. ‍
The panel includes components imported from GitHub: You may be affected.

That's the whole triage. If your Coded components panel is empty, you're all set and can stop here 🙂

If it's not, refer to the dedicated guides below to review your coded components before your next republish.

Why we're making this change

Coded components have handled CSS styling in an older way that limits what we can build on top of it.

Standardizing that approach lets us ship updates that improve how your apps perform for search engines (SEO) and AI answer engines (AEO). It's a foundational change that will pay off across everything you publish next.

What's changing

On August 18, we're standardizing all WeWeb native elements to the new styling approach.

For reference, the elements we're updating are: the flexbox, button, text, image, basic input, mask input, input with advanced placeholder, select input, multiselect, columns, tabs, and OTP input.

If your projects only use standard WeWeb elements, you don't need to do anything. We'll update every instance of these native elements automatically.

However, if you imported coded components from GitHub or you or AI forked one of these elements in the past, the styles of these custom components may be affected by the update.

When is action required?

Your published app continues to work as it does today. The change only takes effect for an affected component the next time you republish.

So there's no deadline and no rush.

Before your next republish after August 18, review any coded components you or AI forked and update the ones that are affected. If you don't republish, nothing changes.

If you republish after August 18 without updating an affected component first, the component's styling may not render correctly.

How to update an affected component

Your path depends on where the component came from.

Components you or AI forked in the WeWeb editor

Forked components live inside your WeWeb project, so WeWeb's MCP can audit and update them for you.

Pre-requisite: If you haven't connected the WeWeb MCP yet, follow the setup steps here.

Once your AI agent is connected to the WeWeb MCP, start a chat with your AI agent and paste this prompt:

You are auditing and then migrating coded components owned by the WeWeb workspace of the currently
selected project.

You have access to the WeWeb MCP.

CSS RENDERER CONTRACT — FOLLOW EXACTLY

- ww-config.js css({ content, style, state, breakpoint }) runs for every compiled state and
  breakpoint combination: base, selector states, runtime states, default, tablet, and mobile.
- content and style are flat compiler proxies already scoped to the current state and breakpoint.
  Usually do not branch on state or breakpoint.
- css() returns an array of { property, value } declarations attached to the component root. There
  is no selector field in a css() output.
- Root styles such as width, height, margin, padding, display, position, overflow, border, and
  background must remain on the component root.
- If an internal node needs a non-inherited value, expose only that value as a narrowly named CSS
  custom property from css(), then consume it in component CSS with a safe fallback.
- Pass formula-capable content/style proxy values directly to css() outputs. Do not spread,
  enumerate, clone, stringify, recursively inspect, or resolve the proxies in JavaScript.
- Nested members of an object-valued content/style property are not recursively formula-aware. A
  value that must remain reactive must be exposed as a top-level property.
- Do not branch on the resolved value of a bindable proxy. For a boolean-to-CSS mapping, use
  content._mapValue or style._mapValue with:
  _mapValue(sourceProperty, stableOutputKey, { trueValue, falseValue }).
- A selector state is declared as { label, selector } or { label, selectors }. Every selector must
  contain & and be anchored to the component root. Keep existing state labels unchanged.
- A plain state string remains a runtime state. Selector states affect CSS matching only and do not
  notify component JavaScript.
- Remove add-state/remove-state for a DOM-derived state only when it exists exclusively for styling.
  Preserve runtime state handling when JavaScript, events, variables, actions, or workflows depend
  on the transition.
- Prefer one real HTML root. If inheritAttrs is false, use v-bind="$attrs" on that root. Do not
  forward WeWeb root classes, technical attributes, or $attrs.style to an internal control.
- css() must be synchronous, deterministic, side-effect free, and browser-independent. It must not
  use window, document, DOM refs, Vue instances, lifecycle state, wwLib, network calls, asynchronous
  work, or runtime-only npm behavior.
- Do not recreate componentStyle or an equivalent generic style bag.
- Preserve unrelated $attrs behavior and legitimate internal inline styles that implement real
  component behavior.

REFERENCE MIGRATION A — VALUE NEEDED BY AN INTERNAL NODE

Before, the component reads a WeWeb style from JavaScript:

    const componentStyle = inject('componentStyle');
    const cursor = computed(() => componentStyle.cursor);

After, ww-config.js exports only the required value:

    export default {
        css({ style }) {
            return [
                { property: '--component-cursor', value: style.cursor },
            ];
        },
    };

The component removes the inject/computed code and consumes the value in CSS:

    .component__control {
        cursor: var(--component-cursor, pointer);
    }

REFERENCE MIGRATION B — BINDABLE BOOLEAN MAPPING

    export default {
        css({ content }) {
            return [
                {
                    property: '--component-white-space',
                    value: content._mapValue('compact', 'white-space', {
                        trueValue: 'nowrap',
                        falseValue: 'normal',
                    }),
                },
            ];
        },
    };

Do not replace this with content.compact ? 'nowrap' : 'normal' because compact may be a bindable
compiler proxy.

REFERENCE MIGRATION C — $attrs.style COPIED TO AN INTERNAL CONTROL

Before:

    <div class="component">
        <ThirdPartyControl :style="{ ...$attrs.style, ...internalStyle }" />
    </div>

After:

    <div class="component">
        <ThirdPartyControl class="component__control" :style="internalStyle" />
    </div>

    .component__control {
        color: inherit;
        font: inherit;
    }

If the internal control needs a non-inherited value, expose only that value through css() as shown
in Reference A.

REFERENCE MIGRATION D — SELECTOR STATE VERSUS RUNTIME STATE

Before:

    states: ['focus', 'open']

    emit('add-state', 'focus');
    emit('remove-state', 'focus');
    emit('add-state', 'open');
    emit('remove-state', 'open');

After, when focus is styling-only but open is semantic:

    states: [
        { label: 'focus', selector: '&:focus-within' },
        'open',
    ]

Remove only the focus add-state/remove-state calls. Preserve the open runtime-state calls.

Do not guess beyond this contract. Stop for human confirmation whenever the correct classification
or behavior is ambiguous.

GOAL

Identify every WeWeb AI-generated or in-WeWeb forked coded component that still depends on the
legacy resolved JavaScript style object. Propose the smallest safe migration without losing any
user customization.

Never modify a GitHub component, an external-source component, a shared component, or a component
that is not owned by the selected workspace.

PHASE 1 — READ-ONLY AUDIT

1. Identify and display the selected WeWeb workspace and project. If either is unclear, stop and ask
   me to confirm the target.

2. Call:
   listCodedComponents({
       includeShared: false,
       readyOnly: false,
   })

3. Limit the audit to components for which:

   - isOwner === true;
   - isEditable === true;
   - type is "ai" or "fork".

4. For each component, call loadComponentFiles with its wwObjectBaseId and the version ID returned
   by listCodedComponents.

5. Inspect all loaded files. Search for and review:

   - componentStyle;
   - inject('componentStyle');
   - $attrs.style;
   - :style and v-bind:style;
   - add-state, remove-state, and toggle-state;
   - states and css() in ww-config.js;
   - values copied from WeWeb styles to internal DOM nodes;
   - inheritAttrs and where $attrs is bound;
   - inherit, options.displayAllowedValues, and options.ignoredStyleProperties;
   - package.json and AI.json.

6. Do not treat every inline style as obsolete. Classify each relevant use as one of:

   - root-only WeWeb CSS: remove the JavaScript style read and leave the root CSS to WeWeb;
   - descendant CSS: export only the required value from css() as a narrowly named CSS custom
     property and consume it with a safe fallback;
   - genuine internal JavaScript behavior: retain it and explain why;
   - styling-only DOM state: replace it with a root-anchored selector state;
   - semantic runtime state used by JavaScript, events, variables, actions, or workflows: retain it;
   - ambiguous: stop and request a human decision.

7. Classify each component as:

   - no migration required;
   - safely migratable;
   - human decision required;
   - not editable.

8. Return an audit table containing:

   - component name;
   - wwObjectBaseId;
   - audited version ID;
   - type;
   - legacy dependencies found;
   - proposed changes;
   - risks and ambiguities.

Do not call publishComponent during Phase 1. Present the complete report and wait for my explicit
approval before modifying or publishing anything.

PHASE 2 — MIGRATION AFTER APPROVAL

For each explicitly approved component, process one component at a time:

1. Reload its current active source with loadComponentFiles.
2. Compare the loaded version ID with the audited version ID. If it changed, repeat the audit and
   stop before publishing.
3. Apply the smallest migration compatible with the CSS renderer contract above.
4. Preserve the component's:
   - existing wwObjectBaseId, name, and tag;
   - property keys and public configuration;
   - state labels;
   - events, actions, variables, and slots;
   - dependencies and user customizations;
   - unrelated behavior and formatting.
5. Never recreate componentStyle or move generic root layout styles to an internal element.
6. If AI.json is missing, derive it only from the component's real public interface. Do not invent
   properties or behavior. Stop if the intended documentation is ambiguous.
7. Ensure that AI.json metadata.name exactly matches package.json name.
8. Call publishComponent with the complete set of component files, the existing wwObjectBaseId, and
   the message "Migrate component to CSS renderer". Never omit wwObjectBaseId when updating, because
   omitting it creates a new component.
9. After publication, report:
   - previous and new version IDs;
   - files changed;
   - before/after behavior for every migrated dependency;
   - checks performed;
   - whether static, responsive, state, formula, and post-mount reactive behavior were verified;
   - remaining manual QA.

A successful publish activates the newly built version. Stop after each component and ask the user
to test it in the editor and in a published application before continuing with the next component.
Do not describe a successful build as functional validation.

STOP WITHOUT PUBLISHING IF:

- a legacy dependency cannot be classified confidently;
- a state has ambiguous functional behavior;
- the migration would change the public API;
- the loaded source is incomplete;
- the component is not editable or not owned by the workspace;
- preserving the user's fork customizations cannot be guaranteed;
- the current workspace or project has not been confirmed.

The agent will list what it found and wait for your go-ahead before changing anything, so you stay in control.

⚠️ Important ⚠️

This is an assisted migration, not a safe unattended bulk rewrite.

The first part of the prompt will ensure that the MCP audits every component without writing anything. Then, you will be invited to review and migrate approved components one at a time.

Make sure to go through the two separate phases distinctly and take the time to review the AI agent's proposals.

Components you imported from GitHub

These components live in a code repository in GitHub, so they should be updated there, not in the WeWeb editor.

We've put together a full technical guide that includes:

a ready-made prompt for an AI coding agent (shared below with placeholders to update),
before-and-after examples for every pattern,
the css() hook contract,
selector-based states,
a verification checklist, and
links to real open-source migrations.

Share the link to the guide and the prompt below with whoever maintains the component, or to an AI coding tool with access to the repo:

You are migrating a WeWeb coded component from the legacy inline-style renderer to WeWeb's CSS renderer.

Component repository: <ABSOLUTE_PATH_OR_REPOSITORY_URL>
Component name/base ID: <BASE_ID>

Goal:
Preserve existing behavior while removing dependencies on the legacy resolved JavaScript style object.

CSS hook execution model:
- ww-config.js css({ content, style, state, breakpoint }) runs for every compiled state × breakpoint slot.
- This includes base, selector-based states, and custom runtime states, for default, tablet, and mobile.
- content/style are flat proxies already scoped to the current state and breakpoint.
- Outputs are declarations on the component root. Use CSS custom properties to carry values to internal nodes.
- Static values become generated CSS; formula values become scoped runtime CSS variables and remain reactive.
- A selector-based state changes CSS matching only. It does not notify component JavaScript.

Technical contract — implement exactly this way:
- css() returns an array of { property, value } declarations. There is no selector field in an output.
- Each output is attached to the component root for the current state and breakpoint.
- An output property may be a normal CSS property or a CSS custom property. Prefer a narrowly named custom property when an internal node needs the value.
- Always consume a custom property with a safe fallback, for example var(--component-cursor, pointer).
- Pass formula-capable proxy values through directly, for example value: content.accentColor. Do not spread, enumerate, clone, stringify, or recursively inspect content/style.
- Nested fields of an object returned by content.foo or style.foo are not recursively formula-aware. Expose a value as a top-level property if it must remain reactive.
- Do not branch on the resolved value of a bindable proxy. Map boolean-like values with content._mapValue or style._mapValue.
- _mapValue(sourceProperty, outputKey, valueMap) receives the source property name, a stable unique output key, and { trueValue, falseValue }.
- Usually do not branch on state or breakpoint because the proxies already read the current slot.
- The state argument is a persisted state ID and is not guaranteed to equal the configured label. Only state === 'base' is stable without further evidence.
- A selector state is declared with { label, selector } or { label, selectors }. Every selector must contain & to anchor it to the component root.
- Keep state labels unchanged so existing saved state styles continue to match.
- A plain state string such as 'open' remains a runtime state and is activated with add-state/remove-state.
- Do not remove DOM event handling when JavaScript behavior, emitted events, variables, or workflows depend on the transition. Selector states replace runtime events only when the state exists solely for styling.
- Prefer one real HTML root. If inheritAttrs is false, use v-bind="$attrs" on that root. Never forward WeWeb root classes or technical attributes to an internal control instead.
- css() must not use window, document, DOM refs, Vue instances, lifecycle state, wwLib, network calls, asynchronous work, or npm runtime imports.

Reference migration A — componentStyle value needed by an internal node:

BEFORE, src/wwElement.vue:
    import { computed, inject } from 'vue';

    setup() {
        const componentStyle = inject('componentStyle');
        const cursor = computed(() => componentStyle.cursor);
        return { cursor };
    }

    <div class="select" :style="{ '--component-cursor': cursor }">...</div>

AFTER, ww-config.js:
    export default {
        css({ style }) {
            return [
                { property: '--component-cursor', value: style.cursor },
            ];
        },
        // Preserve the rest of the existing configuration.
    };

AFTER, src/wwElement.vue:
    // Remove inject('componentStyle'), its computed wrapper, and the inline CSS-variable binding.

    <div class="select">...</div>

    <style scoped>
    .select,
    .select :deep(.select-wrapper) {
        cursor: var(--component-cursor, pointer);
    }
    </style>

Reference migration B — content property with formulas and boolean CSS mapping:

ww-config.js:
    export default {
        css({ content }) {
            return [
                // Direct pass-through preserves static, responsive, state, formula, and reactive values.
                { property: '--component-accent', value: content.accentColor },
                // Do not write `content.compact ? 'nowrap' : 'normal'` for a bindable value.
                {
                    property: '--component-white-space',
                    value: content._mapValue('compact', 'white-space', {
                        trueValue: 'nowrap',
                        falseValue: 'normal',
                    }),
                },
            ];
        },
    };

src/wwElement.vue:
    <style scoped>
    .component__label {
        color: var(--component-accent, currentColor);
        white-space: var(--component-white-space, normal);
    }
    </style>

Reference migration C — $attrs.style was copied to an internal node:

BEFORE:
    <div class="component">
        <ThirdPartyControl class="component__control" :style="{ ...$attrs.style, ...internalStyle }" />
    </div>

AFTER:
    <div class="component">
        <ThirdPartyControl class="component__control" :style="internalStyle" />
    </div>

    <style scoped>
    .component__control {
        color: inherit;
        font: inherit;
    }
    </style>

Root width, margin, padding, display, position, border, and background must stay on the component root. If an internal node needs a non-inherited value, expose only that value through css() as shown in migration A.

Reference migration D — styling-only DOM state versus semantic runtime state:

BEFORE, ww-config.js:
    states: ['focus', 'open']

BEFORE, component code:
    emit('add-state', 'focus');    // on focusin
    emit('remove-state', 'focus'); // on focusout
    emit('add-state', 'open');     // application-controlled state
    emit('remove-state', 'open');

AFTER, ww-config.js:
    states: [
        { label: 'focus', selector: '&:focus-within' },
        'open',
    ]

AFTER, component code:
    // Remove add-state/remove-state for focus only.
    // Keep these because open is semantic application state:
    emit('add-state', 'open');
    emit('remove-state', 'open');

Multiple selector example:
    states: [
        { label: 'readonly', selectors: ['&:read-only', '&:has(input:read-only)'] },
    ]

Use :has() only when the descendant selector can match an element owned by this component. Do not let slotted or arbitrary descendant controls accidentally activate the state.

Non-negotiable constraints:
1. Do not use inject('componentStyle'), an injected componentStyle option, or any equivalent recreated style bag.
2. Do not use $attrs.style as a source of WeWeb visual styles. Preserve unrelated $attrs behavior.
3. Do not move generic root layout styles (width, margin, display, position, etc.) onto internal nodes.
4. Prefer generated root CSS. If an internal DOM node needs a value, export only that value from ww-config.js css() to a narrowly named CSS custom property and consume it in component CSS.
5. Keep ww-config.js css() synchronous, deterministic, side-effect free, browser-independent, and publisher-safe. Use only supported relative, side-effect-free imports.
6. Treat css() content/style arguments as flat compiler proxies, not resolved runtime values or enumerable objects.
7. Preserve formula reactivity by passing proxy values directly to CSS outputs. For boolean keyword mapping, use content._mapValue or style._mapValue with a stable output key. Do not branch on the resolved result of a bindable proxy.
8. Selector-based states must be anchored with &: for example { label: 'focus', selector: '&:focus-within' }. Keep state labels stable. Keep runtime state events for semantic states that cannot be expressed entirely by a DOM selector.
9. Prefer a single real HTML root so WeWeb classes, attributes, and runtime CSS variables target an HTMLElement.
10. Do not change unrelated behavior, formatting, dependencies, or public component APIs.

Required workflow:
A. Read AGENTS.md and repository instructions first.
B. Inspect ww-config.js/json, the root Vue component, child components, stylesheets, and tests.
C. Search the whole component repository for:
   - componentStyle
   - inject(
   - $attrs.style
   - :style / v-bind:style
   - add-state / remove-state / toggle-state
   - states in ww-config
   - CSS variables and getComputedStyle
D. Classify every legacy style read:
   - root-only CSS: delete the JS read;
   - descendant CSS: export a custom property in css();
   - DOM-derived state: use a selector-based state;
   - semantic/runtime behavior: retain the runtime state API;
   - genuine JS behavior: use semantic content/state or explain why no safe automatic migration exists.
E. Inspect inherit, options.displayAllowedValues, and options.ignoredStyleProperties for compatibility.
F. Implement the smallest focused patch. Do not create a compatibility shim that reconstructs componentStyle.
G. Add or update tests where the repository supports them.
H. Run the repository's lint, unit tests, and build/typecheck commands.
I. If a local editor/publisher is available, test editor and published output with base, responsive, state, static, bound, and reactive values.

Before editing, report:
- every legacy dependency found;
- its classification and proposed replacement;
- any ambiguous behavior that needs human confirmation.

After editing, report:
- files changed and why;
- before/after behavior for each migrated dependency;
- commands and browser scenarios tested;
- remaining risks or unsupported cases;
- whether static, responsive, state, formula, and post-mount reactive behavior were each verified.

Stop and ask for confirmation instead of guessing if:
- componentStyle affects non-CSS JavaScript behavior;
- a style must target an ambiguous internal node;
- a state is partly DOM-derived and partly application-controlled;
- css() would need a browser/runtime API;
- a nested formula value cannot be represented by the supported flat proxy;
- the component has multiple roots and changing the DOM shape may be breaking.

‍

Need a hand?

If you're not sure whether a component is affected, or you'd like help updating one, contact our support team in the app. We're happy to walk through it with you.