菜单
Guide for UI styling with semantic design system classes. Never use gray-* colors or arbitrary Tailwind utilities.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | design-system-conventions |
| description | Guide for UI styling with semantic design system classes. Never use gray-* colors or arbitrary Tailwind utilities. |
Enforce consistent styling using semantic design system classes. Prevent arbitrary Tailwind utilities and ensure visual consistency.
FORBIDDEN: text-gray-*, bg-gray-*, border-gray-*
USE INSTEAD: Semantic tokens from the design system.
| Purpose | Token | Example |
|---|---|---|
| Primary text | text-foreground | Main content |
| Strong text | text-foreground-strong | Headings |
| Muted text | text-foreground/80 | Secondary |
| Background | bg-background | Page background |
| Muted background | bg-muted | Cards, sections |
| Border | border-border | All borders |
| Primary button text | text-primary-foreground | Button labels |
Use /80, /70, /60 suffixes for opacity:
// ✅ CORRECT
<p className="text-foreground/80">Secondary text</p>
// ❌ WRONG
<p className="text-gray-600">Secondary text</p>
ALWAYS use semantic classes, NEVER arbitrary text-* utilities for typography.
| Class | Usage |
|---|---|
.heading-1 | Page titles (h1) |
.heading-2 | Section titles (h2) |
.heading-3 | Subsection titles (h3) |
.heading-4 | Minor headings (h4) |
.body-large | Large body text |
.body-normal | Default body text |
.body-small | Small body text |
.label | Form labels, captions |
// ✅ CORRECT
<h1 className="heading-1">Page Title</h1>
<p className="body-normal">Content here</p>
// ❌ WRONG
<h1 className="text-3xl md:text-4xl font-bold">Page Title</h1>
<p className="text-base">Content here</p>
Use semantic button classes (component coming in Week 4):
| Class | Usage |
|---|---|
.btn-primary | Primary actions |
.btn-neutral | Secondary actions |
.btn-outline | Tertiary actions |
.btn-muted | Low-emphasis actions |
// ✅ CORRECT
<button className="btn-primary">Submit</button>
// ❌ WRONG
<button className="bg-primary text-whiteCorp px-6 py-3 rounded-xl hover:bg-primarydark">
Submit
</button>
| Class | Usage |
|---|---|
.card-bordered | Border + subtle shadow |
.card-elevated | Stronger shadow, no border |
.card-body | Inner padding |
.card-header | Header section |
.card-footer | Footer section |
// ✅ CORRECT
<div className="card-bordered">
<div className="card-body">
<h3 className="heading-3">Card Title</h3>
<p className="body-normal">Content</p>
</div>
</div>
| Class | Usage |
|---|---|
.badge-primary | Red background (emphasis) |
.badge-default | Gray background (neutral) |
Replace repetitive flex patterns:
| Semantic Class | Replaces |
|---|---|
.flex-center | flex justify-center items-center |
.flex-between | flex justify-between items-center |
.flex-start | flex justify-start items-center |
.stack | flex flex-col gap-element-gap |
// ✅ CORRECT
<div className="flex-center gap-element-gap">
<Icon />
<span>Text</span>
</div>
// ❌ WRONG
<div className="flex justify-center items-center gap-4">
<Icon />
<span>Text</span>
</div>
| Token | Usage |
|---|---|
py-section-y, px-section-x | Section spacing |
p-card-padding | Card inner padding |
gap-element-gap | Default gaps |
Allowed: One-off micro-spacing inside leaf components (gap-1, gap-2, p-1, p-2)
Not allowed:
Rule: If repeated → create/extend a semantic token instead.
| Token | Usage | Value |
|---|---|---|
rounded-button | Buttons | 8px |
rounded-card | Cards | 12px |
rounded-input | Form inputs | 8px |
rounded-badge | Pills/badges | full |
❌ primarydark, primarySoft, whiteCorp, darkCorp, blackCorp, fullBlackCorp, bColor
Use semantic tokens instead.
Current Phase: Week 0 - Foundation
When modifying existing components:
/docs/reference-data.md for prioritytext-xl font-bold)gray-*)flex-center vs manual flex)Guide for adding environment variables. Use when adding new env vars to ensure all 5 locations are updated (code, env files, Coolify, workflow, GitHub secrets).
Enforce the internal API proxy layer pattern. Use when adding API endpoints, fetching data from backend, implementing HMAC signing, or working with lib/api/* or app/api/*.
Best practices for React 19 and Next.js 16 App Router. Use when creating components, hooks, or pages. Enforces server-first rendering, proper client boundaries, and modern React patterns.
MANDATORY checklist before writing ANY new code. Use this skill FIRST before implementing any feature, component, utility, type, or hook. Enforces DRY principle and existing pattern reuse.
Evaluate external PR suggestions (Gemini, CodeRabbit) against project conventions. Use when asked to review or agree with external code review comments.
Guide for CSP, security headers, and external scripts. Use fetchWithHmac for APIs, safeFetch for external services.