// GOOD: tokens via Tailwind
```
ESLint rule to enforce:
```js
// .eslintrc — custom rule or use stylelint
{
"rules": {
"no-restricted-syntax": [
"error",
{
"selector": "JSXAttribute[name.name='style'] ObjectExpression Property[key.name='color'][value.type='Literal']",
"message": "Use Tailwind classes or CSS custom properties instead of raw color values."
}
]
}
}
```
### 7.3 Skipping the RFC Process
"It's just a small change" is how systems accumulate inconsistency. Every
public API addition — even a new variant on an existing component — should
have at least a lightweight RFC:
- What problem does this solve?
- Why can't existing variants handle it?
- What is the proposed API?
- Does Figma need an update?
### 7.4 Forking Instead of Extending
When a team needs a component that behaves slightly differently, the temptation
is to copy it and modify. This creates divergence that compounds over time.
Instead:
1. Can the existing component accept a new variant?
2. Can it be composed with other components to achieve the goal?
3. Can a wrapper component add the needed behavior?
4. Only if none of the above: propose a new component via RFC.
### 7.5 Using !important to Override System Styles
If you need `!important`, the component API is insufficient. Fix the API.
Add a variant, accept a `className` prop, or use the `cn()` utility for
merge-safe class composition.
```tsx
// The cn() utility (shadcn/ui standard)
import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs))
}
// Allows clean overrides without !important
// cn() merges this correctly, removing conflicting bg classes
```
---
## 8. Figma-Specific Workflows
### 8.1 Component Structure in Figma
Mirror the atomic design hierarchy in Figma page structure:
```
File: Design System
Page: Atoms
Frame: Button
Frame: Input
Frame: Badge
Frame: Avatar
Frame: Separator
Page: Molecules
Frame: SearchBar (composes Input + Button)
Frame: UserCard (composes Avatar + Badge + text)
Page: Organisms
Frame: DataTable (composes multiple molecules)
Frame: NavigationBar (composes molecules + atoms)
Page: Tokens
Frame: Color Palette (all swatches with variable references)
Frame: Typography Scale
Frame: Spacing Scale
Frame: Shadow Elevation
```
### 8.2 Auto-Layout Rules
- Every component must use auto-layout (no absolute positioning)
- Use "Hug contents" by default, "Fill container" for responsive stretching
- Spacing values must use spacing variables, never raw numbers
- Padding must use spacing variables
- Min/max width constraints for responsive behavior
### 8.3 Variant Property Naming
Match code prop names exactly:
| Code Prop | Figma Property | Values |
|-----------|---------------|--------|
| `variant` | `variant` | default, destructive, outline, secondary, ghost, link |
| `size` | `size` | sm, default, lg, icon |
| `disabled` | `state` | enabled, disabled |
| `loading` | `loading` | false, true |
### 8.4 Code Connect Mapping
After creating both code and Figma components, register the mapping:
```ts
// button.figma.tsx — Code Connect file
import figma from "@figma/code-connect"
import { Button } from "@/components/ui/button"
figma.connect(Button, "https://figma.com/design/FILE_KEY?node-id=NODE_ID", {
props: {
variant: figma.enum("variant", {
default: "default",
destructive: "destructive",
outline: "outline",
secondary: "secondary",
ghost: "ghost",
link: "link",
}),
size: figma.enum("size", {
sm: "sm",
default: "default",
lg: "lg",
icon: "icon",
}),
children: figma.string("label"),
disabled: figma.enum("state", { disabled: true }),
},
example: ({ variant, size, children, disabled }) => (
),
})
```
---
## 9. Agent Instructions
When this skill is active, the agent should:
1. **Always check existing tokens before defining new values.** Run a token
audit before adding any color, spacing, or typography value. If a matching
token exists, use it. If a close match exists, evaluate whether a new token
is justified or if the design should align to the existing value.
2. **Classify every component by atomic level.** Before generating code, state
the level (atom/molecule/organism/template/page) and list composition
dependencies. This determines the output directory and import structure.
3. **Design the props API before writing implementation.** Write the TypeScript
interface first. Review it for: minimal required props, discriminated union
variants, ref forwarding, className acceptance, and polymorphic support.
4. **Generate component tokens alongside code.** Every new component gets a
component token set that references alias tokens. No raw values in component
files.
5. **Create Code Connect mappings for every component.** After code generation,
produce the `.figma.tsx` mapping file so Figma inspectors see real code.
6. **Check for breaking changes in every modification.** Before changing an
existing component, evaluate the change against the breaking change
checklist in section 3.1. If breaking, flag it and suggest a non-breaking
alternative if possible.
7. **Enforce quality gates.** Every generated component must include:
accessibility attributes (role, aria-label, keyboard handlers), responsive
behavior (no fixed widths unless intentional), and dark mode support (using
semantic tokens that have dark mode mappings).
8. **Prefer composition over new components.** Before creating a new molecule or
organism, check if existing atoms can be composed to achieve the same result.
The fewer components in the system, the lower the maintenance burden.