A Portal Redesign Broke the Landing Page: The CSS Scope Lesson

A variable called “secondary” can mean dark supporting ink on a marketing page and a pale secondary surface inside a workspace. If both meanings share one global name, replacing the value changes every consumer. The problem is semantic disagreement, not simply choosing the wrong shade.

I would review token names with the contexts that use them. Text, background, border and status roles should remain understandable when read in code. A token that means an action colour in one component and arbitrary decoration in another becomes difficult to change safely. Naming is part of the design system’s behaviour.

A portal component might look perfect during local review while a public heading becomes nearly invisible. Global base rules, font defaults and utility removal can all affect pages that the person making the change did not open. The regression follows the cascade rather than the route structure in the designer’s head.

That is why I want a small inventory of surfaces before integrating a new theme. Public home, login, dashboard, an editor and a dialog are different review cases. The goal is not to screenshot every possible state immediately. It is to identify the boundaries most likely to share styles unexpectedly.

The documented fix uses a scoped portal colour system while preserving the public page’s expected palette. That lets the workspace adopt its own surface relationships without silently redefining the entire site. The later website styling also documents why public tokens and scoped tokens coexist.

There are several valid implementation strategies: a theme container, explicit data attributes or separate style bundles. The right choice depends on the application. The invariant is that a component’s token values come from the intended context. A global search-and-replace can make a patch look comprehensive while breaking that relationship elsewhere.

Dialogs and popovers may render outside the DOM subtree that owns a theme. A beautifully scoped workspace can therefore produce an incorrectly coloured menu when an overlay mounts under the document body. This is an important handoff detail because a static design frame usually does not reveal where the component renders.

Review the overlay container and theme propagation deliberately. Test a dialog in both themes, then close it and verify focus returns to the triggering control. Colour and interaction boundaries meet here: the overlay needs readable tokens and predictable keyboard behaviour. A visually correct modal that loses the user’s place is still unfinished.

During a redesign it is tempting to remove classes that look obsolete. A marketing page may still rely on a gradient-text utility, a glass treatment or a layout helper. Deleting those while reviewing only portal screens can create regressions with no obvious connection to the new component.

I would inspect usage before removal and distinguish global primitives from one-off effects. Where a utility is replaced, migrate its consumers explicitly. Where it remains necessary, keep it with a clear purpose. A cleaner stylesheet is valuable when it describes the product accurately, not when it merely contains fewer lines.

A colour can pass on one background and fail on another. Transparent surfaces, hover states, disabled controls and dark appearance all change the relationship. A glass effect especially depends on what appears behind it. Checking a swatch in isolation cannot establish that the interface remains readable.

The portal audit’s later work on semantic colours and themes is useful evidence of this broader review. Automated contrast checks help, but I would also inspect realistic backgrounds, long labels and ordinary display brightness. A decorative effect should support the hierarchy rather than be the only way a user identifies a control.

My practical matrix includes a public page and workspace page, light and dark appearance, narrow and wide viewports, and at least one open overlay. Add a long label and an error message. Those variations expose token leaks and layout assumptions much faster than repeatedly polishing one ideal dashboard.

The accompanying component study uses real portal components with fictional content. It is not a claim that every protected route has been tested in production. That limitation is useful: source review, local rendering and authenticated end-to-end testing establish different things. A design release should describe which evidence it actually has.

Scroll the table horizontally to see all columns.

Figma variables and component variants are most useful when they communicate intended roles. A handoff that says only “use this hex value” leaves the developer to guess whether it is text, a surface or a status. I want the design file to explain what should remain consistent and what may vary by theme.

The translation into CSS is still engineering work. Auto Layout does not decide portal mounting, and a token export does not certify the cascade. MCP tools can carry context into an IDE, but they do not replace reviewing the integrated application. My workflow needs the loop back from code to the rest of the site.

Should every screen have an entirely separate palette? No. Shared brand primitives can remain shared. The important distinction is between common values and context-specific semantic roles.

Does scoping solve every style regression? No. Global resets, inherited typography and overlays can still cross the boundary. Scoping makes intent clearer; representative checks establish whether it works.

When is the redesign ready? When the target experience works and the surrounding surfaces still behave as intended. A screen that matches its reference but damages navigation, contrast or an unrelated page is an incomplete integration.