faststore-theming

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FastStore Theming & Design Tokens

FastStore 主题定制与设计令牌

When this skill applies

本技能的适用场景

Use this skill when:

You need to change the visual appearance of a FastStore storefront — colors, typography, spacing, borders, or component-specific styles.
You are working with files in
```
src/themes/
```
or creating
```
custom-theme.scss
```
.
You need to customize individual component styles using local tokens and
```
[data-fs-*]
```
data attributes.
You are setting up a brand identity on top of the Brandless default theme.

Do not use this skill for:

Changes that require replacing a component, injecting logic, or modifying behavior — use the
```
faststore-overrides
```
skill.
Client-side state management — use the
```
faststore-state-management
```
skill.
Data fetching or API extensions — use the
```
faststore-data-fetching
```
skill.

在以下场景中使用本技能：

你需要修改FastStore店铺前台的视觉外观——包括颜色、排版、间距、边框或组件特定样式。
你正在处理
```
src/themes/
```
目录下的文件，或创建
```
custom-theme.scss
```
文件。
你需要使用局部令牌和
```
[data-fs-*]
```
数据属性定制单个组件的样式。
你需要在Brandless默认主题基础上搭建品牌专属视觉标识。

请勿在以下场景中使用本技能：

需要替换组件、注入逻辑或修改行为的变更——请使用
```
faststore-overrides
```
技能。
客户端状态管理——请使用
```
faststore-state-management
```
技能。
数据获取或API扩展——请使用
```
faststore-data-fetching
```
技能。

Decision rules

决策规则

Use theming as the first approach before considering overrides — it is lighter and more maintainable.
Use global tokens (
```
:root
```
scope) when the change should propagate store-wide (e.g., brand colors, font families).
Use local tokens (
```
[data-fs-*]
```
scope) when the change applies to a single component (e.g., button background color).
Use
```
[data-fs-*]
```
data attributes to target components — never use
```
.fs-*
```
class names or generic tag selectors.
Place all theme files in
```
src/themes/
```
with
```
custom-theme.scss
```
as the entry point — files elsewhere are not discovered.
Reference design tokens via
```
var(--fs-*)
```
instead of hardcoding hex colors, pixel sizes, or font values.
Use CSS modules for custom (non-FastStore) components to avoid conflicting with FastStore's structural styles.

在考虑组件重写之前，优先使用主题定制方案——这种方式更轻量化且更易于维护。
当变更需要在全店铺生效时（如品牌色、字体族），使用全局令牌（
```
:root
```
作用域）。
当变更仅适用于单个组件时（如按钮背景色），使用局部令牌（
```
[data-fs-*]
```
作用域）。
使用
```
[data-fs-*]
```
数据属性定位组件——绝对不要使用
```
.fs-*
```
类名或通用标签选择器。
将所有主题文件放在
```
src/themes/
```
目录下，以
```
custom-theme.scss
```
作为入口文件——其他位置的文件不会被系统识别。
通过
```
var(--fs-*)
```
引用设计令牌，而非硬编码十六进制颜色、像素尺寸或字体值。
为自定义（非FastStore）组件使用CSS modules，避免与FastStore的结构样式冲突。

Hard constraints

硬性约束

Constraint: Use Design Tokens — Not Inline Styles

约束：使用设计令牌，而非内联样式

MUST use design tokens (global or local) to style FastStore components. MUST NOT use inline

style={}

props on FastStore components for theming purposes.

Why this matters Inline styles bypass the design token hierarchy, cannot be overridden by themes, do not participate in responsive breakpoints, and create maintenance nightmares. They also defeat CSS caching since styles are embedded in HTML. Design tokens ensure consistency and allow store-wide changes from a single file.

Detection If you see

style={{

style={

on FastStore native components (components imported from

@faststore/ui

@faststore/core

) → warn that this bypasses the theming system. Suggest using design tokens or CSS modules instead. Exception: inline styles are acceptable on fully custom components that are not part of the FastStore UI library.

Correct

scss

// src/themes/custom-theme.scss
// Override the BuyButton's primary background color using design tokens
[data-fs-buy-button] {
  --fs-button-primary-bkg-color: #e31c58;
  --fs-button-primary-bkg-color-hover: #c4174d;
  --fs-button-primary-text-color: var(--fs-color-text-inverse);

  [data-fs-button-wrapper] {
    border-radius: var(--fs-border-radius-pill);
  }
}

Wrong

typescript

// WRONG: Using inline styles on a FastStore component
import { BuyButton } from '@faststore/ui'

function ProductActions() {
  return (
    <BuyButton
      style={{ backgroundColor: '#e31c58', color: 'white', borderRadius: '999px' }}
    >
      Add to Cart
    </BuyButton>
  )
  // Inline styles bypass the design token hierarchy.
  // They cannot be changed store-wide from the theme file.
  // They do not respond to dark mode or other theme variants.
}

必须使用设计令牌（全局或局部）为FastStore组件设置样式。绝对不要为FastStore组件使用内联

style={}

属性进行主题定制。

原因内联样式会绕过设计令牌层级，无法被主题覆盖，不支持响应式断点，还会带来维护难题。此外，内联样式会嵌入HTML中，影响CSS缓存。设计令牌可确保样式一致性，且只需修改单个文件即可实现全店铺样式变更。

检测方式 如果发现FastStore原生组件（从

@faststore/ui

或

@faststore/core

导入的组件）使用了

style={{

或

style={

→ 需警告这会绕过主题系统。建议改用设计令牌或CSS modules。例外情况：完全自定义的非FastStore UI库组件可使用内联样式。

正确示例

scss

// src/themes/custom-theme.scss
// 使用设计令牌覆盖BuyButton的主背景色
[data-fs-buy-button] {
  --fs-button-primary-bkg-color: #e31c58;
  --fs-button-primary-bkg-color-hover: #c4174d;
  --fs-button-primary-text-color: var(--fs-color-text-inverse);

  [data-fs-button-wrapper] {
    border-radius: var(--fs-border-radius-pill);
  }
}

错误示例

typescript

// 错误：为FastStore组件使用内联样式
import { BuyButton } from '@faststore/ui'

function ProductActions() {
  return (
    <BuyButton
      style={{ backgroundColor: '#e31c58', color: 'white', borderRadius: '999px' }}
    >
      Add to Cart
    </BuyButton>
  )
  // 内联样式绕过了设计令牌层级。
  // 无法通过主题文件实现全店铺样式变更。
  // 不支持深色模式或其他主题变体。
}

Constraint: Place Theme Files in src/themes/

约束：将主题文件放在src/themes/目录下

MUST place custom theme SCSS files in the

src/themes/

directory. The primary theme file must be named

custom-theme.scss

Why this matters FastStore's build system imports theme files from

src/themes/custom-theme.scss

. Files placed elsewhere will not be picked up by the build and your token overrides will have no effect. There will be no error — the default Brandless theme will render instead.

Detection If you see token override declarations (variables starting with

--fs-

) in SCSS files outside

src/themes/

→ warn that these may not be applied. If the file

src/themes/custom-theme.scss

does not exist in the project → warn that no custom theme is active.

Correct

scss

// src/themes/custom-theme.scss
// Global token overrides — applied store-wide
:root {
  --fs-color-main-0: #003232;
  --fs-color-main-1: #004c4c;
  --fs-color-main-2: #006666;
  --fs-color-main-3: #008080;
  --fs-color-main-4: #00b3b3;

  --fs-color-accent-0: #e31c58;
  --fs-color-accent-1: #c4174d;
  --fs-color-accent-2: #a51342;

  --fs-text-face-body: 'Inter', -apple-system, system-ui, BlinkMacSystemFont, sans-serif;
  --fs-text-face-title: 'Poppins', var(--fs-text-face-body);

  --fs-text-size-title-huge: 3.5rem;
  --fs-text-size-title-page: 2.25rem;
}

// Component-specific token overrides
[data-fs-price] {
  --fs-price-listing-color: #cb4242;
}

Wrong

scss

// src/styles/my-theme.scss
// WRONG: This file is in src/styles/, not src/themes/
// FastStore will NOT import this file. Token overrides will be ignored.
:root {
  --fs-color-main-0: #003232;
  --fs-color-accent-0: #e31c58;
}

// Also WRONG: Creating a theme in the project root
// ./theme.scss — this will not be discovered by the build system

必须将自定义主题SCSS文件放在

src/themes/

目录下。主主题文件必须命名为

custom-theme.scss

。

原因 FastStore的构建系统会从

src/themes/custom-theme.scss

导入主题文件。其他位置的文件不会被构建系统识别，令牌覆盖也不会生效。系统不会报错，而是会渲染默认的Brandless主题。

检测方式 如果在

src/themes/

目录外的SCSS文件中发现令牌覆盖声明（以

--fs-

开头的变量）→ 需警告这些设置可能不会生效。如果项目中不存在

src/themes/custom-theme.scss

文件→ 需警告当前无自定义主题生效。

正确示例

scss

// src/themes/custom-theme.scss
// 全局令牌覆盖——全店铺生效
:root {
  --fs-color-main-0: #003232;
  --fs-color-main-1: #004c4c;
  --fs-color-main-2: #006666;
  --fs-color-main-3: #008080;
  --fs-color-main-4: #00b3b3;

  --fs-color-accent-0: #e31c58;
  --fs-color-accent-1: #c4174d;
  --fs-color-accent-2: #a51342;

  --fs-text-face-body: 'Inter', -apple-system, system-ui, BlinkMacSystemFont, sans-serif;
  --fs-text-face-title: 'Poppins', var(--fs-text-face-body);

  --fs-text-size-title-huge: 3.5rem;
  --fs-text-size-title-page: 2.25rem;
}

// 组件特定令牌覆盖
[data-fs-price] {
  --fs-price-listing-color: #cb4242;
}

错误示例

scss

// src/styles/my-theme.scss
// 错误：文件位于src/styles/而非src/themes/
// FastStore不会导入此文件，令牌覆盖将被忽略。
:root {
  --fs-color-main-0: #003232;
  --fs-color-accent-0: #e31c58;
}

// 同样错误：在项目根目录创建主题文件
// ./theme.scss —— 构建系统无法识别此文件

Constraint: Use Data Attributes for Component Targeting

约束：使用数据属性定位组件

MUST use FastStore's

data-fs-*

data attributes to target components in theme SCSS files. MUST NOT use class names or tag selectors to target FastStore native components.

Why this matters FastStore components use data attributes as their public styling API (e.g.,

data-fs-button

data-fs-price

data-fs-hero

). Class names are implementation details that can change between versions. Using data attributes ensures your theme survives FastStore updates. Each component documents its available data attributes in the customization section of its docs.

Detection If you see CSS selectors targeting

.fs-*

class names or generic tag selectors (

button

h1

div

) to style FastStore components → warn about fragility. Suggest using

[data-fs-*]

selectors instead.

Correct

scss

// src/themes/custom-theme.scss
// Target the Hero section using its data attribute
[data-fs-hero] {
  --fs-hero-text-size: var(--fs-text-size-title-huge);
  --fs-hero-heading-weight: var(--fs-text-weight-bold);

  [data-fs-hero-heading] {
    text-transform: uppercase;
    letter-spacing: 0.05em;
  }

  [data-fs-hero-image] {
    border-radius: var(--fs-border-radius);
    filter: brightness(0.9);
  }
}

Wrong

scss

// src/themes/custom-theme.scss
// WRONG: Targeting by class names — these are internal and may change
.fs-hero {
  font-size: 3.5rem;
}

.fs-hero h1 {
  text-transform: uppercase;
}

// WRONG: Using generic tag selectors
section > div > h1 {
  font-weight: bold;
}
// These are fragile selectors that break when FastStore restructures its HTML.

必须使用FastStore的

[data-fs-*]

数据属性在主题SCSS文件中定位组件。绝对不要使用类名或标签选择器定位FastStore原生组件。

原因 FastStore组件将数据属性作为公开的样式API（如

data-fs-button

、

data-fs-price

、

data-fs-hero

）。类名是实现细节，可能会在版本迭代中变更。使用数据属性可确保主题在FastStore版本更新后仍能正常使用。每个组件的可用数据属性会在其文档的定制部分说明。

检测方式 如果发现CSS选择器使用

.fs-*

类名或通用标签选择器（

button

、

h1

、

div

）为FastStore组件设置样式→ 需警告这种方式的脆弱性。建议改用

[data-fs-*]

选择器。

正确示例

scss

// src/themes/custom-theme.scss
// 使用数据属性定位Hero区块
[data-fs-hero] {
  --fs-hero-text-size: var(--fs-text-size-title-huge);
  --fs-hero-heading-weight: var(--fs-text-weight-bold);

  [data-fs-hero-heading] {
    text-transform: uppercase;
    letter-spacing: 0.05em;
  }

  [data-fs-hero-image] {
    border-radius: var(--fs-border-radius);
    filter: brightness(0.9);
  }
}

错误示例

scss

// src/themes/custom-theme.scss
// 错误：通过类名定位——这些是内部实现，可能会变更
.fs-hero {
  font-size: 3.5rem;
}

.fs-hero h1 {
  text-transform: uppercase;
}

// 错误：使用通用标签选择器
section > div > h1 {
  font-weight: bold;
}
// 这些选择器非常脆弱，当FastStore调整HTML结构时会失效。

Preferred pattern

Common failure modes

常见失败模式

Using
```
!important
```
declarations — creates specificity dead-ends and defeats the cascading nature of design tokens. Use the correct token at the correct selector specificity instead.
Hardcoding hex colors, pixel sizes, and font values directly in component styles instead of referencing
```
var(--fs-*)
```
tokens. Changes cannot propagate store-wide.
Creating a parallel CSS system (Tailwind, Bootstrap, custom global stylesheet) that conflicts with FastStore's structural styles and doubles the CSS payload.
Placing theme files outside
```
src/themes/
```
— they will not be discovered by the build system.
Targeting FastStore components with
```
.fs-*
```
class names or generic tag selectors instead of
```
[data-fs-*]
```
data attributes.

使用
```
!important
```
声明——会导致特异性死胡同，破坏设计令牌的级联特性。应在正确的选择器特异性层级使用正确的令牌。
在组件样式中硬编码十六进制颜色、像素尺寸和字体值，而非引用
```
var(--fs-*)
```
令牌——这种变更无法在全店铺传播。
创建并行CSS系统（如Tailwind、Bootstrap、自定义全局样式表）——会与FastStore的结构样式冲突，且会增加CSS负载。
将主题文件放在
```
src/themes/
```
目录外——这些文件不会被构建系统识别。
使用
```
.fs-*
```
类名或通用标签选择器定位FastStore组件，而非
```
[data-fs-*]
```
数据属性。

Review checklist

审核检查清单

Is the theme file located in
```
src/themes/custom-theme.scss
```
?
Are global token overrides placed in
```
:root
```
scope?
Are component-level overrides using
```
[data-fs-*]
```
data attribute selectors?
Are all values referencing design tokens via
```
var(--fs-*)
```
instead of hardcoded values?
Is there no use of
```
!important
```
declarations?
Could this change be achieved without overrides (is theming sufficient)?
Are custom component styles scoped with CSS modules to avoid conflicts?

主题文件是否位于
```
src/themes/custom-theme.scss
```
？
全局令牌覆盖是否放在
```
:root
```
作用域中？
组件级覆盖是否使用
```
[data-fs-*]
```
数据属性选择器？
所有值是否通过
```
var(--fs-*)
```
引用设计令牌，而非硬编码值？
是否未使用
```
!important
```
声明？
该变更是否无需组件重写即可实现（主题定制是否足够）？
自定义组件样式是否通过CSS modules进行作用域隔离以避免冲突？

Reference

参考资料

Theming overview — Introduction to theming concepts, Brandless architecture, and token hierarchy
Global tokens — Complete reference for all global design tokens (colors, typography, spacing, borders)
Global tokens: Colors — Color token reference and palette structure
Global tokens: Typography — Font family, size, and weight tokens
Global tokens: Spacing — Spacing scale tokens
Styling a component — Guide for customizing individual component styles with local tokens
Available themes — Pre-built themes (Midnight, Soft Blue) available as starting points
Importing FastStore UI component styles — How to import and use component styles in custom sections
```
faststore-overrides
```
— Related skill for when theming alone is insufficient and behavioral changes are needed

主题定制概述 —— 主题定制概念、Brandless架构和令牌层级介绍
全局令牌 —— 所有全局设计令牌（颜色、排版、间距、边框）的完整参考
全局令牌：颜色 —— 颜色令牌参考和调色板结构
全局令牌：排版 —— 字体族、尺寸和字重令牌
全局令牌：间距 —— 间距比例令牌
组件样式定制 —— 使用局部令牌定制单个组件样式的指南
可用主题 —— 可作为起点的预构建主题（Midnight、Soft Blue）
导入FastStore UI组件样式 —— 如何在自定义区块中导入和使用组件样式
```
faststore-overrides
```
—— 当主题定制不足以满足需求，需要修改组件行为时的相关技能

faststore-theming

Original

Translation

FastStore Theming & Design Tokens

FastStore 主题定制与设计令牌

When this skill applies

本技能的适用场景

Decision rules

决策规则

Hard constraints

硬性约束

Constraint: Use Design Tokens — Not Inline Styles

约束：使用设计令牌，而非内联样式

Constraint: Place Theme Files in src/themes/

约束：将主题文件放在src/themes/目录下

Constraint: Use Data Attributes for Component Targeting

约束：使用数据属性定位组件

Preferred pattern

推荐实践模式

Common failure modes

常见失败模式

Review checklist

审核检查清单

Reference

参考资料