Layered CSS Variables and a Ten-Floor Template Keep AI-Generated Product Pages Uniform
theme: vuepress highlight: a11y-dark
Why Build a Component Library?
Because our product detail pages have been highly customized: almost every floor on every page uses a different animation, so animations between floors are hard to reuse. The only reusable pieces were per-brand fonts, theme colors, and so on. That made each detail page expensive to build.
We tried designing a component library multiple times, but the customization problem kept blocking it. So we settled for an animation template. That template listed the mainstream animations used on detail pages, with demos, code, and descriptions. The idea was simple: when building a detail page, find a similar animation in the template, copy the code, tweak it, and avoid building an animation from scratch.
The animation template did help, but with over 100 animations, newcomers spent a lot of time hunting for templates and learning the code.
Later, AI made detail-page development easier, but introduced new problems. Generated code was inconsistent in quality, reviewing it took a long time, and AI produced lots of dead code, making it hard to read when you wanted to tweak a single animation.
What this component library actually solves is that: constrain AI's generation, provide standard templates.
Design Approach
1. Scope First
The component library's styles are only imported by the brand site detail page route and all rules live under a single root class name. Two benefits: it doesn't affect other pages on the site, and old detail page styles can't pollute it.
2. Variable Design
Variables are the foundation of the component library. The design considers three things: how to name them, how many layers, and where to define them.
In the examples below,
.brand-pdpstands for the root class name.
1. Naming Convention
Variables are named uniformly as "namespace - type - object - modifier". For --pdp-font-size-superheadline:
--pdp: namespace, meaning it belongs to the detail page component library.font-size: type, meaning it controls font size.superheadline: object, referring to the extra-large headline.
The pattern makes names derivable: when you need the line height for a superheadline, you can guess --pdp-line-height-superheadline without checking docs. This works for AI too: it can find the right variable instead of writing a hardcoded value.
2. Three Layers, from Atomic to Semantic
.brand-pdp {
/* base values: describe "what they are", no business meaning */
--font-black-headline: #1a1a1a;
--spacing-24: 2.4rem;
/* semantic variables: describe "where they're used", one variable controls one property */
--pdp-text-color-headline: var(--font-black-headline);
--pdp-font-size-superheadline: 6.8rem;
--pdp-line-height-superheadline: 7.6rem;
--pdp-font-weight-superheadline: 600;
}
The third layer is composite variables — they combine weight, size, line height, and font family of the same typography into a font shorthand and hand it to a same-named typography class:
--pdp-superheadline: var(--pdp-font-weight-superheadline) var(--pdp-font-size-superheadline)/var(--pdp-line-height-superheadline) var(--pdp-font-family);
.brand-pdp .pdp-superheadline {
font: var(--pdp-superheadline);
color: var(--pdp-text-color-headline);
}
At the page level, just write <h1 class="pdp-superheadline"> and size, line height, weight, and color all come in one go.
3. Composite Variables Are Defined on Every Element
Composite variables are not defined together with other variables on the root node; they're defined on the root node and all its descendants. The reason: CSS variables are computed at the element where they're defined, and descendants inherit the computed result.
For example, if a floor wants to shrink the superheadline, it only overrides --pdp-font-size-superheadline on that floor.
- If the composite variable were defined on the root, it would already be computed as
6.8remand the floor's override wouldn't take effect. - Defining it on each element causes it to recompute at the point of use; overriding one atomic variable is enough.
3. Template Design
The template is the second part of the component library. Shared styles answer "what to use"; templates answer "how to write".
1. The Template Is a Complete Demonstration Page
The template only has root div, style, and script, matching the shape of real detail content, so it can be used right away. It contains ten floors, each demonstrating a layout: hero visual, selling-point cards, generic image-text, multi-tab carousel, horizontally scrollable explanations, parameter list, product packaging. When building a new page, pick what you need and remove the rest.
2. Public Classes and Floor Classes Each Do Their Own Job
pdp-*: public classes, responsible for page, content containers, and nine-level typography.floor-*: template classes, responsible only for floor structures not covered by shared styles. Among them,floor-container,floor-titleare shared across multiple floors;floorN-semantic-nameare specific to a single floor.
When responsibilities overlap, always use the public class; don't copy or rename. This rule ensures that adjusting a spec only requires changing one place.
Example of a generic image-text floor:
<div class="pdp-page floor-page" data-theme="light">
<div class="floor-common floor3-container">
<div class="floor-text">
<h2 class="pdp-headline animation-item">Title</h2>
<h3 class="pdp-subhead animation-item">Subtitle</h3>
<p class="pdp-body-l animation-item">Body</p>
</div>
<picture class="floor-image floor-image-light">
<source media="(max-width: 1023px), (orientation: portrait)" srcset="mobile image">
<img src="PC image" alt="product name" loading="lazy">
</picture>
</div>
</div>
- The root node has both
pdp-pageandfloor-page: the former enables shared typography, the latter scopes template styles. - Titles, subtitles, and body text don't specify font sizes — they all come from
pdp-*typography classes. - The rise animation only adds an
animation-item; the shared library handles it, and the template contains no JS. floor-commonis the shared structure for generic image-text floors;floor3-containeris reserved for this floor's own differences.
3. Light and Dark Image Sets Live Together
The template demonstrates both light and dark themes, so each image has floor-image-light and floor-image-dark duplicates, and the root node's data-theme decides which one is shown. A real detail page has only one theme; keep the matching set during development.
4. The Template Itself Is the Spec
The code in the template deliberately uses one consistent style:
- Sizes use rem
- Selectors are at most two levels and only use class names
- No unused properties
- Multiple tabs show/hide with the same set of
activeandhide
After AI reads the template and writes to match it, the generated code naturally has a uniform style, which saves review time.
4. Theme and Multi-Device Switch via Variables
Color variables default to light; setting data-theme="dark" on the root node switches the whole page to dark, with no hardcoded color values in styles.
.brand-pdp {
--pdp-text-color-headline: var(--font-black-headline);
}
.brand-pdp .pdp-page[data-theme='dark'] {
--pdp-text-color-headline: var(--font-white-headline);
}
Multi-device is the same: when width is 1023px or below, or in portrait orientation, mobile specs kick in. Media queries only override variables like font size, line height, and spacing; typography classes don't need a second definition.
@media (max-width: 1023px), (orientation: portrait) {
.brand-pdp {
--pdp-font-size-superheadline: 3.6rem;
--pdp-line-height-superheadline: 4.4rem;
}
}
5. Keep Interaction Minimal
Use CSS whenever possible, not JS: the rise animation is handled by the shared library, and horizontally sliding floors use native browser scrolling. Swiper is only introduced where scripts are unavoidable — carousels — and it's wrapped into a single method called consistently by all floors.
Division of Work After Launch
After the component library goes live, work splits into three parts:
| Role | Responsibility |
|---|---|
| Design | Maintain the Figma component library and acceptance criteria; new components and specs are finalized on the design side first |
| Component library maintenance | Maintain shared styles, the test environment template, and the development spec doc; new variables and components are merged in here |
| Detail page development | Produce concrete product detail content from the template; only write product-specific floor styles, never modify shared styles |
There is one boundary: shared things have a single outlet. When a detail-page developer finds a missing variable or component, they report it to the component library maintainer to add to the shared layer and template, rather than adding a temporary copy in their own page.
How to Use
Building a new product detail page follows a fixed process:
- Let AI read two specs first: the project's development spec doc and the test environment's template code.
- Choose floors from the template based on the product needs, replace images and copy.
- Decide on a theme and keep only the matching image set.
- The output only contains root div, style, and script, configured into the backend
staticContentand rendered by the detail page.
Having AI read the template first is the key step. The template is the executable version of the spec: naming, structure, styles, scripts — the code has ready examples for all of it, more accurate than any written description.
Summary
The value of the component library isn't that any one floor is written beautifully; it's three things: the spec has one source, changes have one entry, new pages have one starting point. The extra time spent up front pays back on every detail page after.
Top 1 of 2 from juejin.cn, machine-translated. The original thread is authoritative.
The inheritance timing of combined variables is worth noting.
Yes, the detailed explanation about inheritance is in the definition of combined variables.