| name | figma-to-angular |
| description | Converts Figma designs into production Angular components with Storybook stories for the Bitwarden Clients monorepo. Use this skill whenever the user provides a Figma URL and wants to create an Angular component, or mentions "implement this design", "create a component from Figma", "build this from the design spec", or similar. Also trigger when the user pastes a Figma link and asks for a component, even if they don't say "Figma" explicitly.
|
Figma to Angular Component
This skill turns a Figma design spec into a fully implemented Angular component with Storybook
stories in the Bitwarden Clients monorepo. The output should match the design visually while
following all codebase conventions.
Workflow
Phase 1: Extract the design
Call get_design_context from the Figma MCP server. Extract the fileKey and nodeId from the URL:
figma.com/design/:fileKey/:fileName?node-id=:nodeId → convert - to : in nodeId
- Pass
clientFrameworks: "angular" and clientLanguages: "typescript,html,css"
The response contains reference code (React+Tailwind), a screenshot, and design metadata. Treat the
code as a structural reference only — it must be fully converted to Angular.
Phase 2: Explore the codebase
Before writing any code, understand the conventions of the target location. Use an Explore agent to
discover:
- Component file patterns — look at 2–3 sibling components in the same directory. Note the
file naming, module structure, barrel exports, and whether they use standalone components.
- Existing components to reuse — search for components that match parts of the design (labels,
buttons, inputs, icons). Reuse them instead of reimplementing.
- Tailwind configuration — read the relevant
tailwind.config to understand the prefix
(commonly tw-), available design tokens, and color system.
- Storybook patterns — check how sibling stories are structured: imports,
moduleMetadata,
I18nMockService usage, argTypes.
- i18n setup — find the
I18nPipe import path and the locale messages file to add new keys.
This exploration is critical. Skipping it leads to components that don't match the codebase and
require extensive rework.
Phase 3: Map design tokens
Create a mapping from Figma's design values to the codebase's Tailwind tokens. The Figma response
includes raw CSS values (hex colors, px sizes). These must be translated to semantic tokens.
Common mappings for Bitwarden:
| Figma concept | Where to look |
|---|
| Colors (hex) | tailwind.config → colors, bg, fg, border sections |
| Font sizes | tailwind.config → extend.fontSize |
| Spacing / padding | Standard Tailwind scale with prefix |
| Border radius | Standard Tailwind (rounded-*) |
| Component variants | Existing component source (e.g. base-button.directive.ts) |
Never use raw hex values. Always map to a semantic token. If no exact match exists, use the closest
available token and note the discrepancy.
Phase 4: Plan the component
Before writing code, create a plan covering:
- Selector — follows the relevant prefix convention
- Inputs and outputs — use Angular signal-based
input() and output() functions
- Content projection — identify slots for
<ng-content> (labels, hints, actions)
- Existing component reuse — which existing components to import and use
- i18n keys — list all user-visible strings that need localization
- Accessibility — keyboard navigation, ARIA attributes, focus management
Present this plan to the user and get approval before writing files.
Phase 5: Implement
Create these files following the patterns discovered in Phase 2:
Component TypeScript (component-name.component.ts)
@Component({
selector: "bit-component-name",
templateUrl: "./component-name.component.html",
changeDetection: ChangeDetectionStrategy.OnPush,
imports: [],
host: {
class: "tw-block",
},
})
Key conventions:
ChangeDetectionStrategy.OnPush always
- Signal-based inputs:
input(), input.required<T>(), input(default, { transform: booleanAttribute })
- Signal-based outputs:
output<T>()
- Internal state with
signal() and viewChild()
- Protected methods for template bindings, private for internal logic
- No TypeScript enums — use
Object.freeze({ ... } as const) with a same-name type alias (ADR-0025).
Even for simple string unions, prefer the const object pattern for consistency.
Component template (component-name.component.html)
- Use new Angular control flow:
@if, @for, @switch
- Avoid deprecated attributes like
ngClass and ngStyle, prefer class and style.
- All Tailwind classes use the library's prefix (check
tailwind.config)
- All user-visible strings go through
{{ "key" | i18n }} or {{ "key" | i18n: param }}
- Reuse existing components (
bit-label, bitButton, bit-hint, etc.)
Barrel export (index.ts)
export { ComponentNameComponent } from "./component-name.component";
Storybook stories (component-name.stories.ts)
Every component gets stories. Follow the exact patterns from sibling components:
import { Meta, moduleMetadata, StoryObj } from "@storybook/angular";
import { I18nService } from "@bitwarden/common/platform/abstractions/i18n.service";
import { I18nMockService } from "../utils/i18n-mock.service";
export default {
title: "Component Library/ComponentName",
component: ComponentNameComponent,
decorators: [
moduleMetadata({
imports: [
],
providers: [
{
provide: I18nService,
useFactory: () =>
new I18nMockService({
}),
},
],
}),
],
parameters: {
design: {
type: "figma",
url: "/* original Figma URL */",
},
},
} as Meta<ComponentNameComponent>;
Include stories for:
- Default state
- Key variant states (if applicable)
- Edge cases visible in the design (disabled, loading, empty, etc.)
Unit tests (component-name.component.spec.ts)
Write unit tests when the component has behavior that Storybook stories alone can't verify. Stories
cover visual rendering and variant appearance — don't duplicate that. Tests should focus on:
- Computed state and logic — e.g. a rating component rounding fractional values, a progress bar
clamping percentages to 0–100, variant-to-class mappings
- Event emission — outputs fire with the correct payload (files selected, rating changed, toast
dismissed)
- Input validation / edge cases — boundary values, empty inputs, invalid types rejected
- Accessibility attributes — correct
role, aria-label, aria-live values change with state
- Keyboard interaction — Enter/Space triggers actions, arrow keys navigate
Skip tests for components that are purely presentational with no logic beyond displaying inputs
(e.g. a simple badge or divider). Look at sibling *.spec.ts files to match the test setup
patterns (TestBed configuration, imports, mock providers).
Update barrel exports
Add export * from "./component-name"; to the parent directory's index.ts, inserted
alphabetically.
Phase 6: Verify in Storybook
Use Playwright MCP tools to verify the component renders correctly:
- Navigate to the story's iframe URL:
http://localhost:6006/iframe.html?id=component-library-component-name--default&viewMode=story
- Take a snapshot to confirm the component rendered without errors
- Take a screenshot and compare it against the Figma design screenshot
- Test interactive behavior:
- Click buttons and interactive elements
- Verify correct responses (dialogs, state changes, etc.)
- Check the disabled story if applicable
If Storybook isn't running or Playwright isn't available, tell the user and suggest they verify
manually.
Phase 7: Iterate
Present the screenshot to the user alongside the original Figma screenshot. Ask if adjustments are
needed. Common refinements:
- Token mismatches (wrong shade, spacing off)
- Missing hover/focus states
- Accessibility gaps
- i18n strings that need rewording
Key principles
- Never hardcode user-visible strings. Every string goes through
I18nPipe. This includes
aria-labels and other accessibility text — they need localization too. Add keys to the locale file
and provide mocks in stories.
- Reuse existing components aggressively. If the design has a button, use
bitButton. If it
has a label, use bit-label. Don't reimplement what exists.
- Explore before you build. The codebase exploration step prevents most rework. Patterns vary
between apps and libraries — always check the specific target directory.
- Semantic tokens over raw values. Map every Figma color, spacing, and font size to the
codebase's design token system. Raw hex values break theming.
- Use native HTML patterns for file inputs. For file upload components, use a
<label for>
element pointing at a hidden <input type="file"> rather than programmatic .click(). The
codebase has an AriaDisabledClickCaptureService that intercepts programmatic clicks on certain
elements, causing silent failures.
- No NgModules. All new components must be standalone (
imports: [...] in the @Component
decorator). Do not create *.module.ts files. The codebase is moving away from NgModules.
- Plan before you code. The plan step catches API design issues early. It's cheaper to fix a
plan than to rewrite files.