跪拜 Guibai
← Back to the summary

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.

2fc0bf32b4f18bdb61b0dba3680f777d.png

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-pdp stands for the root class name.

3e156659c26bb62db9e452d5744083b8.png

1. Naming Convention

Variables are named uniformly as "namespace - type - object - modifier". For --pdp-font-size-superheadline:

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.

3. Template Design

The template is the second part of the component library. Shared styles answer "what to use"; templates answer "how to write".

5d3e6922a94ba7ce7a9c29f7bf76534e.png

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

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>

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:

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

79469638745720c5d1368c39acd0239f.png

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:

dfacb916e791eed0cb47160920ffc693.png

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:

d3d58312049b9c5d7a9e4bc9053d2efc.png

  1. Let AI read two specs first: the project's development spec doc and the test environment's template code.
  2. Choose floors from the template based on the product needs, replace images and copy.
  3. Decide on a theme and keep only the matching image set.
  4. The output only contains root div, style, and script, configured into the backend staticContent and 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.

Comments

Top 1 of 2 from juejin.cn, machine-translated. The original thread is authoritative.

卷土的土

The inheritance timing of combined variables is worth noting.

Mh

Yes, the detailed explanation about inheritance is in the definition of combined variables.