pie-design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bootstrap (do this first, every time)

初始化（每次都要先执行这一步）

Paths note: All paths in this skill are relative to
.agents/skills/pie-design-system/
unless stated otherwise.

Check whether
```
.versions
```
exists.

If missing → ensure the three core packages are installed (

@justeattakeaway/pie-webc

@justeattakeaway/pie-css

@justeattakeaway/pie-icons-webc

), then run:

node .agents/skills/pie-design-system/scripts/fetch-references.mjs

If present → compare versions in
```
.versions
```
against the installed package versions (
```
node_modules/@justeattakeaway/pie-webc/package.json
```
etc.). Re-run the script if any version differs. Otherwise proceed to the next section.

路径说明： 除非另有说明，本技能中的所有路径均相对于
.agents/skills/pie-design-system/
。

检查
```
.versions
```
文件是否存在。

若文件缺失 → 确保已安装三个核心包（

@justeattakeaway/pie-webc

、

@justeattakeaway/pie-css

、

@justeattakeaway/pie-icons-webc

），然后运行：

node .agents/skills/pie-design-system/scripts/fetch-references.mjs

若文件存在 → 对比
```
.versions
```
中的版本与已安装包的版本（如
```
node_modules/@justeattakeaway/pie-webc/package.json
```
等）。若版本不一致，重新运行上述脚本；否则进入下一章节。

Answer the question

解答用户问题

Read the user's message and figure out what they need. Use the table below to find the right section — if the request spans multiple areas (e.g., "add a button with an icon"), read all relevant sections before responding.

User wants…	Section
Set up PIE in a new project	First-time PIE integration
Review PIE usage	Review Project
Font setup, typography, font loading, type scale, italic rendering	Typography
Component API / props / slots / usage or Building UI	Looking up components
Import or find an icon	Icons
Component events and interactions	Events
Design tokens (colours, spacing, etc.)	Design tokens
Customise or override a component's look	Customising components
Something broken or unexpected	Looking up components → pre-flight #4

After writing your response, run through the pre-flight checklist before presenting it to the user.

阅读用户的问题，明确其需求。使用下表找到对应的章节——如果需求涉及多个领域（例如“添加带图标的按钮”），请先阅读所有相关章节再回复。

用户需求…	对应章节
在新项目中搭建PIE	首次PIE集成
检查PIE使用情况	项目评审
字体设置、排版、字体加载、字号层级、斜体渲染	排版
组件API / 属性 / 插槽 / 使用方法或构建UI	组件查询
导入或查找图标	图标
组件事件与交互	事件
设计令牌（颜色、间距等）	设计令牌
定制或覆盖组件外观	组件定制
功能异常或问题排查	组件查询 → 预检清单第4条

回复用户前，请先对照预检清单检查内容。

First-time PIE integration

首次PIE集成

Only follow these steps if PIE has never been set up in the project (no existing

@justeattakeaway/pie-*

imports):

Read
```
guides/css-setup.md
```
and apply the base CSS setup.
Read
```
guides/typography.md
```
and wire up the type scale.
If the project uses a framework, read the matching
```
guides/framework-integration-guides-*.md
```
for the framework setup.

These steps establish the foundation every PIE component relies on. Skipping them leads to broken styles and missing tokens.

仅当项目从未搭建过PIE（无现有

@justeattakeaway/pie-*

导入）时，才需执行以下步骤：

阅读
```
guides/css-setup.md
```
并完成基础CSS配置。
阅读
```
guides/typography.md
```
并配置字号层级。
若项目使用框架，请阅读对应的
```
guides/framework-integration-guides-*.md
```
完成框架适配。

这些步骤是所有PIE组件运行的基础，跳过会导致样式异常和令牌缺失。

Review Project (for evaluate/review/audit requests)

项目评审（用于评估/检查/审计需求）

If the user asks to review/evaluate/audit PIE usage, you must read and assess against all of the following sections to ensure a comprehensive review:

Typography
Looking up components
Events
Icons
Design tokens
Customising components

Do not finalize the response until each category has an explicit pass/fail outcome.

若用户要求评审/评估/审计PIE使用情况，你必须阅读并对照以下所有章节，确保评审全面：

排版
组件查询
事件
图标
设计令牌
组件定制

需明确每个类别的检查结果（通过/不通过）后，再提交最终回复。

Typography

排版

Read

guides/typography.md

and

guides/typography-utility-classes.md

when the request involves fonts, type scale, font loading, italic behavior, or general UI baseline setup.

Always recommend using the typography utility classes from

pie-css

instead of custom font styles. These classes ensure consistent application of PIE's type scale and responsive adjustments across all components.

Verify that the implementation in the guide is followed, including @font-face declarations and CSS definitions included globally in the application styles.

当需求涉及字体、字号层级、字体加载、斜体渲染或通用UI基线设置时，请阅读

guides/typography.md

和

guides/typography-utility-classes.md

。

始终推荐使用

pie-css

提供的排版工具类，而非自定义字体样式。这些工具类可确保PIE字号层级的一致性，以及所有组件的响应式适配。

请验证实现是否遵循指南要求，包括全局引入

@font-face

声明和CSS定义。

Looking up components

组件查询

When the user asks about a specific component — say

pie-button

— read

components/pie-button.md

and focus on:

Properties — the props the component accepts
Slots — named and default slot content
Events — emitted events and their payloads
Usage example — pick the one matching the detected framework on the consumer's project.
CSS Variables / CSS Parts — available style overrides

Skip the npm badge, Table of Contents, installation section, irrelevant framework examples, and boilerplate ("Questions and Support", "Contributing").

To see components PIE offers, list the files in

components/

. If a component isn't listed, it either doesn't exist in PIE or is still in alpha — let the user know and point them to #help-designsystem on Slack for timelines or to discuss a custom alternative.

Example 1 — "how do I make a loading button?": Read

components/pie-button.md

, find the

isLoading

prop, show usage in the project's framework.

Example 2 — "what props does the modal have?": Read

components/pie-modal.md

, list its Properties section.

Example 3 — "I need a form with checkboxes and a submit button": Read

components/pie-checkbox.md

and

components/pie-button.md

. Show how to compose them together, including form association patterns.

当用户询问特定组件（例如

pie-button

）时，请阅读

components/pie-button.md

并重点关注：

属性 — 组件支持的所有props
插槽 — 命名插槽与默认插槽的内容
事件 — 组件触发的事件及其负载
使用示例 — 选择与用户项目框架匹配的示例
CSS变量 / CSS部件 — 可用的样式覆盖选项

可跳过npm徽章、目录、安装章节、无关框架示例和通用内容（如“问题与支持”、“贡献指南”）。

若要查看PIE提供的所有组件，可列出

components/

目录下的文件。若组件未在列表中，说明该组件不存在于PIE中或仍处于alpha阶段——请告知用户，并引导其前往Slack的#help-designsystem频道了解时间线或讨论自定义方案。

示例1 — “如何实现加载状态的按钮？”： 阅读

components/pie-button.md

，找到

isLoading

属性，展示用户项目框架下的使用方法。

示例2 — “模态框有哪些属性？”： 阅读

components/pie-modal.md

，列出其属性章节的内容。

示例3 — “我需要一个包含复选框和提交按钮的表单”： 阅读

components/pie-checkbox.md

和

components/pie-button.md

，展示如何组合使用它们，包括表单关联模式。

Events

事件

Read

guides/events.md

for PIE's event conventions, then check the individual component doc for its specific event list. PIE components follow a consistent event pattern — understanding the guide once covers every component.

请先阅读

guides/events.md

了解PIE的事件约定，再查看对应组件文档中的具体事件列表。PIE组件遵循统一的事件模式——只需理解一次指南，即可适用于所有组件。

Icons

图标

Read

guides/pie-icons-webc.md

for icon props and usage patterns. To browse all available icons, list

node_modules/@justeattakeaway/pie-icons-webc/icons/

. Only use icons that exist in the package — inventing icon names causes broken imports at runtime.

阅读

guides/pie-icons-webc.md

了解图标的属性和使用模式。若要浏览所有可用图标，可列出

node_modules/@justeattakeaway/pie-icons-webc/icons/

目录下的文件。仅使用包中已有的图标——自定义图标名称会导致运行时导入失败。

Design tokens

设计令牌

PIE's visual language — colours, spacing, radius, typography — is expressed through design tokens. These are CSS custom properties following the pattern

var(--dt-<category>-<name>)

, where the category maps to the token type:

Colour:

var(--dt-color-interactive-brand)

var(--dt-color-content-default)

, etc.

Spacing:
```
var(--dt-spacing-a)
```
through
```
var(--dt-spacing-j)
```
Radius:
```
var(--dt-radius-rounded-a)
```
, etc.
Font: Don't use font tokens directly. Instead, use the typography utility classes from
```
pie-css
```
. Read
```
guides/typography-utility-classes.md
```
for the available classes and how to apply them.

When the user asks about tokens:

Read
```
guides/design-tokens-cookbook.md
```
for usage patterns and best practices.
Look up available tokens in
```
tokens/tokensMetadata.json
```
— each entry lists the token's category and description. Use
```
tokens/tokenCategories.json
```
to understand how categories are organised.
Only use alias tokens, never global tokens. Global tokens (e.g.,
```
--dt-color-orange-30
```
) are raw values meant for internal token definitions — they aren't semantic and will break when themes change. Always recommend alias tokens (e.g.,
```
--dt-color-interactive-brand
```
) which carry meaning and adapt across themes.
Only recommend token names that appear in the metadata. Inventing token names causes silent failures — CSS treats unknown custom properties as empty.

Example — "what colour token should I use for a button?": Read

tokens/tokensMetadata.json

, find tokens under the

color

→

alias

section related to interactive content, and recommend the appropriate one (e.g.,

var(--dt-color-interactive-brand)

PIE的视觉语言（颜色、间距、圆角、排版）通过设计令牌（Design Tokens）来实现。这些令牌是遵循

var(--dt-<category>-<name>)

格式的CSS自定义属性，其中category对应令牌类型：

颜色：

var(--dt-color-interactive-brand)

、

var(--dt-color-content-default)

等

间距：
```
var(--dt-spacing-a)
```
至
```
var(--dt-spacing-j)
```
圆角：
```
var(--dt-radius-rounded-a)
```
等
字体：请勿直接使用字体令牌，应使用
```
pie-css
```
提供的排版工具类。请阅读
```
guides/typography-utility-classes.md
```
了解可用类及其使用方法。

当用户询问令牌相关问题时：

阅读
```
guides/design-tokens-cookbook.md
```
了解使用模式和最佳实践。
在
```
tokens/tokensMetadata.json
```
中查找可用令牌——每个条目都列出了令牌的类别和描述。可通过
```
tokens/tokenCategories.json
```
了解类别的组织方式。
仅使用别名令牌，禁止使用全局令牌。 全局令牌（如
```
--dt-color-orange-30
```
）是用于内部令牌定义的原始值——它们不具备语义化，且在主题变更时会失效。始终推荐使用别名令牌（如
```
--dt-color-interactive-brand
```
），这类令牌具备语义含义，可适配不同主题。
仅推荐元数据中存在的令牌名称。自定义令牌名称会导致静默失败——CSS会将未知的自定义属性视为空值。

示例 — “按钮应该使用什么颜色令牌？”： 阅读

tokens/tokensMetadata.json

，找到

color

→

alias

分类下与交互内容相关的令牌，推荐合适的选项（如

var(--dt-color-interactive-brand)

）。

Customising components

组件定制

When a user wants to override or customise a component's appearance, follow this order:

Check existing props first — read the component's doc in
```
components/
```
and look for built-in variants, sizes, or visual props that already achieve what the user wants. Most common customisations are handled by props.
Use CSS variables and parts — if props don't cover it, check the component's own CSS Variables and CSS Parts sections in its doc. Then read
```
guides/customising-components.md
```
and
```
guides/css-variables.md
```
for general customisation patterns.
Reach out to the team — if neither props nor the supported CSS mechanisms solve the problem, advise the user to raise it in #help-designsystem on Slack. The team can confirm whether support is planned or give the green light for a custom override.

Avoid jumping straight to CSS hacks or shadow DOM workarounds — unsupported overrides break on upgrades and bypass the design system's accessibility and theming guarantees.

当用户需要覆盖或定制组件外观时，请遵循以下顺序：

优先检查现有属性 — 阅读
```
components/
```
目录下的组件文档，查找是否有内置的变体、尺寸或视觉属性可直接实现用户需求。大多数常见定制需求都可通过属性实现。
使用CSS变量和部件 — 若属性无法满足需求，请查看组件文档中的CSS变量和CSS部件章节。然后阅读
```
guides/customising-components.md
```
和
```
guides/css-variables.md
```
了解通用定制模式。
联系设计系统团队 — 若属性和支持的CSS机制都无法解决问题，请建议用户前往Slack的#help-designsystem频道反馈。团队可确认是否有计划支持该需求，或批准自定义覆盖方案。

避免直接使用CSS hacks或Shadow DOM变通方案——不被支持的覆盖方式会在版本升级时失效，且会违反设计系统的可访问性和主题适配保障。

Pre-flight checklist

预检清单

Before presenting code to the user, every item must pass:

PIE component used? — Always check
```
components/
```
first. PIE components ship with accessibility, RTL, and design tokens baked in — going custom loses all of that.
API matches the docs? — Every prop, slot, and event must exist in the component's doc. If it's undocumented, don't use it. If the API doesn't cover the use case, point the user to #help-designsystem on Slack.
Tokens are real alias tokens? — Every
```
--dt-*
```
variable must exist in
```
tokens/tokensMetadata.json
```
under
```
alias
```
, not
```
global
```
. Don't invent token names — CSS silently ignores them.
No bug workarounds? — If a component misbehaves, advise the user to report it rather than patching around it. Workarounds hide bugs from the team that can fix them for everyone.
Typography guide applied when relevant? — If the request touches fonts/typography or is a PIE audit,
```
guides/typography.md
```
must be read and checked.

向用户展示代码前，必须确保所有项均通过检查：

是否使用了PIE组件？ — 请先检查
```
components/
```
目录。PIE组件内置了可访问性、RTL适配和设计令牌支持——自定义组件会丢失这些特性。
API是否与文档一致？ — 所有属性、插槽和事件必须存在于组件文档中。若未文档化，请勿使用。若API无法满足需求，请引导用户前往Slack的#help-designsystem频道。
是否使用了真实的别名令牌？ — 所有
```
--dt-*
```
变量必须存在于
```
tokens/tokensMetadata.json
```
的
```
alias
```
分类下，而非
```
global
```
分类。请勿自定义令牌名称——CSS会静默忽略它们。
是否存在Bug变通方案？ — 若组件行为异常，请建议用户反馈问题，而非自行修补。变通方案会隐藏Bug，导致团队无法为所有人修复问题。
涉及排版时是否遵循了指南？ — 若需求涉及字体/排版，或为PIE审计，请确保已阅读并检查
```
guides/typography.md
```
的内容。