Component Lifecycle

🧬 Component Lifecycle — Create, Audit & Fix

Complete lifecycle for design system components: from design analysis → token creation → documentation → validation → audit → batch fix.

How to Use This Skill

This skill is organized in 3 layers:

1. This file (SKILL.md) — Standards, workflow, audit. Read this first.
2. references/ — Deep-dive rules and templates. Read only what's relevant.
3. Automated scripts — Run audit-components.js for machine-checkable completeness.

Quick navigation:

Pre-read Requirements

Before creating a NEW component, read these skills first:

⚠️ UX Quick Reference — Apply these rules DURING coding, not after:

Rule	Requirement	Token
T1	Interactive/body text ≥ 14px desktop, ≥ 16px mobile	--font-size-sm minimum
T10	Module title = 16px semibold	--font-size-base + --font-weight-semibold
T11	Overlay title = 18px semibold	--font-size-lg + --font-weight-semibold
B7	Every overlay closes on Escape key	JS keydown handler
F1	Focus ring uses token, never hide outline	:focus-visible + var(--ring)
F3	Modal/overlay traps focus + Escape close	JS focus trap
H1	Every action → visual feedback ≤ 100ms	CSS transition
S1	No hardcoded px/rem for spacing	calc(var(--spacing) * N) or semantic var(--comp-padding-*)
M1	Respect prefers-reduced-motion	@media query

🚫 PRE-CODE GATE — Mandatory Token Resolution

RULE: KHÔNG ĐƯỢC viết code (inline style, CSS, HTML) cho bất kỳ component nào khi chưa hoàn thành bảng resolution bên dưới. Copy bảng này vào response TRƯỚC KHI code.

🔒 TOKEN RESOLUTION TABLE — {component name}
═══════════════════════════════════════════════════

□ Label font-size:
  UX tier = _________ (§6.1: Body/Label/Caption?)
  UX range = _________ px (e.g. Caption = 11-12px)
  Token chosen = var(--_________)
  Token actual value = _____ px
  In UX range? ☐ YES ☐ NO → pick another token

□ Label line-height:
  UX rule = T3: _________ (e.g. caption = 1.4-1.5)
  Token = var(--font-leading-_________)

□ Icon size:
  Spec = ___ px
  Token = var(--icon-___)

□ Gap (icon → label):
  S2 check: multiple of 4px? ☐ YES ☐ NO
  Token = var(--spacing-___) = ___ px

□ Container height:
  Spec = ___ px (source: _________)
  Token = var(--spacing-___) = ___ px

□ Touch target:
  R3: ≥ 44×44px? ☐ YES → min-width/min-height = 44px

□ Indicator/pill:
  Size = ___ × ___ px (source: _________)
  Radius = var(--radius-___)
  bg/fg pair: bg = var(--___), fg = var(--___)

☐ ALL rows resolved → proceed to code
☐ ANY row fails → fix token choice, DO NOT change spec

⚠️ Direction of truth: UX Research → Spec → Token → Code. Nếu token value nằm ngoài UX range → CHỌN TOKEN KHÁC, KHÔNG sửa spec.

1. Eight Categories

Every component MUST cover these 8 token categories (≥7/8 = enterprise-grade):

2. Token Naming Convention

{component}.{element}.{property}[.{variant}]

✅ button.height.sm, button.color.primary-bg, button.transition
❌ button.custom-height, button.#3B82F6

📖 Full naming rules, title size conventions, and bg/fg pair details: references/token-naming-states.md

3. Critical Rules (Quick Reference)

bg/fg Pair Rule (shadcn)

📖 Full rules: references/token-naming-states.md §3

Every color variant MUST have a paired bg + fg:

"primary-bg":  { "$value": "{base.primary}" },
"primary-fg":  { "$value": "{base.primary-foreground}" }

In CSS/HTML: Any element with background: var(--primary) MUST also set color: var(--primary-foreground). Applies to classes, inline styles, and pseudo-elements.

Slot Anatomy (Header / Body / Footer)

📖 Full rules: references/layout-slots-tiers.md §1

Container-level components MUST use generic .slot-header / .slot-body / .slot-footer classes:

<!-- ✅ CORRECT -->
<div class="container-module slotted">
    <div class="slot-header">...</div>
    <div class="slot-body">...</div>
    <div class="slot-footer">...</div>
</div>

<!-- ❌ WRONG — custom per-component slots -->
<div class="card">
    <div class="card-header">...</div>
</div>

Button Pairing (Action Group Hierarchy)

📖 Full rules: references/patterns-dividers.md §1

Divider Rules

📖 Full rules: references/patterns-dividers.md §2

Priority: SPACING > DIVIDER > BORDER. Always try spacing tokens first.

Top 3 rules:

• D1: Spacing first — divider is last resort
• D2: Max 2 consecutive full-width dividers in viewport
• D9: No divider inside card — use spacing or subtle bg shift

4. Component Priority Tiers

5. What to Learn From Each System

Create Workflow

// turbo-all

Step 1: Check Existence

Verify the component doesn't already exist:

## Check ATOMIC-MAPPING.md for existing entry
findstr /i "{component-name}" "design-system\components md\ATOMIC-MAPPING.md"

→ If it exists, STOP. Use Audit & Fix instead.

Step 2: Design Analysis (5-Part Output)

📖 Full template and examples: references/design-analysis.md

Perform a thorough analysis BEFORE creating any token JSON:

CRITICAL: Only proceed to Step 3 when the User has approved all gaps (if any).

Step 3: Add Component to ATOMIC-MAPPING.md

File: design-system/components md/ATOMIC-MAPPING.md

Add a new ### {component-name} section answering 4 questions:

⚠️ NO component token JSON files. Components map DIRECTLY to semantic tokens. See existing entries in ATOMIC-MAPPING.md for patterns.

Step 4: Create Component Documentation

File: design-system/components md/{name}.md

Include: description, variants, states, token mapping, usage guidelines, anti-patterns.

Step 4b: Add Slot Map + Code Connect Entry (MANDATORY — ENF-6)

⚠️ GATE: Component is NOT complete without Figma Slot mapping.

1. Check knowledge/slot-manifest.json for existing slot definitions
2. Read knowledge/slot-convention.md — CSS naming rules (structural .slot-* vs BEM __)
3. Add ## Slot Map (Figma ↔ Code) section to the component .md — see app-bar.md for format:
   • Table: Figma Slot | data-slot | CSS Class | Required | Accepts
   • HTML skeleton with data-slot attributes
4. Add entry to design-system/code-connect/code-connect.config.json:
   • slots: map Figma slot names → data-slot values
   • template: HTML code snippet with {SlotName} placeholders
5. Add typed interface to design-system/code-connect/slot-api.d.ts:
   • Export {Component}Slots interface with JSDoc data-slot comments
6. Add preferred instances to design-system/code-connect/preferred-instances.json:
   • Map each slot → recommended Figma component instances
7. If component has NEW slots not in slot-manifest.json:
   • Add slot definitions to slot-manifest.json FIRST
   • Then update spec + Code Connect config + API types + preferred instances

Step 5: Sync & Validate (Full Pipeline)

node design-system/scripts/pipeline/run-pipeline.js --all

Chạy unified pipeline: sync → build-docs → review CSS → verify output → drift check → audit components. Xem run-pipeline.js --help để biết thêm options (--from=N, --only=1,3, --auto).

Step 6: Add Preview Entry (MANDATORY)

⚠️ GATE: Component is NOT complete until it has a live preview in docs.

File: design-system/scripts/docs/component-previews.js

1. Add a new key matching the component slug (e.g., 'transaction-item')
2. Write HTML template using DS tokens — NO hardcoded px/colors
3. Use icon() helper for all icons (Lucide SVG, no text emoji)
4. Include hover states (onmouseover), focus (tabindex), disabled states
5. All spacing → var(--spacing-*) or calc(var(--spacing) * N)
6. All sizing → calc(var(--spacing) * N), NEVER raw 40px, 48px
7. All colors → var(--semantic-token) pairs (bg + fg)
8. All easing → var(--easing-standard), NEVER raw ease

## Verify preview renders in docs
node design-system/scripts/docs/build-docs.js
## Check output: "{N}/52 components have live previews"
## If your component is missing → FIX before proceeding

Step 7: Audit CSS Class Definition (MANDATORY)

⚠️ GATE: If the component has a CSS class (in preview-extras.css or components.css), audit it.

Check every CSS rule for:

## Quick check for hardcodes in preview CSS
Select-String '\d+px' design-system/scripts/docs/template/preview-extras.css | Where-Object { $_ -notmatch 'spacing|radius|border-width|shadow|0px' }

Audit & Fix Workflow

Commands

## Audit all components — completeness report
node design-system/scripts/pipeline/audit-components.js

## Audit + generate fix plan
node design-system/scripts/pipeline/audit-components.js --fix-plan

## Generate visual previews (after creating/fixing components)
node design-system/scripts/docs/component-previews.js

When to Batch Fix vs Manual Fix

Batch Fix Rule: Fix ALL components with the same category gap at once.

❌ Fix button hover → deploy → fix card hover → ...
✅ Collect ALL missing hover → fix ALL → validate → deploy

MANDATORY after batch-fix: Run node design-system/scripts/pipeline/run-pipeline.js --all to validate (or /post-change).

Anti-patterns

Decision Points

Project Paths

Reference Files