figma-to-spirit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Figma to Spirit Component Conversion

Figma 转 Spirit 组件转换

Component Documentation

组件文档

For detailed API references, examples, and common mistakes:

Layout Components - Flex, Grid, Stack, Box, Section, Container
Typography Components - Heading, Text
Card Components - Card, CardLink, CardTitle, CardDescription

如需详细的API参考、示例和常见问题说明，请查看：

布局组件 - Flex、Grid、Stack、Box、Section、Container
排版组件 - Heading、Text
卡片组件 - Card、CardLink、CardTitle、CardDescription

Core Principles

核心原则

ALWAYS use Spirit Web React components - Never create custom components or use raw HTML/CSS when a Spirit component exists
NEVER use inline CSS - Use component props and styling props instead. Only use
```
UNSAFE_style
```
or
```
UNSAFE_className
```
as a last resort
Use this skill's documentation as the primary reference:
- Check Layout Components for Flex, Grid, Stack, Box, Section, Container
- Check Typography Components for Heading, Text
- These docs contain API references, common mistakes, and correct prop values
Read props from Figma CodeConnect EXACTLY:
- Call
```
get_code_connect_map
```
  to get CodeConnect snippets from Figma
- Use all props from CodeConnect exactly as shown - never override or change them
- If CodeConnect shows
```
Card
```
  , use
```
Card
```
  (not
```
Flex
```
  or
```
Box
```
  )
- CRITICAL - Icon names: If CodeConnect shows
```
iconName="placeholder"
```
  , use EXACTLY
```
"placeholder"
```
  - NEVER substitute with your own icon choices
NEVER substitute icon names:
- Use the EXACT
```
iconName
```
  value from Figma/CodeConnect (even if it's
```
"placeholder"
```
  )
- Do NOT choose "semantically appropriate" icons - that is the designer's decision, not yours
- Placeholder icons are intentional - they indicate the final icon hasn't been decided yet
- Wrong: Seeing
```
iconName="placeholder"
```
  and changing it to
```
"shield-dualtone"
```
  or
```
"folder"
```
- Correct: Using
```
iconName="placeholder"
```
  exactly as shown
Use https://picsum.photos/ for all image placeholders - Format:
```
https://picsum.photos/seed/{identifier}/{width}/{height}
```
DO NOT set props to default values - Only set props when they differ from component defaults (check API Reference tables in component docs)
Context7 MCP is a LAST RESORT - Only use for components not documented in this skill:
- Call
```
resolve-library-id
```
  with
```
@alma-oss/spirit-design-system
```
- Call
```
query-docs
```
  with
```
/alma-oss/spirit-design-system
```
  and the component name
ASK when uncertain - If you encounter a layout, pattern, or problem you don't know how to implement with Spirit components:
- DO NOT guess or improvise - Stop and ask the user for guidance
- Describe what you're trying to achieve and what's unclear
- Ask if there's a specific Spirit component or pattern to use
- Wait for the user's response before proceeding
- This prevents incorrect implementations and teaches you new patterns for future use

始终使用Spirit Web React组件 - 当存在Spirit组件时，绝不要创建自定义组件或使用原生HTML/CSS
绝不使用内联CSS - 改用组件属性和样式属性。仅在万不得已时使用
```
UNSAFE_style
```
或
```
UNSAFE_className
```
以本技能的文档为主要参考依据:
- 查看布局组件了解Flex、Grid、Stack、Box、Section、Container的相关内容
- 查看排版组件了解Heading、Text的相关内容
- 这些文档包含API参考、常见错误说明和正确的属性值
严格按照Figma CodeConnect读取属性:
- 调用
```
get_code_connect_map
```
  从Figma获取CodeConnect代码片段
- 严格按照CodeConnect显示的所有属性使用，绝不要覆盖或修改
- 如果CodeConnect显示
```
Card
```
  ，就使用
```
Card
```
  （不要用
```
Flex
```
  或
```
Box
```
  ）
- 关键注意 - 图标名称：如果CodeConnect显示
```
iconName="placeholder"
```
  ，必须严格使用
```
"placeholder"
```
  - 绝不要自行替换图标
绝不替换图标名称:
- 严格使用Figma/CodeConnect提供的
```
iconName
```
  值（即使是
```
"placeholder"
```
  ）
- 不要选择“语义上合适”的图标 - 这是设计师的决策，而非开发者的
- 占位符图标是有意设置的 - 表示最终图标尚未确定
- 错误示例：看到
```
iconName="placeholder"
```
  后将其改为
```
"shield-dualtone"
```
  或
```
"folder"
```
- 正确示例：严格使用
```
iconName="placeholder"
```
所有图片占位符使用https://picsum.photos/ - 格式：
```
https://picsum.photos/seed/{identifier}/{width}/{height}
```
不要为属性设置默认值 - 仅当属性与组件默认值不同时才进行设置（请查看组件文档中的API参考表格）
Context7 MCP是最后的手段 - 仅用于本技能文档中未提及的组件:
- 调用
```
resolve-library-id
```
  ，参数为
```
@alma-oss/spirit-design-system
```
- 调用
```
query-docs
```
  ，参数为
```
/alma-oss/spirit-design-system
```
  和组件名称
不确定时请询问 - 如果遇到不知道如何用Spirit组件实现的布局、模式或问题:
- 不要猜测或自行发挥 - 停止操作并向用户寻求指导
- 描述你想要实现的内容以及不清楚的地方
- 询问是否有特定的Spirit组件或模式可以使用
- 等待用户回复后再继续
- 这可以避免错误实现，同时帮助你学习未来可用的新模式

Workflow

工作流程

Step 1: Analyze Figma Structure

步骤1：分析Figma结构

CRITICAL: Match Figma layer hierarchy exactly. Each Figma autolayout layer should have a corresponding Spirit layout component.

Extract from Figma:

Component names - If Figma shows "Card Media NEW", "Button", etc., use the corresponding Spirit component
Layer names for props - "Section XLarge" →
```
size="xlarge"
```
, "Button Large" →
```
size="large"
```
Icon names EXACTLY - If CodeConnect shows
```
iconName="placeholder"
```
, use
```
"placeholder"
```
- NEVER substitute your own icon choices

Spacing values - Read

gap

from autolayout properties:

gap-[var(--global/spacing/space-1400,64px)]

→

spacing="space-1400"

Color tokens - Read exact tokens from layer properties:
```
accent-01-subtle
```
,
```
accent-02-subtle
```
, etc.
All wrapper layers - Each Figma layer with autolayout MUST have a corresponding Spirit component
Alignment - Check
```
align-items
```
and
```
justify-content
```
properties
Fill width/height - Figma uses
```
align-self: stretch
```
for "fill" dimensions
Max-width constraints - Check which specific layer has max-width, apply only to that layer
Padding values - Check for
```
pr
```
,
```
pl
```
,
```
pt
```
,
```
pb
```
,
```
px
```
,
```
py
```
on layers; apply using Box padding props
Link colors - Check for
```
themed/link/...
```
tokens; these indicate clickable elements (use CardLink for Card titles)

Layer Structure Matching Example:

text

Figma Layers:                          Spirit Components:
├── Section XLarge                     <Section size="xlarge">
│   └── Container XLarge                 (included in Section)
│       └── Content (gap: 32px)          <Flex spacing="space-1000">
│           ├── Heading (max-w: 800px)     <Box UNSAFE_style={{ maxWidth }}>
│           │   ├── Tag                        <Flex spacing="space-700">
│           │   └── Composition                  <Tag />
│           │       ├── Title                    <Flex spacing="space-900">
│           │       ├── Description                <Heading />
│           │       └── ActionGroup                <Text />
│           │                                      <ActionGroup />
│           └── Column (4 items)             </Flex></Box>
│               ├── number                   <Grid cols={4}>
│               ├── number                     <StatCard />
│               ├── number                     ...
│               └── number                   </Grid>

**关键要求：严格匹配Figma层级结构。**每个Figma自动布局图层都应对应一个Spirit布局组件。

从Figma提取以下信息：

组件名称 - 如果Figma显示“Card Media NEW”、“Button”等，使用对应的Spirit组件
用于属性的图层名称 - “Section XLarge” →
```
size="xlarge"
```
，“Button Large” →
```
size="large"
```
严格匹配图标名称 - 如果CodeConnect显示
```
iconName="placeholder"
```
，必须使用
```
"placeholder"
```
- 绝不要自行替换图标

间距值 - 从自动布局属性中读取

gap

：

gap-[var(--global/spacing/space-1400,64px)]

→

spacing="space-1400"

颜色令牌 - 从图层属性中读取确切的令牌值：
```
accent-01-subtle
```
、
```
accent-02-subtle
```
等
所有包装图层 - 每个带有自动布局的Figma图层都必须有对应的Spirit组件
对齐方式 - 检查
```
align-items
```
和
```
justify-content
```
属性
填充宽度/高度 - Figma使用
```
align-self: stretch
```
表示“填充”尺寸
最大宽度约束 - 检查哪个特定图层有最大宽度，仅对该图层应用约束
内边距值 - 检查图层上的
```
pr
```
、
```
pl
```
、
```
pt
```
、
```
pb
```
、
```
px
```
、
```
py
```
；使用Box的内边距属性进行设置
链接颜色 - 检查是否有
```
themed/link/...
```
令牌；这些表示可点击元素（对卡片标题使用CardLink）

层级结构匹配示例：

text

Figma Layers:                          Spirit Components:
├── Section XLarge                     <Section size="xlarge">
│   └── Container XLarge                 (包含在Section中)
│       └── Content (gap: 32px)          <Flex spacing="space-1000">
│           ├── Heading (max-w: 800px)     <Box UNSAFE_style={{ maxWidth }}>
│           │   ├── Tag                        <Flex spacing="space-700">
│           │   └── Composition                  <Tag />
│           │       ├── Title                    <Flex spacing="space-900">
│           │       ├── Description                <Heading />
│           │       └── ActionGroup                <Text />
│           │                                      <ActionGroup />
│           └── Column (4 items)             </Flex></Box>
│               ├── number                   <Grid cols={4}>
│               ├── number                     <StatCard />
│               ├── number                     ...
│               └── number                   </Grid>

Step 2: Choose Container Type

步骤2：选择容器类型

Figma Pattern	Spirit Component
"Design Block" or main page section	`Section`
Need to constrain content width	`Section containerProps={{ size: "..." }}`
Full-width section content	`Section hasContainer={false}`

Important: Section includes Container by default - don't nest another Container inside.

Figma 模式	Spirit 组件
"设计区块"或主页面区域	`Section`
需要限制内容宽度	`Section containerProps={{ size: "..." }}`
全宽区域内容	`Section hasContainer={false}`

重要提示：Section默认包含Container - 不要在Section内部嵌套另一个Container。

Step 3: Choose Layout Pattern

步骤3：选择布局模式

Figma Pattern	Spirit Component	Notes
Uniform repeatable items (cards, stats)	`Grid`	Set `cols` prop, Grid handles row wrapping
Max-width centered content	`Section containerProps={{ size: "..." }}`	NOT Grid
Single row or column	`Flex`	`direction="horizontal"` or `"vertical"`
Columns with different structures	Multiple `Flex` columns	Horizontal Flex wrapping vertical Flex children
Vertical list with dividers	`Stack`	Use `hasIntermediateDividers`
Only styling (background, border)	`Box`	No layout capabilities
Styling + layout combined	`Box elementType={Flex}`	Combines styling and layout

IMPORTANT: Check Layout Components for API reference, prop values, and common mistakes before implementing.

Figma 模式	Spirit 组件	说明
统一可重复项（卡片、统计数据）	`Grid`	设置 `cols` 属性，Grid会自动处理换行
居中的最大宽度内容	`Section containerProps={{ size: "..." }}`	不要使用Grid
单行或单列	`Flex`	`direction="horizontal"` 或 `"vertical"`
结构不同的列	多个 `Flex` 列	水平Flex包裹垂直Flex子元素
带有分隔线的垂直列表	`Stack`	使用 `hasIntermediateDividers` 属性
仅用于样式（背景、边框）	`Box`	无布局功能
样式+布局组合	`Box elementType={Flex}`	结合样式和布局功能

重要提示：在实现前，请查看布局组件获取API参考、属性值和常见错误说明。

Step 4: Set Alignment Props

步骤4：设置对齐属性

Check Figma Children for W-Full Before Setting Alignment

设置对齐前检查Figma子元素是否为W-Full

When analyzing Figma, check if children have

w-full

(full width) or

shrink-0 w-full

If children have
w-full
→ Parent should use
```
alignmentX="stretch"
```
so children fill the container width
If children do NOT have
w-full
→ Parent should use
```
alignmentX="left"
```
to prevent unwanted width expansion
Children with both
w-full
AND
max-width
→ Parent uses
```
alignmentX="stretch"
```
, child stretches UP TO its max-width constraint

jsx

// WRONG - alignmentX="left" prevents children from filling width even when Figma shows w-full
<Flex direction="vertical" spacing="space-1000" alignmentX="left">
  <Box UNSAFE_style={{ maxWidth: "800px" }}>...</Box>  {/* Won't stretch to 800px */}
  <Grid cols={4}>...</Grid>  {/* Won't fill container width */}
</Flex>

// CORRECT - alignmentX="stretch" lets children fill width (respecting their max-width if set)
<Flex direction="vertical" spacing="space-1000" alignmentX="stretch">
  <Box UNSAFE_style={{ maxWidth: "800px" }}>...</Box>  {/* Stretches up to 800px */}
  <Grid cols={4}>...</Grid>  {/* Fills container width */}
</Flex>

分析Figma时，检查子元素是否有

w-full

（全宽）或

shrink-0 w-full

：

如果子元素有
w-full
→ 父组件应使用
```
alignmentX="stretch"
```
，使子元素填充容器宽度
如果子元素没有
w-full
→ 父组件应使用
```
alignmentX="left"
```
，防止不必要的宽度扩展
子元素同时有
w-full
和
max-width
→ 父组件使用
```
alignmentX="stretch"
```
，子元素会拉伸到其最大宽度约束值

jsx

// 错误示例 - alignmentX="left"会阻止子元素填充宽度，即使Figma显示w-full
<Flex direction="vertical" spacing="space-1000" alignmentX="left">
  <Box UNSAFE_style={{ maxWidth: "800px" }}>...</Box>  {/* 无法拉伸到800px */}
  <Grid cols={4}>...</Grid>  {/* 无法填充容器宽度 */}
</Flex>

// 正确示例 - alignmentX="stretch"允许子元素填充宽度（同时遵守其最大宽度约束）
<Flex direction="vertical" spacing="space-1000" alignmentX="stretch">
  <Box UNSAFE_style={{ maxWidth: "800px" }}>...</Box>  {/* 拉伸至最大800px */}
  <Grid cols={4}>...</Grid>  {/* 填充容器宽度 */}
</Flex>

Value Mapping (CSS → Spirit)

值映射（CSS → Spirit）

CSS Value	alignmentX	alignmentY
`flex-start`	`left`	`top`
`center`	`center`	`center`
`flex-end`	`right`	`bottom`
`stretch`	`stretch`	`stretch`

Direction-based mapping:

Vertical Flex:

align-items

→

alignmentX

justify-content

→

alignmentY

Horizontal Flex:

justify-content

→

alignmentX

align-items

→

alignmentY

Important: Always set

alignmentX

explicitly on vertical Flex. Choose

stretch

when Figma children have

w-full

, otherwise use

left

CSS 值	alignmentX	alignmentY
`flex-start`	`left`	`top`
`center`	`center`	`center`
`flex-end`	`right`	`bottom`
`stretch`	`stretch`	`stretch`

基于方向的映射：

垂直Flex：

align-items

→

alignmentX

，

justify-content

→

alignmentY

水平Flex：

justify-content

→

alignmentX

，

align-items

→

alignmentY

重要提示：始终为垂直Flex显式设置

alignmentX

。当Figma子元素有

w-full

时选择

stretch

，否则使用

left

。

Step 5: Set Typography

步骤5：设置排版

Figma Text Style	Spirit Component	Key Props
Heading styles	`Heading`	`elementType` (REQUIRED), `size` , `emphasis`
Body text	`Text`	`elementType` , `size` , `emphasis`

Accessibility rules:

Use
```
h1-h6
```
only for actual semantic headings
For styled text that isn't a heading (stats, labels):
```
elementType="div"
```
or
```
"span"
```
Maintain heading hierarchy (h1 → h2 → h3, don't skip levels)
Add
```
marginBottom="space-0"
```
to typography elements that have siblings AFTER them in Flex/Grid/Stack (last-child elements don't need it)

Figma 文本样式	Spirit 组件	关键属性
标题样式	`Heading`	`elementType` （必填）、 `size` 、 `emphasis`
正文文本	`Text`	`elementType` 、 `size` 、 `emphasis`

无障碍规则：

仅对实际语义化标题使用
```
h1-h6
```
对于非标题的样式文本（统计数据、标签）：使用
```
elementType="div"
```
或
```
"span"
```
保持标题层级（h1 → h2 → h3，不要跳过层级）
对Flex/Grid/Stack中后面还有同级元素的排版元素添加
```
marginBottom="space-0"
```
（最后一个子元素不需要）

Use Full Accent Color Token Names

使用完整的强调色令牌名称

Heading and Text accept accent colors, but you must use the full token name (not short form).

jsx

// WRONG - short form "accent-02" causes TypeScript lint error
<Heading elementType="div" size="xlarge" textColor="accent-02">300K+</Heading>

// CORRECT - use full token name "accent-02-basic"
<Heading elementType="div" size="xlarge" textColor="accent-02-basic" marginBottom="space-0">300K+</Heading>

Valid accent tokens:

accent-01-basic

accent-01-subtle

accent-02-basic

accent-02-subtle

, etc.

IMPORTANT: Check Typography Components for API reference, prop values, and common mistakes before implementing.

Heading和Text组件支持强调色，但必须使用完整的令牌名称（而非简写形式）。

jsx

// 错误示例 - 简写形式"accent-02"会导致TypeScript lint错误
<Heading elementType="div" size="xlarge" textColor="accent-02">300K+</Heading>

// 正确示例 - 使用完整令牌名称"accent-02-basic"
<Heading elementType="div" size="xlarge" textColor="accent-02-basic" marginBottom="space-0">300K+</Heading>

有效的强调色令牌：

accent-01-basic

、

accent-01-subtle

、

accent-02-basic

、

accent-02-subtle

等。

重要提示：在实现前，请查看排版组件获取API参考、属性值和常见错误说明。

Step 6: Responsive Design

步骤6：响应式设计

When only one breakpoint is provided in Figma:

Identify the breakpoint - Check Figma frame width (mobile < 768px, tablet 768-1024px, desktop > 1024px)
Add responsive props for other breakpoints:

jsx

// Grid: reduce columns on smaller screens
<Grid cols={{ mobile: 1, tablet: 2, desktop: 4 }} />

// Flex: change direction on mobile
<Flex direction={{ mobile: 'vertical', tablet: 'horizontal' }} />

// Spacing: reduce on smaller screens
<Flex spacing={{ mobile: 'space-400', tablet: 'space-800', desktop: 'space-1200' }} />

Design must match exactly on the provided breakpoint

当Figma仅提供一个断点时：

识别断点 - 检查Figma框架宽度（移动端 < 768px，平板端768-1024px，桌面端 > 1024px）
为其他断点添加响应式属性:

jsx

// Grid：在小屏幕上减少列数
<Grid cols={{ mobile: 1, tablet: 2, desktop: 4 }} />

// Flex：在移动端改变方向
<Flex direction={{ mobile: 'vertical', tablet: 'horizontal' }} />

// 间距：在小屏幕上缩小间距
<Flex spacing={{ mobile: 'space-400', tablet: 'space-800', desktop: 'space-1200' }} />

提供的断点上的设计必须完全匹配

Step 7: Crosscheck Design

步骤7：交叉检查设计

Before finalizing, re-fetch Figma data and verify:

CodeConnect snippets match code exactly - Every prop from CodeConnect is present
Component names match - Spirit components used match Figma component names
Icon names match EXACTLY - If CodeConnect shows
```
iconName="placeholder"
```
, code must use
```
"placeholder"
```
(NOT a substituted icon)
Spacing values match - Read from Figma autolayout properties
Color tokens match - Exact tokens from Figma layer properties
Layer structure matches - All wrapper layers represented
Alignment matches - Explicit alignment props matching Figma

在最终确定前，重新获取Figma数据并验证：

CodeConnect代码片段与代码完全匹配 - CodeConnect中的每个属性都已包含
组件名称匹配 - 使用的Spirit组件与Figma组件名称匹配
图标名称完全匹配 - 如果CodeConnect显示
```
iconName="placeholder"
```
，代码中必须使用
```
"placeholder"
```
（不要替换图标）
间距值匹配 - 从Figma自动布局属性中读取
颜色令牌匹配 - 与Figma图层属性中的令牌完全一致
层级结构匹配 - 所有包装图层都已在代码中体现
对齐方式匹配 - 显式的对齐属性与Figma一致

Quick Reference

快速参考

Space Tokens

间距令牌

Token Range	Typical Use
`space-100` - `space-300`	Tight spacing (icons, inline)
`space-400` - `space-600`	Small (within components)
`space-700` - `space-900`	Medium (between components)
`space-1000` - `space-1200`	Large (section padding)
`space-1300` - `space-1600`	Extra large (page sections)

令牌范围	典型用途
`space-100` - `space-300`	紧凑间距（图标、内联元素）
`space-400` - `space-600`	小间距（组件内部）
`space-700` - `space-900`	中等间距（组件之间）
`space-1000` - `space-1200`	大间距（区域内边距）
`space-1300` - `space-1600`	超大间距（页面区域）

Color Token Examples

颜色令牌示例

Type	Examples
Background	`primary` , `secondary` , `tertiary` , `accent-01-subtle` , `accent-02-subtle` , `neutral-subtle`
Text	`primary` , `secondary` , `tertiary` , `inverted` , `disabled` , `accent-01-basic` , `accent-02-basic`
Border	`basic` , `focus` , accent colors

Note: Always use full token names for accent colors (

accent-02-basic

, not

accent-02

). See Typography Components.

类型	示例
背景色	`primary` 、 `secondary` 、 `tertiary` 、 `accent-01-subtle` 、 `accent-02-subtle` 、 `neutral-subtle`
文本色	`primary` 、 `secondary` 、 `tertiary` 、 `inverted` 、 `disabled` 、 `accent-01-basic` 、 `accent-02-basic`
边框色	`basic` 、 `focus` 、强调色

注意：强调色请始终使用完整令牌名称（

accent-02-basic

，而非

accent-02

）。请查看排版组件。

Link Color Tokens (CRITICAL for Card Detection)

链接颜色令牌（卡片检测的关键）

When Figma shows these color tokens on text, it indicates the element should be a link:

Figma Token	Meaning
`themed/link/primary/state-default`	Primary link color - use CardLink for Card titles
`themed/link/primary/state-hover`	Link hover state - CardLink handles automatically
`themed/link/secondary/...`	Secondary link - use CardLink or Link component

If CardTitle has a link color token, use

CardLink

inside

CardTitle

, NOT Heading with textColor.

See Card Components for full documentation.

当Figma文本上显示以下颜色令牌时，表示该元素应为链接：

Figma 令牌	含义
`themed/link/primary/state-default`	主链接颜色 - 卡片标题使用CardLink
`themed/link/primary/state-hover`	链接悬停状态 - CardLink会自动处理
`themed/link/secondary/...`	次要链接 - 使用CardLink或Link组件

如果CardTitle带有链接颜色令牌，请在CardTitle内部使用

CardLink

，而非设置textColor的Heading。

请查看卡片组件获取完整文档。

Implementation Checklist

实现检查清单

Before finalizing code:

Figma Data Extraction:

[ ] CodeConnect snippets used exactly as provided
[ ] Component names verified (Figma → Spirit mapping)
[ ] Icon names used EXACTLY as shown (if
```
iconName="placeholder"
```
, use
```
"placeholder"
```
- NEVER substitute)
[ ] Layer names checked for size/color/variant props
[ ] Spacing values read from Figma autolayout properties
[ ] Color tokens read exactly from Figma layer properties

Layout:

[ ] Layout components have explicit alignment props
[ ] Vertical Flex has
```
alignmentX
```
set explicitly
[ ] Grid has both
```
alignmentX
```
and
```
alignmentY
```
set
[ ] Figma "fill" width uses parent
```
alignmentX="stretch"
```
[ ] All Figma wrapper layers represented in code (match hierarchy)
[ ] Uniform items use Grid, different structures use Flex columns
[ ] Max-width constraints applied to correct innermost wrapper only

Typography:

[ ] Heading
```
elementType
```
set appropriately (h1-h6 for headings, div/span for styled text)
[ ] Heading hierarchy maintained (no skipped levels)
[ ]
```
marginBottom="space-0"
```
added to typography with siblings after them (not needed on last-child elements)
[ ] Accent text colors use full token names (
```
accent-02-basic
```
, NOT
```
accent-02
```
)

Styling:

[ ] No inline CSS (except
```
UNSAFE_style
```
as last resort)
[ ]
```
UNSAFE_style maxWidth
```
only on innermost wrapper containing constrained content
[ ] Box + Flex pattern used when both styling and layout needed
[ ] Box colors/borders match Figma exactly
[ ] Padding values (
```
pr
```
,
```
pl
```
,
```
pt
```
,
```
pb
```
,
```
px
```
,
```
py
```
) from Figma applied using Box props or
```
Flex elementType={Box}
```

Cards & Links:

[ ] CardTitle with
```
themed/link/...
```
color tokens uses
```
CardLink
```
(not Heading with textColor)
[ ] CardLink used inside CardTitle for clickable cards
[ ]
```
isHeading
```
set on CardTitle when appropriate
[ ] Horizontal Card with IconBox in CardArtwork uses Flex wrapper for vertical centering (see Card Components)

Responsive:

[ ] Responsive props added for other breakpoints
[ ] Design matches exactly on provided breakpoint

Images:

[ ] Placeholders use picsum.photos format

Uncertainty:

[ ] Asked user for guidance on any layouts/patterns you weren't sure how to implement (don't guess!)

在最终确定代码前：

Figma数据提取：

严格使用提供的CodeConnect代码片段
已验证组件名称（Figma → Spirit映射）
图标名称严格按照显示使用（如果是
```
iconName="placeholder"
```
，必须使用
```
"placeholder"
```
- 绝不要替换）
已检查图层名称以获取尺寸/颜色/变体属性
已从Figma自动布局属性中读取间距值
已从Figma图层属性中准确读取颜色令牌

布局：

布局组件具有显式的对齐属性
垂直Flex已显式设置
```
alignmentX
```
Grid已设置
```
alignmentX
```
和
```
alignmentY
```
Figma的“填充”宽度使用了父组件的
```
alignmentX="stretch"
```
所有Figma包装图层都已在代码中体现（匹配层级结构）
统一项使用Grid，不同结构使用Flex列
最大宽度约束仅应用于正确的最内层包装器

排版：

Heading的
```
elementType
```
设置恰当（标题使用h1-h6，样式文本使用div/span）
保持了标题层级（没有跳过层级）
对后面有同级元素的排版元素添加了
```
marginBottom="space-0"
```
（最后一个子元素不需要）
强调文本颜色使用了完整令牌名称（
```
accent-02-basic
```
，而非
```
accent-02
```
）

样式：

没有使用内联CSS（万不得已时除外）
```
UNSAFE_style maxWidth
```
仅应用于包含约束内容的最内层包装器
当同时需要样式和布局时使用Box + Flex模式
Box的颜色/边框与Figma完全匹配
从Figma获取的内边距值（
```
pr
```
、
```
pl
```
、
```
pt
```
、
```
pb
```
、
```
px
```
、
```
py
```
）使用Box属性或
```
Flex elementType={Box}
```
进行设置

卡片与链接：

带有
```
themed/link/...
```
颜色令牌的CardTitle使用了
```
CardLink
```
（而非设置textColor的Heading）
可点击卡片的CardTitle内部使用了CardLink
已根据情况为CardTitle设置
```
isHeading
```
CardArtwork中带有IconBox的水平卡片使用Flex包装器实现垂直居中（请查看卡片组件）

响应式：

已为其他断点添加响应式属性
提供的断点上的设计完全匹配

图片：

占位符使用picsum.photos格式

不确定的情况：

对任何不知道如何用Spirit组件实现的布局/模式/问题向用户寻求了指导（不要猜测！）

Common Mistakes

常见错误

1. Substituting Icon Names

1. 替换图标名称

CRITICAL: Never substitute icon names with your own choices.

jsx

// WRONG - Developer substituted "semantically appropriate" icons
<Icon name="shield-dualtone" />  // Was "placeholder" in Figma
<Icon name="folder" />           // Was "placeholder" in Figma
<Icon name="reload" />           // Was "placeholder" in Figma

// CORRECT - Use EXACTLY what Figma/CodeConnect specifies
<Icon name="placeholder" />      // Matches Figma exactly
<Icon name="placeholder" />      // Matches Figma exactly
<Icon name="placeholder" />      // Matches Figma exactly

Why this is wrong:

Placeholder icons indicate the designer hasn't finalized the icon choice yet
Choosing icons is a design decision, not a developer decision
Your "semantically appropriate" choice may conflict with the design system's icon usage patterns
This violates the core principle: "Use all props from CodeConnect exactly as shown"

The rule: If CodeConnect shows

iconName="placeholder"

, your code MUST use

iconName="placeholder"

. Period.

关键要求：绝不要自行替换图标名称。

jsx

// 错误示例 - 开发者替换了“语义上合适”的图标
<Icon name="shield-dualtone" />  // Figma中是"placeholder"
<Icon name="folder" />           // Figma中是"placeholder"
<Icon name="reload" />           // Figma中是"placeholder"

// 正确示例 - 严格使用Figma/CodeConnect指定的内容
<Icon name="placeholder" />      // 与Figma完全匹配
<Icon name="placeholder" />      // 与Figma完全匹配
<Icon name="placeholder" />      // 与Figma完全匹配

错误原因：

占位符图标表示设计师尚未最终确定图标选择
选择图标是设计决策，而非开发决策
你认为“语义上合适”的选择可能与设计系统的图标使用模式冲突
这违反了核心原则：“严格按照CodeConnect显示的所有属性使用”

**规则：**如果CodeConnect显示

iconName="placeholder"

，你的代码必须使用

iconName="placeholder"

。就这么简单。