Playbook

Problem

Before this flow existed, design system requests were handled ad hoc. Requests arrived through chats and informal meetings, or components were added locally with no team visibility.

• Duplicate components built across teams with no shared awareness
• No agreed criteria for what belongs in the design system and what stays a local component
• Components added without team sign-off, which caused inconsistency across products
• Version bumps happened without socialization, which led to unexpected breakages
• Change announcements were inconsistent, so some teams found out about breaking changes too late

Identify

Team retrospectives and discussions surfaced these root-cause gaps.

1. No standard intake format, so scope, intent and urgency were hard to judge
2. No decision criteria. "Should this go in the design system?" was answered differently by each person
3. No designated owner. Requesters were not assigned as PIC, so requests were abandoned
4. No versioning protocol. Version bumps came with no announcement period
5. No code review gate. Front-end contributions had no formal review before merging
6. No feedback loop. After a decision, requesters often got no response

Solution

A structured 4-phase request flow closes each gap.

1. Evaluate request. Anyone submits in a standard format (requester, type, component, description, project, attachment). The design system team runs three gates: does the component exist, does it meet requirements, does it scale. Every path ends with a clear outcome and the requester is always told.
2. Design. The team mocks up the component with all required states, then runs an internal UI/UX review. Design is approved before development starts.
3. Develop. The front-end team opens a Jira card on the design system board and is assigned as PIC. Code review and PR merge are required, and a sign-off gate makes sure the team is aligned before the component ships.
4. Deliver. Publish to Storybook, bump the semantic version (patch, minor, or major with a socialization period), update the changelog, then announce it with the standard template.

Result & Impact

The team gets clear and measurable improvements.

• Clarity: every request follows one format, so there is no guessing about scope or intent
• Faster decisions: defined criteria cut the back-and-forth
• Accountability: the requester is PIC throughout, so fewer requests fall through the cracks
• Fewer breakages: version bumps include a socialization period for teams to adapt
• Cross-team visibility: the changelog and announcement template keep every engineer informed
• Closed feedback loop: every requester gets a clear response, whatever the outcome
• Code quality: the code review gate keeps contributions up to design system standards

This flow reduces rework, makes sure components are production-ready before they are built, and gives every stakeholder full visibility from evaluation to release.

1. Main Principles

1. Non-Destructive: ID assignment happens at the Instance or Frame Handoff level. Modifying the Main Component in the Design System library is prohibited.
2. Kebab-case: naming uses all lowercase letters with hyphens as separators (e.g., qa-pms-save-btn).
3. Single Source of Truth: the ID written in Figma is the same ID used by Developer in code and by QA in automation scripts.

2. Naming Formula

qa-[module]-[component]-[action/name]

• qa: mandatory prefix identifying automation elements
• module: module or page name (e.g., pms, login, profile)
• component: component abbreviation (see Standard Component Dictionary)
• action/name: specific element function (e.g., submit, email, cancel)

3. Standard Component Dictionary

The team must use a shared abbreviation list to stay consistent:

4. Workflow

View image

Close

5. Elements Requiring IDs

Not every element needs annotation. Focus on:

• All clickable elements (Buttons, Links, Tabs)
• All input elements (Inputs, Checkbox, Dropdown)
• Success/failure message elements (Toasts, Alerts)
• Main data containers (Tables, List Cards)

6. Verification Checklist (Quality Control)

Before submitting to the Developer, the designer must ensure:

• No duplicate IDs on a single page
• Spelling aligns with the Standard Dictionary (e.g., "btn", not "button")
• All IDs are written in English
• The "qa-" prefix is applied to the front of every ID

7. Conflict Handling

If a new component has no abbreviation in the dictionary:

1. The designer proposes a new abbreviation to the Lead UI/UX
2. Once approved, the abbreviation is added to this SOP table